# SCENEGOD — machinima director's sandbox (iClone/SFM UX, GODVERSE stack)

Drop characters + animation clips + image backdrops on a 3D stage, keyframe
transforms/cameras/lights on a timeline, render mp4. Web app: FastAPI +
three.js, same conventions as MESHGOD (`~/Documents/MESHGOD`).

## You are one of THREE parallel lane agents
1. **Read, in order:** this file → `PLAN.md` → your lane file in `lanes/` →
   your log in `logs/`. Your lane file is your source of truth — the
   orchestrator (Fable) updates it between your sessions. Re-read it at the
   start of EVERY session; instructions may have changed since your last one.
2. **Only touch files your lane owns** (ownership map in PLAN.md §3). If you
   need a change in another lane's file, write the request in your log under
   BLOCKED/REQUESTS — do not edit it yourself.
3. **Log protocol** — append (never rewrite) to `logs/lane<X>.md` at the end
   of every session, and mid-session when you make a design decision:

   ```
   ## 2026-07-18 session N
   DONE: what shipped, with file:line pointers
   DECISIONS: choices made + why (schema tweaks, deps, algorithms)
   BLOCKED/REQUESTS: what you need from another lane or the orchestrator
   NEXT: what you'd do next session
   ```
4. **Commit early, commit often**, on `main`, prefixed `[laneA]`/`[laneB]`/
   `[laneC]`. `git pull --rebase` before every commit — other lanes commit to
   the same branch. File ownership makes conflicts near-zero; if you hit one
   anyway, resolve only your own files and log it. **Stage your own files
   explicitly (`git add <paths>`) — never `git add -A`/`.`**: another lane's
   uncommitted work may be sitting in the shared working dir, and -A sweeps
   it into your commit (happened once; attribution mess).
5. **Don't exceed your lane's current milestone.** Milestones and sync points
   are in PLAN.md §5. Finishing early = polish + tests + log, not starting
   the next milestone uninvited.

## Stack rules
- Python 3.11 stdlib + `fastapi` + `uvicorn` only (requirements.txt). No
  other server deps without logging a REQUEST first.
- Frontend: vanilla ES modules + three.js via importmap (copy the pattern
  from `/Users/johnking/Documents/MESHGOD/meshgod/web/rigroom.html`). No
  bundler, no npm, no framework.
- Server: `uvicorn scenegod.server:app --port 8020`, binds 127.0.0.1 by
  default (local tool on ultra; VPS deploy is a later problem).
- Secrets/env in `.env` (gitignored). Never commit tokens.
- Reference code you may READ (never edit): the MESHGOD repo, especially
  `meshgod/web/rigroom.html` (retarget bake), `meshgod/library.py` (folder
  scanning), `meshgod/ops.py` (MODELBEAST submit contract),
  `scripts/glb2fbx.py` (headless Blender pattern).

## Gotchas inherited from MESHGOD (learned the hard way — do not relearn)
- trimesh/some GLBs omit `metallicFactor` → glTF default 1.0 → renders black.
  Viewer must use an IBL environment (`RoomEnvironment` + PMREM), not just
  lights.
- Serve HTML **no-cache** — a stale cache once hid UI buttons for a day.
- Mixamo rig quirks (all already solved in rigroom's `bakeRetarget` — port,
  don't reinvent): namespaces differ per download (`mixamorig4Hips`), FBX
  files carry duplicate hierarchies, quaternion sign continuity must be
  enforced, Blender-exported GLB rest poses differ from FBX rests → retarget
  = world-space rotation-delta bake at 30fps, never raw track copy.
- Rigged GLBs must NEVER be sent through any Blender join/decimate "finish"
  path — it spawns phantom joint meshes and mauls the armature.
- Path traversal: every endpoint that takes a path must resolve + verify it
  stays inside its root (ship-check rule).
- Verbose commands (installs, test runs, ffmpeg): pipe through `| lm -l 2`.