SolverForge Site

This repository is the dedicated Bridgetown source for https://solverforge.org/.

What lives here

• src/docs/** for public product docs and tutorials
• src/reference/** for dense engineering reference and clearly labeled maintainer notes
• src/_posts/** for blog and release posts
• src/use-cases.md, src/_data/use_cases.yml, src/images/use-cases/**, and src/videos/use-cases/** for the public use-case showcase: one slide per case with its metrics, constraints, narrated runtime walkthrough, and annotated screenshots
• plugins/use_case_page_generator.rb and src/_layouts/use_case.erb for the per-case pages at /use-cases/<id>/, generated from the same data file so the carousel and the individual pages cannot disagree about a case
• frontend/** for bundled CSS/JS sources
• plugins/** for build-time extensions, including static search generation

Source-of-truth boundaries

This repo owns the published website. It does not replace repo-local engineering surfaces in the product repositories.

• SolverForge/solverforge keeps the Rust workspace README.md and crates/*/WIREFRAME.md files.
• SolverForge/solverforge-cli, SolverForge/solverforge-ui, and SolverForge/solverforge-maps keep their own repo-local maintainer files, architecture notes, and implementation detail.
• This site should summarize and integrate those surfaces where useful, but it should not mirror them wholesale.

When a source repo changes public APIs, naming, onboarding, or maintainer workflow, update the matching published pages here in the same effort.

Local workflow

Preferred entry points:

1. make help
2. make install
3. make ci-local
4. make pre-release
5. make start

Direct Bridgetown commands:

1. bundle install
2. npm ci
3. bundle exec rake frontend:build
4. bundle exec bridgetown build
5. ruby scripts/verify-cli-release.rb
6. ruby scripts/verify-use-cases-page.rb
7. ruby scripts/verify-hospital-tutorial.rb
8. ruby scripts/verify-deliveries-tutorial.rb
9. bundle exec bridgetown start -P 4017

make verify-hospital-tutorial replays the hospital use-case page with the published CLI: it installs solverforge-cli at the version the page documents into ~/.cache/solverforge-cli/<version> (override with SOLVERFORGE_CLI_CACHE), runs the page's scaffold commands and writes the complete files the page shows, then builds, boots and solves the result; it also clones the Hugging Face Space the page names, runs the page's validation commands there, boots and solves it, and checks the page's facts against that clone. make test runs only its static page checks (--static). Set TUTORIAL_REPLAY_TARGET_DIR to share Cargo build output between runs. The replay harness is scripts/lib/tutorial_replay.rb. The Make target is the stable public workflow; the Ruby script is an implementation detail behind that target.

make verify-lessons-tutorial, make verify-deliveries-tutorial and make verify-fsr-tutorial replay the Lessons, Deliveries and FSR use-case pages the way a reader follows them (scripts/lib/use_case_tutorial.rb on the shared scripts/lib/tutorial_replay.rb). Each installs the pinned published solverforge-cli, runs the page's Getting Started commands in page order with the complete files the page shows, builds, boots with the page's run command, runs the page's curl commands, and solves; then it clones the Hugging Face Space the page names, solves it, compares the page's dependency, metadata, solver, path, constraint, and dataset claims with the clone, and runs the page's validation commands there (Docker targets excepted). make test runs the static half (--static). TUTORIAL_REPLAYS lists the replays make ci-local runs; GitHub Actions runs them in the tutorials job, with SOLVERFORGE_CLI_CACHE, TUTORIAL_REPLAY_TARGET_DIR and TUTORIAL_REPLAY_OSM_CACHE pointing at cached directories.

make verify-maintenance-walkthrough holds the agent-skill walkthrough to what it teaches and never skips. It replays the page's command block with the installed solverforge (or SOLVERFORGE_BIN), overlays the hand-written files from scripts/fixtures/maintenance-walkthrough/, runs the app's tests, boots the API shell, solves, and compares the result with the page's analysis table and an independent feasibility check. Every Rust excerpt on the page must be verbatim in a fixture file. make test runs the static half (--static); make ci-local runs the whole contract, so a host without solverforge-cli 3.7.1 and cargo fails it.

make verify-serio-page holds the SERIO concept page to the engine. It builds scripts/fixtures/serio-trace/ against the documented solverforge tag from SOLVERFORGE_RS_REPO, runs one traced move, and compares the printed input and scores with the page's tables; every kept score must equal a fresh full evaluation, and the page's constraint function must be verbatim in the fixture. make test runs the static half; make ci-local runs the trace.

make verify-solver-config holds the solver pages (src/docs/solverforge/solver/ and the lifecycle contract note) to crates.io solverforge =0.24.0. Every ```toml block is parsed with SolverConfig::from_toml_str and solved on a fixture model that owns the variables it names (scripts/fixtures/solver-config/); a block meant to fail carries <!-- sf-toml: expect="parse-error|solve-error" message="..." --> and must fail with that text. Every Rust block on those pages must be verbatim in a // page: region of the fixture, which runs the lifecycle snippets and asserts their outcomes. make test runs the static half; make ci-local builds and runs everything (SOLVER_CONFIG_TARGET_DIR sets the cargo target directory). make verify-ui-getting-started builds the solverforge-ui Getting Started app from the page's own blocks against crates.io, boots it with the page's run command, and loads it in Playwright: / must be text/html, SF.version must equal the solverforge-ui version Cargo resolved, and the browser must report zero console errors. The Scheduling Views Gantt example and the Integration & Assets map example run against the same app's /sf/* assets, and the retained-job route table and createTable unsafe field are compared with the crate's sf.js. It runs in make ci-local.

make verify-python-docs replays the Python pages against PyPI in fresh venvs: the install block, every block saved to schedule.py with its printed output, the API Surface names, the Required Selector Fields table, every complete example (a block with assert), and the Hospital Example's published-package path through a COMPLETED POST /jobs. It needs python3.14 and git. make test runs the page contract (--static); make ci-local runs the replay.

make verify-companion-docs checks the solverforge-maps, solverforge-bench, and Integration Boundaries pages against crates.io release tarballs and the documented solverforge-bench revision (SOLVERFORGE_BENCH_REPO, or a cached clone). It runs in make test and make ci-local. Documentation and reference pages never name a competing solver; make check-public-pages rejects the names.

make ci-local runs the same path as GitHub Actions: toolchain checks, syntax linting, a full Bridgetown build, the public-page copy/link/nav/layout checks, and the portable tutorial verifiers. make pre-release first installs the published solverforge-cli release into /tmp, verifies the scaffold targets, and then delegates to the local CI gate.

Benchmark snapshot

/benchmarks/ renders a checked-in warehouse snapshot, grouped by problem. Refresh it with ruby scripts/import-benchmarks.rb (requires psql; defaults to the local solverforge_bench database, or uses BENCH_DATABASE_URL). The importer uses one read-only transaction and never runs benchmarks. It selects the latest publishable full canonical nightly candidate run per problem, excluding quick, custom, partial, and publication-rejected runs.

src/_data/benchmarks.json holds computed summaries; src/benchmarks/results.json is the downloadable evidence, including every selected result and tested solver version. Missing full runs are shown as unavailable, not replaced by smaller runs. Publication timestamps and versions describe the recorded runs, not current package releases. Normal builds and CI need no warehouse connection.

Normal builds and CI use the site's existing Ruby toolchain; the benchmark importer and verifier require no extra gems. To recompute only the summary from committed evidence without contacting PostgreSQL:

ruby scripts/import-benchmarks.rb --snapshot src/benchmarks/results.json --summary-only

make verify-benchmarks recomputes summaries from the evidence and checks full-run scope, versions, matrix completeness, and rejection of quick or partial data. This gate runs in make test and make ci-local.

Each problem renders gate-based charts from that same data: feasibility per solver and budget, first observed feasible gate per instance, and mean reference gap. Runtime is diagnostic only, never a ranking criterion. A problem whose run holds no reference cost states that in prose instead of drawing an empty panel, since no comparison exists to draw. scripts/check-public-pages.mjs reads src/_data/benchmarks.json and checks the rendered sections, budgets, rows, bar fills, measured-zero marks, legends, and provenance against it, so a problem or budget that stops rendering fails the gate rather than quietly disappearing.

Lint follow-up

The current make lint target is dependency-light and only performs Ruby and JavaScript syntax checks with the existing toolchain. A stricter follow-up should add configured tooling before broadening the gate:

• Ruby: StandardRB or RuboCop, chosen once the repo style is settled
• JavaScript/CSS: ESLint plus Prettier
• Markdown/content: markdownlint and an internal link checker

After those tools are configured, extend fmt, fmt-check, and lint to use them instead of relying only on syntax checks.

Publishing

This repo is meant to be served as solverforge.org. GitHub Actions installs dependencies with make install, runs make ci-local, and deploys output/ to Pages.