From cef80739c6b37a1fa01f522a35d47af36cfe91f2 Mon Sep 17 00:00:00 2001 From: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com> Date: Sun, 4 Oct 2026 21:53:33 -0400 Subject: [PATCH] docs(showcase): say what the showcase proves, not only what it is not The README listed "76 showcase pieces" next to skills and rules and described them only as "budget-conformance props ... not examples", so a first-time visitor could read the repo as an asset pack. The README overview, the examples section and showcase/README.md now say why the showcase exists: each piece is one headless script that runs the pipeline the skills teach (cleanup, bake, LODs, collider, engine export) end to end and asserts measured budgets on every LTS, so it is evidence that the skills compose. The landing page already framed it this way. Closes #383 Signed-off-by: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com> Co-Authored-By: Claude Opus 5.5 --- README.md | 4 ++-- showcase/README.md | 8 ++++++++ 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 9a296cd7..4f9731da 100644 --- a/README.md +++ b/README.md @@ -52,7 +52,7 @@ The content is consumed by AI coding agents reading these files directly from a | **Templates** | A working Extensions Platform add-on starter, a headless batch script starter, and a GLB-in engine-ready asset pipeline | | **Snippets** | 27 small standalone Python files demonstrating canonical patterns | | **Examples** | Runnable headless scripts under [`examples/`](examples/). Each asserts an API contract and exits non-zero on failure. | -| **Showcase** | Budget-conformance props under [`showcase/`](showcase/). Not examples. Conventions: [`showcase/README.md`](showcase/README.md) | +| **Showcase** | Proof that the skills compose: each piece under [`showcase/`](showcase/) is one headless Python script that builds a game prop and runs the whole asset pipeline (cleanup, high-to-low bake, LODs, convex collider, engine export), asserting measured budgets on every LTS. Not API examples. Conventions: [`showcase/README.md`](showcase/README.md) | ## Quick start @@ -130,7 +130,7 @@ per-script exit-code model, are in ## Examples and showcase -**64 examples** in [`examples/`](examples/) are runnable, self-checking scripts: each asserts one API contract, carries a falsifier, and runs headless on Blender 5.2 LTS and 4.5 LTS in the `blender-smoke` workflow (5.1 on the weekly cron or by manual dispatch). Those whose contract is visible also render a still. **76 showcase pieces** in [`showcase/`](showcase/) are game props held to measured budgets (triangle counts, colliders, materials, real-world size); they are not examples. Conventions: [`showcase/README.md`](showcase/README.md). +**64 examples** in [`examples/`](examples/) are runnable, self-checking scripts: each asserts one API contract, carries a falsifier, and runs headless on Blender 5.2 LTS and 4.5 LTS in the `blender-smoke` workflow (5.1 on the weekly cron or by manual dispatch). Those whose contract is visible also render a still. **76 showcase pieces** in [`showcase/`](showcase/) exist to show the skills working together at production scale: each is a single headless script that models a game prop, then runs it through the same cleanup, bake, LOD, collider and export steps the skills teach, and fails if a measured budget (triangle counts, colliders, materials, real-world size) is missed. They are not API examples. Conventions: [`showcase/README.md`](showcase/README.md). Browse both, with filters, full-size renders and each script's README, in the **[gallery](https://tmhsdigital.github.io/Blender-Developer-Tools/gallery/)**. diff --git a/showcase/README.md b/showcase/README.md index 1e1e5cf3..e997abc4 100644 --- a/showcase/README.md +++ b/showcase/README.md @@ -2,6 +2,14 @@ Budget-conformance props. **Not examples.** +**Why it is here:** examples prove one API contract each; the showcase proves +the contracts compose. Every piece is one headless Python script that models +a game prop and runs it through the pipeline the skills teach +(`ai-mesh-cleanup`, `bake-high-to-low`, LOD decimation, a convex collider, +`engine-export-presets`), then asserts measured budgets on 4.5 LTS, 5.1 and +5.2 LTS. Advice that breaks under real use tends to surface here first +(the non-manifold collider in #386 did). + An example witnesses one API contract and carries a falsifier that makes a real assertion fail. A recognizable crate witnesses no API contract. Forcing one into `examples/` produces a vacuous check. Showcase pieces