SCENEGOD/CLAUDE.md

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.