Document DocForge graph view semantics

README.md

@@ -18,6 +18,24 @@ declared manuals, visualizes project structure, and manages reviewable documenta
 DocForge never treats indexed text as instructions. It does not run shell commands, mutate Git,
 build applications, deploy, publish, or select projects globally.
 
+## Graph views
+
+The browser presents the same indexed graph through three complementary views:
+
+- **Nodes** shows a bounded, relation-neutral neighborhood around the focus. It is the broad
+  inspection view for seeing stored incoming and outgoing relationships without changing their
+  direction.
+- **Flow** shows semantic origin-to-destination paths that terminate at the focus. DocForge
+  reverses prerequisite-style relationships for presentation, so imports, dependencies, reads,
+  inheritance, definitions, and tests flow toward the thing they help create or exercise.
+- **Web** shows the larger convergence picture: Flow contributors plus contextual relationships,
+  callers, containers, and direct members or execution dependencies owned by the focus.
+
+**Hide node** removes noise without changing the index. In Flow and Web, hiding a contributor also
+removes upstream ancestors that no longer have a path to the focus. Nodes between the hidden
+contributor and the focus stay visible, and alternate ancestor paths remain intact. **Restore
+hidden** restores the presentation.
+
 ## Five-minute start
 
 Requirements are Python 3.12+, `uv`, and Node.js/npm.

docs/USER_MANUAL.md

@@ -217,24 +217,86 @@ URL. Use `visualization-status` and `visualization-stop` to inspect or stop the
 - Left-click a node for its compact descriptor.
 - Right-click a node for the full inspector.
 - Use **Open source** to read the node’s project-confined source at its anchor.
-- Use **Hide node** to remove noisy non-focus nodes from the current presentation.
-- Use **Restore hidden** above the graph to bring hidden nodes back.
 - Use **Explore neighborhood** to make a node the new focus.
-- Switch to **Flow** to inspect relation-aware paths from origins and prerequisites into the
-  focus. Imports, dependencies, reads, inheritance, and `tested_by` relationships are reversed for
-  presentation so prerequisites point toward their consumers. Context-only documentation
-  relationships stay out of this focused view.
-- Switch to **Web** to inspect the broader structural and dependency makeup of the focus. DocForge
-  follows callers, containers, imports, dependencies, evidence, and contextual contributors into
-  the focus. Direct focus-owned members and execution dependencies become adjacent contributor
-  branches. Traversal does not fan back out through unrelated siblings.
 - Use the mouse wheel or viewport buttons to zoom. Drag the canvas to pan. Press Space to center
   the selected node.
 
-Hidden nodes are a browser presentation preference. They do not alter the index or canonical graph.
-The focus node cannot be hidden; focus another node first. In Flow and Web, hiding a node also
-prunes ancestors whose only remaining route to the focus passed through that node. Descendants
-between the hidden node and the focus remain visible, as do ancestors with another valid route.
+### Nodes: bounded neighborhood
+
+**Nodes** answers: “What is immediately related to this thing?”
+
+DocForge starts at the focus and traverses every stored incoming and outgoing relationship up to
+the selected depth and fixed edge limit. The graph preserves the relationships exactly as the
+index stores them. It does not reinterpret direction or exclude contextual relationships.
+
+The focus appears at the center. Outgoing nodes and their descendants form one visual role, while
+incoming or lateral nodes form another. This is the broadest view and is useful for inspecting raw
+adapter output, discovering nearby nodes, and choosing a better focus. It can also be the noisiest
+view because containment, documentation, dependencies, calls, imports, and other relationship
+types may all appear together.
+
+In Nodes, **Hide node** removes that node and its incident edges from the presentation. It does not
+remove other nodes merely because they become disconnected.
+
+### Flow: semantic paths into the focus
+
+**Flow** answers: “What origins and prerequisites lead to this thing?”
+
+Flow builds bounded semantic paths whose destination is the focus. Structural and execution
+relationships already aimed at the consumer keep their stored direction. Prerequisite-style
+relationships are reversed for presentation so arrows consistently point toward the thing being
+explained:
+
+- `defined_in`, `inherits`, and `imports` become definition, base-class, and imported-module
+  contributions.
+- `depends_on` and `reads` become dependency and data-source contributions.
+- `tested_by` becomes a test path into the exercised node.
+
+For example, a method can appear as:
+
+```text
+tests package → test module → test class → test method
+```
+
+The displayed reversal is a visualization rule only. It does not mutate the canonical
+relationship or derived index. Context-only relationships such as `documents`, `governs`, and
+`relates_to` are omitted so Flow remains a focused origin-to-destination explanation.
+
+### Web: convergence and makeup
+
+**Web** answers: “What makes up this thing, and what paths converge on it?”
+
+Web starts with the same semantic contributor direction as Flow, then includes contextual
+relationships that Flow intentionally omits. It can show callers, containers, imports,
+dependencies, evidence, documentation context, and other contributors converging on the focus.
+It also presents direct relationships owned by the focus as adjacent contributor branches,
+including supported `calls`, `contains`, `defines`, `dispatches_to`, `implemented_by`, `launches`,
+`writes`, and `activates` relationships.
+
+This makes classes and methods useful graph nodes rather than labels attached to a file. A class
+can show its containing module, base class, callers, tests, and methods. A method can show the
+package and class path that contains it alongside imported helpers, dependencies, callers, and
+evidence. Every displayed path is oriented toward the focused node.
+
+Adjacent traversal is deliberately bounded. After DocForge includes a direct member or execution
+dependency owned by the focus, it continues toward that branch rather than fanning back out
+through unrelated siblings. Depth and edge limits provide a second guard against an unbounded web.
+
+### Hiding nodes and pruning ancestors
+
+Hidden nodes are browser presentation state. Hiding never changes canonical files, the derived
+index, or future graph queries. The focus cannot be hidden; focus another node first.
+
+- In **Nodes**, hiding removes only the selected node and its incident edges.
+- In **Flow** and **Web**, hiding removes the selected node, then prunes every upstream ancestor
+  whose only remaining route to the focus passed through it.
+- Descendant nodes between the hidden node and the focus remain visible.
+- Ancestors with another valid path to the focus remain visible through that alternate path.
+- The status line reports how many nodes were hidden or isolated.
+- **Restore hidden** clears the hidden-node set and rebuilds the complete current view.
+
+This behavior lets a user cut away a noisy or irrelevant branch without losing the useful
+downstream chain that explains how the remaining nodes reach the focus.
 
 Source navigation depends on adapter evidence. Numeric anchors, line-style anchors such as `L120`,
 TOML `node-N` anchors, heading slugs, and searchable text anchors are recognized. If a custom