Add semantic flow and convergence web views

docs/CONTRACT.md

@@ -1,4 +1,4 @@
-# DocForge 0.13 contract
+# DocForge 0.14 contract
 
 ## Authority boundary
 
@@ -19,7 +19,7 @@ commit when Git is available; it cannot change repository state.
 - 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.13.1.
+- Core, CLI, and MCP server: version 0.14.0.
 
 Schema files describe the generic interchange contract. Runtime validation remains responsible for
 path confinement, source hashing, relationship resolution, dependency cycles, project limits, stale
@@ -99,12 +99,13 @@ random token is part of every accepted URL path. Only `GET` and `HEAD` are suppo
 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 descriptor-category filtering, exact node content, bounded
-incoming-and-outgoing neighborhoods, and one node's bounded project-confined source file.
+incoming-and-outgoing neighborhoods, semantic Flow ancestry, convergence Web context, and one
+node's bounded project-confined source file.
 Descriptor filtering accepts only
 family, authority, status, or tag plus one exact value. There is no write endpoint, arbitrary query
 endpoint, static filesystem handler, external asset, or project-selection control.
 
-The `graph-browser@12` template provides mouse-wheel zoom centered on the pointer, left-button drag
+The `graph-browser@14` 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
@@ -122,31 +123,35 @@ Right-clicking or pressing Shift+Enter opens the complete inspector. Inspection
 the current neighborhood or reset the viewport. Both dialogs support Escape, explicit close
 controls, and backdrop dismissal. Loading the inspected node as the new root requires the separate
 Explore neighborhood action. Non-focus nodes may be hidden from the presentation and restored
-without mutating graph state. Source actions open the project-confined source and navigate to
+without mutating graph state. Flow and Web recompute focus reachability after each hide so
+disconnected upstream-only branches are pruned while downstream convergence remains visible.
+Source actions open the project-confined source and navigate to
 supported line, TOML, heading, or text anchors. Both side panels support pointer and keyboard
 resizing. The unblurred full inspector supports native resizing, constrained title-bar dragging,
 and a fixed header/footer surrounding a scrollable body.
 
-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 header exposes a Nodes/Flow/Web segmented selector. Nodes displays the complete bounded
+neighborhood. Flow displays semantic ancestry ending at the current root. Structural and execution
+edges retain their declared source-to-target direction. Reads, imports, dependencies, inheritance,
+and `tested_by` reverse because their declared target feeds or qualifies the source. Documentation
+and context relations remain available in Nodes and Web but are excluded from Flow. Web follows
+all relationship types as bounded semantic contributors into the current root. It also reverses
+direct root-owned members and execution dependencies into adjacent contributor branches. Traversal
+does not fan back out through unrelated siblings. These are presentation transforms over the
+validated snapshot; they do not add or change project relationships.
 
-Both views color edges by relationship semantics and retain direction with visible SVG endpoint
+All three 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.
+project-defined relations. Nodes, Flow, and Web 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.
+upstream nodes. In Web, all retained contributors share the convergence role. These roles receive
+distinct palettes and navigation sections. An undirected shortest-hop calculation places Nodes on
+distance rings; Flow and Web use left-to-right distance layers with the destination on the right.
+Each role palette darkens progressively by distance, capped at fifty percent.
 
 Each invocation creates or reuses one worker through the separately supervised, per-user viewer
 manager. The manager is outside the short-lived MCP transport and owns all child workers as one OS

docs/MCP_CONTRACT.md

@@ -82,14 +82,14 @@ only through the explicit local CLI integration command.
 
 ## Visualization boundary
 
-`docforge_visualize` starts the fixed built-in `graph-browser@12` template against the currently
+`docforge_visualize` starts the fixed built-in `graph-browser@14` 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, exact family/authority/status/tag filtering, node-neighborhood JSON, and a bounded
-project-confined source read for one indexed node. The browser
+search, exact family/authority/status/tag filtering, node-neighborhood JSON, semantic Flow,
+convergence Web, and a bounded project-confined source read for one indexed node. The browser
 exposes an exact validated index snapshot. It rejects index
 replacement or alteration and requires another MCP invocation to refresh.
 Viewport interaction is entirely client-side: fitted neighborhood framing, wheel zoom, left-button
@@ -98,14 +98,17 @@ project data. Left activation visibly selects the node and opens a compact descr
 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. Users may hide
-non-focus nodes and restore them entirely client-side. Source actions open the indexed source path
+non-focus nodes and restore them entirely client-side. Flow and Web prune upstream-only branches
+disconnected by a hidden node while retaining descendants that still lead to the focus. Source
+actions open the indexed source path
 and navigate to recognized anchors. 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 browser runs in a project-bound worker owned by
+incoming or lateral context. Flow presents semantic ancestry with relation-aware direction.
+Web follows bounded structural, dependency, execution, evidence, and contextual contributors into
+the focus. Direct focus-owned members and execution dependencies become adjacent contributor
+branches without expanding unrelated siblings. The relationship key is regenerated from each
+visible view. The browser runs in a project-bound worker owned by
 the separately supervised per-user viewer manager. Standard-input transaction completion and MCP
 host exit do not close the listener. Repeated visualization requests reuse the current worker while
 its exact snapshot remains valid. `docforge_visualization_status` reports lifecycle state, and

docs/USER_MANUAL.md

@@ -14,8 +14,9 @@ viewer processes are derived and can be rebuilt.
 - Isolated, optimistic changesets with create, update, move, delete, validation, diffs, and previews.
 - Hash-bound canonical application through both CLI and an explicitly enabled MCP tool.
 - Declared HTML render views. Arbitrary templates, render commands, and output paths are rejected.
-- A loopback-only graph browser with Nodes and Flow views, relationship keys, source inspection,
-  node hiding, panel resizing, zooming, and managed idle shutdown.
+- A loopback-only graph browser with Nodes, semantic Flow, and convergence Web views,
+  relationship keys, source inspection, branch-aware node hiding, panel resizing, zooming, and
+  managed idle shutdown.
 - A generic Markdown/TOML adapter plus contracts for deterministic project-owned adapters.
 
 DocForge does not run shell commands from documentation, mutate Git, build an application, deploy,
@@ -219,12 +220,21 @@ URL. Use `visualization-status` and `visualization-stop` to inspect or stop the
 - 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 bounded directed ancestry.
+- 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.
+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.
 
 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
@@ -461,8 +471,8 @@ ambiguous adapter evidence.
 
 ### Full inspector content does not fit
 
-DocForge 0.13 uses a fixed header and footer with a scrollable inspector body. If an older page is
-still open, stop and reopen the visualization so it loads the current `graph-browser@12` template.
+DocForge 0.14 uses a fixed header and footer with a scrollable inspector body. If an older page is
+still open, stop and reopen the visualization so it loads the current `graph-browser@14` template.
 
 ### Render output is stale