@aura3d/cli 3.0.1 → 4.0.2

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)

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)