# Project notes for agents

## AGENT RULES
- you **MUST NOT** change `AGENTS.md` or `CLAUDE.md` unless explicitly asked
- you **MUST** never do `git push`, unless you're explicitly told to
- you **MUST NOT** commit to `main`. If the current branch is `main`, ask the user before making changes whether to create a new branch or to make the changes without committing
- you **MUST** always run `cargo fmt --all` after changing file contents. Never pass formatting options on the command line (`--config`, `--edition`, ...) or invoke `rustfmt` directly on files; when present, formatting settings come from `rustfmt.toml` and `Cargo.toml`
- you **MUST** use conventional commits when committing (`feat`, `fix`, `perf`, `refactor`, `chore`, `docs`, `test`, `dev`), with `!` and a `BREAKING CHANGE:` footer for API breaks
  - `dev` is used for tooling, debugging aids and test-flakiness work that doesn't change shipped behaviour
  - `bump` (dependency version bumps) and `release` are used by maintainers; don't create release commits unless asked
- you **MUST** end commit messages with a `Co-Authored-By:` trailer naming yourself as the agent (product name only, no model or version), e.g. `Co-Authored-By: Claude <noreply@anthropic.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, unless the user tells you to not commit or a file with the name `.NOCOMMIT` exists in the project root. This applies to all changes, including docs, `AGENTS.md`, CI and config files, not just Rust code
  - changes that affect compilation or tests (Rust code, `Cargo.toml`/`Cargo.lock`, build scripts, test data) may only be committed after `cargo clippy` and `cargo test` pass
  - other changes (Markdown, CI, editor or deployment config) don't need those checks; commit them right away
  - check the current branch (`git branch --show-current`) before every commit, not just at the start of the session
- you **SHOULD** commit formatting-only changes separately from functional changes: if `cargo fmt --all` reformats code you didn't change, commit that first as `chore: cargo fmt`; do not stage unrelated user changes
- you **SHOULD** add user-visible changes to the `Unreleased` section of [CHANGELOG.md](CHANGELOG.md) (Keep a Changelog format), creating that section if needed

## Commands

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

Lint conventions:

- Configure workspace lints in `[workspace.lints]` in the root [Cargo.toml](Cargo.toml); new crates should opt in with `[lints] workspace = true`.
- Change lint levels there, not on the command line or in CI.

## 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

- Use descriptive variable and function names so the code explains itself.
- Comment only code that needs clarification, and keep comments short.
- Add dependencies to `[workspace.dependencies]` in the root [Cargo.toml](Cargo.toml) and use `dep.workspace = true` in crates.
- Use `thiserror` in libraries and `anyhow` only in binaries/tools.
- Use `tracing` for logging. Only add tracy spans in performance-critical code.

## Code reviews

Whenever asked for a code review (of commits, a branch, a diff, or specific files), report every finding as an entry in a list, in this exact shape:

- **Location:** `file:line` (use a range like `file:120-146` when the finding spans several lines)
- **Category:** one of `Blocking`, `FYI`, `Nit` (add categories such as `Question` only when none fit)
- **Comment:** what could be improved and the concrete problem or risk, including the failure scenario when claiming a defect—not just an abstract concern

Order findings by severity (`Blocking` first). Use `Blocking` for things that must change before merge (defects, unbounded resource use, or violations of these rules), `FYI` for design consequences and risks worth a conscious decision, and `Nit` for style/cleanliness. Verify claims against the code and run the Clippy and test commands from [Commands](#commands) before reporting; say when a finding is a possibility rather than a confirmed defect.