@aura3d/cli 4.1.2 → 4.2.0

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)

package/skills/llms.txt

@@ -1,90 +1,34 @@
 # Aura3D
 
-> Aura3D: AI-Native TypeScript 3D SDK for Browser 3D Apps — typed scenes, looks, typed GLB/glTF assets, camera rigs, gameFeel, and gameplay through `@aura3d/engine` plus the `@aura3d/cli` toolchain, for browser 3D apps and interactive websites.
-
-Aura3D is the AI-native TypeScript 3D SDK for browser 3D apps, interactive websites, prompt-to-code scene kits, typed GLB/glTF assets, Vite templates, diagnostics, screenshots, and static deploy checks.
-
-## Facts
-
-- Product: AI-native TypeScript 3D SDK for browser 3D apps, interactive websites, and prompt-to-code scene kits
-- Website: https://aura3d.auraone.ai
-- Current release: Aura3D 4.1.2 (per the repo manifest — the same source the build's version guard uses)
-- Docs: https://aura3d.auraone.ai/docs/api.html
-- Showcase game: https://aura3d.auraone.ai/showcase/aura-clash/
-- Sitemap: https://aura3d.auraone.ai/sitemap.xml
-- Crawl policy: https://aura3d.auraone.ai/robots.txt (public content allow-all; build internals and source maps disallowed)
-- Last updated: 2026-10-23
-
-## Pages
-
-- [Home](https://aura3d.auraone.ai/): Aura3D is the AI-native TypeScript 3D SDK for browser 3D apps, interactive websites, prompt-to-code scene kits, typed GLB/glTF assets, Vite templates, diagnostics, screenshots, and static deploy checks.
-
-### Docs
-
-- [Aura3D Agent Quickstart for TypeScript 3D Apps](https://aura3d.auraone.ai/docs/agent-quickstart.html): Create an Aura3D browser 3D app with Vite, scene kits, typed assets, diagnostics, and AI-assisted TypeScript development.
-- [Aura3D Agent Setup for AI Coding Assistants](https://aura3d.auraone.ai/docs/agent-rules.html): Set up AI coding assistants to generate Aura3D TypeScript scenes with public SDK imports, scene kits, primitives, typed assets, and Vite templates.
-- [Aura3D TypeScript API for Agent-Written 3D Scenes](https://aura3d.auraone.ai/docs/api.html): Aura3D TypeScript API overview for scenes, models, cameras, lights, materials, primitives, scene kits, interactions, diagnostics, screenshots, and typed assets.
-- [Aura3D Typed GLB and glTF Asset Workflow](https://aura3d.auraone.ai/docs/assets.html): Register GLB and glTF assets with the Aura3D CLI, import generated typed asset references, and build product viewers without string asset IDs.
-- [Aura3D Vite Templates for Browser 3D Apps](https://aura3d.auraone.ai/docs/templates.html): Use create-aura3d Vite templates for product viewers, cinematic 3D scenes, mini-games, typed assets, diagnostics, and AI-assisted browser 3D development.
-- [Aura3D Prompt-to-3D Recipes for AI Agents](https://aura3d.auraone.ai/docs/prompt-recipes.html): Prompt-to-3D recipes for Aura3D scene kits, primitives, particles, physics, materials, city scenes, data visualization, mini-games, and typed GLB product viewers.
-- [Aura3D Deployment Checks for Static Browser 3D Sites](https://aura3d.auraone.ai/docs/deployment.html): Deploy Aura3D browser 3D apps with static builds, route checks, asset validation, browser-safe paths, and production hosting guidance.
-- [Aura3D Guide for Claude-Assisted 3D Apps](https://aura3d.auraone.ai/docs/claude.html): Use Claude with Aura3D to generate TypeScript browser 3D scenes from scene kits, primitives, typed GLB/glTF assets, and Vite templates.
-- [Aura3D Guide for Cursor AI 3D Development](https://aura3d.auraone.ai/docs/cursor.html): Use Cursor with Aura3D projects to edit TypeScript browser 3D scenes, Vite templates, typed GLB/glTF assets, scene kits, and prompt-to-3D workflows.
-- [Aura3D Evidence and Release Gates](https://aura3d.auraone.ai/docs/evidence.html): How Aura3D binds public package, asset, browser, game, visual, and deployment claims to retained evidence.
-- [Aura3D Claims, Limits, and Release Scope](https://aura3d.auraone.ai/docs/claims.html): Current Aura3D 4.1.2 claim boundaries for the root API, game presentations, assets, rendering, WebGPU, and diagnostics.
-- [Aura3D 4.1.2 vs. Raw Three.js — Open-Source TypeScript 3D Engine](https://aura3d.auraone.ai/docs/aura3d-vs-threejs.html): Stop assembling 14 fragile npm packages to render a 3D scene. Compare Aura3D 4.1.2 (@aura3d/engine@4.1.2) against raw Three.js across architecture, asset type safety, WebGPU compute, physics, and 18-line scene boot.
-- [Aura Clash: Aura3D Browser Fighting-Game Runtime Proof](https://aura3d.auraone.ai/docs/aura-clash-showcase.html): Aura Clash Arena is the Aura3D browser fighting-game development showcase: typed GLB runtime evidence, arena visuals, gameplay UI, accessibility controls, evidence routes, and release gates.
-
-### Showcase
-
-
-
-### Example apps
-
-- [Aura3D Concept Car Cinema: Typed GLB Product Configurator Example](https://aura3d.auraone.ai/apps/wow-concept-car-cinema/)
-- [Aura3D Damaged Helmet PBR Detail: Typed GLB Asset Viewer Example](https://aura3d.auraone.ai/apps/wow-damaged-helmet-pbr-detail/)
-- [Aura3D Examples and Games](https://aura3d.auraone.ai/apps/showcase-index/)
-- [Aura Slam 3D — Championship 3D Tennis on Aura3D](https://aura3d.auraone.ai/apps/showcase-top-tennis/)
-- [Aura Slam 3D — Championship 3D Tennis (V2) on Aura3D](https://aura3d.auraone.ai/apps/showcase-top-tennis-v2/)
-- [Apex Overdrive — 3D Sky-Lane Highway Racer on Aura3D](https://aura3d.auraone.ai/apps/showcase-roadster-rush/)
-- [Apex Overdrive — 3D Sky-Lane Highway Racer (V2) on Aura3D](https://aura3d.auraone.ai/apps/showcase-roadster-rush-v2/)
-- [THERMAL DRIFT — High-Velocity Combat Drone Racer · Aura3D Showcase](https://aura3d.auraone.ai/apps/showcase-heatsink/)
-- [THERMAL DRIFT — High-Velocity Combat Drone Racer (V2) · Aura3D Showcase](https://aura3d.auraone.ai/apps/showcase-heatsink-v2/)
-- [Grid Dispatch — San Francisco Robotaxi & Autonomous Fleet Showcase (Aura3D 4.0.2)](https://aura3d.auraone.ai/apps/showcase-teleoperator/)
-- [Grid Dispatch — San Francisco Robotaxi & Autonomous Fleet Showcase (V2, Aura3D 4.0.2)](https://aura3d.auraone.ai/apps/showcase-teleoperator-v2/)
-- [IRON CROWN — 2.5D Arena Fighter · Aura3D Showcase](https://aura3d.auraone.ai/apps/showcase-iron-crown/)
-- [PIP'S BIG LEAP — 3D Mascot Platformer · Aura3D Showcase](https://aura3d.auraone.ai/apps/showcase-pips-big-leap/)
-- [Aura Hoops 3D — Streetball Worldwide · Aura3D Showcase](https://aura3d.auraone.ai/apps/showcase-aura-hoops-3d/): Aura Hoops 3D: NBA-Jam-pace 3v3 streetball on the Aura3D engine — check-ball, shot meter, Jam Meter dunk packages, six world courts, Dunk Lab, Handles Lab and a 32-team Street Tour.
-- [Aura Diamond 3D — Baseball at Golden Hour · Aura3D Showcase](https://aura3d.auraone.ai/apps/showcase-aura-diamond-3d/): Aura Diamond 3D: broadcast-grade 3D baseball — real at-bats with PCI hitting, 4 pitch arsenals, 6 ballparks from Harbor Sandlot to Lunar Park, a 10-out Derby Lab, Bullpen Lab pitch-recognition drills, and a 32-team World Classic.
-- [Aura FC 3D — Street & Stadium Football · Aura3D Showcase](https://aura3d.auraone.ai/apps/showcase-aura-fc-3d/): Aura FC 3D: five-a-side broadcast football on the Aura3D engine — six venues from a favela cage to a glacier dome, Shootout & Touch Labs, a 32-team World Circuit, and a Player Studio.
-- [Red Zone 3D — Prime-Time Football on Aura3D](https://aura3d.auraone.ai/apps/showcase-red-zone-3d/): Red Zone 3D: broadcast-grade 3D American football — 7v7 arcade play-calling, six stadiums, Route Lab, Tackle Lab, and a 32-team Gridiron Series, rendered by the Aura3D engine.
-- [Aura Links 3D — Postcard Golf Worldwide · Aura3D Showcase](https://aura3d.auraone.ai/apps/showcase-aura-links-3d/): Aura Links 3D: three-click arcade golf on the Aura3D engine — six storybook courses from Scottish dunes to a lunar crater, Range & Putting Labs, and a 32-player Pro Circuit.
-- [Bunker Zero — Retro Corridor FPS on Aura3D](https://aura3d.auraone.ai/apps/showcase-bunker-zero/): Bunker Zero: a six-floor retro corridor shooter in the Wolfenstein mold — grid mazes, push-wall secrets, three enemy archetypes and the Iron Warden, rendered by the Aura3D engine.
-- [Aura3D - Slingshot Siege](https://aura3d.auraone.ai/apps/showcase-slingshot-siege/): Aura3D Slingshot Siege prototype: a Saturday-morning-cartoon physics destruction sandbox. Pull the pouch, lob five ammo types, squash every gull, topple every tower.
-- [Dot Dash 3D — Neon Maze Chase · Aura3D Showcase](https://aura3d.auraone.ai/apps/showcase-dot-dash-3d/): Aura3D Dot Dash 3D showcase, a neon maze-chase arcade game: dash through six glowing circuits gobbling light-dots while four Specters hunt with distinct AI personalities.
-- [Cross Hop — Aura3D Endless Lane Hopper](https://aura3d.auraone.ai/apps/showcase-cross-hop/): Aura3D Cross Hop showcase, an endless lane-hopping game: dodge cars, trams, trains, rivers and lava across 6 remixed themes, rescue critters, chase the high score.
-- [Strange Orbit — Aura3D port of the mechanics](https://aura3d.auraone.ai/apps/showcase-strange-orbit-port/): Moon-rim bike racing: a seven-lap cup race against five rivals with route splits, checkpoints and a rescue budget, rebuilt from a recorded run of the original. Simulation parity verified against the original's recorded seven-lap run; lit sci-fi look with audio and a difficulty selector; bikes, riders and rim props are generated models (riders are single rigid meshes); no career or garage. Independent Aura3D reconstruction; not affiliated with the original.
-- [Splat Rush — Aura3D port of the mechanics](https://aura3d.auraone.ai/apps/showcase-splat-rush-port/): Colour-gate ball runner with power-ups, colour switching and a splatter game-over; every simulation field matches the original's recorded run. Audio, effects and keyboard play added; backdrop islands and pickups are generated models; platform SDKs are not ported; a blind model judge could still tell the port from the original. Independent Aura3D reconstruction; not affiliated with the original.
-- [Serpentine Sky Run — Aura3D port of the mechanics](https://aura3d.auraone.ai/apps/showcase-serpentine-sky-run-port/): Endless runner on a serpentine sky road: eight stages with boost rungs, roll sections and traffic hazards; the outbound run matches a recorded reference. Outbound run only (no hell run or road home); title, pause, results and audio included; the runner, gate and hazards are generated models; a blind model judge could still tell the port from the original. Independent Aura3D reconstruction; not affiliated with the original.
-- [Drift & Deliver — Aura3D port of the mechanics](https://aura3d.auraone.ai/apps/showcase-drift-and-deliver-port/): Arcade drift driving through a block city: coin pickups, 84 traffic cars, bloom and a chase camera; all four recorded scenarios reproduce exactly. Headlight beam renders; the player car, traffic and street furniture are generated models (pedestrians are static); collision response untested; a blind model judge could still tell the port from the original. Independent Aura3D reconstruction; not affiliated with the original.
-- [HEATSINK — Aura3D port of the mechanics](https://aura3d.auraone.ai/apps/showcase-heatsink-port/): Anti-gravity time trial on the Vesper course with boost pads, pickups, barrels and heat management; the state replay matches the original within 1e-6. Simulation port only: the drone, pylons and scenery are generated models and the art is still visibly different from the original (a blind model judge picked the original in 35 of 48 trials and rated 40 of 48 pairs as the same game design); Time Trial only, no AI or audio. Independent Aura3D reconstruction; not affiliated with the original.
-- [Ninja Runner — Aura3D port of the mechanics](https://aura3d.auraone.ai/apps/showcase-ninja-runner-port/): Lane-running combat with twelve skinned clones, form changes and a full course win; the recorded 106-second run replays event for event. four generated rigged characters plus building and prop models; enemies share two bodies; sun shadows are off; a blind model judge could still tell the port from the original. Independent Aura3D reconstruction; not affiliated with the original.
-- [Last Train to the Sea — Aura3D port of the mechanics](https://aura3d.auraone.ai/apps/showcase-last-train-port/): Train-driving loop with day and night, passengers, fares and tips; loop length and score match the original's recorded loop and memory stays flat over three loops. No garage or level select; the tram, townhouses, landmarks and passengers are generated models (passengers stand rather than sit); a blind model judge could still tell the port from the original. Independent Aura3D reconstruction; not affiliated with the original.
-- [Roadster Hours — Aura3D port of the mechanics](https://aura3d.auraone.ai/apps/showcase-roadster-hours-port/): Coastal drive with 92 vehicles in one batched mesh; the recorded 48-second run replays exactly. Coastal look with sky, ocean and a lit road; vehicles and scenery are generated models and there are no shadows; a blind model judge could still tell the port from the original. Independent Aura3D reconstruction; not affiliated with the original.
-- [Where the Wind Wanders — Aura3D port of the mechanics](https://aura3d.auraone.ai/apps/showcase-where-the-wind-wanders-port/): Meadow walk collecting three letters and ringing a bell; the walking trajectory matches the original within 1e-9 over 2,098 steps. Includes the boat epilogue, journal and audio; the traveller, cottages and trees are generated models; a blind model judge could still tell the port from the original. Independent Aura3D reconstruction; not affiliated with the original.
-- [Silt & Signal — Aura3D port of the mechanics](https://aura3d.auraone.ai/apps/showcase-silt-and-signal-port/): Free-ride flying over a silt world; three recorded rides reproduce the original's simulation state to 1e-9. Chapter 0 has real colliders; the rider, ring beacons and landmarks are generated models; later chapters are generated hills, with no NPCs or minimap; a blind model judge could still tell the port from the original. Independent Aura3D reconstruction; not affiliated with the original.
-- [Cloud Runner — Aura3D port of the mechanics](https://aura3d.auraone.ai/apps/showcase-cloud-runner-port/): Obstacle runner on a cloud: the first chapter's run model replays the original's recorded run to 1e-12. Includes creatures, boulders, the duel and finale, with audio; the hero, creatures and scenery are generated models; a blind model judge could still tell the port from the original. Independent Aura3D reconstruction; not affiliated with the original.
-
-## Notes
-
-- Domain: https://aura3d.auraone.ai is a placeholder — swap AURA3D_SITE_URL (or the generator's ORIGIN) at deploy time; every URL in robots.txt, sitemap.xml, and this file follows.
-
-<!-- agent-guide: everything below this marker is the long-form agent guide; gen-seo.mjs preserves it verbatim -->
-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: see Facts above (4.1 adds the game kit, QA replay hooks, safety net, audio synth, model loader, GLSL chunks, scatter/merge, racket-sports kits and CLI asset tools).
-
-Hello world: every scene gets a look first.
+> Aura3D 4.2.0: a TypeScript SDK for browser 3D apps and games. You write a typed, declarative scene with `@aura3d/engine`; the `@aura3d/cli` toolchain handles typed GLB/glTF assets, checks and deploy gates. Built to be driven by AI coding agents. Site: https://aura3d.auraone.ai
+
+## Fast path (read this first)
+
+What it is, in five lines:
+
+- `@aura3d/engine` exports `createAuraApp(selector, { scene, ...looks.appOptions(id) })` and typed nodes (`scene`, `model`, `looks`, `lights`, `camera`, `effects`, `interactions`, `primitives`, `instances`, `game`).
+- Every scene starts from a `looks.preset(...)`, which supplies light, shadow, fog, background and grade together.
+- Models come from generated typed assets (`model(assets.robot)`), never raw URLs.
+- A game kit, QA/replay hooks, a runtime safety net and an audio synth ship as published subpaths (see Kits).
+- `@aura3d/cli` searches and admits assets (including Meshy generation), checks routes and deploys.
+
+Five commands to a running scene:
+
+```bash
+npx create-aura3d@latest my-scene --template mini-game   # also writes this file and the Aura3D skills
+cd my-scene && npm install
+npm run dev                                              # Vite on 127.0.0.1
+npx @aura3d/cli@latest assets resolve "robot" --name robot   # then use model(assets.robot) from ./src/aura-assets
+npm run build && npx @aura3d/cli@latest check-deploy --dist dist
+```
+
+Other templates: `product-viewer` (default), `cinematic-scene`, `racing-starter`, `falling-blocks-starter`, `fighting-game`, `character-controller`, `arena-shooter`. List them with `npx create-aura3d@latest --help`. Known issue: a stock `vite build` of 4.1.2 fails on a Node-only import; use 4.1.3 or later.
+
+Read next, in this order: `docs/agents/README.md` (index), `docs/agents/agent-quickstart.md` (first scene, step by step), `docs/agents/recipes.md` (copy-and-adapt scenes: PBR cube with orbit, forest of instances, skinned character with crossfade, fixed-step game loop, custom shader on a grid), `docs/agents/claims-and-boundaries.md` (what you may claim). This path is meant to get a new agent to a rendering scene in minutes; the controlled cold-start trial that measures it is in `evidence/agent-eval/` (in progress). Building a game: read `docs/agents/new-game-checklist.md` and `docs/agents/lessons-learned.md` first, then run `node tools/game-checks/run.mjs <game-slug>`.
+
+Working inside the Aura3D monorepo itself: run browsers, Playwright and heavy builds on the remote runner (`tools/remote-acr/run.sh`), never local Docker or local Playwright.
+
+## Hello world
 
 ```ts
 import { createAuraApp, looks, model, scene } from "@aura3d/engine";
@@ -96,139 +40,86 @@ createAuraApp("#app", {
 });
 ```
 
-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):
+## Quality floor and the never list
+
+- A `looks.preset` supplies image-based light, a shadow-casting key, fog, background and a post grade as one unit. Never wire `lights.ambient()` as the only fill.
+- Never a solid void background; the look's sky, biome or studio backdrop owns it.
+- Never `pixelRatio`, `qualityProfile`, `safe-basic`, FXAA or `replaceTextures: true` overrides; `looks.appOptions(id)` carries the renderer contract.
+- Never a hero subject made of primitives; use `model(assets.x)` with a typed asset. Primitives are for ground, lines, rings, beams and colliders.
+- Never emissive cards or sprites faking reflections, puddles or glows; use the look's grade and `effects.*`.
+- Never CSS/DOM particles or labels standing in for rendered output. HUD lives in the DOM, the scene does not.
+- Gate frame 1 on `await app.ready()`; mutate node handles on restart instead of calling `app.setScene()` again.
+
+## Genre looks (starting points)
+
+Pick the look first, then tune. Palette and atmosphere cues per genre:
+
+| Genre | Look | Camera | Palette and atmosphere |
+| --- | --- | --- | --- |
+| platformer | `outdoor-day` | follow2d, fov 50 | greens, sky, wood + gold; fog 0.0025 |
+| racing | `golden-hour` | chase, fov 60 | asphalt, orange + amber; fog 30 to 180 m |
+| fighting | `arena-fight` | fighting, fov 45 | dark arena, crowd + rim light |
+| arena shooter | `space` | topDown, fov 55 | space blue, teal + magenta; no fog |
+| sports or table | `interior-industrial` | topDown, fov 40 | turf, white + ball; soft shadow |
+| product | `product-studio` | orbit, fov 35 | grey, white, metal + brand colour; soft shadow |
+| character | `character-showcase` | orbit, fov 40 | costume neutrals + rim light |
+| outdoor environment | `overcast` | wide, fov 55 | green, slate + fog blue; fog 0.004 |
+| night city | `night-city` | tele, fov 35 | sodium, neon + cyan; fog 15 to 90 m |
+| cinematic | `polar-night` | dolly, fov 35 | aurora, snow + lantern; sky glow |
+
+## three.js habit to Aura3D
 
 | 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 |
+| `GLTFLoader` + `Mesh` | `model(assets.x)` (typed asset) |
+| `PerspectiveCamera` | `camera.perspective(...)`, `camera.rigs.*` |
+| `DirectionalLight` + `AmbientLight` | the look's key, rim and environment slots |
+| `scene.environment` + PMREM | `environments.preset`, `environments.hdri`, `world.biome` |
+| `castShadow = true` | `shadow: true` on the light or 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:
+| `AnimationMixer` | `AnimationController` |
+| `OrbitControls` | `interactions.orbit({ target: "node-name" })` |
+| `InstancedMesh` | `instances.mesh`, `instances.box`, `instances.cone` ... |
 
-```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
-```
+Porting existing three.js code: `aura3d migrate three` and the `aura3d-threejs-migration` skill record every approximation; the codemod is not a drop-in claim.
+
+## Assets
+
+Never invent asset paths, URLs or ids. Every model comes from a generated `assets.<key>`.
 
-Mandatory 3D game & scene anti-failure guardrails:
-
-1. No primitive-box characters, vehicles, or hero props ("no stick-figure humans or box cars") & prop normalization (`targetMaxDimension` vs `targetHeight`):
-   - 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` (use `targetHeight` only for upright humanoids and `targetMaxDimension` for horizontal vehicles, rackets, paddles, weapons, barriers, and wide props so aspect ratios and silhouettes never stretch vertically). 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`.
-   - Drive rigged humanoid and creature GLBs (`skins > 0`) via `handle.setAnimation({ clip, loop: true, speed })` (or `AnimationController`) synchronized to locomotion (`idle`, `walk`, `run`, `attack`, `swing`) so limbs articulate under the key light and shadow instead of sliding rigid statues across the floor.
-   - 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 sequence gate (`await app.ready()`) & default manual control (`autopilot = false` on Frame 1):
-   - Gate Frame 1 on `await app.ready()` before fading out `#boot-gate` (`opacity: 0; pointer-events: none` then remove) and starting the gameplay simulation loop so lighting, shadow, and GLB silhouettes never pop in mid-frame.
-   - Default `autopilot` / AI demo mode to `false` (immediate manual control on Frame 1 once `#boot-gate` clears); enable AI autopilot only when `?autoplay=1` or `?demo=1` is present in the URL or when the user clicks the HUD `Auto` toggle button, and yield back to manual control on keyboard (`keydown`), pointer, touch, or gamepad input.
-   - Keep mode, stage, camera, `Auto`, and roster selectors in a compact, non-blocking top HUD bar that preserves camera framing, and always call `button.blur()` after button clicks so `Space` or `Enter` gameplay keys never re-trigger focused HUD buttons.
-3. Always optimize Meshy 3D GLBs before admission (`aura3d assets optimize --file in.glb --out out.glb --role <role>`):
-   - 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.
-   - Role budgets: prop 6,000, background 15,000, character 30,000, hero or vehicle 40,000 vertices; textures capped at 1024 to 2048 px; 16-bit indices; keep a game's assets near 25 MB. Admit in an isolated project (`assets import-meshy <dir> --into <assets-dir> --prefix <game> --name <role>`), never from the repo root while other work is open.
-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(...)`).
-6. Prevent fog whitewash, overexposure, and instanced emissive blowout:
-   - If a fast route whitewashes, pass `{ fogDensityScale: 0, exposureEv: -0.1 }` to `looks.preset(...)` for that route. Never pin post-processing, the compiler or fog off for every player with a `qualityRebuild.flags` list: it hides bugs and flattens the look. Install `installSafetyNet` from `@aura3d/debug` so a machine that renders black steps down one rung on its own and `?diag=1` shows the GPU, limits and shader failures.
-   - Never set `emissive: "#ffffff"` with high `emissiveIntensity` on an instanced pool material (`instances.box` / `primitives.box({ instances })`): per-instance `instanceColors` multiply `u_baseColor`, not `u_emissiveColor`.
-7. Ground `model()` feet on platform top surfaces (`y + sy / 2`) & wind custom meshes CCW:
-   - `model(asset, { targetHeight })` normalizes the GLB with `minY = 0` (feet at `position[1]`), whereas `primitives.box` and `primitives.cylinder` (`instances.box` / `instances.cylinder`) are centered on `[-0.5..+0.5]` so a platform at `(y, sy)` has its top surface at `y + sy / 2`. Always place grounded characters and vehicles at `platform.y + platform.sy / 2` so they never sink into logs, pads, or road lanes. Wind custom `primitives.mesh` triangles CCW when viewed from `+Y`.
-8. Enforce full-viewport `100vw × 100vh` canvas, deep ground apron, and pushbox separation:
-   - Size `html, body, #app, canvas` to `100vw × 100vh` (`position: fixed; inset: 0; overflow: hidden`) and extend the 3D ground/stage apron deep enough in `+Z`/`-Z` under the camera frustum so the bottom third of the viewport never shows a black clear-color void. Disable `collision: true` on `camera.rigs.shoulder` when the target character has attached child runtime nodes, and enforce `>= 1.4m` fighter pushbox separation (`|x| >= 1.8m` at spawn).
-
-
-Aura3D 4.1 kits (build the shell from these, do not hand-roll it):
-
-- `@aura3d/engine/game`: `createGame` (lifecycle, pause, results, DOM HUD, touch, juice, game sound); the root `createGame` is a headless stub.
-- `@aura3d/engine`: `createFixedStepLoop`, `installQaHooks` (`window.__AURA_<NAME>__`), `readQaParams`, `createCountedRng` for deterministic replay and automated checks; `defineModelAssets` for hashed same-origin models with a `?models=0` procedural fallback; `scatterAlongPath`, `scatterInArea`, `splitScatterByDistance`, `mergeStatic` for draw-call budgets; `game.racketSports()` with `ballFlight`, `scoring`, `athleteRig`.
+- `npx @aura3d/cli@latest assets search "<object>"` searches licence-tagged open public sources and a starter pack; results are candidates to check, and there is no Aura3D-run search service to rely on.
+- `assets resolve "<object>" --name <name>` pulls the top match and types it as `assets.<name>`.
+- `assets add ./assets/model.glb --name model` adds a local file; then read the generated `src/aura-assets.ts`.
+- No catalog match: generate with Meshy (`meshy-cli` skill), optimize (`assets optimize --file in.glb --out out.glb --role <role>`), then admit (`assets import-meshy`).
+- Production needs every model to have a same-origin URL, a 64-character sha256 and provenance, otherwise it draws nothing.
+
+## Kits (build the shell from these)
+
+- `@aura3d/engine/game`: `createGame` (lifecycle, pause, results, DOM HUD, touch, juice, game sound).
+- `@aura3d/engine`: `createFixedStepLoop`, `installQaHooks`, `readQaParams`, `createCountedRng` (deterministic replay); `defineModelAssets`; `game.racketSports()`, `game.platformer`, `game.racing`, `game.fallingBlocks`, `game.fighting`; `effects.toon`.
 - `@aura3d/engine/audio`: `createCueBank`, `createStepSequencer`, `createToneLoop`, `createSampleSlices` on the single `AudioContextManager` (never `new AudioContext(`).
-- `@aura3d/debug`: `installSafetyNet` (`?diag=1`, quality switches `?post=0 ?shadow=0 ?env=0 ?sky=0 ?quality=low`, black-frame self-heal).
-- `material.custom` shaders: `#include <a3d_math>`, `<a3d_noise>`, `<a3d_sky>`, `<a3d_fog>`, `<a3d_triplanar>`, `<a3d_toon>`, `<colorspace_decode>`; custom shaders write linear light, so use `a3dSrgbToLinear` with `toneMapping: "none"` for authored colours, and keep `pow`, `normalize`, `sqrt` and divides NaN-safe (Apple GPUs return NaN where software renderers do not).
-- Production checks that CI missed: the bridge refuses http(s) or unhashed model URLs and then draws nothing; instanced and batched meshes honour texture maps; empty instance arrays are no-ops; software-GL passes are not real-GPU proof. Docs: `docs/api/game-kit.md`, `qa-kit.md`, `safety-net.md`, `audio-synth.md`, `model-loader.md`, `glsl-chunks.md`, `scatter-merge.md`, `cli-asset-tools.md`; pitfalls: `aura3d-core/references/pitfalls.md`.
+- `@aura3d/debug`: `installSafetyNet` (`?diag=1`, quality switches, black-frame self-heal).
+- `material.custom` shaders: `#include <a3d_math>`, `<a3d_noise>`, `<a3d_sky>`, `<a3d_fog>`, `<a3d_toon>`; keep `pow`, `normalize`, `sqrt` and divides NaN-safe.
+- Scatter and merge helpers (`scatterAlongPath`, `scatterInArea`, `mergeStatic`) are exported from the root; the root currently annotates them `@deprecated` (removal planned for 5.0.0), so check `docs/api/public-api.md` before relying on them.
+
+Details: `docs/api/game-kit.md`, `qa-kit.md`, `safety-net.md`, `audio-synth.md`, `model-loader.md`, `glsl-chunks.md`, `scatter-merge.md`, `cli-asset-tools.md`, `toon.md`.
+
+## Look-dev loop
 
-Claims: use every feature freely. Claim only what a judged capture shows.
+1. Pick a genre look and 1 to 3 reference frames; write a three-line brief.
+2. Build with the look preset and typed assets.
+3. Capture frames, judge each against the rubric, fix the single highest-leverage thing, repeat.
+4. Stop when every category reads 7 or higher or the loop exits flat. Skill: `aura3d-art-direction`.
 
-- Label every capability as one of: `createAuraApp` root safe API,
-  `production-runtime`, `rendering` internals, CLI asset pipeline, template-only
-  scaffold, prototype, or roadmap.
+## 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.
+- A compiling route is not proof: route health, typed provenance and a readable frame are required.
+- Comparison numbers against three.js exist only in `evidence/vs-threejs/RESULTS.md`: software WebGL2, one author, five small scenes. They are not GPU results and not a general "less code" or "faster" claim.
 
 Release integrity rules:
 - no raw string asset IDs, raw GLB/glTF URLs, `unsafeModelUrl(...)`, `three` imports, or `GLTFLoader` in public examples;
@@ -237,17 +128,14 @@ Release integrity rules:
 - 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) |
 
+## More
 
-
-
-
-
-
+- Full agent guide, genre recipes, guardrails and the page and example map: https://aura3d.auraone.ai/llms-full.txt
+- Docs: https://aura3d.auraone.ai/docs/api.html, https://aura3d.auraone.ai/docs/agent-quickstart.html, https://aura3d.auraone.ai/docs/claims.html
+- Showcase (26 playable games): https://aura3d.auraone.ai/apps/showcase-index/
+- Sitemap: https://aura3d.auraone.ai/sitemap.xml; crawl policy: https://aura3d.auraone.ai/robots.txt
+- Last updated: 2026-10-25