feat: stabilize graph zone containers

docs/ZoneEntityVisualization.md

@@ -203,6 +203,31 @@ pieces. A follow-up should introduce a zone container placement phase before
 attempting per-zone node layout. That follow-up can keep Cytoscape as the final
 renderer while moving layout decisions into a Fabric-owned view model.
 
+### Stable Zone Containers
+
+The first container implementation keeps zone surfaces as view state keyed by
+stable zone id. When a zone first appears, the global graph layout supplies its
+initial center. Once created, the container owns the zone surface position while
+the global layout continues to arrange the base canvas and unzoned nodes.
+
+Dragging a zone moves the container and its currently assigned visible member
+nodes together. Rerunning layout or switching the layout algorithm should keep
+the container in its stored graph coordinates and then project the zone's
+visible subgraph back into that container.
+
+Container state belongs in saved or copied graph view state, not in the Fabric
+payload. It is an operator workspace preference, similar to manual visibility
+overrides.
+
+### Context Edges
+
+Display-only context edges are not zone connectivity. Repository `declares`
+edges, for example, show which repository declared a node, but they should not
+create boundary diagnostics, attraction paths, or collapsed-zone boundary
+edges. A host can still show them as explanatory evidence in details, but a
+zone boundary should only react to canonical or host-promoted graph
+relationships.
+
 ## Layer Height And Overlap
 
 Zone presentation includes a height. Height is a visual stacking concept, not a

docs/graph-explorer-contract.md

@@ -192,13 +192,27 @@ initial diagnostic set includes empty zone seed sets, visible nodes matched by
 multiple zone definitions, and edges crossing zone boundaries. Attraction
 diagnostics such as multiple attraction candidates or depth-limit stops belong
 to the same resolver diagnostic channel when attraction rules are enabled.
+Display-only context edges, such as repository `declares` edges, are evidence
+for where declarations came from. They must not count as zone boundary
+connectivity, attraction paths, or collapsed-zone boundary edges unless a host
+explicitly promotes them to canonical graph relationships.
 
 Saved graph profiles should persist zone view state as an explicit nested
 `zone` object. The initial fields are `visible`, `grouping`, `definitionSet`,
-and `presentation`. URL parameters may continue to expose compatibility aliases
-such as `zoneBoundaries`, `zoneGrouping`, and `zoneDefinitionSet`, but saved
-profiles should prefer the nested object so future zone definition sets and
-presentation preferences can be restored without another state migration.
+`presentation`, and `containers`. URL parameters may continue to expose
+compatibility aliases such as `zoneBoundaries`, `zoneGrouping`, and
+`zoneDefinitionSet`, but saved profiles should prefer the nested object so
+future zone definition sets, presentation preferences, and operator-placed zone
+surfaces can be restored without another state migration.
+
+Zone containers are view state, not fabric data. A container stores a stable
+zone surface position and size in graph coordinates. Global graph layout may
+place unzoned nodes and provide an initial center for new zones, but existing
+zone containers should keep their operator-chosen positions when the layout
+algorithm changes. After the global layout pass, each zone may project its
+assigned visible nodes into local coordinates inside its container. The first
+local layout may be a deterministic compact layout; later engines can replace
+that with per-zone Cytoscape or engine-owned algorithms.
 
 Zone collapse is a view-only operation. A collapsed zone should hide its visible
 member nodes, replace them with a synthetic zone node, and draw synthetic