fix(instructions): graph narrows scope, source verifies, and upgrades actually reach existing users

.github/copilot-instructions.md

@@ -1,11 +1,9 @@
 <!-- code-review-graph MCP tools -->
 ## MCP Tools: code-review-graph
 
-**IMPORTANT: This project has a knowledge graph. ALWAYS use the
-code-review-graph MCP tools BEFORE using Grep/Glob/Read to explore
-the codebase.** The graph is faster, cheaper (fewer tokens), and gives
-you structural context (callers, dependents, test coverage) that file
-scanning cannot.
+**This project has a knowledge graph. Start with the code-review-graph
+MCP tools to narrow scope, then read the source.** The graph is cheaper than scanning files and
+gives you structural context (callers, dependents, test coverage) that file search cannot.
 
 ### When to use graph tools FIRST
 
@@ -15,7 +13,15 @@ scanning cannot.
 - **Finding relationships**: `query_graph_tool` with callers_of/callees_of/imports_of/tests_for
 - **Architecture questions**: `get_architecture_overview_tool` + `list_communities_tool`
 
-Fall back to Grep/Glob/Read **only** when the graph doesn't cover what you need.
+### Verify in the source
+
+- Narrow scope with the graph, then read the source. Do not change code from graph output alone.
+- For any non-trivial change, read the implementation and the relevant tests before concluding.
+- Verify the exact source when touching behavior, database logic, migrations, retries, fallbacks,
+  recovery, or compatibility code.
+- When the graph and the source disagree, the source wins. The graph may be stale or may not
+  model that relationship.
+- An empty graph result can mean "not indexed" or "not statically visible", not "does not exist".
 
 ### Key Tools
 
@@ -36,3 +42,4 @@ Fall back to Grep/Glob/Read **only** when the graph doesn't cover what you need.
 2. Use `detect_changes_tool` for code review.
 3. Use `get_affected_flows_tool` to understand impact.
 4. Use `query_graph_tool` pattern="tests_for" to check coverage.
+<!-- /code-review-graph MCP tools -->

AGENTS.md

@@ -86,11 +86,9 @@ bd close <id>         # Complete work
 <!-- code-review-graph MCP tools -->
 ## MCP Tools: code-review-graph
 
-**IMPORTANT: This project has a knowledge graph. ALWAYS use the
-code-review-graph MCP tools BEFORE using Grep/Glob/Read to explore
-the codebase.** The graph is faster, cheaper (fewer tokens), and gives
-you structural context (callers, dependents, test coverage) that file
-scanning cannot.
+**This project has a knowledge graph. Start with the code-review-graph
+MCP tools to narrow scope, then read the source.** The graph is cheaper than scanning files and
+gives you structural context (callers, dependents, test coverage) that file search cannot.
 
 ### When to use graph tools FIRST
 
@@ -100,12 +98,20 @@ scanning cannot.
 - **Finding relationships**: `query_graph_tool` with callers_of/callees_of/imports_of/tests_for
 - **Architecture questions**: `get_architecture_overview_tool` + `list_communities_tool`
 
-Fall back to Grep/Glob/Read **only** when the graph doesn't cover what you need.
+### Verify in the source
+
+- Narrow scope with the graph, then read the source. Do not change code from graph output alone.
+- For any non-trivial change, read the implementation and the relevant tests before concluding.
+- Verify the exact source when touching behavior, database logic, migrations, retries, fallbacks,
+  recovery, or compatibility code.
+- When the graph and the source disagree, the source wins. The graph may be stale or may not
+  model that relationship.
+- An empty graph result can mean "not indexed" or "not statically visible", not "does not exist".
 
 ### Key Tools
 
 | Tool | Use when |
-|------|----------|
+| ------ | ---------- |
 | `detect_changes_tool` | Reviewing code changes — gives risk-scored analysis |
 | `get_review_context_tool` | Need source snippets for review — token-efficient |
 | `get_impact_radius_tool` | Understanding blast radius of a change |
@@ -121,3 +127,4 @@ Fall back to Grep/Glob/Read **only** when the graph doesn't cover what you need.
 2. Use `detect_changes_tool` for code review.
 3. Use `get_affected_flows_tool` to understand impact.
 4. Use `query_graph_tool` pattern="tests_for" to check coverage.
+<!-- /code-review-graph MCP tools -->

CHANGELOG.md

@@ -35,6 +35,29 @@
 
 ### Fixed
 
+- The generated instruction sections no longer tell agents to always use the
+  graph before reading source and to fall back to file search only when the
+  graph misses. Every platform instruction file now carries the same short
+  guardrails: narrow scope with the graph, read the implementation and its
+  tests before a non-trivial change, prefer the source when the two disagree,
+  and treat an empty graph result as possibly unindexed rather than absent.
+  CONTRIBUTING.md also states what a new platform target must include before
+  it will be reviewed (#314).
+- Reinstalling now upgrades an instruction section written by an older release
+  instead of skipping the file because the opening marker was already there,
+  which is what made every wording fix invisible to existing users. Generated
+  sections carry a closing marker so the block has real boundaries; blocks from
+  before that marker existed are matched by their exact recorded text, so
+  anything written around them survives byte for byte. A section someone edited
+  by hand is left alone and named in the install output instead of being
+  overwritten, and `install` now reports created, updated and left-alone files
+  separately (#314, #558).
+- `uninstall` now removes an instruction section written by any past release,
+  not only one written by the running version, so asking for the instructions
+  to go no longer leaves orphaned text behind. It matches the same recorded
+  block texts install uses, clears duplicate blocks, keeps the text on both
+  sides of the block, closes the gap without leaving a run of blank lines, and
+  still refuses to touch a section that was edited by hand (#314).
 - C# receiver calls (`Service.StaticCall()`, `obj.Method()`, `obj?.Method()`)
   now resolve to canonical method nodes using receiver-type and namespace
   evidence recorded at parse time, so `callers_of`, `get_impact_radius`, and

CLAUDE.md

@@ -169,11 +169,9 @@ bd close <id>         # Complete work
 <!-- code-review-graph MCP tools -->
 ## MCP Tools: code-review-graph
 
-**IMPORTANT: This project has a knowledge graph. ALWAYS use the
-code-review-graph MCP tools BEFORE using Grep/Glob/Read to explore
-the codebase.** The graph is faster, cheaper (fewer tokens), and gives
-you structural context (callers, dependents, test coverage) that file
-scanning cannot.
+**This project has a knowledge graph. Start with the code-review-graph
+MCP tools to narrow scope, then read the source.** The graph is cheaper than scanning files and
+gives you structural context (callers, dependents, test coverage) that file search cannot.
 
 ### When to use graph tools FIRST
 
@@ -183,12 +181,20 @@ scanning cannot.
 - **Finding relationships**: `query_graph_tool` with callers_of/callees_of/imports_of/tests_for
 - **Architecture questions**: `get_architecture_overview_tool` + `list_communities_tool`
 
-Fall back to Grep/Glob/Read **only** when the graph doesn't cover what you need.
+### Verify in the source
+
+- Narrow scope with the graph, then read the source. Do not change code from graph output alone.
+- For any non-trivial change, read the implementation and the relevant tests before concluding.
+- Verify the exact source when touching behavior, database logic, migrations, retries, fallbacks,
+  recovery, or compatibility code.
+- When the graph and the source disagree, the source wins. The graph may be stale or may not
+  model that relationship.
+- An empty graph result can mean "not indexed" or "not statically visible", not "does not exist".
 
 ### Key Tools
 
 | Tool | Use when |
-|------|----------|
+| ------ | ---------- |
 | `detect_changes_tool` | Reviewing code changes — gives risk-scored analysis |
 | `get_review_context_tool` | Need source snippets for review — token-efficient |
 | `get_impact_radius_tool` | Understanding blast radius of a change |
@@ -204,3 +210,4 @@ Fall back to Grep/Glob/Read **only** when the graph doesn't cover what you need.
 2. Use `detect_changes_tool` for code review.
 3. Use `get_affected_flows_tool` to understand impact.
 4. Use `query_graph_tool` pattern="tests_for" to check coverage.
+<!-- /code-review-graph MCP tools -->

CONTRIBUTING.md

@@ -80,6 +80,47 @@ If you just need a language for your own repo, you may not need to contribute at
 3. Add a sample fixture file in `tests/fixtures/`
 4. Add parsing tests in `tests/test_multilang.py`
 
+## Adding a Platform Target
+
+Every supported AI tool is permanent maintenance surface. Its config path, schema, install merge,
+uninstall, and tests all have to keep working on every release. Some existing targets were merged
+without any evidence that the integration worked in a released client, and those are the ones that
+break. New targets are held to the bar below.
+
+Start with a platform request issue (https://github.com/tirth8205/code-review-graph/issues/new/choose)
+so the client can be discussed before anyone writes code. A pull request that adds a platform will
+not be reviewed until it includes all of the following.
+
+1. A link to the platform's official MCP configuration documentation. Blog posts, forum replies,
+   and screenshots of a settings dialog are not enough.
+2. The exact config file path and the exact schema of a server entry, including which top-level key
+   holds the servers, whether that value is an object or an array, and whether a `type` field is
+   required.
+3. The entry added through the existing `PLATFORMS` table in `code_review_graph/skills.py`, plus
+   `_PLATFORM_CHOICES` in `code_review_graph/cli.py`. Use the fields already there: `name`,
+   `config_path`, `key`, `detect`, `format`, `needs_type`, and where needed `legacy_keys`,
+   `server_type`, `entry_fields`. If the client needs something the table cannot express, say so in
+   the pull request and explain why, rather than adding a bespoke code path beside it.
+4. Preservation of unrelated user settings. Install must merge only the `code-review-graph` server
+   entry and leave every other server, key, and top-level setting intact. If the file cannot be
+   parsed, install must skip it rather than rewrite it.
+5. A byte-idempotent reinstall. Running install twice must leave the config file and any generated
+   instruction file byte for byte identical.
+6. A working uninstall in `code_review_graph/uninstall.py` that removes only what install added,
+   including any legacy keys, and leaves the rest of the file untouched.
+7. Lifecycle tests matching the existing ones: an install, reinstall, and uninstall test in
+   `tests/test_cli_install.py` shaped like `test_copilot_cli_install_reinstall_uninstall_lifecycle`,
+   and a passing run of the all-platforms sweep in `tests/test_uninstall.py`
+   (`test_uninstall_removes_mcp_entry_for_every_current_platform_spec`), which every new entry is
+   automatically subject to.
+8. Evidence from a real released client: a screenshot or transcript of an actual session in that
+   client where a code-review-graph tool is invoked and returns a result. A rendered image of text,
+   a mockup, or a description of what should happen is not evidence.
+
+If no maintainer can install and run the client, the request may be declined or left open until
+someone who uses it is willing to own it and respond when it breaks. An existing target may also be
+removed if it breaks and nobody steps up to fix it.
+
 ## Reporting Issues
 
 - Open an issue via the issue forms: https://github.com/tirth8205/code-review-graph/issues/new/choose (bug report, feature request, or platform request — blank issues are disabled)

GEMINI.md

@@ -1,11 +1,9 @@
 <!-- code-review-graph MCP tools -->
 ## MCP Tools: code-review-graph
 
-**IMPORTANT: This project has a knowledge graph. ALWAYS use the
-code-review-graph MCP tools BEFORE using Grep/Glob/Read to explore
-the codebase.** The graph is faster, cheaper (fewer tokens), and gives
-you structural context (callers, dependents, test coverage) that file
-scanning cannot.
+**This project has a knowledge graph. Start with the code-review-graph
+MCP tools to narrow scope, then read the source.** The graph is cheaper than scanning files and
+gives you structural context (callers, dependents, test coverage) that file search cannot.
 
 ### When to use graph tools FIRST
 
@@ -15,12 +13,20 @@ scanning cannot.
 - **Finding relationships**: `query_graph_tool` with callers_of/callees_of/imports_of/tests_for
 - **Architecture questions**: `get_architecture_overview_tool` + `list_communities_tool`
 
-Fall back to Grep/Glob/Read **only** when the graph doesn't cover what you need.
+### Verify in the source
+
+- Narrow scope with the graph, then read the source. Do not change code from graph output alone.
+- For any non-trivial change, read the implementation and the relevant tests before concluding.
+- Verify the exact source when touching behavior, database logic, migrations, retries, fallbacks,
+  recovery, or compatibility code.
+- When the graph and the source disagree, the source wins. The graph may be stale or may not
+  model that relationship.
+- An empty graph result can mean "not indexed" or "not statically visible", not "does not exist".
 
 ### Key Tools
 
 | Tool | Use when |
-|------|----------|
+| ------ | ---------- |
 | `detect_changes_tool` | Reviewing code changes — gives risk-scored analysis |
 | `get_review_context_tool` | Need source snippets for review — token-efficient |
 | `get_impact_radius_tool` | Understanding blast radius of a change |
@@ -36,3 +42,4 @@ Fall back to Grep/Glob/Read **only** when the graph doesn't cover what you need.
 2. Use `detect_changes_tool` for code review.
 3. Use `get_affected_flows_tool` to understand impact.
 4. Use `query_graph_tool` pattern="tests_for" to check coverage.
+<!-- /code-review-graph MCP tools -->