diff --git a/FAQ.md b/FAQ.md
index 5d08b7b..398b2e5 100644
--- a/FAQ.md
+++ b/FAQ.md
@@ -1 +1,77 @@
-Welcome to the Wiki.
\ No newline at end of file
+# FAQ — dev environment & daily problems
+
+*Tripped on something for 10+ minutes? Once it's solved, add it here (question → answer →
+command). This page is the team's memory — editing it is always allowed, no review needed.*
+
+## API
+
+**The API won't start — "port 5432 already in use"**
+Something else runs PostgreSQL on your machine. Either stop it, or change the mapped port in
+`docker-compose.yml` (e.g. `"5433:5432"`) and set `DB_URL=jdbc:postgresql://localhost:5433/trizagenda`.
+Check what's running: `docker compose ps` · `sudo lsof -i :5432`
+
+**Flyway "checksum mismatch" / "migration failed" on startup**
+You (or a pull) changed an already-applied migration — never edit a migration that ran.
+Dev-only reset (wipes local data): `docker compose down -v && docker compose up -d`, restart the API.
+If you need a schema change: new `V<n>__description.sql`, and announce "taking V<n>" in the channel first.
+
+**Where is the password-reset email?**
+There is no real email in dev — the token prints in the API console (look for the
+`PASSWORD RESET (dev email stub)` block). Token is single-use and expires in 1 hour.
+
+**Login suddenly returns 429**
+Rate limit: 10 login attempts/min per IP (5/min for reset requests). Wait a minute. If you're
+writing a script/test that logs in repeatedly, log in once and reuse the token.
+
+**`./mvnw: Permission denied`**
+The zip stripped the executable bit: `chmod +x mvnw` (or use your own `mvn`).
+
+**What are the dev credentials?**
+`admin@triztech.dz` / `Admin123!` — created by the dev-profile seeder
+(`--spring.profiles.active=dev`). No seeder = no users = every login 401.
+
+## Web
+
+**Login works but every other call returns 401 in a loop**
+Check that `VITE_API_BASE_URL` points at the **real API** (`http://localhost:8080/api/v1`) for
+auth — the Prism mock can't issue real tokens. Also confirm the API's `CORS_ORIGINS` includes
+your dev origin (`http://localhost:5173` is the default) — without it the refresh cookie never arrives.
+
+**How do I run the mock?**
+`npm run mock` → spec-faithful fake API on `http://localhost:4010`. It returns **example data
+from the spec** — don't debug "wrong values" on the mock; only shapes are meaningful there.
+
+**Where do server-side field errors show up?**
+`400 VALIDATION_FAILED` responses carry `error.details[]` with `field` + `message` — map them
+onto the matching inputs (see the conventions in `ARCHITECTURE.md` §4).
+
+## Mobile
+
+**The app can't reach the API from the Android emulator**
+`localhost` inside the emulator is the emulator itself. Use `10.0.2.2`:
+`flutter run --dart-define=API_BASE_URL=http://10.0.2.2:8080/api/v1`
+Physical device on the same Wi-Fi: your machine's LAN IP instead (and both on the same network).
+
+**`flutter analyze` complains after I pulled**
+Run `flutter pub get` first — dependency changes need a fresh resolve. Analyzer must be clean
+before every PR (agreement).
+
+## Cross-cutting
+
+**"It works on the mock but fails on the real API"**
+Expected — that's exactly what integration checkpoints exist to catch. File a `kind/bug` issue
+with the failing request, expected vs actual, and the **`X-Request-Id`** response header value
+(it's on every API response — it finds the exact server log line).
+
+**Which name is right — service or department? meeting or appointment?**
+Both, in different worlds. API/spec/UI say **services, meetings, reservations**; the DB says
+`departments`, `appointments`, `resource_bookings`. Same for roles: API is French
+(`RESPONSABLE`…), DB is English (`MANAGER`…). The API's mapping layer is the only place both
+exist — details in `trizagenda-api/ARCHITECTURE.md`.
+
+**I think the spec is wrong / missing something**
+Don't code around it. Say it in the channel → weekly sync decides → spec version bumps →
+copies in web/mobile repos get re-copied. Spec changes are team decisions (see the working agreements §1).
+
+**I accidentally committed a secret**
+Tell the PM immediately — no blame, speed matters. We rotate the secret and scrub history together.
\ No newline at end of file