docs(app): document hospital crates.io workflow

Document the hospital app structure, planning_model manifest, retained runtime behavior, validation commands, and Docker workflow across the canonical repo docs.

Update the dependency background to published solverforge 0.9.0 and solverforge-ui 0.6.1, with no sibling path setup required.

AGENTS.md

@@ -0,0 +1,112 @@
+# 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 and frontend validation surface.
+- `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 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, `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.
+- `PRD.md` is background/planning context only. It may be useful, but do not
+  treat it as canonical current-state documentation.
+- 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. Update `PRD.md` only if its background note would otherwise
+  become misleading.
+
+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/`. 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 and frontend 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.

PRD.md

@@ -0,0 +1,172 @@
+# PRD: Current `solverforge-hospital` Product Contract
+
+This file is background/planning context. It is not canonical for current
+behavior. The current source of truth is the code, `solver.toml`, `README.md`,
+`WIREFRAME.md`, and `AGENTS.md`.
+
+## Summary
+
+`solverforge-hospital` is now a `solverforge 0.9.0` and `solverforge-ui 0.6.1`
+example. This repo demonstrates current retained-runtime integration, current
+stock UI-shell usage, and current scalar nearby-selection support.
+
+The objective of the repo is not to force every upstream neighborhood family
+into the hospital example. The objective is to keep the example truthful,
+current, teachable, and productive on its own dataset.
+
+## Product Shape
+
+### Backend
+
+- Rust/Axum retained-job backend
+- `Plan` planning solution in the current `solverforge-cli` backend shape
+- scalar planning variable: `Shift.employee_idx`
+- exact runtime telemetry from `SolverTelemetry`
+- hospital-specific transport projection for UI metrics
+
+### Frontend
+
+- stock `SF.createBackend({ type: "axum" })`
+- stock `SF.createHeader()`
+- stock `SF.createStatusBar()`
+- stock `SF.createSolver()`
+- stock `SF.rail.createTimeline()`
+
+### Data
+
+- deterministic `LARGE` dataset
+- `50` employees
+- `688` shifts
+- feasible and stable under the shipped solver policy
+
+## 0.9.0 Alignment Decisions
+
+### Versions
+
+All surfaced versions align to:
+
+- `solverforge` `0.9.0`
+- `solverforge-ui` `0.6.1`
+- app/chart metadata `0.9.0`
+
+No active docs or package metadata should describe the app as an `0.8.x`
+example.
+
+### Nearby selection
+
+Hospital exercises the scalar nearby-selection surface shipped in
+`solverforge 0.9.0`.
+
+To make nearby honest instead of guessed, the domain adds:
+
+- `CareHub`
+- `Employee.home_hub`
+- `Shift.care_hub`
+- scalar nearby meters on `Shift.employee_idx`
+
+Those meters bias:
+
+- shift -> employee by care-hub fit, required-skill fit, and obvious
+  infeasibility
+- shift -> shift by care-hub proximity and start-time band
+
+### Shipped solver policy
+
+The shipped [solver.toml](./solver.toml) is:
+
+- `construction_heuristic(cheapest_insertion)`
+- explicit `local_search`
+- explicit scalar nearby neighborhoods:
+  - `nearby_change_move_selector`
+  - `nearby_swap_move_selector`
+- `late_acceptance`
+- `accepted_count` forager
+
+Reason:
+
+- this uses the new 0.9.0 scalar nearby surface directly
+- it produces real post-construction improvement on the large demo
+- it remains feasible and fast enough for a 30-second example run
+
+Hospital does not ship a broader scalar union here just because upstream now
+supports it. On this dataset:
+
+- adding pillar and ruin-recreate makes the first local-search step too large
+- `VND` can absorb the full global time budget before later phases run
+
+Those are runtime/product facts, not reasons to misdocument the app.
+
+### Truthfulness about upstream surface
+
+SolverForge `0.9.0` ships more scalar neighborhoods than hospital currently
+uses. Hospital documents that honestly:
+
+- upstream ships nearby, pillar, and ruin-recreate for scalar variables
+- hospital currently opts into nearby-only local search because it is the most
+  productive configuration for this example
+
+## Repository Surface
+
+### Source
+
+- `src/domain/mod.rs` is the current `planning_model!` manifest; `src/domain/plan.rs`
+  owns `Plan`, the scalar-variable `Shift`, and nearby meters;
+  `src/domain/employee.rs` and `src/domain/care_hub.rs` own the supporting
+  problem fact and proximity enum
+- `src/constraints/mod.rs` is the canonical CLI-style assembler for
+  `create_constraints`; each hospital score rule lives in its own
+  `src/constraints/*.rs` module
+- `src/data/mod.rs` follows the CLI stable-wrapper shape;
+  `src/data/data_seed.rs` orchestrates the generated dataset and
+  `src/data/data_seed/` owns the focused generator modules; the generator
+  assigns deterministic home hubs from workforce skill bundles
+- `static/app/shell/config-loader.mjs` uses the explicit Axum backend adapter
+- `solver.toml` reflects the shipped nearby-based solver policy
+
+### Docs
+
+- `README.md` markets the repo as `0.9.0` / `0.6.1` and acts as the
+  beginner-facing quick start
+- `WIREFRAME.md` explains architecture and request/data flow
+- this PRD explains why the shipped solver policy stays narrow
+- contributor docs keep `solver.toml` as the runtime source of truth
+- the browser-visible API guide in `static/app/shell/api-guide.mjs` stays in
+  sync with `src/api/routes.rs`
+- inline comments explain non-obvious coordination and invariants for beginners
+
+## Validation
+
+Required checks:
+
+- `cargo test --quiet`
+- `cargo test large_demo_solves_to_feasible_terminal_state -- --ignored --nocapture`
+- `find static/app -name '*.mjs' -print0 | xargs -0 -n1 node --check`
+- `node --test tests/frontend/*.test.js`
+
+Expected current outcome:
+
+- large demo finishes `0hard`
+- local search performs real post-construction improvement over construction
+- docs, API guide, and config comments describe the same current product shape
+
+## Non-Goals
+
+This pass does not:
+
+- redesign the hospital domain
+- rewrite `solverforge-ui`
+- force every `0.9.0` scalar neighborhood family into the app
+- add benchmark tooling
+- change the planning direction away from `shift -> employee`
+
+## Final Intent
+
+`solverforge-hospital` reads as a clean example of:
+
+- current retained-runtime backend integration
+- current stock `solverforge-ui` shell usage
+- current scalar nearby-selection support in `solverforge 0.9.0`
+
+Nothing in the repo should imply that hospital is pinned to an older release
+line or that unshipped broader scalar neighborhoods are the recommended
+hospital policy.

README.md

@@ -0,0 +1,306 @@
+---
+title: SolverForge Hospital
+emoji: 🏥
+colorFrom: orange
+colorTo: red
+sdk: docker
+app_port: 7860
+pinned: false
+license: apache-2.0
+short_description: SolverForge 0.9.0 hospital scheduling example with deterministic demo data and a retained runtime
+---
+
+# SolverForge Hospital
+
+`solverforge-hospital` is a beginner-friendly example of a real SolverForge app.
+It answers one concrete question:
+
+"Given a hospital workforce and a month of shifts, which employee should cover each shift?"
+
+## Documentation Map
+
+Each top-level document has a different job:
+
+- `README.md`
+  Quick start, concepts, API surface, and the shortest learning path.
+- `WIREFRAME.md`
+  Architecture and request/data flow across backend, runtime, and frontend.
+- `PRD.md`
+  Background/planning notes only. It is not canonical for current behavior.
+- `AGENTS.md`
+  Contribution rules, validation commands, and the documentation standard for future edits.
+- `Makefile`
+  The beginner-friendly command surface for local development, validation, and
+  Docker-based Hugging Face Space preparation.
+
+If you are new to SolverForge, read this repo as three layers:
+
+1. The planning-model manifest and model modules in `src/domain/`
+2. The score rules in `src/constraints/`
+3. The runtime and browser app in `src/api/`, `src/solver/`, and `static/app/`
+
+## What SolverForge Is Doing Here
+
+SolverForge is the optimization engine. In this app:
+
+- `Employee` is a problem fact: input data the solver does not move
+- `Shift` is the planning entity: the thing the solver assigns
+- `Shift.employee_idx` is the planning variable: the actual choice the solver makes
+- the constraints decide whether an assignment is legal and whether it is good
+- `solver.toml` tells the runtime how to search for a better assignment
+
+The app ships one serious demo instance rather than many toy presets:
+
+- fixed random seed
+- fixed 28-day schedule horizon
+- 50 employees
+- 688 shifts
+- 8-hour shifts
+- deterministic generator
+- retained-job runtime with pause, resume, cancel, snapshot, and analysis
+
+## Read The Code In This Order
+
+If you want to learn the codebase, this order is the shortest path:
+
+1. [src/domain/employee.rs](src/domain/employee.rs)
+   `Employee` is the input fact model.
+2. [src/domain/care_hub.rs](src/domain/care_hub.rs)
+   `CareHub` explains how the app models service-line proximity.
+3. [src/domain/mod.rs](src/domain/mod.rs)
+   This is the `planning_model!` manifest that lists and exports the model modules.
+4. [src/domain/plan.rs](src/domain/plan.rs)
+   `Shift`, `Plan`, nearby search meters, and transport normalization live here.
+5. [src/constraints/mod.rs](src/constraints/mod.rs)
+   This lists every scoring rule.
+6. [src/constraints/*.rs](src/constraints)
+   Each file explains one real scheduling rule.
+7. [src/data/data_seed/entrypoints.rs](src/data/data_seed/entrypoints.rs)
+   This shows the public demo-data surface.
+8. [src/data/data_seed/large.rs](src/data/data_seed/large.rs)
+   This assembles the published benchmark instance.
+9. [src/solver/service.rs](src/solver/service.rs)
+   This is the retained-job runtime facade.
+10. [src/api/routes.rs](src/api/routes.rs) and [src/api/sse.rs](src/api/sse.rs)
+   These expose the HTTP and live-event contracts.
+11. [static/app/main.mjs](static/app/main.mjs)
+   This is the browser boot sequence.
+12. [static/app/shell/](static/app/shell) and [static/app/schedule/](static/app/schedule)
+   These adapt stock `solverforge-ui` pieces to the hospital example.
+
+## Project Shape
+
+- `src/domain/`
+  `planning_model!` manifest, planning model, derived fields, nearby meters.
+- `src/constraints/`
+  Hard and soft scoring rules.
+- `src/data/`
+  Deterministic demo-data generator.
+- `src/solver/`
+  Retained-job orchestration over `SolverManager<Plan>`.
+- `src/api/`
+  REST routes, DTOs, and SSE endpoint.
+- `static/app/`
+  Browser code built as plain ES modules on top of `solverforge-ui`.
+- `tests/frontend/`
+  Browserless UI tests using the fake DOM in `tests/support/`.
+
+## Quick Start
+
+This repo depends only on published crates.io releases:
+
+- `solverforge = 0.9.0`
+- `solverforge-ui = 0.6.1`
+
+Run the app:
+
+```sh
+make run-release
+```
+
+Then open `http://localhost:7860`.
+
+If you want to inspect the command surface first:
+
+```sh
+make help
+```
+
+## What You Will See
+
+The browser UI does five things:
+
+1. Loads `static/sf-config.json`
+2. Loads `static/generated/ui-model.json`
+3. Fetches the `LARGE` demo dataset from `/demo-data/LARGE`
+4. Renders two schedule views:
+   `By location` and `By employee`
+5. Starts a retained solving job when you click Solve
+
+The frontend is intentionally thin. It mostly uses stock `solverforge-ui` pieces:
+
+- `SF.createBackend({ type: "axum" })`
+- `SF.createHeader()`
+- `SF.createStatusBar()`
+- `SF.createSolver()`
+- `SF.rail.createTimeline()`
+
+The app also exposes a visible "REST API" guide inside the browser shell. That
+guide is generated from `static/app/shell/api-guide.mjs` and is expected to
+match the routes in `src/api/routes.rs` and the route list below.
+
+## Run Validation
+
+Standard local validation:
+
+```sh
+make test
+```
+
+Space-style local CI simulation:
+
+```sh
+make ci-local
+```
+
+Slow acceptance solve:
+
+```sh
+make test-slow
+```
+
+`make ci-local` is the main pre-push validation path for this repo. It checks
+formatting, runs clippy, builds the release binary, runs the standard Rust and
+frontend test surface, and builds the Docker image that the Space-style deploy
+path expects. There is no hosted GitHub Actions workflow to mirror yet.
+
+## Demo Dataset Intent
+
+The generator is not random filler data. It is designed to publish a problem
+that is:
+
+- hard-feasible
+- deterministic
+- narrow enough that candidate choice matters
+- rich enough that soft-score improvements still exist after construction
+
+The hidden witness roster in `src/data/data_seed/witness.rs` is especially
+important: it gives the generator an internal feasible assignment that is used
+to shape unavailability and preferences, but it is never shown to the solver.
+
+The `LARGE` dataset is built once and cached in memory because it is immutable
+and deterministic. Each request still receives an owned `Plan`, but the server
+does not regenerate the same public benchmark from scratch every time.
+
+## REST API
+
+- `GET /health`
+- `GET /info`
+- `GET /demo-data`
+- `GET /demo-data/{id}`
+- `POST /jobs`
+- `GET /jobs/{id}`
+- `GET /jobs/{id}/status`
+- `GET /jobs/{id}/snapshot`
+- `GET /jobs/{id}/analysis`
+- `POST /jobs/{id}/pause`
+- `POST /jobs/{id}/resume`
+- `POST /jobs/{id}/cancel`
+- `DELETE /jobs/{id}`
+- `GET /jobs/{id}/events`
+
+Lifecycle semantics:
+
+- `pause` requests an exact runtime-managed pause and checkpoint
+- `resume` continues from the retained checkpoint
+- the user-facing Stop control calls `cancel` to stop a live or paused job
+- `delete` removes a terminal retained job before the next fresh solve
+- `GET /jobs/{id}` and `GET /jobs/{id}/status` return the same summary payload
+- `snapshot_revision={n}` is optional on both snapshot and analysis requests
+- reconnects bootstrap from current runtime status plus retained snapshot
+  revision, not from cached SSE text
+
+## Payload Shape
+
+The transport payload mirrors the domain model directly. The important field is
+`employeeIdx`, which is the scalar planning assignment chosen for each shift.
+
+```json
+{
+  "employees": [
+    {
+      "id": "employee-0",
+      "name": "Alex Smith",
+      "homeHub": "critical_care",
+      "skills": ["Critical care doctor"],
+      "unavailableDates": [],
+      "undesiredDates": [],
+      "desiredDates": []
+    }
+  ],
+  "shifts": [
+    {
+      "id": "shift-1",
+      "start": "2024-01-01T08:00:00",
+      "end": "2024-01-01T16:00:00",
+      "location": "Critical care",
+      "careHub": "critical_care",
+      "requiredSkill": "Critical care doctor",
+      "employeeIdx": 0
+    }
+  ],
+  "score": "0hard/0soft"
+}
+```
+
+Telemetry is intentionally a UI-facing projection, not the raw runtime type.
+Fields like `elapsedMs`, `movesPerSecond`, and `acceptanceRate` are derived for
+display.
+
+## Solver Policy
+
+The runtime source of truth is [solver.toml](./solver.toml).
+
+The currently shipped policy is deliberately narrow:
+
+- `construction_heuristic = cheapest_insertion`
+- one local-search phase
+- nearby scalar change/swap selectors
+- `late_acceptance`
+- `accepted_count`
+
+That is not an accident. A candidate sweep against broader scalar phase-2/3
+variants showed that the current nearby baseline remained the best balanced
+policy for this dataset and 30-second budget.
+
+The canonical description of current behavior is `solver.toml`, the code, this
+README, and `WIREFRAME.md`, not `PRD.md`.
+
+## Constraints
+
+Hard constraints:
+
+- Assigned shift
+- Required skill
+- Overlapping shift
+- At least 10 hours between 2 shifts
+- One shift per day
+- Unavailable employee
+
+Soft constraints:
+
+- Undesired day for employee
+- Desired day for employee
+- Balance employee assignments
+
+## Docker
+
+Build from this repository root:
+
+```sh
+make space-build
+make space-run
+```
+
+The Docker image resolves `solverforge` and `solverforge-ui` from crates.io, so
+no extra source checkout is required in the build context.

WIREFRAME.md

@@ -0,0 +1,276 @@
+# solverforge-hospital WIREFRAME
+
+This file is the architectural map for beginners.
+
+If `README.md` tells you how to run the app, this document tells you how the
+pieces fit together and in which order to read them.
+
+## Documentation Roles
+
+The docs in this repo are meant to work together rather than compete:
+
+- `README.md`
+  Quick start, concepts, route list, and user-facing orientation.
+- `WIREFRAME.md`
+  Architecture, execution flow, and file-map walkthrough.
+- `PRD.md`
+  Background/planning notes only. It is not canonical for current behavior.
+- `AGENTS.md`
+  Rules for keeping code, comments, tests, and docs aligned in future changes.
+- `Makefile`
+  The shared developer command surface, including the local Space validation
+  pipeline.
+
+## What This Repo Is Teaching
+
+`solverforge-hospital` is a complete SolverForge example, not just a scoring
+snippet.
+
+It shows how to build a planning app where:
+
+- the domain model is small and explicit
+- the score rules are readable one file at a time
+- the dataset is deterministic and intentionally shaped
+- the solver runs as a retained background job
+- the browser UI watches the solve through REST and SSE
+
+The planning question is:
+
+"For each hospital shift, which employee should be assigned?"
+
+## SolverForge Concepts In Plain Language
+
+- `Employee`
+  Input data. The solver reads it, but does not move it.
+- `Shift`
+  The thing the solver is allowed to assign.
+- `employee_idx`
+  The one real decision variable in this app. It points from a shift to one
+  employee inside `Plan.employees`.
+- hard score
+  Rules that must not be broken, such as missing skills or overlapping shifts.
+- soft score
+  Preferences and quality goals, such as honoring desired days or balancing
+  workload.
+- retained job
+  A solve that keeps living in memory after it starts, so the UI can poll it,
+  pause it, resume it, stop it through runtime cancel, or inspect snapshots.
+  Delete is terminal cleanup before the next fresh Solve, not the Stop action.
+
+## Read Order
+
+If you are new to this repo, read files in this order:
+
+1. `src/domain/employee.rs`
+   Learn the input facts first.
+2. `src/domain/care_hub.rs`
+   Learn the hospital service-line grouping used by nearby search.
+3. `src/domain/mod.rs`
+   See the `planning_model!` manifest that lists and exports the model modules.
+4. `src/domain/plan.rs`
+   Learn the planning entity, planning variable, nearby meters, and derived
+   fields.
+5. `src/constraints/mod.rs`
+   See the full score model at a glance.
+6. `src/constraints/*.rs`
+   Read one scheduling rule per file.
+7. `src/data/data_seed/entrypoints.rs`
+   See the public demo-data surface.
+8. `src/data/data_seed/large.rs`
+   See how the published dataset is assembled.
+9. `src/solver/service.rs`
+   See how a domain solve becomes a retained runtime job.
+10. `src/api/routes.rs` and `src/api/sse.rs`
+   See the HTTP contract.
+11. `static/app/main.mjs`
+    See the browser boot sequence.
+12. `static/app/shell/` and `static/app/schedule/`
+    See how stock `solverforge-ui` components are adapted to this hospital demo.
+
+## Runtime Flow
+
+The shortest way to understand the app is to follow one request all the way
+through:
+
+1. The browser loads `static/index.html`.
+2. `static/app/main.mjs` loads config, the generated UI model, and the `LARGE`
+   demo dataset.
+3. The frontend turns the returned `PlanDto` into schedule rails and side-panel
+   summaries.
+4. When the user clicks Solve, the frontend sends the current plan to
+   `POST /jobs`.
+5. `src/api/routes.rs` converts that HTTP request into a `PlanDto`.
+6. `PlanDto::to_domain()` rebuilds the in-memory `Plan`, including derived
+   helper fields the solver expects.
+7. `SolverService` starts a retained solve through `SolverManager<Plan>`.
+8. The solver emits lifecycle, phase, telemetry, best-solution, and analysis
+   events.
+9. `src/solver/service.rs` converts those runtime events into the JSON event
+   shapes expected by the UI.
+10. The browser consumes those events over `/jobs/{id}/events` and updates the
+    visible status, timeline, and analysis panels.
+
+The browser shell also contains a visible REST API guide. That makes
+`static/app/shell/api-guide.mjs` part of the documentation surface, not just a
+UI helper.
+
+## File Map
+
+```text
+.
+├── Cargo.toml
+│   Rust crate metadata and crates.io dependencies.
+├── solver.toml
+│   Embedded solver policy. This is the runtime source of truth for search.
+├── solverforge.app.toml
+│   App metadata used by the surrounding SolverForge tooling.
+├── Dockerfile
+│   Container build for running the app outside the dev checkout.
+├── Makefile
+│   Local build, validation, and Docker/Space workflow wrapper.
+├── README.md
+│   Beginner run guide, API overview, and learning path.
+├── PRD.md
+│   Background/planning notes; not the source of truth for current behavior.
+├── WIREFRAME.md
+│   This architectural walkthrough.
+├── AGENTS.md
+│   Repo-specific contributor and documentation rules.
+├── src/
+│   ├── lib.rs
+│   │   Crate root and public module surface.
+│   ├── main.rs
+│   │   Axum server bootstrap, CORS, static serving, and route composition.
+│   ├── domain/
+│   │   `planning_model!` manifest plus problem model modules.
+│   ├── constraints/
+│   │   One scheduling rule per file plus the assembler in `mod.rs`.
+│   ├── data/
+│   │   Deterministic demo-data generator and published entrypoints.
+│   ├── solver/
+│   │   Retained-job facade over the SolverForge runtime.
+│   └── api/
+│       DTOs, REST routes, and SSE streaming.
+├── static/
+│   ├── index.html
+│   │   Browser entrypoint.
+│   ├── sf-config.json
+│   │   Runtime UI config for the stock frontend shell.
+│   ├── generated/ui-model.json
+│   │   Generated view metadata used by `solverforge-ui`.
+│   └── app/
+│       ├── main.mjs
+│       │   Browser boot and wiring.
+│       ├── shell/
+│       │   App shell, state, solver controls, and panels.
+│       ├── schedule/
+│       │   Hospital-specific grouping, presentation, and rail rendering.
+│       └── views/registry.mjs
+│           Named view registration.
+└── tests/
+    ├── frontend/
+    │   Browserless frontend tests.
+    └── support/
+        Fake DOM support used by the frontend tests.
+```
+
+## Why The Model Looks This Way
+
+This app is intentionally narrow.
+
+- There is one planning entity type: `Shift`.
+- There is one scalar planning variable: `employee_idx`.
+- Nearby search is attached directly to that scalar variable.
+- The solver does not juggle multiple variable types, chained assignments, or
+  list planning.
+
+That makes the example easier to learn because the optimization problem stays
+visible:
+
+- facts live in `Plan.employees`
+- decisions live in `Plan.shifts[*].employee_idx`
+- score rules read those two things and judge the assignment
+
+## Why The Demo Data Is Structured
+
+The demo-data generator is not filler.
+
+It is designed to give beginners a problem that is:
+
+- deterministic
+- feasible
+- interesting enough that local search still has work to do
+- stable enough that tests and comparisons stay meaningful
+
+One important design trick is the hidden witness roster in
+`src/data/data_seed/witness.rs`.
+
+That internal roster gives the generator a known feasible staffing pattern.
+The published dataset is then shaped around that witness, while the solver only
+sees the final public problem. This lets the repo ship a realistic-feeling
+demo without random feasibility failures.
+
+## Why The Runtime Uses REST And SSE
+
+The solve is long-lived compared with a normal request/response handler, so the
+backend splits the contract into two parts:
+
+- REST for control and snapshots
+- SSE for live progress
+
+That separation keeps the frontend simple:
+
+- create a job
+- poll or fetch details when needed
+- subscribe once to the live event stream
+
+It also mirrors how a real retained SolverForge app behaves in production.
+
+One small but important detail: `GET /jobs/{id}` and `GET /jobs/{id}/status`
+return the same summary payload. The second route exists as a stock-compatible
+alias for clients that expect the explicit `/status` URL shape.
+
+## Solver Policy
+
+`solver.toml` is embedded by `Plan` and is therefore part of the actual model,
+not a side document.
+
+The shipped search policy is deliberately conservative:
+
+- `cheapest_insertion` builds a feasible first assignment
+- local search stays in the nearby scalar neighborhood
+- `late_acceptance` and `accepted_count` keep the search moving without blowing
+  up step cost
+
+That narrow configuration is intentional for this demo. It is the balanced
+30-second policy that currently performs best on the hospital dataset.
+
+## Frontend Design
+
+The frontend is intentionally thin.
+
+This repo is not trying to teach a custom framework. It is showing how to take
+stock `solverforge-ui` pieces and adapt them to one concrete planning problem.
+
+- `shell/` owns app lifecycle, backend wiring, and side panels
+- `schedule/` owns the hospital-specific transformation from domain data to
+  visual rails
+- tests in `tests/frontend/` lock that presentation behavior down without a
+  full browser
+
+## Validation Surfaces
+
+When you change this repo, think in four separate layers:
+
+1. Domain and constraint logic:
+   `make test-rust`
+2. Slow end-to-end solve quality:
+   `make test-slow`
+3. Frontend module correctness:
+   `make test-frontend-syntax`
+4. Frontend behavior:
+   `make test-frontend`
+5. Local deploy readiness for the Docker-based Space target:
+   `make ci-local`
+
+If you keep those five layers green, the repo remains teachable and usable.