docs: finish zone entity workplan

docs/ZoneEntityVisualization.md

@@ -169,6 +169,40 @@ introduce a two-phase layout:
 This will likely require an internal view model that separates fabric graph data
 from rendered graph coordinates.
 
+### Per-Zone Layout Preparation
+
+The current graph explorer should not immediately run independent Cytoscape
+layouts inside each zone rectangle. Cytoscape layouts operate on collections in
+one coordinate space, while the current zone overlay is a view layer drawn over
+the already-laid-out graph. Running nested layouts directly against visible
+nodes would make pan/zoom, filters, collapse state, and edge routing fragile.
+
+The safer path is a two-phase view layout:
+
+1. Resolve zones from the current graph and view filters.
+2. Place zone containers and unzoned nodes in the global canvas.
+3. For each zone, compute local coordinates for its assigned nodes using the
+   zone's configured layout algorithm.
+4. Project local zone coordinates into global graph coordinates.
+5. Route internal edges inside the zone and boundary edges through the zone
+   perimeter or collapsed zone node.
+
+The implementation needs these pieces before per-zone layouts become safe:
+
+- a resolved zone view model that survives filtering and saved profiles;
+- a stable assignment invariant so a visible node belongs to no more than one
+  zone;
+- a zone container model with size, position, padding, and height;
+- a local coordinate projection layer from zone space to Cytoscape space;
+- explicit boundary-edge routing rules;
+- collapse state that can replace a zone subgraph with a representative node;
+- diagnostics when a configured zone layout cannot be applied.
+
+The present implementation already establishes the first, second, and sixth
+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.
+
 ## Layer Height And Overlap
 
 Zone presentation includes a height. Height is a visual stacking concept, not a

workplans/RAIL-FAB-WP-0022-zone-entity-visualization-engine.md

@@ -4,7 +4,7 @@ type: workplan
 title: "Promote graph zones to first-class visualization entities"
 domain: railiance
 repo: railiance-fabric
-status: active
+status: finished
 owner: codex
 topic_slug: railiance-fabric
 created: "2026-05-24"
@@ -214,7 +214,7 @@ and restores the original graph view without changing the underlying payload.
 
 ```task
 id: RAIL-FAB-WP-0022-T07
-status: todo
+status: done
 priority: low
 state_hub_task_id: "4b6f0b7e-a066-490d-8160-ba23b03cf820"
 ```
@@ -229,6 +229,12 @@ a follow-up workplan for two-phase layout.
 Expected result: the codebase has a documented path toward per-zone layouts
 without destabilizing the current graph explorer.
 
+Result: Documented the per-zone layout preparation path in
+`docs/ZoneEntityVisualization.md`. The recommended direction is a two-phase
+layout: resolve zones and containers first, then compute local zone coordinates
+and project them into Cytoscape space. The note identifies the prerequisites
+already established by WP-0022 and avoids a premature nested-layout rewrite.
+
 ## Acceptance Criteria
 
 - Zone entity behavior is documented in `docs/ZoneEntityVisualization.md`.