# Workflows

## Build, test, verify

```bash
cargo test                    # 130 tests, all in the lib (sim has 19 dedicated)
cargo clippy --all-targets    # must stay at zero warnings
cargo fmt                     # rustfmt is enforced-by-convention since 05048e4
cargo build --features bevy_ui --bin supervillain-bevy   # keep the Bevy build green
cargo clippy --features bevy_ui --all-targets            # ...and lint-clean
```

The definition of done for a functional change: tests pass, both clippy runs
clean, both frontends build, and the change was *seen running* (below).

## Running the game

```bash
cargo run --release                                        # terminal frontend
cargo run --release --features bevy_ui --bin supervillain-bevy   # Bevy frontend
```

- The Bevy frontend must be run via `cargo run` (or with `BEVY_ASSET_ROOT`
  pointing at the repo root): Bevy resolves `assets/` from `BEVY_ASSET_ROOT`,
  then `CARGO_MANIFEST_DIR`, then the executable's directory. Running the
  binary directly from `target/` silently loads zero assets.

## Headless smoke tests (they catch real bugs)

Terminal frontend through a pty — this found a capacity-overflow crash and an
asset regression on the first two uses:

```bash
(printf '\n'; sleep 4; printf 'm'; sleep 1; printf '\r'; sleep 2; printf '\x1b'; sleep 1; printf 'q') | \
  script -q /dev/null sh -c 'stty rows 40 cols 140; ./target/debug/supervillain'
```

The `stty` matters: `script`'s pty is otherwise 0x0 (the game guards against
< 60x20 now, but you want a real render).

Bevy launch check (opens a window briefly; greps the log for failures):

```bash
BEVY_ASSET_ROOT=$PWD ./target/debug/supervillain-bevy > /tmp/bevy.log 2>&1 &
sleep 8 && kill %1; grep -iE "panic|ERROR" /tmp/bevy.log
```

## Git conventions

- Commits: **no AI attribution**, plain descriptive messages, body bullets for
  multi-part changes. Stage files explicitly — `git add -A` is not permitted.
- Spec-driven rule: functional change commits include their DESIGN.md
  amendment and any knowledge/ updates (see development-style.md).
- Remote: `origin` is a Tangled knot (`tangled.org`, SSH). Push `main`
  directly; no PR flow currently.
- `.letta/settings.local.json` is gitignored (machine-local session state);
  `.letta/.lettaignore` is tracked.

## Documentation flow per session

1. DESIGN.md amendment (if functionality changed).
2. knowledge/ updates (if reality changed).
3. `devlogs/YYYY-MM-DD-topic.md` session writeup; DEVLOG.md gets the short
   ledger line.