Add relationship-aware graph flow

docs/CONTRACT.md

@@ -1,4 +1,4 @@
-# DocForge 0.7 contract
+# DocForge 0.10 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.9.0.
+- Core, CLI, and MCP server: version 0.10.0.
 
 Schema files describe the generic interchange contract. Runtime validation remains responsible for
 path confinement, source hashing, relationship resolution, dependency cycles, project limits, stale
@@ -107,7 +107,7 @@ family, authority, status, or tag plus one exact value. The heartbeat changes no
 state. There is no write endpoint, arbitrary query endpoint, static filesystem handler, external
 asset, or project-selection control.
 
-The `graph-browser@7` template provides mouse-wheel zoom centered on the pointer, left-button drag
+The `graph-browser@8` template provides mouse-wheel zoom centered on the pointer, left-button drag
 pan, explicit zoom-in and zoom-out buttons, a reset-view button, and a live zoom percentage. A
 four-pixel drag threshold defers pointer capture and preserves node activation for ordinary clicks.
 Loading another root node fits the viewport to the returned neighborhood, including a useful
@@ -127,16 +127,26 @@ controls, and backdrop dismissal. Loading the inspected node as the new root req
 Explore neighborhood action. Both side panels support pointer and keyboard resizing. The unblurred
 full inspector supports native resizing and constrained title-bar dragging.
 
-The header exposes a Nodes/Flow segmented selector. Both positions intentionally retain the node
-graph in this contract version. Flow traversal and layout semantics remain unclaimed until relation
-direction and eligibility are defined.
+The header exposes a Nodes/Flow segmented selector. Nodes displays the complete bounded
+neighborhood. Flow displays an upstream lineage ending at the current root. Calls, dispatches,
+launches, activations, and writes retain their declared source-to-target direction. Reads, imports,
+and dependencies reverse for lineage presentation because the declared target feeds the source.
+Structural, evidence, and context relations remain available in Nodes but are excluded from Flow.
+This is a presentation transform over the validated bounded snapshot; it does not add or change
+project relationships.
 
-The browser derives presentation roles only from the returned bounded graph. The current root is
-the primary focus. Nodes reachable through outgoing edges are children. Remaining incoming and
-cross-boundary nodes are edge/context nodes. These roles receive distinct palettes and navigation
-sections. An undirected shortest-hop calculation places nodes on distance rings and darkens each
-role palette progressively, capped at fifty percent. This presentation does not reinterpret,
-replace, or add project relationships.
+Both views color edges by relationship semantics and retain direction with visible SVG endpoint
+symbols. Line patterns provide a non-color cue. A static canvas key shows the exact symbol, color,
+label, and visible count for each displayed relation, including a deterministic fallback for
+project-defined relations. Nodes and Flow use the same map.
+
+The browser derives node presentation roles only from the returned bounded graph. The current root
+is the focus. In Nodes, nodes reachable through outgoing edges are shown as outgoing paths; the
+remaining visible nodes are incoming or lateral context. In Flow, lineage predecessors are shown as
+upstream nodes. These roles receive distinct palettes and navigation sections. An undirected
+shortest-hop calculation places Nodes on distance rings; Flow uses left-to-right distance layers
+with the destination on the right. Each role palette darkens progressively by distance, capped at
+fifty percent.
 
 Each invocation launches the validated snapshot in a detached local worker. The worker is outside
 the short-lived MCP transport process, so transport teardown cannot close an active browser. It

docs/MCP_CONTRACT.md

@@ -61,7 +61,7 @@ only through the explicit local CLI integration command.
 
 ## Visualization boundary
 
-`docforge_visualize` starts the fixed built-in `graph-browser@7` template against the currently
+`docforge_visualize` starts the fixed built-in `graph-browser@8` 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.
 
@@ -75,11 +75,15 @@ drag pan, explicit zoom buttons, reset, and Space-to-center selection never requ
 project data. Left activation visibly selects the node and opens a compact descriptor card.
 Right-click opens the full inspector. Descriptor-pill activation fills the fixed left panel with an
 exact bounded category result set. The fixed right panel contains neighborhood navigation.
-Replacing the current root requires an explicit Explore neighborhood action. The Nodes/Flow
-selector retains the same graph until a later contract defines flow semantics. The open browser
-renews a bounded lease in a detached local worker, so standard-input transaction completion does
-not close the listener. The worker tracks the longer-lived MCP client host and closes when that
-owner exits.
+Replacing the current root requires an explicit Explore neighborhood action. Nodes presents the
+bounded neighborhood with relation-specific colors, line patterns, directional symbols, and a
+visible key. Its navigation groups the focus, nodes reachable through outgoing edges, and remaining
+incoming or lateral context. Flow presents the same bounded snapshot as an upstream lineage.
+Execution edges retain their declared direction; reads, imports, and dependencies reverse to show
+what feeds the focus; structural, evidence, and context edges are excluded. The same relationship
+key is regenerated from the visible Flow edges. The open browser renews a bounded lease in a
+detached local worker, so standard-input transaction completion does not close the listener. The
+worker tracks the longer-lived MCP client host and closes when that owner exits.
 Explicit service shutdown closes its tracked worker, and abandoned pages expire.
 
 ## Excluded tools

docs/NEW_PROJECT_QUICKSTART.md

@@ -16,12 +16,13 @@ The DocForge repository contains the complete generic CLI and stdio MCP server.
 
 - Project identity, validation, exact-node retrieval, lexical search, and filtering.
 - Backlinks, dependency traversal, impact traversal, and bounded context profiles.
-- `docforge_visualize`, which starts the token-protected, loopback-only `graph-browser@7` viewer.
+- `docforge_visualize`, which starts the token-protected, loopback-only `graph-browser@8` viewer.
   The viewer supports search, family filtering, exact-node inspection, bounded neighborhoods,
   exact descriptor-pill filtering, compact left-click descriptors, full right-click inspection,
   fixed search and neighborhood side panels, explicit neighborhood exploration, fitted single- and
   multi-node framing, visible node selection, Space-to-center, mouse-wheel zoom, left-button drag
-  panning, zoom controls, viewport reset, and a reserved Nodes/Flow selector.
+  panning, zoom controls, viewport reset, relationship color and symbol keys, and an upstream
+  lineage Flow view.
 - Isolated documentation changesets, proposal validation, diffs, and escaped HTML previews when a
   proposal writer and render view are configured.