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).

Deploy model (digalot.fyi suite)

• Prod: dealgod VPS root@100.94.195.115, /opt/scenegod — NOT a git checkout: ./deploy/deploy.sh rsyncs from a dev Mac and rebuilds (deploy/docker-compose.yml, project name scenegod — do NOT drop the name: key; meshgod+scenegod both compose from dirs called "deploy" and would otherwise share a project and orphan each other). Container joins the external dealgod_default net; data volumes under /opt/scenegod-data/.
• nginx: deploy/nginx-scenegod.conf block lives in the digalot.fyi server in /opt/dealgod/nginx/dealgod-servers.conf (dealgod-nginx container) — suite basic-auth (meshgod.htpasswd). Live: digalot.fyi/scenegod/.
• Frontend is PREFIX-AGNOSTIC: all web URLs are relative (module imports ./web/..., fetches assets/...) so the app works at / locally AND under /scenegod/. Never reintroduce a leading / in a web-side URL.
• VPS env keeps SCENEGOD_LLM_URL/SCENEGOD_MB UNSET (features 503/hide; they shell to tailnet boxes — ultra-only). rhubarb not in the image.
• Server has ship-check hardening: capped_body on every POST (frames 25MB, scenes 5MB), render dims ≤4096/fps ≤60/frame index ≤20000, esc() on all dock innerHTML interpolations. Keep new endpoints behind the same rules.

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.