Improve local setup and Maven wrapper

.mise.toml

@@ -6,15 +6,38 @@ lefthook = "1.11.12"
 gitleaks = "8.26.0"
 
 [tasks.setup]
-description = "Install deps and git hooks"
+description = "Install deps, git hooks, env file, and validate local toolchain"
 run = """
 #!/bin/bash
-set -e
+set -euo pipefail
+
+if ! command -v java >/dev/null 2>&1; then
+  echo "ERROR: Java 21 JDK not found. Run 'mise install' first, or install OpenJDK 21 and set JAVA_HOME." >&2
+  exit 1
+fi
+
+java_major="$(java -XshowSettings:properties -version 2>&1 | awk -F= '/java.specification.version/ { gsub(/[[:space:]]/, "", $2); print $2; exit }')"
+if [ "${java_major}" != "21" ]; then
+  echo "ERROR: Java 21 is required, but found Java ${java_major}. Run 'mise install' or set JAVA_HOME to a Java 21 JDK." >&2
+  exit 1
+fi
+
+# Prime and validate the Maven wrapper cache so backend startup does not fail later.
+backend/mvnw -f backend/pom.xml -v >/dev/null
+
 npm --prefix frontend install
 lefthook install
 cp -n .env.example .env 2>/dev/null || true
 """
 
+[tasks.backend]
+description = "Run the Spring Boot backend"
+run = "backend/mvnw -f backend/pom.xml spring-boot:run"
+
+[tasks.frontend]
+description = "Run the Vite frontend"
+run = "npm --prefix frontend run dev"
+
 [tasks.check]
 description = "Format-check, lint, and test"
 run = """

README.md

@@ -17,14 +17,16 @@ Docker Compose — Flyway for schema migrations — Tailwind CSS v4 — Biome 1.
 
 ## Quick start
 
-> **Requires a full JDK** (not just JRE) for Maven compilation. `mise install` below handles this.
-> Without mise: `sudo apt install openjdk-21-jdk`.
+> **Requires a full Java 21 JDK** (not just a JRE) for Maven compilation. `mise install` below
+> handles this and sets `JAVA_HOME` when commands are run through `mise`. Without mise:
+> `sudo apt install openjdk-21-jdk`, then ensure `java -version` reports 21 and `JAVA_HOME` points
+> at that JDK.
 
 ```bash
 # 1. Pin toolchain — installs Java 21 JDK, Node 22, Maven, lefthook, gitleaks
 mise install
 
-# 2. Install deps and git hooks (or run the four commands manually)
+# 2. Install deps, git hooks, .env, and validate Java + Maven wrapper
 mise run setup
 
 # 3. Start the database
@@ -35,12 +37,15 @@ Open two terminals:
 
 ```bash
 # Backend → http://localhost:8080
-backend/mvnw -f backend/pom.xml spring-boot:run
+mise run backend
 
 # Frontend → http://localhost:5173  (proxies /api → :8080)
-cd frontend && npm run dev
+mise run frontend
 ```
 
+If you have activated mise in your shell, the direct commands also work:
+`backend/mvnw -f backend/pom.xml spring-boot:run` and `cd frontend && npm run dev`.
+
 ## Verify everything
 
 ```bash
@@ -50,6 +55,14 @@ mise run check       # format-check + lint + test (both stacks)
 Without mise:
 
 ```bash
+# one-time setup
+sudo apt install openjdk-21-jdk nodejs npm docker-compose-plugin
+export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64  # adjust if your JDK is elsewhere
+npm --prefix frontend install
+cp -n .env.example .env
+backend/mvnw -f backend/pom.xml -v                 # primes the Maven wrapper cache
+
+# checks
 backend/mvnw -f backend/pom.xml spotless:check -q
 cd frontend && npx biome check src
 backend/mvnw -f backend/pom.xml test -q
@@ -79,3 +92,11 @@ All other CRUD endpoints follow standard REST conventions under `/api/`.
 ## Environment
 
 `.env.example` documents all env vars. `mise run setup` copies it to `.env` automatically on first run.
+
+## Troubleshooting
+
+- `backend/mvnw: ... exec: .../apache-maven-3.9.9/bin/mvn: not found` — run `mise run setup` again.
+  The setup task primes the Maven wrapper cache. If it still fails, remove the broken cache with
+  `rm -rf ~/.m2/wrapper/dists/apache-maven-3.9.9*` and rerun `mise run setup`.
+- `JAVA_HOME environment variable is not defined correctly` — install a Java 21 JDK and set
+  `JAVA_HOME`, or use the mise tasks (`mise run backend`, `mise run check`) after `mise install`.

backend/mvnw

@@ -8,6 +8,7 @@ MAVEN_URL="https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/${
 
 if [ ! -f "${MAVEN_CACHE}/bin/mvn" ]; then
   MAVEN_TMP="${MAVEN_CACHE}.tmp.$$"
+  mkdir -p "$(dirname "${MAVEN_CACHE}")"
   if mkdir "${MAVEN_CACHE}.lock" 2>/dev/null; then
     echo "Downloading Apache Maven ${MAVEN_VERSION}..." >&2
     mkdir -p "${MAVEN_TMP}"