ENG2-P9-06: Compiled Rust examples in the engine crate (currently zero .rs examples)

[aram-devdocs]

Parent

• Program: ENG2 — GoudEngine v2 Rebuild (see the pinned master tracking issue)
• Phase / Milestone: Phase 9 — Authoring, Platforms, Examples & Polish (eng2-p9-authoring)
• Batch / Group: Batch 9.2 — Examples, docs, agent configs (4 groups, parallel), Group A
• Runbook spec: docs/src/runbook/phases/phase-9.md (committed with the roadmap)

Summary

Add compiled Rust examples under the engine crate — today there are zero .rs examples anywhere in the engine, so the v2 API has no first-party Rust-native usage sample.

Architecture Context

Layer: Layer 4/5 — examples live at the crate's examples/ convention (Cargo [[example]]), exercising the engine's own public Rust API/SDK surface. (see tools/lint_layers.rs — downward-only deps).
Modules/types touched:

• goud_engine/examples/ (new — standard Cargo examples directory; currently does not contain any .rs files).
• Rust SDK (sdks/rust/, ENG2-P1-08) — examples should exercise the real Rust SDK surface once it exists, not internal engine types directly, matching the thin-wrapper principle.

Boundary constraints (only those that apply):

• Examples MUST use the public SDK/engine API surface, never reach into internal modules across layers (.agents/rules/examples.md: "example games use the SDK API, never internal engine types" — the same rule applies to compiled Rust examples).

Pattern to follow: examples/rust/ conventions already documented in .agents/rules/examples.md; mirror the existing SDK-example structure used by other languages, adapted to Cargo's native examples/ mechanism.

Scope

• Add at least one compiled cargo run --example <name> Rust example demonstrating core v2 API usage (context creation, entity spawn, basic render loop).
• Ensure examples build and run in required CI (cargo build --examples / cargo run --example).
• Document how to run the new examples in the relevant AGENTS.md/.agents/rules/examples.md.
• Tests: spec test at goud_engine/tests/spec/ + unit/isolation coverage for the new code paths.
• Docs/rules updates if this invalidates .agents/rules/* or docs/src/*.

Acceptance Criteria

• At least one .rs example exists and builds/runs via cargo run --example in required CI (closing the current zero-.rs-examples gap).
• The example uses only the public v2 API surface, not internal engine types.
• cargo check && cargo fmt --all -- --check && cargo clippy -- -D warnings clean; cargo test green; ./codegen.sh && git diff --exit-code (drift gate)

Breaking Change & Throne Follow-up

None — additive.

Blocked By

None.

Files Likely Touched

• New/Modified/Generated: goud_engine/examples/*.rs (new), CI workflow update to build/run examples, .agents/rules/examples.md (documentation update)

Agent Notes

• Confirmed: the engine crate currently has zero .rs examples — this is a plain gap, not a broken/stale example set to fix. Verify this is still true at implementation time per the discovery-first rule before assuming the count.
• This issue blocks ENG2-P9-07 (the example-games refresh), since that issue's SDK-language example games should be able to point back at a working native Rust reference example for parity checks.

Verification

cargo check && cargo fmt --all -- --check && cargo clippy -- -D warnings
cargo test
./codegen.sh && git diff --exit-code
cargo build --examples