AGENTS.md

Repository Guidelines

Project Structure And Naming

solverforge-fsr is a Rust 1.95 SolverForge field-service routing app with an Axum server and static browser workspace. The app package version is declared in Cargo.toml, and the release binary is solverforge_fsr.

• src/domain/mod.rs owns the solverforge::planning_model! manifest.
• src/domain/field_service_plan.rs owns the FieldServicePlan solution, transient visit-index normalization, and route shadow refresh hook.
• src/domain/location.rs, service_visit.rs, and travel_leg.rs own the problem facts.
• src/domain/technician_route.rs owns the planning entity and its visits list variable.
• src/domain/route_metrics.rs owns route shadow measurement.
• src/constraints/ owns SolverForge scoring rules, one business rule per file. Prefer stock ConstraintFactory streams; assigned_visits.rs keeps the duplicate-assignment check as a small custom IncrementalConstraint because a grouped stream would count singleton groups as analysis matches.
• src/data/data_seed.rs owns STANDARD demo assembly and road-matrix preparation; src/data/bergamo_*.rs owns the static locations, visit profiles, technicians, and shared catalog types.
• src/api/ owns REST, DTO, route geometry, and SSE surfaces.
• src/solver/ owns retained-job runtime orchestration.
• static/ owns the browser workspace, split by responsibility (app-route-state.js, app-render-routes.js, etc.).
• Dockerfile, Makefile, solver.toml, and solverforge.app.toml define the deployment and runtime contract.

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, frontend JavaScript syntax checks, and the Playwright browser smoke.
• 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 includes node --check over static/*.js; served browser behavior is covered by make test-e2e.

Documentation And Commenting Policy

Assume a reader who is new to Rust and new to planning optimization.

• Keep README.md, WIREFRAME.md, this file, solver.toml, solverforge.app.toml, static/sf-config.json, and the visible browser API guide aligned.
• Keep docs/screenshot.png current whenever the visible browser shell changes.
• Add module or function comments where code coordinates SolverForge concepts: facts, planning entities, variables, retained jobs, road matrices, route geometry, or score math.
• Explain domain meaning and solver consequences. Do not keep scaffold placeholders, future-tense planning prose, or comments that merely restate syntax.
• When docs mention versions, counts, routes, demo IDs, solver policy, or validation expectations, verify those facts against current code in the same patch.

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 the declared crates.io dependency line unless the build context explicitly vendors local crates.