fix: archi

docs/technical/target-architecture.md

@@ -2,60 +2,69 @@
 
 This document describes the intended medium-term architecture for the project.
 
+## Relationship To The Current Code
+
+- `docs/technical/architecture.md` is the source of truth for what exists now.
+- This document is intentionally aspirational.
+- If this document conflicts with the current implementation, the current implementation wins.
+
 ## Goals
 
-- Keep `main` stable, `develop` as the integration branch, and `feat/*` for feature work.
-- Keep the runtime split between scene composition, gameplay systems, debug tooling, and HTML UI.
+- Keep `App.tsx` small and orchestration-oriented.
+- Separate production world code from debug-only runtime paths.
 - Keep one clear source of truth per concern.
+- Grow gameplay systems incrementally instead of prebuilding empty architecture.
 
 ## Intended Layers
 
 ### App Layer
 
-- `App.tsx` should stay small and orchestration-oriented.
-- It should mount the canvas scene and top-level HTML overlays.
+- `App.tsx` mounts the canvas scene and top-level HTML overlays.
+- It should stay thin and avoid gameplay logic.
 
 ### World Layer
 
-- `src/world/` should contain only production scene objects and scene composition.
+- `src/world/` should contain production scene composition and production scene objects.
 - Expected responsibilities:
   - world composition
-  - map/environment/lighting
+  - map, environment, lighting
   - player controller
-  - zones
-  - post-processing used in production
+  - production interaction anchors
+  - production post-processing, if needed
 
 ### Debug Layer
 
-- `src/utils/debug/` should contain only developer tooling.
+- Debug-only scenes and tooling should be isolated from the production world path.
 - Expected responsibilities:
   - `lil-gui`
   - performance overlay
   - scene helpers
   - free camera and calibration controls
+  - temporary test scenes used during development
 
 ### UI Layer
 
-- `src/components/ui/` should contain HTML overlays used by the player.
-- Expected examples:
+- `src/components/ui/` should contain player-facing HTML overlays.
+- Expected future examples:
   - crosshair
-  - loading screen
+  - loading flow
   - mission HUD
   - narrative overlays
 
 ### Gameplay Layer
 
-- Gameplay state should eventually live in dedicated managers and thin hooks once those systems exist.
-- Expected future concerns:
+- As the project grows, gameplay state can move toward a clearer orchestration layer.
+- Likely future concerns:
   - missions
   - zones
   - cinematics
+  - dialogue
   - audio
   - interactions
 
 ## Rules
 
-- `world/` should not contain debug-only tooling.
-- `debug/` should not own production gameplay systems.
-- Shared types should live close to their domain and move outward only when they gain multiple real consumers.
-- New files should only be created when they have an active runtime purpose.
+- Prefer direct, working code over speculative scaffolding.
+- Shared types should stay close to their domain until they have multiple real consumers.
+- Avoid creating new managers or service layers without an active runtime need.
+- Debug-only runtime paths should be clearly marked and easy to remove later.