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

Lands the minimum surface so a developer can:

  cd platform/orca-platform && make dev-up
  cd platform/tenant-registry && make dev
  cd platform/portal && make install && make dev
  open http://acme.localhost:3000

and complete a real OIDC sign-in against the breakpilot-dev realm.

Layout:
  src/middleware.ts                host→slug URL rewrite; backstage carve-out
  src/auth.ts                      Auth.js v5 Keycloak provider; passes
                                   tenant_id/slug/org_roles/products/plan/status
                                   claims through to the session
  src/app/api/auth/[...nextauth]/  Auth.js handlers (GET, POST)
  src/app/layout.tsx               root html shell
  src/app/page.tsx                 apex landing
  src/app/[slug]/layout.tsx        fetches tenant via lib/tenant-registry
  src/app/[slug]/page.tsx          redirect to /dashboard
  src/app/[slug]/dashboard/page.tsx
                                   signed-out → Sign in with Keycloak
                                   signed-in  → welcome + Sign out
  src/lib/host.ts                  testable host parser (apex/tenant/backstage)
  src/lib/tenant-registry.ts       fetch client for the Go service

Tooling:
  vitest                           13 tests, 100% coverage of src/lib/
  Next.js 15 build                 compiles all routes; output: standalone
  ESLint flat config               next/core-web-vitals + next/typescript

Real RBAC enforcement, the rest of the customer-area surfaces, and the
backstage shell land per the M5.2 / M10.1 schedule. This is just enough
to be the first thing a developer codes in.

Refs: M5.1 (skeleton)

README.md

@@ -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 / next lint / 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