AGENTS.md

Repository Guidelines

Project Structure And Naming

solverforge-lessons is a Rust 1.95 SolverForge lesson-timetabling app with an Axum server and static browser workspace. Keep the repo-local directory name uc-lessons; product copy, metadata, and UI labels should use solverforge-lessons or SolverForge Lessons.

• src/domain/mod.rs owns the solverforge::planning_model! manifest.
• src/domain/plan.rs owns the Plan planning solution.
• src/domain/lesson.rs owns the Lesson planning entity and its timeslot_idx and room_idx scalar variables.
• src/domain/{timeslot,teacher,group,room}.rs own the problem facts.
• src/constraints/ owns one timetable scoring rule per file plus mod.rs assembly.
• src/data/data_seed/ owns deterministic LARGE demo generation.
• src/api/ owns REST, DTO, and SSE surfaces.
• src/solver/ owns retained-job runtime orchestration.
• static/ owns the browser shell and generated view model.
• Dockerfile, Makefile, solver.toml, and solverforge.app.toml define the deployment and runtime contract.

Keep the canonical solution name Plan and the public demo id LARGE.

Build And Validation Commands

• make help shows the supported command surface.
• make run-release runs the app locally on :7860.
• make test runs Rust tests, frontend syntax checks, and the Playwright smoke.
• make test-e2e runs the real browser smoke.
• make ci-local runs formatting, clippy, release build, standard tests, and the Space Docker image build.
• make test-slow runs the ignored large-demo acceptance solve.
• make pre-release runs ci-local plus the slow acceptance solve.
• cargo test runs Rust unit tests.
• PORT=7861 cargo run --bin solverforge-lessons runs the app on an alternate port when 7860 is already occupied.

Use the Makefile as the authoritative local workflow.

Documentation And Commenting Policy

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

• Keep README.md, WIREFRAME.md, this file, solver.toml, solverforge.app.toml, static/sf-config.json, and docs/screenshot.png aligned.
• Add module-level docs or comments for modules that explain their role in the app and where they sit in the data flow.
• Add function comments when the function coordinates SolverForge concepts, rebuilds invariants, shapes demo data, converts between layers, or otherwise does something a beginner would not infer from the signature.
• Write comments that explain intent, domain meaning, invariants, and runtime consequences. Do not write comments that merely restate syntax.
• Keep comments present-tense and source-backed. If behavior changes, update or delete the stale comment in the same patch.
• When docs mention versions, counts, routes, demo IDs, solver policy, or validation expectations, verify those facts against current code in the same patch.

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

Testing Guidance

Add Rust tests next to the behavior they protect. Real browser flows belong in tests/e2e/. If you change solver behavior, run cargo test and the ignored large-demo solve. If you change UI structure, run the frontend syntax check and Playwright smoke.

Runtime Notes

solver.toml is embedded by Plan through the planning-solution macro. Treat it as the solver policy source of truth.

The app serves stock solverforge-ui assets, local static app modules, and Axum API routes from one process. Retained solver jobs are controlled through REST and observed through SSE.