feat(app): Next.js 16 + Auth.js v5 portal skeleton

Next.js 16 + Auth.js v5 skeleton: host→slug middleware, tenant-context layout, OIDC sign-in flow against breakpilot-dev realm. 100% coverage on src/lib. Bumps next to 16.2.6 to clear trivy CVEs in 15.0.3.

README.md

@@ -1,6 +1,6 @@
 # portal
 
-Next.js 15 customer area + backstage.
+Next.js 16 customer area + backstage.
 
 > Part of the **Breakpilot Platform**. For the big picture see [`platform/docs`](https://gitea.meghsakha.com/platform/docs):
 > [Architecture](https://gitea.meghsakha.com/platform/docs/src/branch/main/PLATFORM_ARCHITECTURE.md) ·
@@ -10,7 +10,7 @@ Next.js 15 customer area + backstage.
 
 ## What this is
 
-Next.js 15 customer area + backstage. Scaffolded under milestone M5.1. See [`platform/docs`](https://gitea.meghsakha.com/platform/docs) for the full architecture context.
+Next.js 16 customer area + backstage. Scaffolded under milestone M5.1. See [`platform/docs`](https://gitea.meghsakha.com/platform/docs) for the full architecture context.
 
 **Plane:** Control
 **Owner:** @sharang
@@ -20,19 +20,43 @@ Next.js 15 customer area + backstage. Scaffolded under milestone M5.1. See [`pla
 ## Run locally
 
 ```bash
-# prerequisites: see CONTRIBUTING.md for tooling once code lands
-make dev          # starts dependencies + this service on http://localhost:3000
-make test         # unit + integration
-make e2e          # only if this repo ships user-facing flows
+# Prerequisites: Node 20+, pnpm 9+, the dev stack running.
+
+# 1. Bring up Keycloak + Postgres + Redis (separate clone):
+cd /path/to/platform/orca-platform && make dev-up
+
+# 2. Run tenant-registry (separate clone):
+cd /path/to/platform/tenant-registry && make dev
+
+# 3. Run this app:
+make install      # pnpm install --frozen-lockfile
+make dev          # next dev on http://localhost:3000
+
+# Or hit a real tenant immediately:
+# open http://acme.localhost:3000  →  redirects to Keycloak  →  back to /acme/dashboard
 ```
 
-Local secrets come from `.env.local` (gitignored). Template at `.env.example`.
+Seed login (from the dev-stack realm): `test@breakpilot.dev` / `test`.
 
-## Endpoints / surface
+`make test` / `make lint` / `make typecheck` / `make build` run vitest / eslint / tsc / next build respectively.
 
-{{For services: list the top-level routes or commands.
-For libraries: list the public API entry points.
-For IaC: list the make targets.}}
+Env vars live in `.env.example`. Copy to `.env.local` for local overrides (gitignored).
+
+## Surface
+
+| Route                              | Renders                                                                 |
+|---|---|
+| `http://localhost:3000/`           | Apex landing — pointer to tenant subdomains                              |
+| `http://<slug>.localhost:3000/`    | Middleware rewrites to `/[slug]/` → redirects to `/[slug]/dashboard`     |
+| `http://<slug>.localhost:3000/dashboard` | OIDC-gated dashboard; signed-out users see "Sign in with Keycloak" |
+| `http://backstage.localhost:3000/` | (Skeleton) backstage route — rewritten to `/__backstage__/*`             |
+| `/api/auth/[...nextauth]`          | Auth.js v5 endpoints (callback, signin, signout, jwt)                    |
+
+## Architecture notes
+
+- **Host → slug routing**: `src/middleware.ts` parses `Host` header via `parseHost()` (in `src/lib/host.ts`) and rewrites the request path to `/<slug>/...`. URL bar stays unchanged. Apex hosts and unknown subdomains fall through unmodified.
+- **Tenant context**: `src/app/[slug]/layout.tsx` fetches the tenant from `tenant-registry` (`src/lib/tenant-registry.ts`). 404 → `notFound()`; HTTP errors bubble up.
+- **Auth**: `src/auth.ts` is the Auth.js v5 config — Keycloak provider, tenant-context claims (`tenant_id`, `tenant_slug`, `org_roles`, `products`, `plan`, `tenant_status`) propagated via JWT/session callbacks. Real RBAC enforcement lands in M5.2 / M10.1.
 
 ## Deployment