docs: write down exit-code roles and the smoke coverage model (#139)

The missing convention was the defect behind #136, not exit 9. Records
per-script 0/2/3+, FATAL 1, smoke 0/1/77, and that blender-smoke has no
push trigger on purpose.

Signed-off-by: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: TMHSDigital

AGENTS.md

@@ -160,7 +160,9 @@ way, and a one-paragraph rationale. 30 to 80 lines is the right size.
   5.2 LTS and 4.5 LTS for every PR. 5.1 is weekly cron, the opt-in
   `needs-5.1` PR label (`pull_request` types include `labeled`), or
   `workflow_dispatch` with a `series` input. Auto-label does not apply
-  `needs-5.1`. Contributor-facing notes live in CONTRIBUTING.md. Examples run
+  `needs-5.1`. Contributor-facing notes for the smoke lever, the deliberate
+  lack of a `push` trigger, Pages path filters, and the three-role exit-code
+  convention live in CONTRIBUTING.md. Examples run
   through `tests/smoke/run_example.py` (catalog: `tests/smoke/catalog.json`).
   SKIP is exit 77 plus a `SMOKE_SKIP:` reason, and only when `--min-version`
   is above this Blender; exit 0 with that marker is a vacuous pass and fails.

CONTRIBUTING.md

@@ -111,6 +111,37 @@ Default PR smoke is Blender 5.2 and 4.5 (`.github/workflows/blender-smoke.yml`).
   pick the branch and the `series` input.
 - Monday 07:00 UTC cron still runs 5.2, 5.1, and 4.5. Do not treat cron as
   PR evidence.
+- **There is deliberately no `push` trigger on `blender-smoke.yml`.**
+  Squash-merging a green PR makes `main` identical to the content already
+  smoke-tested, so a push job would re-prove the same tree at double the
+  CI cost. Absence of post-merge smoke is not a coverage gap.
+- **`pages.yml` is path-filtered.** A workflow-or-docs-only merge does not
+  deploy Pages. Observed on `13ea521` (`ci:` #137): Validate, drift-check,
+  and Release ran; Pages did not. Intentional, not a failed job.
+
+## Exit codes
+
+Three roles, not one global table. Do not copy a code from one script into
+another and assume it means the same thing. `9` is a valid sequential-check
+code; there is no rule against it.
+
+**Per-script exits** (examples and headless templates). `0` success. `2`
+argument or usage error, matching argparse. `3` and above for that script's
+own sequential check failures, in the order the checks run. These codes are
+file-local and are not portable. `no-mesh` is `2` in
+`templates/headless-batch-script-template/` and `5` in
+`templates/ai-asset-pipeline-template/`; both are correct. Copy a template's
+own table from that template, not from this paragraph.
+
+**FATAL wrapper.** `sys.exit(1)` on an uncaught exception in the `__main__`
+guard. Uniform across the examples. `1` means crashed, never a named check.
+
+**Smoke protocol.** Owned by `tests/` and the runner, not by product check
+tables. `0` pass, `1` fail (`tests/smoke/run_example.py`,
+`tests/check_import_export_rules.py`), `77` skip (`tests/smoke/canary_skip.py`,
+and the product scripts that self-skip: `examples/gn-bundle-roundtrip/`,
+`examples/exit-pre-sidecar/`). A script under test prints `SMOKE_SKIP:` and
+exits 77; the runner records SKIP and returns 0 so the YAML step stays green.
 
 ## Standards-version Markers