fix(examples): reserve exits 2/10/11 and make falsifiers reach behavioral checks

CONTRIBUTING.md

@@ -240,6 +240,17 @@ file-local and are not portable. `no-mesh` is `2` in
 `templates/ai-asset-pipeline-template/`; both are correct. Copy a template's
 own table from that template, not from this paragraph.
 
+**Reserved in examples/.** Three codes mean one thing in every example. `2`
+is argparse's usage exit only, never a check. `10` is the gallery framing
+gate (`gallery_framing.EXIT_FRAMING`) and `11` is the asset-quality gate
+(`gallery_asset_quality.EXIT_ASSET_QUALITY`). An example returns the
+helper's constant or check call for those, and gives its own checks other
+numbers. A shared code makes a falsifier impossible to target (catalog
+falsifiers may not expect 2) or misattributes which check fired.
+`tests/check_exit_code_readme.py` rejects a literal 2, 10 or 11 at an
+example's exit site, and an Exit codes row for them that says anything
+else or adds "also".
+
 **FATAL wrapper.** `sys.exit(1)` on an uncaught exception in the `__main__`
 guard. Uniform across the examples. `1` means crashed, never a named check.
 

docs/gallery/car-mirror-symmetry/index.html

@@ -80,7 +80,7 @@ <h2 id="run">Run<a class="anchor" href="#run" aria-label="Link to this section">
 blender --background --python car_mirror_symmetry.py -- --output car.png --engine cycles</code></pre>
 <h2 id="exit-codes">Exit codes<a class="anchor" href="#exit-codes" aria-label="Link to this section">#</a></h2>
 <p>Per-script sequential checks. <code>9</code> is a valid check code; there is no rule against it.</p>
-<div class="table-wrap"><table><thead><tr><th scope="col">Code</th><th scope="col">Meaning</th></tr></thead><tbody><tr><td>0</td><td>Success</td></tr><tr><td>1</td><td>Uncaught exception (FATAL wrapper)</td></tr><tr><td>2</td><td>argparse / usage</td></tr><tr><td>3</td><td>Body datablock is not the authored half</td></tr><tr><td>4</td><td>Authored centerline vert count ≠ 28</td></tr><tr><td>5</td><td>Evaluated verts ≠ <code>2n − c</code> (<code>--no-mirror</code> lands here)</td></tr><tr><td>6</td><td>Evaluated on-plane verts ≠ centerline; also <code>--output</code> produced no file</td></tr><tr><td>7</td><td>Evaluated Euler characteristic ≠ 2</td></tr><tr><td>8</td><td>Non-manifold edges in the evaluated shell</td></tr><tr><td>9</td><td>Evaluated verts lack a mirrored partner</td></tr><tr><td>10</td><td>Mirror partner deviation above tolerance</td></tr><tr><td>11</td><td>Evaluated bbox not symmetric about X</td></tr><tr><td>12</td><td>Mirrored-part origin off the plane</td></tr><tr><td>13</td><td>Mirrored-part datablock is not the authored half (verts, faces, on-plane verts)</td></tr><tr><td>14</td><td>Mirrored-part evaluated counts ≠ <code>2n − weld</code> / <code>2f</code>, or on-plane verts ≠ weld</td></tr><tr><td>15</td><td>Mirrored-part partner check failed</td></tr><tr><td>16</td><td>Mirrored-part evaluated mesh stayed on one side</td></tr><tr><td>17</td><td>Gallery framing violation (<code>--output</code> path only; <code>gallery_framing</code> returns 10, remapped)</td></tr><tr><td>18</td><td>Asset-quality floor violation (<code>--output</code> path only; <code>gallery_asset_quality</code> returns 11, remapped)</td></tr></tbody></table></div>
+<div class="table-wrap"><table><thead><tr><th scope="col">Code</th><th scope="col">Meaning</th></tr></thead><tbody><tr><td>0</td><td>Success</td></tr><tr><td>1</td><td>Uncaught exception (FATAL wrapper)</td></tr><tr><td>2</td><td>argparse / usage</td></tr><tr><td>3</td><td>Body datablock is not the authored half</td></tr><tr><td>4</td><td>Authored centerline vert count ≠ 28</td></tr><tr><td>5</td><td>Evaluated verts ≠ <code>2n − c</code> (<code>--no-mirror</code> lands here)</td></tr><tr><td>6</td><td>Evaluated on-plane verts ≠ centerline; also <code>--output</code> produced no file</td></tr><tr><td>7</td><td>Evaluated Euler characteristic ≠ 2</td></tr><tr><td>8</td><td>Non-manifold edges in the evaluated shell</td></tr><tr><td>9</td><td>Evaluated verts lack a mirrored partner</td></tr><tr><td>10</td><td>Gallery framing violation (<code>--output</code> path only; <code>gallery_framing</code>)</td></tr><tr><td>11</td><td>Asset-quality floor violation (<code>--output</code> path only; <code>gallery_asset_quality</code>)</td></tr><tr><td>12</td><td>Mirrored-part origin off the plane</td></tr><tr><td>13</td><td>Mirrored-part datablock is not the authored half (verts, faces, on-plane verts)</td></tr><tr><td>14</td><td>Mirrored-part evaluated counts ≠ <code>2n − weld</code> / <code>2f</code>, or on-plane verts ≠ weld</td></tr><tr><td>15</td><td>Mirrored-part partner check failed</td></tr><tr><td>16</td><td>Mirrored-part evaluated mesh stayed on one side</td></tr><tr><td>17</td><td>Mirror partner deviation above tolerance</td></tr><tr><td>18</td><td>Evaluated bbox not symmetric about X</td></tr></tbody></table></div>
 <p>The <code>blender-smoke</code> workflow runs the check on Blender 5.2 LTS and 4.5 LTS (5.1 on the weekly cron, the <code>needs-5.1</code> PR label, or manual dispatch). Smoke does not pass <code>--output</code>. Its catalog falsifier is <code>--no-mirror</code> (expects exit 5).</p>
     </section>
     <section class="detail-section src" id="source">

docs/gallery/color-attribute-wheel/index.html

@@ -77,8 +77,8 @@ <h2 id="run">Run<a class="anchor" href="#run" aria-label="Link to this section">
 blender --background --python color_attribute_wheel.py -- --output wheel.png --engine cycles</code></pre>
 <h2 id="exit-codes">Exit codes<a class="anchor" href="#exit-codes" aria-label="Link to this section">#</a></h2>
 <p>Per-script sequential checks. <code>9</code> is a valid check code; there is no rule against it.</p>
-<div class="table-wrap"><table><thead><tr><th scope="col">Code</th><th scope="col">Meaning</th></tr></thead><tbody><tr><td>0</td><td>Success</td></tr><tr><td>1</td><td>Uncaught exception (FATAL wrapper)</td></tr><tr><td>2</td><td>argparse / usage</td></tr><tr><td>3</td><td>Topology ≠ closed form</td></tr><tr><td>4</td><td>Color attribute missing</td></tr><tr><td>5</td><td>Domain/type ≠ CORNER/FLOAT_COLOR (<code>--point-domain</code> lands here)</td></tr><tr><td>6</td><td>Attribute sized to verts, not loops</td></tr><tr><td>7</td><td><code>active_color</code> not set</td></tr><tr><td>8</td><td>Probe loop color off HSV closed form</td></tr><tr><td>9</td><td><code>--output</code> produced no file</td></tr><tr><td>10</td><td>Framing gate violation on the <code>--output</code> path (<code>gallery_framing</code>)</td></tr></tbody></table></div>
-<p>The <code>blender-smoke</code> workflow runs the check on Blender 5.2 LTS and 4.5 LTS (5.1 on the weekly cron, the <code>needs-5.1</code> PR label, or manual dispatch). Smoke does not pass <code>--output</code>. Its catalog falsifier is <code>--point-domain</code> (expects exit 5).</p>
+<div class="table-wrap"><table><thead><tr><th scope="col">Code</th><th scope="col">Meaning</th></tr></thead><tbody><tr><td>0</td><td>Success</td></tr><tr><td>1</td><td>Uncaught exception (FATAL wrapper)</td></tr><tr><td>2</td><td>argparse / usage</td></tr><tr><td>3</td><td>Topology ≠ closed form</td></tr><tr><td>4</td><td>Color attribute missing</td></tr><tr><td>5</td><td>Domain/type ≠ CORNER/FLOAT_COLOR (diagnostic, checked last)</td></tr><tr><td>6</td><td>Attribute sized to verts, not loops (<code>--point-domain</code> lands here)</td></tr><tr><td>7</td><td><code>active_color</code> not set</td></tr><tr><td>8</td><td>Probe loop color off HSV closed form</td></tr><tr><td>9</td><td><code>--output</code> produced no file</td></tr><tr><td>10</td><td>Framing gate violation on the <code>--output</code> path (<code>gallery_framing</code>)</td></tr></tbody></table></div>
+<p>The <code>blender-smoke</code> workflow runs the check on Blender 5.2 LTS and 4.5 LTS (5.1 on the weekly cron, the <code>needs-5.1</code> PR label, or manual dispatch). Smoke does not pass <code>--output</code>. Its catalog falsifier is <code>--point-domain</code> (expects exit 6).</p>
     </section>
     <section class="detail-section src" id="source">
       <h2>Source</h2>

docs/gallery/compositor-glare/index.html

@@ -68,16 +68,16 @@ <h2 id="run">Run<a class="anchor" href="#run" aria-label="Link to this section">
 <pre tabindex="0"><code># Cheap correctness check (two tiny renders) — the CI check:
 blender --background --python compositor_glare.py --
 
-# Falsifier: Threshold=10.0. Must exit non-zero (Threshold==1.0).
+# Falsifier: Threshold=1000.0, above the brightest ring (18). Must exit non-zero (no halo pixels, exit 4).
 blender --background --python compositor_glare.py -- --threshold-high
 
 # Also render a still (EEVEE on a GPU host; use --engine cycles on GPU-less hosts):
 blender --background --python compositor_glare.py -- --output rings.png
 blender --background --python compositor_glare.py -- --output rings.png --engine cycles</code></pre>
 <h2 id="exit-codes">Exit codes<a class="anchor" href="#exit-codes" aria-label="Link to this section">#</a></h2>
 <p>Per-script sequential checks. <code>9</code> is a valid check code; there is no rule against it.</p>
-<div class="table-wrap"><table><thead><tr><th scope="col">Code</th><th scope="col">Meaning</th></tr></thead><tbody><tr><td>0</td><td>Success</td></tr><tr><td>1</td><td>Uncaught exception (FATAL wrapper)</td></tr><tr><td>2</td><td>argparse / usage</td></tr><tr><td>3</td><td>Compositor tree / Glare / Threshold / link-chain contract (<code>--threshold-high</code> lands here)</td></tr><tr><td>4</td><td>Check render missing, tube dark, no halo, or halo does not fall off</td></tr><tr><td>5</td><td>Halo present with compositing off</td></tr><tr><td>6</td><td><code>--output</code> produced no file</td></tr><tr><td>10</td><td>Gallery framing violation (render path; checked before the beauty render)</td></tr></tbody></table></div>
-<p>The <code>blender-smoke</code> workflow runs the check on Blender 5.2 LTS and 4.5 LTS (5.1 on the weekly cron, the <code>needs-5.1</code> PR label, or manual dispatch). Smoke does not pass <code>--output</code>. Its catalog falsifier is <code>--threshold-high</code> (expects exit 3).</p>
+<div class="table-wrap"><table><thead><tr><th scope="col">Code</th><th scope="col">Meaning</th></tr></thead><tbody><tr><td>0</td><td>Success</td></tr><tr><td>1</td><td>Uncaught exception (FATAL wrapper)</td></tr><tr><td>2</td><td>argparse / usage</td></tr><tr><td>3</td><td>Compositor tree / Glare / link-chain contract</td></tr><tr><td>4</td><td>Check render missing, tube dark, no halo, or halo does not fall off (<code>--threshold-high</code> lands here)</td></tr><tr><td>5</td><td>Halo present with compositing off</td></tr><tr><td>6</td><td><code>--output</code> produced no file</td></tr><tr><td>10</td><td>Gallery framing violation (render path; checked before the beauty render)</td></tr></tbody></table></div>
+<p>The <code>blender-smoke</code> workflow runs the check on Blender 5.2 LTS and 4.5 LTS (5.1 on the weekly cron, the <code>needs-5.1</code> PR label, or manual dispatch). Smoke does not pass <code>--output</code>. Its catalog falsifier is <code>--threshold-high</code> (expects exit 4).</p>
     </section>
     <section class="detail-section src" id="source">
       <h2>Source</h2>

docs/gallery/cross-version-property-delete/index.html

@@ -78,7 +78,7 @@ <h2 id="run">Run<a class="anchor" href="#run" aria-label="Link to this section">
 <p>The <code>--output</code> render path measures framing against the Layer 1 band via <code>examples/gallery_framing.py</code> (exit 10 on violation) before writing the still.</p>
 <h2 id="exit-codes">Exit codes<a class="anchor" href="#exit-codes" aria-label="Link to this section">#</a></h2>
 <p>Per-script sequential checks. <code>9</code> is a valid check code; there is no rule against it. <code>10</code> is the shared framing helper.</p>
-<div class="table-wrap"><table><thead><tr><th scope="col">Code</th><th scope="col">Meaning</th></tr></thead><tbody><tr><td>0</td><td>Success</td></tr><tr><td>1</td><td>Uncaught exception (FATAL wrapper)</td></tr><tr><td>2</td><td>argparse / usage; also an active object existed after the data-API build</td></tr><tr><td>3</td><td>Custom ID property did not land</td></tr><tr><td>4</td><td><code>property_unset</code> on a custom ID key did not TypeError, or it deleted the key</td></tr><tr><td>5</td><td><code>del</code> did not report removal</td></tr><tr><td>6</td><td>Keep lamp lost the ID property</td></tr><tr><td>7</td><td>Clear lamp still has the ID property (<code>--skip-delete</code> / <code>--unset-instead</code> land here)</td></tr><tr><td>8</td><td>Registered-prop contract broke: attribute/<code>property_unset</code> failed, the prop sits on the wrong side of the 5.0 ID-property split, or <code>scene[&quot;name&quot;]</code> raised <code>KeyError</code> (<code>--subscript-registered</code> on 5.0+; exits 0 on 4.5, where subscript access still works)</td></tr><tr><td>10</td><td>Gallery framing violation</td></tr><tr><td>12</td><td><code>--output</code> produced no file</td></tr></tbody></table></div>
+<div class="table-wrap"><table><thead><tr><th scope="col">Code</th><th scope="col">Meaning</th></tr></thead><tbody><tr><td>0</td><td>Success</td></tr><tr><td>1</td><td>Uncaught exception (FATAL wrapper)</td></tr><tr><td>2</td><td>argparse / usage</td></tr><tr><td>3</td><td>Custom ID property did not land</td></tr><tr><td>4</td><td><code>property_unset</code> on a custom ID key did not TypeError, or it deleted the key</td></tr><tr><td>5</td><td><code>del</code> did not report removal</td></tr><tr><td>6</td><td>Keep lamp lost the ID property</td></tr><tr><td>7</td><td>Clear lamp still has the ID property (<code>--skip-delete</code> / <code>--unset-instead</code> land here)</td></tr><tr><td>8</td><td>Registered-prop contract broke: attribute/<code>property_unset</code> failed, the prop sits on the wrong side of the 5.0 ID-property split, or <code>scene[&quot;name&quot;]</code> raised <code>KeyError</code> (<code>--subscript-registered</code> on 5.0+; exits 0 on 4.5, where subscript access still works)</td></tr><tr><td>9</td><td>An active object existed after the data-API build (checked first)</td></tr><tr><td>10</td><td>Gallery framing violation</td></tr><tr><td>12</td><td><code>--output</code> produced no file</td></tr></tbody></table></div>
 <p>The <code>blender-smoke</code> workflow runs the check on Blender 5.2 LTS and 4.5 LTS (5.1 on the weekly cron, the <code>needs-5.1</code> PR label, or manual dispatch). Smoke does not pass <code>--output</code>. Its catalog falsifiers are <code>--skip-delete</code> (expects exit 7); <code>--unset-instead</code> (expects exit 7); <code>--subscript-registered</code> (expects exit 8; 5.0+ only; SKIP on older Blender).</p>
     </section>
     <section class="detail-section src" id="source">