@aura3d/engine 3.0.0 → 4.0.0

package/dist/aura3d-cli/index.js

@@ -1,8 +1,16 @@
 import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { dirname, extname, join, relative, resolve } from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { dirname, extname, join, relative, resolve, sep } from "node:path";
 import { inflateSync } from "node:zlib";
+import { writeAgentSkills } from "create-aura3d";
+import { measureLoudness } from "../audio/index.js";
 import { admitAssetForRole } from "./asset-role-admission.js";
+import { hasStylizedFlatApproval } from "./admission/artDirection.js";
+import { AUDIO_SYNTH_RELEASE_ALLOWLIST, isSynthesizedAudioProvenance } from "./admission/audio.js";
+import { profileForRole, requiresPbrTextures } from "./admission/profiles.js";
 import { DEFAULT_AURA_ASSET_MANIFEST, DEFAULT_AURA_ASSET_OUTPUT_DIR, DEFAULT_AURA_ASSET_PUBLIC_PATH, DEFAULT_AURA_ASSET_TYPEGEN } from "./asset-constants.js";
 import { shouldScanSource, validateAssetSource } from "./asset-source-validation.js";
 import { listAssets, readAssetManifest, writeAssetManifest, writeTypedAssets } from "./asset-manifest.js";
@@ -99,6 +107,39 @@ export function readRenderedProbeMetadata(options) {
         ...(foregroundBounds ? { foregroundBounds } : {})
     };
 }
+/**
+ * BS.1770 loudness + true-peak for `assets add --type audio` — the same
+ * decode→measureLoudness path `sfx admit` uses (48 kHz f32 PCM). Returns
+ * `loudnessMeasured: true` even when integrated LUFS is unmeasurable
+ * (sub-400 ms files), so a short blip records a measured-null rather than
+ * looking unmeasured to the C-25 release gate. `undefined` when ffmpeg is
+ * missing or the file will not decode.
+ */
+function measureAudioLoudness(sourcePath) {
+    try {
+        const channelCount = Number(execFileSync("ffprobe", ["-v", "error", "-select_streams", "a:0", "-show_entries", "stream=channels", "-of", "csv=p=0", sourcePath], {
+            maxBuffer: 1 << 24
+        })
+            .toString("utf8")
+            .trim()) || 1;
+        const pcm = execFileSync("ffmpeg", ["-hide_banner", "-loglevel", "error", "-y", "-i", sourcePath, "-f", "f32le", "-ac", String(channelCount), "-ar", "48000", "-"], { maxBuffer: 1 << 28 });
+        const channels = Array.from({ length: channelCount }, (_, c) => {
+            const out = new Float32Array(pcm.length / 4 / channelCount);
+            for (let i = 0; i < out.length; i++)
+                out[i] = pcm.readFloatLE((i * channelCount + c) * 4);
+            return out;
+        });
+        const measured = measureLoudness({ channels, sampleRate: 48_000 });
+        return {
+            loudnessMeasured: true,
+            ...(Number.isFinite(measured.lufs) ? { loudnessLufs: measured.lufs } : {}),
+            truePeakDb: measured.truePeakDb
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
 export function addAsset(options) {
     const projectDir = resolve(options.projectDir ?? process.cwd());
     const sourcePath = resolve(projectDir, options.file);
@@ -170,6 +211,29 @@ export function addAsset(options) {
         ...(options.suitabilityReason ?? existing?.suitabilityReason ? { suitabilityReason: options.suitabilityReason ?? existing?.suitabilityReason } : {}),
         ...(options.renderedProbe ?? existing?.renderedProbe ? { renderedProbe: options.renderedProbe ?? existing?.renderedProbe } : {}),
         ...(options.gameGeometry ?? existing?.gameGeometry ? { gameGeometry: options.gameGeometry ?? existing?.gameGeometry } : {}),
+        ...(options.artDirection ?? existing?.artDirection ? { artDirection: options.artDirection ?? existing?.artDirection } : {}),
+        /*
+         * `#165`/C-25: audio entries carry a measured loudness record — `assets
+         * add --type audio` runs BS.1770 itself (ffmpeg decode + measureLoudness),
+         * and `--loudness-lufs`/`--true-peak-db` remain manual overrides that win
+         * over the measured values.
+         */
+        ...(type === "audio"
+            ? (() => {
+                const measured = measureAudioLoudness(sourcePath);
+                const supplied = options.audio ?? existing?.audio;
+                const merged = { ...measured, ...supplied };
+                return Object.keys(merged).length > 0 ? { audio: merged } : {};
+            })()
+            : options.audio ?? existing?.audio
+                ? { audio: options.audio ?? existing?.audio }
+                : {}),
+        // C-17 clip objects: written only when the inspection produced real
+        // durations (the lane-06 inspector hook, Q-05-1); a prior richer record is
+        // preserved on re-add.
+        ...(c17AnimationClips(inspection.animation) ?? existing?.animationClips
+            ? { animationClips: c17AnimationClips(inspection.animation) ?? existing?.animationClips }
+            : {}),
         warnings: createAssetWarnings(sourcePath, inspection)
     };
     if (options.orientation) {
@@ -182,7 +246,9 @@ export function addAsset(options) {
         }
     }
     const manifest = sortManifest({
-        schema: "aura3d.assets/1.0",
+        // C-17 stub rule: the stored schema is preserved/1.0 until the writer
+        // upgrades under A3D_QR_ASSETS (`writeAssetManifest` decides).
+        schema: current.schema ?? "aura3d.assets/1.0",
         assetBasePath: publicPath,
         outputDir,
         typegen,
@@ -691,11 +757,31 @@ export function validateAssets(options = {}) {
         }
         if (release)
             warnings.push(...createDurableReleaseProvenanceWarnings(asset, provenance));
+        // R-09-1 (lane 09): synthesized audio may not hold `release` unless the id
+        // is on the admission allowlist.
+        if (release && asset.type === "audio" && isSynthesizedAudioProvenance(provenance) && !AUDIO_SYNTH_RELEASE_ALLOWLIST.includes(asset.id)) {
+            warnings.push(`${asset.id}: release audio asset has synthesized provenance without an admission allowlist entry.`);
+        }
+        // #165 (C-25 sfx provenance, adopted from lane 09's `sfx admit`): a
+        // release audio entry requires license + sourceUrl + author + loudness
+        // measurements on its `audio` block.
+        if (release && asset.type === "audio") {
+            const meta = asset.audio;
+            const missingAudio = [
+                !hasUsableLicenseEvidence(provenance) ? "license" : undefined,
+                !(provenance?.sourceUrl || provenance?.sourcePage || meta?.sourceUrl) ? "sourceUrl" : undefined,
+                !(provenance?.author || meta?.author) ? "author" : undefined,
+                meta?.loudnessLufs === undefined && meta?.loudnessMeasured !== true ? "loudnessLufs" : undefined,
+                meta?.truePeakDb === undefined ? "truePeakDb" : undefined,
+            ].filter(Boolean);
+            if (missingAudio.length)
+                failures.push(`${asset.id}: release audio missing C-25 provenance fields: ${missingAudio.join(", ")}.`);
+        }
         warnings.push(...createDerivedMetadataDriftWarnings(outputPath, asset));
         if (release)
-            warnings.push(...createReleaseStructuredQualityWarnings(asset));
+            warnings.push(...createReleaseStructuredQualityWarnings(projectDir, asset));
         if (release)
-            warnings.push(...createReleaseAssetQualityWarnings(asset));
+            warnings.push(...createReleaseAssetQualityWarnings(projectDir, asset));
         if (release)
             warnings.push(...createReleaseRenderedProbeWarnings(projectDir, manifest, asset));
         if (release)
@@ -707,7 +793,7 @@ export function validateAssets(options = {}) {
         const tempProvenance = createTempProvenanceWarning(asset, provenance);
         if (tempProvenance)
             warnings.push(tempProvenance);
-        const storedWarnings = release ? releaseStoredAssetWarnings(asset) : asset.warnings ?? [];
+        const storedWarnings = release ? releaseStoredAssetWarnings(projectDir, asset) : asset.warnings ?? [];
         warnings.push(...storedWarnings.map((warning) => `${asset.id}: ${warning}`));
         if (asset.format === "gltf") {
             for (const dependency of asset.dependencies ?? asset.textures) {
@@ -781,7 +867,9 @@ export function checkDeploy(options = {}) {
     const distDir = normalizeRelativePath(options.distDir ?? "dist");
     const failures = [];
     const warnings = [];
+    const referencedServed = new Set();
     for (const asset of manifest.assets) {
+        referencedServed.add(normalizeServedUrl(asset.url));
         const distPath = resolve(projectDir, distDir, asset.url.replace(/^\//, ""));
         const publicPath = resolve(projectDir, asset.outputPath);
         if (!existsSync(distPath) && !existsSync(publicPath)) {
@@ -789,6 +877,41 @@ export function checkDeploy(options = {}) {
         }
         if (!/[a-f0-9]{8}\.[^.]+$/i.test(asset.url))
             warnings.push(`${asset.id}: URL is not fingerprinted: ${asset.url}`);
+        // §6.8: copy referenced derived files (url/mobile/collision) into the dist
+        // tree so a deploy ships exactly what the manifest points at.
+        const derived = asset.derived;
+        if (derived) {
+            for (const served of [derived.url, derived.mobileUrl, derived.collisionUrl]) {
+                if (!served)
+                    continue;
+                referencedServed.add(normalizeServedUrl(served));
+                const target = resolve(projectDir, distDir, served.replace(/^\//, ""));
+                const derivedOutput = served === derived.url && derived.outputPath
+                    ? derived.outputPath
+                    : join(dirname(derived.outputPath ?? join("public", manifest.assetBasePath)), served.split("/").pop() ?? served);
+                const source = resolve(projectDir, derivedOutput);
+                if (!existsSync(source)) {
+                    failures.push(`Deploy check missing derived asset for "${asset.id}": expected ${derivedOutput} (url ${served})`);
+                    continue;
+                }
+                if (!existsSync(target) || !sameBytes(source, target)) {
+                    mkdirSync(dirname(target), { recursive: true });
+                    copyFileSync(source, target);
+                }
+            }
+        }
+    }
+    // §6.8: schema 1.1 manifests make the deploy subset exact — a file in
+    // <dist>/<assetBasePath> that no manifest entry references fails the check.
+    if (manifest.schema === "aura3d.assets/1.1") {
+        const base = manifest.assetBasePath.replace(/\/$/, "");
+        const servedRoot = resolve(projectDir, distDir, base.replace(/^\//, ""));
+        for (const file of walkFilesUnder(servedRoot)) {
+            const asServed = normalizeServedUrl(`${base}${file.slice(servedRoot.length).split(sep).join("/")}`);
+            if (!referencedServed.has(asServed)) {
+                failures.push(`Deploy check found unreferenced file in ${distDir}: ${file.slice(projectDir.length + 1)}`);
+            }
+        }
     }
     const validation = validateAssets({
         projectDir,
@@ -905,20 +1028,27 @@ export function createCharacterAssemblyPlan(options) {
     };
 }
 export function initAgentFiles(options) {
+    return initAgentSetup(options).written;
+}
+export function initAgentSetup(options) {
     const projectDir = resolve(options.projectDir ?? process.cwd());
     const targets = options.agent === "all" ? ["generic", "claude", "cursor", "copilot"] : [options.agent];
     const written = [];
+    const mode = options.skills ?? "core";
     for (const target of targets) {
         if (target === "generic")
-            written.push(writeAgentFile(projectDir, "AGENTS.md", genericAgentText()));
+            written.push(writeAgentFile(projectDir, "AGENTS.md", genericAgentText("AI coding agent", mode !== "none" ? ".agents/skills" : undefined)));
         if (target === "claude")
-            written.push(writeAgentFile(projectDir, ".claude/CLAUDE.md", genericAgentText("Claude")));
+            written.push(writeAgentFile(projectDir, ".claude/CLAUDE.md", genericAgentText("Claude", mode !== "none" ? ".claude/skills" : undefined)));
         if (target === "cursor")
-            written.push(writeAgentFile(projectDir, ".cursor/rules/aura3d.mdc", genericAgentText("Cursor")));
+            written.push(writeAgentFile(projectDir, ".cursor/rules/aura3d.mdc", genericAgentText("Cursor", mode !== "none" ? ".cursor/skills" : undefined)));
         if (target === "copilot")
-            written.push(writeAgentFile(projectDir, ".github/copilot-instructions.md", genericAgentText("GitHub Copilot")));
+            written.push(writeAgentFile(projectDir, ".github/copilot-instructions.md", genericAgentText("GitHub Copilot", mode !== "none" ? ".github/skills" : undefined)));
     }
-    return written;
+    if (mode === "none")
+        return { written, skills: [], skippedUserModified: [] };
+    const result = writeAgentSkills({ projectDir, agent: options.agent, skills: mode, template: options.template, skillsDir: options.skillsDir });
+    return { written: [...written, ...result.written], skills: result.skills, skippedUserModified: result.skippedUserModified };
 }
 function validateAssetReadiness(profile, options) {
     const projectDir = resolve(options.projectDir ?? process.cwd());
@@ -1758,9 +1888,21 @@ function inspectGlb(buffer, baseDir) {
     if (chunkType !== "JSON")
         throw new Error("Invalid GLB JSON chunk. Suggested fix: re-export the GLB.");
     const json = JSON.parse(buffer.toString("utf8", 20, 20 + chunkLength).trim());
-    return inspectGltf(json, baseDir);
+    // Q-05-1 (lane 06): carry the BIN chunk through so the enriched clip
+    // inspector can read sampler input times (duration/frameRate).
+    let offset = 20 + chunkLength;
+    let bin;
+    while (offset + 8 <= buffer.length && offset + 8 <= length) {
+        const chunkLen = buffer.readUInt32LE(offset);
+        if (buffer.readUInt32LE(offset + 4) === 0x004e4942) {
+            bin = buffer.subarray(offset + 8, offset + 8 + chunkLen);
+            break;
+        }
+        offset += 8 + chunkLen;
+    }
+    return inspectGltf(json, baseDir, bin);
 }
-function inspectGltf(json, baseDir) {
+function inspectGltf(json, baseDir, bin) {
     const dependencies = [
         ...(json.images ?? []).map((image) => image.uri).filter(isExternalUri),
         ...(json.buffers ?? []).map((buffer) => buffer.uri).filter(isExternalUri)
@@ -1778,7 +1920,7 @@ function inspectGltf(json, baseDir) {
         materials: (json.materials ?? []).map((material, index) => material.name ?? `material-${index}`),
         materialMetadata: inspectGltfMaterials(json),
         animations: (json.animations ?? []).map((animation, index) => animation.name ?? `clip-${index}`),
-        animation: inspectGltfAnimations(json),
+        animation: inspectGltfAnimations(json, bin),
         humanoid: inspectGltfHumanoid(json),
         skeleton: inspectGltfSkeleton(json),
         morphTargets: inspectGltfMorphTargets(json),
@@ -1797,7 +1939,33 @@ function emptyAnimationInspection() {
         messages: ["No embedded animation clips detected."]
     };
 }
-function inspectGltfAnimations(json) {
+let lane06ClipInspector;
+function inspectLane06AnimationClips(json, bin) {
+    if (lane06ClipInspector === undefined) {
+        lane06ClipInspector = null;
+        try {
+            const require = createRequire(import.meta.url);
+            const mod = require("./commands/prd06/inspectAnimationClips.js");
+            if (typeof mod?.inspectAnimationClips === "function") {
+                lane06ClipInspector = mod.inspectAnimationClips;
+            }
+        }
+        catch {
+            lane06ClipInspector = null;
+        }
+    }
+    if (!lane06ClipInspector)
+        return undefined;
+    try {
+        const result = lane06ClipInspector(json, bin);
+        return Array.isArray(result) ? result : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function inspectGltfAnimations(json, bin) {
+    const lane06Clips = inspectLane06AnimationClips(json, bin);
     const clips = (json.animations ?? []).map((animation, index) => {
         const channels = animation.channels ?? [];
         const targetPaths = uniqueStrings(channels.map((channel) => channel.target?.path).filter(isString));
@@ -1805,13 +1973,18 @@ function inspectGltfAnimations(json) {
             const nodeIndex = channel.target?.node;
             return typeof nodeIndex === "number" ? json.nodes?.[nodeIndex]?.name ?? `node-${nodeIndex}` : undefined;
         }).filter(isString));
+        const name = animation.name ?? `clip-${index}`;
+        const enriched = lane06Clips?.find((clip) => clip.index === index || clip.name === name);
         return {
             index,
-            name: animation.name ?? `clip-${index}`,
+            name,
             channelCount: channels.length,
             samplerCount: animation.samplers?.length ?? 0,
             targetPaths,
-            targetNodes
+            targetNodes,
+            ...(typeof enriched?.duration === "number" ? { duration: enriched.duration } : {}),
+            ...(typeof enriched?.hasRootMotionCandidate === "boolean" ? { hasRootMotionCandidate: enriched.hasRootMotionCandidate } : {}),
+            ...(typeof enriched?.frameRate === "number" ? { frameRate: enriched.frameRate } : {})
         };
     });
     return {
@@ -1822,6 +1995,18 @@ function inspectGltfAnimations(json) {
             : [`Detected ${clips.length} embedded animation clip${clips.length === 1 ? "" : "s"}.`]
     };
 }
+/**
+ * C-17 `animationClips` manifest objects (Q-05-1). Emitted only when every
+ * clip carries a real duration from the lane-06 inspector — the names-only
+ * Phase-0 inspection does not fabricate `duration: 0`.
+ */
+function c17AnimationClips(inspection) {
+    if (inspection.clipCount === 0)
+        return undefined;
+    if (!inspection.clips.every((clip) => typeof clip.duration === "number" && Number.isFinite(clip.duration)))
+        return undefined;
+    return inspection.clips.map((clip) => ({ name: clip.name, duration: clip.duration ?? 0, channelCount: clip.channelCount }));
+}
 function inspectGltfHumanoid(json) {
     const skinCount = json.skins?.length ?? 0;
     const jointIndexes = uniqueNumbers((json.skins ?? []).flatMap((skin) => skin.joints ?? []));
@@ -2351,7 +2536,11 @@ function createAssetWarnings(path, inspection) {
     const size = statSync(path).size;
     if (size > 25 * 1024 * 1024)
         warnings.push("asset exceeds 25 MB; consider compression before deployment");
-    if (!inspection.bounds)
+    // Bounds are only meaningful on geometry-bearing formats — audio/texture
+    // files can never produce them, so warning (and release-blocking) on them
+    // is noise, matching the format scoping the texture/orientation warnings
+    // below already use.
+    if (!inspection.bounds && ["glb", "gltf"].includes(extname(path).slice(1).toLowerCase()))
         warnings.push("bounds could not be extracted");
     if (inspection.textures.length === 0 && ["glb", "gltf"].includes(extname(path).slice(1).toLowerCase()))
         warnings.push("no texture references detected");
@@ -2643,7 +2832,7 @@ function createDerivedMetadataDriftWarnings(outputPath, asset) {
     }
     return warnings;
 }
-function createReleaseStructuredQualityWarnings(asset) {
+function createReleaseStructuredQualityWarnings(projectDir, asset) {
     if (asset.type !== "model")
         return [];
     const warnings = [];
@@ -2663,7 +2852,7 @@ function createReleaseStructuredQualityWarnings(asset) {
     }
     return warnings;
 }
-function createReleaseAssetQualityWarnings(asset) {
+function createReleaseAssetQualityWarnings(projectDir, asset) {
     if (asset.type !== "model")
         return [];
     const warnings = [];
@@ -2688,8 +2877,17 @@ function createReleaseAssetQualityWarnings(asset) {
     if (asset.materialMetadata?.some((material) => !material.visible || !material.readable)) {
         warnings.push(`${asset.id}: release primary model has invisible or unreadable material metadata.`);
     }
-    if (["glb", "gltf"].includes(asset.format) && asset.textures.length === 0 && !hasHashBoundFlatColorMaterialEvidence(asset)) {
-        warnings.push(`${asset.id}: release primary model has no texture references; use only with explicit material/readability evidence.`);
+    if (["glb", "gltf"].includes(asset.format) && asset.textures.length === 0) {
+        // PRD-05 Phase 0: the hash-bound flat-color evidence waiver is deleted.
+        // The check fails unless the role's profile does not require PBR coverage
+        // (G3 waived-by-role) or `artDirection` resolves to a `stylized-flat`
+        // document with an approved look-dev record (G10).
+        const role = asset.role ?? "unknown";
+        const size = asset.boundsMetadata?.size ?? asset.bounds;
+        const profile = profileForRole(role, size);
+        if (requiresPbrTextures(role, profile) && !hasStylizedFlatApproval(projectDir, asset)) {
+            warnings.push(`${asset.id}: release primary model has no texture references; admit through assets admit (G3) or declare a stylized-flat artDirection with an approved look-dev record.`);
+        }
     }
     return warnings;
 }
@@ -2846,32 +3044,18 @@ function hasValidManifestOrientationOverride(asset) {
     return createManifestOrientationOverrideWarnings(asset).length === 0 &&
         asset.orientation?.source === "manifest-override";
 }
-function releaseStoredAssetWarnings(asset) {
+function releaseStoredAssetWarnings(projectDir, asset) {
     let warnings = asset.warnings ?? [];
     if (hasValidManifestOrientationOverride(asset)) {
         warnings = warnings.filter((warning) => !/orientation metadata missing; facing direction cannot be validated/i.test(warning));
     }
-    if (hasHashBoundFlatColorMaterialEvidence(asset)) {
+    // G10: an approved stylized-flat artDirection + look-dev record sanctions
+    // the absence of textures — the stored no-texture warning stops blocking.
+    if (hasStylizedFlatApproval(projectDir, asset)) {
         warnings = warnings.filter((warning) => !/^no texture references detected$/i.test(warning.trim()));
     }
     return warnings;
 }
-function hasHashBoundFlatColorMaterialEvidence(asset) {
-    if (asset.materials.length === 0)
-        return false;
-    const materialMetadata = asset.materialMetadata ?? [];
-    if (materialMetadata.length < asset.materials.length)
-        return false;
-    if (materialMetadata.some((material) => !nonEmpty(material.name) || material.visible !== true || material.readable !== true ||
-        typeof material.opacity !== "number" || material.opacity <= 0))
-        return false;
-    const probe = asset.renderedProbe;
-    return nonEmpty(probe?.url) &&
-        nonEmpty(probe?.sha256) &&
-        nonEmpty(probe?.assetHash) &&
-        probe?.assetHash === asset.hash &&
-        ["browser-screenshot", "aura-probe-render"].includes(String(probe?.kind));
-}
 function createRenderedProbeForegroundWarnings(assetId, foregroundBounds, probeMetrics) {
     if (!foregroundBounds)
         return [];
@@ -2900,7 +3084,6 @@ function createRenderedProbeForegroundWarnings(assetId, foregroundBounds, probeM
     return warnings;
 }
 function createRoleAwareReleaseQualityWarnings(projectDir, manifest, asset) {
-    void projectDir;
     void manifest;
     if (asset.type !== "model" || asset.quality !== "release")
         return [];
@@ -2909,6 +3092,7 @@ function createRoleAwareReleaseQualityWarnings(projectDir, manifest, asset) {
     const suitabilityReason = asset.suitabilityReason?.trim() ?? "";
     const size = asset.boundsMetadata?.size ?? asset.bounds;
     const dimensions = createRoleAwareDimensions(size);
+    const profile = profileForRole(role, dimensions);
     const hasMaterialEvidence = asset.materials.length > 0 && !(asset.materialMetadata?.every((material) => !material.visible || !material.readable) ?? false);
     const hasTextureEvidence = asset.textures.length > 0 || (asset.hierarchy?.textureCount ?? 0) > 0;
     if (role === "unknown") {
@@ -2941,8 +3125,13 @@ function createRoleAwareReleaseQualityWarnings(projectDir, manifest, asset) {
     if (requiresMaterialEvidence(role) && !hasMaterialEvidence) {
         warnings.push(`${asset.id}: role-aware release ${role} validation requires readable material evidence.`);
     }
-    if (requiresTextureEvidence(role, suitabilityReason) && !hasTextureEvidence) {
-        warnings.push(`${asset.id}: role-aware release ${role} validation requires texture evidence or explicit stylized-material rationale.`);
+    // PRD-05 Phase 0: `requiresTextureEvidence` (the stylized-suitabilityReason
+    // regex waiver) is deleted — texture requirements now come from the §6.2
+    // role profile, matching G3. An approved stylized-flat artDirection + look-dev
+    // record is the only remaining exemption (G10).
+    const stylizedFlatApproved = hasStylizedFlatApproval(projectDir, asset);
+    if (requiresPbrTextures(role, profile) && !hasTextureEvidence && !stylizedFlatApproved) {
+        warnings.push(`${asset.id}: role-aware release ${role} validation requires texture evidence.`);
     }
     if (requiresForwardOrientation(role) && !hasForwardOrientationEvidence(asset, suitabilityReason)) {
         warnings.push(`${asset.id}: role-aware release ${role} validation requires orientation/forward-axis evidence.`);
@@ -3066,14 +3255,6 @@ function hasRoleAwareSuitabilityReason(role, suitabilityReason) {
 function requiresMaterialEvidence(role) {
     return role !== "debug" && role !== "abstract";
 }
-function requiresTextureEvidence(role, suitabilityReason) {
-    if (role === "debug" || role === "abstract")
-        return false;
-    if (/\b(stylized|stylised|flat[-\s]?color|flat[-\s]?colour|untextured|procedural material|clay render|solid material)\b/i.test(suitabilityReason)) {
-        return false;
-    }
-    return role === "character" || role === "vehicle" || role === "product" || role === "track" || role === "world" || role === "environment" || role === "weapon";
-}
 function requiresForwardOrientation(role) {
     return role === "character" || role === "vehicle" || role === "weapon";
 }
@@ -3324,6 +3505,30 @@ function normalizePublicPath(path) {
     const withStart = path.startsWith("/") || path.startsWith("http") ? path : `/${path}`;
     return withStart.endsWith("/") ? withStart : `${withStart}/`;
 }
+function normalizeServedUrl(url) {
+    const withSlash = url.startsWith("/") ? url : `/${url}`;
+    return withSlash.replace(/\/+/g, "/");
+}
+function sameBytes(a, b) {
+    const as = statSync(a);
+    const bs = statSync(b);
+    return as.size === bs.size && readFileSync(a).equals(readFileSync(b));
+}
+function* walkFilesUnder(dir) {
+    if (!existsSync(dir))
+        return;
+    const stack = [dir];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        for (const entry of readdirSync(current, { withFileTypes: true })) {
+            const path = join(current, entry.name);
+            if (entry.isDirectory())
+                stack.push(path);
+            else if (entry.isFile())
+                yield path;
+        }
+    }
+}
 function normalizeRelativePath(path) {
     return path.replaceAll("\\", "/").replace(/^\.\//, "");
 }
@@ -3339,29 +3544,24 @@ function writeAgentFile(projectDir, path, contents) {
     writeFileSync(output, contents);
     return output;
 }
-function genericAgentText(agent = "AI coding agent") {
+function genericAgentText(agent = "AI coding agent", skillsPath) {
+    const skillsLine = skillsPath
+        ? `Load the Aura3D skills in ./${skillsPath}/ on demand. Start with aura3d-core; it routes to the task skill (scene authoring, assets, evidence review, games, animation, migration, materials, performance).\n`
+        : "";
+    // Q-05-1 (#242): the body is the canonical agent file shipped in
+    // skills/agent-files/AGENTS.md (PRD-13 T2.15), not a copy — scaffolded
+    // files can never drift from it again. Its own `# ` title line is dropped;
+    // the per-agent prelude keeps the heading + skills path.
+    // Both src/index.ts (tsx) and dist/index.js sit one level below the package
+    // root, whose published `files` include `skills/`.
+    const canonicalPath = resolve(fileURLToPath(import.meta.url), "..", "..", "skills", "agent-files", "AGENTS.md");
+    if (!existsSync(canonicalPath)) {
+        throw new Error(`canonical agent file not found at ${canonicalPath}`);
+    }
+    const canonical = readFileSync(canonicalPath, "utf8").replace(/^#[^\n]*\n+/, "").trimEnd();
     return `# Aura3D Instructions For ${agent}
 
-Read ./llms.txt first, then ./docs/agents/README.md.
-
-Use @aura3d/engine public imports only:
-- createAuraApp
-- scene
-- model
-- camera
-- lights
-- material
-- effects
-- timeline
-- interactions
-- defineAuraAssets
-
-Do not invent asset paths or asset ids. Read ./src/aura-assets.ts after running:
-
-npx @aura3d/cli@latest assets add ./assets/model.glb --name model
-
-Use model(assets.model), not model("model").
-Run npm run build and the template route-health/screenshot tests before claiming the scene is done.
+${skillsLine}${canonical}
 `;
 }
 function escapeXml(value) {