MCG (Mental Card Game) – Agent Onboarding

# MCG (Mental Card Game) – Agent Onboarding

## Workspace Snapshot

MCG is a Rust Cargo workspace for a browser-based card game. The frontend crate (`frontend`) compiles to WebAssembly with `wasm-pack` and renders using `egui`/`eframe`. The backend crate (`native_mcg`) exposes HTTP, WebSocket, and optional iroh QUIC transports, while the `shared` crate provides protocol and domain types used by both sides. Generated WASM artifacts live under the repository-root `pkg/` directory and are loaded by `index.html`; media assets are served from `media/`.

## Key Commands (`just` recipes)

- `just build [PROFILE]` – Run `wasm-pack` for the frontend (`release`, `profiling`, or `dev`). Output: `pkg/`.
- `just start [PROFILE]` – Build the frontend then run the backend
- `just backend` – Launch the `native_mcg` server; it binds to the first free port ≥3000 and serves `/`, `/pkg`, `/media`, and `/ws`.
- `just backend-bg` / `just kill-backend` – Start or stop the backend in the background (useful for automation).
- `just cli -- <args>` – Forward arguments to the `mcg-cli` binary (WebSocket client for state inspection and commands).
- `just agents` – Copy the current `AGENTS.md` into `CLAUDE.md` and `CRUSH.md` for other assistants.

## Development Notes

- Toolchain: Rust stable plus `wasm-pack`; ensure both are installed before invoking recipes.
- Tests and linting: `cargo test --workspace`, `cargo clippy --workspace --all-targets -- -D warnings`, and `cargo fmt --all`.
- Backend configuration: Defaults are generated in `mcg-server.toml` on first run (controls bot count and timing).
- Architecture intent: Long-term goal is peer-to-peer play—each player runs their own backend; avoid features that assume multiple players share one backend instance.
- Frontend routing: Screens are registered under `frontend/src/game/screens/`; new screens implement `ScreenDef` and `ScreenWidget` and are added to the registry.

## Agent Conduct

- Do not modify documentation files (e.g., `README.md`) unless explicitly requested.
- Run available tests/lints relevant to your changes before reporting success, unless explicitly told otherwise.

## Agent Git-Commit Policy (Extension)

- Agents MUST NOT run `git add`, `git commit`, or `git push` without explicit human authorization (passphrase: `agent-commit-allowed`).
- Agents MAY create or modify workspace files for iteration but must leave staging/committing to a human.
- Provide diffs for review when suggesting commits.
- Humans can inspect changes with `git status --porcelain` and `git diff`, then commit manually as needed.