feat(test): M5.3 — Playwright e2e harness for the dev stack

playwright.config.ts + tests/e2e/{apex,tenant,health}.spec.ts. make e2e for local. CI e2e job opt-in via RUN_E2E repo variable. OIDC click-through deferred to when stage is up.

Refs: M5.3

README.md

@@ -78,6 +78,31 @@ Rollback: `orca rollout undo portal --env={{env}}`.
 
 See [`CONTRIBUTING.md`](./CONTRIBUTING.md). TL;DR: branch from main, open a PR, 1 review + green CI, squash-merge.
 
+
+
+## End-to-end tests (M5.3)
+
+Playwright config at `playwright.config.ts`. Tests under `tests/e2e/`.
+
+```bash
+make e2e-install     # one-time: pnpm exec playwright install chromium
+# bring up the dev stack + tenant-registry + portal in three separate terminals,
+# then:
+make e2e             # pnpm playwright test
+```
+
+Test groups (filter with `--grep`):
+
+| File                       | What it asserts                                                          |
+|---|---|
+| `tests/e2e/apex.spec.ts`   | Apex landing page renders                                                |
+| `tests/e2e/tenant.spec.ts` | Tenant subdomain serves signed-out dashboard + 404 on unknown slug       |
+| `tests/e2e/health.spec.ts` | The whole dev stack is reachable: portal API, tenant-registry, Keycloak  |
+
+`@needs-stack` in a test title means the dev stack must be running. We don't yet have a full OIDC click-through test — Keycloak in headless mode is flaky, so we assert the gate (Sign-in button visible) rather than completing the login.
+
+In CI, the e2e job is gated behind the repo variable `RUN_E2E == 'true'` so it stays off until stage exists. Lint / typecheck / build / vitest still run on every PR.
+
 ## License
 
 Proprietary — all rights reserved. Copyright (c) 2026 Sharang Parnerkar and Benjamin Boenisch. See [`LICENSE`](./LICENSE).