@graphpilot-oss/graphpilot 0.0.1 → 0.1.0

package/README.md

@@ -4,128 +4,386 @@
 
 <h1 align="center">GraphPilot</h1>
 
-> **The refactor-safe code graph for coding agents.** Branch-aware. Evidence-backed.
-> A structural memory layer that knows what changed since `main`, cites every claim
-> with `file:line @ sha`, and re-roots itself to the git worktree automatically.
+<p align="center">
+  <strong>Structural memory for coding agents.</strong><br />
+  A refactor-safe, branch-aware, evidence-backed code graph that runs entirely on your machine.
+</p>
 
-[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
-[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org)
-[![Status](https://img.shields.io/badge/status-alpha-orange.svg)](#status)
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License: Apache 2.0" /></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg" alt="Node ≥20" /></a>
+  <img src="https://img.shields.io/badge/version-0.1.0-blue.svg" alt="v0.1.0" />
+  <img src="https://img.shields.io/badge/status-alpha-orange.svg" alt="alpha" />
+  <img src="https://img.shields.io/badge/tests-239%20passing-brightgreen.svg" alt="239 tests" />
+</p>
 
----
+<p align="center">
+  <a href="#quickstart">Quickstart</a> ·
+  <a href="#the-five-tools">Tools</a> ·
+  <a href="#how-it-works">How it works</a> ·
+  <a href="#editor-setup">Editor setup</a> ·
+  <a href="docs/limitations.md">Limitations</a> ·
+  <a href="bench/README.md">Benchmarks</a>
+</p>
 
-**On 10 standardized structural questions** about a real TypeScript codebase:
-GraphPilot returns the correct answer with **F1 0.89** vs grep's **0.42**, while
-the agent reads **99.9 % fewer bytes** (721 B vs 528 KB) to reach the same
-conclusion. [Reproduce in 30 s →](bench/README.md)
+<p align="center">
+  <img src="docs/press/hero.gif" alt="GraphPilot demo — install, index, and query a real TypeScript repo in under 30 seconds" width="900" />
+</p>
 
 ---
 
-## Status
+## What it is
+
+GraphPilot is a local CLI + MCP server that indexes your TypeScript/JavaScript repo into a structural graph (symbols, callers, callees, blast radius) and exposes it to coding agents — Claude Code, Cursor, Cline, Windsurf, Continue — so they stop re-`grep`ping the same files every conversation.
+
+The problem it solves: agents burn tokens, hallucinate function names, and miss structural relationships ("what calls this?", "what breaks if I rename it?") because each session starts from zero. GraphPilot is the persistent structural memory in between.
+
+**Token cost drops. Hallucinations drop. Refactors get safer.**
+
+On 10 standardized structural questions, GraphPilot reaches **F1 0.89 vs grep's 0.42** while the agent reads **99.9 % fewer bytes** (721 B vs 528 KB) to reach the same conclusion. The same byte-cost reduction holds at scale: indexing **microsoft/TypeScript** (601 files, 17 k symbols, 70 k call edges in 10 s) gives **sub-millisecond queries** and a **99.99 % bytes-read reduction vs grep** on the compiler's hottest symbols. [Reproduce in 30 seconds →](bench/README.md)
+
+## One binary, two modes
+
+GraphPilot ships as a single npm package (`@graphpilot-oss/graphpilot`) with two runtime modes — most users run both.
+
+| Mode           | Command                    | What it does                                                                 |
+| -------------- | -------------------------- | ---------------------------------------------------------------------------- |
+| **CLI**        | `graphpilot index <path>`  | Walks your repo, builds the structural graph, writes it to `~/.graphpilot/`  |
+|                | `graphpilot watch <path>`  | Keeps the graph fresh (~10 ms per file save)                                 |
+|                | `graphpilot status <path>` | Health probe — when the graph was last refreshed, file/symbol/edge counts    |
+| **MCP server** | `graphpilot mcp`           | Speaks MCP over stdio — your coding agent calls into this to query the graph |
+
+**The flow:** the **CLI** builds the index once (and `watch` keeps it warm). The **MCP server** is what your coding agent talks to — you never invoke it yourself, you just point your agent's MCP config at `graphpilot mcp` once and the agent spawns it on every session.
+
+```
+   you ── graphpilot index/watch ──►  ~/.graphpilot/<repo>/graph.json
+                                                  │
+                                                  ▼
+   coding agent ◄── stdio JSON-RPC ── graphpilot mcp ── reads graph
+```
+
+If you only want CLI access to your code graph (no agent), run `graphpilot index` and then `graphpilot stats` / inspect `graph.json` directly. If you only want the agent integration, you still need to run `graphpilot index` once — the MCP server is read-only against the on-disk graph.
+
+## What makes it different
+
+Other code-graph tools treat your repo as a static blob: index once, query forever, no branch awareness, no proof of where an answer came from. GraphPilot is built around three properties none of them ship:
+
+- 🔍 **Evidence anchors.** Every tool response carries `file:line @ sha` on every symbol and call site. The agent can quote the anchor verbatim and you can verify it instantly — hallucinations get exposed the moment you jump to the line.
+- 🌿 **Differential impact.** Pass `since: <commit|branch>` to `gp_impact` and the result is filtered to files your branch actually touches. PR-scoped refactor analysis in one call instead of `git diff | xargs grep`.
+- 🪵 **Worktree-aware by default.** Two `git worktree add`-ed branches naturally produce two separate indexes — no manual config. Run `graphpilot index ./src/feature` from a subdir and it transparently re-roots to the worktree top. Opt out with `--no-worktree`.
+
+Add to that: **local-first** (no telemetry, no remote calls, enforced by an ESLint policy on `src/` itself), **deterministic** (same repo → same graph), **sub-second incremental** updates via watch mode.
+
+## Quickstart
+
+**Prerequisites**
+
+- Node.js ≥ 20 (`node --version` to check)
+- An MCP-capable coding agent (Claude Code, Cursor, Cline, Windsurf, or Continue)
+- A TypeScript or JavaScript repo to index
+
+End-to-end time: ~3 minutes.
+
+**1. Install the CLI**
+
+```bash
+npm install -g @graphpilot-oss/graphpilot
+# or: pnpm add -g @graphpilot-oss/graphpilot
+# or one-shot, no install: npx @graphpilot-oss/graphpilot <command>
+```
+
+Verify it landed on your `PATH`:
+
+```bash
+graphpilot --version
+# → 0.1.0
+```
+
+If you see `command not found: graphpilot`, your global npm bin is not on `PATH`. Run `npm config get prefix` and add `<prefix>/bin` to your shell's `PATH`, or use the `npx` form above.
+
+**2. Build the structural index for your repo**
+
+Run this once per project. It walks your source tree, parses each TS/JS file with tree-sitter, extracts symbols + call edges, and writes the graph to `~/.graphpilot/<repo-id>/graph.json`.
+
+```bash
+graphpilot index ~/code/my-app
+```
+
+Expect a one-line summary like `indexed 412 files · 3,981 symbols · 7,204 edges · 1.8s`.
+
+**3. Wire it into your coding agent**
+
+GraphPilot speaks MCP over stdio. Add this server entry to your agent's MCP config — every supported client uses the same two-line shape:
+
+```json
+{
+  "mcpServers": {
+    "graphpilot": {
+      "command": "graphpilot",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Where this file lives depends on the client (`~/.cursor/mcp.json`, `~/.claude.json`, Cline's settings panel, etc.). Pre-made configs with the exact file path for each agent are in [`examples/`](examples/) — copy the one for your client.
+
+Restart the agent. It now has five new tools: `gp_recall`, `gp_callers`, `gp_impact`, `gp_index`, `gp_stats` — see [The five tools](#the-five-tools) below for what each one does and when the agent should reach for it.
+
+**4. Try it**
+
+Ask your agent a structural question instead of letting it grep:
+
+> _"Use gp_impact to show me everything that breaks if I rename `parseToken`."_
+
+You should see a response with `file:line @ sha` anchors you can click straight to. If the agent doesn't reach for the tool, prompt explicitly: "use the `gp_` MCP tools." If it can't see them at all, the MCP config wasn't picked up — restart the agent and re-check the config path for your client in [`examples/`](examples/).
+
+**5. Keep the index fresh as you edit (optional but recommended)**
+
+```bash
+graphpilot watch ~/code/my-app
+```
+
+Sub-10 ms incremental updates on each file save. Leave it running in a terminal tab.
 
-Pre-alpha, in active development. Not yet published to npm. Expect breaking changes.
+**6. Drop per-editor routing rules into your repo (optional)**
+
+```bash
+graphpilot init
+```
 
-## Quickstart (local dev)
+Auto-detects which editors you have installed (Cursor, Claude Code, Cline, Windsurf, Continue) and writes the matching rules file (`.cursorrules`, `CLAUDE.md`, etc.) to the current directory. The rules teach the agent to reach for `gp_*` tools before grep.
 
 ```bash
-git clone https://github.com/graphpilot-oss/graphpilot.git
-cd graphpilot
-pnpm install
-pnpm build
+graphpilot init --all            # write rules for every supported editor
+graphpilot init --client cursor  # one editor only
+graphpilot init --dry-run        # preview without writing
+```
+
+Full 5-minute walkthrough with screenshots: [`docs/quickstart.md`](docs/quickstart.md).
+
+## The five tools
+
+GraphPilot exposes five MCP tools. Each one answers a structural question your agent would otherwise solve by grepping and reading files.
+
+### `gp_recall` — find a symbol by name
+
+Use this when the agent asks "where is X defined?" or needs to locate a function before reasoning about it.
+
+- **Input:** `{ query, limit?, substring?, path? }`
+- **Returns:** symbols matching the name (exact case-insensitive by default; `substring: true` for partial matches), each with `file:line @ sha`.
+- **Replaces:** `grep -rn "function X"` plus reading each hit to find the real definition.
+
+```text
+Agent: gp_recall({ query: "parseToken" })
+→ parseToken (function) — src/auth.ts:42 @ a1b2c3d
+  export function parseToken(raw: string): Token | null
+```
+
+### `gp_callers` — list callers (or callees)
 
-# Index a repo
-node dist/cli.js index /path/to/your/repo
+Use this when the agent needs to know "who calls X?" or "what does X call?" — the two fundamental questions of refactoring.
 
-# See what got indexed
-node dist/cli.js status /path/to/your/repo
+- **Input:** `{ symbol, direction?: 'callers' | 'callees', limit?, includeUnresolved?, path? }`
+- **Returns:** every call edge where the symbol is target (callers) or source (callees), with anchors.
+- **Replaces:** `grep -rn "X("` followed by manual filtering of comments, strings, and renamed shadows.
 
-# Keep the index fresh as you edit (Ctrl+C to stop)
-node dist/cli.js watch /path/to/your/repo
+```text
+Agent: gp_callers({ symbol: "authenticate", direction: "callers" })
+→ login → authenticate — src/routes/login.ts:18 @ a1b2c3d
+→ refreshSession → authenticate — src/session.ts:64 @ a1b2c3d
 ```
 
-Then wire it into Claude Code (or any MCP client): see
-[docs/mcp-setup.md](docs/mcp-setup.md).
-
-## What it does
-
-Five MCP tools that any MCP-compatible agent (Claude Code, Cursor, Cline,
-Windsurf, Continue) can call:
-
-| Tool         | Use it for                                                                                                                                                                           |
-| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `gp_index`   | Re-index a repo from inside the agent                                                                                                                                                |
-| `gp_recall`  | Look up a function/class/type/interface by name                                                                                                                                      |
-| `gp_callers` | List callers (or callees) of a symbol                                                                                                                                                |
-| `gp_impact`  | Blast radius: direct + transitive callers, tests affected, public-API flag — answers _"what breaks if I rename X?"_ in one call. Pass `since: <commit\|branch>` for PR-scoped impact |
-| `gp_stats`   | Index health probe                                                                                                                                                                   |
-
-Plus `graphpilot watch` for sub-second incremental updates on file save.
-
-The index lives in `~/.graphpilot/<repo-id>/graph.json` (mode 0600). Everything
-stays local. No accounts, no telemetry, no remote calls — enforced by an
-ESLint policy on the codebase itself.
-
-## What's different
-
-Other code-graph tools (CodeGraphContext, Serena, the 15+ existing MCP servers
-in this space) treat your repo as a static blob: index once, query forever, no
-awareness of branches, no proof of where an answer came from. GraphPilot is
-built around three things none of them ship:
-
-- **Evidence anchors.** Every tool response includes `file:line @ sha` for
-  every symbol and call site. The agent can quote the anchor verbatim and
-  you can verify it instantly — fabrications get exposed the moment the user
-  jumps to the line.
-- **Differential impact (`gp_impact({since: <ref>})`).** Ask "of all the
-  callers of `X`, which ones live in code my PR touches?" — answered in one
-  call instead of `git diff | xargs grep`. Branch-scoped refactors without
-  the false-positive noise.
-- **Worktree-aware by default.** Run `graphpilot index ./src/feature` from a
-  subdir and it transparently re-roots to the git worktree top, so two
-  `git worktree add`-ed branches naturally get two separate indexes. Opt out
-  with `--no-worktree`.
-
-## Roadmap
-
-| Milestone                                        | Status            |
-| ------------------------------------------------ | ----------------- |
-| Parser + symbol extraction (TS/JS)               | ✅                |
-| Directory indexer + JSON storage                 | ✅                |
-| Call-edge extraction + resolver                  | ✅                |
-| MCP server (5 tools)                             | ✅                |
-| Watch mode                                       | ✅                |
-| Impact analysis (`gp_impact`)                    | ✅                |
-| Tier-A benchmark (this codebase)                 | ✅                |
-| Tier-B agent benchmark (Claude Code vs baseline) | ⏭                |
-| npm publish                                      | ⏭                |
-| Python language support                          | ⏭ (demand-gated) |
-
-## Why
-
-Most coding agents (Claude Code, Cursor, Aider) re-grep the codebase every
-conversation. That burns tokens, hallucinates function names, and misses
-structural relationships (_"what calls this?"_, _"what breaks if I rename it?"_).
-
-GraphPilot indexes the structural memory of your repo once. The agent reuses
-it across sessions. Token cost drops. Hallucinations drop. Refactors get safer.
-
-The benchmark above is the floor: it measures what's reachable via tool calls,
-not what the agent does with it. The agent-eval Tier B is spec'd in
-[bench/run-agent-tier.md](bench/run-agent-tier.md) and pending a focused
-launch-prep session.
+### `gp_impact` — blast radius in one call
+
+Use this when the agent asks "what breaks if I rename X?" or "what depends on this?" — the single most expensive question an agent normally solves.
+
+- **Input:** `{ symbol, depth? (1–5, default 3), since?, path? }`
+- **Returns:** direct callers, transitive callers grouped by BFS depth, tests likely affected, public-API flag, summary stats.
+- **Killer feature:** pass `since: 'main'` and the result is scoped to files your branch actually touches — PR-scoped refactor review without `git diff` gymnastics.
+
+```text
+Agent: gp_impact({ symbol: "extractSymbols", depth: 2, since: "main" })
+→ Direct callers (2):    indexDirectory, applyUpdate
+→ Depth-2 callers (1):   cmdIndex
+→ Tests affected (3):    tests/indexer.test.ts, tests/symbols.test.ts, tests/cli.test.ts
+→ Public API:            no
+```
+
+### `gp_index` — refresh from inside the agent
+
+Use this after the agent (or the user) has made a batch of structural edits and wants the graph to reflect them without dropping to a shell.
+
+- **Input:** `{ path? }`
+- **Returns:** re-indexes the repo and invalidates the per-path query cache.
+- **Pairs with:** `graphpilot watch` for sub-10 ms incremental updates between explicit re-indexes.
+
+### `gp_stats` — index health probe
+
+Use this as a smoke test: "is the index alive? when was it last refreshed?"
+
+- **Input:** `{ path? }`
+- **Returns:** repo id, `indexedAt`, file/symbol/edge counts, indexed branch + sha when available.
+
+## How it works
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│                  Your TypeScript / JS repo                     │
+└──────────────────────────────┬─────────────────────────────────┘
+                               │
+                ┌──────────────▼──────────────┐
+                │  indexer.ts                 │
+                │  walk dir · skip ignores ·  │
+                │  symlink-safe · 50k cap     │
+                └──────────────┬──────────────┘
+                               │
+                ┌──────────────▼──────────────┐
+                │  parser.ts                  │
+                │  tree-sitter → AST          │
+                │  5 MB cap · iterative walk  │
+                └──────────────┬──────────────┘
+                               │
+            ┌──────────────────┴──────────────────┐
+            │                                     │
+   ┌────────▼────────┐                   ┌────────▼────────┐
+   │  symbols.ts     │                   │  edges.ts       │
+   │  funcs · classes│                   │  call sites +   │
+   │  methods · ifs  │                   │  resolver       │
+   │  types · enums  │                   │ (same-file→glb) │
+   └────────┬────────┘                   └────────┬────────┘
+            │                                     │
+            └──────────────────┬──────────────────┘
+                               │
+                ┌──────────────▼──────────────┐
+                │  storage.ts                 │
+                │  ~/.graphpilot/<repo-id>/   │
+                │  graph.json · mode 0600     │
+                └──────────────┬──────────────┘
+                               │
+                ┌──────────────▼──────────────┐
+                │  query.ts (GraphIndex)      │
+                │  byName · byId · callers ·  │
+                │  callees — sub-ms lookups   │
+                └──────────────┬──────────────┘
+                               │
+                ┌──────────────▼──────────────┐
+                │  mcp.ts                     │
+                │  5 tools · stdio JSON-RPC   │
+                └──────────────┬──────────────┘
+                               │
+                       [MCP protocol]
+                               │
+                ┌──────────────▼──────────────┐
+                │  Claude Code · Cursor ·     │
+                │  Cline · Windsurf · …       │
+                └─────────────────────────────┘
+```
+
+Data flow is one-way: source → tree → symbols + edges → JSON → query → agent. GraphPilot never modifies your code.
+
+Full pipeline writeup with file references: [`docs/architecture.md`](docs/architecture.md).
+
+## When to use which tool
+
+| If the agent is about to…                          | Reach for…                     | Why                                                   |
+| -------------------------------------------------- | ------------------------------ | ----------------------------------------------------- |
+| `grep` for a function by name                      | `gp_recall`                    | One call, no false positives from comments or strings |
+| Read 20 files looking for "who calls X"            | `gp_callers`                   | Pre-computed reverse index, sub-millisecond           |
+| Plan a rename or signature change                  | `gp_impact`                    | Direct + transitive + tests + public-API in one call  |
+| Review a PR's structural blast radius              | `gp_impact({ since: 'main' })` | Differential — only callers your branch touches       |
+| Re-grep after editing several files                | `gp_index`                     | Incremental: lets the next call see your edits        |
+| Sanity-check whether the index is loaded and fresh | `gp_stats`                     | One-liner health probe                                |
+
+For string literals, error messages, config values, or anything in a language other than TS/JS: **stay with grep.** GraphPilot indexes code structure, not text.
+
+## Editor setup
+
+GraphPilot speaks MCP over stdio, so it works with any MCP-capable client. Ready-to-paste configs live in `examples/`:
+
+| Client                        | Folder                                           |
+| ----------------------------- | ------------------------------------------------ |
+| **Claude Code** (Anthropic)   | [`examples/claude-code/`](examples/claude-code/) |
+| **Cursor**                    | [`examples/cursor/`](examples/cursor/)           |
+| **Cline** (VS Code extension) | [`examples/cline/`](examples/cline/)             |
+| **Windsurf** (Codeium)        | [`examples/windsurf/`](examples/windsurf/)       |
+| **Continue.dev**              | [`examples/continue/`](examples/continue/)       |
+| Any other MCP client          | See [`docs/mcp-setup.md`](docs/mcp-setup.md)     |
+
+Each folder contains: a `README.md` walkthrough, a sample config file with the exact JSON to paste, and (where the client supports it) a routing template so the agent automatically reaches for GraphPilot on structural questions.
+
+## Privacy & security
+
+GraphPilot is **local-first by promise and by build gate**.
+
+- **No telemetry, no remote calls, ever.** Verifiable: `src/` has zero `http`, `fetch`, `axios`, or analytics imports — enforced by an ESLint rule plus a meta-test that proves the rule fires on every banned import.
+- **No `child_process`, no `exec`, no `spawn`.** Git facts are read directly from `.git/` via pure-JS helpers.
+- **Source code never leaves your machine.** Only structural metadata (names, locations, signatures, call relationships) lives in `~/.graphpilot/`.
+- **Signatures are redacted** for common secret patterns (OpenAI/Anthropic `sk-`, GitHub `ghp_`/`ghs_`, AWS `AKIA`, JWTs, PEM headers, Slack/Stripe tokens) before they're written to disk.
+- **Strict file permissions:** dir `0o700`, files `0o600`.
+- **Schema validation on load:** tampered or corrupt `graph.json` falls back to "no index" rather than poisoning the agent.
+- **Hand-rolled input validators** on every MCP tool — unknown fields are rejected, every field type-checked, numbers range-checked, strings length-capped.
+
+Threat model and per-defence test references live in [`docs/architecture.md`](docs/architecture.md). Report security issues per [`SECURITY.md`](SECURITY.md).
+
+## Vs alternatives
+
+| Tool               | Branch-aware | Evidence anchors | Local-first | Languages    |
+| ------------------ | ------------ | ---------------- | ----------- | ------------ |
+| **GraphPilot**     | ✅           | ✅               | ✅          | TS/JS        |
+| CodeGraphContext   | ❌           | ❌               | ✅          | TS/JS/Python |
+| Serena             | ❌           | ❌               | ✅          | Multi        |
+| Sourcegraph (SaaS) | ⚠ partial    | ✅               | ❌          | Multi        |
+| Plain grep + read  | n/a          | ❌               | ✅          | All          |
+
+GraphPilot is not trying to be the universal code-graph. It's trying to be the one that makes refactors in TypeScript/JavaScript repos **safe to delegate to an agent** — which means branch awareness and verifiable citations are non-negotiable.
+
+## Limitations
+
+GraphPilot v0.1 makes deliberate trade-offs to ship small and sharp:
+
+- **TS/JS only.** Python, Rust, Go, Java are out of scope for v1. Python is demand-gated for v0.2 / v0.3.
+- **Name-based resolver** (no import-path tracking, no type-based method dispatch). Expected resolution rate: ~25–35 % of edges resolve to in-repo symbols; the rest are stdlib / third-party. That's enough because the questions agents actually ask (_"who calls X in my repo?"_) are the ones the dumb resolver answers correctly.
+- **No semantic search.** `gp_recall` is name-only. "Find code similar to this snippet" is deferred until 30+ users ask for it.
+- **No `.graphpilotignore`** yet (defaults skip `node_modules`, `dist`, `build`, `.git`, `coverage`, `.next`, `.nuxt`, `.cache`, `out`, `*.d.ts`).
+- **Single repo per query.** Workspace abstraction is on the v1.x roadmap.
+
+Full list with mitigations: [`docs/limitations.md`](docs/limitations.md).
+
+## FAQ
+
+**Does it send my code anywhere?**
+No. There is no network code in `src/`, no telemetry, no update check. An ESLint rule blocks adding any of those at the build gate.
+
+**Will it slow down my editor?**
+The MCP server is idle until your agent calls a tool. Tool calls are sub-millisecond after the first lazy load. Watch mode adds ~3–10 ms per file save.
+
+**What happens to the graph when I switch branches?**
+If you use `git worktree`, you automatically get a separate graph per worktree. On a single working copy that you switch with `git checkout`, the graph reflects the last `gp_index` (or watch-mode updates). Run `gp_index` after a branch switch to refresh.
+
+**Do I need to re-index every session?**
+No. The graph persists at `~/.graphpilot/<repo-id>/graph.json`. Re-index after sweeping changes; otherwise, watch mode keeps it fresh incrementally.
+
+**Why TypeScript/JavaScript first?**
+That's where the maintainer's pain was, and tree-sitter-typescript covers TS, TSX, JSX, and JS in a single grammar. Python is the next likely addition; vote with a GitHub Discussion.
+
+**How does this compare to LSP?**
+LSPs are scoped to one editor and one buffer at a time, and they re-compute on each query. GraphPilot is editor-agnostic, persists across sessions, and answers structural questions (who-calls, blast-radius) that LSPs don't expose uniformly.
 
 ## Documentation
 
-- [docs/quickstart.md](docs/quickstart.md) — 5-minute walkthrough
-- [docs/mcp-setup.md](docs/mcp-setup.md) — per-client config
-- [docs/architecture.md](docs/architecture.md) — how the pipeline works
-- [docs/limitations.md](docs/limitations.md) — v1 caveats (read this)
-- [bench/README.md](bench/README.md) — benchmark methodology + results
+- [`docs/quickstart.md`](docs/quickstart.md) — 5-minute walkthrough
+- [`docs/mcp-setup.md`](docs/mcp-setup.md) — per-client config reference
+- [`docs/architecture.md`](docs/architecture.md) — pipeline writeup with file refs
+- [`docs/limitations.md`](docs/limitations.md) — v1 caveats (read this)
+- [`bench/README.md`](bench/README.md) — benchmark methodology + results
+- [`examples/`](examples/) — ready-to-paste configs for every supported client
 
 ## Contributing
 
-We welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md) before
-opening a PR.
+GraphPilot is small, opinionated, and accepting contributions. Start with [`CONTRIBUTING.md`](CONTRIBUTING.md) — especially the _"What we are NOT doing in v1"_ section before you propose a feature.
+
+Found a security issue? Please follow [`SECURITY.md`](SECURITY.md) instead of opening a public issue.
 
 ## License
 

package/dist/cli.js

@@ -13,6 +13,7 @@ Usage:
   graphpilot status <path>    Show info about an indexed repo
   graphpilot watch <path>     Watch the repo and update the index on save
   graphpilot mcp              Start the MCP server (stdio)
+  graphpilot init             Drop routing-rules files for detected editors
   graphpilot help             Show this help
 
 Examples:
@@ -20,6 +21,10 @@ Examples:
   graphpilot status .
   graphpilot watch .          # keeps the index fresh as you edit
   graphpilot mcp              # used by MCP clients (Claude Code, Cursor, ...)
+  graphpilot init             # auto-detect editors and write routing rules
+  graphpilot init --all       # write rules for all supported editors
+  graphpilot init --client cursor --path /my/repo
+  graphpilot init --dry-run   # preview what would be written
 `;
 async function cmdIndex(pathArg, opts = {}) {
     const requested = resolve(pathArg);
@@ -144,6 +149,21 @@ async function main() {
             await watcher.stop();
             return 0;
         }
+        case 'init': {
+            const { runInit } = await import('./init.js');
+            const allFlag = rest.includes('--all');
+            const dryRun = rest.includes('--dry-run');
+            const pathIdx = rest.indexOf('--path');
+            const pathArg = pathIdx !== -1 ? rest[pathIdx + 1] : undefined;
+            const clientIdx = rest.indexOf('--client');
+            const clientArg = clientIdx !== -1 ? rest[clientIdx + 1] : undefined;
+            const repoPath = resolve(pathArg ?? '.');
+            const clients = clientArg
+                ? [clientArg]
+                : undefined;
+            await runInit({ repoPath, clients, all: allFlag, dryRun });
+            return 0;
+        }
         case 'help':
         case '--help':
         case '-h':

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/indexer.js

@@ -1,6 +1,6 @@
 import fg from 'fast-glob';
 import { realpathSync } from 'node:fs';
-import { resolve, relative } from 'node:path';
+import { resolve, relative, sep } from 'node:path';
 import { parseFile } from './parser.js';
 import { extractSymbols } from './symbols.js';
 import { extractRawCalls, resolveCallEdges } from './edges.js';
@@ -61,7 +61,7 @@ export async function indexDirectory(rootPath, opts = {}) {
                 filesFailed++;
                 continue;
             }
-            if (!realFile.startsWith(realRoot)) {
+            if (realFile !== realRoot && !realFile.startsWith(realRoot + sep)) {
                 filesSkippedSymlink++;
                 continue;
             }
@@ -71,7 +71,7 @@ export async function indexDirectory(rootPath, opts = {}) {
             const fileSymbols = extractSymbols(parsed);
             const fileCalls = extractRawCalls(parsed, fileSymbols);
             if (useRelative) {
-                const rel = relative(absRoot, file);
+                const rel = relative(absRoot, file).split(sep).join('/');
                 // Track id rewrites so call edges can be remapped in lockstep.
                 const idRewrites = new Map();
                 for (const s of fileSymbols) {

package/dist/indexer.js.map

@@ -1 +1 @@
-{"version":3,"file":"indexer.js","sourceRoot":"","sources":["../src/indexer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"indexer.js","sourceRoot":"","sources":["../src/indexer.ts"],"names":[],"mappings":"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"}