@aura3d/cli 4.1.2 → 4.1.3

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

@@ -1,6 +1,6 @@
 ---
 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.
+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, or KTX2 textures.
 ---
 
 # Aura3D materials and environments
@@ -25,10 +25,14 @@ descend into manual environments when the look cannot express the mood.
    `--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.
+3. Check the installed `@aura3d/engine` version. `@aura3d/materials` and
+   `@aura3d/environments` were retired in 4.0.0: everything here ships from
+   `@aura3d/engine` (`material`, `environments`, `sky`, `weather`, `water`,
+   `looks`). The Node-side material and HDRI validators (names such as
+   `validateGameReadyMaterialPreset`, `inspectProductionHDR`) live in
+   `packages/engine/src/devtools/` and are not exported from the root or the
+   `@aura3d/engine/devtools` subpath, so do not import them from a project;
+   use the capture checks below.
 4. Benchmark mode: `npm install && npm run build`, then stop.
 
 ## Procedure
@@ -54,11 +58,12 @@ Step 1, presets (always try first):
    `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()`.
+4. Choosing values: start from `material.presets()` and the named builders
+   above (car paint is `material.clearcoatPaint`, thin glass is
+   `material.glass`, brushed metal is `material.brushedMetal`); the in-repo
+   preset library (`GAME_READY_MATERIAL_PRESETS` in
+   `packages/engine/src/devtools/materials/MaterialValidation.ts`) is a source
+   reference for values, not an import.
 
 Step 2, a licensed local file (Poly Haven or another CC0 / CC-BY source you
 downloaded yourself):
@@ -89,11 +94,10 @@ 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.
+8. HDRI file: it must be a Radiance `.hdr` with a 2:1 aspect ratio (check with
+   `file` or an image viewer before `assets add`); `assets add` records the
+   hash, and `assets validate` fails on a missing or changed file. Watch the
+   console for memory and PMREM warnings on the first load.
 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
@@ -108,8 +112,10 @@ Checks (all steps):
     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`.
+13. Screenshots (normal mode only) run through `npm run test` on a remote
+    runner, never local Playwright or GitHub Actions (`RUN_ID=mat-1
+    SPECS="tests/browser/<route>.spec.ts" tools/remote-acr/run.sh` in the
+    Aura3D repository). Hand the claim label to `aura3d-evidence-review`.
 
 14. Custom shaders (`material.custom`): write linear light, use
     `#include <colorspace_decode>` with `toneMapping: "none"` for authored hex
@@ -119,8 +125,8 @@ Checks (all steps):
 
 ## Look-dev loop
 
-`aura3d look capture` → judge against the quality-bar rubric → `aura3d look
-lint`. Judge only frames where the HDRI actually loaded (`iblPixelBacked`
+Capture (remote runner, see `aura3d-art-direction`) → 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.
 

package/skills/aura3d-performance/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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`.
+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 }`, `scene kit budgets`, `instances.*`, `distanceLod`, `text3D`, KTX2 texture compression, BUNDLE_SIZES, `doctor`, or `check-deploy`.
 ---
 
 # Aura3D performance
@@ -24,10 +24,15 @@ manual quality override invalidates every measurement that follows.
 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.
+3. Check which entry the app imports. `@aura3d/lean` was retired in 4.0.0
+   (the package is a deprecated shim), so import from `@aura3d/engine` and its
+   subpaths (`@aura3d/engine/game`, `@aura3d/engine/devtools`). Size is a known
+   weak spot: a one-cube app built from 4.1.2 measured 3,841 KB raw JS (1,089 KB
+   gzip) over about 25 requests, against 496 KB / 125 KB for the equivalent
+   three.js app (`evidence/vs-threejs/RESULTS.md`, section 4), and
+   `BUNDLE_SIZES.md` records the engine critical path failing its budget.
+   Import only what the route uses and keep devtools and cinematic helpers out
+   of the critical path.
 4. Decide the mode. Benchmark mode: `npm install && npm run build`, then stop.
    No profiling, dev server, or browser capture from the agent.
 
@@ -42,17 +47,18 @@ manual quality override invalidates every measurement that follows.
    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:
+2. Compare against the budget for the kit you started from. Each scene kit
+   reports its own budget in its `diagnostics`:
 
    ```ts
-   import { sceneKitPerformanceBudget, sceneKits } from "@aura3d/engine";
+   import { 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.
+   (There is no root `sceneKitPerformanceBudget` export; do not import one.)
 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
@@ -83,13 +89,15 @@ manual quality override invalidates every measurement that follows.
 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,
+9. Bundle: avoid pulling devtools or cinematic helpers into the critical path
+   and measure with a production `vite build`. 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.
+    screenshot runs (`npm run test`, Playwright) go to a remote runner, never
+    local Playwright or GitHub Actions (`tools/remote-acr/run.sh` in the Aura3D
+    repository).
 
 ## Stop and report
 

package/skills/aura3d-retexture/SKILL.md

@@ -82,8 +82,8 @@ again under the real grade.
    ```
 
    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
+6. Capture the filmstrip (normal mode, on a remote runner: `tools/remote-acr/run.sh`
+   in the monorepo, never local Playwright): 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
@@ -112,4 +112,5 @@ again under the real grade.
 - [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`.
+- Meshy retexture runs (10 credits, reserve in `aura3d meshy ledger`), approval, and `--max-credits`: load `meshy-cli`.
+- [Asset workflow](https://github.com/auraoneai/aura3d/blob/main/docs/agents/asset-workflow.md)

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

@@ -1,6 +1,6 @@
 ---
 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`.
+description: Turns a scene prompt into editable `@aura3d/engine` source by picking a scene kit or prompt plan, mounting it, and repairing weak screenshots with the look-dev loop. Use when writing a scene or route from a prompt, choosing among `sceneKits.*`, `prefabs.*`, or `primitives.*`, or using `definePromptPlan` or `promptPlanToScene`.
 ---
 
 # Aura3D scene authoring
@@ -66,7 +66,7 @@ look renders flat on a void.
 4. Plan path, when the prompt is product intent rather than a kit family:
 
    ```ts
-   import { compilePromptPlan, createAuraApp, definePromptPlan, promptPlanToScene } from "@aura3d/engine";
+   import { createAuraApp, definePromptPlan, promptPlanToScene } from "@aura3d/engine";
    import { assets } from "./aura-assets";
 
    const plan = definePromptPlan({
@@ -78,28 +78,26 @@ look renders flat on a void.
      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.
+   `compilePromptPlan` is deprecated with no replacement (removed in 5.0.0): do
+   not use it in new code.
+5. Judge the first frame, not the build. Repair from `kit.diagnostics`, the
+   console warnings and `aura3d look lint` output; each warning names its cause.
+   `prefabs.*` return node arrays, so mount them with `scene().addMany(...)`.
 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
+8. Normal mode only: collect `collectAuraSceneEvidence(scene)` (import it from
+   `@aura3d/engine/devtools`; the root export is deprecated) 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.
+9. Weak screenshot: fix the single biggest issue (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
 
@@ -123,7 +121,9 @@ one change per round (lint first, then the weakest category). Full loop spec:
 ## References
 
 - [Shared boundaries](../aura3d-core/references/boundaries.md)
-- [Build playbook](https://github.com/auraoneai/aura3d/blob/main/docs/agents/build-playbook.md)
+- [Recipes](https://github.com/auraoneai/aura3d/blob/main/docs/agents/recipes.md) (complete compiled scenes for the common tasks: copy one, then adapt; read this before opening any `dist/` file)
+- [Agent quickstart](https://github.com/auraoneai/aura3d/blob/main/docs/agents/agent-quickstart.md) (zero to a rendering scene, mistakes agents make)
+- [Build playbook](https://github.com/auraoneai/aura3d/blob/main/docs/agents/build-playbook.md) (games and assets)
 - [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)

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

@@ -67,8 +67,14 @@ toneMapping constants.
 
 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
+   `aura3d migrate three "src/**/*.ts"` walks each file and prints
+   the per-construct verdicts (`--report` is accepted and is the default);
+   `--write` saves the annotated rewrite in place. The rewrite does not
+   compile as is: on the benchmark PBR viewer it emitted
+   `const scene = scene()` and left `renderer.*` and `THREE.*` references, so
+   finish the port by hand. The verified 40-API mapping, measured codemod
+   output and a before and after are in
+   [docs/migration/from-threejs.md](https://github.com/auraoneai/aura3d/blob/main/docs/migration/from-threejs.md). The
    underlying adapter `migrateThreeToA3D(source)` returns `code`,
    `rewrittenImports`, and `warnings`. Imports in `THREE_COMPAT_UNSUPPORTED_THREE_IMPORTS`
    (`EffectComposer`, `RenderPass`, `UnrealBloomPass`, and others) are left
@@ -116,6 +122,8 @@ toneMapping constants.
 
 ## References
 
+- [Verified mapping, codemod limits, measured before and after](https://github.com/auraoneai/aura3d/blob/main/docs/migration/from-threejs.md)
+- [Honest comparison with three.js](https://github.com/auraoneai/aura3d/blob/main/docs/aura3d-vs-threejs.md)
 - [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)