Doc cleanup

docs/subsystems/README.md

@@ -1,70 +1,44 @@
-# Phase 1 Subsystem Design Index
+# Subsystem Notes Index
 
-This directory contains the subsystem-specific design notes for Phase 1 of the architecture roadmap.
+The current, phase-free architecture summary is:
 
-Start here if you want the Phase 1 package to read as one coherent deliverable rather than as separate subsystem writeups.
+- [Current System Architecture](../CURRENT_SYSTEM_ARCHITECTURE.md)
 
-Parent documents:
+Start there when you want to understand how the application works now.
 
-- [Architecture Resilience Review](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/docs/ARCHITECTURE_RESILIENCE_REVIEW.md)
-- [Phase 1: Subsystem Boundaries and Target Architecture](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/docs/PHASE_1_SUBSYSTEM_BOUNDARIES_DESIGN.md)
-
-## How This Set Fits Together
-
-- [PHASE_1_SUBSYSTEM_BOUNDARIES_DESIGN.md](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/docs/PHASE_1_SUBSYSTEM_BOUNDARIES_DESIGN.md) defines the top-level subsystem split, dependency rules, state categories, and migration guardrails.
-- The notes in this directory expand each subsystem boundary without changing the parent Phase 1 design.
-- The subsystem notes are meant to be read as design companions, not as independent alternate architectures.
-
-Status note:
-
-- The Phase 1 design package is complete.
-- The runtime implementation foothold is complete: the named runtime subsystems exist in code, `RuntimeHost` is retired from the compiled runtime path, and subsystem tests cover the new seams.
-- The whole app is not fully extracted yet, so these notes still describe the architecture later phases should continue toward.
+This directory contains deeper notes for individual subsystem boundaries. These notes were originally written during the phased architecture work, so some files may still mention migration steps or target-state language. Treat them as companion notes, not as the source of truth when they disagree with the current architecture summary.
 
 ## Recommended Reading Order
 
-1. [PHASE_1_SUBSYSTEM_BOUNDARIES_DESIGN.md](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/docs/PHASE_1_SUBSYSTEM_BOUNDARIES_DESIGN.md)
-2. [RuntimeStore.md](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/docs/subsystems/RuntimeStore.md)
-3. [RuntimeCoordinator.md](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/docs/subsystems/RuntimeCoordinator.md)
-4. [RuntimeSnapshotProvider.md](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/docs/subsystems/RuntimeSnapshotProvider.md)
-5. [ControlServices.md](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/docs/subsystems/ControlServices.md)
-6. [RenderEngine.md](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/docs/subsystems/RenderEngine.md)
-7. [VideoBackend.md](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/docs/subsystems/VideoBackend.md)
-8. [HealthTelemetry.md](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/docs/subsystems/HealthTelemetry.md)
+1. [Current System Architecture](../CURRENT_SYSTEM_ARCHITECTURE.md)
+2. [RuntimeStore](RuntimeStore.md)
+3. [RuntimeCoordinator](RuntimeCoordinator.md)
+4. [RuntimeSnapshotProvider](RuntimeSnapshotProvider.md)
+5. [ControlServices](ControlServices.md)
+6. [RenderEngine](RenderEngine.md)
+7. [VideoBackend](VideoBackend.md)
+8. [HealthTelemetry](HealthTelemetry.md)
 
-That order mirrors the intended dependency story:
+That order follows the current ownership story:
 
 - durable state first
 - mutation and publication next
-- ingress and render boundaries after that
-- device timing and operational visibility last
+- control ingress after that
+- render ownership and video timing next
+- operational visibility last
 
 ## Subsystem Notes
 
-- [RuntimeStore.md](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/docs/subsystems/RuntimeStore.md)
-  Durable runtime-state facade over layer-stack, config, package-catalog, presentation, and persistence boundaries.
-- [RuntimeCoordinator.md](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/docs/subsystems/RuntimeCoordinator.md)
-  Mutation validation, state classification, reset/reload policy, and publication/persistence requests.
-- [RuntimeSnapshotProvider.md](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/docs/subsystems/RuntimeSnapshotProvider.md)
-  Render-facing snapshot publication boundary backed by explicit render snapshot building/versioning.
-- [ControlServices.md](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/docs/subsystems/ControlServices.md)
-  OSC, HTTP/WebSocket, and file-watch ingress plus normalization and service-local buffering.
-- [RenderEngine.md](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/docs/subsystems/RenderEngine.md)
-  Sole-owner render/GL boundary, render-local transient state, preview, and playout-ready frame production.
-- [VideoBackend.md](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/docs/subsystems/VideoBackend.md)
-  Device lifecycle, input/output pacing, buffer policy, and producer/consumer playout direction.
-- [HealthTelemetry.md](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/docs/subsystems/HealthTelemetry.md)
-  Logs, warnings, counters, timing traces, and subsystem health snapshots.
+- [RuntimeStore](RuntimeStore.md): durable runtime-state facade over layer-stack, config, package-catalog, presentation, and persistence boundaries.
+- [RuntimeCoordinator](RuntimeCoordinator.md): mutation validation, state classification, reset/reload policy, and publication/persistence requests.
+- [RuntimeSnapshotProvider](RuntimeSnapshotProvider.md): render-facing snapshot publication boundary backed by explicit render snapshot building/versioning.
+- [ControlServices](ControlServices.md): OSC, HTTP/WebSocket, and file-watch ingress plus normalization and service-local buffering.
+- [RenderEngine](RenderEngine.md): GL ownership boundary, render-local transient state, preview, and playout-ready frame production.
+- [VideoBackend](VideoBackend.md): device lifecycle, input/output pacing, buffer policy, and producer/consumer playout behavior.
+- [HealthTelemetry](HealthTelemetry.md): logs, warnings, counters, timing traces, and subsystem health snapshots.
 
-## What Phase 1 Should Settle
+## Historical Documents
 
-Phase 1 should leave the project with:
+The `docs/PHASE_*` files and experiment logs record how the architecture evolved. They are useful when you need rationale, investigation history, or rejected paths, but they are no longer arranged as the main feature split for the app.
 
-- one agreed subsystem vocabulary
-- one agreed dependency direction map
-- one agreed state-category model
-- one agreed current-to-target migration story
-
-Phase 1 does not need to settle every later implementation detail. The subsystem notes intentionally leave some questions open where later phases need room to choose concrete mechanics.
-
-As of the current codebase, those design questions are settled well enough for later work to build against them. Remaining implementation work should be tracked under later phases, especially eventing, render-thread ownership, persistence, backend lifecycle, live-state layering, and telemetry.
+For current implementation work, use [Current System Architecture](../CURRENT_SYSTEM_ARCHITECTURE.md) as the entry point and only dip into the phase documents when you need context for why a subsystem ended up this way.