docs: document deliveries tutorial and Space workflow

Document the current deliveries tutorial surface end to end. The README now includes Hugging Face Space front matter, the dependency and Rust-version line, the SolverForge domain concepts, the validation commands, Space build/run commands, the code reading order, REST routes, routing modes, solver policy, and the current ten-vehicle demo dataset sizes.

Add AGENTS.md as the repo-local editing contract. It records the canonical Plan naming, file-size rule, no-suppression policy, Makefile workflow, documentation alignment requirements, road-network test gating, published dependency policy, and retained-job runtime notes.

Add WIREFRAME.md as the architecture map for future work. It explains the runtime flow from browser boot through demo data, preparation, retained solving, SSE, snapshots, route geometry, and frontend rendering; it also maps the files by responsibility and describes the domain, route-metrics, API, frontend, and validation surfaces.

This is a documentation-only boundary. Reverting it leaves the app, tests, and Space tooling intact while removing the tutorial prose and contributor guidance.

AGENTS.md

@@ -0,0 +1,92 @@
+# Repository Guidelines
+
+## Project Structure And Naming
+
+This repo follows the current `solverforge-cli` app shape. The app package
+version is `1.0.0`, and the release binary is `solverforge_deliveries`.
+
+- `src/domain/mod.rs` owns the `solverforge::planning_model!` manifest.
+- `src/domain/plan.rs` owns the `Plan` planning solution.
+- `src/domain/delivery.rs` owns the `Delivery` problem fact.
+- `src/domain/vehicle.rs` owns the `Vehicle` planning entity and its
+  `delivery_order` list variable.
+- `src/domain/preview.rs` owns transport/view preview structs.
+- `src/domain/route_metrics/` owns route preparation, CVRP hooks, scoring
+  preview, route geometry, and insertion ranking.
+- `src/constraints/` owns one score rule per file plus `mod.rs` assembly.
+- `src/data/data_seed/` owns deterministic city demo-data modules with grouped
+  visit files for scaled delivery counts.
+- `src/api/` owns REST, DTO, and SSE surfaces.
+- `src/solver/` owns retained-job runtime orchestration.
+- `static/app/models/` owns frontend plan modeling.
+- `static/app/ui/` owns browser layout and rendering helpers.
+
+Keep the canonical solution name `Plan`. Do not reintroduce `DeliveryPlan` or
+`delivery_plan.rs`.
+
+## File Size Rule
+
+No source, test, frontend, config, or repo documentation file should reach 300
+lines. Split by responsibility before that point. Large generated/cache output
+under `target/` and `.osm_cache/` is outside this rule.
+
+## Build And Validation Commands
+
+- `make help` shows the supported command surface.
+- `make run-release` runs the app locally on `:7860`.
+- `make test` runs Rust, frontend, and Playwright browser tests.
+- `make test-e2e` runs the real browser Playwright smoke.
+- `make space-build` builds the Docker image used by Hugging Face Spaces.
+- `make space-run` builds and runs that image locally.
+- `make ci-local` runs formatting, clippy, release build, standard tests, and
+  the Space Docker image build.
+- `make test-live-road` runs the env-enabled road-network smoke test.
+- `make pre-release` runs `ci-local` and the live road-network smoke.
+- `cargo test` runs Rust unit and integration tests.
+- `node --test tests/frontend_models.test.mjs` runs frontend model tests.
+
+Use the Makefile as the authoritative local workflow, matching the
+`solverforge-hospital` Space/Docker validation standard.
+
+## No Suppression Policy
+
+Do not add warning suppressions, fallback compatibility branches, or unused
+helper modules. If a split creates unused code, restructure the modules so each
+compiled item is used by its crate.
+
+## Documentation Policy
+
+Keep `Cargo.toml`, `Cargo.lock`, `Makefile`, `Dockerfile`, `README.md`,
+`WIREFRAME.md`, `AGENTS.md`, `solverforge.app.toml`, `solver.toml`,
+`static/sf-config.json`, and the visible API guide in
+`static/app/ui/api-guide.mjs` aligned.
+
+When changing routes, solver policy, demo IDs, dependency sources, file layout,
+or browser behavior, update the docs in the same patch. Prefer current-state
+documentation over planning language.
+
+## Testing Guidance
+
+Add Rust unit tests next to the behavior they protect. Add API integration
+coverage under `tests/api_contract/` and shared integration helpers under
+`tests/support/` only when every helper is used by the single
+`tests/api_contract.rs` crate. Add frontend model tests in
+`tests/frontend_models.test.mjs`, and browser-flow tests in `tests/e2e/`.
+
+Road-network tests should stay env-gated unless the test uses only cached or
+straight-line behavior. Use `SOLVERFORGE_RUN_LIVE_TESTS=1` through
+`make test-live-road` when validating live map/routing paths.
+
+## Runtime Notes
+
+`solver.toml` is embedded by `Plan` through the planning-solution macro. Treat
+it as the solver policy source of truth.
+
+`Cargo.toml` currently uses Rust `1.95` and published crates.io dependencies
+only. Keep every direct dependency declaration at the latest published version,
+and keep `solverforge.app.toml`, `Cargo.lock`, and docs truthful if those
+dependency sources or versions change.
+
+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.

README.md

@@ -0,0 +1,250 @@
+---
+title: SolverForge Deliveries
+emoji: 🚚
+colorFrom: green
+colorTo: blue
+sdk: docker
+app_port: 7860
+pinned: false
+license: apache-2.0
+short_description: SolverForge delivery-route optimization example
+---
+
+# SolverForge Deliveries
+
+`solverforge-deliveries` is a SolverForge vehicle-routing example with retained
+jobs, route geometry, insertion recommendations, and a browser plan viewer.
+
+It answers one concrete question:
+
+"Given depots, vehicles, delivery stops, capacities, and time windows, which
+vehicle should visit each delivery and in what order?"
+
+## Documentation Map
+
+- `README.md`
+  Quick start, concepts, API surface, and the shortest learning path.
+- `WIREFRAME.md`
+  Architecture and request/data flow across backend, runtime, maps, and UI.
+- `AGENTS.md`
+  Repo-specific contribution, validation, and documentation rules.
+- `Makefile`
+  The supported local command surface for development, validation, and
+  Docker-based Hugging Face Space preparation.
+- `Dockerfile`
+  The Docker Space image build, using Rust 1.95 and published crates.io
+  dependencies.
+
+## Current Dependency Shape
+
+The app package version is `1.0.0`; the release binary is
+`solverforge_deliveries`.
+
+This repo requires Rust `1.95` and is configured against published crates.io
+dependencies. Direct dependency declarations use the latest published versions
+checked for this repo:
+
+- `solverforge` `0.9.1`
+- `solverforge-ui` `0.6.3`
+- `solverforge-maps` `2.1.3`
+- `axum` `0.8.9`
+- `tokio` `1.52.1`
+- `tokio-stream` `0.1.18`
+- `tower-http` `0.6.8`
+- `tower` `0.5.3`
+- `serde` `1.0.228`
+- `serde_json` `1.0.149`
+- `rand` `0.10.1`
+- `uuid` `1.23.1`
+- `parking_lot` `0.12.5`
+- `http-body-util` `0.1.3`
+
+The app metadata in `solverforge.app.toml` mirrors that published dependency
+shape and records `solverforge-cli` `2.0.0` as the current scaffold metadata
+line.
+
+## What SolverForge Is Doing Here
+
+- `Delivery` is a problem fact: a stop the solver must place in a route.
+- `Vehicle` is a planning entity: each vehicle owns one mutable route.
+- `Vehicle.delivery_order` is the list planning variable.
+- `Plan` is the planning solution, matching the current `solverforge-cli`
+  default solution name and `src/domain/plan.rs` file shape.
+- Constraints score assignment coverage, capacity, time-window violations, and
+  total travel time.
+- `solver.toml` selects list construction heuristics and local-search moves.
+
+The app ships three city datasets:
+
+- `PHILADELPHIA` (default)
+- `HARTFORD`
+- `FIRENZE`
+
+Each dataset has ten vehicles: 82 Philadelphia deliveries, 50 Hartford
+deliveries, and 80 Firenze deliveries. Philadelphia is the default road-network
+baseline, and all current seed data has enough aggregate vehicle capacity and
+reachable street-front coordinates for the configured delivery stops.
+
+## Quick Start
+
+```sh
+make run-release
+```
+
+Then open `http://localhost:7860`.
+
+To inspect the command surface:
+
+```sh
+make help
+```
+
+## Validation
+
+Standard validation:
+
+```sh
+make test
+```
+
+Full local validation:
+
+```sh
+make ci-local
+```
+
+Space image validation:
+
+```sh
+make space-build
+```
+
+Live road-network smoke:
+
+```sh
+make test-live-road
+```
+
+`make test` includes Rust tests, browserless frontend tests, and Playwright
+browser tests. `make ci-local` adds the Docker image build used by the Hugging
+Face Space. `make pre-release` runs `make ci-local` and then the live
+road-network smoke test. The live road test may touch the local `.osm_cache/`
+through `solverforge-maps`; that cache is ignored by git and by Docker builds.
+
+## Hugging Face Space Deployment
+
+This repo is Docker-Space ready. The Space reads the README front matter,
+builds `Dockerfile`, and expects the app to bind `PORT=7860`.
+
+Local Space-equivalent commands:
+
+```sh
+make space-build
+make space-run
+```
+
+## Read The Code In This Order
+
+1. `src/domain/mod.rs`
+   The `planning_model!` manifest and public domain exports.
+2. `src/domain/plan.rs`
+   The `Plan` solution and list-variable shadow-refresh wiring.
+3. `src/domain/delivery.rs` and `src/domain/vehicle.rs`
+   The fact and planning-entity models.
+4. `src/domain/route_metrics/`
+   Route preparation, CVRP hooks, scoring preview, route geometry, and insertion
+   ranking.
+5. `src/constraints/mod.rs`
+   The constraint-set assembly point.
+6. `src/constraints/*.rs`
+   One scoring rule per file.
+7. `src/data/data_seed/entrypoints.rs`
+   Public demo-data IDs and generator dispatch.
+8. `src/data/data_seed/{philadelphia,hartford,firenze}/`
+   City depots and delivery coordinates.
+9. `src/solver/service.rs`
+   Retained-job orchestration over `SolverManager<Plan>`.
+10. `src/api/routes.rs`, `src/api/dto.rs`, and `src/api/sse.rs`
+    REST, DTO, and event-stream contracts.
+11. `static/app/main.mjs`
+    Browser controller.
+12. `static/app/models/` and `static/app/ui/`
+    Frontend plan normalization, preview modeling, layout, maps, tables, and
+    modals.
+
+## Project Shape
+
+- `src/domain/`
+  Planning model, domain types, route metrics, and test-only model checks.
+- `src/constraints/`
+  Incremental SolverForge scoring rules.
+- `src/data/`
+  Deterministic city demo-data generator.
+- `src/solver/`
+  Retained-job facade and runtime event payload formatting.
+- `src/api/`
+  Axum routes, DTOs, and SSE endpoint.
+- `static/app/`
+  Browser modules built on stock `solverforge-ui` assets.
+- `Dockerfile`
+  Multi-stage Rust 1.95 Alpine build for the Hugging Face Docker Space.
+- `tests/api_contract/`
+  Integration tests for catalog, jobs, lifecycle, SSE, and road-network smoke.
+- `tests/frontend_models.test.mjs`
+  Browserless frontend model tests.
+- `tests/e2e/`
+  Playwright tests for the served browser app, including asset loading, dataset
+  switching, route highlighting, and retained solve start/stop.
+
+## 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`
+- `GET /jobs/{id}/routes`
+- `POST /jobs/{id}/pause`
+- `POST /jobs/{id}/resume`
+- `POST /jobs/{id}/cancel`
+- `DELETE /jobs/{id}`
+- `GET /jobs/{id}/events`
+- `POST /recommendations/delivery-insertions`
+
+Lifecycle semantics:
+
+- `pause` requests a runtime-managed pause and checkpoint.
+- `resume` continues from the retained checkpoint.
+- `cancel` stops a live or paused job.
+- `delete` removes a terminal retained job before the next fresh solve.
+- `snapshot_revision={n}` is optional for snapshots, analysis, and routes.
+- SSE reconnects bootstrap from the retained runtime status/event state.
+
+## Routing Modes
+
+`road_network` is the default and uses `solverforge-maps` to fetch or load a
+road graph for the current plan bounds. `straight_line` is available as a fast
+draft/testing mode. Route geometry is returned by `/jobs/{id}/routes` and drawn
+in the browser map only when it matches the active snapshot and routing mode.
+The route list can highlight one vehicle route while dimming the rest of the
+map geometry without changing the user's current map viewport.
+
+## Solver Policy
+
+`solver.toml` is embedded by `Plan` and is the runtime source of truth:
+
+- `list_clarke_wright` builds delivery routes.
+- `list_k_opt` improves construction output before local search.
+- local search combines nearby list change/swap, reverse, k-opt, ruin, and
+  limited sublist moves.
+- `late_acceptance` and `accepted_count` control acceptance and retained
+  candidates.
+
+The city seeds have coherent capacity and reachable road-network coordinates so
+local search can reach feasible `0hard` road-network solutions. Current seed
+sizes are 82 Philadelphia deliveries, 50 Hartford deliveries, and 80 Firenze
+deliveries, each with ten vehicles.

WIREFRAME.md

@@ -0,0 +1,229 @@
+# solverforge-deliveries WIREFRAME
+
+This file is the architectural map for the deliveries example.
+
+`README.md` explains how to run and use the app. This document explains how the
+pieces fit together and where each responsibility lives.
+
+## Documentation Roles
+
+- `README.md`
+  Quick start, dependency shape, route list, and user-facing orientation.
+- `WIREFRAME.md`
+  Architecture, execution flow, and file-map walkthrough.
+- `AGENTS.md`
+  Repo-specific contribution, validation, and documentation rules.
+- `Makefile`
+  Local development, validation, and Space/Docker command surface.
+- `Dockerfile`
+  Hugging Face Docker Space image definition.
+
+## What This Repo Is Teaching
+
+This repo is a complete `solverforge-deliveries` `1.0.0` list-variable
+SolverForge app for delivery routing.
+
+It shows how to combine:
+
+- a `Plan` solution with a list planning variable
+- route-specific score rules
+- SolverForge CVRP construction and local-search hooks
+- `solverforge-maps` road-network preparation and route geometry
+- retained jobs with snapshots, analysis, cancel, pause, resume, and SSE
+- a browser plan viewer built on stock `solverforge-ui` assets
+
+## SolverForge Concepts In Plain Language
+
+- `Delivery`
+  Input stop data. The solver assigns delivery IDs into vehicle routes.
+- `Vehicle`
+  Planning entity. Each vehicle owns one ordered `delivery_order` list.
+- `Plan`
+  Planning solution. It holds deliveries, vehicles, score, routing mode, view
+  state, and prepared routing data.
+- hard score
+  Missing assignments, capacity overage, late delivery seconds, and unreachable
+  route legs.
+- soft score
+  Total travel seconds.
+- retained job
+  A solve that lives in memory so the UI can stream events, fetch snapshots,
+  pause/resume, cancel, analyze, and delete terminal jobs.
+
+## Runtime Flow
+
+1. The browser loads `static/index.html`.
+2. `static/app/main.mjs` loads `static/sf-config.json`.
+3. The app fetches `/demo-data/PHILADELPHIA`.
+4. `PlanDto::from_plan()` serializes a refreshed transport plan with preview
+   state.
+5. The browser normalizes the plan, renders summary cards, tables, timelines,
+   and a map.
+6. When the user clicks Solve, the browser sends the current plan to
+   `POST /jobs`.
+7. `src/api/routes.rs` deserializes the `PlanDto`, rebuilds a `Plan`, and calls
+   `prepare_plan()`.
+8. `prepare_plan()` builds straight-line or road-network matrices and attaches
+   `PreparedVehicleRouting` to each vehicle.
+9. `SolverService` starts a retained solve through `SolverManager<Plan>`.
+10. Solver events are converted by `src/solver/service/runtime_payload.rs` into
+    UI-facing JSON.
+11. The browser consumes `/jobs/{id}/events` and fetches snapshots, analysis,
+    and route geometry for exact snapshot revisions.
+
+## File Map
+
+```text
+.
+├── Cargo.toml
+│   Rust 1.95 crate metadata for app version 1.0.0 and latest published
+│   crates.io dependencies.
+├── solver.toml
+│   Embedded search policy for construction heuristics and local search.
+├── solverforge.app.toml
+│   App metadata, demo IDs, model facts/entities, crates.io dependency sources,
+│   and the `solverforge 0.9.1` runtime target.
+├── Makefile
+│   Hospital-style local build, validation, and Space/Docker commands.
+├── Dockerfile
+│   Multi-stage Rust 1.95 Docker image for Hugging Face Spaces.
+├── .dockerignore
+│   Keeps build artifacts, git metadata, route cache, and Playwright output out
+│   of the Docker context.
+├── README.md
+│   Run guide, dependency shape, API list, and learning path.
+├── AGENTS.md
+│   Repo-specific rules for future edits.
+├── WIREFRAME.md
+│   This architectural walkthrough.
+├── src/
+│   ├── domain/
+│   │   `planning_model!` manifest, `Plan`, entities, facts, preview structs,
+│   │   and route metrics.
+│   ├── constraints/
+│   │   Assignment, capacity, time-window, and travel-time score rules.
+│   ├── data/
+│   │   Deterministic city seed data and generator entrypoints.
+│   ├── solver/
+│   │   Retained-job service and runtime event payload formatting.
+│   └── api/
+│       Axum routes, DTOs, and SSE endpoint.
+├── static/
+│   ├── index.html
+│   ├── sf-config.json
+│   ├── generated/ui-model.json
+│   └── app/
+│       Browser controller, plan models, and UI renderers.
+└── tests/
+    ├── api_contract.rs
+    │   Single integration-test crate composed from `tests/api_contract/*.rs`.
+    ├── api_contract/
+    │   Catalog, job, lifecycle, SSE, and live-road modules.
+    ├── support/
+    │   Shared integration-test helpers used by that single crate.
+    ├── e2e/
+    │   Playwright browser tests for the served app.
+    └── frontend_models.test.mjs
+        Frontend model tests.
+```
+
+## Domain And Route Metrics
+
+`src/domain/plan.rs` stays small and macro-facing. It owns the `Plan` struct,
+normalization, list shadow refresh, transport refresh, and the
+`VrpSolution` implementation.
+
+Route-specific behavior lives under `src/domain/route_metrics/`:
+
+- `preparation.rs`
+  Builds matrices and per-vehicle prepared routing data.
+- `cvrp_hooks.rs`
+  Supplies Clarke-Wright, k-opt, load, capacity, and route replacement hooks.
+- `metrics.rs`
+  Computes per-vehicle route metrics.
+- `scoring.rs`
+  Builds preview DTOs and aggregate hard/soft score components.
+- `routes.rs`
+  Builds straight-line or encoded road-network route geometry snapshots.
+- `insertions.rs`
+  Ranks candidate insertion positions for one delivery.
+- `types.rs`
+  Shared route metrics, snapshots, candidates, and routing trait types.
+
+This split keeps the public domain API stable while avoiding oversized files.
+
+## Demo Data
+
+`src/data/data_seed/entrypoints.rs` exposes three demo IDs:
+
+- `PHILADELPHIA`
+- `HARTFORD`
+- `FIRENZE`
+
+Each city has a small module with separate depot and grouped visit files. The
+generator is deterministic. Every demo has ten vehicle depots, enough scaled
+deliveries for those vehicles, reachable road-network coordinates, and enough
+aggregate capacity before route ordering.
+
+## API And Retained Runtime
+
+The REST API handles job control and snapshot reads:
+
+- `/jobs` creates a retained solver job.
+- `/jobs/{id}` and `/jobs/{id}/status` expose summary state.
+- `/jobs/{id}/snapshot` returns an exact or latest snapshot.
+- `/jobs/{id}/analysis` runs constraint analysis for a snapshot.
+- `/jobs/{id}/routes` returns route geometry for a snapshot.
+- `/jobs/{id}/events` streams typed lifecycle events.
+
+The insertion endpoint, `/recommendations/delivery-insertions`, is app-specific.
+It prepares the submitted plan, removes the requested delivery from any
+existing route, evaluates candidate insert positions, and returns preview plans.
+
+## Frontend Layout
+
+`static/app/main.mjs` is the controller. It owns current plan state, retained
+job state, route identity tracking, and event handlers.
+
+Supporting modules are split by responsibility:
+
+- `static/app/models/core.mjs`
+  Clone and normalize incoming plans.
+- `static/app/models/preview.mjs`
+  Draft straight-line preview scoring.
+- `static/app/models/timeline.mjs`
+  Vehicle and delivery rail models.
+- `static/app/models/formatters.mjs`
+  Labels, icons, tones, clocks, and durations.
+- `static/app/ui/layout.mjs`
+  Page shell and stock SolverForge UI component composition.
+- `static/app/ui/overview.mjs`
+  Summary, route list, non-panning route highlighting, map, and timeline
+  rendering.
+- `static/app/ui/data-tables.mjs`
+  Read-only vehicle and delivery tables with delivery insertion recommendations.
+- `static/app/ui/modals.mjs`
+  Analysis and insertion recommendation bodies.
+- `static/app/ui/api-guide.mjs`
+  Visible API guide content.
+- `static/app/ui/lifecycle.mjs`
+  Dataset markers and route-identity helpers.
+
+## Validation Surfaces
+
+Use the Makefile as the repo-local workflow:
+
+- `make fmt-check`
+- `make clippy`
+- `make build-release`
+- `make test`
+- `make test-e2e`
+- `make space-build`
+- `make test-live-road`
+- `make ci-local`
+- `make pre-release`
+
+`make ci-local` includes the Docker image build used by the Hugging Face Space.
+
+The file-size rule is part of the architecture: keep files below 300 lines and
+split by responsibility before they become broad catch-all modules.