docs(examples): apply EXAMPLE_STANDARD to board and puzzle examples

[emteebug12-jpg]

Summary

Brings the eight board/puzzle examples up to the EXAMPLE_STANDARD.md quality bar:

• chess, checkers, connect_four, minesweeper, memory_match, tic_tac_toe: split monolithic lib.rs into lib.rs (entrypoints + storage) / components.rs (component types) / systems.rs (pure game logic). chess additionally gets zk.rs for the Groth16 circuit code (relocated unchanged — ZK logic itself is out of scope per the issue).
• reversi, sudoku: already had components.rs/systems.rs; only README/dependency work was needed.
• All eight: README.md rewritten to cover the eight required EXAMPLE_STANDARD.md §4 sections, cougr-core pinned to the published 1.1.0, classified transitional with a banner pointing to snake (none are on the canonical list), and Cargo.lock committed per the repo hygiene rule for example apps.
• tic_tac_toe had a broken cougr-core = { path = "../../" } dependency — fixed to the published crate, which is a real functional fix (the example couldn't previously build outside the monorepo).

No game rule, validation, or ZK-verification logic was changed anywhere — every module split was verified to produce the exact same test count/names/results before and after.

Verification note: stellar-cli could not be installed in this sandbox (libdbus-1-dev system header missing, no sudo access), so the literal stellar contract build command was not run locally for any example. As a proxy, every example was verified with cargo test (all passing) and cargo build --target wasm32v1-none --release (the target stellar contract build itself compiles against). chess and tic_tac_toe already have GitHub Actions workflows that install stellar-cli and run the real build on this PR; the other six don't have CI wired up (out of scope for this issue — not one of the five listed per-example tasks) but should build identically. Flagging this so a maintainer can confirm the real command before merge.

Closes #223

Quality checklists

chess

• Uses published cougr-core version (1.1.0), not a path dependency
• cargo test passes (17/17)
• stellar contract build passes — not run locally, see verification note above; wasm32v1-none release build succeeds
• lib.rs contains only contract entrypoints and storage wiring
• components.rs exists and contains all component types (BoardState, TurnState, ProofRecord, GameState, MoveResult, etc.)
• systems.rs exists and contains game logic systems (init_board, apply_move, check_endgame, compute_state_hash)
• Additional modules added only if used — zk.rs added for CustomCircuit/Groth16Proof/VerificationKey (unchanged logic)
• Purpose and pattern / Public contract API / Architecture overview / Storage model / Main gameplay flow / Cougr APIs used / Build and test commands / Known limitations all present
• No hardcoded testnet contract IDs or deployment results
• Initialization, happy-path, invalid-action, rule/invariant tests present; ZK proof-record flow exercised
• Tests use soroban-sdk testutils and Env::default()
• target/ excluded, no committed .wasm, Cargo.lock committed, no wildcard versions
• Marked transitional with banner pointing to snake

checkers

• Uses published cougr-core version (1.1.0), not a path dependency
• cargo test passes (24/24)
• stellar contract build passes — not run locally, see verification note above; wasm32v1-none release build succeeds
• lib.rs contains only contract entrypoints and storage wiring
• components.rs exists (BoardComponent, TurnComponent, GameStatusComponent, ChainCapture, SmallVec4, error/state types)
• systems.rs exists and contains game logic systems (move/capture legality, promotion, win detection)
• Additional modules added only if used — none needed
• Purpose and pattern / Public contract API / Architecture overview / Storage model / Main gameplay flow / Cougr APIs used / Build and test commands / Known limitations all present
• No hardcoded testnet contract IDs or deployment results
• Initialization, happy-path, invalid-action, rule/invariant tests present
• [~] Cougr integration test — N/A, this example doesn't call into any cougr-core API (see caveat below)
• Tests use soroban-sdk testutils and Env::default()
• target/ excluded, no committed .wasm, Cargo.lock committed
• No unused dependencies — caveat: cougr-core is declared in Cargo.toml but never imported in source (confirmed via grep); kept per the issue's explicit "ensure cougr-core = 1.1.0" requirement rather than removed, but this is a genuine unused-dependency gap worth a maintainer call
• Marked transitional with banner pointing to snake

connect_four

• Uses published cougr-core version (1.1.0), not a path dependency
• cargo test passes (24/24)
• stellar contract build passes — not run locally, see verification note above; wasm32v1-none release build succeeds
• lib.rs contains only contract entrypoints and storage wiring
• components.rs exists (BoardComponent, PlayerComponent, GameStateComponent, ECSWorldState, public view types)
• systems.rs exists and contains game logic systems (validation, gravity, win detection, draw, turn)
• Additional modules added only if used — none needed
• Purpose and pattern / Public contract API / Architecture overview / Storage model / Main gameplay flow / Cougr APIs used / Build and test commands / Known limitations all present
• No hardcoded testnet contract IDs or deployment results
• Initialization, happy-path, invalid-action, rule/invariant tests present
• Tests use soroban-sdk testutils and Env::default()
• target/ excluded, no committed .wasm, Cargo.lock committed, no wildcard versions
• Marked transitional with banner pointing to snake

reversi

• Uses published cougr-core version (1.1.0), not a path dependency
• cargo test passes (14/14)
• stellar contract build passes — not run locally, see verification note above; wasm32v1-none release build succeeds
• lib.rs/components.rs/systems.rs already split (no change needed beyond README/deps)
• Purpose and pattern / Public contract API / Architecture overview / Storage model / Main gameplay flow / Cougr APIs used / Build and test commands / Known limitations all present
• No hardcoded testnet contract IDs or deployment results (the existing MATCH_LOG.md with a testnet contract ID/addresses was left as-is — it's a separate notes file, not the README, which the standard explicitly allows)
• Initialization, happy-path, invalid-action, rule/invariant tests present
• Tests use soroban-sdk testutils and Env::default()
• target/ excluded, no committed .wasm, Cargo.lock committed, no wildcard versions
• Marked transitional with banner pointing to snake

sudoku

• Uses published cougr-core version (1.1.0), not a path dependency
• cargo test passes (15/15)
• stellar contract build passes — not run locally, see verification note above; wasm32v1-none release build succeeds
• lib.rs/components.rs/systems.rs already split (no change needed beyond README/deps)
• Purpose and pattern / Public contract API / Architecture overview / Storage model / Main gameplay flow / Cougr APIs used / Build and test commands / Known limitations all present
• No hardcoded testnet contract IDs or deployment results (existing MATCH_LOG.md left as-is, same rationale as reversi)
• Initialization, happy-path, invalid-action, rule/invariant tests present
• Tests use soroban-sdk testutils and Env::default()
• target/ excluded, no committed .wasm, Cargo.lock committed, no wildcard versions
• Marked transitional with banner pointing to snake

minesweeper

• Uses published cougr-core version (1.1.0), not a path dependency
• cargo test passes (21/21)
• stellar contract build passes — not run locally, see verification note above; wasm32v1-none release build succeeds
• lib.rs contains only contract entrypoints and storage wiring
• components.rs exists (BoardComponent, MineLayoutComponent, GameStateComponent, ECSWorldState, public view types)
• systems.rs exists and contains game logic systems (place_mines_deterministic, completion_system)
• Additional modules added only if used — none needed
• Purpose and pattern / Public contract API / Architecture overview / Storage model / Main gameplay flow / Cougr APIs used / Build and test commands / Known limitations all present
• No hardcoded testnet contract IDs or deployment results
• Initialization, happy-path, invalid-action, rule/invariant tests present
• Tests use soroban-sdk testutils and Env::default()
• target/ excluded, no committed .wasm, Cargo.lock committed, no wildcard versions
• Marked transitional with banner pointing to snake

memory_match

• Uses published cougr-core version (1.1.0), not a path dependency
• cargo test passes (11/11)
• stellar contract build passes — not run locally, see verification note above; wasm32v1-none release build succeeds
• lib.rs contains only contract entrypoints and storage wiring
• components.rs exists (CardComponent, BoardComponent, GameStateComponent, ECSWorldState, public view types)
• systems.rs exists and contains game logic systems (reveal/pair validation and resolution, reset)
• Additional modules added only if used — none needed
• Purpose and pattern / Public contract API / Architecture overview / Storage model / Main gameplay flow / Cougr APIs used / Build and test commands / Known limitations all present
• No hardcoded testnet contract IDs or deployment results
• Initialization, happy-path, invalid-action, rule/invariant tests present
• Tests use soroban-sdk testutils and Env::default()
• target/ excluded, no committed .wasm, Cargo.lock committed, no wildcard versions
• Marked transitional with banner pointing to snake

tic_tac_toe

• Uses published cougr-core version (1.1.0) — fixed from a broken { path = "../../" } dependency, not a cosmetic change
• cargo test passes (33/33)
• stellar contract build passes — not run locally, see verification note above; wasm32v1-none release build succeeds; existing CI workflow runs the real command
• lib.rs contains only contract entrypoints, impl_soroban_game!, and storage wiring
• components.rs exists (Board, Players, TurnState via impl_rich_component!/impl_component!)
• systems.rs exists and contains game logic systems (win-line/draw detection)
• Additional modules added only if used — none needed
• Purpose and pattern / Public contract API / Architecture overview / Storage model / Main gameplay flow / Cougr APIs used / Build and test commands / Known limitations all present
• No hardcoded testnet contract IDs or deployment results
• Initialization, happy-path, invalid-action, rule/invariant tests present
• Tests use soroban-sdk testutils and Env::default()
• target/ excluded, no committed .wasm, Cargo.lock committed (also removed this example's own .gitignore line that was excluding it)
• Marked transitional with banner pointing to snake, with a note that it already uses cougr-core's newest macro-based pattern

[drips-wave]

@emteebug12-jpg Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[salazarsebas]

Review — approve with minor follow-ups

Strong work overall. This is the most complete PR in the queue and all seven triggered CI workflows pass.

Strengths

• Full scope for all eight board/puzzle examples: cougr-core = "1.1.0", module split (components.rs / systems.rs), and READMEs aligned with EXAMPLE_STANDARD.md §4.
• Documentation quality is notably high (e.g. chess structured sections and transitional banner).
• Substantive refactor, not cosmetic README edits.

Requested changes before merge

1. chess is not covered by CI. This PR modifies examples/chess/** but no workflow ran for it. Please run locally and confirm:

   cd examples/chess && cargo fmt --check && cargo clippy --all-targets -- -D warnings && cargo test && stellar contract build

   Consider adding .github/workflows/chess.yml in a follow-up (or this PR if time permits).

2. Transitional banner target. chess points readers to snake, but this is a ZK proof example. Point to hidden_hand (ZK circuits) or remove the transitional classification if the example remains a maintained ZK reference.

3. PR description. Please add the completed EXAMPLE_STANDARD quality checklist per example in the PR body to speed final review of this large diff.

Verdict

Approve after confirming chess builds locally and adjusting the transitional banner reference.

[emteebug12-jpg]

Thanks for the thorough review! Addressed all three points in 6b31e34:

1. chess wasn't covered by CI — found the root cause: examples/chess/.github/workflows/chess.yml was nested under the example directory, but GitHub Actions only discovers workflows in the repo-root .github/workflows/, so that file never ran on any PR, including this one. Moved it to .github/workflows/chess.yml using the same example_reusable.yml pattern as the other seven examples (and deleted the dead nested copy). It's now queued on this PR — action_required since it's a first-time-contributor fork PR, just needs your approval on the Actions tab to actually run.

Ran the requested commands locally before pushing:

cd examples/chess && cargo fmt --check && cargo clippy --all-targets --all-features -- -D warnings && cargo test

cargo clippy -D warnings caught a real pre-existing lint (clippy::bool_assert_comparison on assert_eq!(x, false) in test.rs) that would have failed CI once it actually ran — fixed to assert!(!x). cargo test still 17/17. I still don't have Stellar CLI in this sandbox (no sudo for libdbus-1-dev), so stellar contract build itself will need the CI run (now wired up) or your own machine to confirm — cargo build --target wasm32v1-none --release (the target stellar contract build compiles against) succeeds.

2. Transitional banner target — chess is a maintained ZK reference but its zk::decode_proof is an intentional unimplemented stub and ComponentTrait::deserialize for BoardState/TurnState always returns None, so I don't think it clears the bar for dropping the transitional label. Re-pointed the banner from snake (no ZK content at all) to hidden_hand, which uses cougr_core::circuits' pre-built builders instead of a hand-rolled CustomCircuit — the actually-relevant "current recommended approach" for ZK-backed games. Added a sentence under "Cougr APIs used" explaining the relationship to hidden_hand/fog_explorer/dice_duel/blind_auction.

3. PR description checklist — the per-example EXAMPLE_STANDARD.md quality checklist for all eight examples has been in the PR body since I opened it (see the "Quality checklists" section below the summary) — let me know if it wasn't rendering for you or if you were after a different format/placement.

One more thing I noticed while fixing chess's CI: examples/tic_tac_toe/.github/workflows/ci.yml has the same nested-workflow problem (it never runs; tic_tac_toe is only actually covered by the root-level .github/workflows/tic_tac_toe.yml). Left it alone since it's not part of this issue's explicit scope, but flagging it as a likely follow-up cleanup target.