From 0b84f02cc2395f6ea1ccf4c4bc34d29d958e24aa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=AB=98=E6=98=A5=E6=99=96?= <18220699480@163.com> Date: Wed, 3 Jun 2026 02:05:52 +0800 Subject: [PATCH] docs(init): align setup guidance with default indexing --- CHANGELOG.md | 3 +++ README.md | 12 ++++++------ docs/SEARCH_QUALITY_LOOP.md | 6 +++--- docs/benchmarks/codegraph-ab-matrix.md | 2 +- docs/design/callback-edge-synthesis.md | 2 +- docs/design/dynamic-dispatch-coverage-playbook.md | 4 ++-- scripts/add-lang/bench.sh | 2 +- scripts/agent-eval/audit.sh | 2 +- .../src/content/docs/getting-started/installation.md | 4 ++-- site/src/content/docs/getting-started/quickstart.md | 2 +- .../content/docs/getting-started/your-first-graph.md | 4 ++-- site/src/content/docs/guides/indexing.md | 4 ++-- site/src/content/docs/reference/cli.md | 2 +- src/installer/index.ts | 4 ++-- src/mcp/server-instructions.ts | 2 +- src/sync/worktree.ts | 4 ++-- 16 files changed, 31 insertions(+), 28 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b67542f28..8775911af 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index 9bf05dd1d..ba494b60d 100644 --- a/README.md +++ b/README.md @@ -52,10 +52,10 @@ npm i -g @colbymchenry/codegraph ```bash cd your-project -codegraph init -i +codegraph init ``` -`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. +`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.
@@ -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 diff --git a/docs/SEARCH_QUALITY_LOOP.md b/docs/SEARCH_QUALITY_LOOP.md index 97d57dedf..4ad210b0b 100644 --- a/docs/SEARCH_QUALITY_LOOP.md +++ b/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 /.codegraph -node dist/bin/codegraph.js init -iv +node dist/bin/codegraph.js init -v ``` -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 /.codegraph -node dist/bin/codegraph.js init -iv +node dist/bin/codegraph.js init -v # Re-run the failing tests from above ``` diff --git a/docs/benchmarks/codegraph-ab-matrix.md b/docs/benchmarks/codegraph-ab-matrix.md index db9d0370d..5eef5f7ed 100644 --- a/docs/benchmarks/codegraph-ab-matrix.md +++ b/docs/benchmarks/codegraph-ab-matrix.md @@ -120,6 +120,6 @@ than faked. Canonical harness: `scripts/agent-eval/run-all.sh "" 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/`). diff --git a/docs/design/callback-edge-synthesis.md b/docs/design/callback-edge-synthesis.md index bef831623..e20f8cdca 100644 --- a/docs/design/callback-edge-synthesis.md +++ b/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 \ diff --git a/docs/design/dynamic-dispatch-coverage-playbook.md b/docs/design/dynamic-dispatch-coverage-playbook.md index aa65398e4..db773eb58 100644 --- a/docs/design/dynamic-dispatch-coverage-playbook.md +++ b/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 /.codegraph && ( cd && codegraph init -i ) +rm -rf /.codegraph && ( cd && codegraph init ) node scripts/agent-eval/probe-trace.mjs # does the flow break? where? node scripts/agent-eval/probe-node.mjs # trail: is the next hop missing? ``` @@ -214,7 +214,7 @@ were found). Confirm it's dynamic by reading the break symbol's body. | `sqlite3 /.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 /.codegraph && codegraph init -i`) — the +extraction or resolution change (`rm -rf /.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). diff --git a/scripts/add-lang/bench.sh b/scripts/add-lang/bench.sh index 172fe4064..372622933 100755 --- a/scripts/add-lang/bench.sh +++ b/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" diff --git a/scripts/agent-eval/audit.sh b/scripts/agent-eval/audit.sh index 979e88e62..ffce77f11 100755 --- a/scripts/agent-eval/audit.sh +++ b/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)" diff --git a/site/src/content/docs/getting-started/installation.md b/site/src/content/docs/getting-started/installation.md index 4e8a0e2ce..6cfd10d5d 100644 --- a/site/src/content/docs/getting-started/installation.md +++ b/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 diff --git a/site/src/content/docs/getting-started/quickstart.md b/site/src/content/docs/getting-started/quickstart.md index 1d63bb489..6a884d073 100644 --- a/site/src/content/docs/getting-started/quickstart.md +++ b/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. diff --git a/site/src/content/docs/getting-started/your-first-graph.md b/site/src/content/docs/getting-started/your-first-graph.md index 916edbd44..fff09c375 100644 --- a/site/src/content/docs/getting-started/your-first-graph.md +++ b/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 diff --git a/site/src/content/docs/guides/indexing.md b/site/src/content/docs/guides/indexing.md index 7c0fd1ddc..29b34b745 100644 --- a/site/src/content/docs/guides/indexing.md +++ b/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 diff --git a/site/src/content/docs/reference/cli.md b/site/src/content/docs/reference/cli.md index 76f0e5a31..9eba0a998 100644 --- a/site/src/content/docs/reference/cli.md +++ b/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 diff --git a/src/installer/index.ts b/src/installer/index.ts index edd48ecaf..c66f674ac 100644 --- a/src/installer/index.ts +++ b/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; } diff --git a/src/mcp/server-instructions.ts b/src/mcp/server-instructions.ts index 43cc227ad..2d90cce42 100644 --- a/src/mcp/server-instructions.ts +++ b/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. diff --git a/src/sync/worktree.ts b/src/sync/worktree.ts index bf370b178..458df8d67 100644 --- a/src/sync/worktree.ts +++ b/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.` ); }