feat(portal): M10.1 — fill the 10 customer-area shells

Four real surfaces wired to tenant-registry (settings, settings/api-keys CRUD, audit pagination, products live entitlements), five forward-looking empty states with CTAs. 56 vitest tests + 10 Playwright canaries. lib/format.ts consolidates date helpers.

Refs: M10.1

.env.example

@@ -0,0 +1,32 @@
+# portal — local dev environment.
+# Copy to .env.local (gitignored).
+
+# Tenant Registry — see platform/tenant-registry. Run `make dev` there.
+TENANT_REGISTRY_URL=http://localhost:8090
+
+# Keycloak (dev stack from platform/orca-platform/dev).
+KEYCLOAK_ISSUER=http://localhost:8080/realms/breakpilot-dev
+KEYCLOAK_CLIENT_ID=dev-portal
+# Public PKCE client — secret is structurally required by Auth.js but unused
+# at the OAuth code-exchange step. Any non-empty placeholder works in dev.
+KEYCLOAK_CLIENT_SECRET=unused-public-client
+
+# Auth.js v5 — required for JWT signing.
+# Generate with: openssl rand -base64 32 (keep stable across restarts or
+# every dev login invalidates the existing session).
+AUTH_SECRET=dev-secret-change-me-do-not-ship-replace-with-32-byte-random
+
+# IMPORTANT: AUTH_URL must match the exact subdomain you're using in the
+# browser. Auth.js v5 builds the OAuth redirect_uri from this value (NOT
+# from the request Host header, even with AUTH_TRUST_HOST=true). If you
+# visit http://acme.localhost:3000 but AUTH_URL is http://localhost:3000,
+# the PKCE cookie set on acme.localhost won't be readable at the localhost
+# callback, and Keycloak rejects the token exchange with
+# 'invalid_grant: Incorrect redirect_uri'.
+#
+# For a single tenant dev flow, pin AUTH_URL to the subdomain you use:
+AUTH_URL=http://acme.localhost:3000
+
+# AUTH_TRUST_HOST is on so this still works behind orca-proxy in stage/prod
+# (where the actual host is known via X-Forwarded-Host).
+AUTH_TRUST_HOST=true

.gitea/workflows/ci.yaml

@@ -57,7 +57,7 @@ jobs:
 
   test:
     runs-on: docker
-    if: hashFiles('package.json') != ''
+
     steps:
       - uses: actions/checkout@v4
 
@@ -72,16 +72,26 @@ jobs:
       - run: pnpm install --frozen-lockfile
       - run: pnpm lint
       - run: pnpm typecheck
-      - run: pnpm test --coverage
+      # `pnpm test` already includes --coverage via the package.json script.
+      - run: pnpm test
       - name: coverage gate
         run: |
           node -e "const c=require('./coverage/coverage-summary.json').total.lines.pct; if (c<70) { console.error('coverage', c, '< 70%'); process.exit(1) }"
-      - run: pnpm build
+      - name: build
+        env:
+          # Required at build-time by Auth.js. Replaced by Infisical-sourced
+          # secret in stage/prod via Orca env injection (M5.1+).
+          AUTH_SECRET: ci-build-dummy-${{ github.sha }}
+        run: pnpm build
 
   e2e:
     needs: test
     runs-on: docker
-    if: hashFiles('playwright.config.ts','playwright.config.js') != '' && github.event_name == 'push' && github.ref == 'refs/heads/main'
+    # Two gates: playwright.config.ts must exist + the repo variable
+    # RUN_E2E must be 'true'. Until stage.breakpilot.com is up (M1.2 +
+    # M0.3), the e2e job is opt-in. Locally, devs run `make e2e` against
+    # their own dev stack.
+    if: hashFiles('playwright.config.ts','playwright.config.js') != '' && github.event_name == 'push' && github.ref == 'refs/heads/main' && vars.RUN_E2E == 'true'
     steps:
       - uses: actions/checkout@v4
       - uses: pnpm/action-setup@v4
@@ -92,7 +102,8 @@ jobs:
       - run: pnpm exec playwright install --with-deps chromium
       - run: pnpm e2e
         env:
-          PLAYWRIGHT_BASE_URL: https://stage.breakpilot.com
+          PLAYWRIGHT_BASE_URL: ${{ vars.STAGE_PORTAL_BASE_URL }}
+          PLAYWRIGHT_APEX_URL: ${{ vars.STAGE_PORTAL_APEX_URL }}
           PLAYWRIGHT_TEST_USER: ${{ secrets.STAGE_TEST_USER }}
           PLAYWRIGHT_TEST_PASS: ${{ secrets.STAGE_TEST_PASS }}
 

.gitignore

@@ -57,3 +57,7 @@ coverage/
 .env.development.local
 .env.test.local
 .env.production.local
+
+# Playwright
+playwright-report/
+test-results/

CHANGELOG.md

@@ -6,6 +6,11 @@ Generated section is appended on release tag via `git-cliff` (see `.gitea/workfl
 ## [Unreleased]
 
 ### Added
+- feat(portal): M10.1 — real content for /settings + /settings/api-keys (full CRUD) + /audit (paginated, filterable) + /products (live entitlements). Forward-looking empty states with milestone hooks + CTAs on projects/users/integrations/billing/support.
+- feat(signup): M12.1 — public /start form creates a trial tenant via POST /v1/tenants (KC adapter provisions the org + invites the admin); dashboard renders a trial-days-left banner when status=trial
+- feat(catalog): M11.1 — /[slug]/catalog renders the live catalog, gates owned products, server-action 'Request' (POST /v1/catalog/request) + 'Start 14-day trial' (POST /v1/catalog/trial-request)
+- feat(test): M5.3 — Playwright e2e harness (apex / tenant / dev-stack-health specs). pnpm e2e + make e2e. CI e2e job gated behind RUN_E2E variable until stage exists.
+- feat(app): M5.2 — customer-area route shells (settings, billing, audit, support, catalog, products, projects, settings/{users,api-keys,integrations}); shared Nav component reads session.org_roles and shows only what each role can see; backstage stub at /__backstage__; dashboard renders product tiles from session.products
 - chore(deps): bump next + eslint-config-next to 16.2.6 to clear trivy CVEs (CVE-2025-29927 critical + 7 highs in next 15.0.3)
 - feat(app): Next.js 16 + Auth.js v5 skeleton with host→slug middleware, tenant context layout, OIDC sign-in flow
 -

Makefile

@@ -10,6 +10,8 @@ help:
 	@echo "  make lint          pnpm lint"
 	@echo "  make typecheck     pnpm typecheck"
 	@echo "  make build         pnpm build (Next.js production build)"
+	@echo "  make e2e           pnpm e2e (Playwright; needs dev stack + tenant-registry + portal running)"
+	@echo "  make e2e-install   one-time browser install"
 	@echo "  make docker        build local image (portal:dev)"
 
 install:
@@ -30,6 +32,12 @@ typecheck:
 build:
 	@pnpm build
 
+e2e:
+	@pnpm e2e
+
+e2e-install:
+	@pnpm e2e:install
+
 docker:
 	@docker build -t portal:dev .
 

README.md

@@ -38,7 +38,9 @@ make dev          # next dev on http://localhost:3000
 
 Seed login (from the dev-stack realm): `test@breakpilot.dev` / `test`.
 
-`make test` / `make lint` / `make typecheck` / `make build` run vitest / next lint / tsc / next build respectively.
+> **AUTH_URL gotcha:** Auth.js v5 builds the OAuth `redirect_uri` from `AUTH_URL` — not from the request Host header, even with `AUTH_TRUST_HOST=true`. For multi-tenant dev work, pin `AUTH_URL` to the subdomain you log in on (e.g., `http://acme.localhost:3000`); otherwise Keycloak rejects the token exchange with `invalid_grant: Incorrect redirect_uri`. In prod, orca-proxy passes the right host via `X-Forwarded-Host` and `AUTH_URL` is set to the apex (`https://breakpilot.com`).
+
+`make test` / `make lint` / `make typecheck` / `make build` run vitest / eslint / tsc / next build respectively.
 
 Env vars live in `.env.example`. Copy to `.env.local` for local overrides (gitignored).
 
@@ -78,6 +80,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).

package.json

@@ -14,7 +14,9 @@
     "start": "next start --port 3000",
     "lint": "eslint . --max-warnings 0",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run --coverage"
+    "test": "vitest run --coverage",
+    "e2e": "playwright test",
+    "e2e:install": "playwright install --with-deps chromium"
   },
   "dependencies": {
     "next": "16.2.6",
@@ -23,6 +25,7 @@
     "react-dom": "19.0.0"
   },
   "devDependencies": {
+    "@playwright/test": "^1.60.0",
     "@types/node": "20.16.10",
     "@types/react": "19.0.1",
     "@types/react-dom": "19.0.1",

playwright.config.ts

@@ -0,0 +1,40 @@
+import { defineConfig, devices } from "@playwright/test";
+
+// Playwright e2e harness for the portal.
+//
+// Local: assumes the full dev stack is running —
+//   1. cd platform/orca-platform && make dev-up
+//   2. cd platform/tenant-registry && make dev
+//   3. cd platform/portal && make dev
+//   4. cd platform/portal && pnpm e2e
+//
+// Defaults to http://acme.localhost:3000 so subdomain routing fires.
+// Override with PLAYWRIGHT_BASE_URL for stage (once that exists, M5.x+).
+
+const baseURL = process.env.PLAYWRIGHT_BASE_URL ?? "http://acme.localhost:3000";
+const apexURL = process.env.PLAYWRIGHT_APEX_URL ?? "http://localhost:3000";
+
+export default defineConfig({
+  testDir: "./tests/e2e",
+  fullyParallel: false, // Hosts share subdomains; serial keeps logs sane.
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 1 : 0,
+  reporter: process.env.CI ? "github" : "list",
+  use: {
+    baseURL,
+    trace: "retain-on-failure",
+    screenshot: "only-on-failure",
+  },
+  projects: [
+    {
+      name: "chromium",
+      use: { ...devices["Desktop Chrome"] },
+    },
+  ],
+  // Tag-friendly: tests that need the dev stack alive use `@needs-stack`
+  // in their title so we can split fast/slow runs in CI later.
+  metadata: {
+    apexURL,
+    baseURL,
+  },
+});

pnpm-lock.yaml

@@ -10,10 +10,10 @@ importers:
     dependencies:
       next:
         specifier: 16.2.6
-        version: 16.2.6(@babel/core@7.29.0)(react-dom@19.0.0(react@19.0.0))(react@19.0.0)
+        version: 16.2.6(@babel/core@7.29.0)(@playwright/test@1.60.0)(react-dom@19.0.0(react@19.0.0))(react@19.0.0)
       next-auth:
         specifier: 5.0.0-beta.25
-        version: 5.0.0-beta.25(next@16.2.6(@babel/core@7.29.0)(react-dom@19.0.0(react@19.0.0))(react@19.0.0))(react@19.0.0)
+        version: 5.0.0-beta.25(next@16.2.6(@babel/core@7.29.0)(@playwright/test@1.60.0)(react-dom@19.0.0(react@19.0.0))(react@19.0.0))(react@19.0.0)
       react:
         specifier: 19.0.0
         version: 19.0.0
@@ -21,6 +21,9 @@ importers:
         specifier: 19.0.0
         version: 19.0.0(react@19.0.0)
     devDependencies:
+      '@playwright/test':
+        specifier: ^1.60.0
+        version: 1.60.0
       '@types/node':
         specifier: 20.16.10
         version: 20.16.10
@@ -585,6 +588,11 @@ packages:
     resolution: {integrity: sha512-+1VkjdD0QBLPodGrJUeqarH8VAIvQODIbwh9XpP5Syisf7YoQgsJKPNFoqqLQlu+VQ/tVSshMR6loPMn8U+dPg==}
     engines: {node: '>=14'}
 
+  '@playwright/test@1.60.0':
+    resolution: {integrity: sha512-O71yZIbAh/PxDMNGns37GHBIfrVkEVyn+AXyIa5dOTfb4/xNvRWV+Vv/NMbNCtODB/pO7vLlF2OTmMVLhmr7Ag==}
+    engines: {node: '>=18'}
+    hasBin: true
+
   '@rollup/rollup-android-arm-eabi@4.60.4':
     resolution: {integrity: sha512-F5QXMSiFebS9hKZj02XhWLLnRpJ3B3AROP0tWbFBSj+6kCbg5m9j5JoHKd4mmSVy5mS/IMQloYgYxCuJC0fxEQ==}
     cpu: [arm]
@@ -1425,6 +1433,11 @@ packages:
     resolution: {integrity: sha512-gIXjKqtFuWEgzFRJA9WCQeSJLZDjgJUOMCMzxtvFq/37KojM1BFGufqsCy0r4qSQmYLsZYMeyRqzIWOMup03sw==}
     engines: {node: '>=14'}
 
+  fsevents@2.3.2:
+    resolution: {integrity: sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==}
+    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+    os: [darwin]
+
   fsevents@2.3.3:
     resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
     engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
@@ -1946,6 +1959,16 @@ packages:
     resolution: {integrity: sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==}
     engines: {node: '>=12'}
 
+  playwright-core@1.60.0:
+    resolution: {integrity: sha512-9bW6zvX/m0lEbgTKJ6YppOKx8H3VOPBMOCFh2irXFOT4BbHgrx5hPjwJYLT40Lu+4qtD36qKc/Hn56StUW57IA==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  playwright@1.60.0:
+    resolution: {integrity: sha512-hheHdokM8cdqCb0lcE3s+zT4t4W+vvjpGxsZlDnikarzx8tSzMebh3UiFtgqwFwnTnjYQcsyMF8ei2mCO/tpeA==}
+    engines: {node: '>=18'}
+    hasBin: true
+
   possible-typed-array-names@1.1.0:
     resolution: {integrity: sha512-/+5VFTchJDoVj3bhoqi6UeymcD00DAwb1nJwamzPvHEszJ4FpF6SNNbUbOS8yI56qHzdV8eK0qEfOSiodkTdxg==}
     engines: {node: '>= 0.4'}
@@ -2840,6 +2863,10 @@ snapshots:
   '@pkgjs/parseargs@0.11.0':
     optional: true
 
+  '@playwright/test@1.60.0':
+    dependencies:
+      playwright: 1.60.0
+
   '@rollup/rollup-android-arm-eabi@4.60.4':
     optional: true
 
@@ -3822,6 +3849,9 @@ snapshots:
       cross-spawn: 7.0.6
       signal-exit: 4.1.0
 
+  fsevents@2.3.2:
+    optional: true
+
   fsevents@2.3.3:
     optional: true
 
@@ -4208,13 +4238,13 @@ snapshots:
 
   natural-compare@1.4.0: {}
 
-  next-auth@5.0.0-beta.25(next@16.2.6(@babel/core@7.29.0)(react-dom@19.0.0(react@19.0.0))(react@19.0.0))(react@19.0.0):
+  next-auth@5.0.0-beta.25(next@16.2.6(@babel/core@7.29.0)(@playwright/test@1.60.0)(react-dom@19.0.0(react@19.0.0))(react@19.0.0))(react@19.0.0):
     dependencies:
       '@auth/core': 0.37.2
-      next: 16.2.6(@babel/core@7.29.0)(react-dom@19.0.0(react@19.0.0))(react@19.0.0)
+      next: 16.2.6(@babel/core@7.29.0)(@playwright/test@1.60.0)(react-dom@19.0.0(react@19.0.0))(react@19.0.0)
       react: 19.0.0
 
-  next@16.2.6(@babel/core@7.29.0)(react-dom@19.0.0(react@19.0.0))(react@19.0.0):
+  next@16.2.6(@babel/core@7.29.0)(@playwright/test@1.60.0)(react-dom@19.0.0(react@19.0.0))(react@19.0.0):
     dependencies:
       '@next/env': 16.2.6
       '@swc/helpers': 0.5.15
@@ -4233,6 +4263,7 @@ snapshots:
       '@next/swc-linux-x64-musl': 16.2.6
       '@next/swc-win32-arm64-msvc': 16.2.6
       '@next/swc-win32-x64-msvc': 16.2.6
+      '@playwright/test': 1.60.0
       sharp: 0.34.5
     transitivePeerDependencies:
       - '@babel/core'
@@ -4341,6 +4372,14 @@ snapshots:
 
   picomatch@4.0.4: {}
 
+  playwright-core@1.60.0: {}
+
+  playwright@1.60.0:
+    dependencies:
+      playwright-core: 1.60.0
+    optionalDependencies:
+      fsevents: 2.3.2
+
   possible-typed-array-names@1.1.0: {}
 
   postcss@8.4.31:

src/app/[slug]/audit/page.tsx

@@ -0,0 +1,207 @@
+import Link from "next/link";
+import { redirect } from "next/navigation";
+import { auth } from "@/auth";
+import { NotAuthorized } from "@/components/ShellEmpty";
+import { formatDateTime, formatRelative, truncate } from "@/lib/format";
+import type { SessionWithExtras } from "@/lib/session";
+import { canSee } from "@/lib/session";
+import { fetchAudit, fetchTenantBySlug } from "@/lib/tenant-registry";
+
+const PAGE_SIZE = 50;
+
+export default async function AuditPage({
+  params,
+  searchParams,
+}: {
+  params: Promise<{ slug: string }>;
+  searchParams: Promise<{ cursor?: string; action?: string; actor_id?: string }>;
+}) {
+  const { slug } = await params;
+  const q = await searchParams;
+  const session = (await auth()) as SessionWithExtras | null;
+  if (!canSee(session, "audit")) return <NotAuthorized />;
+
+  const tenant = await fetchTenantBySlug(slug);
+  if (!tenant) redirect(`/${slug}/dashboard`);
+
+  const cursor = q.cursor ? Number(q.cursor) : undefined;
+  const page = await fetchAudit({
+    tenant_id: tenant.id,
+    action: q.action || undefined,
+    actor_id: q.actor_id || undefined,
+    limit: PAGE_SIZE,
+    cursor: cursor && !Number.isNaN(cursor) ? cursor : undefined,
+  });
+
+  const nextHref = page.next_cursor
+    ? buildHref(slug, { ...q, cursor: String(page.next_cursor) })
+    : null;
+  const resetHref = (q.action || q.actor_id || q.cursor) ? `/${slug}/audit` : null;
+
+  return (
+    <section>
+      <h1 style={{ fontSize: 28, marginBottom: 8 }}>Audit log</h1>
+      <p style={{ color: "#444", marginBottom: 16 }}>
+        Every state-changing action emitted by the portal and the products.{" "}
+        <a
+          href="https://gitea.meghsakha.com/platform/docs/src/branch/main/PRODUCT_INTEGRATION_SPEC.md"
+          style={{ color: "#0070f3" }}
+        >
+          Retraced-shape schema
+        </a>{" "}
+        — CSV / PDF export lands in M10.2.
+      </p>
+
+      <Filters slug={slug} active={{ action: q.action, actor_id: q.actor_id }} />
+
+      {page.items.length === 0 ? (
+        <p style={{ color: "#666", fontSize: 14, marginTop: 16 }}>
+          No events match the current filter.
+        </p>
+      ) : (
+        <div style={{ overflow: "auto", marginTop: 16 }}>
+          <table style={{ width: "100%", fontSize: 13, borderCollapse: "collapse" }}>
+            <thead>
+              <tr style={{ textAlign: "left", borderBottom: "1px solid #eaeaea" }}>
+                <th style={th}>When</th>
+                <th style={th}>Action</th>
+                <th style={th}>Actor</th>
+                <th style={th}>Target</th>
+                <th style={th}>Product</th>
+                <th style={th}>Meta</th>
+              </tr>
+            </thead>
+            <tbody>
+              {page.items.map((ev) => (
+                <tr key={ev.id} style={{ borderBottom: "1px solid #f0f0f0" }}>
+                  <td style={td} title={formatDateTime(ev.created_at)}>
+                    {formatRelative(ev.created_at)}
+                  </td>
+                  <td style={{ ...td, fontFamily: "ui-monospace, monospace" }}>
+                    {ev.action}
+                  </td>
+                  <td style={td}>
+                    {ev.actor_name || ev.actor_id || (
+                      <em style={{ color: "#999" }}>system</em>
+                    )}
+                  </td>
+                  <td style={td}>
+                    {ev.target_type && (
+                      <span style={{ color: "#666" }}>{ev.target_type}:</span>
+                    )}{" "}
+                    {ev.target_name || ev.target_id || (
+                      <em style={{ color: "#999" }}>—</em>
+                    )}
+                  </td>
+                  <td style={td}>
+                    {ev.product || <em style={{ color: "#999" }}>portal</em>}
+                  </td>
+                  <td style={{ ...td, fontFamily: "ui-monospace, monospace", color: "#666" }}>
+                    {ev.metadata && Object.keys(ev.metadata).length > 0
+                      ? truncate(JSON.stringify(ev.metadata), 50)
+                      : ""}
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      )}
+
+      <div style={{ marginTop: 16, display: "flex", justifyContent: "space-between" }}>
+        <div>
+          {resetHref && (
+            <Link href={resetHref as `/${string}`} style={btnLink}>
+              ← Clear filters
+            </Link>
+          )}
+        </div>
+        <div>
+          {nextHref && (
+            <Link href={nextHref as `/${string}`} style={btnLink}>
+              Next page →
+            </Link>
+          )}
+        </div>
+      </div>
+    </section>
+  );
+}
+
+function Filters({
+  slug,
+  active,
+}: {
+  slug: string;
+  active: { action?: string; actor_id?: string };
+}) {
+  return (
+    <form
+      action={`/${slug}/audit`}
+      method="GET"
+      style={{
+        display: "flex",
+        gap: 8,
+        marginTop: 8,
+        padding: 12,
+        background: "#fafafa",
+        border: "1px solid #eaeaea",
+        borderRadius: 6,
+      }}
+    >
+      <label style={{ display: "flex", alignItems: "center", gap: 6, fontSize: 13 }}>
+        action
+        <input
+          name="action"
+          defaultValue={active.action ?? ""}
+          placeholder="tenant.created"
+          style={{ ...inputStyle, padding: "4px 8px", fontSize: 13 }}
+        />
+      </label>
+      <label style={{ display: "flex", alignItems: "center", gap: 6, fontSize: 13 }}>
+        actor_id
+        <input
+          name="actor_id"
+          defaultValue={active.actor_id ?? ""}
+          placeholder="kc user id"
+          style={{ ...inputStyle, padding: "4px 8px", fontSize: 13 }}
+        />
+      </label>
+      <button type="submit" style={btnSmall}>
+        Filter
+      </button>
+    </form>
+  );
+}
+
+function buildHref(slug: string, q: Record<string, string | undefined>): string {
+  const qs = new URLSearchParams();
+  for (const [k, v] of Object.entries(q)) {
+    if (v) qs.set(k, v);
+  }
+  const s = qs.toString();
+  return s ? `/${slug}/audit?${s}` : `/${slug}/audit`;
+}
+
+const inputStyle: React.CSSProperties = {
+  padding: "8px 10px",
+  border: "1px solid #ddd",
+  borderRadius: 6,
+  fontSize: 14,
+};
+const btnLink: React.CSSProperties = {
+  color: "#0070f3",
+  fontSize: 13,
+  textDecoration: "none",
+};
+const btnSmall: React.CSSProperties = {
+  padding: "4px 10px",
+  background: "white",
+  color: "#0070f3",
+  border: "1px solid #0070f3",
+  borderRadius: 4,
+  fontSize: 12,
+  cursor: "pointer",
+};
+const th: React.CSSProperties = { padding: "8px 10px", color: "#666", fontWeight: 500 };
+const td: React.CSSProperties = { padding: "8px 10px" };

src/app/[slug]/billing/page.tsx

@@ -0,0 +1,31 @@
+import Link from "next/link";
+import { auth } from "@/auth";
+import { NotAuthorized, ShellEmpty } from "@/components/ShellEmpty";
+import type { SessionWithExtras } from "@/lib/session";
+import { canSee } from "@/lib/session";
+
+export default async function Page({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  const { slug } = await params;
+  const session = (await auth()) as SessionWithExtras | null;
+  if (!canSee(session, "billing")) return <NotAuthorized />;
+  return (
+    <ShellEmpty
+      title="Billing"
+      description="Plan, seats, invoices. Polar Checkout opens here for plan changes."
+      milestone="M8.3"
+      details="Polar.sh is the Merchant of Record — it handles EU VAT MOSS so we don't have to. Invoices mirror to ERPNext (Customer + Sales Invoice) so accounting stays in one place."
+      cta={
+        <Link
+          href={`/${slug}/catalog`}
+          style={{ color: "#0070f3", fontSize: 14, textDecoration: "underline" }}
+        >
+          Browse the catalog →
+        </Link>
+      }
+    />
+  );
+}

src/app/[slug]/catalog/page.tsx

@@ -0,0 +1,205 @@
+import { revalidatePath } from "next/cache";
+import { redirect } from "next/navigation";
+import { auth } from "@/auth";
+import { NotAuthorized } from "@/components/ShellEmpty";
+import type { SessionWithExtras } from "@/lib/session";
+import { canSee } from "@/lib/session";
+import {
+  fetchCatalog,
+  fetchEntitlements,
+  fetchTenantBySlug,
+  requestProduct,
+  startTrial,
+  type CatalogEntry,
+} from "@/lib/tenant-registry";
+
+export default async function CatalogPage({
+  params,
+  searchParams,
+}: {
+  params: Promise<{ slug: string }>;
+  searchParams: Promise<{ ok?: string; err?: string }>;
+}) {
+  const { slug } = await params;
+  const flash = await searchParams;
+  const session = (await auth()) as SessionWithExtras | null;
+  if (!canSee(session, "catalog")) return <NotAuthorized />;
+
+  const tenant = await fetchTenantBySlug(slug);
+  if (!tenant) redirect(`/${slug}/dashboard`);
+
+  const [catalog, entitlements] = await Promise.all([
+    fetchCatalog(),
+    fetchEntitlements(tenant.id),
+  ]);
+  const enabled = new Set(entitlements.filter((e) => e.enabled).map((e) => e.product));
+
+  async function doRequest(formData: FormData) {
+    "use server";
+    const product = String(formData.get("product"));
+    const tenantId = String(formData.get("tenant_id"));
+    const slugV = String(formData.get("slug"));
+    const res = await requestProduct(tenantId, product);
+    const param = res.ok ? `ok=requested:${product}` : `err=${res.error}`;
+    redirect(`/${slugV}/catalog?${param}`);
+  }
+
+  async function doTrial(formData: FormData) {
+    "use server";
+    const product = String(formData.get("product"));
+    const tenantId = String(formData.get("tenant_id"));
+    const slugV = String(formData.get("slug"));
+    const res = await startTrial(tenantId, product);
+    const param = res.ok ? `ok=trial:${product}` : `err=${res.error}`;
+    revalidatePath(`/${slugV}/catalog`);
+    redirect(`/${slugV}/catalog?${param}`);
+  }
+
+  return (
+    <section>
+      <h1 style={{ fontSize: 28, marginBottom: 8 }}>Catalog</h1>
+      <p style={{ color: "#444", marginBottom: 16 }}>
+        Pick a product to add to your plan. Trial-eligible products start a
+        14-day evaluation; everything else opens a CRM lead for sales follow-up.
+      </p>
+
+      <FlashBanner ok={flash.ok} err={flash.err} />
+
+      <ul
+        style={{
+          listStyle: "none",
+          padding: 0,
+          display: "grid",
+          gap: 12,
+          gridTemplateColumns: "repeat(auto-fill, minmax(280px, 1fr))",
+          marginTop: 16,
+        }}
+      >
+        {catalog.map((p) => (
+          <CatalogCard
+            key={p.key}
+            product={p}
+            owned={enabled.has(p.key)}
+            tenantId={tenant.id}
+            slug={slug}
+            doRequest={doRequest}
+            doTrial={doTrial}
+          />
+        ))}
+      </ul>
+    </section>
+  );
+}
+
+function FlashBanner({ ok, err }: { ok?: string; err?: string }) {
+  if (!ok && !err) return null;
+  const isOk = !!ok;
+  return (
+    <div
+      role="status"
+      style={{
+        padding: 12,
+        borderRadius: 8,
+        marginBottom: 12,
+        background: isOk ? "#e6f7ec" : "#fdecea",
+        color: isOk ? "#0a6e2a" : "#a82626",
+        border: `1px solid ${isOk ? "#a4d8b8" : "#e8a5a5"}`,
+      }}
+    >
+      {isOk ? `OK — ${ok}` : `Error — ${err}`}
+    </div>
+  );
+}
+
+function CatalogCard({
+  product,
+  owned,
+  tenantId,
+  slug,
+  doRequest,
+  doTrial,
+}: {
+  product: CatalogEntry;
+  owned: boolean;
+  tenantId: string;
+  slug: string;
+  doRequest: (fd: FormData) => Promise<void>;
+  doTrial: (fd: FormData) => Promise<void>;
+}) {
+  return (
+    <li
+      style={{
+        padding: 16,
+        border: "1px solid #eaeaea",
+        borderRadius: 8,
+        background: "white",
+      }}
+    >
+      <strong style={{ fontSize: 15 }}>{product.name}</strong>
+      <p style={{ color: "#666", fontSize: 13, marginTop: 4, marginBottom: 12 }}>
+        {product.description}
+      </p>
+      <div style={{ fontSize: 12, color: "#666", marginBottom: 12 }}>
+        Plans: {product.plans_required.join(", ")}
+      </div>
+
+      {owned ? (
+        <span
+          style={{
+            fontSize: 12,
+            padding: "4px 8px",
+            background: "#eef",
+            borderRadius: 4,
+            color: "#226",
+          }}
+        >
+          Active
+        </span>
+      ) : (
+        <div style={{ display: "flex", gap: 8 }}>
+          <form action={doRequest}>
+            <input type="hidden" name="product" value={product.key} />
+            <input type="hidden" name="tenant_id" value={tenantId} />
+            <input type="hidden" name="slug" value={slug} />
+            <button
+              type="submit"
+              style={{
+                padding: "6px 10px",
+                background: "white",
+                color: "#0070f3",
+                border: "1px solid #0070f3",
+                borderRadius: 6,
+                fontSize: 13,
+                cursor: "pointer",
+              }}
+            >
+              Request
+            </button>
+          </form>
+
+          {product.supports_trial && (
+            <form action={doTrial}>
+              <input type="hidden" name="product" value={product.key} />
+              <input type="hidden" name="tenant_id" value={tenantId} />
+              <input type="hidden" name="slug" value={slug} />
+              <button
+                type="submit"
+                style={{
+                  padding: "6px 10px",
+                  background: "#0070f3",
+                  color: "white",
+                  border: "none",
+                  borderRadius: 6,
+                  fontSize: 13,
+                  cursor: "pointer",
+                }}
+              >
+                Start 14-day trial
+              </button>
+            </form>
+          )}
+        </div>
+      )}
+    </li>
+  );
+}

src/app/[slug]/dashboard/page.tsx

@@ -1,4 +1,7 @@
 import { auth, signIn, signOut } from "@/auth";
+import { ShellEmpty } from "@/components/ShellEmpty";
+import type { SessionWithExtras } from "@/lib/session";
+import { fetchTenantBySlug } from "@/lib/tenant-registry";
 
 export default async function Dashboard({
   params,
@@ -6,7 +9,7 @@ export default async function Dashboard({
   params: Promise<{ slug: string }>;
 }) {
   const { slug } = await params;
-  const session = await auth();
+  const session = (await auth()) as SessionWithExtras | null;
 
   if (!session) {
     async function login() {
@@ -14,12 +17,25 @@ export default async function Dashboard({
       await signIn("keycloak", { redirectTo: `/${slug}/dashboard` });
     }
     return (
-      <div>
+      <section style={{ maxWidth: 480 }}>
-        <h1>Sign in to {slug}</h1>
+        <h1 style={{ fontSize: 28, marginBottom: 12 }}>Sign in to {slug}</h1>
         <form action={login}>
-          <button type="submit">Sign in with Keycloak</button>
+          <button
+            type="submit"
+            style={{
+              padding: "10px 16px",
+              background: "#0070f3",
+              color: "white",
+              border: "none",
+              borderRadius: 6,
+              fontSize: 14,
+              cursor: "pointer",
+            }}
+          >
+            Sign in with Keycloak
+          </button>
         </form>
-      </div>
+      </section>
     );
   }
 
@@ -28,17 +44,129 @@ export default async function Dashboard({
     await signOut({ redirectTo: `/${slug}/dashboard` });
   }
 
+  const tenant = await fetchTenantBySlug(slug);
+  const products = session.products ?? [];
+  const trialDaysLeft = computeTrialDaysLeft(tenant?.trial_ends_at);
+
   return (
-    <div>
+    <section>
-      <h1>Dashboard</h1>
+      {tenant?.status === "trial" && tenant.trial_ends_at && (
-      <p>
+        <TrialBanner
-        Welcome, {session.user?.name ?? session.user?.email ?? "user"}. This is the{" "}
+          endsAt={tenant.trial_ends_at}
-        <code>{slug}</code> dashboard. Real product tiles, settings, billing — land
+          slug={slug}
-        in M5.2 / M10.1.
+          daysLeft={trialDaysLeft}
+        />
+      )}
+
+      <h1 style={{ fontSize: 28, marginBottom: 8 }}>Dashboard</h1>
+      <p style={{ color: "#444", marginBottom: 24 }}>
+        Welcome, {session.user?.name ?? session.user?.email ?? "user"}. Signed in
+        as <code>{session.org_roles?.join(", ") ?? "(no roles)"}</code>.
       </p>
-      <form action={logout} style={{ marginTop: 24 }}>
+
-        <button type="submit">Sign out</button>
+      <h2 style={{ fontSize: 18, marginTop: 24, marginBottom: 12 }}>Your products</h2>
+      {products.length === 0 ? (
+        <ShellEmpty
+          title="No products yet"
+          description="Browse the catalog and request access to a product, or start a 14-day trial."
+          milestone="M11.1"
+        />
+      ) : (
+        <ul
+          style={{
+            listStyle: "none",
+            padding: 0,
+            display: "grid",
+            gap: 12,
+            gridTemplateColumns: "repeat(auto-fill, minmax(220px, 1fr))",
+          }}
+        >
+          {products.map((p) => (
+            <li
+              key={p}
+              style={{
+                padding: 16,
+                border: "1px solid #eaeaea",
+                borderRadius: 8,
+                background: "white",
+              }}
+            >
+              <strong style={{ textTransform: "capitalize" }}>{p}</strong>
+              <p style={{ color: "#666", fontSize: 13, marginTop: 4 }}>
+                Tile content lands in <code>M10.1</code>.
+              </p>
+            </li>
+          ))}
+        </ul>
+      )}
+
+      <form action={logout} style={{ marginTop: 32 }}>
+        <button
+          type="submit"
+          style={{
+            padding: "8px 12px",
+            background: "white",
+            color: "#0070f3",
+            border: "1px solid #0070f3",
+            borderRadius: 6,
+            fontSize: 13,
+            cursor: "pointer",
+          }}
+        >
+          Sign out
+        </button>
       </form>
+    </section>
+  );
+}
+
+// Pure compute, lives outside any render path so react-hooks/purity is satisfied.
+function computeTrialDaysLeft(endsAt: string | null | undefined): number {
+  if (!endsAt) return 0;
+  const ms = new Date(endsAt).getTime() - Date.now();
+  return Math.max(0, Math.ceil(ms / (24 * 3600 * 1000)));
+}
+
+function TrialBanner({
+  endsAt,
+  slug,
+  daysLeft,
+}: {
+  endsAt: string;
+  slug: string;
+  daysLeft: number;
+}) {
+  const ends = new Date(endsAt);
+  const urgent = daysLeft <= 3;
+  return (
+    <div
+      role="status"
+      style={{
+        padding: 12,
+        marginBottom: 16,
+        borderRadius: 8,
+        background: urgent ? "#fdecea" : "#fff7e0",
+        color: urgent ? "#a82626" : "#7a5a00",
+        border: `1px solid ${urgent ? "#e8a5a5" : "#e6d28a"}`,
+        display: "flex",
+        justifyContent: "space-between",
+        alignItems: "center",
+      }}
+    >
+      <span>
+        Trial — <strong>{daysLeft}</strong> day{daysLeft === 1 ? "" : "s"} left
+        {" "}(ends {ends.toLocaleDateString()}).
+      </span>
+      <a
+        href={`/${slug}/billing`}
+        style={{
+          fontSize: 13,
+          color: urgent ? "#a82626" : "#7a5a00",
+          textDecoration: "underline",
+        }}
+      >
+        Upgrade →
+      </a>
     </div>
   );
 }

src/app/[slug]/layout.tsx

@@ -1,5 +1,8 @@
-import { notFound } from "next/navigation";
+import { notFound, redirect } from "next/navigation";
 import type { ReactNode } from "react";
+import { auth } from "@/auth";
+import { Nav } from "@/components/Nav";
+import type { SessionWithExtras } from "@/lib/session";
 import { fetchTenantBySlug } from "@/lib/tenant-registry";
 
 export default async function TenantLayout({
@@ -13,8 +16,19 @@ export default async function TenantLayout({
   const tenant = await fetchTenantBySlug(slug);
   if (!tenant) notFound();
 
+  const session = (await auth()) as SessionWithExtras | null;
+
+  // Tenant mismatch guard — a JWT scoped to tenant A must not be allowed
+  // to view tenant B. If the slug in the path doesn't match the session
+  // tenant_slug, redirect back to whatever this user CAN see.
+  if (session && session.tenant_slug && session.tenant_slug !== slug) {
+    redirect(`/${session.tenant_slug}/dashboard`);
+  }
+
   return (
-    <div>
+    <div style={{ display: "flex", minHeight: "100vh" }}>
+      {session ? <Nav slug={slug} session={session} /> : null}
+      <div style={{ flex: 1 }}>
         <header
           style={{
             padding: "12px 24px",
@@ -32,5 +46,6 @@ export default async function TenantLayout({
         </header>
         <main style={{ padding: 24 }}>{children}</main>
       </div>
+    </div>
   );
 }

src/app/[slug]/products/page.tsx

@@ -0,0 +1,118 @@
+import { redirect } from "next/navigation";
+import { auth } from "@/auth";
+import { NotAuthorized } from "@/components/ShellEmpty";
+import { formatDateTime, formatRelative } from "@/lib/format";
+import type { SessionWithExtras } from "@/lib/session";
+import { canSee } from "@/lib/session";
+import {
+  fetchCatalog,
+  fetchEntitlements,
+  fetchTenantBySlug,
+  type CatalogEntry,
+  type Entitlement,
+} from "@/lib/tenant-registry";
+
+export default async function ProductsPage({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  const { slug } = await params;
+  const session = (await auth()) as SessionWithExtras | null;
+  if (!canSee(session, "products")) return <NotAuthorized />;
+
+  const tenant = await fetchTenantBySlug(slug);
+  if (!tenant) redirect(`/${slug}/dashboard`);
+
+  const [catalog, entitlements] = await Promise.all([
+    fetchCatalog(),
+    fetchEntitlements(tenant.id),
+  ]);
+
+  const byKey = new Map(catalog.map((c) => [c.key, c]));
+  const active = entitlements.filter((e) => e.enabled);
+
+  return (
+    <section>
+      <h1 style={{ fontSize: 28, marginBottom: 8 }}>Products</h1>
+      <p style={{ color: "#444", marginBottom: 24 }}>
+        Live entitlements for <strong>{tenant.name}</strong>. Open a product to
+        use its web component (M6.x / M7.x).
+      </p>
+
+      {active.length === 0 ? (
+        <div
+          style={{
+            padding: 16,
+            border: "1px dashed #ddd",
+            borderRadius: 8,
+            background: "#fafafa",
+            color: "#666",
+            fontSize: 14,
+          }}
+        >
+          <p style={{ marginBottom: 8 }}>No products yet.</p>
+          <a href={`/${slug}/catalog`} style={{ color: "#0070f3" }}>
+            Browse the catalog →
+          </a>
+        </div>
+      ) : (
+        <ul
+          style={{
+            listStyle: "none",
+            padding: 0,
+            display: "grid",
+            gap: 12,
+            gridTemplateColumns: "repeat(auto-fill, minmax(280px, 1fr))",
+          }}
+        >
+          {active.map((e) => (
+            <ProductCard key={e.product} ent={e} catalog={byKey.get(e.product)} />
+          ))}
+        </ul>
+      )}
+    </section>
+  );
+}
+
+function ProductCard({ ent, catalog }: { ent: Entitlement; catalog?: CatalogEntry }) {
+  return (
+    <li
+      style={{
+        padding: 16,
+        border: "1px solid #eaeaea",
+        borderRadius: 8,
+        background: "white",
+      }}
+    >
+      <div
+        style={{ display: "flex", justifyContent: "space-between", alignItems: "center" }}
+      >
+        <strong style={{ fontSize: 15 }}>{catalog?.name ?? ent.product}</strong>
+        {ent.expires_at && (
+          <span
+            title={formatDateTime(ent.expires_at)}
+            style={{
+              fontSize: 11,
+              padding: "2px 8px",
+              borderRadius: 4,
+              background: "#fff7e0",
+              color: "#7a5a00",
+            }}
+          >
+            trial · {formatRelative(ent.expires_at)}
+          </span>
+        )}
+      </div>
+      {catalog?.description && (
+        <p style={{ color: "#666", fontSize: 13, marginTop: 6, marginBottom: 12 }}>
+          {catalog.description}
+        </p>
+      )}
+      <div style={{ fontSize: 12, color: "#999", marginTop: 8 }}>
+        Web component renders here once <code>{ent.product}-dashboard</code> is
+        registered (M6.3 / M7.2).
+      </div>
+    </li>
+  );
+}

src/app/[slug]/projects/page.tsx

@@ -0,0 +1,17 @@
+import { auth } from "@/auth";
+import { NotAuthorized, ShellEmpty } from "@/components/ShellEmpty";
+import type { SessionWithExtras } from "@/lib/session";
+import { canSee } from "@/lib/session";
+
+export default async function Page() {
+  const session = (await auth()) as SessionWithExtras | null;
+  if (!canSee(session, "projects")) return <NotAuthorized />;
+  return (
+    <ShellEmpty
+      title="Projects"
+      description="Sub-tenancy: scope products by team/environment (GCP-Project-style)."
+      milestone="M10.1 follow-up"
+      details="Most tenants operate as a single implicit 'default' project. Multi-project mode activates once a product opts in via manifest.supports_projects=true."
+    />
+  );
+}

src/app/[slug]/settings/api-keys/page.tsx

@@ -0,0 +1,266 @@
+import { revalidatePath } from "next/cache";
+import { redirect } from "next/navigation";
+import { auth } from "@/auth";
+import { NotAuthorized } from "@/components/ShellEmpty";
+import { formatDateTime, formatRelative, truncate } from "@/lib/format";
+import type { SessionWithExtras } from "@/lib/session";
+import { canSee } from "@/lib/session";
+import {
+  createAPIKey,
+  fetchAPIKeys,
+  fetchCatalog,
+  fetchTenantBySlug,
+  revokeAPIKey,
+  type APIKey,
+} from "@/lib/tenant-registry";
+
+export default async function APIKeysPage({
+  params,
+  searchParams,
+}: {
+  params: Promise<{ slug: string }>;
+  searchParams: Promise<{ plaintext?: string; err?: string }>;
+}) {
+  const { slug } = await params;
+  const flash = await searchParams;
+  const session = (await auth()) as SessionWithExtras | null;
+  if (!canSee(session, "api-keys")) return <NotAuthorized />;
+
+  const tenant = await fetchTenantBySlug(slug);
+  if (!tenant) redirect(`/${slug}/dashboard`);
+
+  const [keys, catalog] = await Promise.all([
+    fetchAPIKeys(tenant.id),
+    fetchCatalog(),
+  ]);
+  const active = keys.filter((k) => !k.revoked_at);
+  const revoked = keys.filter((k) => k.revoked_at);
+
+  async function doCreate(formData: FormData) {
+    "use server";
+    const name = String(formData.get("name") ?? "").trim();
+    const product = String(formData.get("product") ?? "").trim();
+    const tenantId = String(formData.get("tenant_id"));
+    const slugV = String(formData.get("slug"));
+    if (!name) redirect(`/${slugV}/settings/api-keys?err=missing_name`);
+
+    const res = await createAPIKey({
+      tenant_id: tenantId,
+      name,
+      product: product || undefined,
+    });
+    if (!res.ok) {
+      redirect(`/${slugV}/settings/api-keys?err=${res.error}`);
+    }
+    revalidatePath(`/${slugV}/settings/api-keys`);
+    redirect(`/${slugV}/settings/api-keys?plaintext=${encodeURIComponent(res.plaintext)}`);
+  }
+
+  async function doRevoke(formData: FormData) {
+    "use server";
+    const id = String(formData.get("id"));
+    const slugV = String(formData.get("slug"));
+    const res = await revokeAPIKey(id);
+    if (!res.ok) {
+      redirect(`/${slugV}/settings/api-keys?err=${res.error}`);
+    }
+    revalidatePath(`/${slugV}/settings/api-keys`);
+    redirect(`/${slugV}/settings/api-keys`);
+  }
+
+  return (
+    <section>
+      <h1 style={{ fontSize: 28, marginBottom: 8 }}>API keys</h1>
+      <p style={{ color: "#444", marginBottom: 16 }}>
+        Per-tenant keys for headless product calls. Hashed with argon2id;
+        the plaintext is shown <strong>once</strong> on creation.
+      </p>
+
+      {flash.plaintext && <PlaintextBanner plaintext={flash.plaintext} />}
+      {flash.err && <ErrorBanner err={flash.err} />}
+
+      <h2 style={{ fontSize: 18, marginTop: 24, marginBottom: 8 }}>Create a new key</h2>
+      <form action={doCreate} style={{ display: "grid", gap: 8, maxWidth: 480 }}>
+        <input type="hidden" name="tenant_id" value={tenant.id} />
+        <input type="hidden" name="slug" value={slug} />
+        <label style={{ display: "grid", gap: 4, fontSize: 14 }}>
+          <span>Name</span>
+          <input name="name" required maxLength={100} placeholder="ci-bot" style={inputStyle} />
+        </label>
+        <label style={{ display: "grid", gap: 4, fontSize: 14 }}>
+          <span>Product scope (optional)</span>
+          <select name="product" defaultValue="" style={inputStyle}>
+            <option value="">All products</option>
+            {catalog.map((p) => (
+              <option key={p.key} value={p.key}>
+                {p.name}
+              </option>
+            ))}
+          </select>
+        </label>
+        <button type="submit" style={btnPrimary}>
+          Create key
+        </button>
+      </form>
+
+      <h2 style={{ fontSize: 18, marginTop: 32, marginBottom: 8 }}>
+        Active keys ({active.length})
+      </h2>
+      {active.length === 0 ? (
+        <p style={{ color: "#666", fontSize: 14 }}>No active keys.</p>
+      ) : (
+        <KeyTable keys={active} doRevoke={doRevoke} slug={slug} canRevoke />
+      )}
+
+      {revoked.length > 0 && (
+        <>
+          <h2 style={{ fontSize: 18, marginTop: 32, marginBottom: 8 }}>
+            Revoked ({revoked.length})
+          </h2>
+          <KeyTable keys={revoked} doRevoke={doRevoke} slug={slug} canRevoke={false} />
+        </>
+      )}
+    </section>
+  );
+}
+
+function PlaintextBanner({ plaintext }: { plaintext: string }) {
+  return (
+    <div
+      role="status"
+      style={{
+        padding: 12,
+        marginTop: 8,
+        marginBottom: 8,
+        borderRadius: 8,
+        background: "#e6f7ec",
+        border: "1px solid #a4d8b8",
+      }}
+    >
+      <strong style={{ color: "#0a6e2a", fontSize: 14 }}>Key created</strong>
+      <p style={{ margin: "8px 0", fontSize: 13, color: "#444" }}>
+        Store this value — it cannot be retrieved later.
+      </p>
+      <code
+        style={{
+          display: "block",
+          padding: "8px 10px",
+          background: "white",
+          border: "1px solid #ddd",
+          borderRadius: 6,
+          fontSize: 13,
+          wordBreak: "break-all",
+        }}
+      >
+        {plaintext}
+      </code>
+    </div>
+  );
+}
+
+function ErrorBanner({ err }: { err: string }) {
+  return (
+    <div
+      role="status"
+      style={{
+        padding: 12,
+        marginTop: 8,
+        marginBottom: 8,
+        borderRadius: 8,
+        background: "#fdecea",
+        border: "1px solid #e8a5a5",
+        color: "#a82626",
+        fontSize: 14,
+      }}
+    >
+      {err === "name_taken" && "A key with that name already exists."}
+      {err === "missing_name" && "Name is required."}
+      {err === "invalid_input" && "Input failed validation."}
+      {!["name_taken", "missing_name", "invalid_input"].includes(err) && `Error: ${err}`}
+    </div>
+  );
+}
+
+function KeyTable({
+  keys,
+  doRevoke,
+  slug,
+  canRevoke,
+}: {
+  keys: APIKey[];
+  doRevoke: (fd: FormData) => Promise<void>;
+  slug: string;
+  canRevoke: boolean;
+}) {
+  return (
+    <div style={{ overflow: "auto" }}>
+      <table style={{ width: "100%", fontSize: 13, borderCollapse: "collapse" }}>
+        <thead>
+          <tr style={{ textAlign: "left", borderBottom: "1px solid #eaeaea" }}>
+            <th style={th}>Name</th>
+            <th style={th}>Prefix</th>
+            <th style={th}>Product</th>
+            <th style={th}>Created</th>
+            <th style={th}>Last used</th>
+            {canRevoke && <th style={th}></th>}
+          </tr>
+        </thead>
+        <tbody>
+          {keys.map((k) => (
+            <tr key={k.id} style={{ borderBottom: "1px solid #f0f0f0" }}>
+              <td style={td}>{truncate(k.name, 30)}</td>
+              <td style={{ ...td, fontFamily: "ui-monospace, monospace" }}>{k.prefix}…</td>
+              <td style={td}>{k.product || <em style={{ color: "#999" }}>all</em>}</td>
+              <td style={td} title={formatDateTime(k.created_at)}>
+                {formatRelative(k.created_at)}
+              </td>
+              <td style={td}>
+                {k.last_used_at ? formatRelative(k.last_used_at) : <em style={{ color: "#999" }}>never</em>}
+              </td>
+              {canRevoke && (
+                <td style={td}>
+                  <form action={doRevoke}>
+                    <input type="hidden" name="id" value={k.id} />
+                    <input type="hidden" name="slug" value={slug} />
+                    <button type="submit" style={btnDanger}>
+                      Revoke
+                    </button>
+                  </form>
+                </td>
+              )}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}
+
+const inputStyle: React.CSSProperties = {
+  padding: "8px 10px",
+  border: "1px solid #ddd",
+  borderRadius: 6,
+  fontSize: 14,
+};
+const btnPrimary: React.CSSProperties = {
+  marginTop: 4,
+  padding: "8px 14px",
+  background: "#0070f3",
+  color: "white",
+  border: "none",
+  borderRadius: 6,
+  fontSize: 14,
+  cursor: "pointer",
+  justifySelf: "start",
+};
+const btnDanger: React.CSSProperties = {
+  padding: "4px 8px",
+  background: "white",
+  color: "#a82626",
+  border: "1px solid #e8a5a5",
+  borderRadius: 4,
+  fontSize: 12,
+  cursor: "pointer",
+};
+const th: React.CSSProperties = { padding: "8px 10px", color: "#666", fontWeight: 500 };
+const td: React.CSSProperties = { padding: "8px 10px" };

src/app/[slug]/settings/integrations/page.tsx

@@ -0,0 +1,17 @@
+import { auth } from "@/auth";
+import { NotAuthorized, ShellEmpty } from "@/components/ShellEmpty";
+import type { SessionWithExtras } from "@/lib/session";
+import { canSee } from "@/lib/session";
+
+export default async function Page() {
+  const session = (await auth()) as SessionWithExtras | null;
+  if (!canSee(session, "integrations")) return <NotAuthorized />;
+  return (
+    <ShellEmpty
+      title="Integrations"
+      description="Webhooks, outbound integrations, and external IdP configuration."
+      milestone="M15.2"
+      details="Webhook delivery (signed payloads, retry-with-backoff, dead-letter queue) lands alongside the headless-product API surface."
+    />
+  );
+}

src/app/[slug]/settings/page.tsx

@@ -0,0 +1,120 @@
+import { auth } from "@/auth";
+import { NotAuthorized } from "@/components/ShellEmpty";
+import { formatDateTime } from "@/lib/format";
+import type { SessionWithExtras } from "@/lib/session";
+import { canSee } from "@/lib/session";
+import { fetchTenantBySlug } from "@/lib/tenant-registry";
+
+export default async function SettingsPage({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  const { slug } = await params;
+  const session = (await auth()) as SessionWithExtras | null;
+  if (!canSee(session, "settings")) return <NotAuthorized />;
+
+  const tenant = await fetchTenantBySlug(slug);
+  if (!tenant) {
+    return (
+      <section>
+        <h1 style={{ fontSize: 28 }}>Settings</h1>
+        <p style={{ color: "#a82626" }}>Tenant not found.</p>
+      </section>
+    );
+  }
+
+  return (
+    <section>
+      <h1 style={{ fontSize: 28, marginBottom: 8 }}>Settings</h1>
+      <p style={{ color: "#444", marginBottom: 24 }}>
+        Tenant identity and lifecycle metadata. Editing these lands in the
+        M10.1 follow-up; for now contact <a href={`/${slug}/support`}>support</a>.
+      </p>
+
+      <h2 style={{ fontSize: 18, marginTop: 16, marginBottom: 8 }}>Identity</h2>
+      <Field label="Tenant ID" value={tenant.id} mono />
+      <Field label="Slug" value={tenant.slug} mono />
+      <Field label="Name" value={tenant.name} />
+      <Field label="Kind" value={tenant.kind} />
+
+      <h2 style={{ fontSize: 18, marginTop: 24, marginBottom: 8 }}>Plan & status</h2>
+      <Field label="Plan" value={tenant.plan} />
+      <Field label="Status" value={tenant.status} badge={statusColor(tenant.status)} />
+      {tenant.trial_ends_at && (
+        <Field label="Trial ends at" value={formatDateTime(tenant.trial_ends_at)} mono />
+      )}
+
+      <h2 style={{ fontSize: 18, marginTop: 24, marginBottom: 8 }}>Audit</h2>
+      <Field label="Created" value={formatDateTime(tenant.created_at)} mono />
+      <Field label="Last updated" value={formatDateTime(tenant.updated_at)} mono />
+
+      <h2 style={{ fontSize: 18, marginTop: 24, marginBottom: 8 }}>External links</h2>
+      <p style={{ fontSize: 13, color: "#666" }}>
+        ERPNext customer + Polar subscription land in M8.3; rendered here when
+        the IDs land on the tenant row.
+      </p>
+    </section>
+  );
+}
+
+function Field({
+  label,
+  value,
+  mono,
+  badge,
+}: {
+  label: string;
+  value: string;
+  mono?: boolean;
+  badge?: string;
+}) {
+  return (
+    <div style={{ display: "flex", padding: "6px 0", borderBottom: "1px solid #f0f0f0" }}>
+      <span style={{ width: 160, color: "#666", fontSize: 13 }}>{label}</span>
+      <span
+        style={{
+          fontFamily: mono
+            ? "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace"
+            : "inherit",
+          fontSize: mono ? 13 : 14,
+        }}
+      >
+        {badge ? (
+          <span
+            style={{
+              padding: "2px 8px",
+              borderRadius: 4,
+              background: badge,
+              color: "#fff",
+              fontSize: 12,
+              textTransform: "uppercase",
+              letterSpacing: 0.4,
+            }}
+          >
+            {value}
+          </span>
+        ) : (
+          value
+        )}
+      </span>
+    </div>
+  );
+}
+
+function statusColor(s: string): string {
+  switch (s) {
+    case "active":
+      return "#1a7a3e";
+    case "trial":
+      return "#a87a00";
+    case "frozen":
+      return "#a82626";
+    case "archived":
+      return "#666";
+    case "demo":
+      return "#0070f3";
+    default:
+      return "#444";
+  }
+}

src/app/[slug]/settings/users/page.tsx

@@ -0,0 +1,17 @@
+import { auth } from "@/auth";
+import { NotAuthorized, ShellEmpty } from "@/components/ShellEmpty";
+import type { SessionWithExtras } from "@/lib/session";
+import { canSee } from "@/lib/session";
+
+export default async function Page() {
+  const session = (await auth()) as SessionWithExtras | null;
+  if (!canSee(session, "users")) return <NotAuthorized />;
+  return (
+    <ShellEmpty
+      title="Users"
+      description="Invite teammates as IT_ADMIN, CXO, FINANCE, LEGAL, or USER."
+      milestone="M10.1 follow-up"
+      details="User management calls Keycloak's Organizations Admin API. The adapter exists (internal/keycloak in tenant-registry); this UI just needs the list + invite handlers wired."
+    />
+  );
+}

src/app/[slug]/support/page.tsx

@@ -0,0 +1,17 @@
+import { auth } from "@/auth";
+import { NotAuthorized, ShellEmpty } from "@/components/ShellEmpty";
+import type { SessionWithExtras } from "@/lib/session";
+import { canSee } from "@/lib/session";
+
+export default async function Page() {
+  const session = (await auth()) as SessionWithExtras | null;
+  if (!canSee(session, "support")) return <NotAuthorized />;
+  return (
+    <ShellEmpty
+      title="Support"
+      description="Submit a ticket — Frappe HD's customer portal embedded here."
+      milestone="M9.1"
+      details="Email oncall@breakpilot.com in the meantime. Tickets that need engineering attention escalate into Gitea issues automatically (M9.2)."
+    />
+  );
+}

src/app/__backstage__/page.tsx

@@ -0,0 +1,30 @@
+import { auth } from "@/auth";
+import type { SessionWithExtras } from "@/lib/session";
+
+// Backstage — platform-staff-only surface. The middleware rewrites
+// http://backstage.localhost:3000/* → /__backstage__/* so this is
+// reachable only via that hostname. Real RBAC (BREAKPILOT_ADMIN /
+// SUPPORT_ENGINEER / SALES_REP) lands in M13.2.
+
+export default async function Backstage() {
+  const session = (await auth()) as SessionWithExtras | null;
+  if (!session) {
+    return (
+      <section style={{ padding: 32 }}>
+        <h1 style={{ fontSize: 28, marginBottom: 8 }}>Backstage</h1>
+        <p>Sign in with a BREAKPILOT_ADMIN / SUPPORT_ENGINEER / SALES_REP account.</p>
+      </section>
+    );
+  }
+  return (
+    <section style={{ padding: 32 }}>
+      <h1 style={{ fontSize: 28, marginBottom: 8 }}>Backstage</h1>
+      <p>
+        Signed in as <code>{session.user?.email}</code>.
+      </p>
+      <p style={{ marginTop: 24, color: "#666" }}>
+        Tenants list, leads, demo console, impersonation — all land in M13.2 / M14.x.
+      </p>
+    </section>
+  );
+}

src/app/start/page.tsx

@@ -0,0 +1,138 @@
+import { redirect } from "next/navigation";
+import { createTenant } from "@/lib/tenant-registry";
+
+// Public self-serve signup. Apex-level; no slug. Creates a trial tenant
+// via tenant-registry, which also provisions a Keycloak organization +
+// invites the user as IT_ADMIN. The portal middleware rewrites
+// signup.<apex> here, but the bare path also works for dev.
+//
+// After success the user lands at /<slug>/dashboard. In prod they'd
+// follow the KC invite email to set a password; in dev (no Stalwart yet)
+// the invite_url is logged for the operator to share manually.
+
+export default async function StartPage({
+  searchParams,
+}: {
+  searchParams: Promise<{ err?: string }>;
+}) {
+  const flash = await searchParams;
+
+  async function submit(formData: FormData) {
+    "use server";
+    const slug = String(formData.get("slug") ?? "").trim().toLowerCase();
+    const name = String(formData.get("name") ?? "").trim();
+    const email = String(formData.get("email") ?? "").trim();
+    const plan =
+      (String(formData.get("plan") ?? "starter") as "starter" | "professional" | "enterprise") ||
+      "starter";
+
+    if (!slug || !name || !email) {
+      redirect("/start?err=missing_fields");
+    }
+    const res = await createTenant({
+      slug,
+      name,
+      plan,
+      admin_email: email,
+    });
+    if (!res.ok) {
+      redirect(`/start?err=${res.error}`);
+    }
+    redirect(`/${res.tenant.slug}/dashboard?ok=created`);
+  }
+
+  return (
+    <main style={{ maxWidth: 480, margin: "10vh auto", padding: "0 24px" }}>
+      <h1 style={{ fontSize: 28, marginBottom: 8 }}>Start a 14-day trial</h1>
+      <p style={{ color: "#444", marginBottom: 24 }}>
+        Spin up your tenant. You&apos;ll get an email invite from Keycloak with
+        a link to set your password.
+      </p>
+
+      {flash.err && (
+        <div
+          role="status"
+          style={{
+            padding: 12,
+            borderRadius: 8,
+            marginBottom: 16,
+            background: "#fdecea",
+            color: "#a82626",
+            border: "1px solid #e8a5a5",
+            fontSize: 14,
+          }}
+        >
+          {flash.err === "slug_taken" && "That slug is already in use. Pick another."}
+          {flash.err === "invalid_input" && "Slug must be 3+ chars, lowercase letters / digits / hyphens."}
+          {flash.err === "missing_fields" && "All fields are required."}
+          {!["slug_taken", "invalid_input", "missing_fields"].includes(flash.err) &&
+            `Something broke: ${flash.err}`}
+        </div>
+      )}
+
+      <form action={submit} style={{ display: "grid", gap: 12 }}>
+        <label style={{ display: "grid", gap: 4, fontSize: 14 }}>
+          <span>Tenant slug</span>
+          <input
+            name="slug"
+            required
+            placeholder="acme"
+            pattern="^[a-z0-9][a-z0-9-]{1,38}[a-z0-9]$"
+            style={inputStyle}
+          />
+          <small style={{ color: "#666" }}>
+            Becomes <code>&lt;slug&gt;.breakpilot.com</code>. Lowercase, hyphens allowed.
+          </small>
+        </label>
+
+        <label style={{ display: "grid", gap: 4, fontSize: 14 }}>
+          <span>Company name</span>
+          <input name="name" required placeholder="Acme Inc." style={inputStyle} />
+        </label>
+
+        <label style={{ display: "grid", gap: 4, fontSize: 14 }}>
+          <span>Admin email</span>
+          <input
+            name="email"
+            type="email"
+            required
+            placeholder="you@acme.test"
+            style={inputStyle}
+          />
+        </label>
+
+        <label style={{ display: "grid", gap: 4, fontSize: 14 }}>
+          <span>Plan</span>
+          <select name="plan" defaultValue="starter" style={inputStyle}>
+            <option value="starter">Starter</option>
+            <option value="professional">Professional</option>
+            <option value="enterprise">Enterprise</option>
+          </select>
+        </label>
+
+        <button
+          type="submit"
+          style={{
+            marginTop: 8,
+            padding: "10px 16px",
+            background: "#0070f3",
+            color: "white",
+            border: "none",
+            borderRadius: 6,
+            fontSize: 14,
+            cursor: "pointer",
+          }}
+        >
+          Start trial
+        </button>
+      </form>
+    </main>
+  );
+}
+
+const inputStyle: React.CSSProperties = {
+  padding: "8px 10px",
+  border: "1px solid #ddd",
+  borderRadius: 6,
+  fontSize: 14,
+};

src/components/Nav.tsx

@@ -0,0 +1,40 @@
+import Link from "next/link";
+import type { Surface, SessionWithExtras } from "@/lib/session";
+import { canSee } from "@/lib/session";
+
+type NavLink = {
+  href: string;
+  label: string;
+  surface: Surface;
+};
+
+export function Nav({ slug, session }: { slug: string; session: SessionWithExtras }) {
+  const links: NavLink[] = [
+    { href: `/${slug}/dashboard`,    label: "Dashboard",    surface: "dashboard" },
+    { href: `/${slug}/products`,     label: "Products",     surface: "products" },
+    { href: `/${slug}/catalog`,      label: "Catalog",      surface: "catalog" },
+    { href: `/${slug}/projects`,     label: "Projects",     surface: "projects" },
+    { href: `/${slug}/settings`,     label: "Settings",     surface: "settings" },
+    { href: `/${slug}/settings/users`,   label: "Users",        surface: "users" },
+    { href: `/${slug}/settings/api-keys`,  label: "API keys",   surface: "api-keys" },
+    { href: `/${slug}/settings/integrations`, label: "Integrations", surface: "integrations" },
+    { href: `/${slug}/billing`,      label: "Billing",      surface: "billing" },
+    { href: `/${slug}/audit`,        label: "Audit log",    surface: "audit" },
+    { href: `/${slug}/support`,      label: "Support",      surface: "support" },
+  ];
+  const visible = links.filter((l) => canSee(session, l.surface));
+
+  return (
+    <nav style={{ width: 220, padding: 16, borderRight: "1px solid #eaeaea", background: "white" }}>
+      <ul style={{ listStyle: "none", padding: 0, margin: 0 }}>
+        {visible.map((l) => (
+          <li key={l.href} style={{ margin: "8px 0" }}>
+            <Link href={l.href} style={{ color: "#0070f3", textDecoration: "none" }}>
+              {l.label}
+            </Link>
+          </li>
+        ))}
+      </ul>
+    </nav>
+  );
+}

src/components/ShellEmpty.tsx

@@ -0,0 +1,63 @@
+// Empty state for surfaces whose real backend hasn't shipped yet.
+// `milestone` names the milestone that unblocks the surface; `cta` is an
+// optional in-portal action (link or button) the user can take in the
+// meantime (e.g., "Browse the catalog" while real billing waits on M8.3).
+
+import type { ReactNode } from "react";
+
+export function ShellEmpty({
+  title,
+  description,
+  milestone,
+  details,
+  cta,
+}: {
+  title: string;
+  description: string;
+  milestone: string;
+  details?: string;
+  cta?: ReactNode;
+}) {
+  return (
+    <section style={{ maxWidth: 720 }}>
+      <h1 style={{ fontSize: 28, marginBottom: 8 }}>{title}</h1>
+      <p style={{ color: "#444", marginBottom: 24 }}>{description}</p>
+      <div
+        style={{
+          padding: 16,
+          border: "1px dashed #ddd",
+          borderRadius: 8,
+          background: "#fafafa",
+          color: "#666",
+          fontSize: 14,
+        }}
+      >
+        <div style={{ marginBottom: details ? 8 : 0 }}>
+          Lands in <code>{milestone}</code>. See{" "}
+          <a
+            href="https://gitea.meghsakha.com/platform/docs/src/branch/main/PLATFORM_ARCHITECTURE.md"
+            style={{ color: "#0070f3" }}
+          >
+            PLATFORM_ARCHITECTURE.md §5a
+          </a>
+          .
+        </div>
+        {details && <p style={{ marginTop: 8, marginBottom: 0 }}>{details}</p>}
+        {cta && <div style={{ marginTop: 12 }}>{cta}</div>}
+      </div>
+    </section>
+  );
+}
+
+export function NotAuthorized() {
+  return (
+    <section style={{ maxWidth: 720 }}>
+      <h1 style={{ fontSize: 28, marginBottom: 8 }}>403 — Not authorized</h1>
+      <p style={{ color: "#444" }}>
+        This surface requires a role your account doesn&apos;t have. If you think
+        that&apos;s a mistake, ask an IT_ADMIN on your tenant to invite you with
+        the right role.
+      </p>
+    </section>
+  );
+}

src/lib/format.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from "vitest";
+import { formatDateTime, formatRelative, truncate } from "./format";
+
+describe("formatRelative", () => {
+  const NOW = new Date("2026-05-20T12:00:00Z").getTime();
+  test("seconds ago", () => {
+    expect(formatRelative("2026-05-20T11:59:50Z", NOW)).toBe("10 seconds ago");
+  });
+  test("singular unit", () => {
+    expect(formatRelative("2026-05-20T11:59:59Z", NOW)).toBe("1 second ago");
+  });
+  test("minutes ago", () => {
+    expect(formatRelative("2026-05-20T11:55:00Z", NOW)).toBe("5 minutes ago");
+  });
+  test("hours ago", () => {
+    expect(formatRelative("2026-05-20T09:00:00Z", NOW)).toBe("3 hours ago");
+  });
+  test("days ago", () => {
+    expect(formatRelative("2026-05-13T12:00:00Z", NOW)).toBe("1 week ago");
+  });
+  test("future", () => {
+    expect(formatRelative("2026-06-03T12:00:00Z", NOW)).toBe("in 2 weeks");
+  });
+  test("malformed input returns the input", () => {
+    expect(formatRelative("not-a-date", NOW)).toBe("not-a-date");
+  });
+  test("years ago", () => {
+    expect(formatRelative("2024-05-20T12:00:00Z", NOW)).toBe("2 years ago");
+  });
+  test("months ago", () => {
+    expect(formatRelative("2026-01-20T12:00:00Z", NOW)).toBe("4 months ago");
+  });
+});
+
+describe("formatDateTime", () => {
+  test("formats UTC", () => {
+    expect(formatDateTime("2026-05-20T12:34:56Z")).toBe("2026-05-20 12:34:56 UTC");
+  });
+  test("malformed input returns input", () => {
+    expect(formatDateTime("nope")).toBe("nope");
+  });
+});
+
+describe("truncate", () => {
+  test("short string unchanged", () => {
+    expect(truncate("hi", 10)).toBe("hi");
+  });
+  test("long string truncated with ellipsis", () => {
+    expect(truncate("abcdefghij", 6)).toBe("abcde…");
+  });
+  test("default max", () => {
+    expect(truncate("x".repeat(50)).length).toBe(40);
+  });
+});

src/lib/format.ts

@@ -0,0 +1,56 @@
+// Lightweight date/time helpers — shared across server components so we
+// don't reinvent toLocaleString conventions per page.
+
+export function formatRelative(iso: string, now: number = Date.now()): string {
+  const t = new Date(iso).getTime();
+  if (Number.isNaN(t)) return iso;
+  const diff = t - now;
+  const abs = Math.abs(diff);
+  const ago = diff < 0;
+  const units: [string, number][] = [
+    ["second", 1000],
+    ["minute", 60 * 1000],
+    ["hour", 3600 * 1000],
+    ["day", 24 * 3600 * 1000],
+    ["week", 7 * 24 * 3600 * 1000],
+    ["month", 30 * 24 * 3600 * 1000],
+    ["year", 365 * 24 * 3600 * 1000],
+  ];
+  let unit = "second";
+  let n = Math.round(abs / 1000);
+  for (let i = units.length - 1; i >= 0; i--) {
+    if (abs >= units[i][1]) {
+      unit = units[i][0];
+      n = Math.round(abs / units[i][1]);
+      break;
+    }
+  }
+  const suffix = n === 1 ? unit : `${unit}s`;
+  return ago ? `${n} ${suffix} ago` : `in ${n} ${suffix}`;
+}
+
+export function formatDateTime(iso: string): string {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return iso;
+  // YYYY-MM-DD HH:MM:SS — locale-stable, sortable, no surprises.
+  const pad = (n: number) => String(n).padStart(2, "0");
+  return (
+    d.getUTCFullYear() +
+    "-" +
+    pad(d.getUTCMonth() + 1) +
+    "-" +
+    pad(d.getUTCDate()) +
+    " " +
+    pad(d.getUTCHours()) +
+    ":" +
+    pad(d.getUTCMinutes()) +
+    ":" +
+    pad(d.getUTCSeconds()) +
+    " UTC"
+  );
+}
+
+export function truncate(s: string, max = 40): string {
+  if (s.length <= max) return s;
+  return s.slice(0, max - 1) + "…";
+}

src/lib/session.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, test } from "vitest";
+import { canSee, hasAnyOrgRole, hasOrgRole, hasProduct } from "./session";
+import type { SessionWithExtras } from "./session";
+
+function s(roles: SessionWithExtras["org_roles"], products: string[] = []): SessionWithExtras {
+  return {
+    user: { name: "Test", email: "t@x.test" },
+    expires: "2099-01-01T00:00:00Z",
+    org_roles: roles,
+    products,
+  };
+}
+
+describe("hasOrgRole", () => {
+  test("null session has no roles", () => {
+    expect(hasOrgRole(null, "IT_ADMIN")).toBe(false);
+  });
+  test("matches single role", () => {
+    expect(hasOrgRole(s(["CXO"]), "CXO")).toBe(true);
+    expect(hasOrgRole(s(["CXO"]), "IT_ADMIN")).toBe(false);
+  });
+});
+
+describe("hasAnyOrgRole", () => {
+  test("any match wins", () => {
+    expect(hasAnyOrgRole(s(["LEGAL"]), ["IT_ADMIN", "LEGAL"])).toBe(true);
+    expect(hasAnyOrgRole(s(["USER"]), ["IT_ADMIN", "CXO"])).toBe(false);
+  });
+  test("empty roles", () => {
+    expect(hasAnyOrgRole(s(undefined), ["IT_ADMIN"])).toBe(false);
+  });
+});
+
+describe("hasProduct", () => {
+  test("checks products array", () => {
+    expect(hasProduct(s(["USER"], ["certifai"]), "certifai")).toBe(true);
+    expect(hasProduct(s(["USER"], ["certifai"]), "compliance")).toBe(false);
+    expect(hasProduct(null, "certifai")).toBe(false);
+  });
+});
+
+describe("canSee", () => {
+  test("IT_ADMIN sees settings, USER does not", () => {
+    expect(canSee(s(["IT_ADMIN"]), "settings")).toBe(true);
+    expect(canSee(s(["USER"]), "settings")).toBe(false);
+  });
+  test("CXO can see billing", () => {
+    expect(canSee(s(["CXO"]), "billing")).toBe(true);
+  });
+  test("LEGAL can see audit but not settings", () => {
+    expect(canSee(s(["LEGAL"]), "audit")).toBe(true);
+    expect(canSee(s(["LEGAL"]), "settings")).toBe(false);
+  });
+  test("FINANCE sees billing but not settings", () => {
+    expect(canSee(s(["FINANCE"]), "billing")).toBe(true);
+    expect(canSee(s(["FINANCE"]), "settings")).toBe(false);
+  });
+  test("dashboard visible to everyone with any role", () => {
+    expect(canSee(s(["USER"]), "dashboard")).toBe(true);
+    expect(canSee(s(["LEGAL"]), "dashboard")).toBe(true);
+  });
+  test("null session sees nothing", () => {
+    expect(canSee(null, "dashboard")).toBe(false);
+  });
+});

src/lib/session.ts

@@ -0,0 +1,70 @@
+// Session-derived types & helpers — keep all session-shape knowledge in
+// one place so route components don't all repeat the same casts.
+//
+// The breakpilot-dev realm projects these claims into every JWT via
+// protocol mappers (see platform/orca-platform/dev/keycloak/realm-export.json).
+// Auth.js v5 callbacks copy them onto the session in src/auth.ts.
+
+import type { Session } from "next-auth";
+
+export type OrgRole = "IT_ADMIN" | "CXO" | "FINANCE" | "LEGAL" | "USER";
+export type TenantStatus = "demo" | "trial" | "active" | "frozen" | "archived";
+export type Plan = "starter" | "professional" | "enterprise";
+
+export type SessionExtras = {
+  tenant_id?: string;
+  tenant_slug?: string;
+  org_roles?: OrgRole[];
+  products?: string[];
+  plan?: Plan;
+  tenant_status?: TenantStatus;
+};
+
+export type SessionWithExtras = Session & SessionExtras;
+
+export function hasOrgRole(s: SessionWithExtras | null, role: OrgRole): boolean {
+  return !!s?.org_roles?.includes(role);
+}
+
+export function hasAnyOrgRole(s: SessionWithExtras | null, roles: OrgRole[]): boolean {
+  if (!s?.org_roles) return false;
+  return roles.some((r) => s.org_roles?.includes(r));
+}
+
+export function hasProduct(s: SessionWithExtras | null, product: string): boolean {
+  return !!s?.products?.includes(product);
+}
+
+// Permission matrix per PLATFORM_ARCHITECTURE.md §5a "Operating principles":
+// hide what the user can't access. Each portal surface declares which
+// org_roles can see it; the nav uses this to filter links.
+export type Surface =
+  | "dashboard"
+  | "products"
+  | "projects"
+  | "settings"
+  | "users"
+  | "api-keys"
+  | "integrations"
+  | "billing"
+  | "audit"
+  | "support"
+  | "catalog";
+
+export const surfaceRoles: Record<Surface, OrgRole[]> = {
+  dashboard:    ["IT_ADMIN", "CXO", "FINANCE", "LEGAL", "USER"],
+  products:     ["IT_ADMIN", "CXO", "FINANCE", "LEGAL", "USER"],
+  projects:     ["IT_ADMIN", "CXO"],
+  settings:     ["IT_ADMIN"],
+  users:        ["IT_ADMIN"],
+  "api-keys":   ["IT_ADMIN"],
+  integrations: ["IT_ADMIN"],
+  billing:      ["IT_ADMIN", "CXO", "FINANCE"],
+  audit:        ["IT_ADMIN", "CXO", "LEGAL"],
+  support:      ["IT_ADMIN", "CXO", "FINANCE", "LEGAL", "USER"],
+  catalog:      ["IT_ADMIN", "CXO"],
+};
+
+export function canSee(s: SessionWithExtras | null, surface: Surface): boolean {
+  return hasAnyOrgRole(s, surfaceRoles[surface]);
+}

src/lib/tenant-registry.test.ts

@@ -1,14 +1,27 @@
 import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
-import { fetchTenantBySlug, type Tenant } from "./tenant-registry";
+import {
+  createAPIKey,
+  createTenant,
+  fetchAPIKeys,
+  fetchAudit,
+  fetchCatalog,
+  fetchEntitlements,
+  fetchTenantBySlug,
+  requestProduct,
+  revokeAPIKey,
+  startTrial,
+  type Tenant,
+} from "./tenant-registry";
 
 const SAMPLE: Tenant = {
   id: "00000000-0000-0000-0000-000000000001",
   slug: "acme",
   name: "Acme Inc.",
   status: "active",
+  kind: "customer",
   plan: "professional",
-  products: ["certifai", "compliance"],
   created_at: "2026-05-18T22:00:00Z",
+  updated_at: "2026-05-18T22:00:00Z",
 };
 
 const originalFetch = globalThis.fetch;
@@ -20,45 +33,288 @@ afterEach(() => {
   vi.restoreAllMocks();
 });
 
-describe("fetchTenantBySlug", () => {
+beforeEach(() => {
-  beforeEach(() => {
   process.env.TENANT_REGISTRY_URL = "http://test:1234";
-  });
+});
 
-  test("200 → parsed tenant", async () => {
+function mockJSON(status: number, body: unknown) {
-    globalThis.fetch = vi.fn(async () => new Response(JSON.stringify(SAMPLE), { status: 200 }));
+  return vi.fn<typeof fetch>(async () =>
-    const t = await fetchTenantBySlug("acme");
+    new Response(JSON.stringify(body), {
-    expect(t).toEqual(SAMPLE);
+      status,
-  });
+      headers: { "content-type": "application/json" },
-
+    }),
-  test("404 → null", async () => {
-    globalThis.fetch = vi.fn(async () => new Response("", { status: 404 }));
-    const t = await fetchTenantBySlug("nope");
-    expect(t).toBeNull();
-  });
-
-  test("500 → throws", async () => {
-    globalThis.fetch = vi.fn(async () => new Response("", { status: 500, statusText: "boom" }));
-    await expect(fetchTenantBySlug("acme")).rejects.toThrow(/tenant-registry: 500/);
-  });
-
-  test("falls back to default base URL when env unset", async () => {
-    delete process.env.TENANT_REGISTRY_URL;
-    const fetchSpy = vi.fn(async () => new Response(JSON.stringify(SAMPLE), { status: 200 }));
-    globalThis.fetch = fetchSpy;
-    await fetchTenantBySlug("acme");
-    expect(fetchSpy).toHaveBeenCalledWith(
-      "http://localhost:8080/v1/tenants/by-slug/acme",
-      expect.any(Object),
   );
-  });
+}
 
-  test("encodes slug to defend against weird input", async () => {
+describe("fetchTenantBySlug", () => {
-    const fetchSpy = vi.fn<typeof fetch>(async () => new Response("", { status: 404 }));
+  test("200 → parsed tenant", async () => {
-    globalThis.fetch = fetchSpy;
+    globalThis.fetch = mockJSON(200, SAMPLE);
+    expect(await fetchTenantBySlug("acme")).toEqual(SAMPLE);
+  });
+  test("404 → null", async () => {
+    globalThis.fetch = mockJSON(404, {});
+    expect(await fetchTenantBySlug("nope")).toBeNull();
+  });
+  test("500 → throws", async () => {
+    globalThis.fetch = mockJSON(500, {});
+    await expect(fetchTenantBySlug("acme")).rejects.toThrow(/500/);
+  });
+  test("default base URL", async () => {
+    delete process.env.TENANT_REGISTRY_URL;
+    const spy = mockJSON(200, SAMPLE);
+    globalThis.fetch = spy;
+    await fetchTenantBySlug("acme");
+    expect(spy.mock.calls[0]![0]).toBe("http://localhost:8090/v1/tenants/by-slug/acme");
+  });
+  test("encodes slug", async () => {
+    const spy = mockJSON(404, {});
+    globalThis.fetch = spy;
     await fetchTenantBySlug("a/b c");
-    const firstCall = fetchSpy.mock.calls[0];
+    expect(spy.mock.calls[0]![0]).toBe("http://test:1234/v1/tenants/by-slug/a%2Fb%20c");
-    expect(firstCall).toBeDefined();
+  });
-    expect(firstCall![0]).toBe("http://test:1234/v1/tenants/by-slug/a%2Fb%20c");
+});
+
+describe("fetchCatalog", () => {
+  test("returns items[]", async () => {
+    globalThis.fetch = mockJSON(200, {
+      items: [
+        { key: "certifai", name: "CERTifAI", description: "x", plans_required: [], supports_trial: true },
+      ],
+    });
+    const list = await fetchCatalog();
+    expect(list).toHaveLength(1);
+    expect(list[0].key).toBe("certifai");
+  });
+  test("non-200 throws", async () => {
+    globalThis.fetch = mockJSON(500, {});
+    await expect(fetchCatalog()).rejects.toThrow();
+  });
+});
+
+describe("fetchEntitlements", () => {
+  test("happy path", async () => {
+    globalThis.fetch = mockJSON(200, {
+      items: [{ tenant_id: "t1", product: "certifai", enabled: true, config: {} }],
+    });
+    expect(await fetchEntitlements("t1")).toHaveLength(1);
+  });
+  test("404 → []", async () => {
+    globalThis.fetch = mockJSON(404, {});
+    expect(await fetchEntitlements("t1")).toEqual([]);
+  });
+});
+
+describe("requestProduct", () => {
+  test("202 → ok", async () => {
+    globalThis.fetch = mockJSON(202, { status: "accepted" });
+    expect(await requestProduct("t1", "certifai")).toEqual({ ok: true });
+  });
+  test("404 maps to tenant_not_found", async () => {
+    globalThis.fetch = mockJSON(404, {});
+    expect(await requestProduct("t1", "certifai")).toEqual({
+      ok: false,
+      error: "tenant_not_found",
+    });
+  });
+  test("400 maps to invalid_input", async () => {
+    globalThis.fetch = mockJSON(400, {});
+    expect(await requestProduct("t1", "x")).toEqual({ ok: false, error: "invalid_input" });
+  });
+  test("unexpected status surfaces with code", async () => {
+    globalThis.fetch = mockJSON(503, {});
+    expect(await requestProduct("t1", "x")).toEqual({ ok: false, error: "unexpected_503" });
+  });
+});
+
+describe("startTrial", () => {
+  test("201 → entitlement", async () => {
+    globalThis.fetch = mockJSON(201, {
+      tenant_id: "t1", product: "certifai", enabled: true, config: { source: "trial" },
+    });
+    const res = await startTrial("t1", "certifai");
+    expect(res.ok).toBe(true);
+    if (res.ok) expect(res.entitlement.product).toBe("certifai");
+  });
+  test("400 maps to invalid_input", async () => {
+    globalThis.fetch = mockJSON(400, {});
+    expect(await startTrial("t1", "x")).toEqual({ ok: false, error: "invalid_input" });
+  });
+});
+
+describe("createTenant", () => {
+  test("201 returns tenant", async () => {
+    globalThis.fetch = mockJSON(201, {
+      tenant: SAMPLE,
+      invite_url: "http://mock/invite",
+    });
+    const res = await createTenant({ slug: "x", name: "X", admin_email: "a@b.test" });
+    expect(res.ok).toBe(true);
+    if (res.ok) {
+      expect(res.tenant.slug).toBe("acme");
+      expect(res.invite_url).toBe("http://mock/invite");
+    }
+  });
+  test("409 maps to slug_taken", async () => {
+    globalThis.fetch = mockJSON(409, {});
+    expect(await createTenant({ slug: "x", name: "X" })).toEqual({
+      ok: false,
+      error: "slug_taken",
+    });
+  });
+});
+
+describe("coverage gaps", () => {
+  test("startTrial 404 maps to tenant_not_found", async () => {
+    globalThis.fetch = mockJSON(404, {});
+    expect(await startTrial("t1", "x")).toEqual({
+      ok: false,
+      error: "tenant_not_found",
+    });
+  });
+  test("startTrial unexpected status surfaces with code", async () => {
+    globalThis.fetch = mockJSON(503, {});
+    expect(await startTrial("t1", "x")).toEqual({ ok: false, error: "unexpected_503" });
+  });
+  test("createTenant 400 maps to invalid_input", async () => {
+    globalThis.fetch = mockJSON(400, {});
+    expect(await createTenant({ slug: "x", name: "X" })).toEqual({
+      ok: false,
+      error: "invalid_input",
+    });
+  });
+  test("createTenant unexpected status surfaces with code", async () => {
+    globalThis.fetch = mockJSON(500, {});
+    expect(await createTenant({ slug: "x", name: "X" })).toEqual({
+      ok: false,
+      error: "unexpected_500",
+    });
+  });
+  test("req() handles 204 with null data", async () => {
+    // Use a verb that returns 204 — none of our endpoints do, but make sure
+    // the helper handles it. Simulate via fetchEntitlements with 204.
+    globalThis.fetch = vi.fn<typeof fetch>(async () => new Response(null, { status: 204 }));
+    await expect(fetchEntitlements("t1")).rejects.toThrow();
+  });
+  test("fetchCatalog with no data throws", async () => {
+    globalThis.fetch = vi.fn<typeof fetch>(async () =>
+      new Response("not-json", { status: 200, headers: { "content-type": "text/plain" } }),
+    );
+    await expect(fetchCatalog()).rejects.toThrow();
+  });
+});
+
+describe("fetchAPIKeys", () => {
+  test("happy path", async () => {
+    globalThis.fetch = mockJSON(200, {
+      items: [
+        { id: "1", tenant_id: "t1", name: "k1", scopes: [], prefix: "bp_a", created_at: "x" },
+      ],
+    });
+    const list = await fetchAPIKeys("t1");
+    expect(list).toHaveLength(1);
+  });
+  test("404 → []", async () => {
+    globalThis.fetch = mockJSON(404, {});
+    expect(await fetchAPIKeys("t1")).toEqual([]);
+  });
+  test("non-200 throws", async () => {
+    globalThis.fetch = mockJSON(500, {});
+    await expect(fetchAPIKeys("t1")).rejects.toThrow();
+  });
+});
+
+describe("createAPIKey", () => {
+  test("201 returns plaintext", async () => {
+    globalThis.fetch = mockJSON(201, {
+      api_key: { id: "1", tenant_id: "t1", name: "k", scopes: [], prefix: "bp_a", created_at: "x" },
+      plaintext: "bp_abc123",
+    });
+    const res = await createAPIKey({ tenant_id: "t1", name: "k" });
+    expect(res.ok).toBe(true);
+    if (res.ok) expect(res.plaintext).toBe("bp_abc123");
+  });
+  test("404 → tenant_not_found", async () => {
+    globalThis.fetch = mockJSON(404, {});
+    expect(await createAPIKey({ tenant_id: "t1", name: "k" })).toEqual({
+      ok: false,
+      error: "tenant_not_found",
+    });
+  });
+  test("400 → invalid_input", async () => {
+    globalThis.fetch = mockJSON(400, {});
+    expect(await createAPIKey({ tenant_id: "t1", name: "" })).toEqual({
+      ok: false,
+      error: "invalid_input",
+    });
+  });
+  test("409 → name_taken", async () => {
+    globalThis.fetch = mockJSON(409, {});
+    expect(await createAPIKey({ tenant_id: "t1", name: "k" })).toEqual({
+      ok: false,
+      error: "name_taken",
+    });
+  });
+  test("unexpected status", async () => {
+    globalThis.fetch = mockJSON(500, {});
+    expect(await createAPIKey({ tenant_id: "t1", name: "k" })).toEqual({
+      ok: false,
+      error: "unexpected_500",
+    });
+  });
+});
+
+describe("revokeAPIKey", () => {
+  test("204 → ok", async () => {
+    globalThis.fetch = vi.fn<typeof fetch>(async () => new Response(null, { status: 204 }));
+    expect(await revokeAPIKey("k1")).toEqual({ ok: true });
+  });
+  test("404 → not_found", async () => {
+    globalThis.fetch = mockJSON(404, {});
+    expect(await revokeAPIKey("k1")).toEqual({ ok: false, error: "not_found" });
+  });
+  test("unexpected status", async () => {
+    globalThis.fetch = mockJSON(500, {});
+    expect(await revokeAPIKey("k1")).toEqual({ ok: false, error: "unexpected_500" });
+  });
+});
+
+describe("fetchAudit", () => {
+  test("happy path with filters", async () => {
+    const spy = mockJSON(200, {
+      items: [{ id: 1, action: "tenant.created", created_at: "x" }],
+      next_cursor: 1,
+    });
+    globalThis.fetch = spy;
+    const res = await fetchAudit({
+      tenant_id: "t1",
+      product: "certifai",
+      actor_id: "u1",
+      action: "tenant.created",
+      since: "2026-05-01T00:00:00Z",
+      until: "2026-05-20T00:00:00Z",
+      limit: 50,
+      cursor: 10,
+    });
+    expect(res.items).toHaveLength(1);
+    expect(res.next_cursor).toBe(1);
+    const url = String(spy.mock.calls[0]![0]);
+    expect(url).toContain("tenant_id=t1");
+    expect(url).toContain("product=certifai");
+    expect(url).toContain("actor_id=u1");
+    expect(url).toContain("action=tenant.created");
+    expect(url).toContain("limit=50");
+    expect(url).toContain("cursor=10");
+  });
+  test("no filters", async () => {
+    const spy = mockJSON(200, { items: [] });
+    globalThis.fetch = spy;
+    const res = await fetchAudit({});
+    expect(res.items).toEqual([]);
+    const url = String(spy.mock.calls[0]![0]);
+    expect(url).toBe("http://test:1234/v1/audit?");
+  });
+  test("non-200 throws", async () => {
+    globalThis.fetch = mockJSON(500, {});
+    await expect(fetchAudit({ tenant_id: "t1" })).rejects.toThrow();
   });
 });

src/lib/tenant-registry.ts

@@ -1,29 +1,270 @@
-// Tenant Registry client — fetches tenant data from the Go service.
+// Tenant Registry client — covers everything the portal needs to call
-// Skeleton-mode: read-only by-slug lookup. The portal middleware uses this
+// from server components and server actions.
-// to resolve `<slug>.localhost:3000` → tenant context before rendering.
 
 export type Tenant = {
   id: string;
   slug: string;
   name: string;
   status: "active" | "trial" | "frozen" | "archived" | "demo";
+  kind: "customer" | "demo";
   plan: "starter" | "professional" | "enterprise";
-  products: string[];
+  trial_ends_at?: string | null;
+  created_at: string;
+  updated_at: string;
+};
+
+export type CatalogEntry = {
+  key: string;
+  name: string;
+  description: string;
+  plans_required: string[];
+  supports_trial: boolean;
+  demo_url?: string;
+};
+
+export type Entitlement = {
+  tenant_id: string;
+  product: string;
+  enabled: boolean;
+  config: Record<string, unknown>;
+  expires_at?: string | null;
+};
+
+export type APIKey = {
+  id: string;
+  tenant_id: string;
+  product?: string;
+  name: string;
+  scopes: string[];
+  prefix: string;
+  created_by?: string;
+  last_used_at?: string | null;
+  revoked_at?: string | null;
   created_at: string;
 };
 
+export type AuditEvent = {
+  id: number;
+  tenant_id?: string;
+  actor_id?: string;
+  actor_name?: string;
+  actor_type?: string;
+  action: string;
+  target_id?: string;
+  target_type?: string;
+  target_name?: string;
+  product?: string;
+  metadata?: Record<string, unknown>;
+  source_ip?: string;
+  user_agent?: string;
+  created_at: string;
+};
+
+export type AuditPage = {
+  items: AuditEvent[];
+  next_cursor?: number;
+};
+
 function baseUrl(): string {
-  return process.env.TENANT_REGISTRY_URL ?? "http://localhost:8080";
+  return process.env.TENANT_REGISTRY_URL ?? "http://localhost:8090";
 }
 
-export async function fetchTenantBySlug(slug: string): Promise<Tenant | null> {
+async function req<T>(
-  const res = await fetch(`${baseUrl()}/v1/tenants/by-slug/${encodeURIComponent(slug)}`, {
+  method: string,
+  path: string,
+  body?: unknown,
+): Promise<{ status: number; data: T | null }> {
+  const init: RequestInit = {
+    method,
     headers: { accept: "application/json" },
     cache: "no-store",
-  });
+  };
-  if (res.status === 404) return null;
+  if (body !== undefined) {
-  if (!res.ok) {
+    init.body = JSON.stringify(body);
-    throw new Error(`tenant-registry: ${res.status} ${res.statusText}`);
+    init.headers = { ...init.headers, "content-type": "application/json" };
   }
-  return (await res.json()) as Tenant;
+  const res = await fetch(`${baseUrl()}${path}`, init);
+  if (res.status === 204) return { status: 204, data: null };
+  const data = (await res.json().catch(() => null)) as T | null;
+  return { status: res.status, data };
+}
+
+// ─── reads ───────────────────────────────────────────────────────────────
+
+export async function fetchTenantBySlug(slug: string): Promise<Tenant | null> {
+  const { status, data } = await req<Tenant>(
+    "GET",
+    `/v1/tenants/by-slug/${encodeURIComponent(slug)}`,
+  );
+  if (status === 404) return null;
+  if (status >= 400 || !data) {
+    throw new Error(`tenant-registry: GET tenant ${status}`);
+  }
+  return data;
+}
+
+export async function fetchCatalog(): Promise<CatalogEntry[]> {
+  const { status, data } = await req<{ items: CatalogEntry[] }>(
+    "GET",
+    "/v1/catalog",
+  );
+  if (status !== 200 || !data) {
+    throw new Error(`tenant-registry: GET catalog ${status}`);
+  }
+  return data.items;
+}
+
+export async function fetchEntitlements(tenantId: string): Promise<Entitlement[]> {
+  const { status, data } = await req<{ items: Entitlement[] }>(
+    "GET",
+    `/v1/entitlements?tenant_id=${encodeURIComponent(tenantId)}`,
+  );
+  if (status === 404) return [];
+  if (status !== 200 || !data) {
+    throw new Error(`tenant-registry: GET entitlements ${status}`);
+  }
+  return data.items;
+}
+
+// ─── mutations ───────────────────────────────────────────────────────────
+
+export type RequestProductResult =
+  | { ok: true }
+  | { ok: false; error: string };
+
+export async function requestProduct(
+  tenantId: string,
+  product: string,
+): Promise<RequestProductResult> {
+  const { status } = await req<unknown>("POST", "/v1/catalog/request", {
+    tenant_id: tenantId,
+    product,
+  });
+  if (status === 202) return { ok: true };
+  if (status === 404) return { ok: false, error: "tenant_not_found" };
+  if (status === 400) return { ok: false, error: "invalid_input" };
+  return { ok: false, error: `unexpected_${status}` };
+}
+
+export type StartTrialResult =
+  | { ok: true; entitlement: Entitlement }
+  | { ok: false; error: string };
+
+export async function startTrial(
+  tenantId: string,
+  product: string,
+): Promise<StartTrialResult> {
+  const { status, data } = await req<Entitlement>(
+    "POST",
+    "/v1/catalog/trial-request",
+    { tenant_id: tenantId, product },
+  );
+  if (status === 201 && data) return { ok: true, entitlement: data };
+  if (status === 404) return { ok: false, error: "tenant_not_found" };
+  if (status === 400) return { ok: false, error: "invalid_input" };
+  return { ok: false, error: `unexpected_${status}` };
+}
+
+export type CreateTenantInput = {
+  slug: string;
+  name: string;
+  plan?: "starter" | "professional" | "enterprise";
+  admin_email?: string;
+  admin_name?: string;
+};
+
+export type CreateTenantResult =
+  | { ok: true; tenant: Tenant; invite_url?: string }
+  | { ok: false; error: string };
+
+export async function createTenant(
+  in_: CreateTenantInput,
+): Promise<CreateTenantResult> {
+  const { status, data } = await req<{ tenant: Tenant; invite_url?: string }>(
+    "POST",
+    "/v1/tenants",
+    in_,
+  );
+  if (status === 201 && data) {
+    return { ok: true, tenant: data.tenant, invite_url: data.invite_url };
+  }
+  if (status === 409) return { ok: false, error: "slug_taken" };
+  if (status === 400) return { ok: false, error: "invalid_input" };
+  return { ok: false, error: `unexpected_${status}` };
+}
+
+// ─── api keys ────────────────────────────────────────────────────────────
+
+export async function fetchAPIKeys(tenantId: string): Promise<APIKey[]> {
+  const { status, data } = await req<{ items: APIKey[] }>(
+    "GET",
+    `/v1/api-keys?tenant_id=${encodeURIComponent(tenantId)}`,
+  );
+  if (status === 404) return [];
+  if (status !== 200 || !data) {
+    throw new Error(`tenant-registry: GET api-keys ${status}`);
+  }
+  return data.items;
+}
+
+export type CreateAPIKeyInput = {
+  tenant_id: string;
+  name: string;
+  product?: string;
+  scopes?: string[];
+  created_by?: string;
+};
+
+export type CreateAPIKeyResult =
+  | { ok: true; api_key: APIKey; plaintext: string }
+  | { ok: false; error: string };
+
+export async function createAPIKey(in_: CreateAPIKeyInput): Promise<CreateAPIKeyResult> {
+  const { status, data } = await req<{ api_key: APIKey; plaintext: string }>(
+    "POST",
+    "/v1/api-keys",
+    in_,
+  );
+  if (status === 201 && data) return { ok: true, api_key: data.api_key, plaintext: data.plaintext };
+  if (status === 404) return { ok: false, error: "tenant_not_found" };
+  if (status === 400) return { ok: false, error: "invalid_input" };
+  if (status === 409) return { ok: false, error: "name_taken" };
+  return { ok: false, error: `unexpected_${status}` };
+}
+
+export async function revokeAPIKey(id: string): Promise<{ ok: boolean; error?: string }> {
+  const { status } = await req<unknown>("DELETE", `/v1/api-keys/${encodeURIComponent(id)}`);
+  if (status === 204) return { ok: true };
+  if (status === 404) return { ok: false, error: "not_found" };
+  return { ok: false, error: `unexpected_${status}` };
+}
+
+// ─── audit ───────────────────────────────────────────────────────────────
+
+export type AuditFilter = {
+  tenant_id?: string;
+  product?: string;
+  actor_id?: string;
+  action?: string;
+  since?: string;
+  until?: string;
+  limit?: number;
+  cursor?: number;
+};
+
+export async function fetchAudit(f: AuditFilter): Promise<AuditPage> {
+  const qs = new URLSearchParams();
+  if (f.tenant_id) qs.set("tenant_id", f.tenant_id);
+  if (f.product) qs.set("product", f.product);
+  if (f.actor_id) qs.set("actor_id", f.actor_id);
+  if (f.action) qs.set("action", f.action);
+  if (f.since) qs.set("since", f.since);
+  if (f.until) qs.set("until", f.until);
+  if (f.limit) qs.set("limit", String(f.limit));
+  if (f.cursor) qs.set("cursor", String(f.cursor));
+  const { status, data } = await req<AuditPage>("GET", `/v1/audit?${qs.toString()}`);
+  if (status !== 200 || !data) {
+    throw new Error(`tenant-registry: GET audit ${status}`);
+  }
+  return data;
 }

tests/e2e/apex.spec.ts

@@ -0,0 +1,13 @@
+import { expect, test } from "@playwright/test";
+
+// Apex tests don't need the OIDC dance — they just verify Next.js is
+// serving the right routes.
+
+test.describe("apex landing", () => {
+  test("renders the landing page @needs-stack", async ({ page }) => {
+    const apex = test.info().config.metadata?.apexURL ?? "http://localhost:3000";
+    await page.goto(apex);
+    await expect(page.getByRole("heading", { name: "Breakpilot" })).toBeVisible();
+    await expect(page.getByText(/Customer portals live at/)).toBeVisible();
+  });
+});

tests/e2e/health.spec.ts

@@ -0,0 +1,32 @@
+import { expect, test } from "@playwright/test";
+
+// Health checks — confirm the underlying services are reachable before the
+// stack-dependent tests run. Skips with a clear reason if anything is down,
+// so we don't waste 30s on a slow OIDC redirect when Keycloak isn't running.
+
+test.describe("dev stack health @needs-stack", () => {
+  test("portal /api/auth/providers responds", async ({ request }) => {
+    const r = await request.get("/api/auth/providers");
+    expect(r.status()).toBe(200);
+    const data = await r.json();
+    expect(data).toHaveProperty("keycloak");
+  });
+
+  test("tenant-registry /healthz responds", async ({ request }) => {
+    const url =
+      process.env.PLAYWRIGHT_TENANT_REGISTRY_URL ?? "http://localhost:8090";
+    const r = await request.get(`${url}/healthz`);
+    expect(r.status()).toBe(200);
+    expect(await r.json()).toMatchObject({ status: "ok" });
+  });
+
+  test("keycloak realm metadata is exposed", async ({ request }) => {
+    const url =
+      process.env.PLAYWRIGHT_KEYCLOAK_URL ??
+      "http://localhost:8080/realms/breakpilot-dev";
+    const r = await request.get(`${url}/.well-known/openid-configuration`);
+    expect(r.status()).toBe(200);
+    const cfg = await r.json();
+    expect(cfg.issuer).toContain("breakpilot-dev");
+  });
+});

tests/e2e/surfaces.spec.ts

@@ -0,0 +1,26 @@
+import { expect, test } from "@playwright/test";
+
+// One canary per shell surface — confirms the route mounts and renders
+// SOMETHING the user can see (heading or 403 gate) without OIDC.
+// All run signed-out, so role-gated routes land on the NotAuthorized 403.
+
+test.describe("customer-area surfaces @needs-stack", () => {
+  const surfaces = [
+    { path: "/products",                expected: "403" },
+    { path: "/projects",                expected: "403" },
+    { path: "/catalog",                 expected: "403" },
+    { path: "/settings",                expected: "403" },
+    { path: "/settings/users",          expected: "403" },
+    { path: "/settings/api-keys",       expected: "403" },
+    { path: "/settings/integrations",   expected: "403" },
+    { path: "/billing",                 expected: "403" },
+    { path: "/audit",                   expected: "403" },
+    { path: "/support",                 expected: "403" },
+  ];
+  for (const { path, expected } of surfaces) {
+    test(`acme${path} renders signed-out`, async ({ page }) => {
+      await page.goto(path);
+      await expect(page.getByRole("heading", { name: new RegExp(expected, "i") })).toBeVisible();
+    });
+  }
+});

tests/e2e/tenant.spec.ts

@@ -0,0 +1,28 @@
+import { expect, test } from "@playwright/test";
+
+// Tenant subdomain tests — no OIDC click-through (Keycloak in headless mode
+// is flaky); we just assert the SIGNED-OUT view of each protected route
+// renders the expected gate. Once the realm grows a service-account flow
+// for testing (M5.x), we'll bolt on a signed-in suite.
+
+test.describe("tenant subdomain @needs-stack", () => {
+  test("acme dashboard renders the Sign-in button when signed out", async ({ page }) => {
+    await page.goto("/dashboard");
+    await expect(page.getByRole("heading", { name: /Sign in to acme/i })).toBeVisible();
+    await expect(page.getByRole("button", { name: /Sign in with Keycloak/i })).toBeVisible();
+  });
+
+  test("acme /products is gated when signed out", async ({ page }) => {
+    await page.goto("/products");
+    // Signed-out session means canSee(null, "products") is false, so the
+    // page renders the 'NotAuthorized' component. The dashboard route is
+    // the only place that surfaces the Sign-in button today — we'll add
+    // a redirect-to-sign-in in M10.1 once the surface set firms up.
+    await expect(page.getByRole("heading", { name: /403/i })).toBeVisible();
+  });
+
+  test("unknown tenant slug 404s", async ({ page }) => {
+    const resp = await page.goto("http://nope-nope.localhost:3000/dashboard");
+    expect(resp?.status()).toBe(404);
+  });
+});

tsconfig.json

@@ -38,6 +38,8 @@
   ],
   "exclude": [
     "node_modules",
-    ".next"
+    ".next",
+    "tests/e2e",
+    "tests"
   ]
 }