@aura3d/cli 3.0.1 → 4.0.2

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,147 @@
+Aura3D agent guide — a typed scene API for building real 3D apps: scenes, looks,
+lighting, materials, typed assets, camera rigs, gameFeel, SDF text, decals, rigid bodies, and gameplay through
+`@aura3d/engine` plus the `@aura3d/cli` toolchain. Current release: Aura3D 4.0.1 (succeeding 4.0.0).
+
+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(...)` |
+
+Effects, post-processing, atmospherics & VFX (`effects.*` in `@aura3d/engine@4.0.1`):
+- Post-processing: `effects.bloom`, `effects.neonBloom`, `effects.cinematicBloom`, `effects.ambientOcclusion`, `effects.contactOcclusion`, `effects.contactShadows`, `effects.screenSpaceReflections`, `effects.depthOfField`, `effects.motionBlur`, `effects.colorGrade`, `effects.vignette`, `effects.filmGrain`, `effects.chromaticAberration`, `effects.antiAlias`, `effects.outline`
+- Atmospherics & volumetrics: `effects.fog`, `effects.depthFog`, `effects.volumetricFog`, `effects.fogVolume`, `effects.lightCone`, `effects.auroraRibbon`, `atmosphere.setSky`, `atmosphere.setWetness`
+- Particles, weather & trails: `effects.particles`, `effects.meshParticles`, `effects.rain`, `effects.snow`, `effects.flipbook`, `effects.trail`, `effects.beam`, `ResidentGPUParticleRenderer` (WebGPU compute)
+- Game feel & genre kits: `game.feel` / `app.feel` (`hitStop`, `slowMo`, `damageFlash`, `speedLines`, `landingDust`, camera trauma), `game.platformer`, `game.racing`, `game.arcadeKart`, `game.grandPrixRoad`, `game.carSoccer`, `game.carSoccerPitch`, `game.racketSports`, `game.fallingBlocks`, `game.fighting`
+
+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
+```
+
+Mandatory 3D game & scene anti-failure guardrails:
+
+1. No primitive-box characters, vehicles, or hero props ("no stick-figure humans or box cars"):
+   - Never assemble characters, athletes, enemies, vehicles, aircraft, trees, or architectural landmarks out of `primitives.box`, `primitives.sphere`, or `primitives.cylinder` — keep every silhouette, look, lighting, and shadow readable with real 3D geometry.
+   - Every character, vehicle, creature, weapon, and landmark must mount a real 3D GLB via `model(assets.<name>, { targetMaxDimension, role })` from `src/aura-assets.ts`. If the catalog lacks a required 3D model, generate a bespoke PBR 3D model with Meshy (`meshy`) and admit it via `aura3d assets import-meshy`.
+   - Primitives (`primitives.plane`, `primitives.box`, `primitives.cylinder`, `primitives.torus`) are reserved strictly for ground/court surfaces, field lines, UI rings/reticles, laser beams, and invisible physics colliders.
+2. Boot directly into live 60 FPS 3D gameplay (no blocking start modals):
+   - Never hide the 3D canvas, camera framing, or atmosphere behind an opaque full-screen HTML start menu, character select modal, or briefing overlay on initial page load, and never require query parameters (`?autoplay=1`, `?demo=1`, `?play=1`) for the scene to animate.
+   - Every game route must start in active 60 FPS gameplay on Frame 1 with an intelligent AI autopilot/demo controller that plays the game autonomously and yields instant manual control on the first keyboard (`keydown`), pointer, touch, or gamepad input.
+   - Keep mode, stage, camera, and roster selectors in a compact, non-blocking top HUD bar, and always call `button.blur()` after button clicks so `Space` or `Enter` gameplay keys never re-trigger focused HUD buttons.
+3. Always decimate and compress Meshy 3D GLBs before admission (`<= 20,000` vertices, `<= 2 MB`, 16-bit indices):
+   - Raw Meshy exports often contain `200,000–1,750,000` vertices and `20–65 MB` of uncompressed 4K PNG textures, which stall main-thread glTF parsing and exhaust GPU memory when multiple models load in one scene.
+   - Every generated Meshy GLB must be simplified (`MeshoptSimplifier` to `<= 20,000` vertices for props/vehicles, 16-bit `Uint16Array` indices, de-interleaved `byteStride === 0` buffers) and have its textures compressed to `<= 1024x1024` (`~0.5–2.0 MB` per GLB) before being admitted into `public/aura-assets/` so PBR palette, contrast, and reflection stay responsive.
+4. Always use canonical typed asset manifest refs (`hash` required):
+   - The production glTF bridge requires `createAssetProvenance(node.asset).source === "typed-aura-assets-manifest"`, which requires a valid 64-character `sha256-...` `hash` and `public/aura-assets/...` provenance from `aura.assets.json` / `src/aura-assets.ts` so the rendered look and silhouette load cleanly.
+   - Never omit `hash` in custom `defineAssets(...)` declarations and never place unhashed duplicate GLBs in route-local `apps/<route>/public/aura-assets/` that collide with root `public/aura-assets/`.
+5. Mutate node handles instead of calling `app.setScene()` on every restart:
+   - Do not call `app.setScene()` when restarting a round, hole, or bout on the same stage/world; tearing down and remounting the scene disposes live GPU resources, breaks lighting and postprocess continuity, and aborts in-flight GLB loads. Track a scene signature (`stageId` / `worldId`) and reset positions, visibility, and animations through runtime node handles (`app.nodes.require(...)`).
+
+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`.
+
+| Scene Kit | API | Status |
+| --- | --- | --- |
+| Material lab | `sceneKits.materialLab()` | root-proven (partial advanced coat extensions) |
+

package/skills/manifest.json

@@ -0,0 +1,163 @@
+{
+  "schema": "aura3d.skills/1.0",
+  "cliVersion": "4.0.0",
+  "docsBase": "https://github.com/auraoneai/aura3d/blob/main/",
+  "coreSet": [
+    "aura3d-core",
+    "aura3d-art-direction",
+    "aura3d-assets",
+    "aura3d-evidence-review",
+    "aura3d-scene-authoring"
+  ],
+  "skills": {
+    "aura3d-core": {
+      "tier": "core",
+      "prd": "C1"
+    },
+    "aura3d-scene-authoring": {
+      "tier": "core",
+      "prd": "C2"
+    },
+    "aura3d-assets": {
+      "tier": "core",
+      "prd": "C3"
+    },
+    "aura3d-evidence-review": {
+      "tier": "core",
+      "prd": "C4"
+    },
+    "aura3d-art-direction": {
+      "tier": "core",
+      "prd": "QR13"
+    },
+    "aura3d-browser-game": {
+      "tier": "domain",
+      "prd": "D1"
+    },
+    "aura3d-character-animation": {
+      "tier": "domain",
+      "prd": "D2"
+    },
+    "aura3d-animation-studio": {
+      "tier": "domain",
+      "prd": "D3"
+    },
+    "aura3d-threejs-migration": {
+      "tier": "domain",
+      "prd": "D4"
+    },
+    "meshy-cli": {
+      "tier": "asset",
+      "prd": "P1"
+    },
+    "aura3d-materials-environments": {
+      "tier": "asset",
+      "prd": "P2"
+    },
+    "aura3d-game-art": {
+      "tier": "asset",
+      "prd": "P3"
+    },
+    "aura3d-retexture": {
+      "tier": "asset",
+      "prd": "P4"
+    },
+    "aura3d-performance": {
+      "tier": "later",
+      "prd": "L1"
+    }
+  },
+  "templates": {
+    "product-viewer": [
+      "aura3d-materials-environments",
+      "aura3d-retexture",
+      "meshy-cli"
+    ],
+    "cinematic-scene": [
+      "aura3d-materials-environments",
+      "aura3d-character-animation"
+    ],
+    "mini-game": [
+      "aura3d-browser-game",
+      "aura3d-materials-environments",
+      "aura3d-game-art"
+    ],
+    "racing-starter": [
+      "aura3d-browser-game",
+      "aura3d-materials-environments",
+      "aura3d-game-art"
+    ],
+    "falling-blocks-starter": [
+      "aura3d-browser-game",
+      "aura3d-materials-environments",
+      "aura3d-game-art"
+    ],
+    "fighting-game": [
+      "aura3d-browser-game",
+      "aura3d-materials-environments",
+      "aura3d-character-animation",
+      "aura3d-game-art"
+    ],
+    "arena-shooter": [
+      "aura3d-browser-game",
+      "aura3d-materials-environments",
+      "aura3d-game-art"
+    ],
+    "character-controller": [
+      "aura3d-browser-game",
+      "aura3d-materials-environments",
+      "aura3d-character-animation"
+    ],
+    "animation-channel": [
+      "aura3d-character-animation",
+      "aura3d-animation-studio"
+    ],
+    "prompt-animation-channel": [
+      "aura3d-character-animation",
+      "aura3d-animation-studio"
+    ],
+    "animation-studio": [
+      "aura3d-character-animation",
+      "aura3d-animation-studio"
+    ],
+    "episode-builder": [
+      "aura3d-character-animation",
+      "aura3d-animation-studio"
+    ],
+    "premium-product-viewer": [
+      "aura3d-threejs-migration",
+      "aura3d-materials-environments"
+    ],
+    "architecture-interior": [
+      "aura3d-threejs-migration",
+      "aura3d-materials-environments"
+    ],
+    "material-authoring": [
+      "aura3d-threejs-migration",
+      "aura3d-materials-environments"
+    ],
+    "asset-inspector": [
+      "aura3d-threejs-migration"
+    ],
+    "character-viewer": [
+      "aura3d-threejs-migration",
+      "aura3d-character-animation"
+    ],
+    "postprocess-scene": [
+      "aura3d-threejs-migration"
+    ],
+    "custom-scene": [
+      "aura3d-threejs-migration"
+    ],
+    "large-scene": [
+      "aura3d-threejs-migration",
+      "aura3d-performance"
+    ]
+  },
+  "clients": {
+    "claude": ".claude/skills",
+    "cursor": ".cursor/skills",
+    "generic": ".agents/skills",
+    "copilot": ".github/skills"
+  }
+}

package/skills/meshy-cli/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: meshy-cli
+description: Guides safe Meshy 3D generation, retexture, remesh, rigging, and animate work through the pinned official CLI and admits results with `aura3d assets import-meshy`. Use when the catalog has no clean candidate, or when planning, generating, resuming, downloading, post-processing, or admitting Meshy assets for Aura3D.
+---
+
+# Meshy CLI
+
+The installed official Meshy CLI is the command authority. Do not reproduce
+its API or trust remembered flags. Paid-generation controls are shared in
+[boundaries](../aura3d-core/references/boundaries.md).
+
+## Look target
+
+Decide the look before writing the generation prompt — the recipe row's palette
+and material mood belong in the Meshy text ("matte ceramic", "sun-faded
+plastic") so the returned PBR set lands inside the frame's lighting instead of
+fighting it. Judge the result under the scene's look preset, not in a neutral
+viewer.
+
+## Establish the contract
+
+1. Run `meshy --version` and require the repository pin `0.2.0`.
+2. Read `meshy --help`, `meshy resources`, and `meshy <resource> create --help`
+   for every resource you will call.
+3. Run `npx @aura3d/cli@latest --help` and confirm `assets import-meshy` and
+   its `--profile prop|environment|vehicle|humanoid` values.
+4. Confirm the catalog was tried first (`aura3d-assets`) and its rejection
+   reasons were reported. For the full upstream agent skill, review and pin a
+   revision of [meshy-3d-agent](https://github.com/meshy-dev/meshy-3d-agent)
+   before installing; do not copy its text here.
+
+## Decision tree
+
+Start from the closest existing mesh and pick the smallest operation:
+
+| Situation | Operation |
+| --- | --- |
+| Geometry and topology are right, look is wrong | `meshy retexture create` (hand the look to `aura3d-retexture` first) |
+| Look is right, triangle count or topology fails the profile | `meshy remesh create --target-polycount N` |
+| Textured humanoid, static, needs a skeleton | `meshy rigging create --height-meters M` |
+| Rig succeeded, a named action is missing | `meshy animate create --rig-task-id <id> --action-id N` |
+| Nothing usable exists | `meshy make "<prompt>"` or `meshy make ./ref.png` |
+| Only format or real-world size is wrong | `meshy convert` or `meshy resize` |
+
+Reject instead of generating when the subject is a named real product,
+brand, or person whose rights you cannot evidence; when rights evidence for
+the output cannot be recorded; when the user has not approved a maximum; or
+when a catalog candidate already passes the rubric.
+
+## Procedure
+
+1. Plan: `meshy make "<prompt>" --dry-run` and show the steps and estimate.
+   For single resources, read the create help and state the planned inputs.
+2. Get explicit approval for the maximum, then pass `--max-credits <approved>`.
+3. Run, preferring `--async` when other work can proceed. Persist task IDs
+   and provider resume hints in ignored local state. Resume a completed
+   preview; never recreate paid work that succeeded.
+4. Download immediately: `-o artifacts/meshy/<asset>/`. Never overwrite an
+   existing output directory without direct instruction.
+5. Texture precedence on `retexture create`: `--input-task-id` wins over
+   `--model-url`; `--multiview-image-urls` excludes both `--text-style-prompt`
+   and `--image-style-url`, which exclude each other. Keep
+   `--enable-original-uv true` to preserve an admitted mesh's UVs, and keep
+   `--enable-pbr true` so normal, metallic, roughness, and emission maps exist.
+6. Profile traps, from the Aura3D admission budgets:
+
+   | `--profile` | Max triangles | Min triangles | Max textures | Max texture px |
+   | --- | --- | --- | --- | --- |
+   | `prop` | 100,000 | none | 8 | 4096 |
+   | `vehicle` | 250,000 | 1,000 | 12 | 4096 |
+   | `humanoid` | 150,000 | 3,000 | 12 | 4096 |
+   | `environment` | 500,000 | none | 16 | 8192 |
+
+   Meshy `--texture-resolution` defaults to `4k`; `8k` fails every profile
+   except `environment`. With `--enable-pbr` each map counts toward the
+   texture limit. Non-indexed geometry leaves the triangle check `unproven`.
+   Omitting `--profile` infers it from `--role` (`character` to humanoid,
+   `vehicle` to vehicle, `world`/`environment`/`track` to environment, else
+   prop). Remesh defaults to 30,000; about 10,000 rigs well. Raw Meshy exports
+   often contain `200,000–1,750,000` vertices and `20–65 MB` of uncompressed 4K
+   PNG textures, which stall main-thread glTF parsing and exhaust GPU memory
+   when multiple models share one scene look and lighting setup. Before
+   admission into `public/aura-assets/`, always simplify every generated Meshy
+   GLB (`MeshoptSimplifier` to `<= 20,000` vertices for props/vehicles, 16-bit
+   `Uint16Array` indices, de-interleaved `byteStride === 0` buffers) and
+   compress textures to `<= 1024x1024` (`~0.5–2.0 MB` per GLB) so silhouettes,
+   shadows, palette, and PBR reflections load fast.
+7. Admit the local output with rights evidence.
+
+   ```bash
+   npx @aura3d/cli@latest assets import-meshy artifacts/meshy/arena-relic/ \
+     --name arenaRelic --rights-evidence artifacts/meshy/arena-relic/rights.json \
+     --profile prop --role prop --thumbnail artifacts/meshy/arena-relic/thumbnail.png
+   ```
+
+   Use `--file` when the run has several GLBs. Import defaults to
+   `--quality candidate` and refuses release certification. Read the
+   admission `blockers` and `unproven` lists; `routeReady: false` is a result
+   to report. Ensure the admitted entry in `aura.assets.json` /
+   `src/aura-assets.ts` carries a valid 64-character `sha256-...` `hash` and
+   `public/aura-assets/...` provenance for clean look and silhouette so
+   `createAssetProvenance(node.asset).source === "typed-aura-assets-manifest"`
+   preserves lighting and contrast; never omit `hash` in custom
+   `defineAuraAssets(...)` / `defineAssets` declarations (keeps shadow and
+   reflection intact) or place unhashed duplicate GLBs in
+   `apps/<route>/public/aura-assets/`.
+8. Rig handoff: after importing a rigged humanoid, inspect it and map clips
+   before any code names them, then load `aura3d-character-animation`.
+
+   ```bash
+   npx @aura3d/cli@latest assets inspect public/aura-assets/<file>.glb --animation --humanoid --skeleton
+   npx @aura3d/cli@latest assets validate-animation --clips <from inspect> \
+     --map idle=<clip>,walk=<clip>,run=<clip> --require idle,walk,run --require-rig
+   ```
+
+9. Use only the generated `assets.<key>` in code. Provider URLs, task IDs,
+   and `artifacts/meshy` paths never appear in route source. Send review to
+   `aura3d-evidence-review`.
+
+## Safety
+
+- Keep credentials out of arguments, prompts, logs, commits, and output. Use
+  OAuth locally (`meshy auth login`) or runtime `MESHY_API_KEY` injection in
+  authorized CI. Never use `auth login --with-key` with a pasted key.
+- Send Meshy only intentional prompts and selected media, never repository
+  source or unrelated user data.
+- Propagate Meshy exit codes (3 auth, 4 validation, 6 rate limit, 8 timeout,
+  9 credits exhausted). Prism or agent-capacity failures are separate issues.
+
+## Stop and report
+
+- No approved maximum: stop after the dry run and present the plan.
+- Exit code 9 or a plan above the approved maximum: stop; do not split the
+  job to stay under the cap.
+- Admission reports blockers for the chosen profile: keep the file as a
+  rejected local candidate, report the failing checks, and label the route
+  `prototype` or `blocked`.
+- `validate-animation` reports missing clips: do not name them in code;
+  report the gap and consider `meshy animate` with fresh approval.
+- Rights evidence cannot be produced: do not import.
+
+## References
+
+- [Boundaries](../aura3d-core/references/boundaries.md)
+- [Aura3D Meshy pipeline](https://github.com/auraoneai/aura3d/blob/main/docs/meshy-cli.md)
+- [Admission budgets source](https://github.com/auraoneai/aura3d/blob/main/packages/aura3d-cli/src/meshy/admission.ts)
+- [Meshy CLI](https://github.com/meshy-dev/meshy-cli)
+- [Meshy API docs](https://docs.meshy.ai/en/api)