feat(deploy): make fsr Docker Space ready

Add a self-contained multi-stage Docker build for the field-service routing app.
The image builds the release binary from the repository root, copies the static
workspace and SolverForge configuration into the runtime image, exposes the
Space port, and starts solverforge_fsr directly.

Add a Makefile command surface for local development, validation, Docker image
builds, and Hugging Face Space-equivalent checks. The ci-local and pre-release
targets make the deployment contract explicit by running formatting, clippy,
release build, tests, frontend syntax validation, and the Space image build.

Update the README with Hugging Face Docker Space metadata, current runtime and
frontend dependency versions, quick-start commands, project structure, API
surface, and validation instructions. Ignore Playwright/test output and exclude
build-only artifacts from the Docker context so clean Space builds stay focused
on committed source and registry dependencies.

.dockerignore

@@ -0,0 +1,9 @@
+target/
+.git/
+.osm_cache/
+test-results/
+playwright-report/
+*.rs.bk
+/app-session-*.js
+/comment-preload.js
+/main-*.js

.gitignore

@@ -1,6 +1,8 @@
 /target
 .osm_cache/
 **/*.rs.bk
+test-results/
+playwright-report/
 /app-session-*.js
 /comment-preload.js
 /main-*.js

Dockerfile

@@ -0,0 +1,36 @@
+# Multi-stage build for solverforge-fsr.
+#
+# The app depends on published crates.io packages, so the repository root is the
+# complete Docker build context:
+#   docker build -f Dockerfile -t solverforge-fsr .
+
+FROM rust:1.95-alpine AS builder
+
+RUN apk add --no-cache musl-dev
+
+WORKDIR /build
+
+COPY Cargo.toml Cargo.lock ./
+COPY src/ ./src/
+COPY static/ ./static/
+COPY solver.toml ./solver.toml
+COPY solverforge.app.toml ./solverforge.app.toml
+
+RUN cargo build --release --target x86_64-unknown-linux-musl
+
+FROM alpine:latest
+
+RUN apk add --no-cache ca-certificates
+
+WORKDIR /app
+
+COPY --from=builder /build/target/x86_64-unknown-linux-musl/release/solverforge_fsr ./solverforge_fsr
+COPY --from=builder /build/static/ ./static/
+COPY --from=builder /build/solver.toml ./solver.toml
+COPY --from=builder /build/solverforge.app.toml ./solverforge.app.toml
+
+ENV PORT=7860
+
+EXPOSE 7860
+
+CMD ["./solverforge_fsr"]

Makefile

@@ -0,0 +1,184 @@
+# SolverForge FSR Makefile v0.1.0
+# Rust + frontend syntax + Space-oriented local build system.
+
+GREEN := \033[92m
+CYAN := \033[96m
+YELLOW := \033[93m
+RED := \033[91m
+GRAY := \033[90m
+BOLD := \033[1m
+RESET := \033[0m
+
+CHECK := OK
+CROSS := FAIL
+ARROW := =>
+PROGRESS := ..
+
+APP_NAME := solverforge_fsr
+PACKAGE_NAME := solverforge-fsr
+VERSION := $(shell sed -n 's/^version = "\(.*\)"/\1/p' Cargo.toml | head -n1)
+RUST_VERSION := 1.95+
+PORT ?= 7860
+DOCKER_IMAGE ?= $(PACKAGE_NAME)
+DOCKER_CONTEXT ?= .
+DOCKERFILE_PATH := Dockerfile
+
+.PHONY: help doctor build build-release run run-release test test-rust \
+        test-frontend-syntax lint fmt fmt-check clippy check ci-local \
+        space-ci space-build space-run docker-build docker-run pre-release \
+        version clean watch require-node require-docker
+
+.DEFAULT_GOAL := help
+
+require-node:
+	@command -v node >/dev/null 2>&1 || (printf "$(RED)$(CROSS) node is required for frontend validation$(RESET)\n" && exit 1)
+
+require-docker:
+	@command -v docker >/dev/null 2>&1 || (printf "$(RED)$(CROSS) docker is required for Space/Docker targets$(RESET)\n" && exit 1)
+
+doctor:
+	@printf "$(CYAN)$(BOLD)Environment Check$(RESET)\n\n"
+	@missing=0; \
+	if command -v cargo >/dev/null 2>&1; then \
+		printf "$(GREEN)$(CHECK) cargo: $$(cargo --version)$(RESET)\n"; \
+	else \
+		printf "$(RED)$(CROSS) cargo not found$(RESET)\n"; missing=1; \
+	fi; \
+	if command -v rustc >/dev/null 2>&1; then \
+		printf "$(GREEN)$(CHECK) rustc: $$(rustc --version)$(RESET)\n"; \
+	else \
+		printf "$(RED)$(CROSS) rustc not found$(RESET)\n"; missing=1; \
+	fi; \
+	if command -v node >/dev/null 2>&1; then \
+		printf "$(GREEN)$(CHECK) node: $$(node --version)$(RESET)\n"; \
+	else \
+		printf "$(YELLOW)! node not found; frontend syntax validation will be unavailable$(RESET)\n"; \
+	fi; \
+	if command -v docker >/dev/null 2>&1; then \
+		printf "$(GREEN)$(CHECK) docker: $$(docker --version)$(RESET)\n"; \
+	else \
+		printf "$(YELLOW)! docker not found; Space/Docker targets will be unavailable$(RESET)\n"; \
+	fi; \
+	printf "$(GRAY)Docker build context: $(DOCKER_CONTEXT)$(RESET)\n"; \
+	printf "$(GRAY)Default app port: $(PORT)$(RESET)\n"; \
+	if [ $$missing -ne 0 ]; then exit 1; fi
+
+build:
+	@printf "$(ARROW) Building $(PACKAGE_NAME)...\n"
+	@cargo build --bin $(APP_NAME)
+
+build-release:
+	@printf "$(ARROW) Building release binary...\n"
+	@cargo build --release --bin $(APP_NAME)
+
+run:
+	@printf "$(ARROW) Running $(PACKAGE_NAME) on port $(PORT)...\n"
+	@PORT=$(PORT) cargo run --bin $(APP_NAME)
+
+run-release:
+	@printf "$(ARROW) Running release build on port $(PORT)...\n"
+	@PORT=$(PORT) cargo run --release --bin $(APP_NAME)
+
+test: test-rust test-frontend-syntax
+	@printf "\n$(GREEN)$(BOLD)$(CHECK) Standard validation passed$(RESET)\n\n"
+
+test-rust:
+	@printf "$(PROGRESS) Running cargo test --quiet...\n"
+	@cargo test --quiet
+
+test-frontend-syntax: require-node
+	@printf "$(PROGRESS) Checking frontend module syntax...\n"
+	@find static -name '*.js' -print0 | xargs -0 -n1 node --check
+
+fmt:
+	@printf "$(PROGRESS) Formatting Rust code...\n"
+	@cargo fmt
+
+fmt-check:
+	@printf "$(PROGRESS) Checking Rust formatting...\n"
+	@cargo fmt --check
+
+clippy:
+	@printf "$(PROGRESS) Running clippy...\n"
+	@cargo clippy --all-targets -- -D warnings
+
+lint: fmt-check clippy test-frontend-syntax
+	@printf "\n$(GREEN)$(BOLD)$(CHECK) Lint checks passed$(RESET)\n\n"
+
+check: lint test
+
+docker-build: require-docker
+	@printf "$(PROGRESS) Building Docker image $(DOCKER_IMAGE)...\n"
+	@docker build -f "$(DOCKERFILE_PATH)" -t "$(DOCKER_IMAGE)" "$(DOCKER_CONTEXT)"
+
+docker-run: require-docker
+	@printf "$(ARROW) Running $(DOCKER_IMAGE) on port $(PORT)...\n"
+	@docker run --rm -it -e PORT=$(PORT) -p $(PORT):$(PORT) "$(DOCKER_IMAGE)"
+
+space-build: docker-build
+
+space-run: space-build
+	@printf "$(GREEN)$(CHECK) Starting local container that mirrors the Space image$(RESET)\n"
+	@$(MAKE) docker-run --no-print-directory PORT=$(PORT) DOCKER_IMAGE=$(DOCKER_IMAGE)
+
+space-ci: ci-local
+
+ci-local:
+	@printf "$(CYAN)$(BOLD)Local Space Validation Pipeline$(RESET)\n\n"
+	@printf "$(PROGRESS) Step 1/5: Format check...\n"
+	@$(MAKE) fmt-check --no-print-directory
+	@printf "$(PROGRESS) Step 2/5: Clippy...\n"
+	@$(MAKE) clippy --no-print-directory
+	@printf "$(PROGRESS) Step 3/5: Release build...\n"
+	@$(MAKE) build-release --no-print-directory
+	@printf "$(PROGRESS) Step 4/5: Standard test surface...\n"
+	@$(MAKE) test --no-print-directory
+	@printf "$(PROGRESS) Step 5/5: Docker/Space image build...\n"
+	@$(MAKE) space-build --no-print-directory
+	@printf "\n$(GREEN)$(BOLD)$(CHECK) LOCAL SPACE VALIDATION PASSED$(RESET)\n\n"
+
+pre-release: ci-local
+	@printf "$(GREEN)$(BOLD)$(CHECK) Ready for Hugging Face Space update$(RESET)\n\n"
+
+version:
+	@printf "$(CYAN)Current version:$(RESET) $(YELLOW)$(BOLD)$(VERSION)$(RESET)\n"
+	@printf "$(CYAN)Default port:$(RESET) $(YELLOW)$(BOLD)$(PORT)$(RESET)\n"
+
+clean:
+	@printf "$(ARROW) Cleaning build artifacts...\n"
+	@cargo clean
+
+watch:
+	@printf "$(ARROW) Watching and rerunning the app on port $(PORT)...\n"
+	@cargo watch --version >/dev/null 2>&1 || \
+		(printf "$(RED)$(CROSS) cargo-watch is required for make watch$(RESET)\n" && exit 1)
+	@PORT=$(PORT) cargo watch -x "run --bin $(APP_NAME)"
+
+help:
+	@/bin/echo -e "$(CYAN)$(BOLD)Build & Run:$(RESET)"
+	@/bin/echo -e "  $(GREEN)make build$(RESET)          - Build the app in debug mode"
+	@/bin/echo -e "  $(GREEN)make build-release$(RESET)  - Build the app in release mode"
+	@/bin/echo -e "  $(GREEN)make run$(RESET)            - Run locally on port $(PORT)"
+	@/bin/echo -e "  $(GREEN)make run-release$(RESET)    - Run the release build on port $(PORT)"
+	@/bin/echo -e ""
+	@/bin/echo -e "$(CYAN)$(BOLD)Tests & Validation:$(RESET)"
+	@/bin/echo -e "  $(GREEN)make test$(RESET)           - Run Rust tests and frontend syntax checks"
+	@/bin/echo -e "  $(GREEN)make lint$(RESET)           - Run fmt-check, clippy, and frontend syntax checks"
+	@/bin/echo -e "  $(GREEN)make ci-local$(RESET)       - Run local Space validation pipeline"
+	@/bin/echo -e "  $(GREEN)make pre-release$(RESET)    - Run all local Space readiness checks"
+	@/bin/echo -e ""
+	@/bin/echo -e "$(CYAN)$(BOLD)Space & Docker:$(RESET)"
+	@/bin/echo -e "  $(GREEN)make space-build$(RESET)    - Build the Docker image used for Space deployment"
+	@/bin/echo -e "  $(GREEN)make space-run$(RESET)      - Build and run that image locally on port $(PORT)"
+	@/bin/echo -e "  $(GREEN)make docker-build$(RESET)   - Build the Docker image directly"
+	@/bin/echo -e "  $(GREEN)make docker-run$(RESET)     - Run the Docker image directly"
+	@/bin/echo -e ""
+	@/bin/echo -e "$(CYAN)$(BOLD)Other:$(RESET)"
+	@/bin/echo -e "  $(GREEN)make doctor$(RESET)         - Check local cargo/rustc/node readiness"
+	@/bin/echo -e "  $(GREEN)make fmt$(RESET)            - Format Rust code"
+	@/bin/echo -e "  $(GREEN)make version$(RESET)        - Show version and default port"
+	@/bin/echo -e "  $(GREEN)make clean$(RESET)          - Clean build artifacts"
+	@/bin/echo -e "  $(GREEN)make watch$(RESET)          - Watch source files and rerun the app"
+	@/bin/echo -e ""
+	@/bin/echo -e "$(GRAY)Rust version required: $(RUST_VERSION)$(RESET)"
+	@/bin/echo -e "$(GRAY)Current version: v$(VERSION)$(RESET)"

README.md

@@ -1,32 +1,99 @@
-# solverforge-fsr
+---
+title: SolverForge Field Service Routing
+emoji: 🧰
+colorFrom: indigo
+colorTo: blue
+sdk: docker
+app_port: 7860
+pinned: false
+license: apache-2.0
+short_description: SolverForge field-service routing example
+---
 
-A SolverForge constraint optimization project (scaffold: `neutral scaffold`).
+# SolverForge FSR
+
+`solverforge-fsr` is a SolverForge field-service routing example with retained
+jobs, route geometry, technician schedules, and a browser map workspace.
+
+It answers one concrete question:
+
+"Given technicians, service visits, skills, parts, shifts, territories, and
+road-network travel, which technician should serve each visit and in what
+order?"
+
+## Hugging Face Space Deployment
+
+This repo is Docker-Space ready. Hugging Face 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
+```
+
+Full local readiness check:
+
+```sh
+make ci-local
+```
+
+The Space image is self-contained: it builds against published crates.io
+packages, copies `static/`, `solver.toml`, and `solverforge.app.toml`, and runs
+the release binary `solverforge_fsr`.
 
 ## Versioning
 
-- CLI version used to scaffold this project: `2.0.2`
-- SolverForge runtime target for this scaffold: `solverforge 0.10.0`
+The app package version is `0.1.0`; the release binary is `solverforge_fsr`.
+
+- CLI version used to scaffold this project: `2.0.3`
+- SolverForge runtime target for this scaffold: `solverforge 0.11.0`
 - SolverForge UI target for this scaffold: `solverforge-ui 0.6.5`
 - SolverForge maps target for this scaffold: `solverforge-maps 2.1.4`
-- Runtime dependency currently wired into `Cargo.toml`: `crates.io: solverforge 0.10.0`
+- Runtime dependency currently wired into `Cargo.toml`: `crates.io: solverforge 0.11.0`
 - Frontend UI dependency currently wired into `Cargo.toml`: `crates.io: solverforge-ui 0.6.5`
 - Maps dependency currently wired into `Cargo.toml`: `crates.io: solverforge-maps 2.1.4`
 
-This project was scaffolded by `solverforge-cli`, and it currently targets `SolverForge crate target 0.10.0` through the configured crate dependency targets.
+This project was scaffolded by `solverforge-cli`, and it currently targets `SolverForge crate target 0.11.0` through the configured crate dependency targets.
+
+`solverforge-core` is a direct dependency because the 0.11 custom
+incremental-constraint API exposes `ConstraintRef`, while the top-level facade
+does not re-export that type.
+
+## What SolverForge Is Doing Here
+
+- `ServiceVisit` is a problem fact: a customer job the solver must place in a
+  technician route.
+- `TechnicianRoute` is the planning entity: each technician owns one mutable
+  route.
+- `TechnicianRoute.visits` is the list planning variable.
+- `FieldServicePlan` is the planning solution.
+- Constraints score assignment coverage, route reachability, shift capacity,
+  required skills, required parts, time windows, priority slack, territory
+  affinity, travel time, and workload balance.
+- `solver.toml` selects the construction and local-search policy.
+
+The app ships one standard Bergamo field-service dataset and prepares full
+routing data when a job is created so snapshots can expose per-segment geometry.
 
 ## Quick Start
 
-```bash
-# Start the solver server
-solverforge server
+```sh
+make run-release
+```
+
+Then open `http://localhost:7860`.
 
-# Or run directly
-cargo run --release
+To inspect the command surface:
+
+```sh
+make help
 ```
 
 ## Development
 
-```bash
+```sh
 # Add a new constraint
 solverforge generate constraint my_rule --unary --hard
 
@@ -49,5 +116,44 @@ solverforge destroy constraint my_rule
 | `src/solver/` | Solver service and configuration |
 | `src/api/` | HTTP routes and DTOs |
 | `src/data/` | Data loading and generation |
+| `static/` | Browser UI, SolverForge UI config, and generated UI model |
+| `Dockerfile` | Multi-stage Rust 1.95 Alpine build for the Hugging Face Docker Space |
+| `Makefile` | Local development, validation, and Space image commands |
 | `solverforge.app.toml` | Scaffolded app/domain contract |
 | `solver.toml` | Solver configuration (termination, phases) |
+
+## 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`
+
+Route geometry is returned by `/jobs/{id}/routes` with segment-level geometry
+status. Unreachable road-network legs are reported as non-routed segments, so
+one infeasible leg does not hide the rest of the snapshot geometry.
+
+## Validation
+
+Standard validation:
+
+```sh
+make test
+```
+
+Full local Space validation:
+
+```sh
+make ci-local
+```