salazarsebas · salazarsebas · Aug 15, 2026 · Jul 25, 2026 · Jul 29, 2026 · Aug 15, 2026
diff --git a/.github/workflows/cougr-site.yml b/.github/workflows/cougr-site.yml
@@ -0,0 +1,62 @@
+name: Cougr Site
+
+on:
+  push:
+    branches: [main, develop]
+    paths:
+      - 'cougr-site/**'
+      - 'docs/**'
+      - 'ARCHITECTURE.md'
+      - 'CONTRIBUTING.md'
+      - 'CHANGELOG.md'
+      - 'SECURITY.md'
+      - '.github/workflows/cougr-site.yml'
+  pull_request:
+    branches: [main, develop]
+    paths:
+      - 'cougr-site/**'
+      - 'docs/**'
+      - 'ARCHITECTURE.md'
+      - 'CONTRIBUTING.md'
+      - 'CHANGELOG.md'
+      - 'SECURITY.md'
+      - '.github/workflows/cougr-site.yml'
+
+concurrency:
+  group: cougr-site-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  site:
+    name: Build and verify cougr-site
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Sync docs into cougr-site/src
+        run: python3 cougr-site/sync.py
+
+      # The sync reads straight from this checkout, so any drift here means
+      # cougr-site/src was committed out of date with its docs/*.md source.
+      - name: Verify synced content matches docs/*.md
+        run: |
+          if ! git diff --quiet -- cougr-site/src; then
+            echo "cougr-site/src is out of sync with its source docs."
+            echo "Run 'python3 cougr-site/sync.py' and commit the result."
+            git diff --stat -- cougr-site/src
+            exit 1
+          fi
+
+      - uses: peaceiris/actions-mdbook@v2
+        with:
+          mdbook-version: 'latest'
+
+      - name: Build the book
+        working-directory: ./cougr-site
+        run: mdbook build
diff --git a/cougr-site/.gitignore b/cougr-site/.gitignore
@@ -0,0 +1,9 @@
+# mdBook build output — never commit
+book/
+
+# macOS
+.DS_Store
+
+# Editor
+.vscode/
+.idea/
diff --git a/cougr-site/book.toml b/cougr-site/book.toml
@@ -0,0 +1,13 @@
+[book]
+authors = ["Cougr Contributors"]
+language = "en"
+src = "src"
+title = "Cougr Documentation"
+
+[build]
+build-dir = "book"
+create-missing = false
+
+[output.html]
+git-repository-url = "https://github.com/salazarsebas/Cougr"
+edit-url-template = "https://github.com/salazarsebas/Cougr/edit/main/{path}"
diff --git a/cougr-site/src/README.md b/cougr-site/src/README.md
@@ -0,0 +1,5 @@
+# Welcome to Cougr
+
+Cougr is an on-chain game engine built for the Stellar network and Soroban smart contracts. It provides a full Entity-Component-System (ECS) runtime alongside account abstraction and zero-knowledge primitives in a single crate.
+
+This documentation site is generated automatically from the [salazarsebas/Cougr](https://github.com/salazarsebas/Cougr) repository.
diff --git a/cougr-site/src/SUMMARY.md b/cougr-site/src/SUMMARY.md
@@ -0,0 +1,42 @@
+# Summary
+
+[Welcome](README.md)
+
+- [Start](start/README.md)
+  - [Getting Started](start/getting-started.md)
+  - [Build Your First Game](start/build-your-first-game.md)
+- [Learn](learn/README.md)
+  - [Architecture](learn/ARCHITECTURE.md)
+  - [Game Patterns](learn/PATTERNS.md)
+  - [On-Chain / Off-Chain Boundary Guide](learn/boundary-guide.md)
+  - [Smart Contract Patterns](learn/smart-contract-patterns.md)
+  - [Testing Guide](learn/testing-guide.md)
+  - [Deployment Guide](learn/deployment-guide.md)
+- [Reference](reference/README.md)
+  - [ECS Core](reference/ECS_CORE.md)
+  - [Account Kernel](reference/ACCOUNT_KERNEL.md)
+  - [Standards Layer](reference/STANDARDS_LAYER.md)
+  - [Privacy Model](reference/PRIVACY_MODEL.md)
+  - [Feature Flags](reference/FEATURE_FLAGS.md)
+  - [Performance Guide](reference/PERFORMANCE.md)
+  - [API Contract](reference/API_CONTRACT.md)
+  - [Compatibility Promises](reference/COMPATIBILITY_PROMISES.md)
+  - [Migration Guide](reference/MIGRATION_GUIDE.md)
+  - [CLI Reference](reference/cli-reference.md)
+  - [Client SDK Reference](reference/sdk-reference.md)
+  - [ADR: Architecture Decision Records](reference/adr/README.md)
+- [Showcase](showcase/README.md)
+  - [Example Gallery](showcase/gallery.md)
+- [Design](design/README.md)
+  - [Branding Guide](design/branding-guide.md)
+  - [UI Guidelines](design/ui-guidelines.md)
+  - [UX Guidelines](design/ux-guidelines.md)
+  - [Accessibility](design/accessibility.md)
+- [Community](community/README.md)
+  - [Contributing](community/CONTRIBUTING.md)
+  - [Code of Conduct](community/CODE_OF_CONDUCT.md)
+  - [Governance](community/governance.md)
+  - [Security](community/SECURITY.md)
+  - [Roadmap](community/roadmap.md)
+  - [RFC Process](community/rfc-process.md)
+  - [Changelog](community/CHANGELOG.md)
diff --git a/cougr-site/src/community/CHANGELOG.md b/cougr-site/src/community/CHANGELOG.md
@@ -0,0 +1,100 @@
+# Changelog
+
+## Unreleased
+
+### Added
+
+- **`cougr-cli`** — new workspace member publishing the `cougr` binary
+- **`cougr new <name> [--template <name>]`** — scaffolds a Soroban game contract crate
+  following the canonical `lib.rs` / `components.rs` / `systems.rs` layout, with a
+  passing `test::GameHarness` suite and a dependency on the published `cougr-core`
+  release rather than a path dependency
+- **Four embedded templates**, each derived from a canonical example and compiled into
+  the binary so `cougr new` works offline: `starter` (`spawn_and_move`), `turn-based`
+  (`tic_tac_toe`), `hidden-info` (`hidden_hand`), `session-auth` (`session_arena`)
+- **CLI CI workflow** — lints and tests `cougr-cli`, then generates each template and
+  runs `cargo fmt`, `clippy`, `cargo test`, and a `wasm32v1-none` release build against it
+
+## 1.1.0
+
+### Added
+
+- **`game::SorobanGame` trait** — standard `load_world` / `save_world` contract pattern;
+  implement once with `impl_soroban_game!(Contract, "key")`, use in every entrypoint
+- **`impl_soroban_game!` macro** — wires `SorobanGame` to any `#[contract]` struct
+- **`SimpleWorld::load_from_instance`** — load world from Soroban instance storage,
+  returning a fresh empty world on first call
+- **`SimpleWorld::save_to_instance`** — persist world to Soroban instance storage
+- **`SimpleWorld::set_rich_observed`** — store a rich component and emit a
+  `RichComponentChangedEvent` for off-chain indexers
+- **`SimpleWorld::remove_rich_observed`** — remove a rich component and emit a `del` event
+- **`RichComponentChangedEvent`** — new Soroban event type with topics
+  `("COUGR", "rich", component_type)` for rich component change notifications
+- **`spawn_and_move` example** — canonical Cougr starter game demonstrating the complete
+  idiomatic pattern: `impl_component_observed!` + `SorobanGame` + typed ECS access
+- **`SorobanGame` re-exported from `prelude`** — import from `cougr_core::prelude::*`
+- **`cougr_core::circuits`** — four pre-built ZK game builders (hidden cards, fog of war,
+  fair dice, sealed bid) with pipeline-embedded verification keys
+- **`cougr_core::session`** — `SessionManager`, `SessionStatus`, and `ActiveSession` (Beta)
+- **`cougr_core::test`** — `GameHarness`, `Scenario`, and `ReplayLog` sandbox behind the
+  `testutils` feature
+- **Circom pipeline** — `internal/cougr-core-circuits` with CI workflow and on-chain Groth16
+  proof verification using real VKs
+- **ZK examples** — `hidden_hand`, `fog_explorer`, `dice_duel`, and `blind_auction`
+- **Workspace subcrates** — `internal/cougr-core-{circuits,session,test}` per ADR 0007
+
+### Changed
+
+- `tic_tac_toe` example modernised: replaced ~200 lines of manual serialization with
+  `impl_rich_component!` for `Board` and `Players`, and `impl_soroban_game!` for
+  load/save. Public API is unchanged; all existing tests pass
+- README rewritten with clean 30-line quick start and full feature documentation
+- canonical example set expanded from three (`snake`, `battleship`, `guild_arena`) to ten:
+  `spawn_and_move` (Starter), `tic_tac_toe` (Rich components), `session_arena` (Session UX),
+  `hidden_hand`, `fog_explorer`, `dice_duel`, `blind_auction` (ZK circuits),
+  `snake` (Arcade/GameApp), `battleship` (Hidden information), `guild_arena` (Auth & recovery)
+- `session_arena` example added as canonical reference for `session::SessionManager`
+
+### Stability Notes
+
+- `game::SorobanGame` is **Stable**
+- `SimpleWorld::load_from_instance` / `save_to_instance` are **Stable**
+- `set_rich_observed` / `remove_rich_observed` are **Stable**
+- `RichComponentChangedEvent` is **Stable**
+- `cougr_core::session` is **Beta**
+- `cougr_core::circuits` and embedded test VKs are **Experimental**
+- `cougr_core::test` is **Experimental** (`testutils` only)
+
+---
+
+## 1.0.0
+
+### Added
+
+- `app` as the default gameplay runtime surface
+- `auth`, `privacy`, and `ops` as product-level domain namespaces
+- `RuntimeWorld` and `RuntimeWorldMut` as shared Soroban-first backend contracts
+- stronger stage scheduling with ordering, sets, and validation
+- `SimpleQueryBuilder`, query state/cache improvements, and richer `ArchetypeWorld` query helpers
+- expanded benchmark coverage for backend comparisons and cache invalidation behavior
+
+### Changed
+
+- the recommended onboarding path is now `app::GameApp` + `SimpleWorld` + `SimpleQueryBuilder`
+- canonical examples now emphasize the curated runtime story and explicit maturity boundaries
+- `battleship` now uses stable privacy primitives from `zk::stable`
+- documentation now treats `SimpleWorld` and `ArchetypeWorld` as the defended Soroban-first backends
+
+### Stability Notes
+
+- Stable: ECS onboarding/runtime contract, `app`, `ops`, `standards`, `privacy::stable`, `zk::stable`
+- Beta: `auth`, `accounts`, `game_world`
+- Experimental: `privacy::experimental`, `zk::experimental`, hazmat cryptographic helpers
+
+### Upgrade Notes
+
+- Prefer `app` over wiring scheduler/world primitives directly for new gameplay code
+- If you still have pre-1.0 code built around removed runtime abstractions, port directly to `GameApp`, `SimpleWorld`, and `SimpleQuery`
+- Prefer `ops`, `privacy`, and `auth` in application code when you want domain-oriented imports
+- Treat root-level advanced re-exports as compatibility/advanced surfaces rather than the default learning path
+- See [docs/MIGRATION_GUIDE.md](../reference/MIGRATION_GUIDE.md) for concrete migration mappings
diff --git a/cougr-site/src/community/CODE_OF_CONDUCT.md b/cougr-site/src/community/CODE_OF_CONDUCT.md
@@ -0,0 +1,10 @@
+# Code of Conduct
+
+> ⚠️ **This document is an urgent gap** identified in `docs/strategy/12-documentation-architecture.md`:
+> *"Missing despite 25+ active external contributors. Should be added immediately, independent of any other work in this package — this is a near-zero-cost fix for a real, present governance gap."*
+>
+> **Tracked in:** [`salazarsebas/Cougr` issues](https://github.com/salazarsebas/Cougr/issues)
+
+---
+
+A Code of Conduct will be added here imminently. It will be based on the [Contributor Covenant](https://www.contributor-covenant.org/) and apply to all project spaces including GitHub Issues, Pull Requests, and any community channels.
diff --git a/cougr-site/src/community/CONTRIBUTING.md b/cougr-site/src/community/CONTRIBUTING.md
@@ -0,0 +1,82 @@
+# Contributing
+
+Contributions should improve the framework, the example catalog, or the supporting documentation with a clear purpose. This repository is structured to be useful both as a reusable library and as a reference codebase, so changes should optimize for correctness, clarity, and maintainability.
+
+## Scope
+
+Good contributions typically fall into one of these categories:
+
+| Area | Expected outcome |
+|---|---|
+| Core framework | Improved ECS, scheduling, storage, authorization, or zero-knowledge capabilities |
+| Examples | New game patterns, better reference implementations, or tighter example documentation |
+| Documentation | Clearer architecture, setup, or usage guidance aligned with the current codebase |
+| Quality | Better tests, tooling, validation, or CI coverage |
+
+## Development Standards
+
+- Keep changes focused. Avoid mixing unrelated refactors with feature work.
+- Update documentation when behavior, structure, or public APIs change.
+- Prefer clear names and straightforward control flow over clever abstractions.
+- Preserve repository consistency. New files should fit the existing layout and conventions.
+- Do not add generated reports, ad hoc summaries, or temporary planning documents to the repository root.
+
+## Local Validation
+
+Run the relevant checks before opening a pull request:
+
+```bash
+cargo fmt --check
+cargo clippy --all-targets --all-features -- -D warnings
+cargo test
+```
+
+If you modify an example project, also run that example's local checks from its own directory. If the example supports Soroban contract builds, validate that flow as well.
+
+## Documentation Expectations
+
+Documentation should be professional, current, and proportionate:
+
+- avoid stale exact counts when the repository is expected to grow
+- explain decisions and usage patterns without turning every page into a long-form essay
+- use tables when they improve scanability, not as a default for all content
+- keep root-level documentation limited to material with clear long-term value
+- follow the terminology and voice rules in [docs/VOICE_GUIDE.md](docs/VOICE_GUIDE.md) for all doc, example, and marketing copy
+
+## Pull Requests
+
+Pull requests should make it easy to review technical intent. A strong PR description usually covers:
+
+1. what changed
+2. why the change was needed
+3. how it was validated
+4. any follow-up work or constraints reviewers should know about
+
+## Adding Examples
+
+When adding a new example:
+
+- make the example self-contained
+- include a local `README.md`
+- keep the example focused on one or two clear patterns
+- add CI coverage when the example is meant to remain a maintained reference
+
+## Review Criteria
+
+Changes are more likely to be accepted when they:
+
+- solve a real problem in the framework or examples
+- keep the API and repository structure coherent
+- include appropriate validation
+- improve the repository without increasing maintenance noise
+
+## Public API Checklist
+
+Changes that touch public Rust APIs should be reviewed against this checklist before merge:
+
+- the symbol belongs to the curated onboarding path or an intentional namespace such as `accounts`, `zk::stable`, or `zk::experimental`
+- stable, beta, experimental, and test-only surfaces are not mixed in the same default entrypoint
+- new public names do not duplicate an existing public concept
+- root-level re-exports are intentional and minimal
+- examples and integration tests use the sanctioned public path instead of deep internal module paths
+- documentation is updated to match the actual exported API
diff --git a/cougr-site/src/community/README.md b/cougr-site/src/community/README.md
@@ -0,0 +1,13 @@
+# Community
+
+Welcome to the **Community** section. This is where you'll find everything about how to contribute, how decisions are made, and how to stay up to date.
+
+| Document | Description |
+|---|---|
+| [Contributing](CONTRIBUTING.md) | How to open issues, write code, and get PRs merged |
+| [Code of Conduct](CODE_OF_CONDUCT.md) | Expected behaviour in all project spaces |
+| [Governance](governance.md) | How decisions are made, who can merge, how disputes are resolved |
+| [Security](SECURITY.md) | How to report vulnerabilities |
+| [Roadmap](roadmap.md) | Where the project is headed |
+| [RFC Process](rfc-process.md) | How to propose significant changes before implementing them |
+| [Changelog](CHANGELOG.md) | What changed in each release |