From cd71037a7a1cd2a2fec67409c7251044da9ec014 Mon Sep 17 00:00:00 2001
From: Victor Giers <mail@victorgiers.com>
Date: Tue, 31 Mar 2026 01:16:50 +0200
Subject: [PATCH] Add CHAT_CONTEXT.md for lightweight startup context

---
 CHAT_CONTEXT.md | 180 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 180 insertions(+)
 create mode 100644 CHAT_CONTEXT.md

diff --git a/CHAT_CONTEXT.md b/CHAT_CONTEXT.md
new file mode 100644
index 00000000..69785696
--- /dev/null
+++ b/CHAT_CONTEXT.md
@@ -0,0 +1,180 @@
+# CHAT_CONTEXT.md
+
+This file is the lightweight startup context for new Codex chats.
+
+Read this after `AGENTS.md`.
+Then inspect only the relevant sections of `architecture.md`, `roadmap.md`, and `testing.md` for the active slice.
+
+This file does not replace the full docs.
+It exists to keep new chats focused and to reduce repeated context load.
+
+---
+
+## Product summary
+
+This repo is a browser-based 3D scene authoring tool with a built-in runner.
+
+Core loop:
+
+1. author a scene
+2. save/load it reliably
+3. run it in-browser immediately
+
+The product prioritizes:
+
+- brush-first spatial authoring
+- imported assets as first-class additions
+- typed entities and simple interactions
+- browser-native delivery
+
+It is not:
+
+- a full game engine
+- a Blender replacement
+- a general CAD tool
+- an R3F showcase
+
+---
+
+## Hard architectural rules
+
+- The canonical `SceneDocument` is the source of truth.
+- The document must stay independent from three.js objects.
+- Editor-authored mutations should flow through commands.
+- The editor viewport is derived from the document.
+- The runner is a sibling system, not an editor hack.
+- Canonical save format is project JSON, not glTF/GLB.
+- Export/package output is downstream from the document/runtime build.
+- Model instances are separate from typed entities.
+
+---
+
+## Early binding decisions
+
+These are fixed for the early milestones unless a later slice explicitly changes them.
+
+### Coordinates and units
+
+- world is right-handed and **Y-up**
+- `+X` is right
+- `+Y` is up
+- units are meter-like
+
+### Repo shape
+
+- keep the repo as a single Vite app
+- keep domain folders under `src/`
+- do not split into a monorepo early
+
+### State ownership
+
+- do not use the React tree as the canonical state container
+- keep canonical state in a thin external editor store/service
+
+### Persistence
+
+- version the document from day one
+- keep migrations explicit
+- early project persistence can be local draft storage plus JSON import/export
+- binary assets must survive reload via embedded or project-scoped persistent storage
+- never rely on Blob URLs as the only persisted asset reference
+
+### Early box brushes
+
+- first brush kind is an axis-aligned box
+- arbitrary brush rotation is deferred
+- stable box face IDs are:
+  - `posX`
+  - `negX`
+  - `posY`
+  - `negY`
+  - `posZ`
+  - `negZ`
+- `posY` is top and `negY` is bottom
+
+### Early UV data
+
+Per face, keep explicit UV transform values such as:
+
+- `offset`
+- `scale`
+- `rotationQuarterTurns`
+- `flipU`
+- `flipV`
+
+“Fit to face” should rewrite explicit values, not add a magical persistent flag.
+
+### Model placement
+
+- imported assets live in the asset registry
+- placed imported models live in `modelInstances`
+- typed scene objects like `PlayerStart`, `TriggerVolume`, or lights live in `entities`
+
+### Interaction scope
+
+- keep `Trigger -> Action -> Target` typed and explicit
+- do not add actions for systems that do not exist yet
+
+### World environment vs local lights
+
+- global background / ambient / sun / fog belong in `world` settings
+- local authored lights belong in typed entity schemas
+- true skyboxes or environment textures belong after persistent asset storage exists
+
+---
+
+## What a good slice looks like
+
+Each slice should land the smallest coherent end-to-end version of the feature across the layers it touches:
+
+- document data
+- commands
+- viewport behavior
+- runner behavior if relevant
+- persistence
+- UI
+- tests
+
+Do not land speculative scaffolding with no immediate slice use.
+
+If a roadmap item is too large, split it into smaller vertical slices.
+
+---
+
+## Required habits for implementation
+
+- Inspect the current repo first.
+- Extend the current implementation instead of restarting architecture.
+- If persisted schema changes, update versioning/migrations and add a compatibility test.
+- Run the narrowest relevant checks you can.
+- Report what was actually verified.
+
+---
+
+## Early slice ordering to keep in mind
+
+- M0: foundation, document, commands, persistence, test setup
+- M1: axis-aligned box brushes, face materials/UVs, runner, first-room polish, world lighting basics
+- M2: typed entities, simple trigger/action/target interactions, click interactions
+- M3: GLB/GLTF import, local lights + skyboxes, animation, spatial audio
+
+That ordering matters because:
+
+- world settings do not need entity or asset pipelines
+- local lights need the entity system
+- skyboxes need persistent asset storage
+- animation and audio actions should land only with those runtime systems
+
+---
+
+## When to open the full docs
+
+Open the relevant full sections when:
+
+- persistence schema changes
+- runtime/editor boundaries are being touched
+- a slice adds new tests or new failure modes
+- geometry semantics are non-trivial
+- import/export behavior changes
+
+Otherwise, stay focused on the active slice and keep the implementation small.