create-aura3d 3.0.0 → 4.0.0

package/skills/aura3d-animation-studio/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: aura3d-animation-studio
+description: Directs an Animation Studio episode end to end: previs, prompt-to-EpisodeDocument, cast and set binding, blocking, camera, timed dialogue, validation, and a silent render handed to AuraVoice. Use when working in the `animation-studio` template, running `aura3d animation scene <verb>` or `pnpm scene`, editing `dist/scene/working.document.json`, or producing, rendering, or publishing an animated episode.
+---
+
+# Aura3D Animation Studio (director loop)
+
+You are the director. There is no separate model or API key: every Scene-Tool
+verb edits one `EpisodeDocument` at `dist/scene/working.document.json` through
+validated scene tools and is rejected if it would break the scene. Shared rules
+(claim labels, forbidden patterns, typed assets, benchmark mode) are in
+[../aura3d-core/references/boundaries.md](../aura3d-core/references/boundaries.md).
+
+## Look target
+
+An episode holds one look across shots: pick the look preset (usually
+`golden-hour` or `night-city` for drama) before storyboard, keep the grade and
+fog consistent between cuts, and light each shot's key to the same direction
+so intercut frames share a single palette and mood.
+
+## Establish the contract
+
+1. Run `npx @aura3d/cli@latest --help` and confirm the `animation scene` line.
+   `aura3d animation scene <verb> ...` forwards to the template's `scene` npm
+   script (run from the `animation-studio` directory; `pnpm scene` is equivalent).
+2. Run `npx @aura3d/cli@latest animation scene show --dry-run` first: it prints
+   the delegated script, runner, and cwd before anything edits.
+3. Read `src/aura-assets.ts` and `aura.assets.json`. Cast and prop GLBs you
+   bring yourself must be typed assets first (load `aura3d-assets`).
+4. Know where rendering works. The live renderer needs the Aura3D monorepo root
+   (it resolves the source build and runs headless Chromium plus ffmpeg).
+   Authoring and `validate` work in any scaffold; `render` does not.
+5. Benchmark mode: `npm install && npm run build`, then stop. No `render`, no
+   gate suite, no screenshots.
+
+## Procedure
+
+Previs (before any blocking):
+
+1. Write four one-line directions (A/B/C/D) that differ in tone, set, or
+   staging. Pick one and record why.
+2. Write a one-line beat sheet: one beat per planned shot, each with who acts
+   and what changes on screen.
+3. Lock the cast: a stable id per character (for example `worker-1`) that
+
+Author the document:
+
+4. Start from the prompt. `aura3d animation scene new --prompt "..." --full`
+   produces a complete draft (cast, dialogue, camera, per-beat actions). Omit
+   `--full` for an empty-cast skeleton you populate. `new` with no prompt is an
+   error; there is no default scene. Clone with `new --from <doc.json>`.
+5. Bind the cast. `--full` binds the curated A-grade humanoid cast, never the
+   Moon Garden characters. Override a slot from the catalog or a local rig,
+   and adjust size:
+
+   ```sh
+   aura3d animation scene cast add --id worker-1 --query "office worker in a shirt"
+   aura3d animation scene cast add --id worker-2 --file ./assets/hero.glb
+   aura3d animation scene scale --character worker-2 --to 1.1
+   ```
+6. Pick the set. The prompt routes through `pickSetForPrompt`; override with
+   `set <studio|garage|office|kitchen|moon-garden|space-station|meadow>` or
+   `set --query "..."`. Moon Garden is never the fallback; the neutral
+   `studio` is. Dress it with `dress --prop <id> --at x,z`, swap a prop for a
+   real GLB with `prop add --id <id> --query "..."`, and use `clear-props`.
+7. Stage each beat, then add or change shots. Every character needs its own
+   motion per beat; a lone lip flap is not a performance.
+
+   ```sh
+   aura3d animation scene block --character worker-1 --shot shot-1 --to -1,0 --yaw 0.4 --clip talk
+   aura3d animation scene gesture --character worker-2 --shot shot-2 --clip point
+   aura3d animation scene camera --shot shot-3 --preset close-up
+   aura3d animation scene shot add --id shot-4 --preset two-shot --duration 6
+   ```
+
+   Camera presets are `establishing`, `two-shot`, and `close-up`.
+8. Write dialogue yourself, one line per command:
+   `aura3d animation scene dialogue --line l0 --speaker worker-1 --text "We ship Friday." --start 0.4`.
+   `--end` is optional and computed from speech duration. Remove a line with
+   `dialogue --remove --line <id>`. Run `retime` to re-sequence all lines
+   back to back. This single track is the subtitles and the AuraVoice
+   lip-sync contract.
+9. `show` to read the summary, `undo` to step back (50 documents of history),
+   then `validate`. It must print `coherence: PASS` before you render.
+
+Render and hand off:
+
+10. From the monorepo template directory, preview a window, then render final
+    (`AURA_RENDER_STYLE=pbr` for realistic shading):
+
+    ```sh
+    aura3d animation scene render --range 0-12
+    AURA_QUALITY=final AURA_RENDER_STYLE=toon aura3d animation scene render
+    ```
+
+    Run final renders on a remote worker or CI where possible; they launch
+    Chromium and encode VP9.
+11. Outputs land in `dist/episodes/scene/`: `episode-3d.webm`, the stills
+    `frames/first.png`, `dialogue.png`, `action.png`, `final.png`, the
+    `mouth-open.png` / `mouth-closed.png` pair, skeleton-overlay strips, and
+    `render-live-summary.json`.
+12. The video is silent by design. Aura3D never runs TTS or muxes audio.
+    Confirm the summary records `audioOwnedBy: "auravoice"`, `engineTts: false`,
+    and non-zero dialogue line and caption cue counts. AuraVoice generates the
+    voice from the same dialogue track afterward.
+13. Captions: author them only as dialogue lines. Never add caption text as
+    scene geometry, labels, or DOM. The renderer derives burned-in captions
+    for the exported video from the dialogue track; the fidelity stills and
+    mouth pair are captured without captions.
+14. Run the gate suite against this render from the monorepo root:
+
+    ```sh
+    pnpm exec tsx --tsconfig tsconfig.base.json tools/animation-studio-gate-suite/index.ts \
+      --summary packages/create-aura3d/templates/animation-studio/dist/episodes/scene/render-live-summary.json \
+      --out tests/reports/animation-studio/gate-suite.json
+    ```
+
+    It is the AND of body-motion, lip-sync timing, subtitle timing, prompt
+    specificity, motion and visual quality, performance budget, readiness,
+    and no-fake-proof gates. Also run `pnpm scene:determinism`.
+15. Publish checklist, every item with an artifact: real route playback,
+    independently moving characters, visible mouth motion during dialogue,
+    exported captions from the dialogue track, a passing gate suite, and
+    review artifacts. Hand the claim label decision to
+    `aura3d-evidence-review`.
+
+## Stop and report
+
+- `validate` fails and a scene-tool edit cannot fix it: stop and report the
+  errors verbatim. Do not hand-edit `working.document.json` to force a pass.
+- No A-grade or catalog rig binds for a cast slot: stop and name the slot
+  rejected candidates. Do not substitute the Moon Garden cast, a still image,
+  or a primitive stand-in.
+- You are outside the monorepo, or no remote worker is available, so `render`
+  cannot run: stop after `validate`, label the episode `prototype`, and list
+  the render and gate commands still owed.
+- Any gate in the suite fails, or evidence is missing (the suite fails
+  closed): label the episode `prototype` and name the failing gate.
+- Someone needs a caption-free video master: there is no render flag for it
+  today. Report it as a gap.
+- Never present a still with CSS pan, zoom, or subtitles, a `sourceOnly: true`
+  plan, or an `image-puppet` route as animation. Never claim voice, TTS, or
+  audio from Aura3D.
+
+## References
+
+- [Animation Studio guide (commands, schema, rendering)](https://github.com/auraoneai/aura3d/blob/main/docs/animation-studio/guide.md)
+- [Episode production workflow](https://github.com/auraoneai/aura3d/blob/main/docs/workflows/animation-episode-production.md)
+- [Quality gates and limitations](https://github.com/auraoneai/aura3d/blob/main/docs/animation-studio/quality-and-limitations.md)
+- [AuraVoice bridge contract](https://github.com/auraoneai/aura3d/blob/main/docs/api/auravoice-bridge.md)
+- [Scene-Tool CLI source](https://github.com/auraoneai/aura3d/blob/main/packages/create-aura3d/templates/animation-studio/scripts/animation-scene.ts)
+- Rig inspection, clip maps, visemes: load `aura3d-character-animation`.
+- [Episode look continuity](references/shot-looks.md)

package/skills/aura3d-animation-studio/references/shot-looks.md

@@ -0,0 +1,26 @@
+# Episode look continuity
+
+One look across every shot — the episode reads as a single world. Shot
+differences come from framing, key placement and palette accents, never from a
+different grade.
+
+## Shot look board
+
+| Shot kind | Look stays | What moves | Anchor detail |
+| --- | --- | --- | --- |
+| establishing | same preset | wide frame, horizon + fog band visible | palette accent introduced |
+| dialogue | same preset | `interior-warm`-style pools, catchlights | face lit by key, rim separates hair |
+| action | same preset | `chase`/`tracking` framing | motion-blur-free but rim keeps silhouette |
+| night / stealth | `night-city` only if scripted as a second look | key drops to practical sources | emissive signs carry the palette |
+| climax | same preset | contrast maxes — deepest shadow, hardest key | accent hue saturates |
+
+## Rules that keep continuity
+
+- `looks.preset(<id>)` once, in the shared scene assembly — never per shot
+  (`look/multiple-looks`).
+- Fog density and grade stay constant; density jumps between cuts read as a
+  different world.
+- Reuse the key direction across shots; flipping key side mid-dialogue is the
+  classic continuity break.
+- The grade (`output.preset`) is fixed for the whole episode — a different
+  grade is a different timeline, not a different shot.

package/skills/aura3d-art-direction/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: aura3d-art-direction
+description: Sets the visual target and runs the look-dev loop for any Aura3D scene or game: genre look recipe, reference frames, look preset, capture, rubric judgement and iteration. Use when starting or finishing any scene, game, product viewer or template, or when a screenshot looks flat, dark, empty, floaty or placeholder-like.
+---
+
+## Look target
+
+1. Find the genre row in `references/look-recipes.md` (platformer, racing, fighting, arena shooter, sports/table, product, character, outdoor, interior, night city, space, underwater, cinematic).
+2. Pick 1-3 reference frames from `references/reference-frames.md`.
+3. Write a 3-line look brief: time of day, palette, mood. Keep it next to the route file.
+
+## Establish the contract
+
+- Every scene gets a look. The look is the environment, key/rim light, fog, background and grade as one preset.
+- Typed catalog assets for hero subjects (`model(assets.x)`), never a primitive hero.
+- `looks.appOptions(id)` spreads renderer options: `quality: "auto"` and the production profile. No renderer overrides.
+- Run `npx @aura3d/cli@latest --help` / `<cmd> --help` before invoking commands; read `src/aura-assets.ts` for typed asset names.
+
+## Procedure
+
+1. `scene().add(looks.preset("<id from the recipe row>"))` first, then typed assets, then gameplay/props.
+2. `createAuraApp(el, { scene, ...looks.appOptions("<id>") })`.
+3. Camera from the recipe row (rig + fov + subject frame %). The camera state is applied to the camera, not to evidence objects.
+4. Ground contact: full-strength key shadow (`shadow: true`) plus a contact detail at the subject's feet.
+5. HUD lives in DOM/CSS, never in the 3D scene. No debug overlay in shipped frames.
+
+## The 15 looks
+
+| Look | Mood | Palette key |
+| --- | --- | --- |
+| `outdoor-day` | clean midday, saturated | greens, sky blue, warm wood |
+| `golden-hour` | warm dusk drama | amber key, teal shadow |
+| `overcast` | soft even exposure | muted greys, gentle fill |
+| `polar-night` | cold moonlit stillness | ice blue, long shadows |
+| `alpine-snow` | high-altitude glare | white field, hard rim |
+| `product-studio` | neutral softbox stage | grey stage, brand accent |
+| `interior-neutral` | plain interior light | warm walls, clean fill |
+| `interior-warm` | cozy pools of light | wood, amber pools |
+| `interior-industrial` | warehouse cool | concrete, metal, skylight shafts |
+| `night-city` | neon streets | sodium pools, neon, wet reflections |
+| `neon-arcade` | saturated game glow | cyan/magenta emissive |
+| `arena-fight` | spotlit ring | dark crowd, hard key |
+| `space` | void + single sun | graphite, hard key, rim |
+| `underwater` | teal volume | caustics, biolume |
+| `character-showcase` | portrait studio | 3/4 key, rim, soft stage |
+
+## Look-dev loop
+
+Run until every rubric category scores >= 7, or 6 rounds, or 2 rounds with no gain:
+
+1. Capture: `aura3d look capture --route / --shots opening,mid,action --viewports desktop,mobile` (`--runner gh-actions` is the default where the template ships `.github/workflows/aura3d-lookdev.yml`; `--runner local` is the downstream user's choice).
+2. Judge: open each PNG and fill `look-judgement.json` against `references/quality-bar.md`; validate with `aura3d look judge --validate look-judgement.json`. Read `aura3d look lint` plus `app.diagnostics().look`.
+3. Change the single highest-leverage thing: lint codes first, then the lowest category. One change per round.
+4. Repeat. Record remaining gaps with their lint code or engine limitation — never paint over a gap with fake geometry.
+
+Hard checklist (all must hold before claiming done):
+
+- IBL on (environment HDRI or biome present)
+- Key shadow at full strength, contact darkening at feet
+- DPR >= min(devicePixelRatio, tier cap)
+- Background is sky/environment, not a void (or a declared exception)
+- Fog or atmosphere for depth where the genre row lists one
+- Grade through the look's post preset
+- Subject fills its genre frame % (see `references/look-recipes.md`)
+- No pure-primary primitives as the subject
+- Characters animated through the animation controller
+- HUD in DOM, not in-world
+- No debug overlay
+- `aura3d look lint` clean of error-severity codes
+
+## Stop and report
+
+- Stop after the loop exits (>= 7 everywhere, 6 rounds, or 2 flat rounds) and report the final `look-judgement.json` summary with remaining lint codes.
+- Label `prototype` when the loop could not run (no capture runner available): say which step failed.
+- A self-judgement is not a pass of the quality bar; only a panel round passes it. Report medians and the weakest category.
+
+## References
+
+- `references/look-recipes.md` — the 13 genre rows (look, camera, key, palette, atmosphere, post, VFX, assets, reference frames)
+- `references/quality-bar.md` — the 12-category rubric with observable anchors and the hard lint checks
+- `references/reference-frames.md` — named three.js r185 examples plus what you should see in each
+- `references/failure-gallery.md` — the failure patterns and the fix that removes each
+- `../aura3d-core/references/boundaries.md` — the boundary list (read once, do not restate)
+- [Framing and shots](references/framing-and-shots.md)

package/skills/aura3d-art-direction/references/failure-gallery.md

@@ -0,0 +1,64 @@
+# Failure gallery
+
+The recurring failure patterns (research/21) and the fix that removes each.
+Match the symptom on your PNG, apply the fix, re-capture. `visualQA` name-based
+heuristics may be referenced here for diagnosis only — they are deprecated and
+never acceptance evidence; use `structuralQA` names when a structural check is
+needed.
+
+## Void background
+
+Symptom: the world ends in a flat colour; horizonless, airless.
+Fix: add the look's environment (HDRI/biome) or `background`/`fog` from the
+recipe row. Lint: `look/solid-void` (unless the look declares the exception).
+
+## Flat shading
+
+Symptom: every surface the same brightness; no key direction.
+Fix: the look's environment supplies IBL; keep key intensity at the preset
+value. Lint: `look/no-ibl`, `look/no-lights`.
+
+## Ambient soup
+
+Symptom: shadows grey and directionless; scene reads washed-out.
+Fix: remove `lights.ambient` fill; the look's key + hemisphere/IBL supplies
+fill. Lint: `look/ambient-kills-ibl`, `look/ambient-flattens`.
+
+## Floating objects
+
+Symptom: props hover; no contact darkening at feet/wheels.
+Fix: key `shadow: true` at full strength plus a contact detail (ground, AO).
+Lint: `look/weak-shadow`.
+
+## Primitive soup
+
+Symptom: hero subject is boxes/spheres/cylinders.
+Fix: `model(assets.x)` from the typed catalog; `assets resolve "<genre> kit"`
+when unsure. Lint: `look/primitive-subject`.
+
+## Fake effect primitives
+
+Symptom: emissive planes/cards named like "wet reflection", "puddle streak",
+"rain splash" faking an effect the engine should produce.
+Fix: use the look's effects/post preset; model the practical (lamp, sign)
+instead. Lint: `look/fake-effect-names`.
+
+## Debug HUD in-world
+
+Symptom: health pips, timers or counters built from in-scene primitives, or a
+debug overlay in the shipped frame.
+Fix: move the HUD to DOM/CSS; strip the overlay. Lint: `look/debug-overlay`,
+`hud-is-dom` rejection in the v2 prompt report.
+
+## Renderer overrides
+
+Symptom: `pixelRatio`, `qualityProfile`, `safe-basic` or FXAA overrides in app
+code — usually added to "fix" a soft or banded frame.
+Fix: `looks.appOptions(id)` and the post preset; fix the look, not the
+renderer. Lint: `look/low-dpr`, `look/double-aa`.
+
+## Capture-only lighting
+
+Symptom: a `?capture=` branch that adds lights/effects only for screenshots.
+Fix: the shipped path must look right under default flags; iterate the look,
+not the branch. Lint: `look/capture-branch`.

package/skills/aura3d-art-direction/references/framing-and-shots.md

@@ -0,0 +1,45 @@
+# Framing and shots
+
+How to compose the frame so the look can be judged. A great look in a bad
+shot still reads as a bad scene.
+
+## Frame coverage
+
+| Shot | Subject % of height | Camera | Reads |
+| --- | --- | --- | --- |
+| hero/product | 50–70 | `orbit` or `perspective` fov 35–45 | silhouette + material, no crop |
+| environment establish | 10–20 subject | `establishing`/`dolly` fov 50 | fog band, horizon, palette sweep |
+| gameplay | 15–30 | genre rig | playfield + next obstacle in view |
+| character | 60–70 full body / 40 head | `follow` side-on or `orbit` | gait, rim, contact shadow |
+| night scene | 20–35 | `follow` street level | sign glow, wet reflections, pools |
+
+## Composition rules that change the read
+
+- Place the subject on a third line, not dead center, except for product
+  symmetry shots.
+- Keep the horizon near the lower third in outdoors — centering it flattens
+  depth and starves the fog band.
+- Give moving subjects look-ahead room (leading room) toward their direction.
+- One accent hue per frame: the eye finds it; two accents fight.
+- Fog and atmosphere only pay off at depth — an empty mid-ground shows
+  nothing, so stage a second layer (trees, walls, props) between subject and
+  horizon.
+- Vignette/post grade darkens corners; keep key information out of the outer
+  10% of frame.
+
+## Shot checklist before capture
+
+- [ ] subject visible at opening frame, not mid-spawn or mid-fade
+- [ ] `mid` shot shows the busiest expected state (particles, opponents)
+- [ ] `action` shot catches motion with the rim/key still readable
+- [ ] background layer is at least one atmosphere depth behind subject
+- [ ] HUD (DOM) frames the composition, not overlaps the subject
+
+## Shot vocabulary
+
+- `establishing`: wide, horizon in frame — palette and atmosphere carry it.
+- `push-in`: slow dolly toward subject; shadow density deepens as you close.
+- `tracking`: lateral follow; parallax shows depth layers + fog banding.
+- `crane`: vertical reveal; fog gradient reads strongest here.
+- `close-up`: material contrast + rim do all the work; fog irrelevant.
+- `silhouette`: subject against the brightest part of frame — grade defines it.

package/skills/aura3d-art-direction/references/look-recipes.md

@@ -0,0 +1,32 @@
+# Look recipes — 13 genre rows
+
+One row per genre. Use the row's look id verbatim, take its camera/framing/palette
+as the starting point, then iterate in the look-dev loop. Palettes: 3 base tones +
+1 accent, no pure primaries. Key = sun position `elevation°`/`azimuth°`. Subject %
+is the subject's share of frame height.
+
+| Genre | Look | Camera rig + fov | Subject % | Key | Palette | Atmosphere | Post | VFX | Reference frames |
+|---|---|---|---|---|---|---|---|---|---|
+| platformer | `outdoor-day` | `follow` (side-on), fov 50 | 18–25 | 48° / 35° (3/4 front) | saturated greens, sky blue, warm wood + coin gold | fog 0.0025 | `daylight-outdoor` | coin sparkle, land dust | `webgl_animation_skinning_blending` |
+| racing | `golden-hour` | `chase`, fov 60 | 15–25 | 12° / 35° (low sun) | warm asphalt, burnt orange, charcoal + headlight amber | fog 30–180 m | `cinematic-film` | brake glow, speed dust | `webgl_materials_car` |
+| fighting | `arena-fight` | `follow` (side-on), fov 45 | 20–30 (pair) | top spot 60° / 0° | arena dark, rope colour, crowd shadow + spotlight rim | haze cone | `arena-fight` | hit sparks, knockback flash | `webgl_animation_skinning_morph` |
+| arena shooter | `space` | `orthographic` (top-down) 60°, fov 55 | 10–15 (field) | rim 70° / 210° | deep space blue, graphite, teal + laser magenta | none (space background exception) | `space` | model muzzle flash, shield segments | `webgl_shaders_sky` |
+| sports/table | `interior-industrial` | broadcast `orthographic` (top-down) 70°, fov 40 | 25–40 (table) | flood 55° / 45° | turf green, line white, crowd dark + ball accent | indoor haze | `arena-fight` | scoreboard pulse | `webgl_materials_lightmap` |
+| product | `product-studio` | `orbit` autoframe, fov 35 | 45–70 | softbox 45° / 30° | neutral grey, white, metal + one brand accent | none | `product-studio` | sweep highlight on turn | `webgl_materials_video` |
+| character | `character-showcase` | `orbit`, fov 40 | 50–70 | 3-point 50° / 35° | costume-driven neutrals + rim pick | light room haze | `product-studio` | cloth/hair motion settle | `webgl_animation_skinning_blending` |
+| outdoor environment | `overcast` | `establishing` wide, fov 55 | vista | 50° / 40° | muted green, slate, fog blue + wildflower accent | fog 0.004 | `daylight-outdoor` | wind grass, drifting cloud | `webgl_lights_physical` |
+| interior | `interior-warm` | medium `orbit`, fov 45 | 30–50 (anchor) | window 35° / 60° | warm wood, cream wall, book spines + plant green | dust shafts | `cinematic-film` | window bounce | `webgl_lights_spotlight` |
+| night city | `night-city` | low tele, fov 35 | 20–35 (street) | neon rim 25° / 120° | sodium orange, neon sign, dark asphalt + cyan accent | fog 15–90 m, wet street | `neon-night` | sign flicker, drizzle sheen | `webgl_lights_spotlights` |
+| space | `space` | `orbit` wide, fov 60 | 30–50 (planet) | star key 30° / 180° | void blue, planet limb, star field + aurora accent | none (background exception) | `space` | engine trail, planet rotation | `webgl_shaders_sky` |
+| underwater | `underwater` | `follow`, fov 50 | 20–40 (creature) | godray 70° / 10° | deep blue, teal, kelp green + coral accent | scatter 0.03, caustics | `underwater` | bubble stream, silt drift | `webgl_water` |
+| cinematic | `polar-night` | `establishing` dolly, fov 35 | 25–40 | moon 20° / 300° | aurora green, snow blue, night + lantern amber | snow mist 0.006 | `cinematic-film` | aurora drift, breath fog | `webgl_animation_cloth` |
+
+Notes:
+
+- `orbit`/`follow`/`follow` (side-on)/`follow` (side-on)/`shoulder`/`orthographic` (top-down)/`chase`/`establishing`
+  are camera-rig names used by the template gate; wire them through the camera
+  rig spec API of the current engine version, never through evidence fields.
+- "background exception" rows skip the sky-fill hard check; the look's own
+  background supplies the void.
+- VFX rows name models/practicals; no CSS/DOM overlays and no primitive sprite
+  cards faking rain, reflections or splashes.

package/skills/aura3d-art-direction/references/quality-bar.md

@@ -0,0 +1,103 @@
+# Quality bar — the 12-category look rubric
+
+Score every captured PNG per category 0-10 in 0.5 steps. Anchors are written as
+what you observe, not what the code does. A score < 7 needs an `observations`
+entry naming the concrete thing seen on screen.
+
+## lighting
+
+- 2: one flat light everywhere; faces and props read equally bright
+- 5: a key direction exists but the fill flattens it; mood is generic daylight
+- 7: clear key + fill + rim separation; the mood matches the look brief
+- 9: light feels motivated by the world (sun, sign, lamp); bounce and colour temperature vary by area
+
+## shadows
+
+- 2: no visible shadow; objects float
+- 5: a shadow exists but is grey/soft with no contact darkening
+- 7: dark contact shadows ground every object, soft falloff
+- 9: cascaded and stable; contact + ambient occlusion match the reference
+
+## ibl_reflections
+
+- 2: surfaces uniform, no environment response
+- 5: metals look like plastic; reflections faint or absent
+- 7: environment visible in glossy surfaces; roughness varies by material
+- 9: reflections pick up the actual sky/studio setup and track correctly
+
+## environment_world
+
+- 2: solid void background
+- 5: a sky/ground exist but read as a backdrop, not a place
+- 7: horizon, ground and props compose a believable space
+- 9: parallax layers (far, mid, near) plus weather or time-of-day cues
+
+## atmospheric_effects
+
+- 2: air is empty; no depth between near and far
+- 5: a fog exists but mismatches the light (wrong colour or distance)
+- 7: fog/haze ties to the horizon colour and lifts the far field
+- 9: volumetric cues (shafts, mist, drizzle) read at a glance
+
+## material_quality
+
+- 2: one flat colour per object, everything the same
+- 5: some materials differ but most read as untextured plastic
+- 7: wood/metal/fabric/skin read distinctly; normal/roughness respond to light
+- 9: materials carry wear, edge highlights and texture at read distance
+
+## modeling_assets
+
+- 2: hero subject is a box/sphere primitive
+- 5: typed models but scale mismatches or obvious gaps
+- 7: real models at real scale, fitted to the world
+- 9: asset variety, dressing and silhouette richness like the reference
+
+## composition
+
+- 2: subject centred and tiny, or clipping the frame edge
+- 5: subject visible but dead-centre symmetry with wasted space
+- 7: clear focal hierarchy; rule-of-thirds or genre framing used
+- 9: leading lines and depth layers direct the eye through the shot
+
+## camera
+
+- 2: default angle; horizon level but arbitrary
+- 5: a deliberate angle exists but fov/height flattens the subject
+- 7: rig matches the genre row; subject inside its framing band
+- 9: camera reads as a choice (dolly, chase, orbit) and moves with intent
+
+## postprocessing
+
+- 2: raw output; clipped brights or crushed blacks
+- 5: a grade exists but fights the palette (muddy or oversaturated)
+- 7: tone/grade holds the palette; AO grounds the mid-tones
+- 9: grade + bloom + AO are tuned as one image pipeline
+
+## animation_quality
+
+- 2: hero subject static or sliding
+- 5: animation exists but feet slide or loops stutter
+- 7: locomotion matches travel direction; idle vs action states read
+- 9: secondary motion and timing give the subject weight
+
+## ui_hud
+
+- 2: debug overlay or dev counters in the shipped frame
+- 5: HUD exists but overlaps the subject or sits off-layout
+- 7: HUD in DOM, readable, out of the subject's way
+- 9: HUD styled to the game's palette and responsive at mobile width
+
+## Hard checks (lint codes that must be clean)
+
+`aura3d look lint` plus `app.diagnostics().look.lint` must report no
+`error`-severity finding for:
+
+- `look/no-lights`, `look/no-ibl` — the scene lights and reflects nothing
+- `look/ambient-kills-ibl`, `look/ambient-flattens` — ambient used as the only fill
+- `look/solid-void` — void background without a declared exception
+- `look/low-dpr`, `look/double-aa` — renderer overrides or doubled AA
+- `look/fake-effect-names`, `look/capture-branch` — fake effect primitives or
+  capture-only branches (except where the flagged lane allows capture branches)
+- `look/primitive-subject`, `look/debug-overlay` — primitive hero or shipped debug HUD
+- `look/multiple-looks`, `look/expansion-mismatch` — look conflicts

package/skills/aura3d-art-direction/references/reference-frames.md

@@ -0,0 +1,82 @@
+# Reference frames
+
+Named three.js r185 examples (https://threejs.org/examples/) — the day-0 frame
+set. When the C-30 v2 reference scenes and the licensed stills in
+`benchmarks/quality-rebuild/refs/` land on main, they replace rows here. Every
+frame carries "what you should see" so the file is complete without images.
+
+## webgl_animation_skinning_blending
+
+https://threejs.org/examples/#webgl_animation_skinning_blending
+
+What you should see: a rigged character blending between locomotion clips under
+a real key light with shadows that track the feet. Use for: platformer,
+character — how a typed GLB hero should sit in a lit world.
+
+## webgl_animation_skinning_morph
+
+https://threejs.org/examples/#webgl_animation_skinning_morph
+
+What you should see: a creature head deforming through morph targets with skin
+and eye materials responding to environment light. Use for: fighting — facial
+and secondary motion quality on real materials.
+
+## webgl_animation_cloth
+
+https://threejs.org/examples/#webgl_animation_cloth
+
+What you should see: draped cloth catching directional light with soft,
+contact-darkened shadows on the floor. Use for: cinematic — fabric motion plus
+moody lighting discipline.
+
+## webgl_materials_car
+
+https://threejs.org/examples/#webgl_materials_car
+
+What you should see: a car body with clearcoat reflections pulling the
+environment into the paint, grounded by contact shadow. Use for: racing — how
+glossy materials and IBL should look on a vehicle.
+
+## webgl_materials_video
+
+https://threejs.org/examples/#webgl_materials_video
+
+What you should see: a product-like object under studio lighting with clean
+softboxes and a controlled backdrop. Use for: product — framing and soft studio
+key.
+
+## webgl_materials_lightmap
+
+https://threejs.org/examples/#webgl_materials_lightmap
+
+What you should see: baked light/detail on an architectural interior with warm
+bounce in corners. Use for: sports/table and interior — indoor light richness
+without dynamic lights.
+
+## webgl_lights_physical
+
+https://threejs.org/examples/#webgl_lights_physical
+
+What you should see: physically-motivated lamps in a simple room, falloff that
+reads as real. Use for: outdoor environment, interior — key/fill discipline.
+
+## webgl_lights_spotlights
+
+https://threejs.org/examples/#webgl_lights_spotlights
+
+What you should see: spot cones with visible falloff on a dark floor, haze
+inside the beam. Use for: night city — motivated practical lighting after dark.
+
+## webgl_shaders_sky
+
+https://threejs.org/examples/#webgl_shaders_sky
+
+What you should see: a full-bleed sky dome with sun, horizon gradient and haze —
+never a void. Use for: space, arena shooter, outdoor — background treatment.
+
+## webgl_water
+
+https://threejs.org/examples/#webgl_water
+
+What you should see: an animated water surface with normals, reflections and
+shore interaction. Use for: underwater — surface/caustic atmosphere cues.