create-aura3d 3.0.0 → 4.0.0

package/skills/aura3d-assets/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: aura3d-assets
+description: Finds, admits, inspects, validates, and types GLB/glTF, texture, environment, and audio assets through the Aura3D CLI so scenes use `model(assets.x)`. Use when a prompt names a real object, the user brings a GLB, or the task touches `assets search`, `assets resolve`, `assets add`, `assets inspect`, `assets validate`, `assets typegen`, `aura.assets.json`, or `src/aura-assets.ts`.
+---
+
+# Aura3D assets
+
+The CLI is the only path from a file or catalog hit to a typed `assets.<key>`.
+Shared rules (catalog-first, typed assets, paid generation) are in
+[boundaries](../aura3d-core/references/boundaries.md).
+
+## Look target
+
+Preview candidates under the target look, not a neutral stage: a GLB that
+reads clean under `product-studio` softboxes can disappear into `night-city`
+shadow pools or bloom out under `neon-arcade`. The route's recipe row sets the
+lighting you evaluate materials and silhouettes against.
+
+## Establish the contract
+
+1. Run `npx @aura3d/cli@latest --help` and `npx @aura3d/cli@latest assets add
+   --help`. Use only the flags they print; `--profile` values for search and
+   resolve come from the usage line, not memory.
+2. Read `aura.assets.json` and `src/aura-assets.ts`. Reuse an existing key
+   before adding a duplicate.
+3. Note each asset's role: `character`, `vehicle`, `world`, `environment`,
+   `track`, `product`, `weapon`, `prop`, `set-dressing`, `debug`, `abstract`,
+   or `unknown`. Role decides the evidence you need later.
+
+## Procedure
+
+1. User supplied a file: skip search and admit it with provenance.
+
+   ```bash
+   npx @aura3d/cli@latest assets add ./assets/robot.glb --name robot \
+     --type model --role character --quality candidate \
+     --license CC0-1.0 --license-url <url> --source-page <url> \
+     --author "<name>" --retrieved-at <ISO-8601>
+   ```
+
+   Use `--type texture|environment|audio|navigation` for non-model files, and
+   `--public-path /cdn/aura-assets/` when assets are served from a CDN.
+2. Prompt names a real object: search with a descriptive phrase.
+
+   ```bash
+   npx @aura3d/cli@latest assets search "battle-worn knight helmet" --json
+   npx @aura3d/cli@latest assets search "animated humanoid fighting character" \
+     --profile fighting-character --json
+   ```
+
+   Narrow with `--license cc0|cc-by`, `--max-tris N`, or `--animated`.
+3. Read the result. Only auto-pullable candidates may be pulled. Marketplace
+   deep-links and `manual license check required` rows are user-handled: hand
+   the link to the user and admit their download with `assets add`.
+4. Pull the chosen candidate into a typed key.
+
+   ```bash
+   npx @aura3d/cli@latest assets resolve "battle-worn knight helmet" --name helmet
+   ```
+
+   Pick a non-top candidate with `--index N` or `--candidate-id ID`, and repeat
+   the same `--profile` you searched with.
+5. Inspect before naming clips, joints, morphs, or materials in code.
+
+   ```bash
+   npx @aura3d/cli@latest assets inspect public/aura-assets/<file>.glb \
+     --animation --humanoid --skeleton --morphs --license
+   ```
+
+   Treat `"ok": false` warnings (for example missing orientation metadata) as
+   facts to record, not noise.
+6. Regenerate types and validate the shipping set.
+
+   ```bash
+   npx @aura3d/cli@latest assets typegen
+   npx @aura3d/cli@latest assets validate --asset helmet --source
+   ```
+
+   `--source` scans `src` for raw ids, URLs, and loader code, and lists
+   `typedAssetUsages`. Add `--no-placeholders --require-license` for anything
+   public. Refresh stale manifest bounds by re-adding the file.
+7. Use the key exactly as generated.
+
+   ```ts
+   import { createAuraApp, groundedRenderedAssetPlacement, looks, model, scene } from "@aura3d/engine";
+   import { assets } from "./aura-assets";
+
+   const place = groundedRenderedAssetPlacement(assets.helmet, { targetMaxDimension: 1.2, floorY: 0 });
+   createAuraApp("#app", {
+     scene: scene()
+       .add(looks.preset("product-studio"))
+       .add(model(assets.helmet).position(...place.position).scale(place.scale)),
+     ...looks.appOptions("product-studio")
+   });
+   ```
+
+8. Hand off: fighters and games to `aura3d-browser-game`
+   (`assets validate-game`), rigs and clips to `aura3d-character-animation`
+   (`assets validate-animation`), release checks to `aura3d-evidence-review`.
+
+## Reject a candidate when
+
+- license, source page, author, or acquisition time is missing or temp-only
+  (for example a `/var/folders/.../aura3d-resolve-*` source);
+- no material or texture evidence exists where the role expects texture;
+- a character route claims animation but inspection shows no usable clips;
+- bounds are extreme, pivot is bad, or orientation is unknown and public APIs
+  cannot correct it;
+- the hash duplicates another asset without an explanation;
+- it is placeholder-like, or only a generated thumbnail proves it is readable.
+
+## Stop and report
+
+- Search returns no auto-pullable candidate, or every candidate fails the
+  reject list: stop, list the query, profile, and rejection reasons, and offer
+  two options: a user-supplied licensed file, or Meshy generation (load
+  `meshy-cli`, dry run first). Do not model the subject from primitives.
+- Search prints a catalog fetch warning (for example an HTTP 404 from the
+  index): report it verbatim, label asset-dependent work `blocked`, and do not
+  treat fallback deep-links as auto-pullable.
+- `assets validate --release` fails on provenance: keep the route `prototype`
+  until durable evidence is added; never weaken the check.
+- A needed key is absent from `src/aura-assets.ts` after typegen: stop and fix
+  the admission.
+
+## References
+
+- [Boundaries](../aura3d-core/references/boundaries.md)
+- [Asset workflow](https://github.com/auraoneai/aura3d/blob/main/docs/agents/asset-workflow.md)
+- [Asset selection](https://github.com/auraoneai/aura3d/blob/main/docs/agents/asset-selection.md)
+- [Assets docs](https://aura3d.auraone.ai/docs/assets.html)
+- [Previewing assets under a look](references/preview-under-look.md)

package/skills/aura3d-assets/references/preview-under-look.md

@@ -0,0 +1,26 @@
+# Previewing assets under a look
+
+A GLB that survives a neutral viewer can still fail the real scene's lighting.
+Evaluate candidates under the route's look preset.
+
+| Look | What it exposes | Reject signal |
+| --- | --- | --- |
+| `product-studio` | material honesty, silhouette edge quality | faceted normals, muddy PBR, bad pivot on plinth |
+| `golden-hour` | warm key + teal shadow separation | specular wash, albedo too dark to read at dusk |
+| `night-city` | neon rim, wet reflections, dark pools | silhouette disappears into shadow, emissive bloom-out |
+| `outdoor-day` | full daylight exposure, horizon fog | washed-out albedo, no AO at contact points |
+| `interior-warm` | warm pools, wood/fabric pairing | cold grey materials fight the grade |
+| `space` | single hard key, black void | anything mid-grey vanishes; no fill light forgiving |
+| `underwater` | teal volume, caustic shimmer | high-contrast speculars shimmer to noise |
+| `arena-fight` | top spot + rim, dark crowd | midtones crush to black outside the pool |
+
+## Checks at preview time
+
+1. Spin the model `orbit` once under the look — a silhouette that dies at
+   three-quarter back is a bad candidate.
+2. Contact: feet/wheels/anchor inside the look's ground shadow, not beside it.
+3. Emissive parts bloom only where the grade expects glow (pickups, signage);
+   an unbounded emissive channel reads as a bug.
+4. Palette: the asset's dominant hue must sit inside the genre palette or be
+   the declared accent — clashing saturation reads as wrong-asset even when
+   the mesh is fine.

package/skills/aura3d-browser-game/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: aura3d-browser-game
+description: Builds a playable Aura3D browser game route on the public genre kits with typed assets, deterministic input, reset, an objective, and a genre look recipe driven through the look-dev loop. Use when working in the `mini-game`, `racing-starter`, `falling-blocks-starter`, `fighting-game`, or `character-controller` templates, calling `game.platformer`, `game.racing`, `game.fallingBlocks`, `game.fighting`, or `game.evidence`, or running `assets validate-game` or `assets certify-game-geometry`.
+---
+
+# Aura3D browser game
+
+A route with a scene and a key listener is not a game — and a playable scene
+with flat lighting is not a finished game. A public game proves input, reset,
+an objective and a progression loop in the browser AND looks like its genre.
+Shared rules (claim labels, forbidden patterns, typed assets, benchmark mode)
+are in [boundaries](../aura3d-core/references/boundaries.md).
+
+## Look target
+
+Genre → recipe row (full table: `../aura3d-art-direction/references/look-recipes.md`):
+
+| Template | Look | Camera | Frame mood |
+| --- | --- | --- | --- |
+| `mini-game` | `outdoor-day` | `follow` (side-on) fov 50 | saturated greens, sky blue, warm wood + coin gold; fog 0.0025; `daylight-outdoor` post; coin sparkle + land dust |
+| `racing-starter` | `golden-hour` | `chase` fov 60 | warm asphalt, burnt orange, charcoal + headlight amber; low sun haze; `cinematic-film` post; brake glow |
+| `falling-blocks-starter` | `neon-arcade` | `orthographic` (top-down) fov 45 | neon palette per piece colour, dark glossy board + accent rim; `neon-night` post; line-clear flash |
+| `fighting-game` | `arena-fight` | `follow` (side-on) fov 45 | arena dark, rope colour, crowd shadow + spotlight rim; haze cone; `arena-fight` post; hit sparks |
+| `character-controller` | `outdoor-day` | `shoulder` fov 55 | open world greens + cloth accent; fog to horizon; `daylight-outdoor` post |
+
+## Establish the contract
+
+1. Run `npx @aura3d/cli@latest --help`. Use only the commands and flags it
+   prints; `--category` accepts only `racing` or `platformer`.
+2. Read `src/aura-assets.ts` and `aura.assets.json`. Player, vehicle, track,
+   and world must be typed keys with a role (`character`, `vehicle`, `track`,
+   `world`). Missing keys: load `aura3d-assets` first.
+3. Read the template `package.json` so you know what `npm run test` runs.
+4. Decide the mode. Benchmark mode: if `aura3d look capture` is available, run
+   the look-dev loop; otherwise build and stop, label `prototype`.
+
+## Procedure
+
+1. Scaffold the matching template, then add the genre look before any props:
+
+   ```ts
+   import { createAuraApp, game, looks, model, scene } from "@aura3d/engine";
+   import { assets } from "./aura-assets";
+
+   const app = createAuraApp("#app", {
+     scene: scene()
+       .add(looks.preset("outdoor-day"))
+       .add(model(assets.hero).runtime(game.runtimeNode("player", { tags: ["player"] }))),
+     ...looks.appOptions("outdoor-day")
+   });
+   const player = app.nodes.require("player");
+   const input = app.input({
+     actions: { left: ["KeyA", "ArrowLeft"], right: ["KeyD", "ArrowRight"], jump: ["Space"], restart: ["KeyR"] },
+     axes: { moveX: { negative: "left", positive: "right" } },
+     bufferMs: 120
+   });
+   const level = game.platformer({
+     start: { x: 0, y: 0.35 },
+     finish: { x: 12, y: 0.35 },
+     platforms: [{ id: "ground", x: -1, y: 0, width: 14, height: 0.35 }]
+   });
+
+   app.onFrame(({ dt }) => {
+     input.update(dt);
+     const state = level.step(dt, { moveX: input.axis("moveX"), jumpPressed: input.buffered("jump") });
+     player.setPosition(state.player.x, state.player.y, 0);
+   });
+   ```
+
+2. The look supplies the sky light, key shadow, fog and grade — do not add
+   `lights.studio()` or `lights.ambient()` on top.
+3. Typed models at real scale for hero/collectibles (emissive 3–5 on pickups
+   reads as sparkle under the post grade); platforms/track from the best
+   typed catalog kit.
+4. Camera state drives `app.camera` every frame (rig from the genre row) —
+   never write camera position into evidence fields.
+5. Wire HUD and events through `game.eventLog` and `game.hud.*` — DOM HUD only,
+   no in-world counters, no debug overlay in shipped frames.
+6. Make reset real: restart after normal play and after win or fail returns
+   score, timer, bodies, input, and animation to baseline.
+7. Genre gates (mechanics, from the game example standards):
+
+   | Genre | Must have |
+   | --- | --- |
+   | racing | throttle, brake, steer, ordered checkpoints, lap or finish, penalty or timeout |
+   | platformer | move, jump, fall, collision matching visible ledges, collectibles, hazards, camera keeps player visible |
+   | falling blocks | move, rotate, soft + hard drop, lock, line clear, scoring, levels, game over |
+   | fighting | strikes/blocks, hit reactions, round + KO state, both fighters readable |
+   | character controller | walk/run/jump clips playing, camera shoulder follow, locomotion direction matches travel |
+
+   Plan for 60 seconds of meaningful play.
+
+8. `npx @aura3d/cli@latest assets validate --no-placeholders --require-license`
+   and `assets validate-game`; racing/platformer also
+   `assets certify-game-geometry --asset track --category racing`.
+9. Runtime evidence: pause, step one frame, then `game.evidence` over input,
+   bodies, events, HUD, app state — see `aura3d-evidence-review` (one link).
+
+## Look-dev loop
+
+Run the `aura3d look capture` → judge → iterate loop from
+`aura3d-art-direction`: lint first (`aura3d look lint`), then the weakest
+rubric category; one change per round until every category reads 7+, 6
+rounds, or 2 flat rounds.
+
+## Stop and report
+
+- `assets certify-game-geometry` returns `"ok": false` or a blocker such as
+  `racing-road-mesh-not-found`: label `prototype`; never hide the gap with
+  primitive ledges or road strips.
+- Manual input cannot complete the route while a proof replay can: `prototype`.
+- The primary player, vehicle, or world is a primitive stand-in: `prototype`.
+- `assets validate-game` crashes or fails: report the exact message, label
+  `blocked` for public claims.
+- A kit is missing a needed rule (fail state, collision semantics, path
+  alignment): write it route-local, say so, file a library gap.
+- Benchmark mode without `look capture`: build, stop, label `prototype`.
+
+## References
+
+- [Shared boundaries](../aura3d-core/references/boundaries.md)
+- [Look recipes](../aura3d-art-direction/references/look-recipes.md)
+- [Quality bar](../aura3d-art-direction/references/quality-bar.md)
+- [Build a browser game](https://github.com/auraoneai/aura3d/blob/main/docs/guides/build-a-browser-game.md)
+- [Game example standards](https://github.com/auraoneai/aura3d/blob/main/docs/agents/game-example-standards.md)
+- [Game runtime API](https://github.com/auraoneai/aura3d/blob/main/docs/api/game-runtime.md)
+- [Genre looks in the frame](references/genre-looks.md)

package/skills/aura3d-browser-game/references/genre-looks.md

@@ -0,0 +1,52 @@
+# Genre looks in the frame
+
+What each genre's look must visibly deliver, at capture time.
+
+| Genre | The frame must show | Kills the look |
+| --- | --- | --- |
+| platformer | blue sky with depth fog, long grass-edge shadows, warm key on the hero, gold pickups glowing | void background, ambient-only light, floating platforms |
+| racing | low warm sun, orange rim on the car silhouette, asphalt reflection, fog band at the horizon | noon-flat light, grey void, no specular on bodywork |
+| falling blocks | saturated piece hues against a dark glossy board, bloom on line-clear, rim on the stack edge | washed-out palette, flat board, no glow on clears |
+| fighting | top spotlight cones, rim on both fighters, crowd silhouettes in shadow | both fighters evenly lit, empty void arena |
+| character showcase | 3/4-front key, rim separating hair/shoulder from backdrop, ground contact shadow | flat fill, floating feet, void |
+| night city | neon signage, wet-street reflections, sodium pools, window glow | pure black background, one uniform dark |
+
+## Per-genre VFX palette
+
+| Genre | Accents (emissive 3–5× bg) | Motion cue |
+| --- | --- | --- |
+| platformer | coin gold, spring green, hazard red | land dust puff, jump trail |
+| racing | brake amber, exhaust white, dial cyan | speed lines, tire smoke |
+| falling blocks | per-piece neon hue, clear flash white | line-clear flash, lock click glow |
+| fighting | impact spark orange, meter cyan | hit sparks, knockback flash |
+| character | cloth accent, eye catchlight | footstep dust, hair/cloth sway |
+| night city | sign neon, puddle rim | steam wisps, window flicker |
+| sports/table | felt green, chalk white, spot warm | ball trail, score flash |
+| interior | warm pool amber, accent object hue | dust motes, lamp flicker |
+| underwater | caustic teal, biolume cyan | bubbles, particle drift |
+| space | laser magenta, engine white | debris drift, shield ripple |
+
+## HUD style
+
+DOM HUD only. Type color follows the look: warm cream on golden-hour, neon
+cyan on night-city, high-contrast white on product-studio. Pause/menu layers
+inherit the grade (a blur + dark grade band reads as one scene, a raw solid
+overlay reads as a bug).
+
+## Lighting story per template
+
+| Template | Key story | Shadow story | Depth cue |
+| --- | --- | --- | --- |
+| `mini-game` | warm afternoon key 40° | grass-edge shadows toward camera | fog band at far platforms |
+| `racing-starter` | low sun behind the car | long streaks across asphalt | haze silhouettes the horizon |
+| `falling-blocks-starter` | soft top key | piece self-shadow on stack | board gloss reflection |
+| `fighting-game` | overhead spot cones | rim shadows under both fighters | crowd fades to black |
+| `character-controller` | daylight key 3/4 front | contact shadow under feet | fog to horizon on the run |
+
+## Mood one-liners
+
+- platformer: cheerful daylight, saturated palette, motion reads as play.
+- racing: speed sells through low sun, glare, and horizon haze.
+- fighting: drama lives in the dark crowd and the spot's hard edge.
+- blocks: rhythm is the palette — every piece hue distinct at a glance.
+- character: the silhouette is the gameplay; rim keeps it readable.

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

@@ -0,0 +1,129 @@
+---
+name: aura3d-character-animation
+description: Drives rigged Aura3D characters from inspected clip, skeleton, and morph metadata with an animation controller, clip events, runtime pose and morph state, and voice-bridge visemes, then proves motion in character-region pixels. Use when animating a humanoid or creature, using `AnimationController`, `createAnimationController`, or `animation.sampleAuraVoiceBridgeAtTime`, setting morph targets or visemes, or running `assets inspect --animation`, `assets validate-animation`, or `assets assemble-character`.
+---
+
+# Aura3D character animation
+
+Clip, bone, and morph names come from the asset, never from memory. Controller
+state is source evidence; a visible animation claim needs pixel deltas on the
+character. Shared rules (claim labels, forbidden patterns, typed assets,
+benchmark mode) are in [boundaries](../aura3d-core/references/boundaries.md).
+
+## Look target
+
+A character reads through its silhouette and rim: `character-showcase` (or the
+genre recipe's look) supplies the 3/4-front key plus rim that makes locomotion,
+poses and morphs visible. Judge animation under that look — a clip that reads
+in flat light can vanish inside night-city shadow pools or golden-hour haze.
+
+## Establish the contract
+
+1. Run `npx @aura3d/cli@latest --help` and use only the `assets inspect`,
+   `assets validate-animation`, and `assets assemble-character` flags it prints.
+2. Read `src/aura-assets.ts` and `aura.assets.json`. The character must be a
+   typed key with role `character`. No key: load `aura3d-assets` first.
+3. Inspect the rig and record the real names:
+
+   ```bash
+   npx @aura3d/cli@latest assets inspect ./public/aura-assets/hero.glb --animation --skeleton --morphs
+   ```
+
+   Read the JSON fields "animations", "skeleton.skins[].joints", and
+   "morphTargets.targetNames".
+   `"No morph target metadata detected."` means no morph or viseme work on
+   this asset.
+4. Decide the mode. Benchmark mode: `npm install && npm run build`, then stop.
+
+## Procedure
+
+1. Map gameplay actions to real clip names and fail fast on gaps:
+
+   ```bash
+   npx @aura3d/cli@latest assets validate-animation --clips idle,walk,sprint,jump \
+     --map idle=idle,walk=walk,run=sprint --require idle,walk,run --require-rig
+   ```
+
+   Pass `--clips` from the inspection output. `"ok": false` with a
+   `missingActions` entry means the rig cannot play that action.
+2. Multi-part characters: build the assembly from typed keys first.
+
+   ```bash
+   npx @aura3d/cli@latest assets assemble-character --name hero --body heroBody --part hair=heroHair
+   ```
+
+3. Create one controller per character from typed clip metadata, bind it to a
+   runtime node, and update it once per frame:
+
+   ```ts
+   import { createAnimationController, createAuraApp, game, lights, model, scene } from "@aura3d/engine";
+   import { assets } from "./aura-assets";
+
+   const app = createAuraApp("#app", {
+     scene: scene()
+       .add(model(assets.hero).runtime(game.runtimeNode("hero", { tags: ["player"] })))
+       .add(lights.studio())
+   });
+   const hero = app.nodes.require("hero");
+   const controller = createAnimationController({
+     id: "hero-animation",
+     clipRegistry: assets.hero,
+     requiredClips: ["idle", "walk", "sprint"],
+     suppressRootMotion: true
+   });
+   controller.bindRuntimeNode(hero, { id: "hero-binding", defaultClipId: "idle" });
+
+   let moving = false; // set from your input or kinematic body each frame
+   app.onFrame(({ dt }) => {
+     controller.crossFade(moving ? "walk" : "idle", 0.12);
+     controller.update(dt);
+   });
+   ```
+
+4. Clip-local gameplay events (event names such as "hitbox.open", "sfx", "vfx",
+   "camera.impulse", "caption", "viseme") go through the controller's event subscription. Bridge
+   them into public systems such as `game.combatWorld`; never call private
+   hitbox or renderer internals.
+5. Pose and morph state go through the runtime node handle (its animation-pose
+   and morph-target setters). App code never reaches into renderer skinning.
+6. Voice sync: sample the bridge package at the frame time and apply the
+   viseme weights to the node's morph targets, using only morph names the
+   inspection reported.
+
+   ```ts
+   import { animation } from "@aura3d/engine";
+
+   app.onFrame(({ time }) => {
+     const sample = animation.sampleAuraVoiceBridgeAtTime(bridgePackage, time, "host");
+     app.nodes.require("host").setMorphTargets(sample.viseme?.blendshapeWeights ?? {});
+   });
+   ```
+
+7. Retargeting is explicit and selected-roster only. Use an explicit humanoid
+   map; do not claim arbitrary-rig retargeting or full-body IK.
+8. Normal mode: `npm run build` locally. Browser proof (deterministic capture
+   times inside the clip's keyframe range, stable camera, character-region
+   pixel delta, backend and fallback named) runs remotely via the template
+   `npm run test` or CI. Hand results to `aura3d-evidence-review`.
+
+## Stop and report
+
+- A clip, bone, or morph you need is absent from the inspection output: stop
+  and report it. Do not rename clips in code or guess names.
+- `assets validate-animation` returns `"ok": false`: the action map is
+  `blocked` until a rig with the clip is admitted.
+- A clip is a static pose (zero channel motion): it cannot satisfy an
+  animation row; pick a clip with real motion or label `prototype`.
+- The claim is "visible skinning, morphs, or visemes" and you only have
+  controller snapshots or clip lists: label it `prototype`.
+- Only the certified roster in the skinning doc may be called certified.
+
+## References
+
+- [Shared boundaries](../aura3d-core/references/boundaries.md)
+- [Skinning and morphs](https://github.com/auraoneai/aura3d/blob/main/docs/rendering/skinning-and-morphs.md)
+- [Animation, retargeting, IK](https://github.com/auraoneai/aura3d/blob/main/docs/rendering/animation.md)
+- [Animation runtime events](https://github.com/auraoneai/aura3d/blob/main/docs/api/animation-runtime-events.md)
+- [Animation runtime support](https://github.com/auraoneai/aura3d/blob/main/docs/animation/runtime-support.md)
+- [Agent guide llms.txt](https://github.com/auraoneai/aura3d/blob/main/llms.txt)
+- [Character staging and lighting](references/stage-and-lighting.md)

package/skills/aura3d-character-animation/references/stage-and-lighting.md

@@ -0,0 +1,31 @@
+# Character staging and lighting
+
+How to stage a rigged character so the animation itself is what a reviewer
+sees.
+
+## Stage
+
+| Setup | When | Look | Frame |
+| --- | --- | --- | --- |
+| Showcase plinth | clip demos, locomotion cycles | `character-showcase` | full body, 60–70% of frame height |
+| Walk path | locomotion proof | `outdoor-day` | character 25–40%, path leads forward |
+| Fight pair | combat clips | `arena-fight` | both fighters inside spotlight pools |
+| Interior | dialogue, visemes | `interior-warm` | head-and-torso, catchlights visible |
+
+## Lighting reads for motion
+
+- Rim light is what separates a moving silhouette from the backdrop — under
+  `night-city` or `arena-fight` the rim does more work than the key.
+- Ground contact shadow sells weight: feet must plant inside the shadow blob,
+  not beside it (floating feet = `weak-shadow` / grounding lint).
+- Golden-hour key gives long dramatic shadows for walk cycles; overcast gives
+  even exposure for cloth and morph inspection.
+- Keep the palette quiet — one accent (cloth or trim) plus neutral stage
+  colors, so motion draws the eye instead of props.
+
+## Camera for animation proof
+
+- `follow` rig for locomotion (side-on for gait, 3/4 for turn animations).
+- `orbit` for pose/morph inspection on a plinth.
+- Cut between a wide framing (whole body, 60–70%) and a close framing
+  (head/visemes, 40%) — never mid-body crops that amputate feet.

package/skills/aura3d-core/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: aura3d-core
+description: Orients an agent in Aura3D, maps three.js habits to `@aura3d/engine` APIs, routes visual work to art direction first, and sets claim labels. Use when starting any Aura3D task, scaffolding with `create-aura3d`, writing `createAuraApp` code, or before writing public examples, README text, or release claims.
+---
+
+# Aura3D core
+
+Aura3D is a TypeScript engine API, an asset CLI, templates, diagnostics, and a
+deploy checker. You are not writing three.js; `createAuraApp(...)` owns the
+renderer, scene graph, camera, and frame loop. Every scene gets a look — a
+preset that owns environment light, key shadow, fog, background and grade.
+Shared rules (claim labels, forbidden patterns, catalog-first, typed assets,
+paid generation, benchmark mode) live once in
+[references/boundaries.md](references/boundaries.md).
+
+## Look target
+
+Before any code, pick the look: read `aura3d-art-direction`'s recipe row for
+the genre, note the look id, the post preset and the palette accent. A scene
+without a look ships flat shading, void background and floating props.
+
+## Establish the contract
+
+1. Run `npx @aura3d/cli@latest --help` (or `pnpm exec aura3d --help` inside the
+   monorepo) and use only the commands and flags it prints.
+2. Check the installed engine version in `package.json`. Do not name an export
+   you have not seen in the installed package's type declarations.
+3. Read `src/aura-assets.ts` and `aura.assets.json` before writing scene code.
+   Asset keys come from that generated file, never from memory.
+4. Decide the mode. Benchmark mode means `npm install && npm run build`, then
+   stop (run the look-dev loop instead when `aura3d look capture` exists).
+
+## Procedure
+
+1. Pick the starting point in this order: a template (`npx create-aura3d@latest
+   <dir> --template <name>`), then `sceneKits.*`, then `prefabs.*`, and use
+   `primitives.*` last, for set dressing only.
+2. Add the look first — it supplies the sky/environment light, the key shadow,
+   fog, background and the post grade as one unit:
+
+   ```ts
+   import { createAuraApp, looks, model, scene } from "@aura3d/engine";
+   import { assets } from "./aura-assets";
+
+   createAuraApp("#app", {
+     scene: scene().add(looks.preset("product-studio")).add(model(assets.robot)),
+     ...looks.appOptions("product-studio")
+   });
+   ```
+
+3. Translate any three.js instinct with this table:
+
+   | three.js habit | Aura3D |
+   | --- | --- |
+   | `Mesh` plus a glTF loader | `model(assets.x)` (typed asset) |
+   | `new Scene()` | `scene()` |
+   | `PerspectiveCamera` | `camera.perspective(...)`, `camera.rigs.*` |
+   | `AmbientLight` | `lights.hemisphere(...)` or the look fill |
+   | `DirectionalLight`/`PointLight` | the look's key/rim slots, `lights.*` |
+   | `scene.environment` + PMREM | `environments.studio`/`hdri`, `world.biome` |
+   | `toneMapping`, exposure | `output.preset`, the look's grade |
+   | `setPixelRatio` | `quality: "auto"` via `looks.appOptions` |
+   | `castShadow` | `shadow: true` |
+   | `EffectComposer` passes | `output.preset` + `effects.*` |
+   | `AnimationMixer` | `AnimationController` |
+   | OrbitControls | `interactions.orbit(...)` |
+
+4. If the prompt names a real object, resolve it through the catalog before
+   writing model code (load `aura3d-assets`).
+5. Load the next skill from the routing table below. Load more than one when
+   the task spans them.
+
+## Routing table
+
+| Task signal | Load |
+| --- | --- |
+| Any visual task, screenshot looks flat/dark/empty, starting or finishing a scene | `aura3d-art-direction` (first) |
+| Prompt to scene or route, scene kits, `definePromptPlan` | `aura3d-scene-authoring` |
+| Named real object, user GLB, `assets search/resolve/add` | `aura3d-assets` |
+| Done, public, shippable, screenshots, claims, `check-deploy` | `aura3d-evidence-review` |
+| `mini-game`, `racing-starter`, `falling-blocks-starter`, `fighting-game`, `character-controller` | `aura3d-browser-game` |
+| Rigged humanoids, clips, locomotion, morphs, visemes | `aura3d-character-animation` |
+| `animation-studio` template, `aura3d animation scene`, episodes | `aura3d-animation-studio` |
+| Porting three.js code, migration templates (formerly `three-compat-*`) | `aura3d-threejs-migration` |
+| Materials, textures, HDRI, skies, water, weather | `aura3d-materials-environments` |
+| Flipbook VFX sheets, HUD icons, UI sprites | `aura3d-game-art` |
+| Restyling a finished mesh without touching geometry | `aura3d-retexture` |
+| Frame time, bundle size, KTX2, LOD, instancing | `aura3d-performance` |
+| No clean catalog candidate, Meshy generation or import | `meshy-cli` |
+
+A listed skill that is not installed in this project is a gap to report, not
+permission to improvise its procedure.
+
+## Look-dev loop
+
+Capture the route with `aura3d look capture`, judge each frame against the
+quality-bar rubric, fix the single highest-leverage issue (lint codes first),
+and repeat until every category reads 7+ or the loop exits flat. The full loop
+spec lives in `aura3d-art-direction`.
+
+## Stop and report
+
+- The CLI help does not list a command you need: stop, name the missing
+  command, and label the work `blocked`.
+- A required asset key is missing from `src/aura-assets.ts`: stop and fix the
+  import. Do not substitute a string id, URL, or primitive.
+- The claim you are about to write has no matching browser evidence: lower it
+  to `prototype` or `roadmap` per boundaries.md — claim labels are a one-line
+  link, not a restatement.
+- The task needs paid generation and no approval exists: stop at the dry run.
+- Benchmark mode: after `npm install && npm run build`, stop and report the
+  runner-owned launch and capture command.
+
+## References
+
+- [Shared boundaries](references/boundaries.md)
+- [Agent guide llms.txt](https://github.com/auraoneai/aura3d/blob/main/llms.txt)
+- [Claims and boundaries](https://github.com/auraoneai/aura3d/blob/main/docs/agents/claims-and-boundaries.md)
+- [No hackjob rules](https://github.com/auraoneai/aura3d/blob/main/docs/agents/no-hackjob-rules.md)
+- [Anti-hallucination rules](https://github.com/auraoneai/aura3d/blob/main/docs/agents/anti-hallucination-rules.md)
+- [Agent quickstart](https://aura3d.auraone.ai/docs/agent-quickstart.html)