# Project notes for agents

## AGENT RULES
- you **MUST** never do `git push`, unless you're explicitly told to
- you **MUST** always run formatting tools such as `cargo fmt` after you changed the contents of a file
- you **MUST** use conventional commits when committing (`feat`, `fix`, `perf`, `refactor`, `chore`, `docs`), with `!` and a `BREAKING CHANGE:` footer for API breaks
- you **MUST** end commit messages with the trailer `Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>`
- you **MUST** inform the user about commits or any other changes to git, including the commit message
- you **SHOULD** commit your changes after every step, but only when `cargo clippy` and `cargo test` pass
- you **SHOULD** commit formatting-only changes separately from functional changes

## Commands

```sh
cargo build --workspace --all-targets
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings   # must stay clean
cargo fmt --all
```

The server build runs `build.rs`, which builds `ui/` for `wasm32-unknown-unknown`
and embeds the generated assets; there is no separate UI packaging step. See
[README.md](README.md) for setup and run instructions.

## Project Context

- `src/main.rs` hosts the Axum API and simulation thread; `src/world.rs` owns
  world behavior and snapshots; `src/storage.rs` persists snapshots.
- `config.rn` defines the Rune simulation defaults and agent behavior. Runtime
  script edits are not written back to this file; see the README before changing
  reset or persistence behavior.
- `ui/` is the Leptos/Wasm frontend. Keep its API/model changes aligned with the
  server payloads in `src/main.rs`.

## Conventions

- Comment only code that needs clarification.
- Warnings are treated as errors (`-D warnings`).
- After Rust changes, run `cargo fmt --all`; formatting is not needed for
  documentation-only changes.