Stop telling assistants to read GRAPH_REPORT.md first (#580)

[jattree]

Fixes #580.

Three users on that issue reported Claude Code using more tokens with graphify installed than without. The cause is the install-time instruction set, which writes ALWAYS read graphify-out/GRAPH_REPORT.md before reading any source files, running grep/glob searches, or answering codebase questions into the project's CLAUDE.md (and the equivalent into AGENTS.md, GEMINI.md, .cursor/rules/, etc.), plus a PreToolUse hook with the same instruction. On real corpora the report is 47-91K characters, so sessions pay roughly 12-25K tokens of context up front for every search-able question.

Reproduced on a 1500-file Go monorepo using a "where is the Studio type defined" question:

Setup	Tool calls	Agent tokens	First action
Stock graphify (pre-patch)	5	34k	Read GRAPH_REPORT.md → fails (exceeds 25K Read cap) → falls back
No graphify (vanilla baseline)	4	30k	grep -rn "type Studio"
This patch	1	30k	graphify query "..."

Stock graphify is measurably worse than no graphify at all on this corpus, which is the user's complaint. With the patch it matches the no-install token count, drops to one tool call, and surfaces 6 related entities for free from the same BFS subgraph.

What changed

Demote GRAPH_REPORT.md to a fallback for broad architecture review. Route first action to the scoped commands that already exist: graphify query, graphify path, graphify explain. The 2k-budget BFS subgraph is already in serve.py; the install just wasn't pointing at it.

Applied across all ten install surfaces for consistency:

• _SETTINGS_HOOK (Claude Code PreToolUse)
• _CLAUDE_MD_SECTION
• _AGENTS_MD_SECTION (Codex / OpenCode / OpenClaw / Aider / Trae)
• _GEMINI_MD_SECTION
• _GEMINI_HOOK
• _VSCODE_INSTRUCTIONS_SECTION (Copilot)
• _ANTIGRAVITY_RULES
• _KIRO_STEERING
• _CURSOR_RULE
• _OPENCODE_PLUGIN_JS

Plus the matching sentence in README.md. The README also had an inaccuracy: it claimed hooks on Claude Code, Codex, and Gemini CLI all fire before tool calls, but the Codex hook is intentionally a no-op (hook-check does nothing because Codex rejects additionalContext). Reworded to distinguish payload-bearing hooks from instruction-file-only platforms.

Upgrade-in-place fix

Five installers (claude, agents, vscode, gemini, kiro, cursor) were writing their section only when no marker was present, so users who installed graphify pre-fix and ran graphify <platform> install again after upgrading kept the old "ALWAYS read" text on disk. The bug would have stayed live for them.

Added _replace_or_append_section helper that updates in place when the graphify marker is found, treating the section as everything from the marker line to the next H2 heading (or EOF). For wholly-graphify-owned files (.kiro/steering/graphify.md, .cursor/rules/graphify.mdc) the installer now overwrites when content differs.

claude_install also no longer returns before _install_claude_hook, so a stale .claude/settings.json hook payload gets refreshed on upgrade rather than left in place.

Tests

• tests/test_install_strings.py (3 tests): every install constant still mentions graphify query; regex check for banned report-first phrasing (read .*GRAPH_REPORT.md.*before, first tool call.*GRAPH_REPORT, always read.*GRAPH_REPORT); GRAPH_REPORT.md is still referenced in MD sections as the demoted fallback.
• tests/test_install_upgrade.py (7 tests): seeds each platform's instruction file (CLAUDE.md, AGENTS.md, GEMINI.md, .github/copilot-instructions.md, .cursor/rules/graphify.mdc, .kiro/steering/graphify.md, plus the stale Claude hook payload in .claude/settings.json) with pre-fix text, runs install, asserts the on-disk file now contains graphify query and no longer contains the old report-first phrasing.
• test_claude_md.py idempotency tests still pass (the existing "already configured" wording is preserved).

Full suite: 819 pass, 11 pre-existing failures unchanged, zero regressions.

Note on ALWAYS

The regex check intentionally does not ban the bare word ALWAYS. alwaysApply: true (Cursor) and trigger: always_on (Antigravity) are legitimate platform metadata. The banned patterns target report-first semantics, not the keyword.

Scope

10 install constants changed, 1 README sentence, 1 new helper, 6 installer updates, 2 new test files. No architecture changes, no marketing-claim touches, no new artifacts. Happy to split the upgrade-in-place changes out as a follow-up PR if preferred, but they share a load-bearing dependency on the helper.

[diwanmail]

I’ve encountered the same issue where token usage suddenly jumps, and I don’t think it’s happening because of Graph_report.md—I don’t see it being read.

The problem I see is that the query CLI returns a default limit of 2000 tokens, and many times it does not include all the relevant nodes in the response. The response gets cut due to the 2000-token budget, and many of the returned nodes are not meaningful. Because of this, Claude Code ends up doing additional reasoning, making multiple query and explain calls, which further fills the context (another ~2K tokens per query command).

I think the seed scoring mechanism needs significant improvement so that the query command returns more meaningful and relevant nodes.

And when I run the same query with disabled Graphify, it returns faster and less token count.

Another thing: why do we need the /graphify skill for query and explain? Internally, it is just running CLI commands anyway, and CLAUDE.md already instructs Claude to use Graphify query, explain, and path commands. Claude can directly invoke the Graphify CLI using the bash tool.