create-aura3d 3.0.1 → 4.0.0

package/skills/aura3d-retexture/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: aura3d-retexture
+description: Restyles a finished, admitted mesh while proving the geometry is untouched: before and after `assets inspect` bounds plus a position-accessor hash diff, one material family per map set, and a matched before and after screenshot filmstrip. Use when retexturing, recoloring, reskinning, or restyling an existing GLB or typed `assets.<key>` model, including after `meshy retexture`, a DCC texture pass, or a `model(asset, { material })` tint.
+---
+
+# Aura3D retexture (geometry untouched)
+
+A retexture changes how a mesh looks, never its shape. The proof is numeric
+(identical bounds and position data) plus visual (a matched before and after
+filmstrip). Orbit or turnaround views are not produced: the engine renders any
+angle of the real mesh through `camera.*`, and painted angles would be
+unverifiable. Shared rules (claim labels, typed assets, paid generation,
+benchmark mode) are in
+[../aura3d-core/references/boundaries.md](../aura3d-core/references/boundaries.md).
+
+## Look target
+
+Judge a retexture under the look it will ship in — the same map set reads warm
+under `golden-hour` and cold under `night-city`. Fix the route's look preset
+first, then iterate on maps; a recolor tuned against flat lighting drifts
+again under the real grade.
+
+## Establish the contract
+
+1. Run `npx @aura3d/cli@latest --help` and read the `assets inspect` and
+   `assets add` lines.
+2. Read `aura.assets.json` and `src/aura-assets.ts`. The source mesh must be
+   an admitted typed asset with a license. Keep its original file; never
+   overwrite it in place.
+3. Choose the path:
+   - Offline: a new GLB with new maps (a `meshy retexture` result through the
+     `meshy-cli` skill, or a DCC texture pass). This is the only way to change
+     texture maps.
+   - Runtime tint: `model(assets.x, { material: material.pbr({ color, roughness, metallic }) })`.
+     On typed GLBs this applies a flat tint that replaces surface textures on
+     the whole model. It cannot target one part or add maps.
+4. Benchmark mode: `npm install && npm run build`, then stop.
+
+## Procedure
+
+1. Record the before state:
+
+   ```sh
+   npx @aura3d/cli@latest assets inspect ./assets/source.glb --license > artifacts/retexture/before.inspect.json
+   node .agents/skills/aura3d-retexture/references/geometry-hash.mjs ./assets/source.glb > artifacts/retexture/before.geometry.json
+   ```
+
+   (Adjust the script path to wherever your agent client installed this
+   skill.) Keep `bounds`, `boundsMetadata`, `materials`, and `nodeNames` from
+   the inspection, and `geometryHash` plus per-primitive hashes from the
+   script. `assets inspect` reports bounds but no vertex hash, and the
+   manifest `hash` covers the whole file (textures included), so it always
+   changes on a retexture and proves nothing about geometry.
+2. Plan one material family per map set. List each glTF material by name
+   (from `materials`), assign it one target family (for example painted
+   metal, worn leather, matte plastic), and give each family exactly one map
+   set (base color, normal, roughness and metalness, occlusion). Never share
+   one map set across two families, and never split one family across two
+   map sets.
+3. Produce the after file as a new GLB in `artifacts/retexture/`. Only
+   materials, images, and textures may change. The node tree, mesh
+   primitives, UVs, skin, and morph targets stay as they are.
+4. Prove the geometry is untouched:
+
+   ```sh
+   node .agents/skills/aura3d-retexture/references/geometry-hash.mjs ./assets/source.glb artifacts/retexture/after.glb
+   npx @aura3d/cli@latest assets inspect artifacts/retexture/after.glb --license > artifacts/retexture/after.inspect.json
+   ```
+
+   The script exits 0 only when `geometryUntouched` is true (the same
+   POSITION and index bytes for every primitive). The inspections must show
+   identical `boundsMetadata.min`, `boundsMetadata.max`, and `nodeNames`, and
+   the same material names unless you renamed them on purpose. Draco
+   geometry must be decoded before hashing. For a runtime tint the file is
+   unchanged, so record that and skip the hash.
+5. Admit the after file as its own asset with provenance, leaving the
+   original entry in place:
+
+   ```sh
+   npx @aura3d/cli@latest assets add artifacts/retexture/after.glb --name sourceRestyled --license CC-BY-4.0 --author "<author>" --quality candidate --role product
+   npx @aura3d/cli@latest assets typegen
+   ```
+
+   Carry the source license forward; a derived file inherits its terms.
+6. Capture the filmstrip (normal mode, via `npm run test` on CI or a remote
+   worker): the same camera, lights, environment, exposure, and viewport for
+   before and after, 3 to 5 fixed views, for example
+   `camera.frameAsset(assets.source)` plus fixed `camera.perspective(...)`
+   positions. Only the asset key may differ between the paired frames. Place
+   each before frame beside its after frame.
+7. Report: the family-to-map-set table, both geometry reports, the bounds
+   comparison, the filmstrip, and the new asset key. Hand the label to
+   `aura3d-evidence-review`; a retextured asset stays `candidate` until
+   reviewed.
+
+## Stop and report
+
+- `geometryUntouched` is false, or bounds or node names differ: stop. The
+  file is a remesh or rebuild, not a retexture. Report the changed
+  primitives, and do not admit it as a restyle of the source.
+- The request needs per-part maps, but only the runtime tint path is
+  available: report the gap; the tint recolors the whole model.
+- The source has no license or provenance, or its terms forbid derivatives:
+  do not retexture it.
+- A mismatched camera, lighting, or viewport between before and after frames
+  makes the filmstrip invalid: recapture it; do not describe the difference.
+- Someone asks for orbit or turnaround renders painted from a 2D concept:
+  decline, and render real angles of the real mesh instead.
+
+## References
+
+- [Geometry hash script](references/geometry-hash.mjs)
+- [Asset workflow and `assets inspect`](https://github.com/auraoneai/aura3d/blob/main/docs/agents/asset-workflow.md)
+- [Rendering proof rule](https://github.com/auraoneai/aura3d/blob/main/docs/agents/rendering-proof-required.md)
+- Meshy retexture runs, approval, and `--max-credits`: load `meshy-cli`.

package/skills/aura3d-retexture/references/geometry-hash.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+// Geometry-untouched proof for a retexture: hashes every mesh primitive's
+// POSITION (and index) accessor bytes in a .glb, ignoring materials, images,
+// and textures. Two GLBs whose "geometryHash" matches have byte-identical
+// vertex positions and topology. Dependency-free; reads GLB 2.0 (BIN chunk,
+// data: URIs, or relative buffer files). Draco-compressed meshes are rejected.
+//
+// Usage: node geometry-hash.mjs before.glb [after.glb]
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+function readGlb(path) {
+  const buf = readFileSync(path);
+  if (buf.readUInt32LE(0) !== 0x46546c67) throw new Error(`${path}: not a GLB (bad magic)`);
+  let offset = 12;
+  let json;
+  let bin;
+  while (offset < buf.length) {
+    const length = buf.readUInt32LE(offset);
+    const type = buf.readUInt32LE(offset + 4);
+    const chunk = buf.subarray(offset + 8, offset + 8 + length);
+    if (type === 0x4e4f534a) json = JSON.parse(chunk.toString("utf8"));
+    else if (type === 0x004e4942) bin = chunk;
+    offset += 8 + length;
+  }
+  if (!json) throw new Error(`${path}: missing JSON chunk`);
+  // buffer 0 is the BIN chunk unless it declares a uri; data: and relative uris are also read.
+  const buffers = (json.buffers ?? []).map((buffer, index) => {
+    if (!buffer.uri) return index === 0 ? bin : undefined;
+    if (buffer.uri.startsWith("data:")) return Buffer.from(buffer.uri.split(",")[1] ?? "", "base64");
+    if (/^[a-z]+:/i.test(buffer.uri)) throw new Error(`${path}: remote buffer uri not supported`);
+    return readFileSync(resolve(dirname(path), decodeURIComponent(buffer.uri)));
+  });
+  return { json, buffers };
+}
+
+const COMPONENT_BYTES = { 5120: 1, 5121: 1, 5122: 2, 5123: 2, 5125: 4, 5126: 4 };
+const TYPE_COUNT = { SCALAR: 1, VEC2: 2, VEC3: 3, VEC4: 4, MAT4: 16 };
+
+function accessorBytes({ json, buffers }, index) {
+  const accessor = json.accessors[index];
+  if (accessor.bufferView === undefined) return Buffer.alloc(0);
+  const view = json.bufferViews[accessor.bufferView];
+  const bin = buffers[view.buffer ?? 0];
+  if (!bin) throw new Error(`buffer ${view.buffer ?? 0} is not readable`);
+  const elementSize = COMPONENT_BYTES[accessor.componentType] * TYPE_COUNT[accessor.type];
+  const stride = view.byteStride ?? elementSize;
+  const start = (view.byteOffset ?? 0) + (accessor.byteOffset ?? 0);
+  const out = Buffer.alloc(elementSize * accessor.count);
+  for (let i = 0; i < accessor.count; i += 1) bin.copy(out, i * elementSize, start + i * stride, start + i * stride + elementSize);
+  return out;
+}
+
+function geometryReport(path) {
+  const glb = readGlb(path);
+  const whole = createHash("sha256");
+  const primitives = [];
+  (glb.json.meshes ?? []).forEach((mesh, meshIndex) => {
+    (mesh.primitives ?? []).forEach((primitive, primitiveIndex) => {
+      if (primitive.extensions?.KHR_draco_mesh_compression) throw new Error("Draco-compressed geometry: decode before hashing");
+      const position = primitive.attributes?.POSITION;
+      if (position === undefined) return;
+      const positions = accessorBytes(glb, position);
+      const indices = primitive.indices === undefined ? Buffer.alloc(0) : accessorBytes(glb, primitive.indices);
+      const hash = createHash("sha256").update(positions).update(indices).digest("hex");
+      whole.update(hash);
+      const accessor = glb.json.accessors[position];
+      primitives.push({ mesh: mesh.name ?? `mesh${meshIndex}`, primitive: primitiveIndex, vertices: accessor.count, min: accessor.min, max: accessor.max, hash: `sha256-${hash}` });
+    });
+  });
+  return { file: path, primitiveCount: primitives.length, geometryHash: `sha256-${whole.digest("hex")}`, primitives };
+}
+
+const [before, after] = process.argv.slice(2);
+if (!before) {
+  console.error("usage: node geometry-hash.mjs before.glb [after.glb]");
+  process.exit(2);
+}
+const a = geometryReport(before);
+if (!after) {
+  console.log(JSON.stringify(a, null, 2));
+} else {
+  const b = geometryReport(after);
+  const geometryUntouched = a.geometryHash === b.geometryHash;
+  const changed = a.primitives.filter((p, i) => p.hash !== b.primitives[i]?.hash).map((p) => `${p.mesh}#${p.primitive}`);
+  console.log(JSON.stringify({ geometryUntouched, before: a.geometryHash, after: b.geometryHash, primitiveCount: [a.primitiveCount, b.primitiveCount], changed }, null, 2));
+  process.exitCode = geometryUntouched ? 0 : 1;
+}

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

@@ -0,0 +1,132 @@
+---
+name: aura3d-scene-authoring
+description: Turns a scene prompt into editable `@aura3d/engine` source by picking a scene kit or prompt plan, compiling it, and repairing weak screenshots from the compiled report. Use when writing a scene or route from a prompt, choosing among `sceneKits.*`, `prefabs.*`, or `primitives.*`, or using `definePromptPlan`, `compilePromptPlan`, `promptPlanToScene`, or `collectAuraSceneEvidence`.
+---
+
+# Aura3D scene authoring
+
+You turn prompt intent into maintainable TypeScript that calls public Aura3D
+APIs. There is no hidden scene generator. Every scene gets a look — the preset
+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).
+
+## Look target
+
+Read the genre recipe row in `../aura3d-art-direction/references/look-recipes.md`,
+pick the look id, and carry it through the plan and the code. A scene without a
+look renders flat on a void.
+
+## Establish the contract
+
+1. Run `npx @aura3d/cli@latest --help` and use only the commands it prints.
+2. Read `src/aura-assets.ts` and `aura.assets.json`. Every subject model comes
+   from a generated key. If the prompt names a real object and no key exists,
+   load `aura3d-assets` first.
+3. Read the installed `@aura3d/engine` type declarations before naming an
+   export. The prompt-plan enums are narrow: `sceneType` is `product-viewer`,
+   `cinematic-scene`, `mini-game`, or `material-studio`.
+4. Decide the mode. Benchmark mode: if `aura3d look capture` is available,
+   run the look-dev loop; otherwise copy the smallest matching recipe, run
+   `npm install && npm run build`, return the runner-owned run command, stop,
+   and label the result `prototype`.
+
+## Procedure
+
+1. Restate the prompt as scene intent: subject, scene family, camera, lighting,
+   effects, interaction, and what a screenshot must visibly show.
+2. Pick the starting point in this order: a template, then a scene kit, then
+   `prefabs.*`, and `primitives.*` only for set dressing, guides, or explicitly
+   abstract visuals.
+
+   | Prompt family | Start from | Screenshot must show |
+   | --- | --- | --- |
+   | Physics playground | `sceneKits.physicsPlayground` | falling cubes, settled pile, ramp, contact cues, reset |
+   | Particle fountain | `sceneKits.particleFountain` | dense upward flow, nozzle, splash, a real emission-rate control |
+   | Solar system | `sceneKits.solarSystem` | sun glow, six attached planet labels, orbit paths, stars |
+   | Neon tunnel | `sceneKits.neonTunnel` | inside-tube view, receding rings, rails, controlled bloom |
+   | Data visualization | `sceneKits.dataViz` | bars, axes, ticks, title, legend, selected value |
+   | Mini golf | `sceneKits.miniGolf` | ball, cup, aim and power, score, obstacle, boundaries |
+   | Material lab | `sceneKits.materialLab` | material classes distinct in pixels, not labels |
+   | City block | `sceneKits.cityBlock` | buildings, lit windows, streets, a real day/night state |
+   | Humanoid walk | `sceneKits.humanoidWalk` | one connected humanoid, planted feet, path |
+   | Product viewer | `sceneKits.productViewer` | typed model on plinth, contact shadow, softboxes |
+
+3. Kit path: mount the kit once and keep its diagnostics.
+
+   ```ts
+   import { createAuraApp, sceneKits } from "@aura3d/engine";
+   import { assets } from "./aura-assets";
+
+   const kit = sceneKits.productViewer(assets.product);
+   createAuraApp("#app", kit.toAppOptions());
+   console.log(kit.diagnostics, kit.evidence);
+   ```
+
+4. Plan path, when the prompt is product intent rather than a kit family:
+
+   ```ts
+   import { compilePromptPlan, createAuraApp, definePromptPlan, promptPlanToScene } from "@aura3d/engine";
+   import { assets } from "./aura-assets";
+
+   const plan = definePromptPlan({
+     sceneType: "product-viewer",
+     subject: { asset: assets.product },
+     camera: { preset: "product-orbit" },
+     lighting: { preset: "studio-softbox" },
+     interaction: "orbit",
+     acceptanceCriteria: ["product is centered and recognizable"]
+   } as const);
+
+   const compiled = compilePromptPlan(plan);
+   createAuraApp("#app", { scene: promptPlanToScene(plan), diagnostics: { overlay: true } });
+   console.log(compiled.report.visualSystems, compiled.report.repairHints);
+   ```
+
+5. Read the compiled report before editing: `visualSystems` lists what the
+   compiled scene actually contains; `rejected` lists what the engine could
+   not do (each with a code such as `unsupported-effect`); `repairHints`
+   carries the `lookLint` findings; `negativeCriteria` lists what must not
+   ship. Repair from `repairHints` plus `aura3d look lint` output.
+6. Controls go through `ui.*` helpers and must change rendered pixels; CSS and
+   DOM are UI only and never stand in for particles, bloom, trails, labels, or
+   renderer output.
+7. Mount one app per route. Never dispose and recreate the app inside a frame
+   loop to animate values.
+8. Normal mode only: collect `collectAuraSceneEvidence(scene)` or the kit
+   evidence, run `npm run build`, and hand screenshots and route health to
+   `aura3d-evidence-review`. The template `npm run test` gate runs Playwright;
+   run it in CI or on a remote runner, not on the local machine.
+9. Weak screenshot: apply the repair hints (tighter framing, foreground and
+   background structure, key/fill/rim contrast, visible state) or switch back
+   to the matching kit before changing any label or claim.
+
+## Look-dev loop
+
+`aura3d look capture` → judge against `quality-bar.md` → `aura3d look lint` →
+one change per round (lint first, then the weakest category). Full loop spec:
+`aura3d-art-direction`.
+
+## Stop and report
+
+- The subject is a named real object with no typed asset key: stop, load
+  `aura3d-assets`, and label the scene `blocked` until the key exists.
+- The only way to satisfy the prompt is a primitive stand-in for the primary
+  subject: stop and label it `prototype`.
+- An effect, PBR, skinning, WebGPU, or postprocess claim has no pixel evidence
+  from a route importing only `@aura3d/engine`: drop the claim or label it
+  `prototype`.
+- `npm run build` fails on an export you guessed: remove it and re-read the
+  type declarations. Do not add casts to force it through.
+- Benchmark mode: stop after the build and report the runner-owned command.
+
+## References
+
+- [Shared boundaries](../aura3d-core/references/boundaries.md)
+- [Build playbook](https://github.com/auraoneai/aura3d/blob/main/docs/agents/build-playbook.md)
+- [Prompt to 3D workflow](https://github.com/auraoneai/aura3d/blob/main/docs/agents/prompt-to-3d-workflow.md)
+- [Benchmark recipes](https://github.com/auraoneai/aura3d/blob/main/docs/agents/benchmark-recipes.md)
+- [Agent guide llms.txt](https://github.com/auraoneai/aura3d/blob/main/llms.txt)
+- [Prompt recipes](https://aura3d.auraone.ai/docs/prompt-recipes.html)
+- [Look recipes](../aura3d-art-direction/references/look-recipes.md)
+- [Look by scene family](references/look-by-family.md)

package/skills/aura3d-scene-authoring/references/look-by-family.md

@@ -0,0 +1,28 @@
+# Look by scene family
+
+One look per scene family, matched to `aura3d-art-direction/references/look-recipes.md`
+genres. Values are starting points; the look-dev loop refines them.
+
+| Scene family | Look preset | Key light | Palette accent | Atmosphere | Post grade |
+| --- | --- | --- | --- | --- | --- |
+| Physics playground | `interior-industrial` | high window key, 60° elevation | safety orange on concrete | light haze for depth | `product-studio` |
+| Particle fountain | `neon-night` | rim/back light through the spray | cyan-magenta emissive trail | thin fog catching bloom | `neon-night` |
+| Solar system | `space` | single hard key from the sun | warm gold rim on planets | none — void is the look | `space` |
+| Neon tunnel | `neon-arcade` | receding emissive rings | alternating ring hues | fog inside the tube | `neon-night` |
+| Data visualization | `interior-neutral` | soft key over axis plane | single accent per series | none | `product-studio` |
+| Mini golf | `outdoor-day` | warm afternoon key, 40° | turf greens + flag red | light fog on horizon | `daylight-outdoor` |
+| Material lab | `product-studio` | triple softbox | neutral grey stage | none | `product-studio` |
+| City block | `neon-night` | streetlight pools | sodium amber + sign neon | ground fog at street level | `neon-night` |
+| Humanoid walk | `character-showcase` | 3/4 front key + rim | cloth accent color | light ground fog | `product-studio` |
+| Product viewer | `product-studio` | hero softbox | brand accent on plinth | none | `product-studio` |
+| Cinematic scene | `golden-hour` | low warm sun, 15° | teal shadow vs amber key | atmosphere haze layer | `cinematic-film` |
+| Underwater | `underwater` | caustic shafts from surface | deep teal + biolume accent | volume haze, God rays | `underwater` |
+
+## Reading the row
+
+- Look preset supplies IBL, background, fog base and grade; the row's key and
+  palette entries are the scene-specific tweak you apply on top.
+- Fog density belongs to the look until the capture shows depth banding — then
+  raise it in the look, not with ad-hoc `world.fog` nodes.
+- Palette accent is one saturated color the eye can find fast; the rest of the
+  frame stays in the look's own grade.

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

@@ -0,0 +1,125 @@
+---
+name: aura3d-threejs-migration
+description: Ports three.js code to Aura3D by picking the matching migration template, rewriting to `@aura3d/engine` public APIs, and recording every approximation in the migration notes without drop-in claims. Use when porting three.js or R3F code, reading `THREE.*` imports, running the `aura3d migrate three` codemod (`migrateThreeToA3D`), or scaffolding a migration template (formerly `three-compat-*`).
+---
+
+# Aura3D three.js migration
+
+Aura3D is not a three.js drop-in. The target of a migration is a route written
+against `@aura3d/engine` public APIs. There is no installed compat shim
+package — `@aura3d/three-compat` was deleted in 4.0.0 — so the migration
+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).
+
+## Look target
+
+The migration replaces a hand-tuned renderer stack with a look preset: the
+target genre's recipe row maps `toneMapping`, `scene.environment`, exposure and
+fog into `looks.preset(<id>)` + `looks.appOptions(<id>)`. Keep the original
+lighting intent visible in the migration notes rather than porting raw
+toneMapping constants.
+
+## Establish the contract
+
+1. Run `npx @aura3d/cli@latest --help`, and check the installed
+   `@aura3d/engine` version. Name only exports you can see in its types.
+2. Inventory the source: list every `three`, `three/examples/jsm/*`, and
+   `three/addons/*` import, plus any `WebGLRenderer`, render loop, loader, and
+   `EffectComposer` use. That list is the migration scope.
+3. Read `src/aura-assets.ts`. Every GLB the old code loaded by URL must become
+   a typed asset (load `aura3d-assets`).
+4. Benchmark mode: `npm install && npm run build`, then stop.
+
+## Procedure
+
+1. Pick the closest template and scaffold it with
+   `npx create-aura3d@latest <dir> --template <name>`:
+
+   | Source code looks like | Template |
+   | --- | --- |
+   | Hand-rolled starter: renderer, ground, lit primitives | `custom-scene` |
+   | Product on a studio stage | `premium-product-viewer` |
+   | Room or interior built from boxes | `architecture-interior` |
+   | Single asset on an inspection stage | `asset-inspector` |
+   | Character on a pedestal | `character-viewer` |
+   | Material swatch row | `material-authoring` |
+   | Bloom or emissive post pass | `postprocess-scene` |
+   | Many repeated meshes | `large-scene` |
+
+   The former `three-compat-*` names scaffold the same templates through a
+   deprecation alias (removed next minor). All eight templates import only
+   `@aura3d/engine`. Keep it that way.
+2. Map each construct to the engine API. `createAuraApp` owns the renderer,
+   scene graph, camera, and frame loop, so delete them rather than port them.
+
+   | three.js | Aura3D |
+   | --- | --- |
+   | `WebGLRenderer` plus a render loop | `createAuraApp("#app", { scene })` |
+   | `new Scene()` | `scene()` |
+   | `PerspectiveCamera` | `camera.perspective(...)` or `camera.orbit(...)` |
+   | `OrbitControls` | `interactions.orbit(...)` |
+   | Lights | `lights.*` |
+   | `MeshStandardMaterial` and friends | `material.*` |
+   | Mesh plus a glTF loader | `model(assets.x)` |
+   | Box, sphere, plane geometry (set dressing) | `primitives.*` |
+   | `EffectComposer` bloom | `effects.bloom(...)` |
+
+3. When the port must stay three-shaped for a while, run the CLI codemod
+   and keep its output as a report, not as proof:
+   `aura3d migrate three "src/**/*.ts" --report` walks each file and prints
+   the per-construct verdicts; `--write` applies the rewrite in place. The
+   underlying adapter `migrateThreeToA3D(source)` returns `code`,
+   `rewrittenImports`, and `warnings`. Imports in `THREE_COMPAT_UNSUPPORTED_THREE_IMPORTS`
+   (`EffectComposer`, `RenderPass`, `UnrealBloomPass`, and others) are left
+   unchanged with a `postprocessing-unsupported` warning. Treat that as a
+   manual rewrite to `effects.*`, never as a pass.
+4. Triage coverage from the codemod's warning list, not a matrix: the
+   import map `THREE_COMPAT_THREE_IMPORT_MAP` names every specifier the
+   codemod rewrites; anything three-shaped it leaves alone shows up in
+   `warnings` as `postprocessing-unsupported` or an unmapped import. Each
+   warning is the work item — a manual rewrite to `effects.*` or
+   `material.*`, never a pass.
+5. There is no approximation ledger or compatibility matrix anymore — the
+   `@aura3d/three-compat` package was deleted in 4.0.0. For every construct
+   the codemod could not rewrite, record the approximation yourself in the
+   migration notes: what the three.js API did, what the Aura3D replacement
+   does, and the honest delta. For example, `MeshPhongMaterial`'s
+   Blinn-Phong specular maps to a native `material.*` preset with GGX —
+   write that delta down, do not imply equivalence.
+6. Keep `three` out of the engine route. The shipped route must pass
+   `aura3d check-deploy --dist dist --source`; a `three` import anywhere in
+   the shipped tree fails the deploy check.
+7. Write the migration notes: each supported API by name with the test that
+   covers it, each codemod warning and how it was resolved, and each dropped
+   or manually rewritten construct.
+8. Build and verify: `npm run build`, then `npm run test` (the template's
+   route-health and screenshot specs; run on CI or a remote worker), then
+   `aura3d assets validate --source`. Hand claim wording to
+   `aura3d-evidence-review`.
+
+## Stop and report
+
+- The source depends on something with no engine equivalent (custom
+  `ShaderMaterial` passes, render targets, `EffectComposer` chains, or an
+  import the codemod leaves unmapped): stop and list each construct with the
+  codemod warning that flagged it. Do not fake it with CSS, a DOM overlay,
+  or a CPU pixel pass.
+- A kept construct renders only approximately: it is not parity. Label that
+  part `prototype` or rewrite it natively.
+- A codemod warning you cannot resolve: report it; do not silently keep the
+  three.js shape.
+- The old code loaded a GLB by URL and no typed asset replaces it: stop and
+  hand off to `aura3d-assets`. Never keep the URL or use `unsafeModelUrl`.
+- Never write "drop-in", "full parity", or "100% three.js compatible". Name
+  the specific supported API and the test that proves it.
+
+## References
+
+- [Migration guide and boundaries](https://github.com/auraoneai/aura3d/blob/main/docs/project/migration.md)
+- [Migration codemod adapter](https://github.com/auraoneai/aura3d/blob/main/packages/aura3d-cli/src/migrate-three/ThreeToA3DAdapter.ts)
+- [Codemod import map](https://github.com/auraoneai/aura3d/blob/main/packages/aura3d-cli/src/migrate-three/ImportMap.ts)
+- [Codemod warnings](https://github.com/auraoneai/aura3d/blob/main/packages/aura3d-cli/src/migrate-three/CompatibilityWarnings.ts)
+- [Codemod CLI command (`aura3d migrate three`)](https://github.com/auraoneai/aura3d/blob/main/packages/aura3d-cli/src/commands/prd15/index.ts)
+- [Custom migration template](https://github.com/auraoneai/aura3d/blob/main/packages/create-aura3d/templates/custom-scene/src/main.ts)
+- [three.js lighting stack → Aura3D look](references/look-mapping.md)

package/skills/aura3d-threejs-migration/references/look-mapping.md

@@ -0,0 +1,27 @@
+# three.js lighting stack → Aura3D look
+
+The single largest visual change in a migration: a hand-assembled renderer,
+lighting and post stack collapses into one look preset. Map by intent, not by
+constant.
+
+| three.js source pattern | Replaced by | Watch for |
+| --- | --- | --- |
+| `scene.environment` + PMREM + env map | the look's IBL | do not re-add a second environment — lint `look/no-ibl`/`double-aa` guards |
+| `AmbientLight` (any intensity) | drop — the look fills ambient | re-adding it flattens the grade (`look/ambient-kills-ibl`) |
+| `DirectionalLight` key + `castShadow` | the look's key (elevation/azimuth baked per genre) | a second DirectionalLight doubles the shadow read |
+| `toneMapping`, `toneMappingExposure` | the look's `output.preset` | exposure moves inside the preset, not the renderer |
+| `scene.fog = new Fog(...)` | the look's fog/atmosphere | recipe rows give per-genre density |
+| `scene.background = color` | the look's backdrop | a solid color is `look/solid-void` unless declared |
+| `EffectComposer` bloom/vignette | the look's post stack | do not stack `antiAlias`/post twice (`look/double-aa`) |
+| `setPixelRatio` | `looks.appOptions(<id>)` DPR cap | `look/low-dpr` catches manual low ratios |
+| `HemisphereLight` | the look fill (or `lights.hemisphere` when you must override) | hemisphere + IBL flattens (`look/ambient-flattens`) |
+
+## Procedure tie-in
+
+1. Delete the lighting/renderer block entirely, apply `looks.preset(<genre>)` +
+   `looks.appOptions(<genre>)`.
+2. Recapture: the migrated scene's palette, shadow density and background come
+   from the look; the ledger records *intent deltas* (e.g. "original had a
+   cooler fill"), not constant deltas.
+3. `aura3d look lint` catches the leftovers the ledger cannot: orphaned
+   fog nodes, double AA, ambient that kills the IBL.

package/skills/llms.txt

@@ -0,0 +1,117 @@
+Aura3D agent guide — a typed scene API for building real 3D apps: scenes, looks,
+lighting, materials, typed assets, camera rigs and gameplay through
+`@aura3d/engine` plus the `@aura3d/cli` toolchain. Current release: Aura3D 3.0.1.
+
+Hello world: every scene gets a look first.
+
+```ts
+import { createAuraApp, looks, model, scene } from "@aura3d/engine";
+import { assets } from "./aura-assets";
+
+createAuraApp("#app", {
+  scene: scene().add(looks.preset("product-studio")).add(model(assets.robot)),
+  ...looks.appOptions("product-studio")
+});
+```
+
+The quality floor — what the defaults give you, and the never list:
+
+- A `looks.preset` supplies environment light (IBL), a shadow-casting key, fog,
+  background and a post grade as one unit — never hand-wire
+  `lights.ambient()` as the only fill, it flattens shading and kills IBL.
+- Never a solid void background: the look's sky, biome or studio backdrop owns it.
+- Never `pixelRatio`/`qualityProfile`/`safe-basic`/FXAA overrides or
+  `replaceTextures: true` — `looks.appOptions(id)` carries the renderer contract.
+- Never a hero subject made of primitives; `model(assets.x)` with a typed
+  catalog asset.
+- Never emissive cards or sprites faking reflections, puddles, splashes or glows —
+  use the look's `post` grade and `effects.*`.
+- Never CSS/DOM particles, overlays or labels standing in for rendered output;
+  HUD lives in the DOM, the scene does not.
+- Keep the key shadow at full strength with contact darkening at the subject's
+  feet; fog or atmosphere carries depth to the horizon.
+
+three.js → Aura3D mapping (corrected):
+
+| three.js | Aura3D |
+| --- | --- |
+| `new THREE.Scene()` | `scene()` |
+| `new THREE.Mesh(...)` + `new GLTFLoader()` | `model(assets.x)` (typed asset) |
+| `new THREE.PerspectiveCamera(...)` | `camera.perspective(...)`, `camera.rigs.*` |
+| `AmbientLight` | `lights.hemisphere(...)` or the look's environment fill |
+| `DirectionalLight` key/fill | the look's `key`/`rim` slots |
+| `scene.environment` + PMREM | `environments.preset|hdri`, `world.biome` |
+| `toneMapping`/exposure | `output.preset` and the look's post grade |
+| `setPixelRatio` | `quality: "auto"` via `looks.appOptions` |
+| `castShadow = true` | `shadow: true` on the light/node |
+| `EffectComposer` passes | `output.preset` + `effects.*` |
+| `AnimationMixer` | `AnimationController` / `createAnimationController` |
+| `new OrbitControls(...)` | `interactions.orbit(...)` |
+
+Genre recipes (see `aura3d-art-direction/references/look-recipes.md`):
+
+| Genre | Look | Camera + fov | Palette/accent | Atmosphere |
+| --- | --- | --- | --- | --- |
+| platformer | `outdoor-day` | follow2d fov 50 | greens/sky/wood + gold | fog 0.0025 |
+| racing | `golden-hour` | chase fov 60 | asphalt/orange/charcoal + amber | fog 30–180 m |
+| fighting | `arena-fight` | fighting fov 45 | arena dark/rope/crowd + rim | haze cone |
+| arena shooter | `space` | topDown fov 55 | space blue/graphite/teal + magenta | none |
+| sports/table | `interior-industrial` | topDown fov 40 | turf/white/dark + ball | indoor haze |
+| product | `product-studio` | orbit fov 35 | grey/white/metal + brand | none |
+| character | `character-showcase` | orbit fov 40 | costume neutrals + rim | room haze |
+| outdoor env | `overcast` | wide fov 55 | green/slate/fog blue + wildflower | fog 0.004 |
+| interior | `interior-warm` | orbit fov 45 | wood/cream/spines + plant | dust shafts |
+| night city | `night-city` | tele fov 35 | sodium/neon/asphalt + cyan | fog 15–90 m |
+| space | `space` | orbit fov 60 | void blue/limb/stars + aurora | none |
+| underwater | `underwater` | follow fov 50 | deep blue/teal/kelp + coral | scatter 0.03 |
+| cinematic | `polar-night` | dolly fov 35 | aurora/snow/night + lantern | snow mist 0.006 |
+
+The look-dev loop:
+
+1. Pick the genre recipe row and 1–3 reference frames; write a 3-line look brief.
+2. Build with the look preset and typed assets; no renderer overrides.
+3. Capture `aura3d look capture --route / --shots opening,mid,action`.
+4. Judge each frame against the quality-bar rubric; read `aura3d look lint`.
+5. Fix the single highest-leverage thing; one change per round; repeat until
+   every category reads 7+ or the loop exits flat.
+
+Assets — resolve real objects from the catalog first. Do not invent asset paths,
+URLs or ids — every model comes from a generated `assets.<key>`:
+
+- `npx @aura3d/cli@latest assets search "<object>"` (natural descriptive phrase;
+  the catalog is ~850k license-verified GLB/glTF aggregated from Objaverse,
+  Sketchfab, Poly Pizza, Poly Haven, OS3A, Khronos and CC0 packs).
+- `assets resolve "<object>" --name <name>` pulls the top auto-pullable match
+  and types it as `assets.<name>` → `model(assets.<name>)`.
+- Add local files with `assets add ./assets/model.glb --name model`, then read
+  the generated `src/aura-assets.ts`.
+- Playable characters: `assets resolve "animated humanoid fighting character"
+  --profile fighting-character` keeps provenance in `aura.assets.json`.
+
+Scaffold:
+
+```bash
+npx create-aura3d@latest my-scene --template product-viewer
+npx create-aura3d@latest my-fighter --template fighting-game
+cd my-scene && npm run dev
+```
+
+Claims: use every feature freely. Claim only what a judged capture shows.
+
+- Label every capability as one of: `createAuraApp` root safe API,
+  `production-runtime`, `rendering` internals, CLI asset pipeline, template-only
+  scaffold, prototype, or roadmap.
+- Public examples prove only what the safe API renders through `@aura3d/engine`.
+- A compiling route is not proof: route health, typed provenance and a readable
+  frame are required.
+
+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 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.
+
+Benchmark mode: if `aura3d look capture` is available, run the look-dev loop;
+otherwise run finite commands (`npm install && npm run build`) then stop and
+label the result `prototype`.