repository-scoped dependency graph view profile persistence and interactive exploration features

docs/dependency-visualization-exploration.md

@@ -0,0 +1,86 @@
+# Dependency Visualization Exploration
+
+Repository Scoping exposes approved repository characteristics as a layered
+dependency graph for curator review. The graph is Cytoscape-compatible JSON from
+`/repos/{repository_id}/dependency-graph`; the interactive view lives at
+`/ui/repos/{repository_id}/dependency-graph`.
+
+The visualization framework decision is recorded in
+`docs/adr-dependency-graph-visualization-framework.md`.
+
+## Layers
+
+Graph nodes carry stable `layer` metadata:
+
+- `fact`: deterministic scanner output, keyed by fact kind, path, and name.
+- `evidence`: approved evidence records that interpret facts or source
+  references.
+- `feature`: concrete implemented behavior or surface area.
+- `capability`: curator-approved functional claim.
+- `ability`: higher-level ability grouping.
+- `scope`: repository-level scope summary.
+
+Evidence sits between facts and interpreted claims. Evidence should point to a
+feature when it supports a specific implementation surface, such as a test for a
+CLI command. Evidence should point directly to a capability when it supports the
+capability as a whole and no narrower feature target is known. Facts can observe
+evidence and features; evidence can support features or capabilities.
+
+## Display States
+
+Each active graph element receives a `displayState`:
+
+- `show`: visible with normal labels and styling.
+- `blur`: visible in a muted style; labels and descriptions are suppressed
+  until hover or selection.
+- `hide`: removed from the active graph payload and listed in
+  `hidden_elements`.
+
+Rule precedence is deterministic: later rules override earlier rules, then
+manual overrides win last. If a node is hidden, connected edges are hidden too.
+Manual overrides are stored by stable graph key and orphaned keys are surfaced
+when a profile references nodes or edges that no longer exist.
+
+## Filter Rules
+
+Rules are JSON objects with an `action` of `show`, `blur`, or `hide`, plus a
+`match` object. Common match fields include `kind`, `layer`, `primaryClass`,
+`attributes`, `confidence`, `freshnessState`, `ownership`, `dependencyType`,
+`strength`, `sameLayer`, `path`, and `text`.
+
+Example:
+
+```json
+{
+  "name": "Blur deterministic facts",
+  "action": "blur",
+  "match": {"layer": "fact"}
+}
+```
+
+## View Profiles
+
+View profiles are repository-scoped saved graph perspectives. The profile API
+supports create, list, load, update, duplicate, and delete operations under
+`/repos/{repository_id}/dependency-graph/profiles`.
+
+Profiles store:
+
+- name and optional description
+- default graph mode
+- filter rules
+- manual visibility overrides
+- timestamps
+
+Example profiles:
+
+- Scope Impact: default impact mode; show stale or changed nodes and blur
+  current context.
+- Hide Tooling Noise: hide facts with dependency or tooling attributes.
+- Evidence Audit: show evidence and facts; blur abilities and scope.
+- Same-Layer Normalization Review: show same-layer edges and blur ordinary
+  upward dependency arrows.
+
+Hiding evidence can make a graph appear cleaner while also removing the reason a
+capability is trusted. Prefer blurring evidence when reviewing scope impact so
+the support chain remains visible as context.