Align setup guidance with current codegraph init behavior

CHANGELOG.md

@@ -9,6 +9,9 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Fixes
+
+- Installation prompts and setup docs now recommend `codegraph init`, matching the current behavior where the initial index is built by default while `-i`/`--index` remains accepted for older scripts.
 
 ## [0.9.9] - 2026-06-02
 

README.md

@@ -52,10 +52,10 @@ npm i -g @colbymchenry/codegraph
 
 ```bash
 cd your-project
-codegraph init -i
+codegraph init
 ```
 
-<sub>`codegraph init` just creates the local `.codegraph/` index directory; adding `-i` (`--index`) also builds the initial graph in the same step. Without `-i`, run `codegraph index` afterwards to populate it.</sub>
+<sub>`codegraph init` creates the local `.codegraph/` index directory and builds the initial graph by default. `-i` (`--index`) is still accepted for older scripts, but it is no longer required. Run `codegraph index` any time to rebuild.</sub>
 
 <div align="center">
 
@@ -331,10 +331,10 @@ Restart your agent (Claude Code / Cursor / Codex CLI / opencode / Hermes Agent /
 
 ```bash
 cd your-project
-codegraph init -i
+codegraph init
 ```
 
-Builds the per-project knowledge graph index. A single global `codegraph install` works in every project you open — no need to re-run the installer per project.
+Creates and builds the per-project knowledge graph index. A single global `codegraph install` works in every project you open — no need to re-run the installer per project.
 
 That's it — your agent will use CodeGraph tools automatically when a `.codegraph/` directory exists.
 
@@ -387,7 +387,7 @@ CodeGraph's MCP server delivers its usage guidance to your agent **automatically
 - **Answer structural questions directly with CodeGraph** — it *is* the pre-built index, so a grep/read loop just repeats work it already did. Treat the returned source as already read.
 - **Pick the tool by intent:** `codegraph_explore` for almost anything — "how does X work", a flow/"how does X reach Y", or surveying an area (one call returns the relevant symbols' source grouped by file); `codegraph_search` to just locate a symbol; `codegraph_callers`/`codegraph_callees` to walk call flow; `codegraph_impact` before editing; `codegraph_node` for one specific symbol's full source (it returns every overload for an ambiguous name).
 - **Trust the results — don't re-verify with grep**, and check the staleness banner after edits.
-- If `.codegraph/` doesn't exist yet, offer to run `codegraph init -i`.
+- If `.codegraph/` doesn't exist yet, offer to run `codegraph init`.
 
 The exact text is `src/mcp/server-instructions.ts` — the single source of truth.
 
@@ -434,7 +434,7 @@ The exact text is `src/mcp/server-instructions.ts` — the single source of trut
 codegraph                         # Run interactive installer
 codegraph install                 # Run installer (explicit)
 codegraph uninstall               # Remove CodeGraph from your agents (inverse of install)
-codegraph init [path]             # Initialize in a project (--index to also index)
+codegraph init [path]             # Initialize in a project and build the initial index
 codegraph uninit [path]           # Remove CodeGraph from a project (--force to skip prompt)
 codegraph index [path]            # Full index (--force to re-index, --quiet for less output)
 codegraph sync [path]             # Incremental update

docs/SEARCH_QUALITY_LOOP.md

@@ -11,10 +11,10 @@ A language is NOT verified until an LLM can reliably use CodeGraph's MCP tools t
 ```bash
 npm run build
 rm -rf <codebase_path>/.codegraph
-node dist/bin/codegraph.js init -iv <codebase_path>
+node dist/bin/codegraph.js init -v <codebase_path>
 ```
 
-The `-iv` flag gives verbose output showing extraction progress, node/edge counts, and timing.
+The `-v` flag gives verbose output showing extraction progress, node/edge counts, and timing.
 
 ### 2. Quick sanity check
 
@@ -470,7 +470,7 @@ test().catch(console.error);
 ```bash
 npm run build
 rm -rf <codebase_path>/.codegraph
-node dist/bin/codegraph.js init -iv <codebase_path>
+node dist/bin/codegraph.js init -v <codebase_path>
 # Re-run the failing tests from above
 ```
 

docs/benchmarks/codegraph-ab-matrix.md

@@ -120,6 +120,6 @@ than faked.
 Canonical harness: `scripts/agent-eval/run-all.sh <repo> "<question>" headless` (with = codegraph-only
 MCP, without = empty MCP), parsed from the stream-json logs. The throwaway matrix driver + parser used
 for this table live in `/tmp/ab-matrix/`: `run.sh` (the `lang|size|repo|question` matrix — each cell does
-`rm -rf .codegraph && codegraph init -i` then both arms), `parse-matrix.mjs` (cells → this table), and
+`rm -rf .codegraph && codegraph init` then both arms), `parse-matrix.mjs` (cells → this table), and
 `compare.mjs` (old-vs-new diff + aggregates). Build `dist/` from the target commit first so the MCP
 server loads the code under test (`codegraph` on PATH is `npm link`ed to the dev `dist/`).

docs/design/callback-edge-synthesis.md

@@ -37,7 +37,7 @@ We synthesize `dispatcher → callback` edges that static parsing misses. It wor
 ```bash
 npm run build
 rm -rf /tmp/codegraph-corpus/excalidraw/.codegraph
-( cd /tmp/codegraph-corpus/excalidraw && codegraph init -i )
+( cd /tmp/codegraph-corpus/excalidraw && codegraph init )
 # synthesized edges (provenance='heuristic', metadata.synthesizedBy in {callback,event-emitter}):
 sqlite3 /tmp/codegraph-corpus/excalidraw/.codegraph/codegraph.db \
   "select s.name||' → '||t.name||'  '||coalesce(e.metadata,'') from edges e \

docs/design/dynamic-dispatch-coverage-playbook.md

@@ -147,7 +147,7 @@ question and a real repo (add to `.claude/skills/agent-eval/corpus.json`). Examp
 
 ### Step 2 — Measure the hole (deterministic, no agent)
 ```bash
-rm -rf <repo>/.codegraph && ( cd <repo> && codegraph init -i )
+rm -rf <repo>/.codegraph && ( cd <repo> && codegraph init )
 node scripts/agent-eval/probe-trace.mjs <repo> <from-symbol> <to-symbol>   # does the flow break? where?
 node scripts/agent-eval/probe-node.mjs  <repo> <break-symbol>              # trail: is the next hop missing?
 ```
@@ -214,7 +214,7 @@ were found). Confirm it's dynamic by reading the break symbol's body.
 | `sqlite3 <repo>/.codegraph/codegraph.db` | direct edge/node inspection (provenance, metadata, counts) |
 
 Probe scripts use the built `dist/` — run `npm run build` first. Reindex after any
-extraction or resolution change (`rm -rf <repo>/.codegraph && codegraph init -i`) — the
+extraction or resolution change (`rm -rf <repo>/.codegraph && codegraph init`) — the
 synthesizer/resolvers run at index time. Test fixtures: keep a tiny per-pattern fixture
 (see `/tmp/cb-fixture/bus.js`; **move into `__tests__/`** when shipping).
 

scripts/add-lang/bench.sh

@@ -40,7 +40,7 @@ fi
 # 2. Wipe + index with the binary under test.
 echo "→ wiping .codegraph and indexing"
 rm -rf "$REPO/.codegraph"
-( cd "$REPO" && codegraph init -i ) || { echo "indexing failed"; exit 1; }
+( cd "$REPO" && codegraph init ) || { echo "indexing failed"; exit 1; }
 
 # 3. Verify extraction (cheap guard before the paid A/B).
 echo "→ verifying extraction"

scripts/agent-eval/audit.sh

@@ -51,7 +51,7 @@ fi
 #    binary that serves it — different versions extract differently).
 echo "→ [3/4] wiping .codegraph and re-indexing with $ACTUAL"
 rm -rf "$REPO/.codegraph"
-( cd "$REPO" && codegraph init -i ) || { echo "indexing failed"; exit 1; }
+( cd "$REPO" && codegraph init ) || { echo "indexing failed"; exit 1; }
 
 # 4. Run the with/without A/B.
 echo "→ [4/4] running A/B harness (mode=$MODE)"

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

@@ -43,10 +43,10 @@ Restart your agent (Claude Code / Cursor / Codex CLI / opencode / Hermes Agent /
 
 ```bash
 cd your-project
-codegraph init -i
+codegraph init
 ```
 
-This builds the per-project knowledge graph index and wires up any project-local agent surfaces, so a single global `codegraph install` works in every project you open.
+This creates `.codegraph/` and builds the per-project knowledge graph index, so a single global `codegraph install` works in every project you open.
 
 ## Supported platforms
 

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

@@ -28,7 +28,7 @@ CodeGraph bundles its own runtime — nothing to compile, no native build, works
 
 ```bash
 cd your-project
-codegraph init -i
+codegraph init
 ```
 
 That's it — your agent will use CodeGraph tools automatically when a `.codegraph/` directory exists.

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

@@ -9,10 +9,10 @@ Once CodeGraph is installed, building and exploring a graph takes three commands
 
 ```bash
 cd your-project
-codegraph init -i      # initialize + index in one step
+codegraph init         # initialize + index in one step
 ```
 
-`init` creates the `.codegraph/` directory; `-i` (or `--index`) immediately builds the full index. For an existing project you can re-index any time:
+`init` creates the `.codegraph/` directory and immediately builds the full index. The legacy `-i`/`--index` flag is still accepted for older scripts, but it is no longer required. For an existing project you can re-index any time:
 
 ```bash
 codegraph index          # full index

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

@@ -7,10 +7,10 @@ description: Full index, incremental sync, and the file watcher.
 
 ```bash
 cd your-project
-codegraph init -i      # initialize + full index
+codegraph init         # initialize + full index
 ```
 
-`init` creates `.codegraph/`; `-i`/`--index` builds the index immediately. To initialize without indexing, drop the flag and run `codegraph index` later.
+`init` creates `.codegraph/` and builds the initial index by default. The legacy `-i`/`--index` flag is still accepted for older scripts, but it is no longer required. Run `codegraph index` any time to rebuild.
 
 ## Full vs. incremental
 

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

@@ -7,7 +7,7 @@ description: Every CodeGraph command and the flags it accepts.
 codegraph                         # Run interactive installer
 codegraph install                 # Run installer (explicit)
 codegraph uninstall               # Remove CodeGraph from your agents (inverse of install)
-codegraph init [path]             # Initialize in a project (--index to also index)
+codegraph init [path]             # Initialize in a project and build the initial index
 codegraph uninit [path]           # Remove CodeGraph from a project (--force to skip prompt)
 codegraph index [path]            # Full index (--force to re-index, --quiet for less output)
 codegraph sync [path]             # Incremental update

src/installer/index.ts

@@ -208,7 +208,7 @@ export async function runInstallerWithOptions(opts: RunInstallerOptions): Promis
   }
 
   if (location === 'global') {
-    clack.note('cd your-project\ncodegraph init -i', 'Quick start');
+    clack.note('cd your-project\ncodegraph init', 'Quick start');
   }
 
   const finalNote = targets.length > 0
@@ -455,7 +455,7 @@ async function initializeLocalProject(
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     clack.log.error(`Could not load native modules: ${msg}`);
-    clack.log.info('Skipping project initialization. Run "codegraph init -i" later.');
+    clack.log.info('Skipping project initialization. Run "codegraph init" later.');
     return;
   }
 

src/mcp/server-instructions.ts

@@ -63,7 +63,7 @@ typically one to a few calls; a grep/read exploration is dozens.
 
 ## Limitations
 
-- If a tool reports the project isn't initialized, \`.codegraph/\` doesn't exist yet — offer to run \`codegraph init -i\` to build the index.
+- If a tool reports the project isn't initialized, \`.codegraph/\` doesn't exist yet — offer to run \`codegraph init\` to build the index.
 - Index lags file writes by ~1 second.
 - Cross-file resolution is best-effort name matching; ambiguous calls may return multiple candidates.
 - No live correctness validation — that's still the TypeScript compiler / test suite / linter's job. Codegraph supplements those with structural context they don't have.

src/sync/worktree.ts

@@ -86,7 +86,7 @@ export function worktreeMismatchWarning(m: WorktreeIndexMismatch): string {
     `  Running in: ${m.worktreeRoot}\n` +
     `  Index from: ${m.indexRoot}\n` +
     `Results reflect that tree's code (often a different branch), not this worktree — ` +
-    `symbols changed only here are missing. Run "codegraph init -i" in this worktree ` +
+    `symbols changed only here are missing. Run "codegraph init" in this worktree ` +
     `for a worktree-local index.`
   );
 }
@@ -100,7 +100,7 @@ export function worktreeMismatchNotice(m: WorktreeIndexMismatch): string {
   return (
     `⚠ CodeGraph results below come from a different git worktree (${m.indexRoot}), ` +
     `not where you're working (${m.worktreeRoot}) — they may reflect another branch, ` +
-    `and symbols changed only here are missing. Run "codegraph init -i" here for a ` +
+    `and symbols changed only here are missing. Run "codegraph init" here for a ` +
     `worktree-local index.`
   );
 }