@aura3d/cli 4.1.3 → 4.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aura3d/cli",
-  "version": "4.1.3",
+  "version": "4.3.0",
   "type": "module",
   "bin": {
     "aura3d": "dist/cli.js",
@@ -28,10 +28,10 @@
   "types": "./dist/index.d.ts",
   "dependencies": {
     "typescript": "^5.8.3",
-    "@aura3d/asset-index": "4.1.3",
-    "@aura3d/audio": "4.1.3",
-    "create-aura3d": "4.1.3",
-    "@aura3d/rendering": "4.1.3"
+    "create-aura3d": "4.3.0",
+    "@aura3d/audio": "4.3.0",
+    "@aura3d/asset-index": "4.3.0",
+    "@aura3d/rendering": "4.3.0"
   },
   "description": "Bring real GLB/glTF assets into Aura3D browser apps with typed references, provenance, catalog search, validation, screenshots, and deploy checks.",
   "keywords": [

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

@@ -76,7 +76,7 @@ Hard checklist (all must hold before claiming done):
 
 ## Default-look facts
 
-No environment authored means the built-in neutral floor (4.1.2 published builds also log `ENV_FETCH_FAILED` for `/aura-environments/neutral.manifest.json`); the legacy post chain makes frames with bloom or vignette 25% to 40% darker (`POSTPROCESS_V2_UNMIGRATED`, known issue); exposure runs brighter than three.js for the same intensities. Judge the captured frame with the same post settings, and read the full list in `docs/agents/art-direction.md` section 3.
+No environment authored means the built-in neutral floor (4.1.2 published builds also log `ENV_FETCH_FAILED` for `/aura-environments/neutral.manifest.json`); in 4.2.x `effects.vignette()` made frames about 25% to 40% darker (it ran on display-referred bytes; 4.3.0 applies it in linear light, about 6% to 18%; bloom does not darken); exposure runs brighter than three.js for the same intensities. Judge the captured frame with the same post settings, and read the full list in `docs/agents/art-direction.md` section 3.
 
 ## References
 

package/skills/aura3d-assets/SKILL.md

@@ -5,8 +5,8 @@ description: Finds, admits, inspects, validates, and types GLB/glTF, texture, en
 
 # 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
+The CLI is the only path from a file or search hit to a typed `assets.<key>`.
+Shared rules (resolve-first, typed assets, paid generation) are in
 [boundaries](../aura3d-core/references/boundaries.md). The canonical end-to-end
 page (catalog, Meshy, optimise, isolated admission, rig and clips, production
 rules, budgets) is
@@ -44,9 +44,12 @@ lighting you evaluate materials and silhouettes against.
 
    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.
+2. Prompt names a real object: let `assets resolve` decide (project asset,
+   open licence-clear source, Meshy only with `--allow meshy --budget N`, else a
+   primitives recipe), or search to choose yourself. There is no hosted catalog.
 
    ```bash
+   npx @aura3d/cli@latest assets resolve "battle-worn knight helmet" --dry-run
    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
@@ -108,7 +111,8 @@ lighting you evaluate materials and silhouettes against.
    `src/aura-assets.ts` (a 100k-line diff) and `public/aura-assets/*`.
 9. 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`.
+   (`assets validate-animation`, `assets validate --skin`), release checks to
+   `aura3d-evidence-review`.
 
 ## Reject a candidate when
 
@@ -129,9 +133,9 @@ lighting you evaluate materials and silhouettes against.
 - 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 from a text
-  prompt (load `meshy-cli`, dry run and an approved credit maximum first; never
+  prompt (load `meshy-cli`, dry run first, then reserve credits in the ledger; never
   from screenshots or frames of another game or product). Do not model the subject from primitives.
-- Search prints a catalog fetch warning (for example an HTTP 404): report it
+- Search prints a source fetch warning (for example an HTTP 404): report it
   verbatim, label asset-dependent work `blocked`, and never treat fallback
   deep-links as auto-pullable.
 - `assets validate --release` fails on provenance: keep the route `prototype`

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

@@ -145,4 +145,6 @@ per round until every category reads 7+, 6 rounds, or 2 flat rounds.
 - [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)
+- [Mistakes already made (read first)](https://github.com/auraoneai/aura3d/blob/main/docs/agents/lessons-learned.md)
 - [Kits and hooks (4.1)](references/kits-and-hooks.md)
+- Believable motion (`@aura3d/engine/game`): `attachToBone` (bat, club, ball in a hand), `createLocomotion` and `createFootSlideMeter` (legs that match the ground), `createHandBounce` and `measureHandBall` (a ball dribbled by hand: hand and floor contact, hand-offs, proof): `docs/api/motion-hand-bounce.md`, `docs/agents/build-a-game.md`

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

@@ -50,7 +50,9 @@ in flat light can vanish inside night-city shadow pools or golden-hour haze.
    ```
 
    Pass `--clips` from the inspection output. `"ok": false` with a
-   `missingActions` entry means the rig cannot play that action.
+   `missingActions` entry means the rig cannot play that action. Then run
+   `assets validate --skin <glb>`: it fails on stretched triangles, flaps and
+   a mesh not in its skeleton's pose (`assets repair-skin` fixes or guides).
 2. Multi-part characters: build the assembly from typed keys first.
 
    ```bash

package/skills/aura3d-core/SKILL.md

@@ -9,7 +9,7 @@ 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,
+Shared rules (claim labels, forbidden patterns, resolve-first, typed assets,
 paid generation, benchmark mode) live once in
 [references/boundaries.md](references/boundaries.md).
 
@@ -69,8 +69,8 @@ without a look ships flat shading, void background and floating props.
    There is no root `output` or `world` namespace: tone mapping and grade come
    from the look (`looks.appOptions`), environment from `environments.*`.
 
-4. If the prompt names a real object, resolve it through the catalog before
-   writing model code (load `aura3d-assets`).
+4. If the prompt names a real object, run `assets resolve` 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
@@ -112,7 +112,7 @@ without a look ships flat shading, void background and floating props.
 | 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` |
+| No clean open-source 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.

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

@@ -34,11 +34,13 @@ 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
+## Resolve-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.
+A prompt that names a real object goes through `npx @aura3d/cli@latest assets
+resolve "<descriptive phrase>" --name <key>` before any model code. It uses an
+admitted project asset, then an open licence-clear source, then Meshy (only with
+`--allow meshy` and a budget), and otherwise prints a primitives recipe for
+simple props. There is no hosted catalog.
 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`.
@@ -61,7 +63,8 @@ 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.
+- Resolve first. Generation is a fallback after `assets resolve` reports no
+  project or open-source match.
 - 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.

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

@@ -130,6 +130,7 @@ benchmark exception are in [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)
+- [Lessons learned and new-game checklist](https://github.com/auraoneai/aura3d/blob/main/docs/agents/lessons-learned.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-materials-environments/references/custom-shader-chunks.md

@@ -20,12 +20,18 @@ signatures: `docs/api/glsl-chunks.md`.
 
 ## 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
+`#include <a3d_math>`, `<a3d_noise>`, `<a3d_sky>`, `<a3d_fog>`, `<a3d_triplanar>`,
+`<a3d_toon>` and `<a3d_shadow>` 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.
 
+## Sun shadows
+
+Set `receiveShadow: true` on the `material.custom` spec (or `#include <a3d_shadow>`) and multiply
+your lit term by `a3dSunShadowAuto` (arguments: world position, normal): 1 in light, less in the key light's shadow.
+It follows the light's `shadow` options like a PBR surface does, and is exactly 1 with no shadow map.
+
 ## NaN and Inf safety
 
 Apple GPUs return NaN where a software renderer returns a number. One NaN in a

package/skills/llms.txt

@@ -1,6 +1,6 @@
 # Aura3D
 
-> Aura3D 4.1.3: a TypeScript SDK for browser 3D apps and games. You write a typed, declarative scene with `@aura3d/engine`; the `@aura3d/cli` toolchain handles typed GLB/glTF assets, checks and deploy gates. Built to be driven by AI coding agents. Site: https://aura3d.auraone.ai
+> Aura3D 4.3.0: a TypeScript SDK for browser 3D apps and games. You write a typed, declarative scene with `@aura3d/engine`; the `@aura3d/cli` toolchain handles typed GLB/glTF assets, checks and deploy gates. Built to be driven by AI coding agents. Site: https://aura3d.auraone.ai
 
 ## Fast path (read this first)
 
@@ -24,7 +24,7 @@ npm run build && npx @aura3d/cli@latest check-deploy --dist dist
 
 Other templates: `product-viewer` (default), `cinematic-scene`, `racing-starter`, `falling-blocks-starter`, `fighting-game`, `character-controller`, `arena-shooter`. List them with `npx create-aura3d@latest --help`. Known issue: a stock `vite build` of 4.1.2 fails on a Node-only import; use 4.1.3 or later.
 
-Read next, in this order: `docs/agents/README.md` (index), `docs/agents/agent-quickstart.md` (first scene, step by step), `docs/agents/recipes.md` (copy-and-adapt scenes: PBR cube with orbit, forest of instances, skinned character with crossfade, fixed-step game loop, custom shader on a grid), `docs/agents/claims-and-boundaries.md` (what you may claim). This path is meant to get a new agent to a rendering scene in minutes; the controlled cold-start trial that measures it is in `evidence/agent-eval/` (in progress).
+Read next, in this order: `docs/agents/README.md` (index), `docs/agents/agent-quickstart.md` (first scene, step by step), `docs/agents/recipes.md` (copy-and-adapt scenes: PBR cube with orbit, forest of instances, skinned character with crossfade, fixed-step game loop, custom shader on a grid), `docs/agents/claims-and-boundaries.md` (what you may claim). This path is meant to get a new agent to a rendering scene in minutes; the controlled cold-start trial that measures it is in `evidence/agent-eval/` (in progress). Building a game: read `docs/agents/new-game-checklist.md` and `docs/agents/lessons-learned.md` first, then run `node tools/game-checks/run.mjs <game-slug>`.
 
 Working inside the Aura3D monorepo itself: run browsers, Playwright and heavy builds on the remote runner (`tools/remote-acr/run.sh`), never local Docker or local Playwright.
 
@@ -88,7 +88,7 @@ Porting existing three.js code: `aura3d migrate three` and the `aura3d-threejs-m
 
 Never invent asset paths, URLs or ids. Every model comes from a generated `assets.<key>`.
 
-- `npx @aura3d/cli@latest assets search "<object>"` searches the license-verified catalog.
+- `npx @aura3d/cli@latest assets search "<object>"` searches licence-tagged open public sources and a starter pack; results are candidates to check, and there is no Aura3D-run search service to rely on.
 - `assets resolve "<object>" --name <name>` pulls the top match and types it as `assets.<name>`.
 - `assets add ./assets/model.glb --name model` adds a local file; then read the generated `src/aura-assets.ts`.
 - No catalog match: generate with Meshy (`meshy-cli` skill), optimize (`assets optimize --file in.glb --out out.glb --role <role>`), then admit (`assets import-meshy`).
@@ -136,6 +136,6 @@ Release integrity rules:
 
 - Full agent guide, genre recipes, guardrails and the page and example map: https://aura3d.auraone.ai/llms-full.txt
 - Docs: https://aura3d.auraone.ai/docs/api.html, https://aura3d.auraone.ai/docs/agent-quickstart.html, https://aura3d.auraone.ai/docs/claims.html
-- Showcase (15 playable games): https://aura3d.auraone.ai/apps/showcase-index/
+- Showcase (25 playable games): https://aura3d.auraone.ai/apps/showcase-index/
 - Sitemap: https://aura3d.auraone.ai/sitemap.xml; crawl policy: https://aura3d.auraone.ai/robots.txt
-- Last updated: 2026-10-24
+- Last updated: 2026-10-25

package/skills/meshy-cli/SKILL.md

@@ -28,7 +28,7 @@ viewer.
    downloads artifacts.
 3. Run `npx @aura3d/cli@latest --help` and confirm `assets import-meshy` and
    its `--profile prop|environment|vehicle|humanoid` values.
-4. Confirm the catalog was tried first (`aura3d-assets`) and its rejection
+4. Confirm `assets resolve` was tried first (`aura3d-assets`) and its skip
    reasons were reported. For the full upstream agent skill, review and pin a
    revision of [meshy-3d-agent](https://github.com/meshy-dev/meshy-3d-agent)
    before installing; do not copy its text here.
@@ -50,19 +50,21 @@ Reject instead of generating when the subject is a named real product,
 brand, character or person, or a request to reproduce another game's or
 product's art from its screenshots or frames; when rights evidence for
 the output cannot be recorded; when the user has not approved a maximum; or
-when a catalog candidate already passes the rubric.
+when an open-source candidate already passes the rubric.
 
 ## Procedure
 
 1. Plan: `meshy make "<prompt>" --dry-run` and show the steps and estimate.
    For single resources, read the create help and state the planned inputs.
-2. Get an approved maximum, then pass `--max-credits <approved>` and reserve
-   every paid call in the ledger first:
-   `rid=$(aura3d meshy ledger reserve --game <tag> --op preview --cap <per-game> --global-cap <total>)`,
-   then `aura3d meshy ledger settle --rid "$rid" --exit-code 0 --task-id <id>`.
+2. Spend is uncapped by owner decision on 2026-10-25 (credits tracked for visibility, no default cap). If the
+   user states a limit, pass `--max-credits <limit>` and `aura3d meshy ledger config --global-cap <N>`. Reserve
+   every paid call first: `aura3d meshy ledger reserve --dry-run --game <tag> --op preview,refine` (cost),
+   `rid=$(aura3d meshy ledger reserve --game <tag> --op preview)`, then
+   `aura3d meshy ledger settle --rid "$rid" --exit-code 0 --task-id <id>`. A cap that was set hard-stops and
+   prints the credits left and the flag that raises or removes it.
    Credits per operation: preview 20, refine 10 (`make` = 30), remesh 5,
    rigging 5, animate 3, retexture 10. A rate-limited or timed-out call keeps
-   counting until `ledger reconcile`.
+   counting until `ledger reconcile --rid <id>`; compare the whole ledger with the Prism pool using `ledger reconcile`.
 3. Run, preferring `--async` when other work can proceed. Persist task IDs
    and provider resume hints in ignored local state. Resume a completed
    preview; never recreate paid work that succeeded.
@@ -100,8 +102,7 @@ when a catalog candidate already passes the rubric.
    `defineAuraAssets(...)` / `defineAssets` declarations (keeps shadow and
    reflection intact) or place unhashed duplicate GLBs in
    `apps/<route>/public/aura-assets/`.
-8. Rig handoff: after importing a rigged humanoid, inspect it and map clips
-   before any code names them, then load `aura3d-character-animation`.
+8. Rig handoff: after importing a rigged humanoid, inspect it, map clips and run `assets validate --skin <glb>` (a mesh modelled in a pose tears) before any code names them, then load `aura3d-character-animation`.
 
    ```bash
    npx @aura3d/cli@latest assets inspect public/aura-assets/<file>.glb --animation --humanoid --skeleton
@@ -131,9 +132,9 @@ when a catalog candidate already passes the rubric.
 
 ## Stop and report
 
-- No approved maximum: stop after the dry run and present the plan.
-- Exit code 9 or a plan above the approved maximum: stop; do not split the
-  job to stay under the cap.
+- Always show the dry-run plan and its cost before paying.
+- Exit code 9 (credits exhausted) or a plan above a limit the user set: stop; do
+  not split the job to stay under that limit.
 - Admission reports blockers for the chosen profile: keep the file as a
   rejected local candidate, report the failing checks, and label the route
   `prototype` or `blocked`.

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

@@ -56,20 +56,31 @@ a bare `rocks` or `board`: two games sharing one `rocks.raw.glb` silently reuse
 ## 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 reserve --dry-run --game drift --op preview,refine
+rid=$(npx @aura3d/cli@latest meshy ledger reserve --game drift --op preview)
 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.
+The ledger (`--ledger path` or `AURA3D_MESHY_LEDGER`, default `~/.aura3d/meshy-ledger.jsonl`) tracks credits under a
+lock so concurrent agents share one total. Spend is uncapped by owner decision on 2026-10-25 (credits are tracked for
+visibility); a per-game cap (`--cap N`, `--game-cap N`, `AURA3D_MESHY_GAME_CAP`) and a global cap (`--global-cap N`,
+`AURA3D_MESHY_GLOBAL_CAP`, or `ledger config`) are opt-in, and `config --global-cap off --game-cap off` removes them.
+A cap that is set is a hard stop: exit 3 with the credits left and the flag that raises it. `--game` is
+required and must be a lowercase tag. Estimates: preview 20, refine 10, remesh 5, rigging 5, animate 3, retexture 10.
+`reserve --dry-run --op preview,refine,rigging` prices a chain without writing.
 
 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.
+exit 3, validation exit 4, credits exit 9, a FAILED task, or a 429 on a create) settles as `failed` and counts 0.
+Pass the Meshy stderr with `settle --exit-code 6 --error-text "<stderr>"`: a 429 on a poll
+(`/text-to-3d/<id>`) means the task exists, so it stays `unconfirmed` with that task id and keeps counting.
+
+`meshy ledger reconcile` (no `--rid`) compares the ledger with the Kiro Prism pool balance since the last
+`baseline` and prints the delta; `--apply` books it as an `unattributed` adjustment. It reads `GET /admin/meshy`
+with `AURA3D_PRISM_KEY` or `AURA3D_PRISM_KEY_FILE` (never printed) or a saved `--pool-json`.
 
 ## Profile traps