Propose interactive Fabric map workplan

workplans/RAIL-FAB-WP-0008-interactive-fabric-map.md

@@ -0,0 +1,159 @@
+---
+id: RAIL-FAB-WP-0008
+type: workplan
+title: "Interactive Fabric Map"
+domain: railiance
+repo: railiance-fabric
+status: proposed
+owner: codex
+topic_slug: railiance
+planning_priority: high
+planning_order: 8
+state_hub_workstream_id: "0018ee65-dd90-4162-8837-c72d71f0dc9e"
+created: "2026-05-18"
+updated: "2026-05-18"
+---
+
+# RAIL-FAB-WP-0008 - Interactive Fabric Map
+
+## Goal
+
+Build a clever interactive auto-layouting map over the registered Fabric
+entities so humans and agents can orient inside the infrastructure graph.
+
+The current repo has static graph exports through JSON and Mermaid. That is
+useful for snapshots and docs, but it does not yet provide a navigable
+orientation surface for the registered ecosystem.
+
+## Design Direction
+
+The first map should be an operational tool, not a landing page. It should open
+directly into the graph and make the current infrastructure legible through
+stable grouping, filtering, and drill-down.
+
+The map should support:
+
+- force or layered auto-layout with stable seeded positions
+- grouping by domain, repo, service, capability, interface, dependency, and
+  unresolved status
+- search across repo slugs, graph ids, names, capabilities, interfaces, and
+  library names
+- quick filters for active services, external interfaces, missing declarations,
+  unresolved dependencies, blast radius, and dependency path
+- hover and selection detail panels with links back to registry endpoints,
+  State Hub repo ids, workplans, and source files where available
+- shareable map state through URL query parameters or a copied state blob
+- graceful handling of registered-only repos that do not yet have local
+  `fabric/` declarations
+
+## Architecture Notes
+
+Keep the registry as the data source. The UI should consume registry exports and
+queries rather than reloading repo files directly.
+
+Likely implementation path:
+
+- add a map-oriented projection endpoint or CLI export that preserves existing
+  graph ids while adding visual facets
+- serve a small local web UI from the registry service or a separate lightweight
+  static bundle
+- use a proven browser graph/layout library instead of hand-rolling physics
+- keep layout state client-side first; persist only after the workflows prove
+  useful
+
+## Tasks
+
+### T01 - Map UX And Information Architecture
+
+```task
+id: RAIL-FAB-WP-0008-T01
+status: todo
+priority: high
+state_hub_task_id: "9844a9a7-f285-4523-a8d6-4ca62008ce08"
+```
+
+Define map views, entity visual grammar, navigation behaviors, and orientation
+affordances.
+
+Acceptance notes:
+
+- Decide initial visual grammar for repos, services, capabilities, interfaces,
+  dependencies, bindings, libraries, and registered-only repos.
+- Decide default grouping and default filters for first load.
+- Decide whether the first implementation uses a force-directed, layered, or
+  hybrid layout.
+
+### T02 - Layout-Ready Graph Projection
+
+```task
+id: RAIL-FAB-WP-0008-T02
+status: todo
+priority: high
+state_hub_task_id: "cb0cc9f1-5225-47e5-8b47-a945c92e7168"
+```
+
+Add or shape registry exports for map-friendly nodes, edges, groups, facets, and
+stable identifiers.
+
+Acceptance notes:
+
+- Include registered repositories even when they have no graph snapshot yet.
+- Include node type, domain, repo, lifecycle, unresolved flags, and edge type.
+- Preserve stable ids so layout state and deep links do not churn.
+
+### T03 - Interactive Auto-Layout Map UI
+
+```task
+id: RAIL-FAB-WP-0008-T03
+status: todo
+priority: high
+state_hub_task_id: "ecd967fc-05ed-4cda-bca2-cf74e26e60b3"
+```
+
+Build a local interactive map with layout controls, filtering, search, zoom,
+pan, and detail panels.
+
+Acceptance notes:
+
+- The first screen is the actual map.
+- Users can search, select, expand/collapse groups, and inspect details without
+  leaving the page.
+- The map remains useful with the current sparse state where many repos are
+  registered-only.
+
+### T04 - Operational Orientation Workflows
+
+```task
+id: RAIL-FAB-WP-0008-T04
+status: todo
+priority: medium
+state_hub_task_id: "75c1f234-026c-44ed-9c88-db39653b81e0"
+```
+
+Add workflows for blast-radius exploration, dependency paths, unresolved gaps,
+repo grouping, and current selection sharing.
+
+Acceptance notes:
+
+- Selecting an interface can show consumers and blast radius.
+- Selecting a service can show its dependency path and provider chain.
+- Registered-only repos are visible as onboarding gaps rather than noise.
+
+### T05 - Verification And Documentation
+
+```task
+id: RAIL-FAB-WP-0008-T05
+status: todo
+priority: medium
+state_hub_task_id: "64fe53f1-fbea-4624-8f52-1b5e2a27cf67"
+```
+
+Verify the map against seeded registry data, document usage, and capture
+follow-on data quality gaps.
+
+Acceptance notes:
+
+- Verify against the local registry after `registry/local-repos.yaml` onboarding.
+- Include at least one automated projection/API test and one UI smoke test.
+- Document how to launch the map and how to refresh the underlying registry
+  data.