# AGENTS.md

This repository is managed with `uv`. Use `uv run ...` so the project
environment and Cython extensions are built and loaded consistently.

## Active project path

The active product and research path is **JAX + PPO**:

- `src/lost_cities_jax/`: pure JAX rules, observations, PPO, evaluation,
  league, and human-play tools.
- `configs/jax_ppo/`: active YAML configurations.
- `web/`: static TypeScript client with the final JAX PPO ONNX policy.
- `web/public/models/jax-ppo.onnx`: verified browser policy. Keep its manifest
  in sync and do not replace it without running the export validation.

Historical Deep CFR and ISMCTS implementations live under
`src/coolrl_lost_cities/games/classic/`. Their configs are in `legacy/`; they
are reproduction-only and must not be used as the default for new work. See
`docs/legacy.md`.

## Core commands

```bash
uv run ruff check .
uv run pytest -q tests/lost_cities_jax
uv run pytest -q
uv run lost-cities-jax-ppo --help
```

Web checks:

```bash
cd web
npm test
npm run build
```

## JAX PPO workflow

CPU smoke runs write disposable artifacts under `runs/tmp/`:

```bash
uv run lost-cities-jax-ppo rollout-smoke --config configs/jax_ppo/smoke.yaml
uv run lost-cities-jax-ppo train --config configs/jax_ppo/smoke.yaml
```

GPU training must hold the shared compute lock. Use a real `tmux` session for
long user-observable jobs:

```bash
flock -n .compute.lock uv run --with 'jax[cuda12]' lost-cities-jax-ppo train \
  --config configs/jax_ppo/balanced.yaml \
  --set run.artifact_root=runs/jax-ppo
```

Evaluation is deterministic and does not need the lock:

```bash
uv run lost-cities-jax-ppo eval \
  --config configs/jax_ppo/balanced.yaml \
  --checkpoint runs/jax-ppo/<run>/latest \
  --opponent heuristic_balanced --games 10000 --duplicate
```

Generated artifacts under `runs/` are gitignored. Do not modify or delete
`runs/archive/`.

## Static browser policy

The checked-in ONNX policy is small enough for static distribution. To replace
it, export a validated checkpoint and rebuild the web app:

```bash
uv run --with onnx scripts/export_jax_ppo_onnx.py \
  --checkpoint /path/to/checkpoint \
  --output web/public/models/jax-ppo.onnx
cd web && npm test && npm run build
```

Commit the ONNX file and its JSON manifest together. The app must continue to
use a base-relative model URL so static subpath hosts work.

## Documentation

- Active plans: `docs/plans/`.
- Retired plans and historical evidence: `docs/plans/archive/`,
  `docs/archive/`, and `docs/research/`.
- Do not edit archival documents; add a new dated note or active plan instead.

When changing docs, run `scripts/librarian.sh` to validate Markdown links and
`file:line` citations.

## Git policy

Do not create git branches unless the user explicitly asks in the current
task. Work on the checked-out branch. Before committing, run `uv run ruff
check .` and the relevant tests. Never commit generated run artifacts.