Update documentation for AGENTS.md, CHAT_CONTEXT.md, architecture.md, and testing.md with new time-related features and direction.

AGENTS.md

@@ -84,6 +84,24 @@ This is not:
 - Global ambient/sun/background/fog belong in `world` settings.
 - Local authored lights belong in typed entity schemas.
 
+### Project time and living-world direction
+
+- Project time is a global project-level system, not a separate main clock per scene.
+- Scene world settings may opt in/out of time-driven lighting, but scenes should not own independent core time progression.
+- Near-term time slices should prioritize authored day/night control:
+  - sunrise/sunset
+  - day phases
+  - night/dawn/dusk appearance
+  - scene-level lighting opt-in/out
+- Do not build a large generic schedule editor before the runtime hooks it would drive are real.
+- Long-term world logic should resolve deterministically from:
+  - global time
+  - persistent/cycle flags
+  - scene/location context
+- Prefer deterministic resolution over fully simulating unloaded scenes.
+- NPC presence, routines, dialogue variants, interaction availability, and path progress should eventually be reconstructible from authored rules plus global state.
+- If loop/reset mechanics are added later, they should reset/re-resolve cycle-scoped state rather than trying to rewind arbitrary runtime simulation.
+
 ### Imported model collision
 
 - Collision authoring for imported models belongs on `modelInstances`, not assets.

CHAT_CONTEXT.md

@@ -29,6 +29,8 @@ Broadly implemented already:
 - multi-viewport editor foundations
 - unified creation/placement foundations
 - transform foundations
+- project-wide time foundation with a running global clock
+- first day/night lighting override tied to project time
 
 Important consequence:
 
@@ -74,6 +76,8 @@ Treat current box-brush structures as the starting point for whitebox solids unl
 - world settings own global background / ambient / sun / fog
 - local authored lights stay in typed entities
 - project save/load and runner export are separate concerns
+- project time is global, not per scene
+- current day/night logic exists, but it is still a small dedicated driver rather than a generic schedule system
 
 Imported model collision:
 
@@ -133,6 +137,8 @@ The next large topics are more likely to be things like:
 - whitebox-solid editing model
 - multi-scene / project structure
 - richer runtime systems
+- authored day/night refinement on top of project-global time
+- later deterministic schedule/routine/event systems driven by global time + flags + scene context
 - remaining packaging / portability work
 - future primitives and topology tools after the whitebox direction is coherent
 

architecture.md

@@ -409,6 +409,23 @@ Imported model collision settings should be represented canonically on the relev
 
 `ProjectTimeSettings` is the correct home for project-wide clock and day/night settings that persist across scene transitions.
 
+Time architecture direction:
+
+- the project clock is global and should survive scene transitions inside a run session
+- scenes may opt in/out of time-driven lighting, but should not own separate main clock progression
+- authored day/night semantics such as sunrise, sunset, and day phases belong in project-level time settings or a tightly related typed structure
+- runtime should derive visible day/night state from:
+  - project time
+  - authored day/night settings
+  - scene world settings
+- do not hide time semantics only inside renderer-side constants; keep reusable pure resolution logic where practical
+- generic schedules, NPC routines, dialogue variants, and interaction availability should eventually resolve from:
+  - global time
+  - world/quest flags
+  - scene/location context
+- unloaded scenes should be reconstructible from those rules rather than fully simulated in the background
+- future loop/reset mechanics should clear or reinitialize cycle-scoped state, then re-resolve current world state deterministically
+
 Do not model global world lighting as ad hoc hidden viewport state.
 
 ---

roadmap.md

@@ -621,11 +621,25 @@ These items are also likely candidates for sub-slices if needed.
 
 Expand capability without compromising the core.
 
+### Directional note
+
+The time/living-world direction should stay closer to Majora's Mask than to a fully simulated always-loaded sandbox:
+
+- one global project clock
+- deterministic resolution from time + flags + scene context
+- unloaded scenes reconstructed on demand instead of fully simulated all the time
+- authored day/night comes before a large generic scheduling UI
+
 ### Candidate slices
 
+- authored day/night refinement on top of project-global time
+- small reusable time-query/day-phase foundation
+- typed NPC/runtime actor foundation
+- spline/path authoring for camera/object/NPC motion
+- deterministic schedules/routines driven by time windows and flags
+- cycle/reset mechanics if loop gameplay becomes a core pillar
 - advanced UV tools
 - nav waypoints authoring
-- camera zones / guided tours
 - ambient zones and audio buses
 - lightweight scripting
 - plugin/tool API

testing.md

@@ -47,6 +47,8 @@ Highest-priority confidence areas:
 9. runner navigation/input reliability
 10. spatial audio and interaction basics
 11. critical regressions caught in CI
+12. project-time/day-phase determinism where time-driven runtime systems exist
+13. later schedule/routine resolution from time + flags + scene context
 
 ---
 
@@ -474,6 +476,8 @@ The following invariants are important enough to deserve repeated coverage:
 - missing optional systems fail gracefully
 - navigation controller activation is exclusive and consistent
 - interactions target the correct entities or model instances
+- project-global time survives scene transitions where intended
+- time-driven scene state resolves deterministically from canonical/authored inputs
 
 ---