create-aura3d 3.0.1 → 4.0.0

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

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

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

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

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

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

package/skills/aura3d-game-art/references/sheet-check.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// Flipbook sprite-sheet pre-flight for Aura3D `effects.flipbook`.
+// Reads a PNG header (no dependencies) and checks that the sheet divides evenly
+// into columns x rows, that the declared frame count fits the grid, and that the
+// PNG carries an alpha channel. It does not look at pixels; a transparent
+// background and clean frame edges still need a visual check.
+//
+// Usage: node sheet-check.mjs sheet.png --columns 8 --rows 4 [--frames 30]
+import { readFileSync } from "node:fs";
+
+const args = process.argv.slice(2);
+const file = args[0];
+const opt = (name) => {
+  const i = args.indexOf(`--${name}`);
+  return i >= 0 ? Number(args[i + 1]) : undefined;
+};
+const columns = opt("columns");
+const rows = opt("rows");
+if (!file || !columns || !rows) {
+  console.error("usage: node sheet-check.mjs sheet.png --columns N --rows N [--frames N]");
+  process.exit(2);
+}
+const frames = opt("frames") ?? columns * rows;
+
+const buf = readFileSync(file);
+const PNG_SIGNATURE = "89504e470d0a1a0a";
+const failures = [];
+if (buf.subarray(0, 8).toString("hex") !== PNG_SIGNATURE || buf.toString("ascii", 12, 16) !== "IHDR") {
+  console.log(JSON.stringify({ ok: false, file, failures: ["not a PNG (flipbook sheets must be PNG with alpha)"] }, null, 2));
+  process.exit(1);
+}
+const width = buf.readUInt32BE(16);
+const height = buf.readUInt32BE(20);
+const colorType = buf[25];
+// PNG color types 4 (gray+alpha) and 6 (RGBA) carry alpha; a tRNS chunk adds it to palette images.
+const hasAlpha = colorType === 4 || colorType === 6 || buf.includes(Buffer.from("tRNS"));
+
+for (const [name, value] of [["columns", columns], ["rows", rows], ["frames", frames]]) {
+  if (!Number.isInteger(value) || value <= 0) failures.push(`${name} must be a positive integer`);
+}
+if (width % columns !== 0) failures.push(`width ${width} is not divisible by ${columns} columns`);
+if (height % rows !== 0) failures.push(`height ${height} is not divisible by ${rows} rows`);
+if (frames > columns * rows) failures.push(`frames ${frames} exceed sheet capacity ${columns * rows}`);
+if (!hasAlpha) failures.push("PNG has no alpha channel; the background cannot be transparent");
+
+const cell = [width / columns, height / rows];
+console.log(JSON.stringify({
+  ok: failures.length === 0,
+  file,
+  size: [width, height],
+  grid: [columns, rows],
+  cell,
+  frames,
+  emptyCells: columns * rows - frames,
+  hasAlpha,
+  failures
+}, null, 2));
+process.exitCode = failures.length === 0 ? 0 : 1;

package/skills/aura3d-game-art/references/sprite-palettes.md

@@ -0,0 +1,25 @@
+# Sprite and flipbook palettes per genre
+
+Hue and luminance targets so hand-drawn or generated sprites land inside the
+route's look instead of reading as pasted stickers.
+
+| Genre look | Sprite family | Hues (sRGB) | Emissive target |
+| --- | --- | --- | --- |
+| `outdoor-day` | pickups, coins, springs | gold #FFC53D, leaf green #5DBB63, sky blue #56B4F0 | 3× ground luminance |
+| `golden-hour` | brake glow, exhaust, UI accents | amber #FF9E3D, burnt orange #D96C2C, charcoal #2B2623 | 4× asphalt |
+| `arena-fight` | hit sparks, meter fills, KO flash | impact orange #FF7A2B, meter cyan #46E8FF, KO white #FFFFFF | 5× arena floor |
+| `neon-arcade` | pieces, line-clear flash, grid glow | cyan #2EE6FF, magenta #FF3DE8, lime #B8FF2E, violet #8A5BFF | 4× board |
+| `night-city` | signs, window glow, puddle decals | sodium #FFB84D, neon red #FF2E6E, cool cyan #4DD8FF | 3× wet street |
+| `space` | lasers, shields, engine trails | laser magenta #FF4DFF, shield teal #3DFFE8, trail white | 6× starfield |
+| `underwater` | bubbles, biolume, fauna glints | deep teal #1FA8A0, biolume #7DFFD4, coral #FF8A6B | 3× water |
+| `product-studio` | callouts, tag glyphs, swatches | brand accent + neutral greys | none — flat read |
+
+## Drawing rules
+
+- Desaturate sprite fills slightly vs. the accent — the grade re-saturates and
+  pure-primary fills clip to flat color.
+- Keep alpha edges dark-tolerant: a white halo invisible in the texture viewer
+  blooms against `night-city` fog.
+- Flipbook frames must carry their own lighting direction matching the look's
+  key (a spark sheet lit from below fights a `golden-hour` key).
+- UI glyphs in DOM HUD use the look's foreground color, not the world palette.

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

@@ -0,0 +1,139 @@
+---
+name: aura3d-materials-environments
+description: Chooses and verifies surface looks and lighting environments: built-in `material.*`, `environments.*`, `sky.dayNight`, `weather`, and `water` first, then licensed local textures or HDRIs admitted with `assets add --type texture`, with seam, PBR-channel, and visual-QA checks. Use when a route needs a material, texture set, PBR maps, HDRI or IBL, skybox, night or daytime sky, rain, snow, water, KTX2 textures, or `@aura3d/materials` / `@aura3d/environments` validation.
+---
+
+# Aura3D materials and environments
+
+Order is fixed: looks/biomes/env presets first, then built-ins, then a
+licensed local file, then a generated plate as a candidate. There is no
+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).
+
+## 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.
+
+## Establish the contract
+
+1. Run `npx @aura3d/cli@latest --help` and read the `assets add` line and its
+   `--type texture|environment` option.
+2. Read `src/aura-assets.ts` and `aura.assets.json`. Map slots take typed
+   `assets.<key>` refs only, never a URL string.
+3. Check the installed `@aura3d/engine`, `@aura3d/materials`, and
+   `@aura3d/environments` versions. The validators below come from the
+   `/node` subpaths (`@aura3d/materials/node`, `@aura3d/environments/node`)
+   and run in Node scripts, not in browser routes.
+4. Benchmark mode: `npm install && npm run build`, then stop.
+
+## Procedure
+
+Step 1, presets (always try first):
+
+0. Looks and biomes: `looks.preset("outdoor-day" | "night-city" | "product-studio" ...)`
+   and `world.biome(<id>)` supply IBL + background + fog + key as one unit;
+   `environments.<named>`/`environments.hdri` cover the remaining cases before
+   any file admission.
+1. Materials: `material.pbr(...)`, `material.physical(...)`, `material.metal`,
+   `material.glass`, `material.rubber`, `material.fabric`,
+   `material.brushedMetal`, `material.ceramic`, `material.matteClay`,
+   `material.clearcoatPaint`, and `material.emissive`, plus
+   `material.proceduralTextures` (fabric, rubber, brushedMetal, plastic) for
+   maps without files. `material.presets()` lists the named specs.
+2. Environments: `environments.studio`, `environments.materialLab`,
+   `environments.productHero`, `environments.nightCinematic`,
+   `environments.metalStudio`, `environments.glassStudio`, or
+   `environments.forMaterial("metal" | "glass" | "product" | "studio")`.
+3. Outdoor: `sky.dayNight({ hour })` returns `nodes`, `background`, and
+   `dayFactor`; `weather.precipitation({ type: "rain" | "snow" })` and
+   `weather.wetGround(...)`; `water.surface({ preset: "calm" | "moderate" |
+   "rough" | "storm" })`. Add their `nodes` with `scene().addMany(...)` and use
+   the returned `background`.
+4. Library references for choosing values: `GAME_READY_MATERIAL_PRESETS` (car
+   paint, thin glass, brushed metal, skin approximation, and more),
+   `listThreeCompatPbrMaterials()`, and `THREE_COMPAT_TEXTURE_SETS`. Check a
+   preset in Node with `validateGameReadyMaterialPreset(preset)` or the whole
+   library with `validateGameReadyMaterialLibrary()`.
+
+Step 2, a licensed local file (Poly Haven or another CC0 / CC-BY source you
+downloaded yourself):
+
+5. Admit each map and each HDRI as a texture:
+
+   ```sh
+   npx @aura3d/cli@latest assets add ./textures/oak_diff_2k.jpg --name oakBase --type texture --license CC0-1.0 --source-page <page> --author "<author>"
+   npx @aura3d/cli@latest assets add ./hdri/night_1k.hdr --name nightSky --type texture --license CC0-1.0 --source-page <page> --author "<author>"
+   npx @aura3d/cli@latest assets typegen
+   ```
+
+   Use `--type texture` for HDRIs too: `environments.hdri({ texture })` only
+   accepts a texture-typed ref, and an `--type environment` ref fails to
+   type-check there. Use Radiance `.hdr`, not `.exr`, for IBL.
+6. Wire maps into one material: `texture` (base color), `normal`,
+   `roughnessMap`, `metalnessMap`, `occlusionMap`, `emissiveMap`, with
+   `texTransforms` for tiling. Wire the sky with
+   `environments.hdri({ texture: assets.nightSky, intensity, rotation })` and an
+   optional sharper `reflectionTexture`.
+7. Reject a PBR set that is missing roughness or metalness data where the
+   role expects PBR (metal, painted, or product surfaces). Do not invent the
+   missing map with a flat color and call it PBR.
+
+Step 3, a generated plate (optional, from an image skill outside Aura3D): keep
+it under `artifacts/`, admit it with `--quality candidate`, and label the
+route `prototype` until the checks below pass.
+
+Checks (all steps):
+
+8. HDRI file: in Node, `inspectProductionHDR(path, [width, height])` must
+   report a Radiance header and a 2:1 `declaredResolution`. For a manifest
+   preset, `verifyThreeCompatHdriFile(preset)` checks the file hash and
+   `createThreeCompatEnvironmentDiagnostics(preset)` reports memory and PMREM
+   warnings.
+9. Equirect seam: capture the sky at a yaw that puts the left and right edge
+   in frame and confirm no visible seam. `environments.hdri` renders a
+   procedural studio fallback first and swaps in the HDRI after load, so
+   judge only frames where diagnostics report `iblPixelBacked` true.
+10. Tiling: capture a surface at a texture scale that repeats the map at least
+    3 times and confirm no visible seam or mirrored repeat.
+11. On material showcase scenes, `structuralQA.material(nodes)` reports
+    `ok` plus per-class structural-name checks (nodes named like
+    chrome/glass/rubber actually present). These are diagnostics only —
+    acceptance comes from the captured frames.
+12. KTX2: `.ktx2` files are accepted by `assets add --type texture`, and
+    renderer coverage exists only for selected tested cases. Keep a
+    PNG/JPG fallback, and make no compression or memory claim without a
+    route-level capture.
+13. Screenshots (normal mode only) run through `npm run test` on CI or a remote
+    worker. Hand the claim label to `aura3d-evidence-review`.
+
+## Look-dev loop
+
+`aura3d look capture` → judge against the quality-bar rubric → `aura3d look
+lint`. Judge only frames where the HDRI actually loaded (`iblPixelBacked`
+true); a seam visible in one capture re-checks at a different yaw. One change
+per round.
+
+## Stop and report
+
+- No built-in matches and no licensed file is available: stop, label the look
+  `prototype`, and say a texture or HDRI source is needed. Do not fetch a URL
+  you have not verified, and do not claim a catalog texture exists.
+- License or source page is unknown: do not admit the file.
+- 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.
+- Any check above was not run: the route is `prototype`, not release.
+
+## References
+
+- [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)
+- [Material validation source](https://github.com/auraoneai/aura3d/blob/main/packages/engine/src/devtools/materials/MaterialValidation.ts)
+- [HDRI environment source](https://github.com/auraoneai/aura3d/blob/main/packages/engine/src/devtools/environments/HDRIEnvironment.ts)
+- [Sky, weather, and water browser harness](https://github.com/auraoneai/aura3d/blob/main/tests/browser/d3-atmosphere-water-harness.ts)

package/skills/aura3d-performance/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: aura3d-performance
+description: Measures and reduces Aura3D frame cost, draw calls, and bundle size with diagnostics, scene-kit budgets, instancing, distance LOD, frustum culling, and KTX2 textures, without turning counters into visual claims. Use when a route is slow, draw calls or bundle size exceed budget, or the task mentions `diagnostics: { overlay: true }`, `sceneKitPerformanceBudget`, `instances.*`, `distanceLod`, `text3D`, KTX2 texture compression, BUNDLE_SIZES, `doctor`, or `check-deploy`.
+---
+
+# Aura3D performance
+
+Measure first, change one thing, measure again. Diagnostics counters are
+evidence for performance claims only; they never prove a scene looks right.
+Shared rules (claim labels, forbidden patterns, typed assets, benchmark mode)
+are in [boundaries](../aura3d-core/references/boundaries.md).
+
+## Look target
+
+Measure with the final look active: the look sets the DPR cap, the post grade
+(bloom, AO, vignette) and shadow map size — most of the frame cost you are
+optimizing. `looks.appOptions(<id>)` already applies `quality: "auto"`; a
+manual quality override invalidates every measurement that follows.
+
+## Establish the contract
+
+1. Run `npx @aura3d/cli@latest --help` and `npx @aura3d/cli@latest doctor`.
+   Fix doctor failures before profiling; warnings are listed separately.
+2. Read `src/aura-assets.ts` and `aura.assets.json`. Note each asset's
+   `sizeBytes`, texture list, and bounds; heavy GLBs and uncompressed textures
+   are usually the first cost.
+3. Check which entry the app imports. New product and game apps should use
+   `@aura3d/lean`, `@aura3d/lean/product`, or `@aura3d/lean/game`. The
+   `@aura3d/engine` root is a compatibility entry and is far over the new-app
+   gzip budget.
+4. Decide the mode. Benchmark mode: `npm install && npm run build`, then stop.
+   No profiling, dev server, or browser capture from the agent.
+
+## Procedure
+
+1. Turn diagnostics on while measuring and off for release screenshots:
+
+   ```ts
+   createAuraApp("#app", { scene, diagnostics: { overlay: true, performancePanel: true } });
+   ```
+
+   The app's diagnostics report `backend`, `fps`, `drawCalls`, `renderSize`,
+   asset load states, `warnings`, and `errors`. Record them with the viewport,
+   device, and route so the finding reproduces.
+2. Compare against the budget for the kit you started from:
+
+   ```ts
+   import { sceneKitPerformanceBudget, sceneKits } from "@aura3d/engine";
+
+   console.log(sceneKitPerformanceBudget("miniGolf"));
+   console.log(sceneKits.miniGolf().diagnostics);
+   ```
+
+   Budgets carry `maxDrawCalls`, `estimatedDrawCalls`, `maxGzipBytes`, and
+   `targetP50Fps`. FPS targets require calibration on the measuring machine.
+3. Many repeated objects: replace per-node primitives with one `instances.box`
+   (or `instances.sphere`, `instances.plane`, `instances.cylinder`,
+   `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
+   `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
+   occlusion culling; do not claim it.
+6. Text: `text3D` is extruded mesh text (A-Z, 0-9, space, dash, period);
+   `labels.billboard` is DOM UI. Pick by need, not to save draws.
+7. Particles: check `particles.diagnostics` for total particles and
+   estimated update cost before raising counts.
+8. Textures: prefer KTX2/Basis-compressed textures supplied through typed
+   assets. Compression support is bounded to the tested decoder paths; verify
+   in the browser before claiming a memory or load-time win.
+9. Bundle: keep new imports on the lean entry and avoid pulling devtools or
+   cinematic helpers into the critical path. In the Aura3D monorepo,
+   `pnpm check:bundle-size` regenerates BUNDLE_SIZES; never raise a budget to
+   manufacture a pass.
+10. Ship check: `npm run build`, then
+    `npx @aura3d/cli@latest check-deploy --dist dist`. Browser frame-time and
+    screenshot runs (`npm run test`, Playwright) go to CI or a remote runner.
+
+## Stop and report
+
+- `doctor` or `check-deploy` fails: stop and fix that first; label `blocked`.
+- A win is measured on one machine only: call it directional, name the
+  machine and workload, and do not generalize it to a frame-time guarantee.
+- 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.
+
+## References
+
+- [Shared boundaries](../aura3d-core/references/boundaries.md)
+- [Profiling and diagnostics](https://github.com/auraoneai/aura3d/blob/main/docs/debug/profiling-and-diagnostics.md)
+- [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)
+- [Deployment](https://aura3d.auraone.ai/docs/deployment.html)