@aura3d/cli 5.0.0 → 5.0.2

package/skills/agent-docs/threejs-to-aura3d.md

@@ -0,0 +1,30 @@
+# If you would write this in three.js, write this in Aura3D
+
+Read this first. Aura3D is a standalone engine with its own renderer: you describe a scene as typed nodes and `createAuraApp` owns the renderer, camera aspect, resize, loop, context loss and disposal. Do not port that plumbing, delete it. Every Aura3D line below is type-checked against the engine in [`recipes-src/translation-table.check.ts`](recipes-src/translation-table.check.ts) (`pnpm exec tsc -p docs/agents/recipes-src/tsconfig.json`). Complete scenes with no admitted models: [`recipes.md`](recipes.md) recipes 8 to 15.
+
+| If you would write (three.js) | Write (Aura3D) | Difference that bites |
+| --- | --- | --- |
+| `Scene` + `PerspectiveCamera` + `WebGLRenderer` + `setAnimationLoop` | `scene({ background }).camera(camera.perspective({ position, target, fov }))` then `createAuraApp("#app", { scene })`; per frame `app.onFrame((f) => ...)` with `f.dt`; `await app.ready()` | No renderer, resize or loop code. Mount target is a `<canvas>` or a sized wrapper. |
+| `new Mesh(geometry, material)` | `primitives.box({ name, size: [w, h, d], material: material.pbr({ color }) })` (also `sphere`, `plane`, `cylinder`, `capsule`, `cone`, `torus`, `torusKnot`, `lathe`, `extrude`, `tube`) | Primitives are unit shapes scaled by `size`. `sphere` size is the **diameter**; `plane` is `[w, 1, d]` and lies in XZ. Unknown option keys are reported, not ignored. |
+| `mesh.position.set(...)`, `rotation`, `scale` | Build time: `.position(x, y, z).rotate(x, y, z).scale(2)`. Runtime: `.runtime({ id, mutable: true })`, then `app.nodes.require(id).setPosition(x, y, z)`, `.setRotation`, `.setScale` | A node you move later needs `runtime({ id, mutable: true })`. Handles have `set*`, not `.position.x`. Vectors are tuples, not `Vector3`. |
+| `Group` / `Object3D` hierarchy, bones as groups | `group("arm", [children], { position }).runtime({ id, mutable: true })` | Children use local transforms; a group's origin is its pivot. |
+| `BufferGeometry` + `setAttribute` + `setIndex` | `geometry.custom(geometry.define({ positions, normals, uvs, colors, indices, bounds }), { name, material })` | Typed arrays in; `bounds` required; `colors` are per-vertex RGBA. `geometry.dynamic` for geometry you rewrite. |
+| `MeshStandardMaterial` | `material.pbr({ color, roughness, metallic, emissive, opacity })` | Also `physical` (clearcoat), `emissive`, `toon`, `matcap`. Colour is a CSS string. |
+| `ShaderMaterial` | `material.custom({ glsl: { vertex, fragment }, uniforms: { t: { type: "f32", value: 0 } } })`; `handle.setUniform("t", v)` | GLSL 3.00 (`in`/`out`, write `outColor`). Prelude names: `position`, `normal`, `uv`, `modelViewProjectionMatrix`, `modelMatrix`, `cameraPosition`, `uTime`. Node/TSL: `material.node`. |
+| `DirectionalLight` + `castShadow` | `lights.directional({ position, target, intensity, shadow: true })` | `shadow: true` on the light; meshes take `castShadow` / `receiveShadow`. Also `point`, `spot`, `hemisphere`, `ambient`, `rect`. |
+| `scene.environment = pmrem` | `environments.neutral({ intensity, background: false })` (also `studio`, `outdoor`, `hdri`, `preset`) | Metals render dark without an environment. `looks.preset(id)` bundles environment, key light, fog and grade. |
+| `scene.background = sky shader`, `Sky` | `sky.preetham({ sun: { elevationDeg, azimuthDeg } })`, `sky.gradient`, `sky.dayNight` | Move the sun live with `app.atmosphere.setSky({ sun })`. |
+| `scene.fog = new FogExp2` | `effects.fog({ color, density })` | A scene node, not a property. |
+| `InstancedMesh` + `setMatrixAt`/`setColorAt` | `instances.cone({ name, transforms: [{ position, rotation, scale }], colors: ["#...", ...], material })` | One draw call per node. Instance colour multiplies the material colour: use a `#ffffff` base material. |
+| `AnimationMixer` + `clipAction().play()` | GLB: `app.nodes.require(id).play("Idle", { loop: true, crossFade: 0.3 })`. Procedural: set joint handles in `onFrame` | Clips come from the file (`assets inspect --animation`). |
+| `OrbitControls` | `interactions.orbit({ target: "node-name" })` + `camera.orbit({ position, target, fov })` | `target` is a node **name**, not a point. |
+| `Raycaster.intersectObjects` | `raycast({ origin, direction })` or `interactions.pointer({ target })` + `bindPointerInteractions(app, listener)` | Returns hits against scene nodes, no object references. |
+| `EffectComposer` + `UnrealBloomPass` | `effects.bloom({ intensity, threshold, radius })`, `effects.vignette`, `effects.colorGrade` | Passes are scene nodes; no composer. |
+| `TextGeometry`, CSS2D labels | `text3D("Aura3D", { size, depth })`, `labels.billboard("score", { position })` | HUD belongs in the DOM. |
+| `Points`, particle libraries | `effects.particles({ rate, lifetime: [a, b], speed, size, color, blend: "additive" })` | Built-in sprite atlas needs no art. |
+| `geometry.dispose()`, `renderer.dispose()` | `app.dispose()` | One call disposes everything the app made. |
+| `Vector3`, `Clock` | `[x, y, z]` tuples at option sites; `Clock` from `@aura3d/engine`; `Vector3` from `@aura3d/math/three` | Mutable three.js-shaped math lives only in `@aura3d/math/three`. |
+
+Not here: `GLTFLoader` (use a typed asset, `model(assets.x)`; see [`asset-workflow.md`](asset-workflow.md)), `renderer.toneMapping` (use the look preset's `output`), custom render targets and `EffectComposer` chains (no equivalent; check `docs/migration/from-threejs.md`).
+
+Porting an existing file: `npx @aura3d/cli@latest migrate three "src/**/*.ts"` lists what maps, what is approximate and what has no equivalent; it is a worklist, not a drop-in conversion. Full mapping with verdicts: [`docs/migration/from-threejs.md`](../migration/from-threejs.md).

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

@@ -3,6 +3,10 @@ name: aura3d-art-direction
 description: Sets the visual target and runs the look-dev loop for any Aura3D scene or game: genre look recipe, reference frames, look preset, capture, rubric judgement and iteration. Use when starting or finishing any scene, game, product viewer or template, or when a screenshot looks flat, dark, empty, floaty or placeholder-like.
 ---
 
+Start with [threejs-to-aura3d.md](https://github.com/auraoneai/aura3d/blob/main/docs/agents/threejs-to-aura3d.md) when the author knows
+three.js, and [recipes 8 to 15](https://github.com/auraoneai/aura3d/blob/main/docs/agents/recipes.md) when no model is admitted: each
+lists the look and light values it used and has a retained real-GPU frame.
+
 ## Look target
 
 1. Find the genre row in `references/look-recipes.md` (platformer, racing, fighting, arena shooter, sports/table, product, character, outdoor, interior, night city, space, underwater, cinematic).

package/skills/aura3d-core/SKILL.md

@@ -48,41 +48,34 @@ without a look ships flat shading, void background and floating props.
    });
    ```
 
-3. Translate any three.js instinct with this table (every row compiles against
-   the engine types; the full table and the mistakes agents make are in
-   [agent-quickstart.md](https://github.com/auraoneai/aura3d/blob/main/docs/agents/agent-quickstart.md)):
-
-   | three.js habit | Aura3D |
-   | --- | --- |
-   | `new Scene()` | `scene()`, then `.add(node)` |
-   | `GLTFLoader` + `Mesh` | `model(assets.x, { targetHeight })` |
-   | `PerspectiveCamera` | `scene({ camera: camera.perspective({ fov, position, target }) })` |
-   | `AmbientLight`/`HemisphereLight` | `lights.ambient(...)`/`lights.hemisphere(...)` or the look |
-   | `DirectionalLight` + `castShadow` | `lights.directional({ shadow: true })`; models cast by default |
-   | `FogExp2` | `effects.fog({ density })` |
-   | `EffectComposer` + bloom | `effects.bloom()` |
-   | `ShaderMaterial` | `material.custom({ glsl: { fragment }, uniforms: { uTime: { type: "f32", value: 0 } } })` |
-   | `InstancedMesh` | `instances.cone/box/sphere({ transforms, colors })` |
-   | `OrbitControls` | `interactions.orbit({ target: "<node name>" })` |
-   | `AnimationMixer` | `app.nodes.require(name).play(clip, { crossFade })` |
-
-   There is no root `output` or `world` namespace: tone mapping and grade come
-   from the look (`looks.appOptions`), environment from `environments.*`.
+3. Translate any three.js instinct with the table "if you would write X in
+   three.js, write Y" (every Aura3D line is type-checked against the engine):
+   [threejs-to-aura3d.md](https://github.com/auraoneai/aura3d/blob/main/docs/agents/threejs-to-aura3d.md). Signatures for the common
+   roots: [api-signatures.md](https://github.com/auraoneai/aura3d/blob/main/docs/agents/api-signatures.md); read them instead of
+   opening `node_modules` type files. 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, 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
-   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.
+6. A named real object (character, athlete, vehicle, aircraft, landmark) uses a
+   real GLB via `model(assets.<name>, { targetMaxDimension, role })` from
+   `src/aura-assets.ts` (`targetHeight` only for upright humanoids, so aspect
+   ratios stay proportional); drive rigged characters (`skins > 0`) with
+   `handle.setAnimation({ clip, loop: true, speed })`. No model admitted and
+   none wanted (a world, a creature, a prop set, an abstract piece)? Build it
+   procedurally from `primitives.*`, `geometry.define`, `instances.*`,
+   `material.*`, `group` joints and `environments.neutral`, starting from a
+   recipe in [recipes.md](https://github.com/auraoneai/aura3d/blob/main/docs/agents/recipes.md) (recipes 8 to 15: humanoid with joints,
+   terrain, props kit, PBR viewer, custom-shader water, sky and day/night,
+   fire, night street). Label such a route `procedural`, not a showcase claim,
+   and never leave flat unlit placeholders.
+   Capabilities in the 5.0 scope list that matter for visuals (try them, judge
+   by capture, claim nothing unproven): shader graphs through `material.node`,
+   `renderOrder` on nodes, post effects through `effects.*` including
+   `effects.shaderPass`, depth and normal inputs for post, motion vectors.
 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

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

@@ -11,11 +11,11 @@ catalog search for textures or HDRIs today (the asset index has no texture or
 HDRI adapter), so `assets search` will not find them. Shared rules (claim
 labels, typed assets, catalog-first for models, benchmark mode) are in
 [../aura3d-core/references/boundaries.md](../aura3d-core/references/boundaries.md).
+No texture or model admitted: [procedural recipes](https://github.com/auraoneai/aura3d/blob/main/docs/agents/recipes.md) 9, 11, 12, 13 and 15 cover vertex-colour terrain, PBR metal under `environments.neutral`, `material.custom` water, `sky.preetham` and emissive plus bloom; 5.0 adds shader graphs (`material.node`) and depth and normal inputs for post.
 
 ## Look target
 
-Most scenes need no per-file HDRI at all: `looks.preset(<genre>)` already supplies environment light, sky/background, fog and grade — pick it from the
-recipe row in `../aura3d-art-direction/references/look-recipes.md` and only descend into manual environments when the look cannot express the mood.
+Most scenes need no per-file HDRI at all: `looks.preset(<genre>)` already supplies environment light, sky/background, fog and grade — pick it from the recipe row in `../aura3d-art-direction/references/look-recipes.md` and only descend into manual environments when the look cannot express the mood.
 From 4.7.0 a look takes overrides (a catalogued `hdri` id, environment intensity and rotation, key, rim, fog, grade, post) and the app changes light,
 environment, fog and post at runtime: [look overrides, HDRI ids and runtime setters](references/look-overrides-4.7.md).
 

package/skills/aura3d-scene-authoring/SKILL.md

@@ -11,6 +11,13 @@ that supplies environment light, key shadow, fog, background and grade. Shared
 rules (claim labels, forbidden patterns, typed assets, benchmark mode) are in
 [boundaries](../aura3d-core/references/boundaries.md).
 
+Start from [threejs-to-aura3d.md](https://github.com/auraoneai/aura3d/blob/main/docs/agents/threejs-to-aura3d.md) (if you would write
+X in three.js, write Y) and, with no admitted model, a procedural recipe from
+[recipes.md](https://github.com/auraoneai/aura3d/blob/main/docs/agents/recipes.md) (recipes 8 to 15).
+No model admitted: compose `primitives.*`, `geometry.define`, `instances.*`,
+`group` joints, `material.*` and `environments.neutral` under a look, and say
+the route is procedural.
+
 ## Look target
 
 Read the genre recipe row in `../aura3d-art-direction/references/look-recipes.md`,

package/skills/aura3d-threejs-migration/SKILL.md

@@ -12,6 +12,11 @@ codemod plus an honest written record of what could not be reproduced is the
 on-ramp. Shared rules (claim labels, forbidden patterns, typed assets) are in
 [../aura3d-core/references/boundaries.md](../aura3d-core/references/boundaries.md).
 
+First stop: [threejs-to-aura3d.md](https://github.com/auraoneai/aura3d/blob/main/docs/agents/threejs-to-aura3d.md), the table of three.js
+idioms and the Aura3D line for each (type-checked), then the mapping below.
+A port that loaded no GLB can use a procedural recipe from
+[recipes.md](https://github.com/auraoneai/aura3d/blob/main/docs/agents/recipes.md) (recipes 8 to 15) as its starting scene.
+
 ## Look target
 
 The migration replaces a hand-tuned renderer stack with a look preset: the

package/skills/llms.txt

@@ -1,6 +1,24 @@
 # Aura3D
 
-> Aura3D 5.0.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
+> Aura3D 5.0.2: 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
+
+## Read first
+
+1. Coming from three.js? `docs/agents/threejs-to-aura3d.md` maps each three.js idiom to the Aura3D line (every line type-checked); the full table is in https://aura3d.auraone.ai/llms-full.txt under "three.js to Aura3D". Do not port renderer, resize, loop or disposal code: `createAuraApp` owns them.
+2. No model admitted yet? Build it procedurally from `primitives.*`, `geometry.define`, `instances.*`, `material.*` and `environments.neutral`. Eight complete scenes (humanoid, terrain, props kit, PBR viewer, custom-shader water, sky and day/night, fire, night street with bloom) are `docs/agents/recipes.md` recipes 8 to 15, sources in `docs/agents/recipes-src/`.
+3. Do not open `node_modules` or `dist` to find an API: signatures are in `docs/agents/api-signatures.md`.
+
+## Pitfalls that cost the most turns (one-line fixes)
+
+- Dark or flat frame: authored lights with no environment get no image-based light. Add `environments.neutral({ intensity })` or a `looks.preset(id)`; metals need it to reflect anything.
+- Colour applied twice: instance `colors` multiply the material colour. Use a `#ffffff` base material when you pass `colors`.
+- Moving a node: give it `.runtime({ id, mutable: true })` at build time, then `app.nodes.require(id).setPosition(...)`. Without the runtime id `require` throws.
+- Do not invent asset paths or ids: `npx @aura3d/cli@latest assets resolve "<object>" --name <name>`, then `model(assets.<name>)`.
+- Black frame with an admitted model: a route-local URL built with `new URL(..., import.meta.url)` is absolute and blocked as unsafe-url. Use `/aura-assets/<file>`, the file under the app's `public/aura-assets/`, and list it in `aura.assets.json`.
+- Custom shader: the prelude names are `position`, `normal`, `uv`, `modelViewProjectionMatrix`, `modelMatrix`, `cameraPosition`, `uTime`. A compile error logs `CUSTOM_SHADER_COMPILE_FAILED` and that draw is skipped silently.
+- One skinned body per character: never animate primitives beside a skinned mesh (double-framed skeleton, a ghosted limb).
+- Pools (bullets, traffic, particles) must be sized from the simulation's measured peak, or objects pop in and out.
+- Judge steady state: the first frame is lit differently from the baked probe seconds later. Capture at 3, 25 and 60 s; animated scenes flip between captures, so compare static bands before reverting anything.
 
 ## Fast path (read this first)
 
@@ -35,6 +53,8 @@ Working inside the Aura3D monorepo itself: run browsers, Playwright and heavy bu
 
 ## Hello world
 
+Hello world: one typed model under a look preset.
+
 ```ts
 import { createAuraApp, looks, model, scene } from "@aura3d/engine";
 import { assets } from "./aura-assets";
@@ -50,7 +70,7 @@ createAuraApp("#app", {
 - A `looks.preset` supplies image-based light, a shadow-casting key, fog, background and a post grade as one unit. Never wire `lights.ambient()` as the only fill.
 - Never a solid void background; the look's sky, biome or studio backdrop owns it.
 - Never `pixelRatio`, `qualityProfile`, `safe-basic`, FXAA or `replaceTextures: true` overrides; `looks.appOptions(id)` carries the renderer contract.
-- Never a hero subject made of primitives; use `model(assets.x)` with a typed asset. Primitives are for ground, lines, rings, beams and colliders.
+- Hero subject: use `model(assets.x)` with a typed asset when one exists or the prompt names a real object. With no admitted model (a world, a creature, a prop set, an abstract piece) build it procedurally as in recipes 8 to 15, never as a flat placeholder.
 - Never emissive cards or sprites faking reflections, puddles or glows; use the look's grade and `effects.*`.
 - Never CSS/DOM particles or labels standing in for rendered output. HUD lives in the DOM, the scene does not.
 - Gate frame 1 on `await app.ready()`; mutate node handles on restart instead of calling `app.setScene()` again.
@@ -74,18 +94,7 @@ Pick the look first, then tune. Palette and atmosphere cues per genre:
 
 ## three.js habit to Aura3D
 
-| three.js | Aura3D |
-| --- | --- |
-| `new THREE.Scene()` | `scene()` |
-| `GLTFLoader` + `Mesh` | `model(assets.x)` (typed asset) |
-| `PerspectiveCamera` | `camera.perspective(...)`, `camera.rigs.*` |
-| `DirectionalLight` + `AmbientLight` | the look's key, rim and environment slots |
-| `scene.environment` + PMREM | `environments.preset`, `environments.hdri`, `world.biome` |
-| `castShadow = true` | `shadow: true` on the light or node |
-| `EffectComposer` passes | `output.preset` + `effects.*` |
-| `AnimationMixer` | `AnimationController` |
-| `OrbitControls` | `interactions.orbit({ target: "node-name" })` |
-| `InstancedMesh` | `instances.mesh`, `instances.box`, `instances.cone` ... |
+See `docs/agents/threejs-to-aura3d.md` (first stop above).
 
 Porting existing three.js code: `aura3d migrate three` and the `aura3d-threejs-migration` skill record every approximation; the codemod is not a drop-in claim.
 
@@ -127,7 +136,7 @@ Use every feature freely. Claim only what a judged capture shows.
 
 Release integrity rules:
 - 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 primary character, vehicle, product, weapon, creature, world, or hero environment made only from primitives unless the route is explicitly abstract visualization or a labelled procedural recipe (recipes 8 to 15 are docs recipes, not showcase claims);
 - 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.
@@ -142,4 +151,4 @@ Release integrity rules:
 - Docs: https://aura3d.auraone.ai/docs/api.html, https://aura3d.auraone.ai/docs/agent-quickstart.html, https://aura3d.auraone.ai/docs/claims.html
 - 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-11-02
+- Last updated: 2026-11-06