Improve local setup and Maven wrapper

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`.