blendops 0.0.0-stage → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (485) hide show
  1. package/CHANGELOG.md +74 -0
  2. package/LICENSE +21 -0
  3. package/README.md +208 -2
  4. package/bin/blendops.mjs +4 -0
  5. package/bundles/claude-desktop-manual/BLENDOPS_SINGLE_FILE.md +78 -0
  6. package/bundles/claude-desktop-manual/IMPORT_STEPS.md +43 -0
  7. package/bundles/claude-desktop-manual/INSTALL_REPORT_TEMPLATE.md +13 -0
  8. package/bundles/claude-desktop-manual/README.md +70 -0
  9. package/bundles/claude-desktop-manual/SKILL.md +62 -0
  10. package/bundles/claude-desktop-manual/manifest.json +278 -0
  11. package/bundles/claude-desktop-manual/references/evidence-rules.md +13 -0
  12. package/bundles/claude-desktop-manual/references/install-boundary.md +13 -0
  13. package/bundles/claude-desktop-manual/references/laws/evidence-before-done.md +14 -0
  14. package/bundles/claude-desktop-manual/references/laws/no-arbitrary-python-interface.md +12 -0
  15. package/bundles/claude-desktop-manual/references/laws/non-blender-user-language.md +13 -0
  16. package/bundles/claude-desktop-manual/references/laws/official-runtime-only.md +20 -0
  17. package/bundles/claude-desktop-manual/references/packs/product-hero-v0.md +30 -0
  18. package/bundles/claude-desktop-manual/references/runtime-stacks.md +13 -0
  19. package/bundles/claude-desktop-manual/references/skill-map.md +36 -0
  20. package/bundles/claude-desktop-manual/references/skills/acceptance-criteria-builder.md +69 -0
  21. package/bundles/claude-desktop-manual/references/skills/asset-discovery.md +73 -0
  22. package/bundles/claude-desktop-manual/references/skills/asset-fallback-strategy.md +66 -0
  23. package/bundles/claude-desktop-manual/references/skills/asset-library-plan.md +69 -0
  24. package/bundles/claude-desktop-manual/references/skills/asset-license-checker.md +69 -0
  25. package/bundles/claude-desktop-manual/references/skills/asset-style-check.md +69 -0
  26. package/bundles/claude-desktop-manual/references/skills/blender-brainstorming.md +62 -0
  27. package/bundles/claude-desktop-manual/references/skills/blender-recipe-decomposer.md +66 -0
  28. package/bundles/claude-desktop-manual/references/skills/blender-troubleshooting.md +78 -0
  29. package/bundles/claude-desktop-manual/references/skills/blendops-help.md +82 -0
  30. package/bundles/claude-desktop-manual/references/skills/bridge-conflicts.md +68 -0
  31. package/bundles/claude-desktop-manual/references/skills/camera-composition.md +65 -0
  32. package/bundles/claude-desktop-manual/references/skills/character-portrait.md +68 -0
  33. package/bundles/claude-desktop-manual/references/skills/cli-appendix-job-outline.md +62 -0
  34. package/bundles/claude-desktop-manual/references/skills/color-management-decision.md +68 -0
  35. package/bundles/claude-desktop-manual/references/skills/composition-quality-checker.md +71 -0
  36. package/bundles/claude-desktop-manual/references/skills/cycles-vs-eevee-decision.md +65 -0
  37. package/bundles/claude-desktop-manual/references/skills/done-criteria.md +70 -0
  38. package/bundles/claude-desktop-manual/references/skills/environment-shot.md +65 -0
  39. package/bundles/claude-desktop-manual/references/skills/glb-animation-handoff.md +69 -0
  40. package/bundles/claude-desktop-manual/references/skills/glb-web-handoff.md +68 -0
  41. package/bundles/claude-desktop-manual/references/skills/intent-to-3d-brief-writer.md +68 -0
  42. package/bundles/claude-desktop-manual/references/skills/interior-scene.md +73 -0
  43. package/bundles/claude-desktop-manual/references/skills/lighting-material-plan.md +65 -0
  44. package/bundles/claude-desktop-manual/references/skills/lighting-quality-checker.md +70 -0
  45. package/bundles/claude-desktop-manual/references/skills/material-quality-checker.md +71 -0
  46. package/bundles/claude-desktop-manual/references/skills/mobile-glb-budget.md +73 -0
  47. package/bundles/claude-desktop-manual/references/skills/output-format-decision.md +63 -0
  48. package/bundles/claude-desktop-manual/references/skills/pack-prerequisite-checker.md +74 -0
  49. package/bundles/claude-desktop-manual/references/skills/path-one-host-outline.md +66 -0
  50. package/bundles/claude-desktop-manual/references/skills/plain-language-response.md +70 -0
  51. package/bundles/claude-desktop-manual/references/skills/polycount-budget-checker.md +71 -0
  52. package/bundles/claude-desktop-manual/references/skills/pre-handoff-verification.md +76 -0
  53. package/bundles/claude-desktop-manual/references/skills/preview-report.md +62 -0
  54. package/bundles/claude-desktop-manual/references/skills/product-grid-scene-planner.md +72 -0
  55. package/bundles/claude-desktop-manual/references/skills/product-hero-scene-planner.md +68 -0
  56. package/bundles/claude-desktop-manual/references/skills/r3f-component-plan.md +66 -0
  57. package/bundles/claude-desktop-manual/references/skills/recipe-fit-assessor.md +75 -0
  58. package/bundles/claude-desktop-manual/references/skills/render-export-evidence.md +70 -0
  59. package/bundles/claude-desktop-manual/references/skills/resolution-aspect-decision.md +65 -0
  60. package/bundles/claude-desktop-manual/references/skills/runtime-attempt-report.md +67 -0
  61. package/bundles/claude-desktop-manual/references/skills/runtime-path-picker.md +67 -0
  62. package/bundles/claude-desktop-manual/references/skills/runtime-readiness.md +63 -0
  63. package/bundles/claude-desktop-manual/references/skills/runtime-setup.md +63 -0
  64. package/bundles/claude-desktop-manual/references/skills/scene-readiness.md +65 -0
  65. package/bundles/claude-desktop-manual/references/skills/scope-guard.md +62 -0
  66. package/bundles/claude-desktop-manual/references/skills/stage-gates.md +91 -0
  67. package/bundles/claude-desktop-manual/references/skills/workflow-stage-router.md +67 -0
  68. package/bundles/generic-project-local/BLENDOPS.md +71 -0
  69. package/bundles/generic-project-local/INSTALL_REPORT_TEMPLATE.md +52 -0
  70. package/bundles/generic-project-local/README.md +73 -0
  71. package/bundles/generic-project-local/ROLLBACK.md +66 -0
  72. package/bundles/generic-project-local/manifest.json +66 -0
  73. package/bundles/skill-package/README.md +54 -0
  74. package/bundles/skill-package/blendops/LICENSE.txt +21 -0
  75. package/bundles/skill-package/blendops/SKILL.md +50 -0
  76. package/bundles/skill-package/blendops/agents/README.md +61 -0
  77. package/bundles/skill-package/blendops/agents/openai.yaml +4 -0
  78. package/bundles/skill-package/blendops/references/evidence-rules.md +17 -0
  79. package/bundles/skill-package/blendops/references/install-boundary.md +13 -0
  80. package/bundles/skill-package/blendops/references/law-evidence-before-done.md +12 -0
  81. package/bundles/skill-package/blendops/references/law-no-arbitrary-python-interface.md +7 -0
  82. package/bundles/skill-package/blendops/references/law-non-blender-user-language.md +8 -0
  83. package/bundles/skill-package/blendops/references/law-official-runtime-only.md +9 -0
  84. package/bundles/skill-package/blendops/references/pack-product-hero-v0.md +21 -0
  85. package/bundles/skill-package/blendops/references/runtime-stacks.md +13 -0
  86. package/bundles/skill-package/blendops/references/skill-acceptance-criteria-builder.md +51 -0
  87. package/bundles/skill-package/blendops/references/skill-asset-discovery.md +54 -0
  88. package/bundles/skill-package/blendops/references/skill-asset-fallback-strategy.md +48 -0
  89. package/bundles/skill-package/blendops/references/skill-asset-library-plan.md +51 -0
  90. package/bundles/skill-package/blendops/references/skill-asset-license-checker.md +51 -0
  91. package/bundles/skill-package/blendops/references/skill-asset-style-check.md +52 -0
  92. package/bundles/skill-package/blendops/references/skill-blender-brainstorming.md +43 -0
  93. package/bundles/skill-package/blendops/references/skill-blender-recipe-decomposer.md +48 -0
  94. package/bundles/skill-package/blendops/references/skill-blender-troubleshooting.md +59 -0
  95. package/bundles/skill-package/blendops/references/skill-blendops-help.md +62 -0
  96. package/bundles/skill-package/blendops/references/skill-bridge-conflicts.md +48 -0
  97. package/bundles/skill-package/blendops/references/skill-camera-composition.md +48 -0
  98. package/bundles/skill-package/blendops/references/skill-character-portrait.md +50 -0
  99. package/bundles/skill-package/blendops/references/skill-cli-appendix-job-outline.md +44 -0
  100. package/bundles/skill-package/blendops/references/skill-color-management-decision.md +50 -0
  101. package/bundles/skill-package/blendops/references/skill-composition-quality-checker.md +53 -0
  102. package/bundles/skill-package/blendops/references/skill-cycles-vs-eevee-decision.md +47 -0
  103. package/bundles/skill-package/blendops/references/skill-done-criteria.md +53 -0
  104. package/bundles/skill-package/blendops/references/skill-environment-shot.md +47 -0
  105. package/bundles/skill-package/blendops/references/skill-glb-animation-handoff.md +51 -0
  106. package/bundles/skill-package/blendops/references/skill-glb-web-handoff.md +51 -0
  107. package/bundles/skill-package/blendops/references/skill-intent-to-3d-brief-writer.md +50 -0
  108. package/bundles/skill-package/blendops/references/skill-interior-scene.md +54 -0
  109. package/bundles/skill-package/blendops/references/skill-lighting-material-plan.md +48 -0
  110. package/bundles/skill-package/blendops/references/skill-lighting-quality-checker.md +52 -0
  111. package/bundles/skill-package/blendops/references/skill-map.md +32 -0
  112. package/bundles/skill-package/blendops/references/skill-material-quality-checker.md +53 -0
  113. package/bundles/skill-package/blendops/references/skill-mobile-glb-budget.md +55 -0
  114. package/bundles/skill-package/blendops/references/skill-output-format-decision.md +46 -0
  115. package/bundles/skill-package/blendops/references/skill-pack-prerequisite-checker.md +56 -0
  116. package/bundles/skill-package/blendops/references/skill-path-one-host-outline.md +48 -0
  117. package/bundles/skill-package/blendops/references/skill-plain-language-response.md +53 -0
  118. package/bundles/skill-package/blendops/references/skill-polycount-budget-checker.md +53 -0
  119. package/bundles/skill-package/blendops/references/skill-pre-handoff-verification.md +57 -0
  120. package/bundles/skill-package/blendops/references/skill-preview-report.md +45 -0
  121. package/bundles/skill-package/blendops/references/skill-product-grid-scene-planner.md +54 -0
  122. package/bundles/skill-package/blendops/references/skill-product-hero-scene-planner.md +51 -0
  123. package/bundles/skill-package/blendops/references/skill-r3f-component-plan.md +48 -0
  124. package/bundles/skill-package/blendops/references/skill-recipe-fit-assessor.md +57 -0
  125. package/bundles/skill-package/blendops/references/skill-render-export-evidence.md +51 -0
  126. package/bundles/skill-package/blendops/references/skill-resolution-aspect-decision.md +48 -0
  127. package/bundles/skill-package/blendops/references/skill-runtime-attempt-report.md +49 -0
  128. package/bundles/skill-package/blendops/references/skill-runtime-path-picker.md +49 -0
  129. package/bundles/skill-package/blendops/references/skill-runtime-readiness.md +45 -0
  130. package/bundles/skill-package/blendops/references/skill-runtime-setup.md +45 -0
  131. package/bundles/skill-package/blendops/references/skill-scene-readiness.md +48 -0
  132. package/bundles/skill-package/blendops/references/skill-scope-guard.md +44 -0
  133. package/bundles/skill-package/blendops/references/skill-stage-gates.md +73 -0
  134. package/bundles/skill-package/blendops/references/skill-workflow-stage-router.md +49 -0
  135. package/docs/README.md +276 -0
  136. package/docs/examples/glb-web-handoff/README.md +174 -0
  137. package/docs/examples/glb-web-handoff/r3f-glb-viewer.tsx +320 -0
  138. package/docs/examples/glb-web-handoff/threejs-glb-viewer.mjs +709 -0
  139. package/docs/knowledge-and-recipe-catalog.md +236 -0
  140. package/docs/recipes/README.md +27 -0
  141. package/docs/recipes/cyberpunk-shoe-hero.md +97 -0
  142. package/docs/workflows/README.md +14 -0
  143. package/docs/workflows/full-non-blender-user-workflow.md +210 -0
  144. package/docs/workflows/product-hero-workflow.md +92 -0
  145. package/laws/README.md +32 -0
  146. package/laws/evidence-before-done.md +37 -0
  147. package/laws/no-arbitrary-python-interface.md +32 -0
  148. package/laws/non-blender-user-language.md +32 -0
  149. package/laws/official-runtime-only.md +78 -0
  150. package/package.json +103 -4
  151. package/packs/README.md +11 -0
  152. package/packs/product-hero-v0/PACK.md +114 -0
  153. package/registry/catalog-index.json +21344 -0
  154. package/registry/compatibility-matrix.json +533 -0
  155. package/registry/contract-context-fields.json +391 -0
  156. package/registry/knowledge-catalog.json +4648 -0
  157. package/registry/knowledge-sources.json +438 -0
  158. package/registry/recipe-catalog.json +2565 -0
  159. package/registry/runtime-capability-policy.json +525 -0
  160. package/registry/runtime-operations.json +4468 -0
  161. package/registry/skills.json +10231 -0
  162. package/registry/workflow-graph.json +7390 -0
  163. package/schemas/adapter-compatibility-matrix.schema.json +166 -0
  164. package/schemas/contract-context-fields.schema.json +147 -0
  165. package/schemas/execution-plan.schema.json +325 -0
  166. package/schemas/glb-web-handoff-manifest.schema.json +744 -0
  167. package/schemas/knowledge-record.schema.json +460 -0
  168. package/schemas/knowledge-source-registry.schema.json +268 -0
  169. package/schemas/operation-execution-ledger.schema.json +348 -0
  170. package/schemas/recipe-record.schema.json +469 -0
  171. package/schemas/runtime-capability-policy.schema.json +184 -0
  172. package/schemas/runtime-evidence-packet.schema.json +211 -0
  173. package/schemas/runtime-operations.schema.json +535 -0
  174. package/schemas/runtime-qualification-report.schema.json +540 -0
  175. package/schemas/runtime-session.schema.json +350 -0
  176. package/schemas/scene-spec.schema.json +624 -0
  177. package/schemas/skill-contract.schema.json +402 -0
  178. package/schemas/skill-eval.schema.json +509 -0
  179. package/scripts/build-knowledge-catalog.mjs +2376 -0
  180. package/scripts/compile-scene-plan.mjs +1945 -0
  181. package/scripts/export-claude-skills.mjs +634 -0
  182. package/scripts/generate-glb-handoff-report.mjs +2376 -0
  183. package/scripts/inspect-glb.mjs +1627 -0
  184. package/scripts/install-skills.mjs +5443 -0
  185. package/scripts/runtime-orchestrator.mjs +7713 -0
  186. package/scripts/validate-capability-policy.mjs +531 -0
  187. package/scripts/validate-evidence-packet.mjs +256 -0
  188. package/skills/README.md +315 -0
  189. package/skills/_template/SKILL.md +296 -0
  190. package/skills/acceptance-criteria-builder/EVAL.md +25 -0
  191. package/skills/acceptance-criteria-builder/SKILL.md +257 -0
  192. package/skills/acceptance-criteria-builder/contract.json +205 -0
  193. package/skills/acceptance-criteria-builder/references/brief-to-criteria-mapper.md +22 -0
  194. package/skills/acceptance-criteria-builder/references/checklist-patterns.md +22 -0
  195. package/skills/acceptance-criteria-builder/references/evidence-hook-rules.md +19 -0
  196. package/skills/asset-discovery/EVAL.md +81 -0
  197. package/skills/asset-discovery/SKILL.md +252 -0
  198. package/skills/asset-discovery/contract.json +291 -0
  199. package/skills/asset-discovery/references/asset-strategy-decision-tree.md +40 -0
  200. package/skills/asset-discovery/references/budget-reconciliation-patterns.md +54 -0
  201. package/skills/asset-discovery/references/license-confidence-table.md +41 -0
  202. package/skills/asset-fallback-strategy/EVAL.md +34 -0
  203. package/skills/asset-fallback-strategy/SKILL.md +248 -0
  204. package/skills/asset-fallback-strategy/contract.json +190 -0
  205. package/skills/asset-fallback-strategy/references/drop-with-caveat-rules.md +36 -0
  206. package/skills/asset-fallback-strategy/references/fallback-option-types.md +55 -0
  207. package/skills/asset-fallback-strategy/references/scoring-rubric.md +61 -0
  208. package/skills/asset-library-plan/EVAL.md +28 -0
  209. package/skills/asset-library-plan/SKILL.md +263 -0
  210. package/skills/asset-library-plan/contract.json +177 -0
  211. package/skills/asset-library-plan/references/folder-structure-rules.md +63 -0
  212. package/skills/asset-library-plan/references/metadata-schema.md +62 -0
  213. package/skills/asset-library-plan/references/naming-rules.md +51 -0
  214. package/skills/asset-license-checker/EVAL.md +33 -0
  215. package/skills/asset-license-checker/SKILL.md +245 -0
  216. package/skills/asset-license-checker/contract.json +172 -0
  217. package/skills/asset-license-checker/references/attribution-rendering-patterns.md +48 -0
  218. package/skills/asset-license-checker/references/common-license-mapping.md +39 -0
  219. package/skills/asset-license-checker/references/license-source-rules.md +38 -0
  220. package/skills/asset-style-check/EVAL.md +26 -0
  221. package/skills/asset-style-check/SKILL.md +238 -0
  222. package/skills/asset-style-check/contract.json +251 -0
  223. package/skills/asset-style-check/references/drift-classification.md +40 -0
  224. package/skills/asset-style-check/references/intentional-mixed-style.md +39 -0
  225. package/skills/asset-style-check/references/style-axes.md +46 -0
  226. package/skills/blender-brainstorming/EVAL.md +79 -0
  227. package/skills/blender-brainstorming/SKILL.md +228 -0
  228. package/skills/blender-brainstorming/contract.json +115 -0
  229. package/skills/blender-brainstorming/references/alternative-scoping-templates.md +43 -0
  230. package/skills/blender-brainstorming/references/clarification-patterns.md +29 -0
  231. package/skills/blender-brainstorming/references/intent-summary-style-guide.md +25 -0
  232. package/skills/blender-recipe-decomposer/EVAL.md +35 -0
  233. package/skills/blender-recipe-decomposer/SKILL.md +258 -0
  234. package/skills/blender-recipe-decomposer/contract.json +152 -0
  235. package/skills/blender-recipe-decomposer/references/dependency-patterns.md +53 -0
  236. package/skills/blender-recipe-decomposer/references/recipe-grouping-rules.md +58 -0
  237. package/skills/blender-recipe-decomposer/references/recipe-naming-rules.md +44 -0
  238. package/skills/blender-troubleshooting/EVAL.md +78 -0
  239. package/skills/blender-troubleshooting/SKILL.md +263 -0
  240. package/skills/blender-troubleshooting/contract.json +352 -0
  241. package/skills/blender-troubleshooting/references/common-symptom-playbooks.md +51 -0
  242. package/skills/blender-troubleshooting/references/divergence-routing-table.md +23 -0
  243. package/skills/blender-troubleshooting/references/four-phase-template.md +51 -0
  244. package/skills/blendops-help/EVAL.md +67 -0
  245. package/skills/blendops-help/SKILL.md +312 -0
  246. package/skills/blendops-help/contract.json +229 -0
  247. package/skills/blendops-help/references/lifecycle-phases.md +91 -0
  248. package/skills/blendops-help/references/quick-start-prompts.md +65 -0
  249. package/skills/blendops-help/references/routing-decision-tree.md +57 -0
  250. package/skills/bridge-conflicts/EVAL.md +83 -0
  251. package/skills/bridge-conflicts/SKILL.md +246 -0
  252. package/skills/bridge-conflicts/contract.json +145 -0
  253. package/skills/bridge-conflicts/references/bridge-state-matrix-template.md +82 -0
  254. package/skills/bridge-conflicts/references/conflict-playbooks.md +99 -0
  255. package/skills/bridge-conflicts/references/do-not-reminders.md +42 -0
  256. package/skills/camera-composition/EVAL.md +32 -0
  257. package/skills/camera-composition/SKILL.md +196 -0
  258. package/skills/camera-composition/contract.json +180 -0
  259. package/skills/camera-composition/references/camera-presets.md +30 -0
  260. package/skills/camera-composition/references/camera-rubric.md +24 -0
  261. package/skills/camera-composition/references/hero-composition-patterns.md +24 -0
  262. package/skills/camera-composition/references/web-layout-negative-space.md +25 -0
  263. package/skills/character-portrait/EVAL.md +42 -0
  264. package/skills/character-portrait/SKILL.md +245 -0
  265. package/skills/character-portrait/contract.json +205 -0
  266. package/skills/character-portrait/references/portrait-framing-rules.md +39 -0
  267. package/skills/character-portrait/references/portrait-lighting-patterns.md +50 -0
  268. package/skills/character-portrait/references/style-consistency-rules.md +41 -0
  269. package/skills/cli-appendix-job-outline/EVAL.md +26 -0
  270. package/skills/cli-appendix-job-outline/SKILL.md +252 -0
  271. package/skills/cli-appendix-job-outline/contract.json +147 -0
  272. package/skills/cli-appendix-job-outline/references/flag-order-reminders.md +16 -0
  273. package/skills/cli-appendix-job-outline/references/job-type-matrix.md +13 -0
  274. package/skills/cli-appendix-job-outline/references/stateless-limitations.md +12 -0
  275. package/skills/color-management-decision/EVAL.md +28 -0
  276. package/skills/color-management-decision/SKILL.md +254 -0
  277. package/skills/color-management-decision/contract.json +162 -0
  278. package/skills/color-management-decision/references/look-comparison.md +44 -0
  279. package/skills/color-management-decision/references/per-channel-rules.md +49 -0
  280. package/skills/color-management-decision/references/pipeline-mapping.md +47 -0
  281. package/skills/composition-quality-checker/EVAL.md +38 -0
  282. package/skills/composition-quality-checker/SKILL.md +260 -0
  283. package/skills/composition-quality-checker/contract.json +221 -0
  284. package/skills/composition-quality-checker/references/aspect-ratio-rules.md +37 -0
  285. package/skills/composition-quality-checker/references/composition-rules.md +58 -0
  286. package/skills/composition-quality-checker/references/headroom-leadroom-rules.md +46 -0
  287. package/skills/cycles-vs-eevee-decision/EVAL.md +26 -0
  288. package/skills/cycles-vs-eevee-decision/SKILL.md +249 -0
  289. package/skills/cycles-vs-eevee-decision/contract.json +142 -0
  290. package/skills/cycles-vs-eevee-decision/references/engine-feature-matrix.md +39 -0
  291. package/skills/cycles-vs-eevee-decision/references/gpu-device-rules.md +51 -0
  292. package/skills/cycles-vs-eevee-decision/references/samples-by-quality.md +53 -0
  293. package/skills/done-criteria/EVAL.md +33 -0
  294. package/skills/done-criteria/SKILL.md +225 -0
  295. package/skills/done-criteria/contract.json +199 -0
  296. package/skills/done-criteria/references/done-vs-perfect.md +56 -0
  297. package/skills/done-criteria/references/out-of-scope-patterns.md +50 -0
  298. package/skills/done-criteria/references/stop-condition-templates.md +39 -0
  299. package/skills/environment-shot/EVAL.md +44 -0
  300. package/skills/environment-shot/SKILL.md +237 -0
  301. package/skills/environment-shot/contract.json +162 -0
  302. package/skills/environment-shot/references/depth-layering-rules.md +49 -0
  303. package/skills/environment-shot/references/time-and-weather-rules.md +35 -0
  304. package/skills/environment-shot/references/wide-shot-camera-rules.md +51 -0
  305. package/skills/glb-animation-handoff/EVAL.md +39 -0
  306. package/skills/glb-animation-handoff/SKILL.md +271 -0
  307. package/skills/glb-animation-handoff/contract.json +247 -0
  308. package/skills/glb-animation-handoff/references/animation-types.md +36 -0
  309. package/skills/glb-animation-handoff/references/transition-rules.md +55 -0
  310. package/skills/glb-animation-handoff/references/web-stack-caveats.md +40 -0
  311. package/skills/glb-web-handoff/EVAL.md +33 -0
  312. package/skills/glb-web-handoff/SKILL.md +212 -0
  313. package/skills/glb-web-handoff/contract.json +171 -0
  314. package/skills/glb-web-handoff/references/artifact-status-language.md +26 -0
  315. package/skills/glb-web-handoff/references/glb-handoff-checklist.md +30 -0
  316. package/skills/glb-web-handoff/references/performance-caveats.md +26 -0
  317. package/skills/glb-web-handoff/references/threejs-r3f-handoff.md +28 -0
  318. package/skills/intent-to-3d-brief-writer/EVAL.md +82 -0
  319. package/skills/intent-to-3d-brief-writer/SKILL.md +238 -0
  320. package/skills/intent-to-3d-brief-writer/contract.json +195 -0
  321. package/skills/intent-to-3d-brief-writer/references/acceptance-criteria-patterns.md +46 -0
  322. package/skills/intent-to-3d-brief-writer/references/eight-slot-template.md +123 -0
  323. package/skills/intent-to-3d-brief-writer/references/mixed-audience-handling.md +39 -0
  324. package/skills/interior-scene/EVAL.md +44 -0
  325. package/skills/interior-scene/SKILL.md +261 -0
  326. package/skills/interior-scene/contract.json +277 -0
  327. package/skills/interior-scene/references/furniture-layout-rules.md +51 -0
  328. package/skills/interior-scene/references/interior-architecture-rules.md +47 -0
  329. package/skills/interior-scene/references/interior-camera-rules.md +47 -0
  330. package/skills/lighting-material-plan/EVAL.md +32 -0
  331. package/skills/lighting-material-plan/SKILL.md +194 -0
  332. package/skills/lighting-material-plan/contract.json +213 -0
  333. package/skills/lighting-material-plan/references/cyberpunk-lookdev.md +22 -0
  334. package/skills/lighting-material-plan/references/lighting-patterns.md +30 -0
  335. package/skills/lighting-material-plan/references/material-portability.md +25 -0
  336. package/skills/lighting-material-plan/references/reflective-floor-pattern.md +22 -0
  337. package/skills/lighting-material-plan/references/web-material-simplification.md +23 -0
  338. package/skills/lighting-quality-checker/EVAL.md +41 -0
  339. package/skills/lighting-quality-checker/SKILL.md +247 -0
  340. package/skills/lighting-quality-checker/contract.json +187 -0
  341. package/skills/lighting-quality-checker/references/hdri-balance-rules.md +48 -0
  342. package/skills/lighting-quality-checker/references/intensity-ranges.md +73 -0
  343. package/skills/lighting-quality-checker/references/shadow-softness-rules.md +38 -0
  344. package/skills/material-quality-checker/EVAL.md +40 -0
  345. package/skills/material-quality-checker/SKILL.md +261 -0
  346. package/skills/material-quality-checker/contract.json +244 -0
  347. package/skills/material-quality-checker/references/consumer-stack-rules.md +62 -0
  348. package/skills/material-quality-checker/references/pbr-sanity-rules.md +78 -0
  349. package/skills/material-quality-checker/references/texture-budget-rules.md +48 -0
  350. package/skills/mobile-glb-budget/EVAL.md +40 -0
  351. package/skills/mobile-glb-budget/SKILL.md +264 -0
  352. package/skills/mobile-glb-budget/contract.json +309 -0
  353. package/skills/mobile-glb-budget/references/budget-tiers.md +30 -0
  354. package/skills/mobile-glb-budget/references/degradation-plan.md +34 -0
  355. package/skills/mobile-glb-budget/references/violation-rules.md +43 -0
  356. package/skills/output-format-decision/EVAL.md +27 -0
  357. package/skills/output-format-decision/SKILL.md +222 -0
  358. package/skills/output-format-decision/contract.json +179 -0
  359. package/skills/output-format-decision/references/bit-depth-rules.md +56 -0
  360. package/skills/output-format-decision/references/compression-tradeoffs.md +62 -0
  361. package/skills/output-format-decision/references/format-decision-matrix.md +34 -0
  362. package/skills/pack-prerequisite-checker/EVAL.md +26 -0
  363. package/skills/pack-prerequisite-checker/SKILL.md +272 -0
  364. package/skills/pack-prerequisite-checker/contract.json +214 -0
  365. package/skills/pack-prerequisite-checker/references/blocked-start-playbook.md +21 -0
  366. package/skills/pack-prerequisite-checker/references/pack-readiness-template.md +38 -0
  367. package/skills/pack-prerequisite-checker/references/prerequisite-matrix.md +20 -0
  368. package/skills/path-one-host-outline/EVAL.md +26 -0
  369. package/skills/path-one-host-outline/SKILL.md +251 -0
  370. package/skills/path-one-host-outline/contract.json +167 -0
  371. package/skills/path-one-host-outline/references/connector-vs-manual-matrix.md +21 -0
  372. package/skills/path-one-host-outline/references/host-checklist-template.md +35 -0
  373. package/skills/path-one-host-outline/references/lab-addon-reminders.md +12 -0
  374. package/skills/plain-language-response/EVAL.md +33 -0
  375. package/skills/plain-language-response/SKILL.md +194 -0
  376. package/skills/plain-language-response/contract.json +242 -0
  377. package/skills/plain-language-response/references/caveat-language.md +25 -0
  378. package/skills/plain-language-response/references/plain-language-patterns.md +30 -0
  379. package/skills/plain-language-response/references/stakeholder-friendly-examples.md +30 -0
  380. package/skills/plain-language-response/references/status-summary-templates.md +50 -0
  381. package/skills/polycount-budget-checker/EVAL.md +40 -0
  382. package/skills/polycount-budget-checker/SKILL.md +251 -0
  383. package/skills/polycount-budget-checker/contract.json +196 -0
  384. package/skills/polycount-budget-checker/references/instance-counting-rules.md +39 -0
  385. package/skills/polycount-budget-checker/references/per-mesh-rules.md +43 -0
  386. package/skills/polycount-budget-checker/references/topology-hints.md +56 -0
  387. package/skills/pre-handoff-verification/EVAL.md +84 -0
  388. package/skills/pre-handoff-verification/SKILL.md +252 -0
  389. package/skills/pre-handoff-verification/contract.json +295 -0
  390. package/skills/pre-handoff-verification/references/downgrade-rules.md +39 -0
  391. package/skills/pre-handoff-verification/references/seven-point-checklist.md +46 -0
  392. package/skills/pre-handoff-verification/references/text-only-mode-handling.md +36 -0
  393. package/skills/preview-report/EVAL.md +39 -0
  394. package/skills/preview-report/SKILL.md +254 -0
  395. package/skills/preview-report/contract.json +141 -0
  396. package/skills/preview-report/references/handoff-recipients.md +41 -0
  397. package/skills/preview-report/references/report-schema.md +60 -0
  398. package/skills/preview-report/references/truth-label-rules.md +36 -0
  399. package/skills/product-grid-scene-planner/EVAL.md +42 -0
  400. package/skills/product-grid-scene-planner/SKILL.md +246 -0
  401. package/skills/product-grid-scene-planner/contract.json +257 -0
  402. package/skills/product-grid-scene-planner/references/grid-consistency-rules.md +53 -0
  403. package/skills/product-grid-scene-planner/references/grid-layout-rules.md +42 -0
  404. package/skills/product-grid-scene-planner/references/grid-output-naming-rules.md +52 -0
  405. package/skills/product-hero-scene-planner/EVAL.md +33 -0
  406. package/skills/product-hero-scene-planner/SKILL.md +227 -0
  407. package/skills/product-hero-scene-planner/contract.json +228 -0
  408. package/skills/product-hero-scene-planner/references/clarification-patterns.md +24 -0
  409. package/skills/product-hero-scene-planner/references/cyberpunk-shoe-example.md +28 -0
  410. package/skills/product-hero-scene-planner/references/product-hero-playbooks.md +22 -0
  411. package/skills/product-hero-scene-planner/references/scene-plan-schema.md +35 -0
  412. package/skills/r3f-component-plan/EVAL.md +43 -0
  413. package/skills/r3f-component-plan/SKILL.md +290 -0
  414. package/skills/r3f-component-plan/contract.json +171 -0
  415. package/skills/r3f-component-plan/references/component-shape-patterns.md +54 -0
  416. package/skills/r3f-component-plan/references/suspense-placement-rules.md +50 -0
  417. package/skills/r3f-component-plan/references/usegltf-caching-rules.md +53 -0
  418. package/skills/recipe-fit-assessor/EVAL.md +28 -0
  419. package/skills/recipe-fit-assessor/SKILL.md +266 -0
  420. package/skills/recipe-fit-assessor/contract.json +220 -0
  421. package/skills/recipe-fit-assessor/references/recipe-catalog.md +30 -0
  422. package/skills/recipe-fit-assessor/references/scope-gap-rules.md +27 -0
  423. package/skills/recipe-fit-assessor/references/workflow-recommendation-template.md +34 -0
  424. package/skills/render-export-evidence/EVAL.md +86 -0
  425. package/skills/render-export-evidence/SKILL.md +339 -0
  426. package/skills/render-export-evidence/contract.json +206 -0
  427. package/skills/render-export-evidence/references/attempted-vs-failed-rubric.md +75 -0
  428. package/skills/render-export-evidence/references/evidence-record-templates.md +143 -0
  429. package/skills/render-export-evidence/references/truth-label-decision-tree.md +57 -0
  430. package/skills/resolution-aspect-decision/EVAL.md +26 -0
  431. package/skills/resolution-aspect-decision/SKILL.md +246 -0
  432. package/skills/resolution-aspect-decision/contract.json +160 -0
  433. package/skills/resolution-aspect-decision/references/aspect-defaults.md +41 -0
  434. package/skills/resolution-aspect-decision/references/print-vs-screen-rules.md +58 -0
  435. package/skills/resolution-aspect-decision/references/resolution-defaults.md +64 -0
  436. package/skills/runtime-attempt-report/EVAL.md +26 -0
  437. package/skills/runtime-attempt-report/SKILL.md +268 -0
  438. package/skills/runtime-attempt-report/contract.json +176 -0
  439. package/skills/runtime-attempt-report/references/attempt-record-template.md +49 -0
  440. package/skills/runtime-attempt-report/references/triage-next-steps.md +15 -0
  441. package/skills/runtime-attempt-report/references/truth-label-blocks.md +27 -0
  442. package/skills/runtime-path-picker/EVAL.md +26 -0
  443. package/skills/runtime-path-picker/SKILL.md +268 -0
  444. package/skills/runtime-path-picker/contract.json +191 -0
  445. package/skills/runtime-path-picker/references/anti-patterns.md +14 -0
  446. package/skills/runtime-path-picker/references/decision-tree.md +29 -0
  447. package/skills/runtime-path-picker/references/path-constraints-table.md +18 -0
  448. package/skills/runtime-readiness/EVAL.md +33 -0
  449. package/skills/runtime-readiness/SKILL.md +218 -0
  450. package/skills/runtime-readiness/contract.json +190 -0
  451. package/skills/runtime-readiness/references/blocker-report-template.md +28 -0
  452. package/skills/runtime-readiness/references/evidence-examples.md +23 -0
  453. package/skills/runtime-readiness/references/readiness-matrix.md +46 -0
  454. package/skills/runtime-setup/EVAL.md +33 -0
  455. package/skills/runtime-setup/SKILL.md +209 -0
  456. package/skills/runtime-setup/contract.json +171 -0
  457. package/skills/runtime-setup/references/runtime-option-decision-tree.md +28 -0
  458. package/skills/runtime-setup/references/setup-summary-template.md +33 -0
  459. package/skills/runtime-setup/references/source-confidence-labels.md +23 -0
  460. package/skills/scene-readiness/EVAL.md +33 -0
  461. package/skills/scene-readiness/SKILL.md +195 -0
  462. package/skills/scene-readiness/contract.json +198 -0
  463. package/skills/scene-readiness/references/blocker-catalog.md +24 -0
  464. package/skills/scene-readiness/references/not-run-handling.md +22 -0
  465. package/skills/scene-readiness/references/quality-rubric.md +23 -0
  466. package/skills/scene-readiness/references/verdict-language.md +22 -0
  467. package/skills/scope-guard/EVAL.md +33 -0
  468. package/skills/scope-guard/SKILL.md +222 -0
  469. package/skills/scope-guard/contract.json +171 -0
  470. package/skills/scope-guard/references/options-language-template.md +51 -0
  471. package/skills/scope-guard/references/recurring-creep-patterns.md +55 -0
  472. package/skills/scope-guard/references/scope-addition-classification.md +55 -0
  473. package/skills/stage-gates/EVAL.md +40 -0
  474. package/skills/stage-gates/SKILL.md +257 -0
  475. package/skills/stage-gates/contract.json +490 -0
  476. package/skills/stage-gates/references/failed-gate-handling.md +42 -0
  477. package/skills/stage-gates/references/gate-template.md +46 -0
  478. package/skills/stage-gates/references/stage-decomposition-patterns.md +55 -0
  479. package/skills/workflow-stage-router/EVAL.md +25 -0
  480. package/skills/workflow-stage-router/SKILL.md +259 -0
  481. package/skills/workflow-stage-router/contract.json +150 -0
  482. package/skills/workflow-stage-router/references/milestone-model.md +20 -0
  483. package/skills/workflow-stage-router/references/routing-decision-tree.md +32 -0
  484. package/skills/workflow-stage-router/references/stage-handoff-template.md +37 -0
  485. package/skills.sh.json +102 -0
@@ -0,0 +1,2565 @@
1
+ {
2
+ "$schema": "../schemas/recipe-record.schema.json",
3
+ "schemaVersion": "1.0.0",
4
+ "recipes": [
5
+ {
6
+ "id": "recipe.product-hero-scene",
7
+ "title": "Product Hero Scene & Web-Ready Presentation",
8
+ "domain": "lighting-camera-and-rendering",
9
+ "summary": "End-to-end procedure for planning, staging, lighting, shading, validating, and preparing a single hero product asset for both studio presentation renders and web-ready GLB delivery.",
10
+ "aliases": [
11
+ "product-hero-workflow",
12
+ "cyberpunk-shoe-hero",
13
+ "ecommerce-hero-turntable"
14
+ ],
15
+ "intent": "Transform a product brief into a verified single-subject hero scene with three-point/accent lighting, physically plausible materials, controlled reflections, and an optional web-ready GLB handoff package.",
16
+ "intent_signals": [
17
+ "create a product hero scene for a sneaker or gadget",
18
+ "studio product showcase with rim lighting and reflective floor",
19
+ "ecommerce 3D product hero render and GLB web export",
20
+ "floating product hero shot with cinematic camera framing"
21
+ ],
22
+ "applicable_scenarios": {
23
+ "use_when": [
24
+ "The user wants a single focal product (footwear, electronics, cosmetics, watch, packaging) staged as a hero visual or interactive web 3D viewer asset.",
25
+ "Visual hierarchy requires clean silhouette separation, controlled specular highlights, and explicit quality gates before rendering or exporting."
26
+ ],
27
+ "do_not_use_when": [
28
+ "The user wants a multi-item catalog comparison grid of 4+ products (use recipe.scene-quality-inspection-and-correction with product-grid-scene-planner instead).",
29
+ "The user wants a wide outdoor landscape or interior architectural walkthrough (use recipe.stylized-environment-scene)."
30
+ ]
31
+ },
32
+ "prerequisites": [
33
+ "Confirmed 8-slot 3D brief from intent-to-3d-brief-writer with target delivery channel (render, web GLB, or both).",
34
+ "Source product mesh or acquisition strategy cleared via asset-discovery and asset-license-checker."
35
+ ],
36
+ "inputs": [
37
+ {
38
+ "name": "subject_asset",
39
+ "type": "string",
40
+ "required": true,
41
+ "description": "Primary product mesh identifier or asset description (e.g., cyberpunk sneaker, brushed-aluminum headphones)."
42
+ },
43
+ {
44
+ "name": "delivery_target",
45
+ "type": "string",
46
+ "required": true,
47
+ "default_value": "both_render_and_glb",
48
+ "description": "Target output surface: still_render, web_glb, or both_render_and_glb."
49
+ },
50
+ {
51
+ "name": "camera_focal_length_mm",
52
+ "type": "number",
53
+ "required": false,
54
+ "default_value": 85,
55
+ "description": "Full-frame equivalent lens focal length in millimeters (70-105mm recommended to avoid perspective distortion)."
56
+ },
57
+ {
58
+ "name": "view_transform",
59
+ "type": "string",
60
+ "required": false,
61
+ "default_value": "AgX",
62
+ "description": "Color management view transform (AgX for Blender 4.0+, Filmic for 3.6 LTS)."
63
+ }
64
+ ],
65
+ "stages": [
66
+ {
67
+ "stage_number": 1,
68
+ "id": "stage-brief-and-scope",
69
+ "title": "Intent Lock, Done Criteria & Asset Clearance",
70
+ "objective": "Lock the 8-slot 3D brief, pin explicit stop conditions, and verify source product asset strategy and license compliance.",
71
+ "skill_ids": [
72
+ "intent-to-3d-brief-writer",
73
+ "done-criteria",
74
+ "asset-discovery",
75
+ "asset-license-checker"
76
+ ],
77
+ "knowledge_ids": [
78
+ "knowledge.mesh-manifold-normals-and-scale-hygiene",
79
+ "knowledge.triangle-draw-call-and-vram-budgets"
80
+ ],
81
+ "actions": [
82
+ "Translate the user request into an 8-slot brief specifying hero subject, mood, aspect ratio, and delivery target.",
83
+ "Pin explicit done criteria and out-of-scope exclusions so lookdev does not drift into unbounded scope creep.",
84
+ "Verify asset acquisition source, license terms, and unit scale (1 BU = 1 meter, applied scale 1,1,1)."
85
+ ],
86
+ "stage_outputs": [
87
+ "locked_3d_brief",
88
+ "stop_condition_contract",
89
+ "cleared_asset_manifest"
90
+ ],
91
+ "gate_check": "All 8 brief slots are populated, asset license is cleared, and product bounding box is in plausible real-world meters."
92
+ },
93
+ {
94
+ "stage_number": 2,
95
+ "id": "stage-scene-and-camera-plan",
96
+ "title": "Hero Staging & Telephoto Camera Composition",
97
+ "objective": "Establish subject elevation, ground/backdrop plane geometry, and distortion-free camera framing with reserved negative space.",
98
+ "skill_ids": [
99
+ "product-hero-scene-planner",
100
+ "camera-composition",
101
+ "resolution-aspect-decision"
102
+ ],
103
+ "knowledge_ids": [
104
+ "knowledge.physically-based-camera-lens-and-dof",
105
+ "knowledge.modular-architectural-grid-and-metric-scale"
106
+ ],
107
+ "actions": [
108
+ "Position the hero product near world origin with applied rotation/scale and clear silhouette separation from the ground plane.",
109
+ "Configure a 36mm full-frame sensor camera with an 85mm lens, rule-of-thirds or centered hero framing, and shallow f/4-f/8 depth of field focused on the primary brand detail.",
110
+ "Lock output resolution and aspect ratio before lighting placement so rim highlights align with the active camera frustum."
111
+ ],
112
+ "stage_outputs": [
113
+ "product_scene_plan",
114
+ "camera_rig_specification",
115
+ "resolution_aspect_contract"
116
+ ],
117
+ "gate_check": "Camera focal length is >= 50mm, subject occupies 45-70% of frame height without edge clipping, and aspect ratio is locked."
118
+ },
119
+ {
120
+ "stage_number": 3,
121
+ "id": "stage-lighting-and-materials",
122
+ "title": "Studio Lighting & Energy-Conserving PBR Lookdev",
123
+ "objective": "Build key/fill/rim lighting with controlled floor reflections and author portable Principled BSDF materials.",
124
+ "skill_ids": [
125
+ "lighting-material-plan",
126
+ "color-management-decision",
127
+ "cycles-vs-eevee-decision"
128
+ ],
129
+ "knowledge_ids": [
130
+ "knowledge.three-point-and-hdri-studio-lighting",
131
+ "knowledge.principled-bsdf-v2-energy-conserving-pbr",
132
+ "knowledge.agx-filmic-color-management-and-cycles-eevee",
133
+ "knowledge.shader-node-gltf-export-portability"
134
+ ],
135
+ "actions": [
136
+ "Establish key-to-fill illuminance ratio (4:1 to 8:1) and place dedicated rim/accent area lights to separate dark product silhouettes from dark backgrounds.",
137
+ "Author energy-conserving Principled BSDF materials with baseColor albedo within 0.04-0.90 linear and Non-Color data space on normal/roughness/metallic maps.",
138
+ "Select AgX (Blender 4.0+) or Filmic (3.6 LTS) color management and flag any procedural shader nodes that require baking prior to GLB export."
139
+ ],
140
+ "stage_outputs": [
141
+ "lighting_rig_plan",
142
+ "material_portability_plan",
143
+ "render_engine_and_color_config"
144
+ ],
145
+ "gate_check": "No clipped highlights under AgX/Filmic, metallic values are binary (0 or 1) or masked, and non-portable shader nodes have a bake plan."
146
+ },
147
+ {
148
+ "stage_number": 4,
149
+ "id": "stage-quality-and-handoff",
150
+ "title": "Quality Gate, Evidence Verification & Stakeholder Handoff",
151
+ "objective": "Run domain quality checkers, record honest runtime/artifact truth labels, and prepare final render/GLB handoff documentation.",
152
+ "skill_ids": [
153
+ "lighting-quality-checker",
154
+ "material-quality-checker",
155
+ "composition-quality-checker",
156
+ "scene-readiness",
157
+ "render-export-evidence",
158
+ "pre-handoff-verification",
159
+ "glb-web-handoff",
160
+ "plain-language-response"
161
+ ],
162
+ "knowledge_ids": [
163
+ "knowledge.glb-binary-chunk-alignment-and-khronos-validation",
164
+ "knowledge.threejs-r3f-tone-mapping-and-environment-parity"
165
+ ],
166
+ "actions": [
167
+ "Evaluate lighting, material, and composition quality gates and synthesize an overall scene-readiness Pass/Warn/Fail verdict.",
168
+ "Verify on-disk render/GLB evidence via render-export-evidence and pre-handoff-verification (keeping Runtime status: Not Run and Artifact status: Not Produced if no Blender execution occurred).",
169
+ "Generate the plain-language stakeholder summary and web viewer integration notes."
170
+ ],
171
+ "stage_outputs": [
172
+ "scene_readiness_verdict",
173
+ "artifact_truth_ledger",
174
+ "stakeholder_handoff_summary"
175
+ ],
176
+ "gate_check": "All 7 pre-handoff verification checks pass and truth labels match actual on-disk evidence."
177
+ }
178
+ ],
179
+ "required_knowledge_ids": [
180
+ "knowledge.mesh-manifold-normals-and-scale-hygiene",
181
+ "knowledge.triangle-draw-call-and-vram-budgets",
182
+ "knowledge.physically-based-camera-lens-and-dof",
183
+ "knowledge.modular-architectural-grid-and-metric-scale",
184
+ "knowledge.three-point-and-hdri-studio-lighting",
185
+ "knowledge.principled-bsdf-v2-energy-conserving-pbr",
186
+ "knowledge.agx-filmic-color-management-and-cycles-eevee",
187
+ "knowledge.shader-node-gltf-export-portability",
188
+ "knowledge.glb-binary-chunk-alignment-and-khronos-validation",
189
+ "knowledge.threejs-r3f-tone-mapping-and-environment-parity"
190
+ ],
191
+ "required_skill_ids": [
192
+ "intent-to-3d-brief-writer",
193
+ "done-criteria",
194
+ "asset-discovery",
195
+ "asset-license-checker",
196
+ "product-hero-scene-planner",
197
+ "camera-composition",
198
+ "resolution-aspect-decision",
199
+ "lighting-material-plan",
200
+ "color-management-decision",
201
+ "cycles-vs-eevee-decision",
202
+ "lighting-quality-checker",
203
+ "material-quality-checker",
204
+ "composition-quality-checker",
205
+ "scene-readiness",
206
+ "render-export-evidence",
207
+ "pre-handoff-verification",
208
+ "glb-web-handoff",
209
+ "plain-language-response"
210
+ ],
211
+ "expected_outputs": {
212
+ "intermediate": [
213
+ "locked_3d_brief",
214
+ "product_scene_plan",
215
+ "lighting_rig_plan",
216
+ "material_portability_plan"
217
+ ],
218
+ "final": [
219
+ "scene_readiness_verdict",
220
+ "artifact_truth_ledger",
221
+ "stakeholder_handoff_summary"
222
+ ],
223
+ "truth_state_defaults": {
224
+ "runtime_status": "Not Run",
225
+ "artifact_status": "Not Produced"
226
+ }
227
+ },
228
+ "validation_criteria": [
229
+ {
230
+ "id": "vc.silhouette-readability",
231
+ "criterion": "Hero subject silhouette separates cleanly from the background and floor across 100% of its contour.",
232
+ "measurement_method": "Inspect rim light placement and luminance contrast ratio in composition-quality-checker and lighting-quality-checker.",
233
+ "pass_threshold": "Dedicated rim/backlight present with >= 3:1 edge contrast against backdrop."
234
+ },
235
+ {
236
+ "id": "vc.pbr-portability",
237
+ "criterion": "All hero materials use energy-conserving PBR sockets or have an explicit texture-bake plan for glTF 2.0 export.",
238
+ "measurement_method": "Audit shader nodes against knowledge.shader-node-gltf-export-portability and material-quality-checker.",
239
+ "pass_threshold": "Zero unbaked Blender-only procedural nodes on GLB export path; normal/ORM maps set to Non-Color."
240
+ },
241
+ {
242
+ "id": "vc.truth-state-compliance",
243
+ "criterion": "Runtime and artifact truth states accurately reflect whether Blender executed.",
244
+ "measurement_method": "Verify pre-handoff-verification 7-point gate and render-export-evidence ledger.",
245
+ "pass_threshold": "Runtime status is Not Run and Artifact status is Not Produced unless backed by a verified evidence file."
246
+ }
247
+ ],
248
+ "failure_modes": [
249
+ {
250
+ "symptom": "Product silhouette merges into dark background or glossy floor reflections overpower the subject.",
251
+ "root_cause": "Missing rim light or floor roughness/specular intensity is uncalibrated relative to key light.",
252
+ "recovery_action": "Add a dedicated grazing rim area light behind the subject and increase floor roughness to 0.15-0.30 with controlled specular weight.",
253
+ "fallback_skill_id": "lighting-quality-checker"
254
+ },
255
+ {
256
+ "symptom": "Exported GLB appears flat or missing procedural surface details in Three.js / React Three Fiber.",
257
+ "root_cause": "Blender procedural nodes (Noise, Voronoi, ColorRamp) were left unbaked in the shader graph.",
258
+ "recovery_action": "Bake procedural channels to tangent-space normal, roughness, and baseColor image textures using Cycles bake before GLB export.",
259
+ "fallback_skill_id": "material-quality-checker"
260
+ }
261
+ ],
262
+ "blender_versions": {
263
+ "minimum": "3.6 LTS",
264
+ "recommended": "4.5.15 LTS",
265
+ "doc_checked_version": "5.2.3 LTS",
266
+ "runtime_tested_version": null,
267
+ "maintained_lts_versions": [
268
+ "4.2 LTS",
269
+ "4.5.15 LTS",
270
+ "5.2.3 LTS"
271
+ ],
272
+ "legacy_compatibility_target": "3.6 LTS",
273
+ "version_considerations": "Blender 4.0+ introduces Principled BSDF v2 (Coat/Sheen/Specular IOR layers) and AgX view transform; Blender 5.1+ is required only if executing via Path 1 Official Blender Lab MCP. Reconciled with Blender 4.5.15 LTS and 5.2.3 LTS documentation baselines (live runtime: Not Run)."
274
+ },
275
+ "source_refs": [
276
+ {
277
+ "source_id": "source.blender-manual-shading-color",
278
+ "locator": "Principled BSDF & Color Management (AgX)"
279
+ },
280
+ {
281
+ "source_id": "source.blender-manual-gltf-io",
282
+ "locator": "glTF 2.0 Material Socket Mapping"
283
+ },
284
+ {
285
+ "source_id": "source.khronos-gltf-asset-auditor",
286
+ "locator": "3D Commerce Product Visualization Guidelines"
287
+ }
288
+ ],
289
+ "evidence_status": "version-checked",
290
+ "documentation_path": "docs/recipes/cyberpunk-shoe-hero.md",
291
+ "related_recipes": [
292
+ "recipe.presentation-lighting-and-camera",
293
+ "recipe.blender-to-glb-handoff",
294
+ "recipe.uv-and-pbr-material-preparation"
295
+ ]
296
+ },
297
+ {
298
+ "id": "recipe.stylized-environment-scene",
299
+ "title": "Stylized Environment & Establishing Shot Assembly",
300
+ "domain": "environment-and-architecture",
301
+ "summary": "Structured procedure for assembling a wide environment or small diorama scene with foreground/midground/background depth layering, procedural scatter, and atmospheric lighting.",
302
+ "aliases": [
303
+ "environment-establishing-shot",
304
+ "diorama-scene-assembly",
305
+ "landscape-and-archviz-exterior"
306
+ ],
307
+ "intent": "Plan and assemble a readable environment or diorama establishing shot with metric scale cues, three-plane depth staging, instanced foliage/props, and time-of-day atmospheric lighting.",
308
+ "intent_signals": [
309
+ "build a stylized environment or fantasy village diorama",
310
+ "wide establishing shot of an outdoor landscape or street scene",
311
+ "assemble an exterior architectural environment with depth layers and fog",
312
+ "create a small 3D world scene with scattered trees and props"
313
+ ],
314
+ "applicable_scenarios": {
315
+ "use_when": [
316
+ "The user wants an exterior environment, diorama island, street corner, or landscape establishing shot.",
317
+ "Spatial readability across foreground, midground focal structure, and background vista is critical."
318
+ ],
319
+ "do_not_use_when": [
320
+ "The user wants a close-up single-product studio shot (use recipe.product-hero-scene).",
321
+ "The user wants a closed-room interior furniture layout without exterior vista (use interior-scene with recipe.presentation-lighting-and-camera)."
322
+ ]
323
+ },
324
+ "prerequisites": [
325
+ "Locked 3D brief specifying locale, time of day, weather/atmosphere, and whether output is an offline render or real-time GLB.",
326
+ "Asset style consistency and polycount budget targets defined."
327
+ ],
328
+ "inputs": [
329
+ {
330
+ "name": "environment_theme",
331
+ "type": "string",
332
+ "required": true,
333
+ "description": "Locale and art direction (e.g., dusk alpine cabin, stylized harbour village, rain-slicked cyberpunk alley)."
334
+ },
335
+ {
336
+ "name": "time_of_day",
337
+ "type": "string",
338
+ "required": true,
339
+ "default_value": "golden_hour_dusk",
340
+ "description": "Primary lighting state: midday, golden_hour_dusk, overcast, or night_practicals."
341
+ },
342
+ {
343
+ "name": "camera_focal_length_mm",
344
+ "type": "number",
345
+ "required": false,
346
+ "default_value": 28,
347
+ "description": "Wide-to-standard focal length in mm (24-35mm for expansive establishing shots; 50mm+ for compressed diorama look)."
348
+ }
349
+ ],
350
+ "stages": [
351
+ {
352
+ "stage_number": 1,
353
+ "id": "stage-environment-brief-and-assets",
354
+ "title": "Brief Lock, Asset Discovery & Style Consistency",
355
+ "objective": "Define the environment brief, source modular architectural/foliage kit assets, and verify visual style coherence.",
356
+ "skill_ids": [
357
+ "intent-to-3d-brief-writer",
358
+ "asset-discovery",
359
+ "asset-license-checker",
360
+ "asset-style-check"
361
+ ],
362
+ "knowledge_ids": [
363
+ "knowledge.modular-architectural-grid-and-metric-scale",
364
+ "knowledge.mesh-manifold-normals-and-scale-hygiene"
365
+ ],
366
+ "actions": [
367
+ "Lock the 8-slot environment brief and establish real-world metric scale (1 BU = 1m) with human-scale reference proxies (1.75m height).",
368
+ "Audit modular building and foliage kit assets for consistent texel density, edge bevel softness, and color palette harmony."
369
+ ],
370
+ "stage_outputs": [
371
+ "locked_environment_brief",
372
+ "style_verified_asset_kit"
373
+ ],
374
+ "gate_check": "All kit assets share consistent metric scale and pass asset-style-check across realism, detail frequency, and palette axes."
375
+ },
376
+ {
377
+ "stage_number": 2,
378
+ "id": "stage-depth-layering-and-camera",
379
+ "title": "Three-Plane Depth Staging & Wide Camera Composition",
380
+ "objective": "Arrange foreground framing elements, midground focal landmark, and background silhouette with a locked establishing camera.",
381
+ "skill_ids": [
382
+ "environment-shot",
383
+ "camera-composition",
384
+ "resolution-aspect-decision"
385
+ ],
386
+ "knowledge_ids": [
387
+ "knowledge.environment-depth-layering-and-atmospheric-perspective",
388
+ "knowledge.physically-based-camera-lens-and-dof"
389
+ ],
390
+ "actions": [
391
+ "Block out foreground framing silhouettes (15-25% frame periphery), midground hero landmark at rule-of-thirds intersection, and distant background horizon.",
392
+ "Set a 24-35mm wide establishing camera (or 85mm tilt-shift for miniature dioramas) with deliberate horizon placement."
393
+ ],
394
+ "stage_outputs": [
395
+ "environment_depth_layout",
396
+ "establishing_camera_plan"
397
+ ],
398
+ "gate_check": "Foreground, midground, and background planes do not tangentially overlap the focal landmark silhouette."
399
+ },
400
+ {
401
+ "stage_number": 3,
402
+ "id": "stage-procedural-scatter-and-atmosphere",
403
+ "title": "Procedural Instancing & Time-of-Day Atmospheric Lighting",
404
+ "objective": "Populate foliage/debris via Geometry Nodes point instancing without blowing memory budgets, and stage sun/sky/practical lighting.",
405
+ "skill_ids": [
406
+ "lighting-material-plan",
407
+ "polycount-budget-checker",
408
+ "cycles-vs-eevee-decision"
409
+ ],
410
+ "knowledge_ids": [
411
+ "knowledge.procedural-instancing-and-realize-instances-budget",
412
+ "knowledge.procedural-scatter-poisson-disk-and-slope-masking",
413
+ "knowledge.volumetrics-fog-and-principled-volume-tradeoffs"
414
+ ],
415
+ "actions": [
416
+ "Scatter secondary props/foliage using Poisson Disk distribution and normal-slope masking while keeping Instance on Points unrealized to preserve GPU instancing.",
417
+ "Configure directional sun/sky angle for the chosen time of day, warm practical point/area lights for night/dusk focal cues, and mist/volumetric depth separation."
418
+ ],
419
+ "stage_outputs": [
420
+ "instanced_scatter_plan",
421
+ "atmospheric_lighting_plan"
422
+ ],
423
+ "gate_check": "Scattered instances remain instanced (not destructively realized) and volumetric/fog caveats are documented if targeting GLB export."
424
+ },
425
+ {
426
+ "stage_number": 4,
427
+ "id": "stage-environment-validation-and-handoff",
428
+ "title": "Readiness Audit & Evidence-Bound Handoff",
429
+ "objective": "Verify composition, lighting, and polycount gates and produce the final truth-labeled environment report.",
430
+ "skill_ids": [
431
+ "composition-quality-checker",
432
+ "lighting-quality-checker",
433
+ "scene-readiness",
434
+ "pre-handoff-verification",
435
+ "plain-language-response"
436
+ ],
437
+ "knowledge_ids": [
438
+ "knowledge.agx-filmic-color-management-and-cycles-eevee",
439
+ "knowledge.triangle-draw-call-and-vram-budgets"
440
+ ],
441
+ "actions": [
442
+ "Validate depth-plane value separation (dark foreground, high-contrast focal midground, desaturated background) and draw-call/instance counts.",
443
+ "Record truthful runtime/artifact statuses and deliver the plain-language environment summary."
444
+ ],
445
+ "stage_outputs": [
446
+ "environment_readiness_verdict",
447
+ "environment_handoff_report"
448
+ ],
449
+ "gate_check": "Focal landmark is the highest local contrast region and all truth-state labels are verified."
450
+ }
451
+ ],
452
+ "required_knowledge_ids": [
453
+ "knowledge.modular-architectural-grid-and-metric-scale",
454
+ "knowledge.mesh-manifold-normals-and-scale-hygiene",
455
+ "knowledge.environment-depth-layering-and-atmospheric-perspective",
456
+ "knowledge.physically-based-camera-lens-and-dof",
457
+ "knowledge.procedural-instancing-and-realize-instances-budget",
458
+ "knowledge.procedural-scatter-poisson-disk-and-slope-masking",
459
+ "knowledge.volumetrics-fog-and-principled-volume-tradeoffs",
460
+ "knowledge.agx-filmic-color-management-and-cycles-eevee",
461
+ "knowledge.triangle-draw-call-and-vram-budgets"
462
+ ],
463
+ "required_skill_ids": [
464
+ "intent-to-3d-brief-writer",
465
+ "asset-discovery",
466
+ "asset-license-checker",
467
+ "asset-style-check",
468
+ "environment-shot",
469
+ "camera-composition",
470
+ "resolution-aspect-decision",
471
+ "lighting-material-plan",
472
+ "polycount-budget-checker",
473
+ "cycles-vs-eevee-decision",
474
+ "composition-quality-checker",
475
+ "lighting-quality-checker",
476
+ "scene-readiness",
477
+ "pre-handoff-verification",
478
+ "plain-language-response"
479
+ ],
480
+ "expected_outputs": {
481
+ "intermediate": [
482
+ "locked_environment_brief",
483
+ "environment_depth_layout",
484
+ "instanced_scatter_plan"
485
+ ],
486
+ "final": [
487
+ "environment_readiness_verdict",
488
+ "environment_handoff_report"
489
+ ],
490
+ "truth_state_defaults": {
491
+ "runtime_status": "Not Run",
492
+ "artifact_status": "Not Produced"
493
+ }
494
+ },
495
+ "validation_criteria": [
496
+ {
497
+ "id": "vc.three-plane-depth",
498
+ "criterion": "Scene exhibits distinct foreground, midground, and background depth layers with clear luminance separation.",
499
+ "measurement_method": "Check depth plane assignments in environment-shot and composition-quality-checker.",
500
+ "pass_threshold": "All 3 depth planes populated; midground focal landmark has highest contrast."
501
+ },
502
+ {
503
+ "id": "vc.instance-preservation",
504
+ "criterion": "Repeated foliage and modular props use collection/geometry-node instancing rather than duplicated unique meshes.",
505
+ "measurement_method": "Audit instance vs. unique mesh counts in polycount-budget-checker.",
506
+ "pass_threshold": "Repeated scatter elements use Instance on Points without unnecessary Realize Instances."
507
+ },
508
+ {
509
+ "id": "vc.volumetric-export-honesty",
510
+ "criterion": "Volumetric fog shaders are flagged as Blender-only if GLB web export is requested.",
511
+ "measurement_method": "Verify knowledge.volumetrics-fog-and-principled-volume-tradeoffs compliance in material/lighting plan.",
512
+ "pass_threshold": "Web targets replace Principled Volume with engine fog or depth-fade cards."
513
+ }
514
+ ],
515
+ "failure_modes": [
516
+ {
517
+ "symptom": "Viewport freezes or memory spikes to several gigabytes after scattering foliage.",
518
+ "root_cause": "Realize Instances node was placed after high-poly foliage instancing or Poisson Disk density is uncalibrated for object scale.",
519
+ "recovery_action": "Remove Realize Instances downstream of Instance on Points, apply object scale (1,1,1) to terrain, and enforce a minimum Poisson Disk distance.",
520
+ "fallback_skill_id": "polycount-budget-checker"
521
+ },
522
+ {
523
+ "symptom": "Scene feels flat and cluttered with no clear focal point.",
524
+ "root_cause": "Uniform light intensity across all depth planes and competing high-contrast textures in the background.",
525
+ "recovery_action": "Shadow the foreground plane with a gobo/cutter, focus warm key/practical light on the midground landmark, and increase atmospheric haze on background elements.",
526
+ "fallback_skill_id": "composition-quality-checker"
527
+ }
528
+ ],
529
+ "blender_versions": {
530
+ "minimum": "3.6 LTS",
531
+ "recommended": "4.5.15 LTS",
532
+ "doc_checked_version": "5.2.3 LTS",
533
+ "runtime_tested_version": null,
534
+ "maintained_lts_versions": [
535
+ "4.2 LTS",
536
+ "4.5.15 LTS",
537
+ "5.2.3 LTS"
538
+ ],
539
+ "legacy_compatibility_target": "3.6 LTS",
540
+ "version_considerations": "EEVEE Next in Blender 4.2 LTS changes horizon scan raytracing and volumetric tile resolution settings compared to Legacy EEVEE in 3.6 LTS. Reconciled with Blender 4.5.15 LTS and 5.2.3 LTS documentation baselines (live runtime: Not Run)."
541
+ },
542
+ "source_refs": [
543
+ {
544
+ "source_id": "source.blender-manual-geometry-nodes",
545
+ "locator": "Instances & Point Distribution"
546
+ },
547
+ {
548
+ "source_id": "source.blender-studio-pipeline",
549
+ "locator": "Set Dressing & Collection Instancing"
550
+ }
551
+ ],
552
+ "evidence_status": "version-checked",
553
+ "related_recipes": [
554
+ "recipe.procedural-geometry-nodes-asset",
555
+ "recipe.presentation-lighting-and-camera"
556
+ ]
557
+ },
558
+ {
559
+ "id": "recipe.hard-surface-prop",
560
+ "title": "Non-Destructive Hard-Surface Prop Modeling & Shading Hygiene",
561
+ "domain": "hard-surface-and-organic",
562
+ "summary": "Structured workflow for creating clean hard-surface props using non-destructive Boolean/Bevel/Weighted Normal modifier stacks, CAD panel detailing, and artifact-free shading.",
563
+ "aliases": [
564
+ "hard-surface-modifier-workflow",
565
+ "mechanical-prop-modeling",
566
+ "boolean-bevel-prop-pipeline"
567
+ ],
568
+ "intent": "Design and validate a mechanical or manufactured hard-surface prop with consistent millimeter bevel widths, clean boolean shading via weighted normals or quad holding loops, and export-ready mesh hygiene.",
569
+ "intent_signals": [
570
+ "model a hard-surface sci-fi prop or mechanical device",
571
+ "fix shading artifacts after boolean cutouts and bevels",
572
+ "set up a non-destructive bevel and weighted normal modifier stack",
573
+ "prepare a manufactured product or weapon prop with panel lines"
574
+ ],
575
+ "applicable_scenarios": {
576
+ "use_when": [
577
+ "The user is building or auditing a mechanical, industrial, electronic, or sci-fi hard-surface asset with sharp creases, booleans, and machined bevels.",
578
+ "Shading artifacts (pinching, dark gradients across flat faces) must be prevented without destructively applying every modifier prematurely."
579
+ ],
580
+ "do_not_use_when": [
581
+ "The asset is a deforming organic character or creature requiring all-quad animation loops (use organic sculpting/retopology with recipe.rigged-and-animated-asset).",
582
+ "The user only needs lighting and camera setup on an already finalized mesh (use recipe.presentation-lighting-and-camera)."
583
+ ]
584
+ },
585
+ "prerequisites": [
586
+ "Confirmed prop dimensions in real-world meters/millimeters and target representation (subdivision hero mesh vs. weighted-normal game/web mesh).",
587
+ "Target triangle budget established if destined for real-time GLB."
588
+ ],
589
+ "inputs": [
590
+ {
591
+ "name": "prop_subject",
592
+ "type": "string",
593
+ "required": true,
594
+ "description": "Hard-surface prop description and physical dimensions."
595
+ },
596
+ {
597
+ "name": "surface_representation",
598
+ "type": "string",
599
+ "required": true,
600
+ "default_value": "bevel_plus_weighted_normal",
601
+ "description": "Target topology strategy: bevel_plus_weighted_normal (mid-poly real-time) or quad_subdivision (offline hero)."
602
+ },
603
+ {
604
+ "name": "primary_bevel_width_mm",
605
+ "type": "number",
606
+ "required": false,
607
+ "default_value": 2,
608
+ "description": "Primary structural edge bevel width in millimeters (must be visible at camera distance)."
609
+ }
610
+ ],
611
+ "stages": [
612
+ {
613
+ "stage_number": 1,
614
+ "id": "stage-prop-scale-and-blockout",
615
+ "title": "Metric Scale Hygiene & Primary Silhouette Blockout",
616
+ "objective": "Establish primary forms at 1:1 metric scale with applied transforms and clean outward face orientation.",
617
+ "skill_ids": [
618
+ "intent-to-3d-brief-writer",
619
+ "done-criteria",
620
+ "scope-guard"
621
+ ],
622
+ "knowledge_ids": [
623
+ "knowledge.mesh-manifold-normals-and-scale-hygiene",
624
+ "knowledge.cad-creases-and-panel-gap-detailing"
625
+ ],
626
+ "actions": [
627
+ "Block out primary, secondary, and tertiary forms at real-world scale and apply object scale (Ctrl+A -> Scale) so bevel widths evaluate uniformly in millimeters.",
628
+ "Verify Face Orientation overlay shows 100% outward-facing normals on both base meshes and boolean cutters."
629
+ ],
630
+ "stage_outputs": [
631
+ "metric_prop_blockout",
632
+ "transform_hygiene_checklist"
633
+ ],
634
+ "gate_check": "All base and cutter objects have scale (1.0, 1.0, 1.0), outward normals, and zero non-manifold open boundary holes on boolean operands."
635
+ },
636
+ {
637
+ "stage_number": 2,
638
+ "id": "stage-modifier-stack-and-topology",
639
+ "title": "Non-Destructive Modifier Stack & Shading Control",
640
+ "objective": "Order Mirror, Boolean, Bevel, and Weighted Normal / Subdivision modifiers to eliminate shading gradients and pinching.",
641
+ "skill_ids": [
642
+ "stage-gates",
643
+ "polycount-budget-checker"
644
+ ],
645
+ "knowledge_ids": [
646
+ "knowledge.non-destructive-hard-surface-modifier-stack",
647
+ "knowledge.boolean-bevel-shading-cleanup",
648
+ "knowledge.quad-dominant-subdivision-topology"
649
+ ],
650
+ "actions": [
651
+ "Order the modifier stack strictly: Mirror -> Boolean (Exact solver for coplanar/overlapping cuts) -> Bevel (Angle limit ~30 deg, Clamp Overlap enabled, Harden Normals or followed by Weighted Normal) -> Weighted Normal (Keep Sharp enabled).",
652
+ "Route support edges around curved cylinder/boolean intersections so bevel vertices do not collide with adjacent stray edges."
653
+ ],
654
+ "stage_outputs": [
655
+ "ordered_modifier_stack_spec",
656
+ "shading_cleanup_plan"
657
+ ],
658
+ "gate_check": "MatCap reflection lines flow smoothly across flat and cylindrical surfaces without diagonal shading streaks or bevel overlap spikes."
659
+ },
660
+ {
661
+ "stage_number": 3,
662
+ "id": "stage-uv-and-surface-materials",
663
+ "title": "Seam Placement, Baking & Machined PBR Materials",
664
+ "objective": "Unwrap hard edges or bake high-to-low normal/curvature maps and assign physically plausible metal/dielectric materials.",
665
+ "skill_ids": [
666
+ "lighting-material-plan",
667
+ "material-quality-checker"
668
+ ],
669
+ "knowledge_ids": [
670
+ "knowledge.uv-seam-placement-and-texel-density",
671
+ "knowledge.high-to-low-normal-and-ao-baking",
672
+ "knowledge.principled-bsdf-v2-energy-conserving-pbr"
673
+ ],
674
+ "actions": [
675
+ "Place UV seams along sharp >=60 deg edges so MikkTSpace tangents split cleanly at hard shading breaks.",
676
+ "Assign conductor (metallic=1.0) vs. dielectric coating (metallic=0.0) materials with subtle roughness breakup."
677
+ ],
678
+ "stage_outputs": [
679
+ "hard_surface_uv_plan",
680
+ "machined_pbr_material_spec"
681
+ ],
682
+ "gate_check": "Hard shading edges have matching UV seams and normal/roughness maps use Non-Color space."
683
+ },
684
+ {
685
+ "stage_number": 4,
686
+ "id": "stage-prop-validation-and-handoff",
687
+ "title": "Geometry, Budget & Export Readiness Verification",
688
+ "objective": "Validate triangle budget, custom split normals preservation, and final readiness verdict.",
689
+ "skill_ids": [
690
+ "polycount-budget-checker",
691
+ "scene-readiness",
692
+ "pre-handoff-verification",
693
+ "plain-language-response"
694
+ ],
695
+ "knowledge_ids": [
696
+ "knowledge.triangle-draw-call-and-vram-budgets",
697
+ "knowledge.gltf-2-coordinate-system-and-transform-conventions"
698
+ ],
699
+ "actions": [
700
+ "Verify that custom weighted normals are preserved on export and total triangle count fits within the target device tier budget.",
701
+ "Produce the final readiness report with explicit truth states."
702
+ ],
703
+ "stage_outputs": [
704
+ "prop_readiness_verdict",
705
+ "prop_handoff_summary"
706
+ ],
707
+ "gate_check": "Zero shading artifacts under glossy MatCap inspection, triangle budget within tier limit, and truth states verified."
708
+ }
709
+ ],
710
+ "required_knowledge_ids": [
711
+ "knowledge.mesh-manifold-normals-and-scale-hygiene",
712
+ "knowledge.cad-creases-and-panel-gap-detailing",
713
+ "knowledge.non-destructive-hard-surface-modifier-stack",
714
+ "knowledge.boolean-bevel-shading-cleanup",
715
+ "knowledge.quad-dominant-subdivision-topology",
716
+ "knowledge.uv-seam-placement-and-texel-density",
717
+ "knowledge.high-to-low-normal-and-ao-baking",
718
+ "knowledge.principled-bsdf-v2-energy-conserving-pbr",
719
+ "knowledge.triangle-draw-call-and-vram-budgets",
720
+ "knowledge.gltf-2-coordinate-system-and-transform-conventions"
721
+ ],
722
+ "required_skill_ids": [
723
+ "intent-to-3d-brief-writer",
724
+ "done-criteria",
725
+ "scope-guard",
726
+ "stage-gates",
727
+ "polycount-budget-checker",
728
+ "lighting-material-plan",
729
+ "material-quality-checker",
730
+ "scene-readiness",
731
+ "pre-handoff-verification",
732
+ "plain-language-response"
733
+ ],
734
+ "expected_outputs": {
735
+ "intermediate": [
736
+ "metric_prop_blockout",
737
+ "ordered_modifier_stack_spec",
738
+ "hard_surface_uv_plan"
739
+ ],
740
+ "final": [
741
+ "prop_readiness_verdict",
742
+ "prop_handoff_summary"
743
+ ],
744
+ "truth_state_defaults": {
745
+ "runtime_status": "Not Run",
746
+ "artifact_status": "Not Produced"
747
+ }
748
+ },
749
+ "validation_criteria": [
750
+ {
751
+ "id": "vc.uniform-bevel-scale",
752
+ "criterion": "Bevel widths evaluate uniformly across all axes without stretching.",
753
+ "measurement_method": "Verify object scale is (1.0, 1.0, 1.0) in knowledge.mesh-manifold-normals-and-scale-hygiene.",
754
+ "pass_threshold": "100% of beveled objects have applied unit scale."
755
+ },
756
+ {
757
+ "id": "vc.weighted-normal-shading",
758
+ "criterion": "Flat faces adjacent to bevels exhibit zero dark shading gradients.",
759
+ "measurement_method": "Check Weighted Normal modifier placement at bottom of stack with Keep Sharp enabled.",
760
+ "pass_threshold": "Weighted Normal is the final normal-modifying operation and MatCap reflections are flat on planar faces."
761
+ },
762
+ {
763
+ "id": "vc.boolean-manifold-operands",
764
+ "criterion": "Boolean cutters and target meshes are closed manifold volumes with outward normals.",
765
+ "measurement_method": "Audit mesh manifold status and Exact solver setting.",
766
+ "pass_threshold": "Zero inverted normals or open non-manifold edges on boolean operands."
767
+ }
768
+ ],
769
+ "failure_modes": [
770
+ {
771
+ "symptom": "Boolean modifier disappears, leaves open holes, or creates inverted faces.",
772
+ "root_cause": "Cutter or base mesh has non-manifold open edges, inverted face normals, or coplanar faces using the Fast solver.",
773
+ "recovery_action": "Recalculate normals outside (Shift+N) on both meshes, close open holes, switch Boolean solver to Exact, and nudge coplanar faces by 0.1mm if needed.",
774
+ "fallback_skill_id": "blender-troubleshooting"
775
+ },
776
+ {
777
+ "symptom": "Bevel modifier clamps to nearly zero width despite increasing the amount slider.",
778
+ "root_cause": "Two vertices or edges from a preceding Boolean cut are nearly coincident, triggering Clamp Overlap immediately.",
779
+ "recovery_action": "Insert a Weld / Merge by Distance modifier (0.0001m) between Boolean and Bevel or slide the intersecting cutter slightly.",
780
+ "fallback_skill_id": "blender-troubleshooting"
781
+ }
782
+ ],
783
+ "blender_versions": {
784
+ "minimum": "3.6 LTS",
785
+ "recommended": "4.5.15 LTS",
786
+ "doc_checked_version": "5.2.3 LTS",
787
+ "runtime_tested_version": null,
788
+ "maintained_lts_versions": [
789
+ "4.2 LTS",
790
+ "4.5.15 LTS",
791
+ "5.2.3 LTS"
792
+ ],
793
+ "legacy_compatibility_target": "3.6 LTS",
794
+ "version_considerations": "Blender 4.1+ replaced the legacy mesh Auto Smooth checkbox with the Smooth by Angle modifier / node group; Weighted Normal Keep Sharp continues to work with sharp edges in 4.2 LTS and 5.1+. Reconciled with Blender 4.5.15 LTS and 5.2.3 LTS documentation baselines (live runtime: Not Run)."
795
+ },
796
+ "source_refs": [
797
+ {
798
+ "source_id": "source.blender-manual-modeling",
799
+ "locator": "Bevel, Boolean, and Weighted Normal Modifiers"
800
+ },
801
+ {
802
+ "source_id": "source.mikktspace-tangent-standard",
803
+ "locator": "Hard Edges and UV Seam Splitting"
804
+ }
805
+ ],
806
+ "evidence_status": "version-checked",
807
+ "related_recipes": [
808
+ "recipe.uv-and-pbr-material-preparation",
809
+ "recipe.web-ready-asset-optimization"
810
+ ]
811
+ },
812
+ {
813
+ "id": "recipe.procedural-geometry-nodes-asset",
814
+ "title": "Procedural Geometry Nodes Asset & Scatter Pipeline",
815
+ "domain": "geometry-nodes-and-procedural",
816
+ "summary": "Structured workflow for designing parametric Geometry Nodes setups using Fields, named attributes, Poisson Disk point scattering, and safe instancing-to-mesh realization rules.",
817
+ "aliases": [
818
+ "geometry-nodes-parametric-generator",
819
+ "procedural-instancing-pipeline",
820
+ "gn-fields-and-attributes-workflow"
821
+ ],
822
+ "intent": "Build a deterministic, parameter-exposed Geometry Nodes asset or scatter system with explicit attribute domain propagation, instance memory discipline, and clear realization rules for rendering vs. glTF export.",
823
+ "intent_signals": [
824
+ "create a procedural Geometry Nodes generator or scatter system",
825
+ "pass Geometry Nodes attributes to shader materials",
826
+ "export a Geometry Nodes setup to GLB without losing instances or UVs",
827
+ "build a parametric modular fence, building, or foliage scatter in Geometry Nodes"
828
+ ],
829
+ "applicable_scenarios": {
830
+ "use_when": [
831
+ "The user wants parametric repetition, surface scattering, curve-to-mesh sweeps, or procedural variation driven by Geometry Nodes.",
832
+ "Attribute data (UVMap, vertex color, random per-instance variation) must survive into Cycles/EEVEE shaders or exported meshes."
833
+ ],
834
+ "do_not_use_when": [
835
+ "A single static hand-modeled prop is simpler and requires no parametric variation (use recipe.hard-surface-prop).",
836
+ "The user expects Geometry Nodes procedural node graphs to execute dynamically inside a standard Three.js GLTFLoader without realization/baking."
837
+ ]
838
+ },
839
+ "prerequisites": [
840
+ "Target output channel known (Blender render vs. exported GLB mesh/instances).",
841
+ "Base instance collection or procedural primitive specifications locked."
842
+ ],
843
+ "inputs": [
844
+ {
845
+ "name": "generator_goal",
846
+ "type": "string",
847
+ "required": true,
848
+ "description": "Description of the parametric asset or scatter behavior."
849
+ },
850
+ {
851
+ "name": "export_to_glb",
852
+ "type": "boolean",
853
+ "required": true,
854
+ "default_value": false,
855
+ "description": "Whether the procedural output must be exported to a standard glTF/GLB container."
856
+ },
857
+ {
858
+ "name": "random_seed",
859
+ "type": "number",
860
+ "required": false,
861
+ "default_value": 42,
862
+ "description": "Deterministic integer seed exposed on the Group Input interface."
863
+ }
864
+ ],
865
+ "stages": [
866
+ {
867
+ "stage_number": 1,
868
+ "id": "stage-gn-interface-and-inputs",
869
+ "title": "Parametric Group Input Contract & Scale Normalization",
870
+ "objective": "Define bounded Group Input parameters (seed, density, dimensions) and ensure host geometry has applied scale.",
871
+ "skill_ids": [
872
+ "intent-to-3d-brief-writer",
873
+ "done-criteria",
874
+ "stage-gates"
875
+ ],
876
+ "knowledge_ids": [
877
+ "knowledge.geometry-nodes-fields-and-anonymous-attributes",
878
+ "knowledge.mesh-manifold-normals-and-scale-hygiene"
879
+ ],
880
+ "actions": [
881
+ "Expose user-facing Group Inputs with explicit minimum/maximum bounds (especially density and subdivision levels) to prevent accidental viewport lockups.",
882
+ "Apply object scale on emitter/curve host objects so field distances and curve radii evaluate in true meters."
883
+ ],
884
+ "stage_outputs": [
885
+ "gn_group_input_schema",
886
+ "normalized_host_geometry"
887
+ ],
888
+ "gate_check": "All density/count inputs have safe upper clamps and host transforms are (1.0, 1.0, 1.0)."
889
+ },
890
+ {
891
+ "stage_number": 2,
892
+ "id": "stage-gn-distribution-and-instancing",
893
+ "title": "Field Evaluation, Distribution & Instance on Points",
894
+ "objective": "Construct the procedural field graph using Poisson Disk distribution, slope/altitude masks, and collection instancing.",
895
+ "skill_ids": [
896
+ "polycount-budget-checker",
897
+ "asset-style-check"
898
+ ],
899
+ "knowledge_ids": [
900
+ "knowledge.procedural-scatter-poisson-disk-and-slope-masking",
901
+ "knowledge.procedural-instancing-and-realize-instances-budget"
902
+ ],
903
+ "actions": [
904
+ "Use Distribute Points on Faces (Poisson Disk) with normal dot-product masking to filter valid placement surfaces.",
905
+ "Feed points into Instance on Points with Pick Instance enabled and bounded random rotation/scale driven by a deterministic Seed."
906
+ ],
907
+ "stage_outputs": [
908
+ "procedural_field_graph_spec",
909
+ "instance_budget_estimate"
910
+ ],
911
+ "gate_check": "Instance count * average instance triangles stays within the target polycount budget."
912
+ },
913
+ {
914
+ "stage_number": 3,
915
+ "id": "stage-gn-attributes-and-shading",
916
+ "title": "Named Attribute Storage & Shader Integration",
917
+ "objective": "Persist UV coordinates and per-instance/per-point attributes via Store Named Attribute for material evaluation.",
918
+ "skill_ids": [
919
+ "lighting-material-plan",
920
+ "material-quality-checker"
921
+ ],
922
+ "knowledge_ids": [
923
+ "knowledge.geometry-nodes-fields-and-anonymous-attributes",
924
+ "knowledge.shader-node-gltf-export-portability"
925
+ ],
926
+ "actions": [
927
+ "Write procedural UVs to the Face Corner domain using Store Named Attribute (2D Vector, name 'UVMap') so shaders and exporters recognize texture coordinates.",
928
+ "Read custom named attributes in the Shader Editor via the Attribute node (Instancer mode for per-instance variation, Geometry mode for mesh domains)."
929
+ ],
930
+ "stage_outputs": [
931
+ "named_attribute_contract",
932
+ "procedural_shader_binding"
933
+ ],
934
+ "gate_check": "Spreadsheet editor confirms UVMap exists on Face Corner domain and custom attributes contain non-zero values."
935
+ },
936
+ {
937
+ "stage_number": 4,
938
+ "id": "stage-gn-realization-and-export",
939
+ "title": "Realization Boundary, Validation & Handoff",
940
+ "objective": "Apply the correct realization/baking strategy for the target delivery surface and verify final readiness.",
941
+ "skill_ids": [
942
+ "scene-readiness",
943
+ "glb-web-handoff",
944
+ "pre-handoff-verification",
945
+ "plain-language-response"
946
+ ],
947
+ "knowledge_ids": [
948
+ "knowledge.procedural-instancing-and-realize-instances-budget",
949
+ "knowledge.glb-binary-chunk-alignment-and-khronos-validation"
950
+ ],
951
+ "actions": [
952
+ "Keep instances unrealized for Cycles/EEVEE rendering; for GLB export, either realize low-poly merged geometry with preserved Face Corner UVMap or export collection instances as shared-mesh glTF nodes.",
953
+ "Verify truth states and document that the Geometry Nodes graph itself is baked on export."
954
+ ],
955
+ "stage_outputs": [
956
+ "gn_realization_decision",
957
+ "gn_handoff_report"
958
+ ],
959
+ "gate_check": "Exported or planned mesh preserves UVs and normals, and memory footprint is verified."
960
+ }
961
+ ],
962
+ "required_knowledge_ids": [
963
+ "knowledge.geometry-nodes-fields-and-anonymous-attributes",
964
+ "knowledge.mesh-manifold-normals-and-scale-hygiene",
965
+ "knowledge.procedural-scatter-poisson-disk-and-slope-masking",
966
+ "knowledge.procedural-instancing-and-realize-instances-budget",
967
+ "knowledge.shader-node-gltf-export-portability",
968
+ "knowledge.glb-binary-chunk-alignment-and-khronos-validation"
969
+ ],
970
+ "required_skill_ids": [
971
+ "intent-to-3d-brief-writer",
972
+ "done-criteria",
973
+ "stage-gates",
974
+ "polycount-budget-checker",
975
+ "asset-style-check",
976
+ "lighting-material-plan",
977
+ "material-quality-checker",
978
+ "scene-readiness",
979
+ "glb-web-handoff",
980
+ "pre-handoff-verification",
981
+ "plain-language-response"
982
+ ],
983
+ "expected_outputs": {
984
+ "intermediate": [
985
+ "gn_group_input_schema",
986
+ "procedural_field_graph_spec",
987
+ "named_attribute_contract"
988
+ ],
989
+ "final": [
990
+ "gn_realization_decision",
991
+ "gn_handoff_report"
992
+ ],
993
+ "truth_state_defaults": {
994
+ "runtime_status": "Not Run",
995
+ "artifact_status": "Not Produced"
996
+ }
997
+ },
998
+ "validation_criteria": [
999
+ {
1000
+ "id": "vc.face-corner-uv-domain",
1001
+ "criterion": "Procedurally generated meshes store UV coordinates on the Face Corner domain so seams do not smear.",
1002
+ "measurement_method": "Check Store Named Attribute domain setting in knowledge.geometry-nodes-fields-and-anonymous-attributes.",
1003
+ "pass_threshold": "UVMap attribute is stored as 2D Vector on Face Corner domain."
1004
+ },
1005
+ {
1006
+ "id": "vc.safe-density-clamps",
1007
+ "criterion": "Point distribution density and subdivision levels have hard upper bounds.",
1008
+ "measurement_method": "Inspect Group Input socket max limits and Poisson Disk distance.",
1009
+ "pass_threshold": "Total generated points/vertices cannot exceed budget ceiling on slider drag."
1010
+ },
1011
+ {
1012
+ "id": "vc.realize-instances-discipline",
1013
+ "criterion": "Realize Instances is only used when downstream vertex deformation or merged-mesh export requires it.",
1014
+ "measurement_method": "Audit node graph against knowledge.procedural-instancing-and-realize-instances-budget.",
1015
+ "pass_threshold": "High-poly scatter instances are never realized into a single multi-million-poly mesh."
1016
+ }
1017
+ ],
1018
+ "failure_modes": [
1019
+ {
1020
+ "symptom": "Textures disappear or turn into a solid single-pixel color after Realize Instances or Curve to Mesh.",
1021
+ "root_cause": "UV coordinates were not captured/stored as a Face Corner 2D Vector named attribute ('UVMap') or the Shader Editor references UV Texture Coordinate instead of the named attribute.",
1022
+ "recovery_action": "Store the UV vector via Store Named Attribute (2D Vector, Face Corner, 'UVMap') and connect an Attribute node ('UVMap') in the Shader Editor.",
1023
+ "fallback_skill_id": "blender-troubleshooting"
1024
+ },
1025
+ {
1026
+ "symptom": "Scattered instances float away from the surface or orient sideways.",
1027
+ "root_cause": "Instance collection objects have unapplied location/rotation offsets from world origin or Align Euler to Vector uses the wrong primary axis.",
1028
+ "recovery_action": "Place instance source assets at world origin (or enable Separate Children + Reset Children on Collection Info) and align Z axis to surface Normal.",
1029
+ "fallback_skill_id": "blender-troubleshooting"
1030
+ }
1031
+ ],
1032
+ "blender_versions": {
1033
+ "minimum": "3.6 LTS",
1034
+ "recommended": "4.5.15 LTS",
1035
+ "doc_checked_version": "5.2.3 LTS",
1036
+ "runtime_tested_version": null,
1037
+ "maintained_lts_versions": [
1038
+ "4.2 LTS",
1039
+ "4.5.15 LTS",
1040
+ "5.2.3 LTS"
1041
+ ],
1042
+ "legacy_compatibility_target": "3.6 LTS",
1043
+ "version_considerations": "Blender 3.0+ uses the Fields system; Blender 4.0+ adds Repeat Zones and Simulation Zones (Blender 3.6 LTS supports Simulation Zones), while Blender 4.1+ replaces Auto Smooth with the Smooth by Angle node group. Reconciled with Blender 4.5.15 LTS and 5.2.3 LTS documentation baselines (live runtime: Not Run)."
1044
+ },
1045
+ "source_refs": [
1046
+ {
1047
+ "source_id": "source.blender-manual-geometry-nodes",
1048
+ "locator": "Fields, Attributes, and Instances"
1049
+ },
1050
+ {
1051
+ "source_id": "source.blender-manual-gltf-io",
1052
+ "locator": "Geometry Nodes and Instancing Export"
1053
+ }
1054
+ ],
1055
+ "evidence_status": "version-checked",
1056
+ "related_recipes": [
1057
+ "recipe.stylized-environment-scene",
1058
+ "recipe.web-ready-asset-optimization"
1059
+ ]
1060
+ },
1061
+ {
1062
+ "id": "recipe.uv-and-pbr-material-preparation",
1063
+ "title": "UV Unwrapping, Texel Density & Energy-Conserving PBR Material Preparation",
1064
+ "domain": "uv-texturing-and-baking",
1065
+ "summary": "Complete procedure for unwrapping 3D meshes with hidden seams, uniform texel density, mipmap-safe UV packing, tangent-space MikkTSpace baking, and glTF-compatible Principled BSDF materials.",
1066
+ "aliases": [
1067
+ "uv-unwrapping-and-baking",
1068
+ "pbr-texture-and-shader-prep",
1069
+ "mikktspace-normal-bake-workflow"
1070
+ ],
1071
+ "intent": "Prepare clean, non-overlapping 0-1 UV layouts (or UDIM tiles for offline renders), bake high-to-low or procedural maps without seam artifacts, and wire physically accurate PBR materials.",
1072
+ "intent_signals": [
1073
+ "unwrap UVs and bake normal and ambient occlusion maps",
1074
+ "prepare PBR textures and ORM channel packing for glTF export",
1075
+ "fix UV stretching, texel density mismatch, or normal map seam lines",
1076
+ "bake procedural Blender shaders into image textures"
1077
+ ],
1078
+ "applicable_scenarios": {
1079
+ "use_when": [
1080
+ "A mesh needs UV unwrapping, texture baking (normal, AO, roughness, baseColor), or PBR material validation before rendering or GLB export.",
1081
+ "Procedural Blender materials must be converted into standard image-texture PBR maps for Three.js / React Three Fiber."
1082
+ ],
1083
+ "do_not_use_when": [
1084
+ "The asset uses only flat untextured vertex colors or simple uniform PBR scalars that require no image textures.",
1085
+ "Mesh topology is not yet finalized and major boolean/extrusion changes are still pending (complete recipe.hard-surface-prop Stages 1-2 first)."
1086
+ ]
1087
+ },
1088
+ "prerequisites": [
1089
+ "Finalized low/mid-poly target mesh with applied scale (1.0, 1.0, 1.0) and outward face normals.",
1090
+ "Target texture resolution (e.g., 1024x1024 mobile, 2048x2048 desktop web, 4096x4096 hero offline) decided."
1091
+ ],
1092
+ "inputs": [
1093
+ {
1094
+ "name": "target_mesh",
1095
+ "type": "string",
1096
+ "required": true,
1097
+ "description": "Target mesh to unwrap and texture."
1098
+ },
1099
+ {
1100
+ "name": "texture_resolution_px",
1101
+ "type": "number",
1102
+ "required": true,
1103
+ "default_value": 2048,
1104
+ "description": "Power-of-two texture resolution in pixels (1024, 2048, or 4096)."
1105
+ },
1106
+ {
1107
+ "name": "uv_layout_mode",
1108
+ "type": "string",
1109
+ "required": false,
1110
+ "default_value": "single_0_1_atlas",
1111
+ "description": "single_0_1_atlas (required for standard glTF/GLB) or udim_tiles (offline Cycles only)."
1112
+ }
1113
+ ],
1114
+ "stages": [
1115
+ {
1116
+ "stage_number": 1,
1117
+ "id": "stage-uv-seams-and-unwrap",
1118
+ "title": "Seam Placement, Unwrapping & Texel Density Normalization",
1119
+ "objective": "Mark seams along hard edges and occluded cuts, unwrap with minimal distortion, and equalize texel density.",
1120
+ "skill_ids": [
1121
+ "stage-gates",
1122
+ "material-quality-checker"
1123
+ ],
1124
+ "knowledge_ids": [
1125
+ "knowledge.uv-seam-placement-and-texel-density",
1126
+ "knowledge.udim-vs-single-atlas-uv-packing",
1127
+ "knowledge.mesh-manifold-normals-and-scale-hygiene"
1128
+ ],
1129
+ "actions": [
1130
+ "Apply object scale (Ctrl+A -> Scale), mark UV seams along all sharp shading edges (>=60 deg) and hidden undercuts, and unwrap using Angle Based (organic) or Conformal (hard-surface).",
1131
+ "Average island scale and pack into 0-1 UV space with at least 8-16 pixels of margin at 2048x2048 to prevent mipmap bleeding."
1132
+ ],
1133
+ "stage_outputs": [
1134
+ "uv_unwrap_layout",
1135
+ "texel_density_report"
1136
+ ],
1137
+ "gate_check": "Zero overlapping UV islands (unless intentionally mirrored/stacked with 1-unit offset during baking) and UV Stretch angle overlay is uniform blue."
1138
+ },
1139
+ {
1140
+ "stage_number": 2,
1141
+ "id": "stage-mikktspace-baking",
1142
+ "title": "Tangent-Space MikkTSpace Normal, AO & Procedural Map Baking",
1143
+ "objective": "Bake high-poly details or procedural Blender shader channels into Non-Color and sRGB image textures using Cycles.",
1144
+ "skill_ids": [
1145
+ "cycles-vs-eevee-decision",
1146
+ "output-format-decision"
1147
+ ],
1148
+ "knowledge_ids": [
1149
+ "knowledge.high-to-low-normal-and-ao-baking",
1150
+ "knowledge.normal-roughness-and-orm-channel-packing"
1151
+ ],
1152
+ "actions": [
1153
+ "Triangulate the low-poly mesh (or add a Triangulate modifier with Keep Normals) before baking so tangent bases never flip on export.",
1154
+ "Bake Normal (Tangent space, +X +Y +Z OpenGL, Non-Color 16-bit PNG), Roughness (Non-Color), Metallic (Non-Color), Ambient Occlusion (Non-Color), and Base Color (sRGB) using a cage or tuned Max Ray Distance."
1155
+ ],
1156
+ "stage_outputs": [
1157
+ "baked_pbr_texture_set",
1158
+ "orm_packed_texture_spec"
1159
+ ],
1160
+ "gate_check": "Normal map is baked in Non-Color space with zero ray-miss projection cages and ORM channels are packed R=AO, G=Roughness, B=Metalness."
1161
+ },
1162
+ {
1163
+ "stage_number": 3,
1164
+ "id": "stage-principled-bsdf-wiring",
1165
+ "title": "Energy-Conserving Principled BSDF v2 Wiring",
1166
+ "objective": "Connect baked textures to Principled BSDF sockets following strict glTF 2.0 and physical PBR rules.",
1167
+ "skill_ids": [
1168
+ "lighting-material-plan",
1169
+ "material-quality-checker"
1170
+ ],
1171
+ "knowledge_ids": [
1172
+ "knowledge.principled-bsdf-v2-energy-conserving-pbr",
1173
+ "knowledge.shader-node-gltf-export-portability",
1174
+ "knowledge.normal-roughness-and-orm-channel-packing"
1175
+ ],
1176
+ "actions": [
1177
+ "Wire Base Color (sRGB), Separate Color on the ORM texture (R -> glTF Occlusion, G -> Roughness, B -> Metallic in Non-Color), and Normal Map node (Tangent Space, Non-Color) into Principled BSDF.",
1178
+ "Ensure dielectric baseColor luminance stays between 0.04 and 0.90 linear and conductor baseColor stays above 0.50 with metallic=1.0."
1179
+ ],
1180
+ "stage_outputs": [
1181
+ "portable_pbr_shader_graph"
1182
+ ],
1183
+ "gate_check": "material-quality-checker passes with zero color-space mismatches and 100% glTF-portable node connections."
1184
+ },
1185
+ {
1186
+ "stage_number": 4,
1187
+ "id": "stage-material-validation-and-handoff",
1188
+ "title": "Material Audit & Export Verification",
1189
+ "objective": "Verify texture memory budget, compression readiness, and truth-labeled material handoff.",
1190
+ "skill_ids": [
1191
+ "mobile-glb-budget",
1192
+ "scene-readiness",
1193
+ "pre-handoff-verification",
1194
+ "plain-language-response"
1195
+ ],
1196
+ "knowledge_ids": [
1197
+ "knowledge.texture-resolution-ktx2-and-draco-meshopt-compression",
1198
+ "knowledge.triangle-draw-call-and-vram-budgets"
1199
+ ],
1200
+ "actions": [
1201
+ "Compute uncompressed VRAM footprint (width * height * 4 * 1.33 mip factor per texture) and recommend KTX2 UASTC/ETC1S compression if targeting web/mobile.",
1202
+ "Deliver the verified UV and PBR material readiness report."
1203
+ ],
1204
+ "stage_outputs": [
1205
+ "uv_material_readiness_verdict",
1206
+ "vram_budget_summary"
1207
+ ],
1208
+ "gate_check": "All texture dimensions are powers of two, VRAM fits within tier budget, and truth labels are accurate."
1209
+ }
1210
+ ],
1211
+ "required_knowledge_ids": [
1212
+ "knowledge.uv-seam-placement-and-texel-density",
1213
+ "knowledge.udim-vs-single-atlas-uv-packing",
1214
+ "knowledge.mesh-manifold-normals-and-scale-hygiene",
1215
+ "knowledge.high-to-low-normal-and-ao-baking",
1216
+ "knowledge.normal-roughness-and-orm-channel-packing",
1217
+ "knowledge.principled-bsdf-v2-energy-conserving-pbr",
1218
+ "knowledge.shader-node-gltf-export-portability",
1219
+ "knowledge.texture-resolution-ktx2-and-draco-meshopt-compression",
1220
+ "knowledge.triangle-draw-call-and-vram-budgets"
1221
+ ],
1222
+ "required_skill_ids": [
1223
+ "stage-gates",
1224
+ "material-quality-checker",
1225
+ "cycles-vs-eevee-decision",
1226
+ "output-format-decision",
1227
+ "lighting-material-plan",
1228
+ "mobile-glb-budget",
1229
+ "scene-readiness",
1230
+ "pre-handoff-verification",
1231
+ "plain-language-response"
1232
+ ],
1233
+ "expected_outputs": {
1234
+ "intermediate": [
1235
+ "uv_unwrap_layout",
1236
+ "baked_pbr_texture_set",
1237
+ "portable_pbr_shader_graph"
1238
+ ],
1239
+ "final": [
1240
+ "uv_material_readiness_verdict",
1241
+ "vram_budget_summary"
1242
+ ],
1243
+ "truth_state_defaults": {
1244
+ "runtime_status": "Not Run",
1245
+ "artifact_status": "Not Produced"
1246
+ }
1247
+ },
1248
+ "validation_criteria": [
1249
+ {
1250
+ "id": "vc.non-color-data-maps",
1251
+ "criterion": "All normal, roughness, metallic, and packed ORM image textures use Non-Color (linear) color space.",
1252
+ "measurement_method": "Inspect Image Texture node color space in material-quality-checker.",
1253
+ "pass_threshold": "100% of non-albedo/non-emissive data textures are set to Non-Color."
1254
+ },
1255
+ {
1256
+ "id": "vc.hard-edge-uv-splits",
1257
+ "criterion": "Every sharp edge (>=60 deg) on a normal-baked mesh has a corresponding UV seam and island margin.",
1258
+ "measurement_method": "Verify seam alignment in knowledge.high-to-low-normal-and-ao-baking.",
1259
+ "pass_threshold": "Zero sharp edges lack a UV split; island padding >= 8px at 2K."
1260
+ },
1261
+ {
1262
+ "id": "vc.single-atlas-for-gltf",
1263
+ "criterion": "Meshes targeting glTF/GLB pack UVs within the 0-1 UV square (or valid tiling with KHR_texture_transform) rather than uncollapsed UDIM tiles.",
1264
+ "measurement_method": "Check UV layout mode against knowledge.udim-vs-single-atlas-uv-packing.",
1265
+ "pass_threshold": "Standard glTF export uses 0-1 UV space."
1266
+ }
1267
+ ],
1268
+ "failure_modes": [
1269
+ {
1270
+ "symptom": "Visible dark seam lines appear along UV borders when the normal map is applied.",
1271
+ "root_cause": "The Normal Map Image Texture node is set to 'sRGB' instead of 'Non-Color', or the green channel uses DirectX (-Y) instead of OpenGL (+Y).",
1272
+ "recovery_action": "Switch the Normal Image Texture node Color Space to 'Non-Color' and ensure +Y (OpenGL) orientation.",
1273
+ "fallback_skill_id": "material-quality-checker"
1274
+ },
1275
+ {
1276
+ "symptom": "Texture colors bleed across seams when viewed from a distance in Three.js or Blender.",
1277
+ "root_cause": "Insufficient pixel margin between UV islands causes mipmap downsampling to average adjacent islands.",
1278
+ "recovery_action": "Repack UV islands with at least 8-16 pixels of margin at 2048x2048 and set bake Margin to >= 16 px.",
1279
+ "fallback_skill_id": "material-quality-checker"
1280
+ }
1281
+ ],
1282
+ "blender_versions": {
1283
+ "minimum": "3.6 LTS",
1284
+ "recommended": "4.5.15 LTS",
1285
+ "doc_checked_version": "5.2.3 LTS",
1286
+ "runtime_tested_version": null,
1287
+ "maintained_lts_versions": [
1288
+ "4.2 LTS",
1289
+ "4.5.15 LTS",
1290
+ "5.2.3 LTS"
1291
+ ],
1292
+ "legacy_compatibility_target": "3.6 LTS",
1293
+ "version_considerations": "Blender 4.0+ Principled BSDF renamed Specular to Specular IOR Level and Subsurface to Subsurface Weight/Scale; Separate Color replaces legacy Separate RGB. Reconciled with Blender 4.5.15 LTS and 5.2.3 LTS documentation baselines (live runtime: Not Run)."
1294
+ },
1295
+ "source_refs": [
1296
+ {
1297
+ "source_id": "source.blender-manual-uv-baking",
1298
+ "locator": "UV Unwrapping and Render Baking"
1299
+ },
1300
+ {
1301
+ "source_id": "source.mikktspace-tangent-standard",
1302
+ "locator": "Tangent Space Normal Map Baking"
1303
+ },
1304
+ {
1305
+ "source_id": "source.blender-manual-gltf-io",
1306
+ "locator": "Principled BSDF and ORM Channel Packing"
1307
+ }
1308
+ ],
1309
+ "evidence_status": "version-checked",
1310
+ "related_recipes": [
1311
+ "recipe.hard-surface-prop",
1312
+ "recipe.product-hero-scene",
1313
+ "recipe.blender-to-glb-handoff"
1314
+ ]
1315
+ },
1316
+ {
1317
+ "id": "recipe.presentation-lighting-and-camera",
1318
+ "title": "Studio Lighting, Physical Camera & Color-Managed Render Setup",
1319
+ "domain": "lighting-camera-and-rendering",
1320
+ "summary": "Structured workflow for designing physically plausible studio or interior/portrait lighting, calibrating lens focal length and depth of field, and configuring AgX/Filmic color management and render engines.",
1321
+ "aliases": [
1322
+ "studio-lighting-and-camera-rig",
1323
+ "presentation-render-setup",
1324
+ "agx-cycles-eevee-lookdev"
1325
+ ],
1326
+ "intent": "Configure a production-ready camera, lighting rig, color management pipeline, and render engine (Cycles or EEVEE) with verified contrast ratios, shadow softness, and output format settings.",
1327
+ "intent_signals": [
1328
+ "set up studio three-point lighting and camera for a presentation render",
1329
+ "choose between Cycles and EEVEE and configure AgX color management",
1330
+ "fix blown-out highlights, flat lighting, or wide-angle camera distortion",
1331
+ "plan portrait or architectural interior lighting and camera framing"
1332
+ ],
1333
+ "applicable_scenarios": {
1334
+ "use_when": [
1335
+ "The user needs lighting, camera framing, color management (AgX/Filmic), render engine selection (Cycles vs. EEVEE), and output format configuration for a still or turntable render.",
1336
+ "Applies to product hero shots, character portraits, or interior architectural presentations."
1337
+ ],
1338
+ "do_not_use_when": [
1339
+ "The user only needs binary GLB container inspection without rendering or lighting changes (use recipe.blender-to-glb-handoff).",
1340
+ "Mesh modeling or rigging has not yet started and no scene subject exists."
1341
+ ]
1342
+ },
1343
+ "prerequisites": [
1344
+ "Staged 3D subject or room geometry at real-world metric scale (1 BU = 1m) so inverse-square light falloff and f-stop depth of field behave physically.",
1345
+ "Target output medium (web sRGB PNG/WebP vs. linear OpenEXR compositing) identified."
1346
+ ],
1347
+ "inputs": [
1348
+ {
1349
+ "name": "scene_archetype",
1350
+ "type": "string",
1351
+ "required": true,
1352
+ "default_value": "studio_product_or_portrait",
1353
+ "description": "Scene type: studio_product_or_portrait, interior_archviz, or stylized_diorama."
1354
+ },
1355
+ {
1356
+ "name": "render_engine",
1357
+ "type": "string",
1358
+ "required": false,
1359
+ "default_value": "Cycles",
1360
+ "description": "Primary render engine: Cycles (path-traced accuracy) or EEVEE (real-time speed)."
1361
+ },
1362
+ {
1363
+ "name": "output_format",
1364
+ "type": "string",
1365
+ "required": false,
1366
+ "default_value": "PNG_16bit",
1367
+ "description": "Target image format: PNG_8bit, PNG_16bit, WebP, or OpenEXR_DWAA."
1368
+ }
1369
+ ],
1370
+ "stages": [
1371
+ {
1372
+ "stage_number": 1,
1373
+ "id": "stage-camera-optics-and-framing",
1374
+ "title": "Physical Camera Sensor, Lens & Composition Setup",
1375
+ "objective": "Lock sensor width, focal length, f-stop depth of field, aspect ratio, and visual hierarchy.",
1376
+ "skill_ids": [
1377
+ "camera-composition",
1378
+ "resolution-aspect-decision",
1379
+ "character-portrait",
1380
+ "interior-scene"
1381
+ ],
1382
+ "knowledge_ids": [
1383
+ "knowledge.physically-based-camera-lens-and-dof",
1384
+ "knowledge.modular-architectural-grid-and-metric-scale"
1385
+ ],
1386
+ "actions": [
1387
+ "Configure a 36mm full-frame camera sensor: use 85-105mm for portraits/products to avoid facial/proportion distortion, or 24-35mm with 2-point vertical tilt-shift (Shift X/Y with zero X-axis pitch offset from 90 deg) for architectural interiors.",
1388
+ "Bind Depth of Field to an empty focus target on the subject's primary feature (nearest eye for portraits, brand mark for products)."
1389
+ ],
1390
+ "stage_outputs": [
1391
+ "physical_camera_spec",
1392
+ "framing_and_aspect_plan"
1393
+ ],
1394
+ "gate_check": "Focal length matches scene archetype, verticals are parallel in architectural shots, and headroom/lead-room pass composition-quality-checker."
1395
+ },
1396
+ {
1397
+ "stage_number": 2,
1398
+ "id": "stage-three-point-and-hdri-lighting",
1399
+ "title": "Key/Fill/Rim Illuminance Ratios & Shadow Softness",
1400
+ "objective": "Stage area lights and environment HDRI with deliberate contrast ratios and Kelvin color temperature balance.",
1401
+ "skill_ids": [
1402
+ "lighting-material-plan",
1403
+ "lighting-quality-checker"
1404
+ ],
1405
+ "knowledge_ids": [
1406
+ "knowledge.three-point-and-hdri-studio-lighting",
1407
+ "knowledge.principled-bsdf-v2-energy-conserving-pbr"
1408
+ ],
1409
+ "actions": [
1410
+ "Set key light as the dominant shadow-casting source (e.g., 45 deg azimuth, 30-45 deg elevation), fill light or HDRI at 25-50% of key intensity (2:1 to 8:1 key-to-fill ratio), and rim light opposite the key to carve out the silhouette.",
1411
+ "Control shadow penumbra softness by adjusting Area Light physical size relative to distance rather than disabling shadows."
1412
+ ],
1413
+ "stage_outputs": [
1414
+ "illuminance_ratio_plan",
1415
+ "kelvin_color_balance_spec"
1416
+ ],
1417
+ "gate_check": "Single dominant shadow direction exists, key-to-fill ratio matches mood brief, and HDRI rotation does not wash out shadow contrast."
1418
+ },
1419
+ {
1420
+ "stage_number": 3,
1421
+ "id": "stage-color-and-render-engine",
1422
+ "title": "AgX / Filmic Color Management, Engine & Output Format",
1423
+ "objective": "Configure view transform, exposure, sampling/denoising, and bit-depth output format.",
1424
+ "skill_ids": [
1425
+ "color-management-decision",
1426
+ "cycles-vs-eevee-decision",
1427
+ "output-format-decision"
1428
+ ],
1429
+ "knowledge_ids": [
1430
+ "knowledge.agx-filmic-color-management-and-cycles-eevee"
1431
+ ],
1432
+ "actions": [
1433
+ "Select AgX (Blender 4.0+) with Medium High Contrast look for natural highlight desaturation, or Standard ONLY when exact un-tonemapped hex UI colors are required.",
1434
+ "Configure Cycles (adaptive sampling threshold 0.01-0.02, OpenImageDenoise with Albedo+Normal passes) or EEVEE Next raytracing, and select 16-bit PNG or OpenEXR output."
1435
+ ],
1436
+ "stage_outputs": [
1437
+ "color_management_contract",
1438
+ "render_engine_sampling_plan",
1439
+ "output_format_contract"
1440
+ ],
1441
+ "gate_check": "View transform, exposure, and output bit depth are consistent with downstream delivery requirements."
1442
+ },
1443
+ {
1444
+ "stage_number": 4,
1445
+ "id": "stage-render-quality-and-handoff",
1446
+ "title": "Quality Gate Audit & Evidence-Verified Handoff",
1447
+ "objective": "Validate composition and lighting checklists and produce truth-labeled render readiness documentation.",
1448
+ "skill_ids": [
1449
+ "composition-quality-checker",
1450
+ "lighting-quality-checker",
1451
+ "scene-readiness",
1452
+ "render-export-evidence",
1453
+ "pre-handoff-verification",
1454
+ "plain-language-response"
1455
+ ],
1456
+ "knowledge_ids": [
1457
+ "knowledge.three-point-and-hdri-studio-lighting",
1458
+ "knowledge.physically-based-camera-lens-and-dof"
1459
+ ],
1460
+ "actions": [
1461
+ "Run composition-quality-checker and lighting-quality-checker and record the scene-readiness verdict.",
1462
+ "Verify artifact status via render-export-evidence and summarize next steps in plain language."
1463
+ ],
1464
+ "stage_outputs": [
1465
+ "presentation_render_verdict",
1466
+ "render_handoff_summary"
1467
+ ],
1468
+ "gate_check": "All quality checkers pass and runtime/artifact truth labels are verified."
1469
+ }
1470
+ ],
1471
+ "required_knowledge_ids": [
1472
+ "knowledge.physically-based-camera-lens-and-dof",
1473
+ "knowledge.modular-architectural-grid-and-metric-scale",
1474
+ "knowledge.three-point-and-hdri-studio-lighting",
1475
+ "knowledge.principled-bsdf-v2-energy-conserving-pbr",
1476
+ "knowledge.agx-filmic-color-management-and-cycles-eevee"
1477
+ ],
1478
+ "required_skill_ids": [
1479
+ "camera-composition",
1480
+ "resolution-aspect-decision",
1481
+ "character-portrait",
1482
+ "interior-scene",
1483
+ "lighting-material-plan",
1484
+ "lighting-quality-checker",
1485
+ "color-management-decision",
1486
+ "cycles-vs-eevee-decision",
1487
+ "output-format-decision",
1488
+ "composition-quality-checker",
1489
+ "scene-readiness",
1490
+ "render-export-evidence",
1491
+ "pre-handoff-verification",
1492
+ "plain-language-response"
1493
+ ],
1494
+ "expected_outputs": {
1495
+ "intermediate": [
1496
+ "physical_camera_spec",
1497
+ "illuminance_ratio_plan",
1498
+ "color_management_contract"
1499
+ ],
1500
+ "final": [
1501
+ "presentation_render_verdict",
1502
+ "render_handoff_summary"
1503
+ ],
1504
+ "truth_state_defaults": {
1505
+ "runtime_status": "Not Run",
1506
+ "artifact_status": "Not Produced"
1507
+ }
1508
+ },
1509
+ "validation_criteria": [
1510
+ {
1511
+ "id": "vc.lens-distortion-control",
1512
+ "criterion": "Portraits and close-up products use >= 50mm (85mm ideal) focal length; architectural interiors maintain parallel vertical lines.",
1513
+ "measurement_method": "Inspect camera focal length and rotation X/shift Y in composition-quality-checker.",
1514
+ "pass_threshold": "Zero wide-angle distortion on close-up subjects; zero converging verticals in archviz."
1515
+ },
1516
+ {
1517
+ "id": "vc.highlight-headroom",
1518
+ "criterion": "Bright specular and emissive highlights roll off smoothly without hard RGB channel clipping.",
1519
+ "measurement_method": "Check view transform (AgX/Filmic) and baseColor albedo <= 0.90 in lighting-quality-checker.",
1520
+ "pass_threshold": "AgX or Filmic active with exposure tuned below clipping threshold."
1521
+ },
1522
+ {
1523
+ "id": "vc.banding-free-output",
1524
+ "criterion": "Smooth dark lighting gradients are saved with sufficient bit depth or dithering.",
1525
+ "measurement_method": "Verify output-format-decision bit depth (16-bit PNG or OpenEXR) and dithering >= 1.0.",
1526
+ "pass_threshold": "16-bit or 32-bit float format selected for gradient-heavy scenes."
1527
+ }
1528
+ ],
1529
+ "failure_modes": [
1530
+ {
1531
+ "symptom": "Depth of field has no visible blur even at f/1.4, or blurs the entire scene into an unintelligible smudge.",
1532
+ "root_cause": "Scene geometry was modeled at 100x or 0.01x real-world meter scale, throwing off physical aperture diameter math.",
1533
+ "recovery_action": "Rescale scene to real-world metric units (1 BU = 1m) and apply scale (Ctrl+A -> Scale) before adjusting f-stop.",
1534
+ "fallback_skill_id": "camera-composition"
1535
+ },
1536
+ {
1537
+ "symptom": "Saturated neon or colored area lights clip to harsh yellow/cyan/magenta bands.",
1538
+ "root_cause": "Color Management View Transform is set to 'Standard' or 'Filmic' without AgX chroma attenuation.",
1539
+ "recovery_action": "Switch View Transform to 'AgX' (Blender 4.0+) with 'Medium High Contrast' or 'Punchy' look.",
1540
+ "fallback_skill_id": "color-management-decision"
1541
+ }
1542
+ ],
1543
+ "blender_versions": {
1544
+ "minimum": "3.6 LTS",
1545
+ "recommended": "4.5.15 LTS",
1546
+ "doc_checked_version": "5.2.3 LTS",
1547
+ "runtime_tested_version": null,
1548
+ "maintained_lts_versions": [
1549
+ "4.2 LTS",
1550
+ "4.5.15 LTS",
1551
+ "5.2.3 LTS"
1552
+ ],
1553
+ "legacy_compatibility_target": "3.6 LTS",
1554
+ "version_considerations": "AgX view transform ships natively in Blender 4.0+; Blender 3.6 LTS defaults to Filmic. EEVEE Next in Blender 4.2 LTS replaces legacy screen-space bloom with compositor Glare node. Reconciled with Blender 4.5.15 LTS and 5.2.3 LTS documentation baselines (live runtime: Not Run)."
1555
+ },
1556
+ "source_refs": [
1557
+ {
1558
+ "source_id": "source.blender-manual-lighting-rendering",
1559
+ "locator": "Cameras, Lighting, Cycles & EEVEE Next"
1560
+ },
1561
+ {
1562
+ "source_id": "source.blender-manual-shading-color",
1563
+ "locator": "Color Management — AgX and Filmic"
1564
+ }
1565
+ ],
1566
+ "evidence_status": "version-checked",
1567
+ "related_recipes": [
1568
+ "recipe.product-hero-scene",
1569
+ "recipe.stylized-environment-scene"
1570
+ ]
1571
+ },
1572
+ {
1573
+ "id": "recipe.rigged-and-animated-asset",
1574
+ "title": "Skeletal Rigging, Skin Weight Normalization & NLA Action Baking for Export",
1575
+ "domain": "rigging-and-animation",
1576
+ "summary": "Structured workflow for preparing an armature-rigged or morph-target-animated 3D asset with normalized 4-joint skin weights, baked visual keyframes, and web-ready GLB animation clips.",
1577
+ "aliases": [
1578
+ "skeletal-animation-glb-pipeline",
1579
+ "armature-skinning-and-nla-bake",
1580
+ "character-and-prop-animation-handoff"
1581
+ ],
1582
+ "intent": "Rig, skin, animate, and bake skeletal or shape-key animations so that IK/constraint rigs convert cleanly into self-contained FK deform keyframes and export to GLB without deformation breakage.",
1583
+ "intent_signals": [
1584
+ "rig and animate a character or mechanical prop for GLB export",
1585
+ "bake IK constraints and NLA actions for Three.js or game engines",
1586
+ "fix broken skin weights, stretched meshes, or missing animation clips in GLB",
1587
+ "export multiple named animation clips (idle, walk, open) in one GLB"
1588
+ ],
1589
+ "applicable_scenarios": {
1590
+ "use_when": [
1591
+ "An asset requires skeletal deformation (Armature + vertex weights), rigid bone hierarchies, or morph targets (shape keys) exported to glTF/GLB or rendered.",
1592
+ "Complex Blender constraints (IK, Copy Transforms, Drivers, Rigify control rigs) must be baked to deform bones for downstream engines."
1593
+ ],
1594
+ "do_not_use_when": [
1595
+ "The asset is completely static and requires no animation clips or pose changes.",
1596
+ "The user wants a fluid or smoke volumetric simulation that changes vertex topology every frame (glTF skeletal/morph animation requires fixed vertex count; see recipe.scene-quality-inspection-and-correction)."
1597
+ ]
1598
+ },
1599
+ "prerequisites": [
1600
+ "Both mesh and armature share the exact same world origin with applied Location/Rotation/Scale (scale = 1.0, 1.0, 1.0) before parenting.",
1601
+ "Deformation topology has sufficient edge loops (minimum 3 loops) at bending joints."
1602
+ ],
1603
+ "inputs": [
1604
+ {
1605
+ "name": "animated_subject",
1606
+ "type": "string",
1607
+ "required": true,
1608
+ "description": "Character or articulated prop description."
1609
+ },
1610
+ {
1611
+ "name": "clip_names",
1612
+ "type": "array",
1613
+ "required": true,
1614
+ "description": "Named animation clips to produce (e.g., ['Idle', 'Walk', 'Interact'])."
1615
+ },
1616
+ {
1617
+ "name": "frame_rate_fps",
1618
+ "type": "number",
1619
+ "required": false,
1620
+ "default_value": 30,
1621
+ "description": "Target animation playback frame rate (24, 30, or 60 FPS)."
1622
+ }
1623
+ ],
1624
+ "stages": [
1625
+ {
1626
+ "stage_number": 1,
1627
+ "id": "stage-armature-and-transform-hygiene",
1628
+ "title": "Transform Application, Joint Hierarchy & Deform Bone Separation",
1629
+ "objective": "Align mesh and armature origins, apply transforms, and establish a clean single-root deform bone hierarchy.",
1630
+ "skill_ids": [
1631
+ "intent-to-3d-brief-writer",
1632
+ "stage-gates"
1633
+ ],
1634
+ "knowledge_ids": [
1635
+ "knowledge.armature-joint-hierarchy-and-linear-blend-skinning",
1636
+ "knowledge.mesh-manifold-normals-and-scale-hygiene",
1637
+ "knowledge.organic-sculpt-to-retopology-workflow"
1638
+ ],
1639
+ "actions": [
1640
+ "Apply Location, Rotation, and Scale (Ctrl+A -> All Transforms) on both mesh and Armature before skin binding, and ensure zero negative or non-uniform bone scale exists.",
1641
+ "Organize deform bones under a single root bone with consistent bone roll and mark non-deforming IK/control helper bones with Deform disabled."
1642
+ ],
1643
+ "stage_outputs": [
1644
+ "clean_armature_hierarchy",
1645
+ "transform_alignment_check"
1646
+ ],
1647
+ "gate_check": "Mesh and Armature have identical origins, scale (1,1,1), and control bones have Deform unchecked."
1648
+ },
1649
+ {
1650
+ "stage_number": 2,
1651
+ "id": "stage-skin-weights-and-morphs",
1652
+ "title": "4-Influence Linear Blend Skinning & Shape Key Discipline",
1653
+ "objective": "Limit vertex group influences to 4 bones per vertex, normalize weights to 1.0, and audit morph target budgets.",
1654
+ "skill_ids": [
1655
+ "polycount-budget-checker",
1656
+ "mobile-glb-budget"
1657
+ ],
1658
+ "knowledge_ids": [
1659
+ "knowledge.armature-joint-hierarchy-and-linear-blend-skinning",
1660
+ "knowledge.nla-action-baking-and-morph-target-export"
1661
+ ],
1662
+ "actions": [
1663
+ "Run Weight Paint -> Limit Total (Limit = 4) and Normalize All across all deforming vertex groups so glTF JOINTS_0 and WEIGHTS_0 attributes do not truncate weights on export.",
1664
+ "Keep shape keys (morph targets) restricted to facial/local meshes rather than full-body high-poly meshes to avoid multiplying vertex buffer size."
1665
+ ],
1666
+ "stage_outputs": [
1667
+ "normalized_skin_weight_spec",
1668
+ "morph_target_budget_plan"
1669
+ ],
1670
+ "gate_check": "Maximum 4 bone influences per vertex, sum of weights = 1.0 for every vertex, and morph target buffer overhead fits budget."
1671
+ },
1672
+ {
1673
+ "stage_number": 3,
1674
+ "id": "stage-nla-action-baking",
1675
+ "title": "Visual Keying Action Bake & NLA Track Stashing",
1676
+ "objective": "Bake IK/constraint/driver motion onto deform bones and organize named clips as NLA tracks.",
1677
+ "skill_ids": [
1678
+ "glb-animation-handoff",
1679
+ "r3f-component-plan"
1680
+ ],
1681
+ "knowledge_ids": [
1682
+ "knowledge.nla-action-baking-and-morph-target-export",
1683
+ "knowledge.rigid-body-cloth-and-simulation-cache-baking",
1684
+ "knowledge.gltf-2-coordinate-system-and-transform-conventions"
1685
+ ],
1686
+ "actions": [
1687
+ "Run Pose -> Animation -> Bake Action with Only Selected Deform Bones, Visual Keying = True, Clear Constraints = True, and Bake Data = Pose.",
1688
+ "Push each baked Action down into a dedicated NLA track (or Action Stash) with exact clip naming ('Idle', 'Walk') and matching start/end pose keyframes for seamless loops."
1689
+ ],
1690
+ "stage_outputs": [
1691
+ "baked_nla_clip_manifest",
1692
+ "web_animation_contract"
1693
+ ],
1694
+ "gate_check": "All exported clips are baked onto deform bones without live Blender constraints, and looping clips have identical start/end poses."
1695
+ },
1696
+ {
1697
+ "stage_number": 4,
1698
+ "id": "stage-animation-validation-and-handoff",
1699
+ "title": "Animation Handoff Contract & Evidence Verification",
1700
+ "objective": "Document clip names, durations, FPS, looping behavior, and R3F/Three.js AnimationMixer integration.",
1701
+ "skill_ids": [
1702
+ "glb-animation-handoff",
1703
+ "glb-web-handoff",
1704
+ "pre-handoff-verification",
1705
+ "plain-language-response"
1706
+ ],
1707
+ "knowledge_ids": [
1708
+ "knowledge.glb-binary-chunk-alignment-and-khronos-validation",
1709
+ "knowledge.threejs-r3f-tone-mapping-and-environment-parity"
1710
+ ],
1711
+ "actions": [
1712
+ "Verify animation count and accessor integrity if a GLB file is present (via blendops glb-inspect), or keep statuses Not Run / Not Produced for planning.",
1713
+ "Deliver the complete animation handoff contract for the web/engine team."
1714
+ ],
1715
+ "stage_outputs": [
1716
+ "animation_readiness_verdict",
1717
+ "animation_handoff_report"
1718
+ ],
1719
+ "gate_check": "Clip contract specifies exact clip names, FPS, loop mode, and truthful runtime/artifact status."
1720
+ }
1721
+ ],
1722
+ "required_knowledge_ids": [
1723
+ "knowledge.armature-joint-hierarchy-and-linear-blend-skinning",
1724
+ "knowledge.mesh-manifold-normals-and-scale-hygiene",
1725
+ "knowledge.organic-sculpt-to-retopology-workflow",
1726
+ "knowledge.nla-action-baking-and-morph-target-export",
1727
+ "knowledge.rigid-body-cloth-and-simulation-cache-baking",
1728
+ "knowledge.gltf-2-coordinate-system-and-transform-conventions",
1729
+ "knowledge.glb-binary-chunk-alignment-and-khronos-validation",
1730
+ "knowledge.threejs-r3f-tone-mapping-and-environment-parity"
1731
+ ],
1732
+ "required_skill_ids": [
1733
+ "intent-to-3d-brief-writer",
1734
+ "stage-gates",
1735
+ "polycount-budget-checker",
1736
+ "mobile-glb-budget",
1737
+ "glb-animation-handoff",
1738
+ "r3f-component-plan",
1739
+ "glb-web-handoff",
1740
+ "pre-handoff-verification",
1741
+ "plain-language-response"
1742
+ ],
1743
+ "expected_outputs": {
1744
+ "intermediate": [
1745
+ "clean_armature_hierarchy",
1746
+ "normalized_skin_weight_spec",
1747
+ "baked_nla_clip_manifest"
1748
+ ],
1749
+ "final": [
1750
+ "animation_readiness_verdict",
1751
+ "animation_handoff_report"
1752
+ ],
1753
+ "truth_state_defaults": {
1754
+ "runtime_status": "Not Run",
1755
+ "artifact_status": "Not Produced"
1756
+ }
1757
+ },
1758
+ "validation_criteria": [
1759
+ {
1760
+ "id": "vc.four-joint-weight-limit",
1761
+ "criterion": "No vertex is weighted to more than 4 deform bones, and weights sum to 1.0.",
1762
+ "measurement_method": "Check Limit Total (4) and Normalize All in knowledge.armature-joint-hierarchy-and-linear-blend-skinning.",
1763
+ "pass_threshold": "Max 4 joint influences per vertex across all skinned meshes."
1764
+ },
1765
+ {
1766
+ "id": "vc.visual-keying-baked",
1767
+ "criterion": "All IK, driver, and constraint motion is baked to deform bone keyframes before glTF export.",
1768
+ "measurement_method": "Verify Bake Action with Visual Keying in glb-animation-handoff.",
1769
+ "pass_threshold": "Zero unbaked Blender-only bone constraints required for playback."
1770
+ },
1771
+ {
1772
+ "id": "vc.deform-only-bones",
1773
+ "criterion": "glTF exporter is configured to export Deform Bones Only so helper/IK bones do not bloat joint matrices.",
1774
+ "measurement_method": "Verify Export Deformation Bones Only option in animation handoff plan.",
1775
+ "pass_threshold": "Only deform hierarchy joints are exported."
1776
+ }
1777
+ ],
1778
+ "failure_modes": [
1779
+ {
1780
+ "symptom": "Character mesh explodes, flips inside out, or scales 100x when animation plays in Three.js.",
1781
+ "root_cause": "Mesh or Armature had unapplied scale/rotation before parenting, or non-uniform bone scaling was used in parent bones.",
1782
+ "recovery_action": "Unparent with Keep Transform, apply Location/Rotation/Scale (Ctrl+A) to both Mesh and Armature at Rest Pose, re-parent to Armature, and avoid non-uniform scale on parent bones.",
1783
+ "fallback_skill_id": "glb-animation-handoff"
1784
+ },
1785
+ {
1786
+ "symptom": "Exported GLB contains only one animation clip or the limbs stay frozen while the root moves.",
1787
+ "root_cause": "Actions were not pushed down into separate NLA tracks, or IK constraints were not baked with Visual Keying onto deform bones.",
1788
+ "recovery_action": "Bake each action with Visual Keying onto deform bones, stash each into its own named NLA track, and enable NLA Strips export in glTF exporter.",
1789
+ "fallback_skill_id": "glb-animation-handoff"
1790
+ }
1791
+ ],
1792
+ "blender_versions": {
1793
+ "minimum": "3.6 LTS",
1794
+ "recommended": "4.5.15 LTS",
1795
+ "doc_checked_version": "5.2.3 LTS",
1796
+ "runtime_tested_version": null,
1797
+ "maintained_lts_versions": [
1798
+ "4.2 LTS",
1799
+ "4.5.15 LTS",
1800
+ "5.2.3 LTS"
1801
+ ],
1802
+ "legacy_compatibility_target": "3.6 LTS",
1803
+ "version_considerations": "Blender 4.0+ replaced numbered Armature bone layers with named Bone Collections; glTF 2.0 exporter in 4.2 LTS supports exporting by Action Filter or NLA Tracks. Reconciled with Blender 4.5.15 LTS and 5.2.3 LTS documentation baselines (live runtime: Not Run)."
1804
+ },
1805
+ "source_refs": [
1806
+ {
1807
+ "source_id": "source.blender-manual-rigging-animation",
1808
+ "locator": "Armatures, Skinning & Action Baking"
1809
+ },
1810
+ {
1811
+ "source_id": "source.khronos-gltf-2-spec",
1812
+ "locator": "Skins (JOINTS_0 / WEIGHTS_0) and Animations"
1813
+ }
1814
+ ],
1815
+ "evidence_status": "version-checked",
1816
+ "related_recipes": [
1817
+ "recipe.blender-to-glb-handoff",
1818
+ "recipe.web-ready-asset-optimization"
1819
+ ]
1820
+ },
1821
+ {
1822
+ "id": "recipe.scene-quality-inspection-and-correction",
1823
+ "title": "Multi-Gate Scene Quality Inspection, Root-Cause Triage & Correction Plan",
1824
+ "domain": "lighting-camera-and-rendering",
1825
+ "summary": "Diagnostic and quality-gate procedure that audits an existing or planned Blender scene across geometry, materials, lighting, composition, and performance budgets, isolating root causes and prescribing targeted corrections.",
1826
+ "aliases": [
1827
+ "scene-quality-audit-workflow",
1828
+ "blender-diagnostic-and-triage",
1829
+ "pre-render-pre-export-gate-review"
1830
+ ],
1831
+ "intent": "Systematically evaluate a 3D scene or plan against domain quality rubrics, classify blockers vs. warnings, run 4-phase root-cause troubleshooting on defects, and issue an evidence-backed Pass/Warn/Fail readiness verdict.",
1832
+ "intent_signals": [
1833
+ "inspect my Blender scene and tell me why the render or export looks wrong",
1834
+ "run a complete quality check on lighting, materials, composition, and polycount",
1835
+ "troubleshoot shading glitches, noisy renders, or blown-out colors",
1836
+ "audit scene readiness before rendering or exporting to GLB"
1837
+ ],
1838
+ "applicable_scenarios": {
1839
+ "use_when": [
1840
+ "A scene plan or rendered/exported output exhibits visual defects, budget overruns, or uncertain readiness before final delivery.",
1841
+ "The user asks for a comprehensive quality review or systematic troubleshooting of a Blender workflow."
1842
+ ],
1843
+ "do_not_use_when": [
1844
+ "No scene brief, plan, or symptom exists yet and the user is asking for initial brainstorming from scratch (use blender-brainstorming first)."
1845
+ ]
1846
+ },
1847
+ "prerequisites": [
1848
+ "Description of the current scene state, plan, or observed defect symptoms.",
1849
+ "Intended target delivery surface (offline render, desktop web GLB, or mobile web GLB)."
1850
+ ],
1851
+ "inputs": [
1852
+ {
1853
+ "name": "scene_context_or_symptoms",
1854
+ "type": "string",
1855
+ "required": true,
1856
+ "description": "Scene description, checklist state, or observed visual/export defects."
1857
+ },
1858
+ {
1859
+ "name": "target_device_tier",
1860
+ "type": "string",
1861
+ "required": false,
1862
+ "default_value": "desktop_web",
1863
+ "description": "Budget tier for validation: mobile_web, desktop_web, or offline_render."
1864
+ }
1865
+ ],
1866
+ "stages": [
1867
+ {
1868
+ "stage_number": 1,
1869
+ "id": "stage-symptom-triage-and-geometry-audit",
1870
+ "title": "4-Phase Symptom Triage & Geometry/Budget Audit",
1871
+ "objective": "Isolate the subsystem causing defects (geometry, UV/shader, lighting/color, or export) and audit mesh hygiene and triangle budgets.",
1872
+ "skill_ids": [
1873
+ "blender-troubleshooting",
1874
+ "polycount-budget-checker"
1875
+ ],
1876
+ "knowledge_ids": [
1877
+ "knowledge.mesh-manifold-normals-and-scale-hygiene",
1878
+ "knowledge.boolean-bevel-shading-cleanup",
1879
+ "knowledge.triangle-draw-call-and-vram-budgets"
1880
+ ],
1881
+ "actions": [
1882
+ "Apply the 4-phase troubleshooting protocol: (1) Observe exact symptom, (2) Isolate subsystem layer, (3) Verify invariant (scale, normals, color space), (4) Prescribe minimal reversible fix.",
1883
+ "Check per-mesh and total triangle counts, draw calls, applied transforms, and face orientation."
1884
+ ],
1885
+ "stage_outputs": [
1886
+ "root_cause_triage_report",
1887
+ "geometry_budget_audit"
1888
+ ],
1889
+ "gate_check": "Every reported defect is mapped to a concrete subsystem invariant rather than guesswork."
1890
+ },
1891
+ {
1892
+ "stage_number": 2,
1893
+ "id": "stage-material-and-lighting-audit",
1894
+ "title": "Material PBR Sanity & Lighting/Color Audit",
1895
+ "objective": "Verify shader energy conservation, texture color spaces, lighting ratios, and view transform configuration.",
1896
+ "skill_ids": [
1897
+ "material-quality-checker",
1898
+ "lighting-quality-checker",
1899
+ "color-management-decision"
1900
+ ],
1901
+ "knowledge_ids": [
1902
+ "knowledge.principled-bsdf-v2-energy-conserving-pbr",
1903
+ "knowledge.normal-roughness-and-orm-channel-packing",
1904
+ "knowledge.three-point-and-hdri-studio-lighting",
1905
+ "knowledge.agx-filmic-color-management-and-cycles-eevee"
1906
+ ],
1907
+ "actions": [
1908
+ "Audit all materials for Non-Color data map settings, plausible albedo ranges (0.04-0.90), and glTF export compatibility.",
1909
+ "Audit light intensity ratios, shadow softness, and AgX/Filmic view transform settings."
1910
+ ],
1911
+ "stage_outputs": [
1912
+ "material_quality_verdict",
1913
+ "lighting_quality_verdict"
1914
+ ],
1915
+ "gate_check": "All material and lighting blockers are itemized with exact parameter corrections."
1916
+ },
1917
+ {
1918
+ "stage_number": 3,
1919
+ "id": "stage-composition-and-holistic-readiness",
1920
+ "title": "Composition Audit & Holistic Scene Readiness Verdict",
1921
+ "objective": "Check camera framing, focal hierarchy, and synthesize the unified Pass/Warn/Fail readiness gate.",
1922
+ "skill_ids": [
1923
+ "composition-quality-checker",
1924
+ "scene-readiness",
1925
+ "stage-gates"
1926
+ ],
1927
+ "knowledge_ids": [
1928
+ "knowledge.physically-based-camera-lens-and-dof",
1929
+ "knowledge.environment-depth-layering-and-atmospheric-perspective"
1930
+ ],
1931
+ "actions": [
1932
+ "Evaluate focal length, subject framing, headroom/lead-room, and background separation.",
1933
+ "Aggregate all domain checker results into a single scene-readiness Pass/Warn/Fail verdict with prioritized blocker remediation steps."
1934
+ ],
1935
+ "stage_outputs": [
1936
+ "composition_quality_verdict",
1937
+ "holistic_scene_readiness_report"
1938
+ ],
1939
+ "gate_check": "Any single domain Fail downgrades holistic scene-readiness to Fail/Not Ready until resolved."
1940
+ },
1941
+ {
1942
+ "stage_number": 4,
1943
+ "id": "stage-correction-verification-and-response",
1944
+ "title": "Pre-Handoff Verification & Plain-Language Action Plan",
1945
+ "objective": "Verify evidence truth states and deliver a prioritized, jargon-free correction and readiness report.",
1946
+ "skill_ids": [
1947
+ "render-export-evidence",
1948
+ "pre-handoff-verification",
1949
+ "plain-language-response"
1950
+ ],
1951
+ "knowledge_ids": [
1952
+ "knowledge.glb-binary-chunk-alignment-and-khronos-validation"
1953
+ ],
1954
+ "actions": [
1955
+ "Enforce the 7-point pre-handoff verification gate so unexecuted plans remain Runtime status: Not Run and Artifact status: Not Produced.",
1956
+ "Present the prioritized correction checklist in plain language."
1957
+ ],
1958
+ "stage_outputs": [
1959
+ "verified_correction_plan",
1960
+ "stakeholder_quality_summary"
1961
+ ],
1962
+ "gate_check": "All truth states are accurate and every blocker has a deterministic remediation action."
1963
+ }
1964
+ ],
1965
+ "required_knowledge_ids": [
1966
+ "knowledge.mesh-manifold-normals-and-scale-hygiene",
1967
+ "knowledge.boolean-bevel-shading-cleanup",
1968
+ "knowledge.triangle-draw-call-and-vram-budgets",
1969
+ "knowledge.principled-bsdf-v2-energy-conserving-pbr",
1970
+ "knowledge.normal-roughness-and-orm-channel-packing",
1971
+ "knowledge.three-point-and-hdri-studio-lighting",
1972
+ "knowledge.agx-filmic-color-management-and-cycles-eevee",
1973
+ "knowledge.physically-based-camera-lens-and-dof",
1974
+ "knowledge.environment-depth-layering-and-atmospheric-perspective",
1975
+ "knowledge.glb-binary-chunk-alignment-and-khronos-validation"
1976
+ ],
1977
+ "required_skill_ids": [
1978
+ "blender-troubleshooting",
1979
+ "polycount-budget-checker",
1980
+ "material-quality-checker",
1981
+ "lighting-quality-checker",
1982
+ "color-management-decision",
1983
+ "composition-quality-checker",
1984
+ "scene-readiness",
1985
+ "stage-gates",
1986
+ "render-export-evidence",
1987
+ "pre-handoff-verification",
1988
+ "plain-language-response"
1989
+ ],
1990
+ "expected_outputs": {
1991
+ "intermediate": [
1992
+ "root_cause_triage_report",
1993
+ "material_quality_verdict",
1994
+ "lighting_quality_verdict",
1995
+ "composition_quality_verdict"
1996
+ ],
1997
+ "final": [
1998
+ "holistic_scene_readiness_report",
1999
+ "verified_correction_plan",
2000
+ "stakeholder_quality_summary"
2001
+ ],
2002
+ "truth_state_defaults": {
2003
+ "runtime_status": "Not Run",
2004
+ "artifact_status": "Not Produced"
2005
+ }
2006
+ },
2007
+ "validation_criteria": [
2008
+ {
2009
+ "id": "vc.blocker-downgrade-discipline",
2010
+ "criterion": "Any unresolved P0 blocker in geometry, materials, lighting, or composition prevents a Pass readiness verdict.",
2011
+ "measurement_method": "Verify scene-readiness aggregation rules across the 4 domain checkers.",
2012
+ "pass_threshold": "Zero unresolved Fail items in a Pass verdict."
2013
+ },
2014
+ {
2015
+ "id": "vc.root-cause-specificity",
2016
+ "criterion": "Troubleshooting pinpoints concrete Blender settings (e.g., Non-Color space, unapplied scale, Exact boolean solver) rather than vague advice.",
2017
+ "measurement_method": "Check root_cause_triage_report against linked knowledge records.",
2018
+ "pass_threshold": "Every defect cites an observable check and specific parameter fix."
2019
+ },
2020
+ {
2021
+ "id": "vc.no-false-verification",
2022
+ "criterion": "Inspecting a plan is never reported as inspecting a live rendered frame or GLB file unless the file exists on disk.",
2023
+ "measurement_method": "Verify pre-handoff-verification truth-state gate.",
2024
+ "pass_threshold": "100% separation between plan review and artifact verification."
2025
+ }
2026
+ ],
2027
+ "failure_modes": [
2028
+ {
2029
+ "symptom": "Agent changes lighting and camera repeatedly when the actual defect is inverted face normals or sRGB on a normal map.",
2030
+ "root_cause": "Skipping Phase 1 subsystem isolation in blender-troubleshooting.",
2031
+ "recovery_action": "Always verify mesh scale/normals and texture color-space invariants before modifying lighting or camera rigs.",
2032
+ "fallback_skill_id": "blender-troubleshooting"
2033
+ },
2034
+ {
2035
+ "symptom": "Scene passes individual aesthetic checks but crashes mobile web browsers on load.",
2036
+ "root_cause": "Unchecked 4K uncompressed textures and high triangle counts exceeded device VRAM limits.",
2037
+ "recovery_action": "Run polycount-budget-checker and material-quality-checker against mobile-glb-budget limits.",
2038
+ "fallback_skill_id": "mobile-glb-budget"
2039
+ }
2040
+ ],
2041
+ "blender_versions": {
2042
+ "minimum": "3.6 LTS",
2043
+ "recommended": "4.5.15 LTS",
2044
+ "doc_checked_version": "5.2.3 LTS",
2045
+ "runtime_tested_version": null,
2046
+ "maintained_lts_versions": [
2047
+ "4.2 LTS",
2048
+ "4.5.15 LTS",
2049
+ "5.2.3 LTS"
2050
+ ],
2051
+ "legacy_compatibility_target": "3.6 LTS",
2052
+ "version_considerations": "Check whether the scene uses Blender 3.6 LTS (Auto Smooth property, Legacy EEVEE, Filmic) or Blender 4.2 LTS (Smooth by Angle modifier, EEVEE Next, AgX, Principled BSDF v2) before prescribing UI steps. Reconciled with Blender 4.5.15 LTS and 5.2.3 LTS documentation baselines (live runtime: Not Run)."
2053
+ },
2054
+ "source_refs": [
2055
+ {
2056
+ "source_id": "source.blender-studio-pipeline",
2057
+ "locator": "Asset & Scene Quality Gates"
2058
+ },
2059
+ {
2060
+ "source_id": "source.khronos-gltf-asset-auditor",
2061
+ "locator": "3D Asset Quality & Conformance Checks"
2062
+ }
2063
+ ],
2064
+ "evidence_status": "version-checked",
2065
+ "related_recipes": [
2066
+ "recipe.product-hero-scene",
2067
+ "recipe.blender-to-glb-handoff",
2068
+ "recipe.web-ready-asset-optimization"
2069
+ ]
2070
+ },
2071
+ {
2072
+ "id": "recipe.blender-to-glb-handoff",
2073
+ "title": "Verified Blender-to-GLB Export, Binary Inspection & Web Viewer Handoff",
2074
+ "domain": "interchange-gltf-and-web",
2075
+ "summary": "End-to-end procedure for preparing a Blender asset for glTF 2.0 / GLB export, validating binary container structure and Khronos invariants via local CLI tools, and generating Three.js / React Three Fiber viewer integration contracts.",
2076
+ "aliases": [
2077
+ "glb-web-delivery-pipeline",
2078
+ "gltf-export-and-r3f-handoff",
2079
+ "blender-to-threejs-handoff"
2080
+ ],
2081
+ "intent": "Ensure a Blender asset exports cleanly to a spec-compliant GLB 2.0 binary container, run deterministic structural inspection (`blendops glb-inspect` / `glb-handoff`), and provide complete Three.js or React Three Fiber integration guidance.",
2082
+ "intent_signals": [
2083
+ "export my Blender model to GLB for a Three.js or React Three Fiber website",
2084
+ "inspect a GLB file and generate a web handoff report",
2085
+ "fix coordinate axes (+Z up vs +Y up), scale, or dark materials in exported GLB",
2086
+ "plan a React Three Fiber useGLTF component with Suspense and DRACO/KTX2"
2087
+ ],
2088
+ "applicable_scenarios": {
2089
+ "use_when": [
2090
+ "The user wants to export a Blender asset/scene to `.glb` and hand it off to a web frontend (Three.js or React Three Fiber).",
2091
+ "An existing `.glb` file needs deterministic container/accessor inspection (`scripts/inspect-glb.mjs`) and a schema-validated handoff manifest."
2092
+ ],
2093
+ "do_not_use_when": [
2094
+ "The deliverable is exclusively an offline still image or video render with no 3D file interchange (use recipe.presentation-lighting-and-camera)."
2095
+ ]
2096
+ },
2097
+ "prerequisites": [
2098
+ "Applied transforms (Location/Rotation/Scale) and glTF-compatible Principled BSDF materials (or baked textures).",
2099
+ "Target web viewer stack (`threejs` or `r3f`) and device budget tier identified."
2100
+ ],
2101
+ "inputs": [
2102
+ {
2103
+ "name": "asset_or_glb_path",
2104
+ "type": "string",
2105
+ "required": true,
2106
+ "description": "Target asset name or on-disk path to an exported .glb file."
2107
+ },
2108
+ {
2109
+ "name": "viewer_stack",
2110
+ "type": "string",
2111
+ "required": true,
2112
+ "default_value": "r3f",
2113
+ "description": "Consumer web stack: threejs or r3f (React Three Fiber)."
2114
+ },
2115
+ {
2116
+ "name": "compression_mode",
2117
+ "type": "string",
2118
+ "required": false,
2119
+ "default_value": "draco_or_meshopt",
2120
+ "description": "Geometry/texture compression strategy: none, draco, meshopt, or ktx2_plus_meshopt."
2121
+ }
2122
+ ],
2123
+ "stages": [
2124
+ {
2125
+ "stage_number": 1,
2126
+ "id": "stage-pre-export-gltf-audit",
2127
+ "title": "Coordinate Transform, Shader Portability & Animation Pre-Export Check",
2128
+ "objective": "Verify +Y Up conversion readiness, applied scale, baked procedural textures, and NLA animation tracks before export.",
2129
+ "skill_ids": [
2130
+ "material-quality-checker",
2131
+ "polycount-budget-checker",
2132
+ "glb-animation-handoff"
2133
+ ],
2134
+ "knowledge_ids": [
2135
+ "knowledge.gltf-2-coordinate-system-and-transform-conventions",
2136
+ "knowledge.shader-node-gltf-export-portability",
2137
+ "knowledge.normal-roughness-and-orm-channel-packing"
2138
+ ],
2139
+ "actions": [
2140
+ "Verify all objects have applied Scale (1,1,1) and Rotation (0,0,0) with -Y Forward / +Z Up in Blender so the glTF exporter's '+Y Up' option converts cleanly to +Y Up / +Z Forward.",
2141
+ "Confirm all shader graphs use core glTF 2.0 Principled BSDF sockets (Base Color, Metallic, Roughness, Normal, Occlusion, Emissive) with zero unbaked procedural nodes."
2142
+ ],
2143
+ "stage_outputs": [
2144
+ "pre_export_gltf_checklist",
2145
+ "shader_portability_confirmation"
2146
+ ],
2147
+ "gate_check": "100% of exported meshes have applied transforms and glTF-compatible material sockets."
2148
+ },
2149
+ {
2150
+ "stage_number": 2,
2151
+ "id": "stage-glb-container-inspection",
2152
+ "title": "Binary GLB 2.0 Structural Inspection & Evidence Ledger",
2153
+ "objective": "Inspect the exported `.glb` binary container (if present on disk) using `blendops glb-inspect` or record `Not Produced` if planning only.",
2154
+ "skill_ids": [
2155
+ "render-export-evidence",
2156
+ "preview-report"
2157
+ ],
2158
+ "knowledge_ids": [
2159
+ "knowledge.glb-binary-chunk-alignment-and-khronos-validation",
2160
+ "knowledge.texture-resolution-ktx2-and-draco-meshopt-compression"
2161
+ ],
2162
+ "actions": [
2163
+ "If a `.glb` file exists on disk, run `blendops glb-inspect <file.glb>` to validate the 12-byte header (`magic 0x46546C67`, `version 2`), 4-byte JSON/BIN chunk alignment, accessor bounds, mesh/material/texture counts, and required extensions (`KHR_draco_mesh_compression`, `KHR_texture_basisu`, `EXT_meshopt_compression`).",
2164
+ "Record the exact 4-tier validation statuses (Tier 1 Container Structural, Tier 2 Khronos glTF Spec, Tier 3 Visual Quality, Tier 4 Live Runtime)."
2165
+ ],
2166
+ "stage_outputs": [
2167
+ "glb_inspection_report",
2168
+ "preview_report_markdown"
2169
+ ],
2170
+ "gate_check": "Container inspection passes Tier 1 structural checks (or status is explicitly marked Artifact status: Not Produced if no file was exported yet)."
2171
+ },
2172
+ {
2173
+ "stage_number": 3,
2174
+ "id": "stage-web-viewer-component-plan",
2175
+ "title": "Three.js / React Three Fiber Viewer & Tone-Mapping Parity Plan",
2176
+ "objective": "Design the consumer viewer component shape, loader decoders (DRACO/KTX2/Meshopt), and tone-mapping/environment parity.",
2177
+ "skill_ids": [
2178
+ "r3f-component-plan",
2179
+ "glb-web-handoff"
2180
+ ],
2181
+ "knowledge_ids": [
2182
+ "knowledge.threejs-r3f-tone-mapping-and-environment-parity",
2183
+ "knowledge.agx-filmic-color-management-and-cycles-eevee"
2184
+ ],
2185
+ "actions": [
2186
+ "Specify Three.js / R3F color management (`THREE.AgXToneMapping` or `THREE.ACESFilmicToneMapping`, `outputColorSpace = THREE.SRGBColorSpace`, PMREM environment map) so web rendering matches Blender lookdev.",
2187
+ "Plan the React Three Fiber component boundary (`<Suspense fallback={...}>` outside the `useGLTF` child component, `useGLTF.preload()`, `useAnimations()` cleanup, and decoder paths)."
2188
+ ],
2189
+ "stage_outputs": [
2190
+ "r3f_or_threejs_component_plan",
2191
+ "glb_web_handoff_manifest"
2192
+ ],
2193
+ "gate_check": "Viewer plan includes explicit decoder setup for any compressed extensions and matches Blender's tone-mapping curve."
2194
+ },
2195
+ {
2196
+ "stage_number": 4,
2197
+ "id": "stage-handoff-verification-and-summary",
2198
+ "title": "Pre-Handoff Gate & Plain-Language Web Delivery Summary",
2199
+ "objective": "Run the 7-point pre-handoff verification check and deliver the final stakeholder and developer handoff report.",
2200
+ "skill_ids": [
2201
+ "pre-handoff-verification",
2202
+ "plain-language-response"
2203
+ ],
2204
+ "knowledge_ids": [
2205
+ "knowledge.glb-binary-chunk-alignment-and-khronos-validation"
2206
+ ],
2207
+ "actions": [
2208
+ "Verify that structural container pass is never conflated with visual rendering verification or live Blender execution.",
2209
+ "Deliver the final developer handoff manifest and plain-language summary."
2210
+ ],
2211
+ "stage_outputs": [
2212
+ "verified_glb_handoff_package",
2213
+ "stakeholder_handoff_response"
2214
+ ],
2215
+ "gate_check": "All 7 pre-handoff checks pass and truth labels (`Runtime status`, `Artifact status`) are strictly accurate."
2216
+ }
2217
+ ],
2218
+ "required_knowledge_ids": [
2219
+ "knowledge.gltf-2-coordinate-system-and-transform-conventions",
2220
+ "knowledge.shader-node-gltf-export-portability",
2221
+ "knowledge.normal-roughness-and-orm-channel-packing",
2222
+ "knowledge.glb-binary-chunk-alignment-and-khronos-validation",
2223
+ "knowledge.texture-resolution-ktx2-and-draco-meshopt-compression",
2224
+ "knowledge.threejs-r3f-tone-mapping-and-environment-parity",
2225
+ "knowledge.agx-filmic-color-management-and-cycles-eevee"
2226
+ ],
2227
+ "required_skill_ids": [
2228
+ "material-quality-checker",
2229
+ "polycount-budget-checker",
2230
+ "glb-animation-handoff",
2231
+ "render-export-evidence",
2232
+ "preview-report",
2233
+ "r3f-component-plan",
2234
+ "glb-web-handoff",
2235
+ "pre-handoff-verification",
2236
+ "plain-language-response"
2237
+ ],
2238
+ "expected_outputs": {
2239
+ "intermediate": [
2240
+ "pre_export_gltf_checklist",
2241
+ "glb_inspection_report",
2242
+ "r3f_or_threejs_component_plan"
2243
+ ],
2244
+ "final": [
2245
+ "glb_web_handoff_manifest",
2246
+ "verified_glb_handoff_package",
2247
+ "stakeholder_handoff_response"
2248
+ ],
2249
+ "truth_state_defaults": {
2250
+ "runtime_status": "Not Run",
2251
+ "artifact_status": "Not Produced"
2252
+ }
2253
+ },
2254
+ "validation_criteria": [
2255
+ {
2256
+ "id": "vc.glb-chunk-alignment",
2257
+ "criterion": "Exported GLB binary satisfies 12-byte header magic (0x46546C67, version 2) and 4-byte JSON/BIN chunk alignment.",
2258
+ "measurement_method": "Run `blendops glb-inspect` (`scripts/inspect-glb.mjs`).",
2259
+ "pass_threshold": "Tier 1 Container Structural status = Passed with 0 errors."
2260
+ },
2261
+ {
2262
+ "id": "vc.decoder-requirement-matching",
2263
+ "criterion": "Any `KHR_draco_mesh_compression`, `EXT_meshopt_compression`, or `KHR_texture_basisu` extension in `extensionsRequired` has matching loader configuration in the web viewer plan.",
2264
+ "measurement_method": "Verify `extensionsRequired` vs. `r3f-component-plan` / `glb-web-handoff` manifest.",
2265
+ "pass_threshold": "100% of required glTF extensions have configured web decoders."
2266
+ },
2267
+ {
2268
+ "id": "vc.color-space-and-tonemapping-parity",
2269
+ "criterion": "Web viewer configures environment lighting (PMREM) and tone mapping (`AgXToneMapping` or `ACESFilmicToneMapping`) to match Blender lookdev.",
2270
+ "measurement_method": "Check viewer configuration against `knowledge.threejs-r3f-tone-mapping-and-environment-parity`.",
2271
+ "pass_threshold": "Metallic PBR surfaces have an environment map and tone mapping is explicitly set."
2272
+ }
2273
+ ],
2274
+ "failure_modes": [
2275
+ {
2276
+ "symptom": "Metallic materials render completely black in Three.js despite looking bright in Blender Material Preview.",
2277
+ "root_cause": "Metallic conductors (metallic = 1.0) have zero diffuse reflection and require an environment map (`scene.environment` / R3F `<Environment />`) in Three.js.",
2278
+ "recovery_action": "Attach a PMREM environment HDRI or room environment in Three.js / React Three Fiber in addition to direct lights.",
2279
+ "fallback_skill_id": "glb-web-handoff"
2280
+ },
2281
+ {
2282
+ "symptom": "`GLTFLoader` throws an error on load when the GLB uses Draco, Meshopt, or KTX2 compression.",
2283
+ "root_cause": "The GLB declares compression in `extensionsRequired` without `DRACOLoader`, `MeshoptDecoder`, or `KTX2Loader` attached to `GLTFLoader`.",
2284
+ "recovery_action": "Configure the required decoder instance on `GLTFLoader` (or pass the decoder props in `@react-three/drei` `useGLTF`).",
2285
+ "fallback_skill_id": "r3f-component-plan"
2286
+ }
2287
+ ],
2288
+ "blender_versions": {
2289
+ "minimum": "3.6 LTS",
2290
+ "recommended": "4.5.15 LTS",
2291
+ "doc_checked_version": "5.2.3 LTS",
2292
+ "runtime_tested_version": null,
2293
+ "maintained_lts_versions": [
2294
+ "4.2 LTS",
2295
+ "4.5.15 LTS",
2296
+ "5.2.3 LTS"
2297
+ ],
2298
+ "legacy_compatibility_target": "3.6 LTS",
2299
+ "version_considerations": "Blender 4.2 LTS glTF exporter includes updated KHR_materials_ior, KHR_materials_specular, KHR_materials_coat, and KHR_materials_sheen export mappings from Principled BSDF v2. Reconciled with Blender 4.5.15 LTS and 5.2.3 LTS documentation baselines (live runtime: Not Run)."
2300
+ },
2301
+ "source_refs": [
2302
+ {
2303
+ "source_id": "source.khronos-gltf-2-spec",
2304
+ "locator": "GLB Binary File Format Specification"
2305
+ },
2306
+ {
2307
+ "source_id": "source.blender-manual-gltf-io",
2308
+ "locator": "glTF 2.0 Exporter Options & Extensions"
2309
+ },
2310
+ {
2311
+ "source_id": "source.threejs-color-and-gltf",
2312
+ "locator": "Color Management & GLTFLoader"
2313
+ }
2314
+ ],
2315
+ "evidence_status": "version-checked",
2316
+ "related_recipes": [
2317
+ "recipe.web-ready-asset-optimization",
2318
+ "recipe.product-hero-scene",
2319
+ "recipe.rigged-and-animated-asset"
2320
+ ]
2321
+ },
2322
+ {
2323
+ "id": "recipe.web-ready-asset-optimization",
2324
+ "title": "Mobile/Web GLB Performance Budgeting, Compression & LOD Pipeline",
2325
+ "domain": "optimization-lod-and-performance",
2326
+ "summary": "Structured optimization workflow for bringing heavy 3D scenes and assets within strict mobile/desktop web triangle, draw-call, VRAM, and download-size budgets using material/mesh consolidation, LODs, KTX2 textures, and Draco/Meshopt compression.",
2327
+ "aliases": [
2328
+ "mobile-glb-optimization",
2329
+ "web-3d-performance-budget-pipeline",
2330
+ "ktx2-draco-meshopt-lod-workflow"
2331
+ ],
2332
+ "intent": "Pin device-tier performance budgets upfront, audit geometry/texture/draw-call bottlenecks, design a progressive degradation and LOD plan, and select optimal texture (KTX2 ETC1S/UASTC) and mesh (Draco vs. Meshopt) compression.",
2333
+ "intent_signals": [
2334
+ "optimize a heavy 3D model or GLB for mobile web performance",
2335
+ "reduce GLB file size, draw calls, triangle count, and texture VRAM",
2336
+ "create LOD levels and compress textures with KTX2 and Meshopt or Draco",
2337
+ "set a performance budget for a Three.js or React Three Fiber web app"
2338
+ ],
2339
+ "applicable_scenarios": {
2340
+ "use_when": [
2341
+ "A 3D asset or scene targets mobile browsers, low-power laptops, or multi-asset web pages where download size, GPU memory (VRAM), and frame rate (60 FPS) are constrained.",
2342
+ "An existing asset exceeds triangle, texture dimension, or draw-call budgets."
2343
+ ],
2344
+ "do_not_use_when": [
2345
+ "The asset is exclusively used for offline Cycles still rendering where GPU real-time draw calls and browser download size do not apply."
2346
+ ]
2347
+ },
2348
+ "prerequisites": [
2349
+ "Target device tier (`mobile_low_end`, `mobile_mainstream`, `desktop_web`) identified.",
2350
+ "Inventory of current or planned meshes, materials, textures, and animations."
2351
+ ],
2352
+ "inputs": [
2353
+ {
2354
+ "name": "device_tier",
2355
+ "type": "string",
2356
+ "required": true,
2357
+ "default_value": "mobile_mainstream",
2358
+ "description": "Target device budget tier: mobile_low_end, mobile_mainstream, or desktop_web."
2359
+ },
2360
+ {
2361
+ "name": "max_file_size_mb",
2362
+ "type": "number",
2363
+ "required": false,
2364
+ "default_value": 5,
2365
+ "description": "Maximum compressed GLB payload size in megabytes."
2366
+ }
2367
+ ],
2368
+ "stages": [
2369
+ {
2370
+ "stage_number": 1,
2371
+ "id": "stage-pin-device-budget",
2372
+ "title": "Pin Device-Tier Triangle, Draw-Call, VRAM & Payload Budgets",
2373
+ "objective": "Lock hard numerical ceilings for triangles, draw calls, texture dimensions, VRAM, and compressed file size.",
2374
+ "skill_ids": [
2375
+ "mobile-glb-budget",
2376
+ "done-criteria"
2377
+ ],
2378
+ "knowledge_ids": [
2379
+ "knowledge.triangle-draw-call-and-vram-budgets"
2380
+ ],
2381
+ "actions": [
2382
+ "Pin explicit budgets by tier (e.g., Mobile Mainstream: <= 50,000 triangles, <= 25 draw calls, <= 1024-2048px max texture, <= 64 MB uncompressed GPU VRAM, <= 3-5 MB compressed GLB).",
2383
+ "Define the ordered degradation ladder if the source asset exceeds the pinned ceiling."
2384
+ ],
2385
+ "stage_outputs": [
2386
+ "pinned_device_budget_contract"
2387
+ ],
2388
+ "gate_check": "All 5 budget axes (triangles, draw calls, texture resolution, GPU VRAM, payload MB) have explicit numerical ceilings."
2389
+ },
2390
+ {
2391
+ "stage_number": 2,
2392
+ "id": "stage-geometry-and-lod-optimization",
2393
+ "title": "Topology Decimation, Draw-Call Consolidation & LOD Hierarchy",
2394
+ "objective": "Reduce worst-offender mesh triangle counts, merge static draw calls sharing materials, and define LOD0-LOD2 tiers.",
2395
+ "skill_ids": [
2396
+ "polycount-budget-checker",
2397
+ "asset-fallback-strategy"
2398
+ ],
2399
+ "knowledge_ids": [
2400
+ "knowledge.lod-hierarchy-and-decimation-strategy",
2401
+ "knowledge.procedural-instancing-and-realize-instances-budget"
2402
+ ],
2403
+ "actions": [
2404
+ "Identify top triangle offenders via polycount-budget-checker; remove hidden interior faces, reduce unseen cylinder/bevel segments, and bake fine geometric detail into normal maps.",
2405
+ "Plan discrete LOD levels (LOD0 100%, LOD1 50%, LOD2 25% triangles) preserving UV seams and silhouettes, and use instancing for repeated props."
2406
+ ],
2407
+ "stage_outputs": [
2408
+ "geometry_decimation_plan",
2409
+ "lod_hierarchy_spec"
2410
+ ],
2411
+ "gate_check": "LOD0 fits within active scene triangle budget and draw calls are minimized via material/mesh consolidation or instancing."
2412
+ },
2413
+ {
2414
+ "stage_number": 3,
2415
+ "id": "stage-texture-and-mesh-compression",
2416
+ "title": "ORM Channel Packing, KTX2 BasisU & Draco/Meshopt Selection",
2417
+ "objective": "Minimize both network download size and GPU VRAM footprint using channel packing and standard glTF compression extensions.",
2418
+ "skill_ids": [
2419
+ "material-quality-checker",
2420
+ "output-format-decision"
2421
+ ],
2422
+ "knowledge_ids": [
2423
+ "knowledge.normal-roughness-and-orm-channel-packing",
2424
+ "knowledge.texture-resolution-ktx2-and-draco-meshopt-compression",
2425
+ "knowledge.udim-vs-single-atlas-uv-packing"
2426
+ ],
2427
+ "actions": [
2428
+ "Pack Ambient Occlusion, Roughness, and Metallic into a single ORM texture (reducing 3 textures to 1) and downscale secondary maps to 512px or 1024px.",
2429
+ "Select KTX2 (`KHR_texture_basisu`: UASTC for normal/ORM maps, ETC1S for baseColor/emissive) to reduce GPU VRAM by 4x-8x (unlike PNG/WebP which decompress to full RGBA8 in VRAM), and choose Draco (smallest download) or Meshopt (fastest decode + morph/animation friendly)."
2430
+ ],
2431
+ "stage_outputs": [
2432
+ "compression_pipeline_spec",
2433
+ "vram_reduction_estimate"
2434
+ ],
2435
+ "gate_check": "Estimated GPU VRAM (accounting for 1.33x mipmap chain) and compressed payload size both pass the Stage 1 budget contract."
2436
+ },
2437
+ {
2438
+ "stage_number": 4,
2439
+ "id": "stage-optimization-verification-and-handoff",
2440
+ "title": "Budget Verification & Web Handoff Report",
2441
+ "objective": "Verify post-optimization metrics against the budget contract and document loader requirements.",
2442
+ "skill_ids": [
2443
+ "glb-web-handoff",
2444
+ "r3f-component-plan",
2445
+ "pre-handoff-verification",
2446
+ "plain-language-response"
2447
+ ],
2448
+ "knowledge_ids": [
2449
+ "knowledge.glb-binary-chunk-alignment-and-khronos-validation",
2450
+ "knowledge.threejs-r3f-tone-mapping-and-environment-parity"
2451
+ ],
2452
+ "actions": [
2453
+ "Verify that `KTX2Loader` (with Basis universal transcoder path) and `DRACOLoader` / `MeshoptDecoder` are documented in the web handoff contract.",
2454
+ "Report verified vs. estimated metrics honestly with accurate truth states."
2455
+ ],
2456
+ "stage_outputs": [
2457
+ "optimization_readiness_verdict",
2458
+ "web_optimization_handoff_report"
2459
+ ],
2460
+ "gate_check": "All budget ceilings are satisfied and truth states (`Not Run` / `Not Produced` vs. inspected `.glb`) are accurate."
2461
+ }
2462
+ ],
2463
+ "required_knowledge_ids": [
2464
+ "knowledge.triangle-draw-call-and-vram-budgets",
2465
+ "knowledge.lod-hierarchy-and-decimation-strategy",
2466
+ "knowledge.procedural-instancing-and-realize-instances-budget",
2467
+ "knowledge.normal-roughness-and-orm-channel-packing",
2468
+ "knowledge.texture-resolution-ktx2-and-draco-meshopt-compression",
2469
+ "knowledge.udim-vs-single-atlas-uv-packing",
2470
+ "knowledge.glb-binary-chunk-alignment-and-khronos-validation",
2471
+ "knowledge.threejs-r3f-tone-mapping-and-environment-parity"
2472
+ ],
2473
+ "required_skill_ids": [
2474
+ "mobile-glb-budget",
2475
+ "done-criteria",
2476
+ "polycount-budget-checker",
2477
+ "asset-fallback-strategy",
2478
+ "material-quality-checker",
2479
+ "output-format-decision",
2480
+ "glb-web-handoff",
2481
+ "r3f-component-plan",
2482
+ "pre-handoff-verification",
2483
+ "plain-language-response"
2484
+ ],
2485
+ "expected_outputs": {
2486
+ "intermediate": [
2487
+ "pinned_device_budget_contract",
2488
+ "geometry_decimation_plan",
2489
+ "compression_pipeline_spec"
2490
+ ],
2491
+ "final": [
2492
+ "optimization_readiness_verdict",
2493
+ "web_optimization_handoff_report"
2494
+ ],
2495
+ "truth_state_defaults": {
2496
+ "runtime_status": "Not Run",
2497
+ "artifact_status": "Not Produced"
2498
+ }
2499
+ },
2500
+ "validation_criteria": [
2501
+ {
2502
+ "id": "vc.vram-vs-download-distinction",
2503
+ "criterion": "Optimization plan distinguishes network download size (PNG/WebP/Draco) from uncompressed GPU VRAM usage (which requires resolution reduction or KTX2 block compression).",
2504
+ "measurement_method": "Check VRAM calculation in `knowledge.triangle-draw-call-and-vram-budgets` and `knowledge.texture-resolution-ktx2-and-draco-meshopt-compression`.",
2505
+ "pass_threshold": "VRAM calculation accounts for RGBA8 decompression of PNG/JPG/WebP + 1.33x mipmap factor."
2506
+ },
2507
+ {
2508
+ "id": "vc.uastc-for-normal-maps",
2509
+ "criterion": "When KTX2 compression is used on tangent-space normal maps, UASTC mode is specified instead of low-bitrate ETC1S to prevent blocky shading artifacts.",
2510
+ "measurement_method": "Inspect compression_pipeline_spec against `knowledge.texture-resolution-ktx2-and-draco-meshopt-compression`.",
2511
+ "pass_threshold": "Normal maps use UASTC (or uncompressed/high-precision) rather than lossy ETC1S."
2512
+ },
2513
+ {
2514
+ "id": "vc.preserved-uv-seams-on-lod",
2515
+ "criterion": "LOD decimation preserves UV seam boundaries and hard normal splits.",
2516
+ "measurement_method": "Verify Collapse/Planar decimation delimiter settings in `knowledge.lod-hierarchy-and-decimation-strategy`.",
2517
+ "pass_threshold": "Decimate modifier Delimit = UVs / Sharp enabled for LOD1-LOD2."
2518
+ }
2519
+ ],
2520
+ "failure_modes": [
2521
+ {
2522
+ "symptom": "Converting 4K PNG textures to 4K WebP shrank the `.glb` download from 25 MB to 3 MB, but iOS Safari still crashes due to memory exhaustion.",
2523
+ "root_cause": "PNG, JPEG, and WebP all decompress to uncompressed 32-bit RGBA8 in GPU VRAM (a single 4096x4096 texture consumes ~89 MB of VRAM with mipmaps regardless of WebP file size).",
2524
+ "recovery_action": "Downscale textures to 1024x1024 or 2048x2048 for mobile and/or transcode to KTX2 (`KHR_texture_basisu`), which stays block-compressed directly on the GPU.",
2525
+ "fallback_skill_id": "mobile-glb-budget"
2526
+ },
2527
+ {
2528
+ "symptom": "Normal maps show severe blocky staircase artifacts after KTX2 compression.",
2529
+ "root_cause": "Normal map was compressed with ETC1S (designed for color/diffuse maps) instead of UASTC.",
2530
+ "recovery_action": "Encode normal and ORM data maps with KTX2 UASTC + Zstandard supercompression, reserving ETC1S for baseColor/emissive maps.",
2531
+ "fallback_skill_id": "material-quality-checker"
2532
+ }
2533
+ ],
2534
+ "blender_versions": {
2535
+ "minimum": "3.6 LTS",
2536
+ "recommended": "4.5.15 LTS",
2537
+ "doc_checked_version": "5.2.3 LTS",
2538
+ "runtime_tested_version": null,
2539
+ "maintained_lts_versions": [
2540
+ "4.2 LTS",
2541
+ "4.5.15 LTS",
2542
+ "5.2.3 LTS"
2543
+ ],
2544
+ "legacy_compatibility_target": "3.6 LTS",
2545
+ "version_considerations": "Blender's built-in glTF exporter supports Draco (`KHR_draco_mesh_compression`) natively; KTX2 (`KHR_texture_basisu`) and Meshopt (`EXT_meshopt_compression`) are typically applied in the post-export glTF-Transform / gltfpack step. Reconciled with Blender 4.5.15 LTS and 5.2.3 LTS documentation baselines (live runtime: Not Run)."
2546
+ },
2547
+ "source_refs": [
2548
+ {
2549
+ "source_id": "source.khronos-ktx2-draco-meshopt",
2550
+ "locator": "KHR_texture_basisu, KHR_draco_mesh_compression & EXT_meshopt_compression"
2551
+ },
2552
+ {
2553
+ "source_id": "source.khronos-gltf-asset-auditor",
2554
+ "locator": "Real-Time 3D Commerce Performance Budgets"
2555
+ }
2556
+ ],
2557
+ "evidence_status": "version-checked",
2558
+ "related_recipes": [
2559
+ "recipe.blender-to-glb-handoff",
2560
+ "recipe.uv-and-pbr-material-preparation",
2561
+ "recipe.hard-surface-prop"
2562
+ ]
2563
+ }
2564
+ ]
2565
+ }