@aura3d/cli 3.0.1 → 4.0.2

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,143 @@
+---
+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.
+6. Never assemble characters, athletes, enemies, vehicles, aircraft, trees, or
+   architectural landmarks out of `primitives.box`, `primitives.sphere`, or
+   `primitives.cylinder` (keep every silhouette, look, and style readable):
+   every hero subject, lighting, and shadow requires a real 3D GLB via
+   `model(assets.<name>, { targetMaxDimension, role })` from `src/aura-assets.ts`
+   (use `targetHeight` only for upright humanoids and `targetMaxDimension` for
+   vehicles, rackets, weapons, barriers, and wide props so aspect ratios and
+   silhouettes stay proportional). Drive rigged characters (`skins > 0`) with
+   `handle.setAnimation({ clip, loop: true, speed })` so limbs articulate under
+   the key light and shadow rather than sliding as rigid statues.
+7. For interactive and game routes, gate Frame 1 on `await app.ready()` before
+   fading `#boot-gate` so lighting, shadow, and GLB silhouettes are fully
+   mounted; default `autopilot` to `false` (manual control on Frame 1) unless
+   `?autoplay=1` / `?demo=1` is in the URL or the user clicks the HUD `Auto`
+   button (with `button.blur()` for clean framing). Pass
+   `qualityRebuild: { flags: ["game", "-compiler", "-post", "-vfxFog"] }` when
+   fast arcade contrast and frame pacing are required, decimate Meshy GLBs
+   (`<= 20,000` vertices, `<= 2 MB`, 16-bit indices, `<= 1024x1024` textures for
+   sharp reflection and palette), keep canonical `sha256-...` `hash` provenance
+   in `defineAuraAssets(...)` for clean look and silhouette, and mutate runtime
+   node handles (`app.nodes.require(...)`) instead of calling `app.setScene()`
+   on same-stage restarts so lighting, shadow, and postprocess grade never drop.
+
+## 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)

package/skills/aura3d-core/references/boundaries.md

@@ -0,0 +1,91 @@
+# Aura3D shared boundaries
+
+Every Aura3D skill links here instead of restating these rules. The full
+policy is in [claims and boundaries](https://github.com/auraoneai/aura3d/blob/main/docs/agents/claims-and-boundaries.md)
+and the [agent guide](https://github.com/auraoneai/aura3d/blob/main/llms.txt).
+
+## Claim labels
+
+Label every capability with exactly one of these:
+
+| Label | Meaning | Minimum evidence |
+| --- | --- | --- |
+| `createAuraApp` root safe API | A browser route imports only `@aura3d/engine` and mounts through `createAuraApp(...)`. | Build, route-health or equivalent diagnostics, typed asset manifest, browser screenshot, claim-specific pixel or runtime assertion. |
+| `production-runtime` | Exists in production-runtime packages or adapters, not necessarily root APIs. | Package or browser tests for that package, worded without implying root support. |
+| `rendering` package | Exists in the lower-level `@aura3d/rendering` package. | Package exports plus renderer unit or browser evidence, worded at package level. |
+| CLI asset pipeline | Asset search, add, resolve, validation, provenance, typegen, thumbnails, deploy checks. | CLI output, `aura.assets.json`, `src/aura-assets.ts`, license metadata, validation reports. |
+| Template-only scaffold | A template starts a project; it does not prove production capability. | Template generation smoke test and honest scaffold wording. |
+| `prototype` | Illustrates direction without release-quality evidence. | Prototype label and no flagship or production wording. |
+| `roadmap` | Planned, not implemented or not public. | Future tense and a linked issue or PRD item. |
+
+When evidence is missing, use `prototype` or `roadmap`. A route that loads,
+compiles, or produces a large screenshot is not proof.
+
+## Forbidden patterns
+
+- no raw string asset IDs, raw GLB/glTF URLs, `unsafeModelUrl(...)`, `three` imports, or `GLTFLoader` in public examples;
+- no primary character, vehicle, product, weapon, creature, world, or hero environment made only from primitives unless the route is explicitly abstract visualization;
+- no CSS/DOM particle implementation for examples claiming Aura3D particle rendering;
+- no WebGPU, PBR, postprocess, skinned animation, morph, or game-runtime claim without matching browser evidence;
+- no public showcase or README claim that exceeds detected capability, route-health evidence, or screenshots.
+
+Related prohibitions from the same sources: no hand-wired renderer, scene, or
+camera loop; no memorized or guessed model URLs (they are hallucinated
+provenance); no `createAuraApp()` call per frame; no CSS, DOM, or canvas
+overlay standing in for 3D effects, labels on models, or renderer output.
+
+## Catalog-first rule
+
+A prompt that names a real object resolves through the asset catalog before
+any model code: `npx @aura3d/cli@latest assets search "<descriptive phrase>"`,
+then `assets resolve "<phrase>" --name <key>` for an auto-pullable candidate.
+Auto-pullable means verified, redistributable (CC0 or CC-BY), and
+direct-download. Marketplace and deep-link results are user-handled: the user
+downloads and licenses them, then admits the file with `assets add`.
+Primitives are set dressing around a resolved asset, never the named subject.
+
+## Typed-asset rule
+
+1. Admit every file through the CLI (`assets add`, `assets resolve`, or
+   `assets import-meshy`) so it is hashed, inspected, and recorded in
+   `aura.assets.json`.
+2. Read the generated `src/aura-assets.ts` and import `assets` from
+   `./aura-assets`.
+3. Render with `model(assets.<key>)` or a kit such as
+   `sceneKits.productViewer(assets.<key>)`, using the exact generated key.
+4. Place with render-normalized helpers such as
+   `groundedRenderedAssetPlacement(...)`, not raw bounds math.
+
+If the key you need is missing, fix the import. Never fall back to a string
+id, a URL, a copied GLB, or a draft artifact path.
+
+## Paid generation controls (Meshy)
+
+- Catalog first. Generation is a fallback after a reported catalog rejection.
+- Run `meshy make ... --dry-run` and show the plan before any paid call.
+- Get explicit user approval for the displayed maximum, then pass
+  `--max-credits <approved>` on the paid command. Prices are never assumed.
+- Resume recorded task IDs. Do not repeat paid work that already succeeded.
+- Download immediately with `-o artifacts/meshy/<asset>/`. Provider retention
+  is short and signed URLs expire.
+- Keep credentials out of arguments, prompts, logs, commits, and output.
+- Admit through `assets import-meshy` with rights evidence. Import defaults to
+  `candidate` quality and never certifies release quality.
+
+## Benchmark mode versus normal mode
+
+| | Benchmark mode | Normal mode |
+| --- | --- | --- |
+| Starting point | `sceneKits.<name>()` first, `prefabs.*` if needed, primitives only for small additions | Template, kit, prefab, primitives last |
+| Commands | `npm install && npm run build`, then stop | `npm run build`, `npm run test`, asset validation, `check-deploy` |
+| Forbidden in the agent process | `npm run dev`, `npm run preview`, Playwright, screenshot capture, manual visual review | Nothing extra; heavy browser suites still run in CI or a remote runner |
+| Report | Build output and the runner-owned capture command | Evidence bundle and a claim label |
+
+A nonblank screenshot is not enough in either mode. The image must visibly
+match the prompt.
+
+## Evidence language
+
+Say `reported` for another agent's claim, `recorded` for a manifest or board
+entry, `verified` only for something you opened or ran (and state the scope),
+and `unknown` when you cannot establish current state.

package/skills/aura3d-evidence-review/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: aura3d-evidence-review
+description: Reviews Aura3D work before it is called done, public, or shippable by collecting route-health, screenshots, visual QA, asset release checks, and `check-deploy` output, then choosing a claim label through a capped critique loop. Use when finishing a route or template, writing README or showcase claims, comparing catalog versus Meshy candidates, capturing thumbnails or posters with `assets thumbnail`, or running `assets validate --release` and `check-deploy`.
+---
+
+# Aura3D evidence review
+
+A compiling route is not proof. This skill turns a finished change into an
+evidence bundle and one claim label — claim labels live here only; other
+skills link to them, never restate or reinterpret them. Label meanings and the
+benchmark exception are in [boundaries](../aura3d-core/references/boundaries.md).
+
+## Establish the contract
+
+1. Run `npx @aura3d/cli@latest --help` and confirm `assets validate`,
+   `assets thumbnail`, and `check-deploy` are listed.
+2. Read `package.json` scripts. Templates gate on `npm run build` and
+   `npm run test` (route-health and screenshot specs under `tests/`).
+3. Read `aura.assets.json` and `src/aura-assets.ts` so you know which typed
+   assets the route claims.
+4. Decide the mode. Benchmark mode: run `npm install && npm run build`, report
+   the output and the runner-owned capture command, then stop. Skip every
+   step below.
+
+## Procedure
+
+1. Pre-register the rubric before looking at output. Write 3 to 6 checks
+   taken from the prompt and the claim you intend to make, for example
+   "product centered and seated", "studio lighting visible", "metal and rubber
+   read differently". Add the role evidence from `aura3d-assets`.
+2. Run the local finite gates.
+
+   ```bash
+   npm run build
+   npx @aura3d/cli@latest assets validate --source --no-placeholders --require-license
+   npx @aura3d/cli@latest assets validate --release
+   npx @aura3d/cli@latest check-deploy --dist dist --release
+   ```
+
+   Read `failures` in the JSON, not only the exit code. Keep the reports.
+3. Run the browser gate (`npm run test`) in CI or a remote runner, not in the
+   local agent process. It writes route-health output and
+   `tests/reports/screenshot.png` plus pixel metrics. Capture desktop and
+   mobile viewports and retain the PNGs with hashes.
+4. For kit-based or prompt-plan scenes, collect structured evidence:
+   `collectAuraSceneEvidence(scene)` for bodies, cameras, clips, and asset
+   provenance; `app.diagnostics().look` (resolved look, expansion, lint
+   findings); and `compilePromptPlan(plan).report.repairHints`. Structural
+   name heuristics exist under `structuralQA.*` — they are diagnostics, never
+   acceptance evidence.
+5. Open the screenshots yourself and grade each rubric item `pass`, `warn`,
+   or `fail` in one batch. Every verdict cites a file: a PNG, a report field,
+   or a validation failure line.
+6. Critique loop, at most 6 rounds for visual findings (the look-dev loop).
+   For each `fail`, apply the highest-leverage fix — lint codes first, then
+   the lowest rubric category (a repair hint, the matching scene kit, a better
+   typed asset), rerun only the affected gates, and regrade. Do not change
+   labels, rubric items, or thresholds to make a round pass.
+7. Grade cinematic scenes on the ladder: L0 text only, L1 primitive sketch,
+   L2 asset-backed draft, L3 realtime cinematic scene, L4 production handoff.
+   Only L3 or better is public product proof.
+8. Bake-offs: when comparing a catalog candidate against a Meshy candidate,
+   use one brief, one rubric, one camera and lighting setup, and the same
+   gates for both. Report both verdict sets and pick on evidence, not source.
+9. Thumbnails and posters: run `npx @aura3d/cli@latest assets thumbnail` for
+   manifest thumbnails, and use the screenshot spec output as the poster.
+   Marketing previews use a static approved poster unless the live embed
+   passes the same gates as the route.
+10. Choose the label and write the claim at exactly that strength. Record
+    the prompt, typed asset keys, screenshot paths, route-health report,
+    verdicts, label, and next action.
+
+## What does not count
+
+- blank, cropped, tiny, or unreadable screenshots, or PNG size alone;
+- renderer-internal imports offered as root API proof;
+- CSS, DOM, or canvas stand-ins for particles, bloom, lighting, or labels;
+- stale route-health that names assets the source no longer uses;
+- `structuralQA`/`visualQA` name-heuristic output as acceptance evidence — it
+  diagnoses, it does not prove pixels;
+- an in-repo scorer as release proof (use a neutral human or opposite-vendor
+  model reviewer);
+- a report generated with missing evidence inputs, even when it exits 0.
+
+## Stop and report
+
+- A gate command is missing from the installed CLI or scripts: label the
+  work `blocked`, name the missing gate, and do not substitute a weaker check.
+- `assets validate --release` lists provenance failures: label `prototype`
+  until durable evidence exists.
+- After 6 critique rounds any rubric item still fails: stop, report the
+  failing items with their evidence, and label `prototype`.
+- Browser evidence could not be captured (no capture runner available): the
+  claim stays `prototype` AND the report names which look-dev loop step
+  failed (capture, judge, or lint); do not describe visual results you did
+  not see.
+- The claim needs WebGPU, PBR, postprocess, skinned animation, morph, or game
+  runtime proof and the pixels do not show it: remove the claim.
+
+## References
+
+- [Boundaries](../aura3d-core/references/boundaries.md)
+- [Verification](https://github.com/auraoneai/aura3d/blob/main/docs/agents/verification.md)
+- [Rendering proof required](https://github.com/auraoneai/aura3d/blob/main/docs/agents/rendering-proof-required.md)
+- [Cinematic scene quality](https://github.com/auraoneai/aura3d/blob/main/docs/agents/cinematic-scene-quality.md)
+- [Deployment](https://aura3d.auraone.ai/docs/deployment.html)

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

@@ -0,0 +1,118 @@
+---
+name: aura3d-game-art
+description: Produces 2D game art that a real Aura3D consumer uses: flipbook VFX sprite sheets for `effects.flipbook` (the `flipbook-sprite` effect with `spriteColumns` / `spriteRows`) and HUD icons or UI sprites for DOM overlays, each admitted as a typed texture asset. Use when a game template (`mini-game`, `racing-starter`, `falling-blocks-starter`, `fighting-game`) needs explosion, muzzle-flash, or hit VFX sheets, HUD icons, score or health sprites, or a style-consistent batch of UI art.
+---
+
+# Aura3D game art (flipbook VFX and HUD sprites)
+
+Only two consumers exist, so only two kinds of art are produced: flipbook
+sheets for the `flipbook-sprite` effect and icons for the DOM HUD. Tilesets
+are out of scope: no 2D tile runtime consumes them, so 3D levels come from
+`aura3d-browser-game` and `aura3d-assets`. Shared rules (claim labels, typed
+assets, CSS/DOM is UI only, benchmark mode) are in
+[../aura3d-core/references/boundaries.md](../aura3d-core/references/boundaries.md).
+
+## Look target
+
+Sprites live or die by the route's look: a flipbook explosion pops against a
+night-city grade and washes out under `product-studio` key light. Design the
+sheet against the genre recipe palette (see
+`aura3d-art-direction/references/look-recipes.md`) — emissive colors 3–5×
+background luminance read as glow through bloom; flat fills read as UI, not
+VFX. Keep alpha edges clean: the frame's fog and grade will expose halos the
+texture viewer hides.
+
+## Establish the contract
+
+1. Run `npx @aura3d/cli@latest --help` and read the `assets add` line.
+2. Read `src/aura-assets.ts` and `aura.assets.json`, and find the consumer
+   first: the `effects.flipbook(...)` call, or the HUD element in `src/main.ts`
+   (the `mini-game` HUD is a DOM `aside`). No consumer means no art.
+3. Know the flipbook state. `effects.flipbook` records validated sheet
+   geometry (`spriteColumns`, `spriteRows`, `frameRate`) but the root renderer
+   has no sprite-sheet sampler yet and submits no flipbook pass.
+   `renderer.diagnostics(scene)` reports the warning "flipbook-sprite is
+   recorded but withheld". Any route relying on it is `prototype` for that
+   effect.
+4. Benchmark mode: `npm install && npm run build`, then stop.
+
+## Procedure
+
+Flipbook VFX sheets:
+
+1. Fix the grid before producing art: columns, rows, frame count, and cell
+   size (for example 8 x 4 at 64 px per cell makes a 512 x 256 sheet with up
+   to 32 frames). Frames run left to right, top row first; that is the order
+   `resolveFlipbookUv(frame, columns, rows)` in `@aura3d/rendering` maps to
+   UVs.
+2. Author every frame in its own cell with the effect centered, a
+   transparent background, and no bleed across cell edges. Keep a frame
+   inventory (index to description) next to the file.
+3. Pre-flight the file with the bundled checker:
+
+   ```sh
+   node .agents/skills/aura3d-game-art/references/sheet-check.mjs ./art/explosion.png --columns 8 --rows 4 --frames 30
+   ```
+
+   (Adjust the path to wherever your agent client installed this skill.) It
+   fails when the width or height does not divide by the grid, when the frame
+   count exceeds the grid, or when the PNG has no alpha channel. It does not
+   inspect pixels, so review the transparent background and edges visually.
+4. Admit it as a typed texture with provenance:
+
+   ```sh
+   npx @aura3d/cli@latest assets add ./art/explosion.png --name explosionSheet --type texture --license CC0-1.0 --author "<author>" --quality candidate
+   npx @aura3d/cli@latest assets typegen
+   ```
+
+5. Declare the effect with the same grid:
+   `effects.flipbook({ spriteColumns: 8, spriteRows: 4, frameRate: 24 })`.
+   Mismatched or non-integer values throw a `RangeError` (fail loud); never
+   catch and ignore it. The effect has no texture slot today, so the sheet is
+   ready for the sampler but not yet drawn.
+
+HUD icons and UI sprites:
+
+6. Produce PNG or WebP icons (SVG is not an accepted asset format) at 1x and
+   2x, on a transparent background, sized to the HUD slot.
+7. Admit each with `assets add ... --type texture`, then reference the
+   typed URL in DOM markup, for example an `<img>` whose `src` is
+   `assets.hudHeart.url`, mounted with `ui.html(...)` or the template's HUD
+   element. Give every icon a text alternative (`alt`, or `aria-label` on the
+   control).
+8. DOM and CSS are allowed for UI only. Never use them for particles,
+   explosions, hit sparks, or anything claimed as rendered 3D VFX.
+
+Style-consistent batches:
+
+9. Write one style sheet before the batch: palette (hex values), outline
+   weight, light direction, and cell or icon size. Produce every item against
+   it, then review the batch side by side and redo outliers instead of
+   shipping a mixed set.
+10. Generated images (from an image skill outside Aura3D) are candidates:
+    keep them under `artifacts/`, admit them with `--quality candidate`, and
+    run the same checks.
+11. Normal mode: capture the HUD on desktop and mobile through `npm run test`
+    on CI or a remote worker, then hand claim wording to
+    `aura3d-evidence-review`.
+
+## Stop and report
+
+- The sheet fails `sheet-check.mjs`, or frames bleed across cells: fix the
+  sheet; do not change the grid in code to paper over it.
+- The route's VFX depends on flipbook pixels: label that effect `prototype`
+  and quote the withheld warning. Do not fake it with CSS, a DOM overlay, or
+  an animated `<img>` on top of the canvas.
+- Someone asks for a tileset: decline it and route level work to
+  `aura3d-browser-game`.
+- A file has no license or author: do not admit it.
+
+## References
+
+- [Flipbook UV math (`@aura3d/rendering`)](https://github.com/auraoneai/aura3d/blob/main/packages/rendering/src/SpriteFlipbook.ts)
+- [Flipbook and beam root builder test](https://github.com/auraoneai/aura3d/blob/main/tests/unit/engine/phase2-root-bridge.test.ts)
+- [Flipbook browser harness](https://github.com/auraoneai/aura3d/blob/main/tests/browser/d4-flipbook-beam-harness.ts)
+- [Mini-game template HUD](https://github.com/auraoneai/aura3d/blob/main/packages/create-aura3d/templates/mini-game/src/main.ts)
+- [Build a browser game guide](https://github.com/auraoneai/aura3d/blob/main/docs/guides/build-a-browser-game.md)
+- [Sheet checker](references/sheet-check.mjs)
+- [Sprite and flipbook palettes](references/sprite-palettes.md)