AGENTS.md

# Repository Guidelines

## Project Structure & Module Organization

`solverforge-fsr` is a Rust 1.95 SolverForge field-service routing app with an
Axum server and static browser workspace. Rust code lives in `src/`:
`domain/` defines planning entities and facts, `constraints/` contains scoring
rules, `solver/` owns retained solver jobs, `api/` exposes REST/SSE routes and
DTOs, and `data/` builds the Bergamo demo dataset. Browser assets live in
`static/`, split by responsibility (`app-route-state.js`,
`app-render-routes.js`, etc.). Deployment and configuration files are at the
repo root: `Dockerfile`, `Makefile`, `solver.toml`, and `solverforge.app.toml`.

Keep handwritten source, docs, and deployment files under 300 lines; split by
module or responsibility when a file approaches that size.

## Build, Test, and Development Commands

- `make doctor` checks local `cargo`, `rustc`, `node`, and `docker` readiness.
- `make run` runs the debug server on `PORT` (default `7860`).
- `make build-release` builds `solverforge_fsr` in release mode.
- `make test` runs Rust tests plus frontend JavaScript syntax checks.
- `make lint` runs `cargo fmt --check`, clippy with warnings denied, and JS syntax checks.
- `make ci-local` runs the full Hugging Face Space validation path, including Docker image build.
- `make space-run` builds and runs the Docker Space image locally.

## Coding Style & Naming Conventions

Use idiomatic Rust 2021 with `cargo fmt` formatting and clippy under
`-D warnings`. Rust modules and files use `snake_case`; types use `PascalCase`;
functions, fields, and variables use `snake_case`. Keep API DTOs explicit and
snapshot-scoped. Frontend files should stay plain JavaScript modules with clear
ownership boundaries rather than large shared scripts.

## Testing Guidelines

Place Rust unit tests near the code they cover, using descriptive names such as
`reports_unreachable_route_segments`. Run `make test` before handing off normal
changes and `make ci-local` before deployment, dependency, Docker, or Space
changes. Frontend validation is currently syntax-level via `node --check` over
`static/*.js`.

## Commit & Pull Request Guidelines

History uses conventional commits such as `feat(fsr): ...`, `fix(ui): ...`,
and `chore: ...`. Keep each commit focused on one revertable
intent and include a full body when the change spans behavior, deployment, or
dependencies. PRs should describe the user-visible effect, linked issue or
review comment, validation commands run, and include screenshots for visible UI
changes.

## Security & Configuration Tips

Do not commit credentials, local Hugging Face tokens, generated desktop bundles,
or build output. Keep Docker/Space builds registry-backed through crates.io
dependencies unless the build context explicitly vendors local crates.