@aura3d/cli 4.0.7 → 4.1.0

package/skills/aura3d-browser-game/references/kits-and-hooks.md

@@ -0,0 +1,107 @@
+# Kits and hooks for browser games (4.1)
+
+Eleven ports and a tennis rebuild each copied the same shell code. The pieces below
+are now library surface: start from them instead of hand-rolling a HUD, an input
+store, a fixed-step loop, QA hooks or a synth. Every name here is verified against
+`docs/api/*.md` and the source; if an import fails, the installed version predates
+4.1 and you stop and report instead of re-creating the kit.
+
+## Pick the piece
+
+| Need | Use | Import |
+| --- | --- | --- |
+| Lifecycle, pause, results, DOM HUD, touch controls, juice, game sound | the game kit: `createGame`, `mountHud`, `createJuice`, `sfxUrl` | `@aura3d/engine/game` |
+| Deterministic fixed-step simulation and automated checks | `createFixedStepLoop`, `installQaHooks`, `readQaParams`, `createCountedRng` | `@aura3d/engine` |
+| Procedural sound cues, a mute key, ducking, step sequencer, engine drone | `createCueBank`, `createStepSequencer`, `createToneLoop`, `noteFrom`, `SCALES` | `@aura3d/engine/audio` |
+| Recorded takes (several hits in one sprite sheet) | `createSampleSlices` | `@aura3d/engine/audio` |
+| Rebindable keys with validation and persistence | `createBindingStore` (private `@aura3d/game` today; publishing through the game kit is the follow-up) | in-repo only |
+| Racket and ball sports | `game.racketSports()`: `ballFlight`, `scoring`, `athleteRig` | `@aura3d/engine` |
+| A black-frame safety net and a GPU diagnostics panel | `installSafetyNet` | `@aura3d/debug` |
+
+`createGame` from `@aura3d/engine` is a headless stub that logs `CREATE_GAME_STUB`.
+The real kit is the `@aura3d/engine/game` entry, and importing it turns the `game`
+quality-rebuild lane on by default. Do not add a `qualityRebuild` flag list by hand.
+
+## Deterministic replay and QA hooks
+
+A browser spec, a capture tool and the live smoke all drive the page through
+`window.__AURA_<NAME>__`. Install it once with `installQaHooks(name, options)` and
+keep the `state` hook plain data: never put engine objects in it.
+
+```ts
+import { createFixedStepLoop, installQaHooks, readQaParams } from "@aura3d/engine";
+
+const config = readQaParams({ seed: { type: "number", default: 1 }, manual: { type: "flag" } });
+const loop = createFixedStepLoop({
+  manual: config.manual,
+  isActive: () => ready,
+  step: () => sim.advance(readInput()),
+  render: () => draw()
+});
+const qa = installQaHooks("my-game", {
+  ready: () => ready,
+  seed: config.seed,
+  state: () => sim.snapshot(),
+  stepFrames: (n, input) => { for (let i = 0; i < n; i++) sim.advance(input); draw(); },
+  reset: (seed) => { sim = new Sim(seed ?? config.seed); draw(); },
+  app: () => app
+});
+loop.start();
+```
+
+Rules that came out of the ports:
+
+- Keep the simulation a pure fixed-timestep module with a seedable RNG
+  (`createCountedRng` exposes a draw counter so a replay can assert it). It never
+  touches the DOM, `Math.random`, `Date` or `performance.now`.
+- Record a scripted input run from the original or the reference build in two
+  independent sessions, derive the tolerance from their spread, and replay it as a
+  unit test. The Crayon ports match to 1e-6 or better; Aura Slam matches the
+  original engine bit for bit.
+- Anything that advances inside the render callback (autoplay, assist swings)
+  makes extra renders change the game: render once per step in manual mode.
+- Read `?manual=1`, `?warmup=`, `?seed=` through `readQaParams`, not by hand.
+
+## Production safety net
+
+For any route you ship, install the safety net and keep `?diag=1` working. It is
+opt-in: with `safety` unset the handle is inert and only parses the switches.
+
+```ts
+import { installSafetyNet } from "@aura3d/debug";
+
+const net = installSafetyNet({ safety: true, canvas, app });
+const { post, shadow, env, quality } = net.switches; // read before building the scene
+// after each drawn frame: net.sample(framesDrawn);
+```
+
+`?post=0 ?shadow=0 ?env=0 ?sky=0 ?aa=0 ?quality=low ?tm=aces ?heal=0 ?diag=1` are
+the switches; your game decides what each one changes. A canvas that stays black
+for about 23 samples reloads one rung down (`no-aa`, `no-post`, `aces-tone`,
+`no-env`, `no-shadow`, `low-quality`), logs `SAFETY_BLACK_FRAME`, and the next page
+logs `SAFETY_COMPAT_MODE`. Never replace this with a blanket `qualityRebuild` pin
+that disables post-processing for every player.
+
+## Sound
+
+`createCueBank({ cues, muteKey })` sits on the page's single `AudioContextManager`,
+so the one-owner rule holds: never write `new AudioContext(`. Call `bank.install()`
+for first-gesture unlock and the mute key, then `bank.play(id, { level })`. Bind
+`play` to simulation events, not to key presses, so replays sound the same.
+
+## Racket sports
+
+`game.racketSports().ballFlight(config)` is exact event-time flight (bounce, net,
+tape, boards) in court units with a different axis convention from the simple
+`stepBallPhysics` (z up, net at y = 0). `scoring` is a pure game, match and
+tiebreak state machine that defaults to tennis. `athleteRig` has `locomotion`,
+`applyLimbs` and `solveKnee`. Line calls, AI and costumes stay game code.
+
+## Converting an existing game
+
+Follow the order used for Aura Slam: capture a deterministic reference, write the
+typed contract, transcribe the pure simulation behind differential tests, port
+render, input, audio and UI behind that contract, then gate on replay, matching
+frames, a real-input play-through and a production-build check before swapping the
+route. See `docs/aura-slam/ARCHITECTURE.md` and
+`docs/workflows/crayon-game-reverse-engineering.md`.

package/skills/aura3d-core/SKILL.md

@@ -83,14 +83,14 @@ without a look ships flat shading, void background and floating props.
    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.
+   button (with `button.blur()` for clean framing), keep canonical `sha256-...`
+   `hash` provenance in `defineAuraAssets(...)` or `defineModelAssets(...)`, run
+   Meshy GLBs through `assets optimize --role` first, never pin post-processing or
+   the compiler off with a `qualityRebuild` list (use the safety net), and mutate
+   runtime node handles (`app.nodes.require(...)`) instead of calling
+   `app.setScene()` on same-stage restarts so lighting and grade never drop.
+   Build the HUD, replay hooks and sound from the kits:
+   [kits and hooks](../aura3d-browser-game/references/kits-and-hooks.md).
 
 ## Routing table
 
@@ -136,6 +136,7 @@ spec lives in `aura3d-art-direction`.
 ## References
 
 - [Shared boundaries](references/boundaries.md)
+- [Known pitfalls](references/pitfalls.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)

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

@@ -0,0 +1,62 @@
+# Known pitfalls (from porting eleven games and rebuilding four)
+
+Every item below cost a debugging session and is now either fixed in 4.1 or has a
+rule. Read it before you ship a route, and when a page looks wrong on a real device
+but passes in CI.
+
+## Rendering that passes in CI and fails on a player's GPU
+
+- **NaN from `pow` (Apple GPUs).** A custom shader's `pow` call with a base that
+  rounds slightly negative returns NaN on Apple silicon; bloom spreads it and the
+  page presents black while the engine reports hundreds of draw calls. Use the
+  `a3d_math` chunk helpers; 4.1 injects a total `pow` into `material.custom` and
+  drops non-finite samples in the output stage and bloom downsample.
+- **Software GL is not real-GPU proof.** SwiftShader passed pages that were black or
+  missing objects on an M-series Mac. Say "software GL" in reports; install the
+  safety net (`installSafetyNet`, `?diag=1`, black-frame self-heal) on shipped
+  routes and ask for a `?diag=1` screenshot from a real device.
+- **Custom shader colour.** Custom shaders write linear light that the output stage
+  sRGB-encodes and ACES tones down: use `#include <colorspace_decode>` and
+  `toneMapping: "none"` for authored colours. See `aura3d-materials-environments`.
+- **Directional shadow depth range.** With a narrow-fov camera far from the scene
+  (fov 15 at 40 m) one small caster used to darken a third of the frame; fixed in
+  4.1 by clamping receiver depth to [0, 1] in every directional sampler.
+- **Instanced textures.** `instances.mesh` and `batched.mesh` drew textured models
+  white before 4.1. A multi-geometry `batched.mesh` also needs the `tiers.batching`
+  flag for packed multi-draw; without it the engine now falls back to per-geometry
+  instancing.
+- **Empty instance arrays.** A zero-length `instances.*`, zero-position points or
+  lines, or a zero draw range used to throw on every render and blank the canvas.
+  They are now no-ops with `INSTANCES_EMPTY` / `GEOMETRY_EMPTY` diagnostics.
+
+## Assets and the production bridge
+
+- The production bridge refuses `model()` assets whose URL is http(s) or that lack a
+  valid `sha256` and provenance, and then draws nothing while the game state keeps
+  advancing. Declare models with `defineModelAssets`; check every asset URL returns
+  200 on the built site.
+- Never run `assets import-meshy`, `validate` or `typegen` from the repo root while
+  other work is open: they rewrite `aura.assets.json`, `src/aura-assets.ts` (a
+  100k-line diff) and `public/aura-assets/*`. Use `import-meshy --into <dir>
+  --prefix <game> --name <role>`.
+- Prefix every raw download with the game name: unprefixed `rocks.raw.glb` files
+  collide across games.
+- A rate-limited Meshy poll is not a failed task: record it `unconfirmed`, resume it
+  with `get`, and never create it again.
+- A large imported model set blows past upload and budget limits: run
+  `assets optimize --role` and keep a game's assets under about 25 MB.
+
+## Bundles, builds and tooling
+
+- Bare side-effect imports of self-registering modules are tree-shaken from
+  production bundles unless the root `sideEffects` allowlist covers them (4.1 covers
+  `./examples/**`, `./apps/**`, `./templates/**`). Test the production build, not the
+  dev server.
+- Never `git add -A` in a worktree whose `node_modules` is a symlink, and never run
+  `pnpm` there: it tries to remove the linked modules directory. Call the binaries
+  directly.
+- A deploy upload over 15,000 files fails: deploy from a clean export of a committed
+  commit, not the working tree.
+- A game that pins post-processing or the compiler off for everyone hides a bug and
+  makes the look worse. Fix the bug or let the safety net step down on the one
+  machine that breaks.

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

@@ -42,6 +42,18 @@ benchmark exception are in [boundaries](../aura3d-core/references/boundaries.md)
    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.
+   Games and simulations: drive the page through `installQaHooks`
+   (`window.__AURA_<NAME>__.stepFrames/state/replay`) and compare the `state` hook with a
+   recorded reference whose tolerance comes from two independent sessions.
+   Test the **production build**, not the dev server: bundling can drop modules
+   and the production bridge refuses unhashed model URLs, so assert a non-blank
+   canvas, `drawCalls > 0`, zero console errors and 200 for every asset URL. A
+   state hook that advances proves nothing about pixels (a page can run its
+   simulation under a black canvas).
+   Software GL (SwiftShader) proves correctness and draw-call counts only. Ship
+   the safety net (`installSafetyNet`, `?diag=1`, black-frame self-heal) on any
+   route you deploy, ask for a real-device `?diag=1` screenshot before claiming it
+   works on GPUs, and label software-only runs as such.
 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
@@ -59,7 +71,11 @@ benchmark exception are in [boundaries](../aura3d-core/references/boundaries.md)
 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,
+8. Parity and look claims against an original: report a seeded, randomised
+   blind A/B judge as identification accuracy against chance (50%) with trial
+   count and seed, and say it is a model's judgement, not a human's. "Same game
+   design" and "indistinguishable" are different claims; never say pixel parity
+   from histograms and a judge. 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
@@ -80,7 +96,9 @@ benchmark exception are in [boundaries](../aura3d-core/references/boundaries.md)
   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.
+- a report generated with missing evidence inputs, even when it exits 0;
+- software-GL frames offered as proof of real-GPU behaviour;
+- a live smoke that only checks the simulation state advanced.
 
 ## Stop and report
 
@@ -100,6 +118,8 @@ benchmark exception are in [boundaries](../aura3d-core/references/boundaries.md)
 ## References
 
 - [Boundaries](../aura3d-core/references/boundaries.md)
+- [QA and replay kit](https://github.com/auraoneai/aura3d/blob/main/docs/api/qa-kit.md)
+- [Runtime safety net](https://github.com/auraoneai/aura3d/blob/main/docs/api/safety-net.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)

package/skills/aura3d-materials-environments/SKILL.md

@@ -111,6 +111,12 @@ Checks (all steps):
 13. Screenshots (normal mode only) run through `npm run test` on CI or a remote
     worker. Hand the claim label to `aura3d-evidence-review`.
 
+14. Custom shaders (`material.custom`): write linear light, use
+    `#include <colorspace_decode>` with `toneMapping: "none"` for authored hex
+    colours, take hash/noise/sky/fog from the `a3d_*` chunks, and keep every
+    `pow`, `normalize`, `sqrt` and divide NaN-safe —
+    [custom shader chunks](references/custom-shader-chunks.md).
+
 ## Look-dev loop
 
 `aura3d look capture` → judge against the quality-bar rubric → `aura3d look
@@ -127,10 +133,12 @@ per round.
 - The HDRI is not 2:1, has a seam, or never reaches `iblPixelBacked`: report
   it and keep the built-in environment.
 - A PBR role is missing roughness or metalness: reject the set.
+- A custom-shader colour looks grey or the frame goes black on a real GPU: fix the colour contract or the NaN source; do not pin post off.
 - Any check above was not run: the route is `prototype`, not release.
 
 ## References
 
+- [Custom shader chunks (4.1)](references/custom-shader-chunks.md)
 - [Environment lighting](https://github.com/auraoneai/aura3d/blob/main/docs/rendering/environment-lighting.md)
 - [HDR, IBL, tone mapping, and color](https://github.com/auraoneai/aura3d/blob/main/docs/rendering/lighting-environment-color.md)
 - [Texture compression (KTX2/Basis)](https://github.com/auraoneai/aura3d/blob/main/docs/rendering/texture-compression.md)

package/skills/aura3d-materials-environments/references/custom-shader-chunks.md

@@ -0,0 +1,53 @@
+# Custom shaders: colour contract, chunks and NaN safety (4.1)
+
+`material.custom({ glsl: { vertex, fragment } })` is the escape hatch for effects the
+built-in materials do not cover (sky, water, energy, toon ramps). It has a colour
+contract and three failure modes that cost real time on real GPUs. Chunk names and
+signatures: `docs/api/glsl-chunks.md`.
+
+## Colour contract
+
+- A custom shader writes **linear light**. The output stage always sRGB-encodes it,
+  and the default ACES operator tones it down further, so a hex colour written
+  straight to `outColor` comes out greyer than authored (a day sky read grey for
+  exactly this reason). Post effects are not the cause: bloom, grade, vignette and
+  fxaa leave a custom shader's colour unchanged.
+- To show a hex colour as authored: `#include <colorspace_decode>`, wrap the colour
+  in `a3dSrgbToLinear`, and set `output: { toneMapping: "none" }` on the app.
+  `<colorspace_encode>` provides `a3dLinearToSrgb` for the other direction.
+- Any other tone-mapping operator still tone-maps custom colours; tune the exposure
+  instead of compensating in the shader.
+
+## Chunks
+
+`#include <a3d_math>`, `<a3d_noise>`, `<a3d_sky>`, `<a3d_fog>`, `<a3d_triplanar>`
+and `<a3d_toon>` are tested GLSL ES 3.00 helpers prefixed `a3d`. Use them instead of
+pasting hashes, fbm, sky gradients or fog into every shader. Precedence when names
+collide: built-in chunks, then these, then `registerShaderChunk`, then the material's
+`patch`. A material that includes chunks is GLSL-only: it has no WGSL twin.
+
+## NaN and Inf safety
+
+Apple GPUs return NaN where a software renderer returns a number. One NaN in a
+bright pixel is smeared across the whole frame by bloom, and the page presents black
+even though the engine reports hundreds of draw calls.
+
+- `pow` with a base that rounding makes slightly negative, `normalize` of a
+  zero vector, `sqrt` of a negative, `acos` outside [-1, 1] and a divide by zero
+  are the usual sources. Use `a3dSafeDiv`, `a3dSafeSqrt`, `a3dSafeAcos` and
+  `a3dFinite` from `<a3d_math>`.
+- The engine now injects a total `pow` into `material.custom` shaders that call
+  `pow`, and drops non-finite samples in the output stage and the bloom downsample.
+  Treat that as a net, not licence to skip clamps.
+- A shader that declares an attribute or uniform it never reads is reported as
+  `CUSTOM_ATTRIBUTE_UNUSED` or `CUSTOM_UNIFORM_UNUSED` and still draws.
+
+## Related fixes that change what you see
+
+- Directional shadows with a narrow-fov camera far from the scene (a tennis court at
+  fov 15) darkened up to a third of the frame before the 4.1 depth clamp. A game
+  that switched shadows off for that reason can switch them back on.
+- `instances.mesh` and `batched.mesh` apply texture maps since 4.1; before that a
+  textured model drawn through them was white.
+- `model()` rejects http(s) URLs and models without a valid `sha256` and provenance:
+  the scene then draws nothing. Declare models with `defineModelAssets`.

package/skills/aura3d-performance/SKILL.md

@@ -58,7 +58,20 @@ manual quality override invalidates every measurement that follows.
    `instances.capsule`, `instances.torus`) node with a transform list. Advanced
    PBR extensions can fall back to expanded draws, so confirm native instanced
    submissions in diagnostics before claiming one draw.
-4. Distant detail: use `distanceLod` with increasing `maxDistance` levels and a
+   Repeated `model()` nodes of one asset share decoded textures (4.1) but still
+   upload geometry per node: use `instances.model` for repeats. `instances.mesh` and
+   `batched.mesh` apply texture maps since 4.1; older builds drew them white.
+   An empty instance array is a no-op with an `INSTANCES_EMPTY` diagnostic, not a
+   crash, so plan for zero placements instead of special-casing them.
+4. Scattered props (trees, rocks, lamps, houses): plan placements with
+   `scatterAlongPath` or `scatterInArea` (seeded, exclusion zones, `minDistance`,
+   slope and height filters), split them by distance with `splitScatterByDistance`
+   (detailed model near, cheap instance far), and feed `scatterTransforms` into
+   `instances.model` / `instances.*`. Bake static sets that share a material with
+   `mergeStatic` / `mergeStaticByKey` (one draw per material). Turn off shadow
+   casting on small props and actors: the ports went from 1,249, 1,980 and 677
+   draw calls to 133, about 100 and 137 this way, with the look unchanged.
+   Distant detail: use `distanceLod` with increasing `maxDistance` levels and a
    `hysteresis` band so the camera cannot flap between levels.
 5. Large scenes: rely on CPU frustum culling plus the static-bounds BVH. Give
    custom geometry explicit bounds via `geometry.custom`. There is no GPU
@@ -86,6 +99,8 @@ manual quality override invalidates every measurement that follows.
 - A performance change alters the rendered scene: rerun screenshot review
   through `aura3d-evidence-review` before shipping.
 - GPU timing is unavailable or noisy on the device: say so; do not fill in.
+- Numbers came from a software renderer (SwiftShader): they prove draw-call
+  counts and correctness, not frame rate. Say "software GL" and ask for a real GPU run.
 
 ## References
 
@@ -94,4 +109,5 @@ manual quality override invalidates every measurement that follows.
 - [Bundle sizes](https://github.com/auraoneai/aura3d/blob/main/BUNDLE_SIZES.md)
 - [Texture compression](https://github.com/auraoneai/aura3d/blob/main/docs/rendering/texture-compression.md)
 - [Geometry, instancing, LOD, text](https://github.com/auraoneai/aura3d/blob/main/docs/rendering/geometry-instancing-lod-text.md)
+- [Scatter and merge](https://github.com/auraoneai/aura3d/blob/main/docs/api/scatter-merge.md)
 - [Deployment](https://aura3d.auraone.ai/docs/deployment.html)

package/skills/llms.txt

@@ -8,12 +8,12 @@ Aura3D is the AI-native TypeScript 3D SDK for browser 3D apps, interactive websi
 
 - Product: AI-native TypeScript 3D SDK for browser 3D apps, interactive websites, and prompt-to-code scene kits
 - Website: https://aura3d.auraone.ai
-- Current release: Aura3D 4.0.7 (per the repo manifest — the same source the build's version guard uses)
+- Current release: Aura3D 4.1.0 (per the repo manifest — the same source the build's version guard uses)
 - Docs: https://aura3d.auraone.ai/docs/api.html
 - Showcase game: https://aura3d.auraone.ai/showcase/aura-clash/
 - Sitemap: https://aura3d.auraone.ai/sitemap.xml
 - Crawl policy: https://aura3d.auraone.ai/robots.txt (public content allow-all; build internals and source maps disallowed)
-- Last updated: 2026-10-20
+- Last updated: 2026-10-23
 
 ## Pages
 
@@ -31,8 +31,8 @@ Aura3D is the AI-native TypeScript 3D SDK for browser 3D apps, interactive websi
 - [Aura3D Guide for Claude-Assisted 3D Apps](https://aura3d.auraone.ai/docs/claude.html): Use Claude with Aura3D to generate TypeScript browser 3D scenes from scene kits, primitives, typed GLB/glTF assets, and Vite templates.
 - [Aura3D Guide for Cursor AI 3D Development](https://aura3d.auraone.ai/docs/cursor.html): Use Cursor with Aura3D projects to edit TypeScript browser 3D scenes, Vite templates, typed GLB/glTF assets, scene kits, and prompt-to-3D workflows.
 - [Aura3D Evidence and Release Gates](https://aura3d.auraone.ai/docs/evidence.html): How Aura3D binds public package, asset, browser, game, visual, and deployment claims to retained evidence.
-- [Aura3D Claims, Limits, and Release Scope](https://aura3d.auraone.ai/docs/claims.html): Current Aura3D 4.0.7 claim boundaries for the root API, game presentations, assets, rendering, WebGPU, and diagnostics.
-- [Aura3D 4.0.7 vs. Raw Three.js — Open-Source TypeScript 3D Engine](https://aura3d.auraone.ai/docs/aura3d-vs-threejs.html): Stop assembling 14 fragile npm packages to render a 3D scene. Compare Aura3D 4.0.7 (@aura3d/engine@4.0.7) against raw Three.js across architecture, asset type safety, WebGPU compute, physics, and 18-line scene boot.
+- [Aura3D Claims, Limits, and Release Scope](https://aura3d.auraone.ai/docs/claims.html): Current Aura3D 4.1.0 claim boundaries for the root API, game presentations, assets, rendering, WebGPU, and diagnostics.
+- [Aura3D 4.1.0 vs. Raw Three.js — Open-Source TypeScript 3D Engine](https://aura3d.auraone.ai/docs/aura3d-vs-threejs.html): Stop assembling 14 fragile npm packages to render a 3D scene. Compare Aura3D 4.1.0 (@aura3d/engine@4.1.0) against raw Three.js across architecture, asset type safety, WebGPU compute, physics, and 18-line scene boot.
 - [Aura Clash: Aura3D Browser Fighting-Game Runtime Proof](https://aura3d.auraone.ai/docs/aura-clash-showcase.html): Aura Clash Arena is the Aura3D browser fighting-game development showcase: typed GLB runtime evidence, arena visuals, gameplay UI, accessibility controls, evidence routes, and release gates.
 
 ### Showcase
@@ -45,13 +45,13 @@ Aura3D is the AI-native TypeScript 3D SDK for browser 3D apps, interactive websi
 - [Aura3D Damaged Helmet PBR Detail: Typed GLB Asset Viewer Example](https://aura3d.auraone.ai/apps/wow-damaged-helmet-pbr-detail/)
 - [Aura3D Examples and Games](https://aura3d.auraone.ai/apps/showcase-index/)
 - [Aura Slam 3D — Championship 3D Tennis on Aura3D](https://aura3d.auraone.ai/apps/showcase-top-tennis/)
-- [Aura Slam 3D — Championship 3D Tennis (Second Edition) on Aura3D](https://aura3d.auraone.ai/apps/showcase-top-tennis-v2/)
+- [Aura Slam 3D — Championship 3D Tennis (V2) on Aura3D](https://aura3d.auraone.ai/apps/showcase-top-tennis-v2/)
 - [Apex Overdrive — 3D Sky-Lane Highway Racer on Aura3D](https://aura3d.auraone.ai/apps/showcase-roadster-rush/)
-- [Apex Overdrive — 3D Sky-Lane Highway Racer (Second Edition) on Aura3D](https://aura3d.auraone.ai/apps/showcase-roadster-rush-v2/)
+- [Apex Overdrive — 3D Sky-Lane Highway Racer (V2) on Aura3D](https://aura3d.auraone.ai/apps/showcase-roadster-rush-v2/)
 - [THERMAL DRIFT — High-Velocity Combat Drone Racer · Aura3D Showcase](https://aura3d.auraone.ai/apps/showcase-heatsink/)
-- [THERMAL DRIFT — High-Velocity Combat Drone Racer (Second Edition) · Aura3D Showcase](https://aura3d.auraone.ai/apps/showcase-heatsink-v2/)
-- [Grid Dispatch — San Francisco Robotaxi & Autonomous Fleet Showcase (Aura3D 4.0.7)](https://aura3d.auraone.ai/apps/showcase-teleoperator/)
-- [Grid Dispatch — San Francisco Robotaxi & Autonomous Fleet Showcase (Second Edition, Aura3D 4.0.7)](https://aura3d.auraone.ai/apps/showcase-teleoperator-v2/)
+- [THERMAL DRIFT — High-Velocity Combat Drone Racer (V2) · Aura3D Showcase](https://aura3d.auraone.ai/apps/showcase-heatsink-v2/)
+- [Grid Dispatch — San Francisco Robotaxi & Autonomous Fleet Showcase (Aura3D 4.0.2)](https://aura3d.auraone.ai/apps/showcase-teleoperator/)
+- [Grid Dispatch — San Francisco Robotaxi & Autonomous Fleet Showcase (V2, Aura3D 4.0.2)](https://aura3d.auraone.ai/apps/showcase-teleoperator-v2/)
 - [IRON CROWN — 2.5D Arena Fighter · Aura3D Showcase](https://aura3d.auraone.ai/apps/showcase-iron-crown/)
 - [PIP'S BIG LEAP — 3D Mascot Platformer · Aura3D Showcase](https://aura3d.auraone.ai/apps/showcase-pips-big-leap/)
 - [Aura Hoops 3D — Streetball Worldwide · Aura3D Showcase](https://aura3d.auraone.ai/apps/showcase-aura-hoops-3d/): Aura Hoops 3D: NBA-Jam-pace 3v3 streetball on the Aura3D engine — check-ball, shot meter, Jam Meter dunk packages, six world courts, Dunk Lab, Handles Lab and a 32-team Street Tour.
@@ -63,6 +63,17 @@ Aura3D is the AI-native TypeScript 3D SDK for browser 3D apps, interactive websi
 - [Aura3D - Slingshot Siege](https://aura3d.auraone.ai/apps/showcase-slingshot-siege/): Aura3D Slingshot Siege prototype: a Saturday-morning-cartoon physics destruction sandbox. Pull the pouch, lob five ammo types, squash every gull, topple every tower.
 - [Dot Dash 3D — Neon Maze Chase · Aura3D Showcase](https://aura3d.auraone.ai/apps/showcase-dot-dash-3d/): Aura3D Dot Dash 3D showcase, a neon maze-chase arcade game: dash through six glowing circuits gobbling light-dots while four Specters hunt with distinct AI personalities.
 - [Cross Hop — Aura3D Endless Lane Hopper](https://aura3d.auraone.ai/apps/showcase-cross-hop/): Aura3D Cross Hop showcase, an endless lane-hopping game: dodge cars, trams, trains, rivers and lava across 6 remixed themes, rescue critters, chase the high score.
+- [Strange Orbit — Aura3D port of the mechanics](https://aura3d.auraone.ai/apps/showcase-strange-orbit-port/): Moon-rim bike racing: a seven-lap cup race against five rivals with route splits, checkpoints and a rescue budget, rebuilt from a recorded run of the original. Simulation parity verified against the original's recorded seven-lap run; lit sci-fi look with audio and a difficulty selector; bikes, riders and rim props are generated models (riders are single rigid meshes); no career or garage. Independent Aura3D reconstruction; not affiliated with the original.
+- [Splat Rush — Aura3D port of the mechanics](https://aura3d.auraone.ai/apps/showcase-splat-rush-port/): Colour-gate ball runner with power-ups, colour switching and a splatter game-over; every simulation field matches the original's recorded run. Audio, effects and keyboard play added; backdrop islands and pickups are generated models; platform SDKs are not ported; a blind model judge could still tell the port from the original. Independent Aura3D reconstruction; not affiliated with the original.
+- [Serpentine Sky Run — Aura3D port of the mechanics](https://aura3d.auraone.ai/apps/showcase-serpentine-sky-run-port/): Endless runner on a serpentine sky road: eight stages with boost rungs, roll sections and traffic hazards; the outbound run matches a recorded reference. Outbound run only (no hell run or road home); title, pause, results and audio included; the runner, gate and hazards are generated models; a blind model judge could still tell the port from the original. Independent Aura3D reconstruction; not affiliated with the original.
+- [Drift & Deliver — Aura3D port of the mechanics](https://aura3d.auraone.ai/apps/showcase-drift-and-deliver-port/): Arcade drift driving through a block city: coin pickups, 84 traffic cars, bloom and a chase camera; all four recorded scenarios reproduce exactly. Headlight beam renders; the player car, traffic and street furniture are generated models (pedestrians are static); collision response untested; a blind model judge could still tell the port from the original. Independent Aura3D reconstruction; not affiliated with the original.
+- [HEATSINK — Aura3D port of the mechanics](https://aura3d.auraone.ai/apps/showcase-heatsink-port/): Anti-gravity time trial on the Vesper course with boost pads, pickups, barrels and heat management; the state replay matches the original within 1e-6. Simulation port only: the drone, pylons and scenery are generated models and the art is still visibly different from the original (a blind model judge picked the original in 35 of 48 trials and rated 40 of 48 pairs as the same game design); Time Trial only, no AI or audio. Independent Aura3D reconstruction; not affiliated with the original.
+- [Ninja Runner — Aura3D port of the mechanics](https://aura3d.auraone.ai/apps/showcase-ninja-runner-port/): Lane-running combat with twelve skinned clones, form changes and a full course win; the recorded 106-second run replays event for event. four generated rigged characters plus building and prop models; enemies share two bodies; sun shadows are off; a blind model judge could still tell the port from the original. Independent Aura3D reconstruction; not affiliated with the original.
+- [Last Train to the Sea — Aura3D port of the mechanics](https://aura3d.auraone.ai/apps/showcase-last-train-port/): Train-driving loop with day and night, passengers, fares and tips; loop length and score match the original's recorded loop and memory stays flat over three loops. No garage or level select; the tram, townhouses, landmarks and passengers are generated models (passengers stand rather than sit); a blind model judge could still tell the port from the original. Independent Aura3D reconstruction; not affiliated with the original.
+- [Roadster Hours — Aura3D port of the mechanics](https://aura3d.auraone.ai/apps/showcase-roadster-hours-port/): Coastal drive with 92 vehicles in one batched mesh; the recorded 48-second run replays exactly. Coastal look with sky, ocean and a lit road; vehicles and scenery are generated models and there are no shadows; a blind model judge could still tell the port from the original. Independent Aura3D reconstruction; not affiliated with the original.
+- [Where the Wind Wanders — Aura3D port of the mechanics](https://aura3d.auraone.ai/apps/showcase-where-the-wind-wanders-port/): Meadow walk collecting three letters and ringing a bell; the walking trajectory matches the original within 1e-9 over 2,098 steps. Includes the boat epilogue, journal and audio; the traveller, cottages and trees are generated models; a blind model judge could still tell the port from the original. Independent Aura3D reconstruction; not affiliated with the original.
+- [Silt & Signal — Aura3D port of the mechanics](https://aura3d.auraone.ai/apps/showcase-silt-and-signal-port/): Free-ride flying over a silt world; three recorded rides reproduce the original's simulation state to 1e-9. Chapter 0 has real colliders; the rider, ring beacons and landmarks are generated models; later chapters are generated hills, with no NPCs or minimap; a blind model judge could still tell the port from the original. Independent Aura3D reconstruction; not affiliated with the original.
+- [Cloud Runner — Aura3D port of the mechanics](https://aura3d.auraone.ai/apps/showcase-cloud-runner-port/): Obstacle runner on a cloud: the first chapter's run model replays the original's recorded run to 1e-12. Includes creatures, boulders, the duel and finale, with audio; the hero, creatures and scenery are generated models; a blind model judge could still tell the port from the original. Independent Aura3D reconstruction; not affiliated with the original.
 
 ## Notes
 
@@ -71,7 +82,7 @@ Aura3D is the AI-native TypeScript 3D SDK for browser 3D apps, interactive websi
 <!-- agent-guide: everything below this marker is the long-form agent guide; gen-seo.mjs preserves it verbatim -->
 Aura3D agent guide — a typed scene API for building real 3D apps: scenes, looks,
 lighting, materials, typed assets, camera rigs, gameFeel, SDF text, decals, rigid bodies, and gameplay through
-`@aura3d/engine` plus the `@aura3d/cli` toolchain. Current release: Aura3D 4.0.7 (succeeding 4.0.1).
+`@aura3d/engine` plus the `@aura3d/cli` toolchain. Current release: see Facts above (4.1 adds the game kit, QA replay hooks, safety net, audio synth, model loader, GLSL chunks, scatter/merge, racket-sports kits and CLI asset tools).
 
 Hello world: every scene gets a look first.
 
@@ -184,23 +195,32 @@ Mandatory 3D game & scene anti-failure guardrails:
    - Gate Frame 1 on `await app.ready()` before fading out `#boot-gate` (`opacity: 0; pointer-events: none` then remove) and starting the gameplay simulation loop so lighting, shadow, and GLB silhouettes never pop in mid-frame.
    - Default `autopilot` / AI demo mode to `false` (immediate manual control on Frame 1 once `#boot-gate` clears); enable AI autopilot only when `?autoplay=1` or `?demo=1` is present in the URL or when the user clicks the HUD `Auto` toggle button, and yield back to manual control on keyboard (`keydown`), pointer, touch, or gamepad input.
    - Keep mode, stage, camera, `Auto`, and roster selectors in a compact, non-blocking top HUD bar that preserves camera framing, and always call `button.blur()` after button clicks so `Space` or `Enter` gameplay keys never re-trigger focused HUD buttons.
-3. Always decimate and compress Meshy 3D GLBs before admission (`<= 20,000` vertices, `<= 2 MB`, 16-bit indices):
+3. Always optimize Meshy 3D GLBs before admission (`aura3d assets optimize --file in.glb --out out.glb --role <role>`):
    - Raw Meshy exports often contain `200,000–1,750,000` vertices and `20–65 MB` of uncompressed 4K PNG textures, which stall main-thread glTF parsing and exhaust GPU memory when multiple models load in one scene.
-   - Every generated Meshy GLB must be simplified (`MeshoptSimplifier` to `<= 20,000` vertices for props/vehicles, 16-bit `Uint16Array` indices, de-interleaved `byteStride === 0` buffers) and have its textures compressed to `<= 1024x1024` (`~0.5–2.0 MB` per GLB) before being admitted into `public/aura-assets/` so PBR palette, contrast, and reflection stay responsive.
+   - Role budgets: prop 6,000, background 15,000, character 30,000, hero or vehicle 40,000 vertices; textures capped at 1024 to 2048 px; 16-bit indices; keep a game's assets near 25 MB. Admit in an isolated project (`assets import-meshy <dir> --into <assets-dir> --prefix <game> --name <role>`), never from the repo root while other work is open.
 4. Always use canonical typed asset manifest refs (`hash` required):
    - The production glTF bridge requires `createAssetProvenance(node.asset).source === "typed-aura-assets-manifest"`, which requires a valid 64-character `sha256-...` `hash` and `public/aura-assets/...` provenance from `aura.assets.json` / `src/aura-assets.ts` so the rendered look and silhouette load cleanly.
    - Never omit `hash` in custom `defineAssets(...)` declarations and never place unhashed duplicate GLBs in route-local `apps/<route>/public/aura-assets/` that collide with root `public/aura-assets/`.
 5. Mutate node handles instead of calling `app.setScene()` on every restart:
    - Do not call `app.setScene()` when restarting a round, hole, or bout on the same stage/world; tearing down and remounting the scene disposes live GPU resources, breaks lighting and postprocess continuity, and aborts in-flight GLB loads. Track a scene signature (`stageId` / `worldId`) and reset positions, visibility, and animations through runtime node handles (`app.nodes.require(...)`).
-6. Prevent fog whitewash, overexposure, and instanced emissive blowout (`qualityRebuild.flags`):
-   - Pass `{ fogDensityScale: 0, exposureEv: -0.1 }` to `looks.preset(...)` and include `qualityRebuild: { flags: ["game", "-compiler", "-post", "-vfxFog"] }` alongside `...looks.appOptions(...)` on fast action/arcade routes unless distance haze is explicitly desired (`looks.preset` emits `density: 24 / far`, which under `A3D_QR_VFX_FOG` creates an `exp2` haze wall at 20–30m). Never stack duplicate high-intensity `lights.directional`, `lights.ambient`, or `lights.hemisphere` nodes on top of `looks.preset(...)`.
-   - Never set `emissive: "#ffffff"` with high `emissiveIntensity` on an instanced pool material (`instances.box` / `primitives.box({ instances })`): per-instance `instanceColors` multiply `u_baseColor`, not `u_emissiveColor`, so white emissive blows out every instance to pure white regardless of instance color. Always pass an explicit `material: material.pbr({ color })` on untextured preview GLBs.
+6. Prevent fog whitewash, overexposure, and instanced emissive blowout:
+   - If a fast route whitewashes, pass `{ fogDensityScale: 0, exposureEv: -0.1 }` to `looks.preset(...)` for that route. Never pin post-processing, the compiler or fog off for every player with a `qualityRebuild.flags` list: it hides bugs and flattens the look. Install `installSafetyNet` from `@aura3d/debug` so a machine that renders black steps down one rung on its own and `?diag=1` shows the GPU, limits and shader failures.
+   - Never set `emissive: "#ffffff"` with high `emissiveIntensity` on an instanced pool material (`instances.box` / `primitives.box({ instances })`): per-instance `instanceColors` multiply `u_baseColor`, not `u_emissiveColor`.
 7. Ground `model()` feet on platform top surfaces (`y + sy / 2`) & wind custom meshes CCW:
    - `model(asset, { targetHeight })` normalizes the GLB with `minY = 0` (feet at `position[1]`), whereas `primitives.box` and `primitives.cylinder` (`instances.box` / `instances.cylinder`) are centered on `[-0.5..+0.5]` so a platform at `(y, sy)` has its top surface at `y + sy / 2`. Always place grounded characters and vehicles at `platform.y + platform.sy / 2` so they never sink into logs, pads, or road lanes. Wind custom `primitives.mesh` triangles CCW when viewed from `+Y`.
 8. Enforce full-viewport `100vw × 100vh` canvas, deep ground apron, and pushbox separation:
    - Size `html, body, #app, canvas` to `100vw × 100vh` (`position: fixed; inset: 0; overflow: hidden`) and extend the 3D ground/stage apron deep enough in `+Z`/`-Z` under the camera frustum so the bottom third of the viewport never shows a black clear-color void. Disable `collision: true` on `camera.rigs.shoulder` when the target character has attached child runtime nodes, and enforce `>= 1.4m` fighter pushbox separation (`|x| >= 1.8m` at spawn).
 
 
+Aura3D 4.1 kits (build the shell from these, do not hand-roll it):
+
+- `@aura3d/engine/game`: `createGame` (lifecycle, pause, results, DOM HUD, touch, juice, game sound); the root `createGame` is a headless stub.
+- `@aura3d/engine`: `createFixedStepLoop`, `installQaHooks` (`window.__AURA_<NAME>__`), `readQaParams`, `createCountedRng` for deterministic replay and automated checks; `defineModelAssets` for hashed same-origin models with a `?models=0` procedural fallback; `scatterAlongPath`, `scatterInArea`, `splitScatterByDistance`, `mergeStatic` for draw-call budgets; `game.racketSports()` with `ballFlight`, `scoring`, `athleteRig`.
+- `@aura3d/engine/audio`: `createCueBank`, `createStepSequencer`, `createToneLoop`, `createSampleSlices` on the single `AudioContextManager` (never `new AudioContext(`).
+- `@aura3d/debug`: `installSafetyNet` (`?diag=1`, quality switches `?post=0 ?shadow=0 ?env=0 ?sky=0 ?quality=low`, black-frame self-heal).
+- `material.custom` shaders: `#include <a3d_math>`, `<a3d_noise>`, `<a3d_sky>`, `<a3d_fog>`, `<a3d_triplanar>`, `<a3d_toon>`, `<colorspace_decode>`; custom shaders write linear light, so use `a3dSrgbToLinear` with `toneMapping: "none"` for authored colours, and keep `pow`, `normalize`, `sqrt` and divides NaN-safe (Apple GPUs return NaN where software renderers do not).
+- Production checks that CI missed: the bridge refuses http(s) or unhashed model URLs and then draws nothing; instanced and batched meshes honour texture maps; empty instance arrays are no-ops; software-GL passes are not real-GPU proof. Docs: `docs/api/game-kit.md`, `qa-kit.md`, `safety-net.md`, `audio-synth.md`, `model-loader.md`, `glsl-chunks.md`, `scatter-merge.md`, `cli-asset-tools.md`; pitfalls: `aura3d-core/references/pitfalls.md`.
+
 Claims: use every feature freely. Claim only what a judged capture shows.
 
 - Label every capability as one of: `createAuraApp` root safe API,
@@ -229,3 +249,5 @@ label the result `prototype`.
 
 
 
+
+

package/skills/meshy-cli/SKILL.md

@@ -80,11 +80,9 @@ when a catalog candidate already passes the rubric.
    often contain `200,000–1,750,000` vertices and `20–65 MB` of uncompressed 4K
    PNG textures, which stall main-thread glTF parsing and exhaust GPU memory
    when multiple models share one scene look and lighting setup. Before
-   admission into `public/aura-assets/`, always simplify every generated Meshy
-   GLB (`MeshoptSimplifier` to `<= 20,000` vertices for props/vehicles, 16-bit
-   `Uint16Array` indices, de-interleaved `byteStride === 0` buffers) and
-   compress textures to `<= 1024x1024` (`~0.5–2.0 MB` per GLB) so silhouettes,
-   shadows, palette, and PBR reflections load fast.
+   admission run `assets optimize --file in.glb --out out.glb --role prop` on
+   every generated GLB (role vertex budgets, textures `<= 1024–2048` px,
+   float32 geometry kept; see [asset-tooling](references/asset-tooling.md)).
 7. Admit the local output with rights evidence.
 
    ```bash
@@ -93,6 +91,10 @@ when a catalog candidate already passes the rubric.
      --profile prop --role prop --thumbnail artifacts/meshy/arena-relic/thumbnail.png
    ```
 
+   Use `--into <game-assets> --prefix <game> --name <role>` for isolated import
+   (default in the monorepo; no shared root manifests are written). Merge each
+   `animate` clip into one rig with `assets merge-clips`, and reserve every paid
+   call with `meshy ledger`: see [asset-tooling](references/asset-tooling.md).
    Use `--file` when the run has several GLBs. Import defaults to
    `--quality candidate` and refuses release certification. Read the
    admission `blockers` and `unproven` lists; `routeReady: false` is a result

package/skills/meshy-cli/references/asset-tooling.md

@@ -0,0 +1,72 @@
+# Asset tooling for Meshy work
+
+Detail for the `meshy-cli` skill: optimise, merge clips, admit in isolation, and keep a credit ledger.
+None of these commands call Meshy or handle a credential; they work on files you already downloaded.
+
+## Optimise a download
+
+```bash
+npx @aura3d/cli@latest assets optimize --file artifacts/meshy/drift-lamp/model.glb \
+  --out artifacts/meshy/drift-lamp/model.opt.glb --role prop
+```
+
+Role budgets (vertices, texture px): `hero` and `vehicle` 40,000 / 2048, `character` 30,000 / 2048,
+`background` 15,000 / 1024, `prop` 6,000 / 1024. Override with `--max-verts N` and `--tex N`
+(max 4096), skip simplification with `--no-simplify`. The command dedups, welds, simplifies to the
+budget (locking borders on skinned meshes), prunes, downsizes textures (colour and ORM to jpeg,
+normal to png) and never overwrites its input. Geometry stays float32 unless you pass `--meshopt`:
+quantisation moves scale into a node transform and skews the grounding and bounds checks that
+`import-meshy` runs, so use it only for static background props you will not measure.
+The glTF-Transform stack resolves from your project; a missing package is reported with the install command.
+
+## Merge animation clips into one rig
+
+Each `animate` task returns its own GLB with one clip on the rig's skeleton. Merge them by node name:
+
+```bash
+npx @aura3d/cli@latest assets merge-clips --base artifacts/meshy/hero-rig/ \
+  --out artifacts/meshy/hero/model.glb \
+  run=artifacts/meshy/hero-run/ idle=artifacts/meshy/hero-idle/ jump=artifacts/meshy/hero-jump/
+```
+
+`--base` and each clip accept a GLB or a Meshy download directory (`rigged_character_glb.glb`,
+`animation_glb.glb`). A clip whose channels match no node of the base rig is rejected (different
+skeleton) instead of producing a silent T-pose; unmatched channels are counted per clip. The rest
+poses the rig task shipped with are dropped unless you pass `--keep-base-animations`.
+
+## Admit in isolation
+
+Inside the Aura3D monorepo, `assets import-meshy` runs isolated by default because a plain import
+rewrites shared root files (`aura.assets.json`, `src/aura-assets.ts`, `public/aura-assets/*`,
+`aura-evidence/*`) and many games importing at once race. Isolated mode admits in a temporary project,
+validates there, and copies only the hashed GLB and its evidence into the game's folder:
+
+```bash
+npx @aura3d/cli@latest assets import-meshy artifacts/meshy/drift-lamp/ \
+  --into examples/drift-port/assets --prefix drift --name lamp \
+  --rights-evidence artifacts/meshy/drift-lamp/rights.json --profile prop
+```
+
+The typed key is `drift_lamp`; files land in `models/drift_lamp.glb` and
+`provenance/drift_lamp.rights.json` and `.meta.json`. A different model already at that path is refused
+unless `--overwrite`; `--keep-temp` keeps the temporary project for debugging; `--shared-manifest` opts out
+and writes the current project's manifests. Name raw downloads with the game prefix (`drift-lamp`), never
+a bare `rocks` or `board`: two games sharing one `rocks.raw.glb` silently reuse each other's model.
+
+## Credit ledger
+
+```bash
+rid=$(npx @aura3d/cli@latest meshy ledger reserve --game drift --op preview --cap 800 --global-cap 10000)
+npx @aura3d/cli@latest meshy ledger settle --rid "$rid" --exit-code 0 --task-id <id>
+npx @aura3d/cli@latest meshy ledger status
+```
+
+The ledger (`--ledger path` or `AURA3D_MESHY_LEDGER`, default `~/.aura3d/meshy-ledger.jsonl`) enforces a
+per-game cap and one global cap under a lock, so concurrent agents cannot overspend. `--game` is required
+and must be a lowercase tag. Estimates: preview 20, refine 10, remesh 5, rigging 5, animate 3, retexture 10.
+
+A rate-limited (exit 6) or timed-out (exit 8) call is NOT a failure: the task usually finishes and is
+charged. `settle --exit-code` records it as `unconfirmed`, which keeps counting its estimate. Resume the
+task with `meshy <resource> get <id>` instead of paying again, then
+`meshy ledger reconcile --rid <id> --status ok` (or `failed`). Only a confirmed no-charge outcome (auth
+exit 3, validation exit 4, credits exit 9, or a FAILED task) settles as `failed` and counts 0.