docs(env): add the .env.example the README already told people to copy

README.md line 72 says `cp .env.example .env`, but no such file existed and
.gitignore's `.env.*` rule would have swallowed it — hence the explicit
negation alongside it.

Documents the two variables the code actually reads, VITE_BASE_API_URL and
VITE_USE_MOCKS, rather than the longer list in the README, none of which is
referenced anywhere in apps/ or libs/. Notes that Vite resolves this from the
workspace root via envDir, and that Fayda needs nothing here beyond the callback
path matching the API's FAYDA_REDIRECT_URI.

.env.example

@@ -0,0 +1,38 @@
+# emaui environment
+#
+# Vite reads this from the workspace root, not from the app directory:
+# apps/portal/vite.config.mts and apps/backoffice/vite.config.mts both set
+# `envDir: '../../'`. So copy this file to ./.env here, at the repo root.
+#
+#   cp .env.example .env
+#
+# Only VITE_-prefixed values reach the browser, and everything that does is
+# public — it ships inside the built bundle. Never put a secret here. The Fayda
+# client id, private key and endpoints live in the API's environment only; the
+# frontend never speaks to Fayda directly.
+
+# Base URL of the emaapi backend, including the /api prefix.
+# Defaults to http://localhost:3000/api when unset.
+VITE_BASE_API_URL=http://localhost:3000/api
+
+# Serve fixture data instead of calling the API. Any value other than "true"
+# uses the real backend.
+VITE_USE_MOCKS=false
+
+# --- Docker Compose only -----------------------------------------------------
+# Host ports published by docker-compose.yml. It also expects per-app env files
+# at apps/portal/.env and apps/backoffice/.env, which can each be a copy of this
+# file. Ignored when running the Vite dev servers, which serve the portal on
+# 4200 and the backoffice on 4201.
+# EMA_PORTAL_PORT=8021
+# EMA_BACKOFFICE_PORT=8022
+
+# --- Fayda note --------------------------------------------------------------
+# There is nothing to configure here for Fayda. The portal serves the callback
+# page at /callback and /signup/fayda/callback, and whichever path is registered
+# with Fayda must match the API's FAYDA_REDIRECT_URI exactly.
+#
+# The value being registered first is http://localhost:3000/callback, which is
+# also emaapi's default port — so when testing that redirect, serve the portal
+# on 3000 (`npx nx serve portal --port 3000`) and move the API elsewhere, or
+# register a URI that points at the port the portal actually runs on.

.gitignore

@@ -13,6 +13,8 @@ coverage/
 # env
 .env
 .env.*
+# ...but the checked-in template must survive that rule.
+!.env.example
 
 # logs
 *.log