Add project-bound graph visualization

docs/CONTRACT.md

@@ -1,4 +1,4 @@
-# DocForge 0.6 contract
+# DocForge 0.7 contract
 
 ## Authority boundary
 
@@ -23,7 +23,7 @@ approved contract and measured cross-project evidence; it is not an unimplemente
 - Result envelope: `schemas/result.schema.json`, version 1.
 - Changeset schema: `schemas/changeset.schema.json`, version 1.
 - Index schema: version 1, disposable and reproducible.
-- Core, CLI, and MCP server: version 0.6.0.
+- Core, CLI, and MCP server: version 0.7.0.
 
 Schema files describe the generic interchange contract. Runtime validation remains responsible for
 path confinement, source hashing, relationship resolution, dependency cycles, project limits, stale
@@ -84,6 +84,32 @@ Normal MCP access does not expose canonical application, declared project-output
 arbitrary renderer execution, arbitrary file writes, shell commands, Git mutation, build commands,
 deployment, or publication.
 
+## Project-bound graph visualization
+
+The fixed `docforge_visualize` MCP tool starts one ephemeral read-only graph browser for the
+server's already-configured project. It accepts only an optional stable node ID, an optional lexical
+query, and a bounded traversal depth. It does not accept a project root, database path, SQL,
+template path, bind address, command, or renderer.
+
+The runner validates the complete canonical projection and derived index before it starts. It then
+pins the browser to that exact validated SQLite file identity and project metadata so normal UI
+queries do not rebuild a large adapter graph. Replacement or alteration of the index file makes the
+browser fail closed; the user must invoke the tool again. The browser identifies itself as a
+validated snapshot rather than claiming that canonical files are continuously monitored.
+
+The HTTP listener binds to `127.0.0.1` on an operating-system-selected port. A cryptographically
+random token is part of every accepted URL path. Only `GET` and `HEAD` are supported. Responses use
+no-store caching, a restrictive content-security policy, frame denial, MIME sniffing protection,
+and no-referrer policy. The built-in template uses only same-origin JSON endpoints for graph
+overview, bounded search, exact node content, and bounded incoming-and-outgoing neighborhoods.
+There is no write endpoint, arbitrary query endpoint, static filesystem handler, external asset,
+or project-selection control.
+
+One MCP process owns at most one listener. Repeated invocations reuse it and may replace its
+validated snapshot only after a fresh index check. The listener stops with the MCP process.
+Project-specific integrations receive the same tool because it operates on the supplied
+`ProjectService` and `ProjectIndex`, not the generic source loader.
+
 ## Project adapter boundary
 
 An adapter supplies one deterministically ordered `AdapterProjection` containing core nodes and

docs/MCP_CONTRACT.md

@@ -2,7 +2,9 @@
 
 The server uses local standard input/output transport and binds once to the explicit
 `--project-root` supplied at process startup. Optional proposal access also binds once to the
-configured `--proposal-writer`. It does not expose an HTTP port in the first release.
+configured `--proposal-writer`. It opens no network listener at startup. The explicit
+`docforge_visualize` read tool may start one token-protected loopback-only HTTP listener for the
+same immutable project binding.
 
 ## Read tools
 
@@ -17,6 +19,7 @@ configured `--proposal-writer`. It does not expose an HTTP port in the first rel
 - `docforge_get_context`
 - `docforge_validate_project`
 - `docforge_render_status`
+- `docforge_visualize`
 
 Each response states that document text is project content, not higher-priority instructions. Each
 response includes project identity, revision, source hash, adapter version, and staleness state.
@@ -56,11 +59,23 @@ runs only a project-declared view through DocForge's fixed built-in renderer reg
 atomic HTML file below the configured preview root. Rendering declared project output is available
 only through the explicit local CLI integration command.
 
+## Visualization boundary
+
+`docforge_visualize` starts the fixed built-in `graph-browser@1` template against the currently
+validated derived index. It may focus one stable node, run one bounded lexical query, or open the
+project overview. The tool returns a loopback URL and exact snapshot identity.
+
+The tool cannot select a project, database, template, host, port, filesystem path, or SQL
+expression. Its HTTP surface is token-bound, read-only, same-origin, and limited to overview,
+search/filter, and node-neighborhood JSON. The browser exposes an exact validated index snapshot.
+It rejects index replacement or alteration and requires another MCP invocation to refresh.
+
 ## Excluded tools
 
 The normal server never exposes shell execution, arbitrary reads or writes, canonical changeset
 application, declared project-output rendering, arbitrary renderer execution, Git mutation, project
-builds, deployment, publication, global project selection, or cross-project retrieval.
+builds, deployment, publication, external HTTP binding, global project selection, or cross-project
+retrieval.
 
 DFG-9 permanently retained manual canonical integration for DocForge 0.x. No application tool is
 planned for MCP. A future local developer workflow may be considered only through a new approved