AGENTS.md

# Repository Guidelines

## Project Structure & Module Organization

`src/` follows the current `solverforge-cli` app shape: `api/` for HTTP
routes, SSE, and DTOs; `solver/` for retained-job orchestration; `domain/mod.rs`
for the current `solverforge::planning_model!` manifest; `domain/` for the
exported model modules; `constraints/mod.rs` for constraint assembly; and
`constraints/*.rs` for the individual score rules. `data/mod.rs` is the stable
wrapper; `data/data_seed.rs` is the thin public data surface; and
`data/data_seed/` holds the deterministic sample dataset modules, including the
public entrypoints and the `LARGE` instance builder. `domain/plan.rs` owns
`Plan`, the scalar-variable `Shift`, and the scalar nearby hook functions;
`domain/employee.rs` and `domain/care_hub.rs` hold supporting domain types.
`static/` holds the browser app (`static/app/**/*.mjs`) and generated UI config.
Frontend tests live in `tests/frontend/`. Container packaging is defined by
`Dockerfile`.

This project depends on the published `solverforge` and `solverforge-ui` crates.

## Build, Test, and Development Commands

- `make help` — show the supported local development and validation commands.
- `make run-release` — run the app locally on `:7860`.
- `make test` — run the standard Rust, frontend, and Playwright validation surface.
- `make test-e2e` — run the real browser Playwright smoke.
- `make ci-local` — run the Space-oriented local CI pipeline: fmt, clippy,
  release build, standard tests, and Docker image build.
- `make test-slow` — run the ignored large-demo acceptance solve.
- `make pre-release` — run `make ci-local` plus the slow acceptance solve.
- `make space-build` — build the Docker image used by the Docker-based Space
  deployment path.
- `cargo run --release --bin solverforge-hospital` — run the app locally on
  `:7860`.
- `cargo test` — run Rust unit and integration tests.
- `cargo test large_demo_solves_to_feasible_terminal_state -- --ignored --nocapture`
  — slow end-to-end solver acceptance test.
- `find static/app -name '*.mjs' -print0 | xargs -0 -n1 node --check` —
  syntax-check frontend modules.
- `node --test tests/frontend/*.test.js` — run browserless frontend tests.
- `docker build -f Dockerfile -t solverforge-hospital .` — build the image from
  the repository root context.

## Coding Style & Naming Conventions

Use Rust 2021 style with `cargo fmt`; keep imports and formatting
rustfmt-compatible. Prefer small, explicit functions over clever indirection.
Rust module and file names are `snake_case`; types are `UpperCamelCase`; tests
should describe behavior plainly. Frontend modules are plain ES modules in
`snake-case` filenames. Keep generator logic deterministic: do not introduce
random behavior without a fixed seed and an explicit reason.

## Documentation And Commenting Policy

Assume a beginner reader who is new to SolverForge and new to optimization
modeling.

- Treat `README.md`, `WIREFRAME.md`, this file,
  `docs/api-and-solver-policy.md`, `docs/screenshot.png`,
  `solver.toml` comments, and the visible API help in
  `static/app/shell/api-guide.mjs` as one canonical documentation surface. When
  one changes, audit the others that describe the same behavior.
- Add module-level docs or comments for every new module that explain its role
  in the app and where it sits in the data flow.
- Add function comments when the function does real coordination work, rebuilds
  invariants, shapes demo data, converts between layers, or otherwise does
  something a beginner would not infer immediately from the signature.
- Write comments that explain intent, domain meaning, invariants, and runtime
  consequences. Do not write comments that merely restate syntax.
- Keep comments truthful. If behavior changes, update or delete the stale
  comment in the same patch.
- When docs mention versions, counts, routes, solver policy, or validation
  expectations, verify those facts against the current code and tests in the
  same turn.
- Prefer present-tense current-state docs after a refactor lands. Do not leave
  future-tense planning language in repo docs unless the file is intentionally a
  still-pending plan.
- When onboarding surfaces change, keep `README.md`, `WIREFRAME.md`, and this
  file aligned.

The standard to aim for is: a new reader should be able to understand why a
piece of code exists before they need to understand every line of how it works.

This repo does not have a canonical hosted GitHub Actions workflow yet. Treat
the Makefile targets, especially `make ci-local` and `make pre-release`, as the
authoritative validation surface for the current Hugging Face Space-oriented
deployment path.

## Testing Guidelines

Add Rust tests next to the behavior they protect, usually in `src/...`
`#[cfg(test)]` modules. Frontend behavior belongs in `tests/frontend/` and
should use the existing fake DOM support in `tests/support/`; real browser
flows belong in `tests/e2e/`. If you change solver behavior, run both
`cargo test` and the ignored large-demo solve. If you change UI modules, run
the Node syntax check, frontend tests, and Playwright tests.

## Commit & Pull Request Guidelines

Follow the workspace commit style seen upstream: conventional prefixes such as
`fix(...)`, `feat(...)`, `refactor(...)`, `test(...)`, and `chore(...)` (for
example, `fix(runtime): route pure scalar construction to descriptor path`).
PRs should state user-visible impact, changed config or API surface, and the
exact validation commands run. Include screenshots only for visible UI changes.

## Configuration & Runtime Notes

`solver.toml` is embedded from `domain/plan.rs` via
`#[planning_solution(..., solver_toml = "../../solver.toml")]`; treat it as
the runtime source of truth. Keep `solverforge.app.toml`,
`static/sf-config.json`, and Docker/runtime port settings aligned with any port
or route changes.