Phase4: Stripe

.env.example

@@ -17,3 +17,7 @@ LITELLM_MASTER_KEY=
 
 # Portal Database (CloudNativePG)
 DATABASE_URL=postgresql://portal:${PORTAL_DB_PASSWORD}@portal-db-rw.pieced-system.svc:5432/portal
+
+# Threema relay (central pieced-threema-gateway)
+THREEMA_RELAY_URL=http://pieced-threema-gateway.threema-gateway.svc:8080
+THREEMA_RELAY_ADMIN_TOKEN=__from_openbao__

README.md

@@ -1,100 +1,54 @@
-# PieCed Portal
+# PieCed Portal — Billing Phase 1 patch (suspend-via-admin fix)
 
-Customer self-service portal for the PieCed IT multi-tenant OpenClaw platform.
+Single-file fix on top of the Phase 1 v2 drop.
 
-## Stack
+## What it fixes
 
-| Layer | Choice |
-|-------|--------|
-| Framework | Next.js 15 LTS (App Router, standalone output, Turbopack) |
-| Auth | NextAuth v5 + ZITADEL OIDC (CODE flow) |
-| Tenant mgmt | Direct K8s API → `PiecedTenant` CRs (Option A) |
-| Usage data | LiteLLM `/team/info` + `/global/spend/logs` |
-| i18n | next-intl 4.x (en/de) |
-| Styling | Tailwind CSS 4 |
-| Deployment | Container in `pieced-system`, exposed at `app.pieced.ch` |
+The admin panel's suspend/resume button hits
+`/api/admin/tenants/[name]/suspend` (a different route from the
+customer-side `/api/tenants/[name]/suspend`). The v2 drop only
+hooked the customer route — admin suspends were going to K8s
+without producing a row in `tenant_suspension_events`.
 
-## Setup
+This patch adds the same `recordSuspensionEvent` hook to the
+admin route. No other code paths affected; no schema changes.
 
-### 1. ZITADEL Application
-
-In ZITADEL console (`auth.pieced.ch`), project "OpenClaw Platform":
-
-1. Create Application → **PieCed Portal** → Web → Authentication Method: **CODE**
-2. Redirect URI: `https://app.pieced.ch/api/auth/callback/zitadel`
-3. Post-logout URI: `https://app.pieced.ch/login`
-4. Note Client ID and Client Secret
-
-### 2. OpenBao Secrets
-
-```bash
-bao kv put pieced/portal/oidc \
-  client_id="<from step 1>" \
-  client_secret="<from step 1>" \
-  nextauth_secret="$(openssl rand -base64 32)"
-```
-
-### 3. Build & Push
-
-```bash
-docker build -t registry.c5ai.ch/pieced/pieced-portal:0.1.0 .
-docker push registry.c5ai.ch/pieced/pieced-portal:0.1.0
-```
-
-Update image tag in `pieced-gitops/apps/portal/deployment.yaml`, push, ArgoCD syncs.
-
-### 4. DNS
-
-Ensure `app.pieced.ch` A record → MetalLB ingress IP (or ExternalDNS handles it).
-
-## Local Development
-
-```bash
-cp .env.example .env.local
-# Fill in values — K8s client uses ~/.kube/config locally
-npm install
-npm run dev
-```
-
-## Project Structure
+## Files
 
 ```
-src/
-├── app/
-│   ├── api/
-│   │   ├── auth/[...nextauth]/route.ts   # NextAuth handler
-│   │   ├── tenants/route.ts              # Tenant CRUD (K8s API)
-│   │   └── usage/route.ts                # Usage stub
-│   ├── [locale]/
-│   │   ├── layout.tsx                    # Locale layout + NavShell
-│   │   ├── page.tsx                      # Redirect → /dashboard
-│   │   ├── login/page.tsx                # ZITADEL sign-in
-│   │   ├── dashboard/page.tsx            # Customer dashboard
-│   │   └── admin/page.tsx                # Platform admin tenant list
-│   ├── layout.tsx                        # Root layout
-│   └── globals.css                       # Tailwind 4 theme
-├── components/
-│   ├── layout/nav-shell.tsx              # Header + navigation
-│   └── ui/                               # Reusable UI components
-├── i18n/
-│   ├── routing.ts                        # next-intl 4.x routing config
-│   ├── navigation.ts                     # Localized Link, redirect, etc.
-│   └── request.ts                        # Server-side i18n config
-├── lib/
-│   ├── auth.ts                           # NextAuth v5 + ZITADEL config
-│   ├── k8s.ts                            # K8s client for PiecedTenant CRs
-│   ├── litellm.ts                        # LiteLLM API client
-│   └── session.ts                        # Session helpers
-├── messages/
-│   ├── en.json
-│   └── de.json
-└── types/index.ts                        # Shared TypeScript types
+src/app/api/admin/tenants/[name]/suspend/route.ts    MODIFIED
 ```
 
-## Session Roadmap
+## Deploy
 
-- **6.1** ← This session: scaffold, auth, basic pages
-- **6.2**: Instance management, package config, usage display
-- **6.3**: Onboarding flow (create ZITADEL org → PiecedTenant CR)
-- **6.4**: Workspace editor (SOUL.md, AGENTS.md, TOOLS.md)
-- **6.5**: Admin panel (tenant lifecycle, billing overview)
+Extract over your `pieced-portal/` tree, rebuild, redeploy as
+usual. After the new image is running, verify:
+
+1. Suspend any test tenant from the `/admin` panel.
+2. Check the events table:
+
+   ```bash
+   kubectl -n pieced-system exec -it portal-db-1 -- psql -U postgres -d portal -c \
+     "SELECT * FROM tenant_suspension_events ORDER BY id DESC LIMIT 5;"
+   ```
+
+   Expect a fresh `suspended` row for the tenant you just toggled.
+
+3. Resume → expect a `resumed` row.
+
+## Why I missed this
+
+Both routes share the same shape (PATCH/POST that sets
+`spec.suspend`), but they differ on:
+
+- URL path (`/api/admin/tenants/...` vs `/api/tenants/...`)
+- Method (POST vs PATCH)
+- Authorization (platform-only vs owner+platform)
+- Caller (admin panel vs customer cancel button)
+
+When I grepped for the suspend hook target I matched on the
+customer endpoint and didn't audit cross-cutting admin
+duplicates. I've since checked every site that calls
+`patchTenantSpec`, `createTenant`, or `deleteTenant` — this was
+the only missed billing-relevant one. Other `patchTenantSpec`
+sites are confirmed non-billing (openClawImage, channelUsers).

deploy/README-threema.md

@@ -0,0 +1,70 @@
+# Wiring Threema relay into the portal
+
+Drop-in files in this archive:
+
+```
+src/lib/packages.ts                                       # add 'threema' to catalog + customProvisioning flag
+src/lib/threema-relay.ts                                  # new — admin API client
+src/app/api/tenants/[name]/threema/route.ts               # new — POST provision / DELETE deprovision
+src/app/api/tenants/[name]/threema/routes/route.ts        # new — atomic add/remove of a single Threema ID
+src/components/channel-users/channel-users.tsx            # branch threema through relay-managed endpoint
+src/components/packages/package-card.tsx                  # handle customProvisioning enable/disable
+deploy/patch-i18n-threema.mjs                             # idempotent i18n key injection
+```
+
+## Manual steps after dropping in
+
+1. `.env` (and `.env.example`) — add:
+   ```
+   THREEMA_RELAY_URL=http://pieced-threema-gateway.threema-gateway.svc:8080
+   THREEMA_RELAY_ADMIN_TOKEN=__from_openbao__
+   ```
+   The portal pod's OpenBao client should also read `secret/data/threema-gateway/admin` and surface `token` as this env var (existing ESO pattern in the portal's Helm chart).
+
+2. Patch the message files (one-time):
+   ```bash
+   node deploy/patch-i18n-threema.mjs
+   ```
+
+3. Re-export `CHANNEL_PACKAGE_IDS` is unchanged in source; verify
+   `tenants/[name]/page.tsx` still derives the enabled-channels list
+   from it — it should now include `threema` automatically once a
+   tenant has it in `spec.packages`.
+
+4. Type-check:
+   ```bash
+   npx tsc --noEmit
+   ```
+
+## Flow summary
+
+### Enabling Threema for a tenant
+1. Customer toggles the threema package card.
+2. PackageCard sees `customProvisioning: true` → POSTs `/api/tenants/<name>/threema`.
+3. Handler calls relay `POST /admin/tokens` → gets `{token, hmacSecret}`.
+4. Handler writes them to OpenBao at `secret/data/tenants/tenant-<name>/threema-relay`.
+5. PackageCard then PATCHes `tenant.spec.packages` to include `threema`.
+6. Operator reconciles: ExternalSecret syncs OpenBao → Secret; OpenClaw pod restarts with `THREEMA_RELAY_*` env vars; plugin registers `threema` channel.
+
+### Customer adds a Threema ID
+1. UI calls `POST /api/tenants/<name>/threema/routes` with `{threemaId}`.
+2. Handler calls relay `POST /admin/routes` (uniqueness enforced at PK).
+3. On 201 or 409-from-same-tenant: handler patches K8s `spec.channelUsers.threema`.
+4. On 409-from-other-tenant: 409 to client with explanation.
+5. On K8s patch failure after relay success: handler compensates by `DELETE /admin/routes/...` at the relay.
+
+### Customer removes a Threema ID
+1. UI calls `DELETE /api/tenants/<name>/threema/routes?threemaId=...`.
+2. Handler patches K8s `spec.channelUsers.threema` to drop the ID.
+3. Handler calls relay `DELETE /admin/routes/...` (404 = idempotent OK).
+4. If relay drop fails: K8s already updated, surface warning but treat as success — relay deletes are idempotent on retry.
+
+### Disabling Threema for a tenant
+1. Customer disables the threema card.
+2. PackageCard DELETEs `/api/tenants/<name>/threema`.
+3. Handler calls relay `DELETE /admin/tokens/<name>` (cascades to all routes for this tenant).
+4. Handler deletes OpenBao secret at `secret/data/tenants/tenant-<name>/threema-relay`.
+5. PackageCard then PATCHes `tenant.spec.packages` to drop `threema`.
+6. Operator reconciles: ExternalSecret targets a missing OpenBao path → Secret deleted → OpenClaw pod restarts without `threema` channel.
+
+There's a small window (between step 4 and the operator's reconcile) where the pod still thinks it has a relay token but the relay has revoked it. Outbound during that window returns 401 from the relay; inbound is blackholed at the relay because routes are gone. Both are graceful failures.

deploy/patch-i18n-threema.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * Run: node deploy/patch-i18n-threema.mjs
+ *
+ * Idempotently injects (or overwrites) customer-facing Threema texts:
+ *   - packages.threema.{description, instructions, disclaimer}
+ *   - channelUsers.threemaIdHelp
+ *   - channelUsers.threemaSetup.{title, step1, step2, step3, qrAlt}
+ *
+ * Replaces the earlier version of this script entirely. The new texts:
+ *   - Drop "Gateway account" jargon (customers don't know it)
+ *   - Drop asterisk-prefix references (customers don't see / type it)
+ *   - Tell the customer to add their OWN Threema ID, not someone else's
+ *   - Disclose that Threema charges per message via the gateway
+ *   - Walk through the QR-scan + add-your-ID flow explicitly
+ *
+ * Re-running is safe — keys are set, not merged, so this is the
+ * source of truth for the values it touches.
+ */
+import { readFileSync, writeFileSync } from "fs";
+
+const i18n = {
+  en: {
+    pkg: {
+      description:
+        "Send and receive messages through Threema. Each inbound and outbound message uses the shared PieCed messaging service and incurs a per-message charge from Threema — a third-party cost, separate from your PieCed subscription.",
+      instructions:
+        "1. Enable this package.\n2. Open Threema on your phone, scan the QR code shown under Authorized Users → threema, and accept the contact.\n3. Add your own Threema ID under Authorized Users → threema so the assistant recognises your messages.\n4. Send a message from Threema to start chatting with the assistant.",
+      disclaimer:
+        "Messages between Threema and PieCed are end-to-end encrypted up to PieCed's messaging service, where they are decrypted to be routed to your assistant. Each message sent or received is counted toward Threema's per-message billing — see your plan for current rates.",
+    },
+    channelHelp:
+      "Enter your own Threema ID — the 8 characters shown in your Threema app under Settings → My Threema ID. Once added, you'll be able to chat with the assistant directly from Threema.",
+    setup: {
+      title: "Add the assistant to your Threema",
+      step1: "Open Threema on your phone.",
+      step2: "Tap the scan icon and scan this QR code to add the assistant as a contact.",
+      step3: "Then add your own Threema ID below.",
+      qrAlt: "QR code to add {gateway} as a Threema contact",
+      bannerTitle: "Set up Threema",
+      bannerBody: "Open Threema on your phone and scan our QR code to add the assistant as a contact. Then add your own Threema ID below.",
+      bannerButton: "Show QR code",
+    },
+  },
+  de: {
+    pkg: {
+      description:
+        "Senden und empfangen Sie Nachrichten über Threema. Jede eingehende und ausgehende Nachricht läuft über den gemeinsamen PieCed-Messaging-Dienst und verursacht eine Gebühr pro Nachricht bei Threema — eine Drittanbieter-Kostenposition, unabhängig von Ihrem PieCed-Abonnement.",
+      instructions:
+        "1. Aktivieren Sie dieses Paket.\n2. Öffnen Sie Threema auf Ihrem Telefon, scannen Sie den QR-Code unter Autorisierte Benutzer → threema und akzeptieren Sie den Kontakt.\n3. Tragen Sie Ihre eigene Threema-ID unter Autorisierte Benutzer → threema ein, damit der Assistent Ihre Nachrichten erkennt.\n4. Schreiben Sie eine Nachricht aus Threema, um das Gespräch zu beginnen.",
+      disclaimer:
+        "Nachrichten zwischen Threema und PieCed werden Ende-zu-Ende verschlüsselt bis zum PieCed-Messaging-Dienst, wo sie entschlüsselt und an Ihren Assistenten weitergeleitet werden. Jede gesendete oder empfangene Nachricht wird gemäss Threema-Tarif pro Nachricht abgerechnet — die aktuellen Preise finden Sie in Ihrem Plan.",
+    },
+    channelHelp:
+      "Geben Sie Ihre eigene Threema-ID ein — die 8 Zeichen, die in Ihrer Threema-App unter Einstellungen → Meine Threema-ID angezeigt werden. Anschliessend können Sie direkt aus Threema mit dem Assistenten chatten.",
+    setup: {
+      title: "Assistenten zu Threema hinzufügen",
+      step1: "Öffnen Sie Threema auf Ihrem Telefon.",
+      step2: "Tippen Sie auf das Scan-Symbol und scannen Sie diesen QR-Code, um den Assistenten als Kontakt hinzuzufügen.",
+      step3: "Fügen Sie anschliessend unten Ihre eigene Threema-ID hinzu.",
+      qrAlt: "QR-Code, um {gateway} als Threema-Kontakt hinzuzufügen",
+      bannerTitle: "Threema einrichten",
+      bannerBody: "Öffnen Sie Threema auf Ihrem Telefon und scannen Sie unseren QR-Code, um den Assistenten als Kontakt hinzuzufügen. Geben Sie anschliessend unten Ihre eigene Threema-ID ein.",
+      bannerButton: "QR-Code anzeigen",
+    },
+  },
+  fr: {
+    pkg: {
+      description:
+        "Envoyez et recevez des messages via Threema. Chaque message entrant ou sortant transite par le service de messagerie PieCed partagé et entraîne des frais par message facturés par Threema — un coût tiers, distinct de votre abonnement PieCed.",
+      instructions:
+        "1. Activez ce package.\n2. Ouvrez Threema sur votre téléphone, scannez le QR code affiché dans Utilisateurs autorisés → threema, puis acceptez le contact.\n3. Ajoutez votre propre identifiant Threema sous Utilisateurs autorisés → threema afin que l'assistant reconnaisse vos messages.\n4. Envoyez un message depuis Threema pour commencer la conversation.",
+      disclaimer:
+        "Les messages entre Threema et PieCed sont chiffrés de bout en bout jusqu'au service de messagerie PieCed, où ils sont déchiffrés pour être acheminés vers votre assistant. Chaque message envoyé ou reçu est facturé par Threema selon son tarif par message — consultez votre plan pour les tarifs en vigueur.",
+    },
+    channelHelp:
+      "Saisissez votre propre identifiant Threema — les 8 caractères affichés dans votre application Threema sous Réglages → Mon identifiant Threema. Une fois ajouté, vous pourrez discuter directement avec l'assistant depuis Threema.",
+    setup: {
+      title: "Ajouter l'assistant à Threema",
+      step1: "Ouvrez Threema sur votre téléphone.",
+      step2: "Appuyez sur l'icône de scan et scannez ce QR code pour ajouter l'assistant comme contact.",
+      step3: "Puis ajoutez votre propre identifiant Threema ci-dessous.",
+      qrAlt: "QR code pour ajouter {gateway} comme contact Threema",
+      bannerTitle: "Configurer Threema",
+      bannerBody: "Ouvrez Threema sur votre téléphone et scannez notre QR code pour ajouter l'assistant comme contact. Saisissez ensuite votre propre identifiant Threema ci-dessous.",
+      bannerButton: "Afficher le QR code",
+    },
+  },
+  it: {
+    pkg: {
+      description:
+        "Invia e ricevi messaggi tramite Threema. Ogni messaggio in entrata e in uscita passa attraverso il servizio di messaggistica condiviso di PieCed e comporta un addebito per messaggio da parte di Threema — un costo di terzi, separato dall'abbonamento PieCed.",
+      instructions:
+        "1. Attiva questo pacchetto.\n2. Apri Threema sul tuo telefono, scansiona il QR code mostrato in Utenti autorizzati → threema e accetta il contatto.\n3. Aggiungi il tuo ID Threema sotto Utenti autorizzati → threema affinché l'assistente riconosca i tuoi messaggi.\n4. Invia un messaggio da Threema per iniziare la conversazione.",
+      disclaimer:
+        "I messaggi tra Threema e PieCed sono cifrati end-to-end fino al servizio di messaggistica PieCed, dove vengono decifrati per essere inoltrati al tuo assistente. Ogni messaggio inviato o ricevuto viene addebitato da Threema secondo la sua tariffa per messaggio — consulta il tuo piano per i prezzi attuali.",
+    },
+    channelHelp:
+      "Inserisci il tuo ID Threema — gli 8 caratteri mostrati nella tua app Threema sotto Impostazioni → Il mio ID Threema. Una volta aggiunto, potrai conversare con l'assistente direttamente da Threema.",
+    setup: {
+      title: "Aggiungi l'assistente a Threema",
+      step1: "Apri Threema sul tuo telefono.",
+      step2: "Tocca l'icona di scansione e scansiona questo QR code per aggiungere l'assistente ai contatti.",
+      step3: "Quindi aggiungi il tuo ID Threema qui sotto.",
+      qrAlt: "QR code per aggiungere {gateway} come contatto Threema",
+      bannerTitle: "Configura Threema",
+      bannerBody: "Apri Threema sul tuo telefono e scansiona il nostro QR code per aggiungere l'assistente ai contatti. Inserisci poi il tuo ID Threema qui sotto.",
+      bannerButton: "Mostra QR code",
+    },
+  },
+};
+
+for (const [lang, entries] of Object.entries(i18n)) {
+  const path = `src/messages/${lang}.json`;
+  const json = JSON.parse(readFileSync(path, "utf8"));
+
+  json.packages = json.packages ?? {};
+  json.packages.threema = {
+    description: entries.pkg.description,
+    instructions: entries.pkg.instructions,
+    disclaimer: entries.pkg.disclaimer,
+  };
+
+  json.channelUsers = json.channelUsers ?? {};
+  json.channelUsers.threemaIdHelp = entries.channelHelp;
+  json.channelUsers.threemaSetup = entries.setup;
+
+  writeFileSync(path, JSON.stringify(json, null, 2) + "\n");
+  console.log(`Patched ${path}`);
+}

next.config.mjs

@@ -5,7 +5,11 @@ const withNextIntl = createNextIntlPlugin();
 /** @type {import('next').NextConfig} */
 const nextConfig = {
   output: "standalone",
-  serverExternalPackages: ["pg"],
+  // pg uses native node bindings, @react-pdf/renderer pulls in
+  // fontkit / pdfkit which don't play nicely with webpack bundling.
+  // Both are pure server-side concerns; mark external so Next ships
+  // them as Node modules rather than bundling.
+  serverExternalPackages: ["pg", "@react-pdf/renderer"],
 };
 
 export default withNextIntl(nextConfig);

package-lock.json

@@ -9,6 +9,7 @@
       "version": "0.1.0",
       "dependencies": {
         "@kubernetes/client-node": "^1.4.0",
+        "@react-pdf/renderer": "^4.4.0",
         "@types/nodemailer": "^8.0.0",
         "@types/pg": "^8.20.0",
         "next": "^15.5.15",
@@ -18,6 +19,7 @@
         "pg": "^8.20.0",
         "react": "^19.1.0",
         "react-dom": "^19.1.0",
+        "stripe": "^22.1.1",
         "zod": "^3.24.0"
       },
       "devDependencies": {
@@ -73,6 +75,15 @@
         }
       }
     },
+    "node_modules/@babel/runtime": {
+      "version": "7.29.2",
+      "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.29.2.tgz",
+      "integrity": "sha512-JiDShH45zKHWyGe4ZNVRrCjBz8Nh9TMmZG1kh4QTK8hCBTWBi8Da+i7s1fJw7/lYpM4ccepSNfqzZ/QvABBi5g==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
     "node_modules/@emnapi/core": {
       "version": "1.9.2",
       "resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.9.2.tgz",
@@ -1089,6 +1100,30 @@
         "node": ">= 10"
       }
     },
+    "node_modules/@noble/ciphers": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/@noble/ciphers/-/ciphers-1.3.0.tgz",
+      "integrity": "sha512-2I0gnIVPtfnMw9ee9h1dJG7tp81+8Ob3OJb3Mv37rx5L40/b0i7djjCVvGOVqc9AEIQyvyu1i6ypKdFw8R8gQw==",
+      "license": "MIT",
+      "engines": {
+        "node": "^14.21.3 || >=16"
+      },
+      "funding": {
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
+    "node_modules/@noble/hashes": {
+      "version": "1.8.0",
+      "resolved": "https://registry.npmjs.org/@noble/hashes/-/hashes-1.8.0.tgz",
+      "integrity": "sha512-jCs9ldd7NwzpgXDIf6P3+NrHh9/sD6CQdxHyjQI+h/6rDNo88ypBxxz45UDuZHz9r3tNz7N/VInSVoVdtXEI4A==",
+      "license": "MIT",
+      "engines": {
+        "node": "^14.21.3 || >=16"
+      },
+      "funding": {
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
     "node_modules/@nodelib/fs.scandir": {
       "version": "2.1.5",
       "resolved": "https://registry.npmjs.org/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz",
@@ -1453,6 +1488,183 @@
         "url": "https://github.com/sponsors/jonschlinkert"
       }
     },
+    "node_modules/@react-pdf/fns": {
+      "version": "3.1.3",
+      "resolved": "https://registry.npmjs.org/@react-pdf/fns/-/fns-3.1.3.tgz",
+      "integrity": "sha512-0I7pApDr1/RLAKbizuLy/IHTEa93LSPy/bEwYniboC3Xqnp6Od8xFJKbKEzGw2wh/5zKFFwl00g4t9RwgIMc3w==",
+      "license": "MIT"
+    },
+    "node_modules/@react-pdf/font": {
+      "version": "4.0.8",
+      "resolved": "https://registry.npmjs.org/@react-pdf/font/-/font-4.0.8.tgz",
+      "integrity": "sha512-deNd+emtZAJho1IlzKL9bRoLAGv/6oXOIKO2oZfs4RuXUrK1onLHbJO7e2YoVLPFP/sQxisRTnzdJFtd35iKwA==",
+      "license": "MIT",
+      "dependencies": {
+        "@react-pdf/pdfkit": "^5.1.1",
+        "@react-pdf/types": "^2.11.1",
+        "fontkit": "^2.0.2",
+        "is-url": "^1.2.4"
+      }
+    },
+    "node_modules/@react-pdf/image": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/@react-pdf/image/-/image-3.1.0.tgz",
+      "integrity": "sha512-ks7Ry8v711r8NvKWSELehj0BXBNPRihSnWsM09nDD8Ur175zbWBCK217LLwQMKDNYDVpkZaipdoJPom1LGaE9g==",
+      "license": "MIT",
+      "dependencies": {
+        "@react-pdf/svg": "^1.1.0",
+        "jay-peg": "^1.1.1",
+        "png-js": "^2.0.0"
+      }
+    },
+    "node_modules/@react-pdf/layout": {
+      "version": "4.6.1",
+      "resolved": "https://registry.npmjs.org/@react-pdf/layout/-/layout-4.6.1.tgz",
+      "integrity": "sha512-gN6PmWoEffvlIkifLfEhMsVucRywVMyH3rnxdyOVOhGy0nWJKKGpHyPc4plbDdpP6EfZ0r8prHXujDSkIG2nSA==",
+      "license": "MIT",
+      "dependencies": {
+        "@react-pdf/fns": "3.1.3",
+        "@react-pdf/image": "^3.1.0",
+        "@react-pdf/primitives": "^4.3.0",
+        "@react-pdf/stylesheet": "^6.2.1",
+        "@react-pdf/textkit": "^6.3.0",
+        "@react-pdf/types": "^2.11.1",
+        "emoji-regex-xs": "^1.0.0",
+        "queue": "^6.0.1",
+        "yoga-layout": "^3.2.1"
+      }
+    },
+    "node_modules/@react-pdf/pdfkit": {
+      "version": "5.1.1",
+      "resolved": "https://registry.npmjs.org/@react-pdf/pdfkit/-/pdfkit-5.1.1.tgz",
+      "integrity": "sha512-wNcdSsNlNYyGHGAgIdt453egBF7fiF9UxpRlklUfVvu8OWCrUppG9xiUrPLVoKiqWet5tMi0w6LmuFUJuYqjEg==",
+      "license": "MIT",
+      "dependencies": {
+        "@babel/runtime": "^7.20.13",
+        "@noble/ciphers": "^1.0.0",
+        "@noble/hashes": "^1.6.0",
+        "browserify-zlib": "^0.2.0",
+        "fontkit": "^2.0.2",
+        "jay-peg": "^1.1.1",
+        "js-md5": "^0.8.3",
+        "linebreak": "^1.1.0",
+        "png-js": "^2.0.0",
+        "vite-compatible-readable-stream": "^3.6.1"
+      }
+    },
+    "node_modules/@react-pdf/primitives": {
+      "version": "4.3.0",
+      "resolved": "https://registry.npmjs.org/@react-pdf/primitives/-/primitives-4.3.0.tgz",
+      "integrity": "sha512-nYXoZ36pvwNzbc54+DbL8RCn15jU7woJ9D/svnh5tpUXekJ+CbI4mZLo6boSv24CvJgychOu6h7gxX03B4ps0A==",
+      "license": "MIT"
+    },
+    "node_modules/@react-pdf/reconciler": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/@react-pdf/reconciler/-/reconciler-2.0.0.tgz",
+      "integrity": "sha512-7zaPRujpbHSmCpIrZ+b9HSTJHthcVZzX0Wx7RzvQGsGBUbHP4p6s5itXrAIOuQuPvDepoHGNOvf6xUuMVvdoyw==",
+      "license": "MIT",
+      "dependencies": {
+        "object-assign": "^4.1.1",
+        "scheduler": "0.25.0-rc-603e6108-20241029"
+      },
+      "peerDependencies": {
+        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+      }
+    },
+    "node_modules/@react-pdf/reconciler/node_modules/scheduler": {
+      "version": "0.25.0-rc-603e6108-20241029",
+      "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.25.0-rc-603e6108-20241029.tgz",
+      "integrity": "sha512-pFwF6H1XrSdYYNLfOcGlM28/j8CGLu8IvdrxqhjWULe2bPcKiKW4CV+OWqR/9fT52mywx65l7ysNkjLKBda7eA==",
+      "license": "MIT"
+    },
+    "node_modules/@react-pdf/render": {
+      "version": "4.5.1",
+      "resolved": "https://registry.npmjs.org/@react-pdf/render/-/render-4.5.1.tgz",
+      "integrity": "sha512-IW/N4HWJWtioBXCf7n02IR24VJJ8gbdS3jGypf+vW/rSErEx3/URRzh9UK6Ma8Fpog9+T/W6GE2NHJ5AAKHhVA==",
+      "license": "MIT",
+      "dependencies": {
+        "@babel/runtime": "^7.20.13",
+        "@react-pdf/fns": "3.1.3",
+        "@react-pdf/primitives": "^4.3.0",
+        "@react-pdf/textkit": "^6.3.0",
+        "@react-pdf/types": "^2.11.1",
+        "abs-svg-path": "^0.1.1",
+        "color-string": "^2.1.4",
+        "normalize-svg-path": "^1.1.0",
+        "parse-svg-path": "^0.1.2",
+        "svg-arc-to-cubic-bezier": "^3.2.0"
+      }
+    },
+    "node_modules/@react-pdf/renderer": {
+      "version": "4.5.1",
+      "resolved": "https://registry.npmjs.org/@react-pdf/renderer/-/renderer-4.5.1.tgz",
+      "integrity": "sha512-5r1VQrE6FRLXX5wWUxwZzM24E2BJMo6g8AQWuS8WyPs9ugu5yMnb2g8/RpPYka/Z6J+RUEWc32wty2NoUJF42Q==",
+      "license": "MIT",
+      "dependencies": {
+        "@babel/runtime": "^7.20.13",
+        "@react-pdf/fns": "3.1.3",
+        "@react-pdf/font": "^4.0.8",
+        "@react-pdf/layout": "^4.6.1",
+        "@react-pdf/pdfkit": "^5.1.1",
+        "@react-pdf/primitives": "^4.3.0",
+        "@react-pdf/reconciler": "^2.0.0",
+        "@react-pdf/render": "^4.5.1",
+        "@react-pdf/types": "^2.11.1",
+        "events": "^3.3.0",
+        "object-assign": "^4.1.1",
+        "prop-types": "^15.6.2",
+        "queue": "^6.0.1"
+      },
+      "peerDependencies": {
+        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+      }
+    },
+    "node_modules/@react-pdf/stylesheet": {
+      "version": "6.2.1",
+      "resolved": "https://registry.npmjs.org/@react-pdf/stylesheet/-/stylesheet-6.2.1.tgz",
+      "integrity": "sha512-2+UEk+7e+z8baaWi2l5kPLWmwtJeOI+T5wW9GGeN3iDH7vd3kbTqOpN1yt9mmfNVZFxQsnDHpznFb5v5UF983A==",
+      "license": "MIT",
+      "dependencies": {
+        "@react-pdf/fns": "3.1.3",
+        "@react-pdf/types": "^2.11.1",
+        "color-string": "^2.1.4",
+        "hsl-to-hex": "^1.0.0",
+        "media-engine": "^1.0.3",
+        "postcss-value-parser": "^4.1.0"
+      }
+    },
+    "node_modules/@react-pdf/svg": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/@react-pdf/svg/-/svg-1.1.0.tgz",
+      "integrity": "sha512-cTIHXiz9x1HrbfqzfxfZP3FRdDwUXG77QWF6Fb5MP/lV3ONxR+g0Z3hwtBatCS9HeGBQCpxX/Lzb8wHE+co1PA==",
+      "license": "MIT",
+      "dependencies": {
+        "@react-pdf/primitives": "^4.3.0"
+      }
+    },
+    "node_modules/@react-pdf/textkit": {
+      "version": "6.3.0",
+      "resolved": "https://registry.npmjs.org/@react-pdf/textkit/-/textkit-6.3.0.tgz",
+      "integrity": "sha512-v6+V8nAcVwm7s2s1jIG2MD3Iw//x/k+XrH1foWOELBE4b32pyDgKyPXN/6KJE0dnX7+fVy27uctLNCLNMvzKzQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@react-pdf/fns": "3.1.3",
+        "bidi-js": "^1.0.2",
+        "hyphen": "^1.6.4",
+        "unicode-properties": "^1.4.1"
+      }
+    },
+    "node_modules/@react-pdf/types": {
+      "version": "2.11.1",
+      "resolved": "https://registry.npmjs.org/@react-pdf/types/-/types-2.11.1.tgz",
+      "integrity": "sha512-i9xQgfaDU9QoeNnbp6rltXCWg1huEh195rpOuN8cE4BZ2FuLdQrsIcb2dhFF9aOxXf+XBA6LOSpIW051MDD/bw==",
+      "license": "MIT",
+      "dependencies": {
+        "@react-pdf/font": "^4.0.8",
+        "@react-pdf/primitives": "^4.3.0",
+        "@react-pdf/stylesheet": "^6.2.1"
+      }
+    },
     "node_modules/@rtsao/scc": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/@rtsao/scc/-/scc-1.1.0.tgz",
@@ -2617,6 +2829,12 @@
         "win32"
       ]
     },
+    "node_modules/abs-svg-path": {
+      "version": "0.1.1",
+      "resolved": "https://registry.npmjs.org/abs-svg-path/-/abs-svg-path-0.1.1.tgz",
+      "integrity": "sha512-d8XPSGjfyzlXC3Xx891DJRyZfqk5JU0BJrDQcsWomFIV1/BIzPW5HDH5iDdWpqWaav0YVIEzT1RHTwWr0FFshA==",
+      "license": "MIT"
+    },
     "node_modules/acorn": {
       "version": "8.16.0",
       "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.16.0.tgz",
@@ -3029,6 +3247,35 @@
         "bare-path": "^3.0.0"
       }
     },
+    "node_modules/base64-js": {
+      "version": "1.5.1",
+      "resolved": "https://registry.npmjs.org/base64-js/-/base64-js-1.5.1.tgz",
+      "integrity": "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ],
+      "license": "MIT"
+    },
+    "node_modules/bidi-js": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/bidi-js/-/bidi-js-1.0.3.tgz",
+      "integrity": "sha512-RKshQI1R3YQ+n9YJz2QQ147P66ELpa1FQEg20Dk8oW9t2KgLbpDLLp9aGZ7y8WHSshDknG0bknqGw5/tyCs5tw==",
+      "license": "MIT",
+      "dependencies": {
+        "require-from-string": "^2.0.2"
+      }
+    },
     "node_modules/brace-expansion": {
       "version": "1.1.13",
       "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.13.tgz",
@@ -3053,6 +3300,24 @@
         "node": ">=8"
       }
     },
+    "node_modules/brotli": {
+      "version": "1.3.3",
+      "resolved": "https://registry.npmjs.org/brotli/-/brotli-1.3.3.tgz",
+      "integrity": "sha512-oTKjJdShmDuGW94SyyaoQvAjf30dZaHnjJ8uAF+u2/vGJkJbJPJAT1gDiOJP5v1Zb6f9KEyW/1HpuaWIXtGHPg==",
+      "license": "MIT",
+      "dependencies": {
+        "base64-js": "^1.1.2"
+      }
+    },
+    "node_modules/browserify-zlib": {
+      "version": "0.2.0",
+      "resolved": "https://registry.npmjs.org/browserify-zlib/-/browserify-zlib-0.2.0.tgz",
+      "integrity": "sha512-Z942RysHXmJrhqk88FmKBVq/v5tqmSkDz7p54G/MGyjMnCFFnC79XWNbg+Vta8W6Wb2qtSZTSxIGkJrRpCFEiA==",
+      "license": "MIT",
+      "dependencies": {
+        "pako": "~1.0.5"
+      }
+    },
     "node_modules/call-bind": {
       "version": "1.0.9",
       "resolved": "https://registry.npmjs.org/call-bind/-/call-bind-1.0.9.tgz",
@@ -3155,6 +3420,15 @@
       "integrity": "sha512-IV3Ou0jSMzZrd3pZ48nLkT9DA7Ag1pnPzaiQhpW7c3RbcqqzvzzVu+L8gfqMp/8IM2MQtSiqaCxrrcfu8I8rMA==",
       "license": "MIT"
     },
+    "node_modules/clone": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/clone/-/clone-2.1.2.tgz",
+      "integrity": "sha512-3Pe/CF1Nn94hyhIYpjtiLhdCoEoz0DqQ+988E9gmeEdQZlojxnOb74wctFyuwWQHzqyf9X7C7MG8juUpqBJT8w==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.8"
+      }
+    },
     "node_modules/color-convert": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz",
@@ -3175,6 +3449,27 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/color-string": {
+      "version": "2.1.4",
+      "resolved": "https://registry.npmjs.org/color-string/-/color-string-2.1.4.tgz",
+      "integrity": "sha512-Bb6Cq8oq0IjDOe8wJmi4JeNn763Xs9cfrBcaylK1tPypWzyoy2G3l90v9k64kjphl/ZJjPIShFztenRomi8WTg==",
+      "license": "MIT",
+      "dependencies": {
+        "color-name": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/color-string/node_modules/color-name": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/color-name/-/color-name-2.1.0.tgz",
+      "integrity": "sha512-1bPaDNFm0axzE4MEAzKPuqKWeRaT43U/hyxKPBdqTfmPF+d6n7FSoTFxLVULUJOmiLp01KjhIPPH+HrXZJN4Rg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12.20"
+      }
+    },
     "node_modules/combined-stream": {
       "version": "1.0.8",
       "resolved": "https://registry.npmjs.org/combined-stream/-/combined-stream-1.0.8.tgz",
@@ -3355,6 +3650,12 @@
         "node": ">=8"
       }
     },
+    "node_modules/dfa": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/dfa/-/dfa-1.2.0.tgz",
+      "integrity": "sha512-ED3jP8saaweFTjeGX8HQPjeC1YYyZs98jGNZx6IiBvxW7JG5v492kamAQB3m2wop07CvU/RQmzcKr6bgcC5D/Q==",
+      "license": "MIT"
+    },
     "node_modules/doctrine": {
       "version": "2.1.0",
       "resolved": "https://registry.npmjs.org/doctrine/-/doctrine-2.1.0.tgz",
@@ -3389,6 +3690,12 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/emoji-regex-xs": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/emoji-regex-xs/-/emoji-regex-xs-1.0.0.tgz",
+      "integrity": "sha512-LRlerrMYoIDrT6jgpeZ2YYl/L8EulRTt5hQcYjy5AInh7HWXKimpqx68aknBFpGL2+/IcogTcaydJEgaTmOpDg==",
+      "license": "MIT"
+    },
     "node_modules/end-of-stream": {
       "version": "1.4.5",
       "resolved": "https://registry.npmjs.org/end-of-stream/-/end-of-stream-1.4.5.tgz",
@@ -4006,6 +4313,15 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/events": {
+      "version": "3.3.0",
+      "resolved": "https://registry.npmjs.org/events/-/events-3.3.0.tgz",
+      "integrity": "sha512-mQw+2fkQbALzQ7V0MY0IqdnXNOeTtP4r0lN9z7AAawCXgqea7bDii20AYrIBrFd/Hx0M2Ocz6S111CaFkUcb0Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.8.x"
+      }
+    },
     "node_modules/events-universal": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/events-universal/-/events-universal-1.0.1.tgz",
@@ -4019,7 +4335,6 @@
       "version": "3.1.3",
       "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
       "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/fast-fifo": {
@@ -4082,6 +4397,12 @@
         "reusify": "^1.0.4"
       }
     },
+    "node_modules/fflate": {
+      "version": "0.8.3",
+      "resolved": "https://registry.npmjs.org/fflate/-/fflate-0.8.3.tgz",
+      "integrity": "sha512-tbZNuJrLwGUp3zshBtdy4W+ORxZuIh8a5ilyIEQDC5rY1f3U20JMry0Ll3WBzU58EZKsEuJFXhb5gwv8CsPvgA==",
+      "license": "MIT"
+    },
     "node_modules/file-entry-cache": {
       "version": "8.0.0",
       "resolved": "https://registry.npmjs.org/file-entry-cache/-/file-entry-cache-8.0.0.tgz",
@@ -4146,6 +4467,23 @@
       "dev": true,
       "license": "ISC"
     },
+    "node_modules/fontkit": {
+      "version": "2.0.4",
+      "resolved": "https://registry.npmjs.org/fontkit/-/fontkit-2.0.4.tgz",
+      "integrity": "sha512-syetQadaUEDNdxdugga9CpEYVaQIxOwk7GlwZWWZ19//qW4zE5bknOKeMBDYAASwnpaSHKJITRLMF9m1fp3s6g==",
+      "license": "MIT",
+      "dependencies": {
+        "@swc/helpers": "^0.5.12",
+        "brotli": "^1.3.2",
+        "clone": "^2.1.2",
+        "dfa": "^1.2.0",
+        "fast-deep-equal": "^3.1.3",
+        "restructure": "^3.0.0",
+        "tiny-inflate": "^1.0.3",
+        "unicode-properties": "^1.4.0",
+        "unicode-trie": "^2.0.0"
+      }
+    },
     "node_modules/for-each": {
       "version": "0.3.5",
       "resolved": "https://registry.npmjs.org/for-each/-/for-each-0.3.5.tgz",
@@ -4458,6 +4796,27 @@
         "node": ">=14"
       }
     },
+    "node_modules/hsl-to-hex": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/hsl-to-hex/-/hsl-to-hex-1.0.0.tgz",
+      "integrity": "sha512-K6GVpucS5wFf44X0h2bLVRDsycgJmf9FF2elg+CrqD8GcFU8c6vYhgXn8NjUkFCwj+xDFb70qgLbTUm6sxwPmA==",
+      "license": "MIT",
+      "dependencies": {
+        "hsl-to-rgb-for-reals": "^1.1.0"
+      }
+    },
+    "node_modules/hsl-to-rgb-for-reals": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/hsl-to-rgb-for-reals/-/hsl-to-rgb-for-reals-1.1.1.tgz",
+      "integrity": "sha512-LgOWAkrN0rFaQpfdWBQlv/VhkOxb5AsBjk6NQVx4yEzWS923T07X0M1Y0VNko2H52HeSpZrZNNMJ0aFqsdVzQg==",
+      "license": "ISC"
+    },
+    "node_modules/hyphen": {
+      "version": "1.14.1",
+      "resolved": "https://registry.npmjs.org/hyphen/-/hyphen-1.14.1.tgz",
+      "integrity": "sha512-kvL8xYl5QMTh+LwohVN72ciOxC0OEV79IPdJSTwEXok9y9QHebXGdFgrED4sWfiax/ODx++CAMk3hMy4XPJPOw==",
+      "license": "ISC"
+    },
     "node_modules/icu-minify": {
       "version": "4.9.0",
       "resolved": "https://registry.npmjs.org/icu-minify/-/icu-minify-4.9.0.tgz",
@@ -4510,6 +4869,12 @@
         "node": ">=0.8.19"
       }
     },
+    "node_modules/inherits": {
+      "version": "2.0.4",
+      "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
+      "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==",
+      "license": "ISC"
+    },
     "node_modules/internal-slot": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/internal-slot/-/internal-slot-1.1.0.tgz",
@@ -4899,6 +5264,12 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/is-url": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/is-url/-/is-url-1.2.4.tgz",
+      "integrity": "sha512-ITvGim8FhRiYe4IQ5uHSkj7pVaPDrCTkNd3yq3cV7iZAcJdHTUMPMEHcqSOy9xZ9qFenQCvi+2wjH9a1nXqHww==",
+      "license": "MIT"
+    },
     "node_modules/is-weakmap": {
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/is-weakmap/-/is-weakmap-2.0.2.tgz",
@@ -4986,6 +5357,15 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/jay-peg": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/jay-peg/-/jay-peg-1.1.1.tgz",
+      "integrity": "sha512-D62KEuBxz/ip2gQKOEhk/mx14o7eiFRaU+VNNSP4MOiIkwb/D6B3G1Mfas7C/Fit8EsSV2/IWjZElx/Gs6A4ww==",
+      "license": "MIT",
+      "dependencies": {
+        "restructure": "^3.0.0"
+      }
+    },
     "node_modules/jiti": {
       "version": "2.6.1",
       "resolved": "https://registry.npmjs.org/jiti/-/jiti-2.6.1.tgz",
@@ -5005,11 +5385,16 @@
         "url": "https://github.com/sponsors/panva"
       }
     },
+    "node_modules/js-md5": {
+      "version": "0.8.3",
+      "resolved": "https://registry.npmjs.org/js-md5/-/js-md5-0.8.3.tgz",
+      "integrity": "sha512-qR0HB5uP6wCuRMrWPTrkMaev7MJZwJuuw4fnwAzRgP4J4/F8RwtodOKpGp4XpqsLBFzzgqIO42efFAyz2Et6KQ==",
+      "license": "MIT"
+    },
     "node_modules/js-tokens": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz",
       "integrity": "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/js-yaml": {
@@ -5406,6 +5791,25 @@
         "url": "https://opencollective.com/parcel"
       }
     },
+    "node_modules/linebreak": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/linebreak/-/linebreak-1.1.0.tgz",
+      "integrity": "sha512-MHp03UImeVhB7XZtjd0E4n6+3xr5Dq/9xI/5FptGk5FrbDR3zagPa2DS6U8ks/3HjbKWG9Q1M2ufOzxV2qLYSQ==",
+      "license": "MIT",
+      "dependencies": {
+        "base64-js": "0.0.8",
+        "unicode-trie": "^2.0.0"
+      }
+    },
+    "node_modules/linebreak/node_modules/base64-js": {
+      "version": "0.0.8",
+      "resolved": "https://registry.npmjs.org/base64-js/-/base64-js-0.0.8.tgz",
+      "integrity": "sha512-3XSA2cR/h/73EzlXXdU6YNycmYI7+kicTxks4eJg2g39biHR84slg2+des+p7iHYhbRg/udIS4TD53WabcOUkw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
     "node_modules/locate-path": {
       "version": "6.0.0",
       "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-6.0.0.tgz",
@@ -5433,7 +5837,6 @@
       "version": "1.4.0",
       "resolved": "https://registry.npmjs.org/loose-envify/-/loose-envify-1.4.0.tgz",
       "integrity": "sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "js-tokens": "^3.0.0 || ^4.0.0"
@@ -5461,6 +5864,12 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/media-engine": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/media-engine/-/media-engine-1.0.3.tgz",
+      "integrity": "sha512-aa5tG6sDoK+k70B9iEX1NeyfT8ObCKhNDs6lJVpwF6r8vhUfuKMslIcirq6HIUYuuUYLefcEQOn9bSBOvawtwg==",
+      "license": "MIT"
+    },
     "node_modules/merge2": {
       "version": "1.4.1",
       "resolved": "https://registry.npmjs.org/merge2/-/merge2-1.4.1.tgz",
@@ -5844,6 +6253,15 @@
         "node": ">=6.0.0"
       }
     },
+    "node_modules/normalize-svg-path": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/normalize-svg-path/-/normalize-svg-path-1.1.0.tgz",
+      "integrity": "sha512-r9KHKG2UUeB5LoTouwDzBy2VxXlHsiM6fyLQvnJa0S5hrhzqElH/CH7TUGhT1fVvIYBIKf3OpY4YJ4CK+iaqHg==",
+      "license": "MIT",
+      "dependencies": {
+        "svg-arc-to-cubic-bezier": "^3.0.0"
+      }
+    },
     "node_modules/oauth4webapi": {
       "version": "3.8.5",
       "resolved": "https://registry.npmjs.org/oauth4webapi/-/oauth4webapi-3.8.5.tgz",
@@ -5857,7 +6275,6 @@
       "version": "4.1.1",
       "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz",
       "integrity": "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==",
-      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=0.10.0"
@@ -6066,6 +6483,12 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/pako": {
+      "version": "1.0.11",
+      "resolved": "https://registry.npmjs.org/pako/-/pako-1.0.11.tgz",
+      "integrity": "sha512-4hLB8Py4zZce5s4yd9XzopqwVv/yGNhV1Bl8NTmCq1763HeK2+EwVTv+leGeL13Dnh2wfbqowVPXCIO0z4taYw==",
+      "license": "(MIT AND Zlib)"
+    },
     "node_modules/parent-module": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/parent-module/-/parent-module-1.0.1.tgz",
@@ -6079,6 +6502,12 @@
         "node": ">=6"
       }
     },
+    "node_modules/parse-svg-path": {
+      "version": "0.1.2",
+      "resolved": "https://registry.npmjs.org/parse-svg-path/-/parse-svg-path-0.1.2.tgz",
+      "integrity": "sha512-JyPSBnkTJ0AI8GGJLfMXvKq42cj5c006fnLz6fXy6zfoVjJizi8BNTpu8on8ziI1cKy9d9DGNuY17Ce7wuejpQ==",
+      "license": "MIT"
+    },
     "node_modules/path-exists": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/path-exists/-/path-exists-4.0.0.tgz",
@@ -6214,6 +6643,14 @@
         "url": "https://github.com/sponsors/jonschlinkert"
       }
     },
+    "node_modules/png-js": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/png-js/-/png-js-2.0.0.tgz",
+      "integrity": "sha512-GdzJuUMc6ZSpxFJWVxtOH1bzYHym+TOnveqUjb+VJIbZWbZzyiRGFiKhbiielfpYbgMlhHVhsJ0FTazfuRFkMA==",
+      "dependencies": {
+        "fflate": "^0.8.2"
+      }
+    },
     "node_modules/po-parser": {
       "version": "2.1.1",
       "resolved": "https://registry.npmjs.org/po-parser/-/po-parser-2.1.1.tgz",
@@ -6259,6 +6696,12 @@
         "node": "^10 || ^12 || >=14"
       }
     },
+    "node_modules/postcss-value-parser": {
+      "version": "4.2.0",
+      "resolved": "https://registry.npmjs.org/postcss-value-parser/-/postcss-value-parser-4.2.0.tgz",
+      "integrity": "sha512-1NNCs6uurfkVbeXG4S8JFT9t19m45ICnif8zWLd5oPSZ50QnwMfK+H3jv408d4jw/7Bttv5axS5IiHoLaVNHeQ==",
+      "license": "MIT"
+    },
     "node_modules/postgres-array": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/postgres-array/-/postgres-array-2.0.0.tgz",
@@ -6331,7 +6774,6 @@
       "version": "15.8.1",
       "resolved": "https://registry.npmjs.org/prop-types/-/prop-types-15.8.1.tgz",
       "integrity": "sha512-oj87CgZICdulUohogVAR7AjlC0327U4el4L6eAvOqCeudMDVU0NThNaV+b9Df4dXgSP1gXMTnPdhfe/2qDH5cg==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "loose-envify": "^1.4.0",
@@ -6359,6 +6801,15 @@
         "node": ">=6"
       }
     },
+    "node_modules/queue": {
+      "version": "6.0.2",
+      "resolved": "https://registry.npmjs.org/queue/-/queue-6.0.2.tgz",
+      "integrity": "sha512-iHZWu+q3IdFZFX36ro/lKBkSvfkztY5Y7HMiPlOUjhupPcG2JMfst2KKEpu5XndviX/3UhFbRngUPNKtgvtZiA==",
+      "license": "MIT",
+      "dependencies": {
+        "inherits": "~2.0.3"
+      }
+    },
     "node_modules/queue-microtask": {
       "version": "1.2.3",
       "resolved": "https://registry.npmjs.org/queue-microtask/-/queue-microtask-1.2.3.tgz",
@@ -6405,7 +6856,6 @@
       "version": "16.13.1",
       "resolved": "https://registry.npmjs.org/react-is/-/react-is-16.13.1.tgz",
       "integrity": "sha512-24e6ynE2H+OKt4kqsOvNd8kBpV65zoxbA4BVsEOB3ARVWQki/DHzaUoC5KuON/BiccDaCCTZBuOcfZs70kR8bQ==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/reflect.getprototypeof": {
@@ -6452,6 +6902,15 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/require-from-string": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz",
+      "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/resolve": {
       "version": "2.0.0-next.6",
       "resolved": "https://registry.npmjs.org/resolve/-/resolve-2.0.0-next.6.tgz",
@@ -6496,6 +6955,12 @@
         "url": "https://github.com/privatenumber/resolve-pkg-maps?sponsor=1"
       }
     },
+    "node_modules/restructure": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/restructure/-/restructure-3.0.2.tgz",
+      "integrity": "sha512-gSfoiOEA0VPE6Tukkrr7I0RBdE0s7H1eFCDBk05l1KIQT1UIKNc5JZy6jdyW6eYH3aR3g5b3PuL77rq0hvwtAw==",
+      "license": "MIT"
+    },
     "node_modules/reusify": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/reusify/-/reusify-1.1.0.tgz",
@@ -6557,6 +7022,26 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/safe-buffer": {
+      "version": "5.2.1",
+      "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz",
+      "integrity": "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ],
+      "license": "MIT"
+    },
     "node_modules/safe-push-apply": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/safe-push-apply/-/safe-push-apply-1.0.0.tgz",
@@ -6901,6 +7386,15 @@
         "text-decoder": "^1.1.0"
       }
     },
+    "node_modules/string_decoder": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.3.0.tgz",
+      "integrity": "sha512-hkRX8U1WjJFd8LsDJ2yQ/wWWxaopEsABU1XfkM8A+j0+85JAGppt16cr1Whg6KIbb4okU6Mql6BOj+uup/wKeA==",
+      "license": "MIT",
+      "dependencies": {
+        "safe-buffer": "~5.2.0"
+      }
+    },
     "node_modules/string.prototype.includes": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/string.prototype.includes/-/string.prototype.includes-2.0.1.tgz",
@@ -7037,6 +7531,23 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/stripe": {
+      "version": "22.1.1",
+      "resolved": "https://registry.npmjs.org/stripe/-/stripe-22.1.1.tgz",
+      "integrity": "sha512-cmodIYP27tBkJ8G7DuGgWw0PFuemlFZbuF3Wwr1TrjFjUa3T7NIgCe6TVwX8BO2ynu+xtTuDGfHafNDCPt9lXA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "peerDependencies": {
+        "@types/node": ">=18"
+      },
+      "peerDependenciesMeta": {
+        "@types/node": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/styled-jsx": {
       "version": "5.1.6",
       "resolved": "https://registry.npmjs.org/styled-jsx/-/styled-jsx-5.1.6.tgz",
@@ -7086,6 +7597,12 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/svg-arc-to-cubic-bezier": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/svg-arc-to-cubic-bezier/-/svg-arc-to-cubic-bezier-3.2.0.tgz",
+      "integrity": "sha512-djbJ/vZKZO+gPoSDThGNpKDO+o+bAeA4XQKovvkNCqnIS2t+S4qnLAGQhyyrulhCFRl1WWzAp0wUDV8PpTVU3g==",
+      "license": "ISC"
+    },
     "node_modules/tailwindcss": {
       "version": "4.2.2",
       "resolved": "https://registry.npmjs.org/tailwindcss/-/tailwindcss-4.2.2.tgz",
@@ -7151,6 +7668,12 @@
         "b4a": "^1.6.4"
       }
     },
+    "node_modules/tiny-inflate": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/tiny-inflate/-/tiny-inflate-1.0.3.tgz",
+      "integrity": "sha512-pkY1fj1cKHb2seWDy0B16HeWyczlJA9/WW3u3c4z/NiWDsO3DOU5D7nhTLE9CF0yXv/QZFY7sEJmj24dK+Rrqw==",
+      "license": "MIT"
+    },
     "node_modules/tinyglobby": {
       "version": "0.2.16",
       "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.16.tgz",
@@ -7380,6 +7903,32 @@
       "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",
       "license": "MIT"
     },
+    "node_modules/unicode-properties": {
+      "version": "1.4.1",
+      "resolved": "https://registry.npmjs.org/unicode-properties/-/unicode-properties-1.4.1.tgz",
+      "integrity": "sha512-CLjCCLQ6UuMxWnbIylkisbRj31qxHPAurvena/0iwSVbQ2G1VY5/HjV0IRabOEbDHlzZlRdCrD4NhB0JtU40Pg==",
+      "license": "MIT",
+      "dependencies": {
+        "base64-js": "^1.3.0",
+        "unicode-trie": "^2.0.0"
+      }
+    },
+    "node_modules/unicode-trie": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/unicode-trie/-/unicode-trie-2.0.0.tgz",
+      "integrity": "sha512-x7bc76x0bm4prf1VLg79uhAzKw8DVboClSN5VxJuQ+LKDOVEW9CdH+VY7SP+vX7xCYQqzzgQpFqz15zeLvAtZQ==",
+      "license": "MIT",
+      "dependencies": {
+        "pako": "^0.2.5",
+        "tiny-inflate": "^1.0.0"
+      }
+    },
+    "node_modules/unicode-trie/node_modules/pako": {
+      "version": "0.2.9",
+      "resolved": "https://registry.npmjs.org/pako/-/pako-0.2.9.tgz",
+      "integrity": "sha512-NUcwaKxUxWrZLpDG+z/xZaCgQITkA/Dv4V/T6bw7VON6l1Xz/VnrBqrYjZQ12TamKHzITTfOEIYUj48y2KXImA==",
+      "license": "MIT"
+    },
     "node_modules/unrs-resolver": {
       "version": "1.11.1",
       "resolved": "https://registry.npmjs.org/unrs-resolver/-/unrs-resolver-1.11.1.tgz",
@@ -7446,6 +7995,26 @@
         "react": "^17.0.0 || ^18.0.0 || >=19.0.0-rc <19.0.0 || ^19.0.0"
       }
     },
+    "node_modules/util-deprecate": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz",
+      "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==",
+      "license": "MIT"
+    },
+    "node_modules/vite-compatible-readable-stream": {
+      "version": "3.6.1",
+      "resolved": "https://registry.npmjs.org/vite-compatible-readable-stream/-/vite-compatible-readable-stream-3.6.1.tgz",
+      "integrity": "sha512-t20zYkrSf868+j/p31cRIGN28Phrjm3nRSLR2fyc2tiWi4cZGVdv68yNlwnIINTkMTmPoMiSlc0OadaO7DXZaQ==",
+      "license": "MIT",
+      "dependencies": {
+        "inherits": "^2.0.3",
+        "string_decoder": "^1.1.1",
+        "util-deprecate": "^1.0.1"
+      },
+      "engines": {
+        "node": ">= 6"
+      }
+    },
     "node_modules/webidl-conversions": {
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-3.0.1.tgz",
@@ -7626,6 +8195,12 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/yoga-layout": {
+      "version": "3.2.1",
+      "resolved": "https://registry.npmjs.org/yoga-layout/-/yoga-layout-3.2.1.tgz",
+      "integrity": "sha512-0LPOt3AxKqMdFBZA3HBAt/t/8vIKq7VaQYbuA8WxCgung+p9TVyKRYdpvCb80HcdTN2NkbIKbhNwKUfm3tQywQ==",
+      "license": "MIT"
+    },
     "node_modules/zod": {
       "version": "3.25.76",
       "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz",

package.json

@@ -11,6 +11,7 @@
   },
   "dependencies": {
     "@kubernetes/client-node": "^1.4.0",
+    "@react-pdf/renderer": "^4.4.0",
     "@types/nodemailer": "^8.0.0",
     "@types/pg": "^8.20.0",
     "next": "^15.5.15",
@@ -20,6 +21,7 @@
     "pg": "^8.20.0",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
+    "stripe": "^22.1.1",
     "zod": "^3.24.0"
   },
   "devDependencies": {

src/app/[locale]/admin/billing/generate/page.tsx

@@ -0,0 +1,71 @@
+import { redirect } from "next/navigation";
+import { getTranslations } from "next-intl/server";
+import { getSessionUser } from "@/lib/session";
+import { listTenants } from "@/lib/k8s";
+import { getOrgBilling } from "@/lib/db";
+import { BackLink } from "@/components/ui/back-link";
+import { GenerateForm } from "@/components/admin/billing/generate-form";
+
+/**
+ * /admin/billing/generate — testing tool to compute & commit an
+ * invoice for a given (org, period).
+ *
+ * Workflow:
+ *   1. Admin picks org + year/month + locale (default auto-detected
+ *      from country).
+ *   2. "Preview" runs computeInvoiceDraft (dryRun) — shows lines,
+ *      totals, warnings.
+ *   3. "Commit" persists + renders the PDF.
+ *
+ * The org dropdown is hydrated server-side here so the page loads
+ * with the list pre-populated. Per-org billing status (address
+ * present / open balance) is fetched on demand from /api/admin/
+ * billing/orgs since it can change as admin edits.
+ */
+export default async function AdminBillingGeneratePage() {
+  const user = await getSessionUser();
+  if (!user) redirect("/login");
+  if (!user.isPlatform) redirect("/dashboard");
+  const t = await getTranslations("adminBilling");
+
+  // Build initial org list from tenant labels.
+  const tenants = await listTenants();
+  const orgMap = new Map<string, string[]>();
+  for (const t of tenants) {
+    const oid = t.metadata.labels?.["pieced.ch/zitadel-org-id"];
+    if (!oid) continue;
+    if (!orgMap.has(oid)) orgMap.set(oid, []);
+    orgMap.get(oid)!.push(t.metadata.name);
+  }
+  // Hydrate company name + country in parallel.
+  const orgList = await Promise.all(
+    [...orgMap.entries()].map(async ([orgId, tenantNames]) => {
+      const billing = await getOrgBilling(orgId).catch(() => null);
+      return {
+        zitadelOrgId: orgId,
+        tenantNames,
+        companyName: billing?.companyName ?? null,
+        country: billing?.country ?? null,
+        hasBillingAddress: !!billing,
+      };
+    })
+  );
+  orgList.sort((a, b) =>
+    (a.companyName ?? a.zitadelOrgId).localeCompare(
+      b.companyName ?? b.zitadelOrgId
+    )
+  );
+
+  return (
+    <main className="max-w-4xl mx-auto px-6 py-8">
+      <BackLink href="/admin/billing" label={t("backToBilling")} />
+      <div className="mb-8 animate-in">
+        <h1 className="font-display text-2xl font-semibold accent-rule">
+          {t("generateTitle")}
+        </h1>
+        <p className="text-sm text-text-secondary mt-3">{t("generatePageDesc")}</p>
+      </div>
+      <GenerateForm orgs={orgList} />
+    </main>
+  );
+}

src/app/[locale]/admin/billing/invoices/[id]/page.tsx

@@ -0,0 +1,35 @@
+import { notFound, redirect } from "next/navigation";
+import { getTranslations } from "next-intl/server";
+import { getSessionUser } from "@/lib/session";
+import { getInvoiceDetail } from "@/lib/db";
+import { BackLink } from "@/components/ui/back-link";
+import { InvoiceDetailView } from "@/components/admin/billing/invoice-detail-view";
+
+/**
+ * /admin/billing/invoices/[id] — full detail of one invoice.
+ *
+ * Server-renders the static body (header, lines, totals, billing
+ * snapshot); the action bar (mark-paid, delete, PDF download) is
+ * a client component for the interactive bits.
+ */
+export default async function AdminInvoiceDetailPage({
+  params,
+}: {
+  params: Promise<{ id: string }>;
+}) {
+  const user = await getSessionUser();
+  if (!user) redirect("/login");
+  if (!user.isPlatform) redirect("/dashboard");
+  const t = await getTranslations("adminBilling");
+
+  const { id } = await params;
+  const detail = await getInvoiceDetail(id);
+  if (!detail) notFound();
+
+  return (
+    <main className="max-w-4xl mx-auto px-6 py-8">
+      <BackLink href="/admin/billing/invoices" label={t("backToInvoices")} />
+      <InvoiceDetailView detail={detail} />
+    </main>
+  );
+}

src/app/[locale]/admin/billing/invoices/page.tsx

@@ -0,0 +1,39 @@
+import { redirect } from "next/navigation";
+import { getTranslations } from "next-intl/server";
+import { getSessionUser } from "@/lib/session";
+import { listInvoices, syncOverdueInvoices } from "@/lib/db";
+import { BackLink } from "@/components/ui/back-link";
+import { InvoicesTable } from "@/components/admin/billing/invoices-table";
+
+/**
+ * /admin/billing/invoices — list of all issued invoices, filterable
+ * by status and month. Click a row to drill into detail.
+ *
+ * Server-renders the initial table with no filters applied (showing
+ * the most recent 200). Client filters trigger a fetch with query
+ * params and re-render in place.
+ */
+export default async function AdminInvoicesListPage() {
+  const user = await getSessionUser();
+  if (!user) redirect("/login");
+  if (!user.isPlatform) redirect("/dashboard");
+  const t = await getTranslations("adminBilling");
+
+  await syncOverdueInvoices().catch((e) =>
+    console.error("syncOverdueInvoices failed:", e)
+  );
+  const invoices = await listInvoices({ limit: 200 });
+
+  return (
+    <main className="max-w-5xl mx-auto px-6 py-8">
+      <BackLink href="/admin/billing" label={t("backToBilling")} />
+      <div className="mb-8 animate-in">
+        <h1 className="font-display text-2xl font-semibold accent-rule">
+          {t("invoicesTitle")}
+        </h1>
+        <p className="text-sm text-text-secondary mt-3">{t("invoicesPageDesc")}</p>
+      </div>
+      <InvoicesTable initialInvoices={invoices} />
+    </main>
+  );
+}

src/app/[locale]/admin/billing/page.tsx

@@ -0,0 +1,128 @@
+import Link from "next/link";
+import { redirect } from "next/navigation";
+import { getTranslations } from "next-intl/server";
+import { getSessionUser } from "@/lib/session";
+import { getOrgOpenBalances, syncOverdueInvoices } from "@/lib/db";
+import { Card } from "@/components/ui/card";
+
+/**
+ * /admin/billing — landing page with sub-section links and a
+ * quick overview of orgs in arrears.
+ *
+ * Sub-pages:
+ *   - /admin/billing/pricing   — platform + skill prices
+ *   - /admin/billing/generate  — manual invoice generator (testing)
+ *   - /admin/billing/invoices  — invoice list/detail
+ *
+ * The Phase 2 customer-side /billing landing page is added in
+ * Phase 3.
+ */
+export default async function AdminBillingPage() {
+  const user = await getSessionUser();
+  if (!user) redirect("/login");
+  if (!user.isPlatform) redirect("/dashboard");
+  const t = await getTranslations("adminBilling");
+
+  // Sweep open invoices past due → 'overdue' so the counters below
+  // reflect reality without needing a cron.
+  await syncOverdueInvoices().catch((e) =>
+    console.error("syncOverdueInvoices failed:", e)
+  );
+  const balances = await getOrgOpenBalances().catch(() => []);
+  const totalOpen = balances.reduce((acc, b) => acc + b.totalOpenChf, 0);
+  const totalOverdue = balances.reduce((acc, b) => acc + b.overdueCount, 0);
+
+  return (
+    <main className="max-w-5xl mx-auto px-6 py-8">
+      <div className="mb-8 animate-in">
+        <h1 className="font-display text-2xl font-semibold accent-rule">
+          {t("title")}
+        </h1>
+        <p className="text-sm text-text-secondary mt-3">{t("subtitle")}</p>
+      </div>
+
+      {/* Stats strip */}
+      <div className="grid grid-cols-3 gap-4 mb-8 animate-in animate-in-delay-1">
+        <Card>
+          <div className="text-xs text-text-muted">{t("totalOpenBalance")}</div>
+          <div className="text-2xl font-semibold mt-1">
+            CHF {totalOpen.toFixed(2)}
+          </div>
+        </Card>
+        <Card>
+          <div className="text-xs text-text-muted">{t("orgsWithBalance")}</div>
+          <div className="text-2xl font-semibold mt-1">{balances.length}</div>
+        </Card>
+        <Card>
+          <div className="text-xs text-text-muted">{t("overdueInvoices")}</div>
+          <div className="text-2xl font-semibold mt-1">
+            {totalOverdue > 0 ? (
+              <span className="text-error">{totalOverdue}</span>
+            ) : (
+              totalOverdue
+            )}
+          </div>
+        </Card>
+      </div>
+
+      {/* Sub-tool cards */}
+      <div className="grid grid-cols-3 gap-4 mb-8 animate-in animate-in-delay-2">
+        <Link href="/admin/billing/pricing">
+          <Card interactive>
+            <div className="font-semibold mb-1">{t("pricingTitle")}</div>
+            <div className="text-sm text-text-muted">{t("pricingDesc")}</div>
+          </Card>
+        </Link>
+        <Link href="/admin/billing/generate">
+          <Card interactive>
+            <div className="font-semibold mb-1">{t("generateTitle")}</div>
+            <div className="text-sm text-text-muted">{t("generateDesc")}</div>
+          </Card>
+        </Link>
+        <Link href="/admin/billing/invoices">
+          <Card interactive>
+            <div className="font-semibold mb-1">{t("invoicesTitle")}</div>
+            <div className="text-sm text-text-muted">{t("invoicesDesc")}</div>
+          </Card>
+        </Link>
+      </div>
+
+      {/* Orgs with open balance */}
+      {balances.length > 0 && (
+        <div className="animate-in animate-in-delay-3">
+          <h2 className="text-lg font-semibold mb-3">{t("balancesTitle")}</h2>
+          <Card>
+            <table className="w-full text-sm">
+              <thead className="text-xs text-text-muted text-left">
+                <tr>
+                  <th className="pb-2">{t("orgIdCol")}</th>
+                  <th className="pb-2 text-right">{t("openCountCol")}</th>
+                  <th className="pb-2 text-right">{t("overdueCountCol")}</th>
+                  <th className="pb-2 text-right">{t("totalOpenCol")}</th>
+                </tr>
+              </thead>
+              <tbody>
+                {balances.map((b) => (
+                  <tr key={b.zitadelOrgId} className="border-t border-border">
+                    <td className="py-2 font-mono text-xs">{b.zitadelOrgId}</td>
+                    <td className="py-2 text-right">{b.openCount}</td>
+                    <td className="py-2 text-right">
+                      {b.overdueCount > 0 ? (
+                        <span className="text-error">{b.overdueCount}</span>
+                      ) : (
+                        <span className="text-text-muted">0</span>
+                      )}
+                    </td>
+                    <td className="py-2 text-right">
+                      CHF {b.totalOpenChf.toFixed(2)}
+                    </td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </Card>
+        </div>
+      )}
+    </main>
+  );
+}

src/app/[locale]/admin/billing/pricing/page.tsx

@@ -0,0 +1,55 @@
+import { redirect } from "next/navigation";
+import { getTranslations } from "next-intl/server";
+import { getSessionUser } from "@/lib/session";
+import { getPlatformPricing, listSkillPricing } from "@/lib/db";
+import { PACKAGE_CATALOG } from "@/lib/packages";
+import { BackLink } from "@/components/ui/back-link";
+import { PricingEditor } from "@/components/admin/billing/pricing-editor";
+
+/**
+ * /admin/billing/pricing — edit platform-wide pricing config
+ * (monthly fee, setup fee, Threema per-message, VAT rate for
+ * CH/LI) and per-skill daily prices.
+ *
+ * Single-row platform_pricing semantics: one global pricing
+ * config applies to every tenant. No per-tenant overrides in
+ * v1.
+ */
+export default async function AdminBillingPricingPage() {
+  const user = await getSessionUser();
+  if (!user) redirect("/login");
+  if (!user.isPlatform) redirect("/dashboard");
+  const t = await getTranslations("adminBilling");
+
+  const [pricing, skillPricing] = await Promise.all([
+    getPlatformPricing(),
+    listSkillPricing(),
+  ]);
+
+  // Surface every package in the catalog so admin can price any of
+  // them — UI defaults the picker to skill-kind entries but doesn't
+  // hard-block other kinds (a future scenario where a non-skill
+  // package gets a per-day price shouldn't need a code change).
+  const catalog = Object.values(PACKAGE_CATALOG).map((p) => ({
+    id: p.id,
+    name: p.name,
+    category: p.category,
+  }));
+
+  return (
+    <main className="max-w-4xl mx-auto px-6 py-8">
+      <BackLink href="/admin/billing" label={t("backToBilling")} />
+      <div className="mb-8 animate-in">
+        <h1 className="font-display text-2xl font-semibold accent-rule">
+          {t("pricingTitle")}
+        </h1>
+        <p className="text-sm text-text-secondary mt-3">{t("pricingPageDesc")}</p>
+      </div>
+      <PricingEditor
+        initialPricing={pricing}
+        initialSkillPricing={skillPricing}
+        catalog={catalog}
+      />
+    </main>
+  );
+}

src/app/[locale]/admin/openclaw/page.tsx

@@ -0,0 +1,71 @@
+import { redirect } from "next/navigation";
+import { getTranslations } from "next-intl/server";
+import { getSessionUser } from "@/lib/session";
+import { listTenants, getOpenClawDefaults } from "@/lib/k8s";
+import { OpenClawAdminPanel } from "@/components/admin/openclaw-admin-panel";
+
+/**
+ * /admin/openclaw — platform-default OpenClaw image + per-tenant
+ * overrides table.
+ *
+ * Two sections:
+ *   1. Default — readable from `pieced-openclaw-config` ConfigMap.
+ *      Editable via the same form. Empty fields show as "(unset)"
+ *      and the operator falls back to its built-in default in that
+ *      case (intentionally invisible to the portal — the binary's
+ *      baked version moves with releases and we don't want the UI
+ *      to claim a misleading "current default").
+ *   2. Tenant table — every tenant in the cluster with its current
+ *      override (or "follows default"). Clicking a row opens a small
+ *      inline editor.
+ *
+ * Authorization is gated server-side: `user.isPlatform` only. Any
+ * other user gets redirected to /dashboard.
+ */
+export default async function OpenClawAdminPage() {
+  const user = await getSessionUser();
+  if (!user) redirect("/login");
+  if (!user.isPlatform) redirect("/dashboard");
+  const t = await getTranslations("openclawAdmin");
+
+  // Parallel fetch — defaults and tenants are independent.
+  const [defaults, tenants] = await Promise.all([
+    getOpenClawDefaults(),
+    listTenants(),
+  ]);
+
+  // Sort tenants: overridden first (more interesting to review),
+  // then alphabetically by display name. Helps the admin spot which
+  // tenants are off the platform default at a glance.
+  const sorted = [...tenants].sort((a, b) => {
+    const aOverride = a.spec.openClawImage ? 1 : 0;
+    const bOverride = b.spec.openClawImage ? 1 : 0;
+    if (aOverride !== bOverride) return bOverride - aOverride;
+    return (a.spec.displayName || a.metadata.name).localeCompare(
+      b.spec.displayName || b.metadata.name
+    );
+  });
+
+  return (
+    <main className="max-w-5xl mx-auto px-6 py-8">
+      <div className="mb-8 animate-in">
+        <h1 className="font-display text-2xl font-semibold accent-rule">
+          {t("title")}
+        </h1>
+        <p className="text-sm text-text-secondary mt-3">{t("subtitle")}</p>
+      </div>
+
+      <OpenClawAdminPanel
+        initialDefaults={defaults}
+        tenants={sorted.map((tn) => ({
+          name: tn.metadata.name,
+          displayName: tn.spec.displayName || tn.metadata.name,
+          phase: tn.status?.phase ?? "Unknown",
+          override: tn.spec.openClawImage?.tag
+            ? { tag: tn.spec.openClawImage.tag }
+            : null,
+        }))}
+      />
+    </main>
+  );
+}

src/app/[locale]/admin/page.tsx

@@ -2,6 +2,7 @@ import { getSessionUser } from "@/lib/session";
 import { getTranslations } from "next-intl/server";
 import { redirect } from "next/navigation";
 import { listTenants } from "@/lib/k8s";
+import { countPendingSkillActivationRequests } from "@/lib/db";
 import { AdminPanel } from "@/components/admin/admin-panel";
 
 export default async function AdminPage() {
@@ -19,15 +20,55 @@ export default async function AdminPage() {
   }
 
   const tenants = await listTenants();
+  // Phase 2.5: badge counter for the skill-activation admin queue.
+  // Cheap COUNT(*) on a partial-indexed status='pending' column —
+  // bounded by request volume and never expected to be high.
+  const pendingSkillCount = await countPendingSkillActivationRequests().catch(
+    () => 0
+  );
 
   return (
     <div>
-      <div className="mb-8 animate-in">
+      <div className="mb-8 animate-in flex items-end justify-between gap-4 flex-wrap">
+        <div>
           <h1 className="font-display text-2xl font-semibold accent-rule mb-2">
             {t("title")}
           </h1>
           <p className="text-text-secondary text-sm mt-4">{t("subtitle")}</p>
         </div>
+        {/* Sub-tools: links to other admin pages. Plain links rather
+            than nav-shell entries — these are platform-team utilities,
+            not main navigation. */}
+        <div className="flex items-center gap-2">
+          <a
+            href="/admin/skills/pending"
+            className={`text-sm px-4 py-2 rounded-lg border transition-colors flex items-center gap-2 ${
+              pendingSkillCount > 0
+                ? "border-warning text-warning hover:bg-warning/10"
+                : "border-border text-text-secondary hover:text-text-primary hover:border-text-secondary"
+            }`}
+          >
+            <span>{t("skillsQueueTool")}</span>
+            {pendingSkillCount > 0 && (
+              <span className="text-xs px-1.5 py-0.5 rounded bg-warning text-surface-0 font-semibold">
+                {pendingSkillCount}
+              </span>
+            )}
+          </a>
+          <a
+            href="/admin/billing"
+            className="text-sm px-4 py-2 rounded-lg border border-border text-text-secondary hover:text-text-primary hover:border-text-secondary transition-colors"
+          >
+            {t("billingTool")}
+          </a>
+          <a
+            href="/admin/openclaw"
+            className="text-sm px-4 py-2 rounded-lg border border-border text-text-secondary hover:text-text-primary hover:border-text-secondary transition-colors"
+          >
+            {t("openclawTool")}
+          </a>
+        </div>
+      </div>
 
       <div className="animate-in animate-in-delay-1">
         <AdminPanel initialTenants={tenants} />

src/app/[locale]/admin/skills/pending/page.tsx

@@ -0,0 +1,59 @@
+import { redirect } from "next/navigation";
+import { getTranslations } from "next-intl/server";
+import { getSessionUser } from "@/lib/session";
+import { listPendingSkillActivationRequests, getOrgBilling } from "@/lib/db";
+import { getPackageDef } from "@/lib/packages";
+import { BackLink } from "@/components/ui/back-link";
+import { PendingSkillRequests } from "@/components/admin/skills/pending-skill-requests";
+
+/**
+ * /admin/skills/pending — admin queue for manual-setup skill
+ * activation requests. Each row shows tenant, skill, requester
+ * info, and offers Approve / Reject actions.
+ *
+ * Server-renders the initial list. Approval/rejection trigger a
+ * client-side fetch + router.refresh() so the row disappears and
+ * the count updates without a hard reload.
+ */
+export default async function AdminPendingSkillRequestsPage() {
+  const user = await getSessionUser();
+  if (!user) redirect("/login");
+  if (!user.isPlatform) redirect("/dashboard");
+  const t = await getTranslations("adminSkills");
+
+  const pending = await listPendingSkillActivationRequests();
+
+  // Hydrate display fields: skill name from catalog, org company name
+  // from billing. Skill name fallback to skillId for off-catalog
+  // entries (shouldn't happen but defensive). Company name is
+  // looked up lazily per row; dedup'd via a Map so we don't issue
+  // duplicate getOrgBilling calls for the same org.
+  const seenOrg = new Map<string, string | null>();
+  const rows = await Promise.all(
+    pending.map(async (r) => {
+      if (!seenOrg.has(r.zitadelOrgId)) {
+        const billing = await getOrgBilling(r.zitadelOrgId).catch(() => null);
+        seenOrg.set(r.zitadelOrgId, billing?.companyName ?? null);
+      }
+      const def = getPackageDef(r.skillId);
+      return {
+        ...r,
+        skillName: def?.name ?? r.skillId,
+        companyName: seenOrg.get(r.zitadelOrgId) ?? null,
+      };
+    })
+  );
+
+  return (
+    <main className="max-w-5xl mx-auto px-6 py-8">
+      <BackLink href="/admin" label={t("backToAdmin")} />
+      <div className="mb-8 animate-in">
+        <h1 className="font-display text-2xl font-semibold accent-rule">
+          {t("title")}
+        </h1>
+        <p className="text-sm text-text-secondary mt-3">{t("subtitle")}</p>
+      </div>
+      <PendingSkillRequests initialRows={rows} />
+    </main>
+  );
+}

src/app/[locale]/billing/[invoiceNumber]/page.tsx

@@ -0,0 +1,35 @@
+import { redirect, notFound } from "next/navigation";
+import { getTranslations } from "next-intl/server";
+import { getSessionUser } from "@/lib/session";
+import { getInvoiceByNumberForOrg } from "@/lib/db";
+import { BackLink } from "@/components/ui/back-link";
+import { CustomerInvoiceDetail } from "@/components/billing/customer-invoice-detail";
+
+/**
+ * /billing/[invoiceNumber] — single-invoice view.
+ *
+ * Lookup is by the human-readable invoice number (the YYYY-NNNNN
+ * format printed on the PDF and in the issuance email). Org
+ * filter is enforced in the DB query — a customer trying another
+ * org's number gets 404, not 403, to avoid leaking the existence
+ * of other orgs' invoices.
+ */
+export default async function CustomerInvoiceDetailPage({
+  params,
+}: {
+  params: Promise<{ invoiceNumber: string; locale: string }>;
+}) {
+  const user = await getSessionUser();
+  if (!user) redirect("/login");
+  const { invoiceNumber } = await params;
+  const t = await getTranslations("customerBilling");
+  const detail = await getInvoiceByNumberForOrg(invoiceNumber, user.orgId);
+  if (!detail) notFound();
+
+  return (
+    <main className="max-w-3xl mx-auto px-6 py-8">
+      <BackLink href="/billing" label={t("backToBilling")} />
+      <CustomerInvoiceDetail invoice={detail.invoice} lines={detail.lines} />
+    </main>
+  );
+}

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

@@ -0,0 +1,63 @@
+import { redirect } from "next/navigation";
+import { getTranslations } from "next-intl/server";
+import { getSessionUser } from "@/lib/session";
+import { listInvoices, syncOverdueInvoices } from "@/lib/db";
+import { CustomerInvoiceList } from "@/components/billing/customer-invoice-list";
+import { RunningTotalWidget } from "@/components/billing/running-total-widget";
+
+/**
+ * /billing — customer's billing home.
+ *
+ * Shows two things:
+ *   1. RunningTotalWidget — current calendar month's accruing cost
+ *      (or the already-issued invoice for the current month, if
+ *      that ran early).
+ *   2. CustomerInvoiceList — every issued invoice for this org,
+ *      newest first. Status is reflected with a colored badge.
+ *
+ * Anyone signed in can view this. The data is org-scoped; even
+ * non-owner team members see the same view. Phase 4 will add a
+ * "settings.payByInvoice" toggle visibility-gated to owners only.
+ */
+export default async function CustomerBillingPage() {
+  const user = await getSessionUser();
+  if (!user) redirect("/login");
+  const t = await getTranslations("customerBilling");
+
+  // Sync overdue status before listing — cheap, idempotent.
+  try {
+    await syncOverdueInvoices();
+  } catch (e) {
+    console.warn("syncOverdueInvoices failed in /billing:", e);
+  }
+
+  const invoices = await listInvoices({
+    zitadelOrgId: user.orgId,
+    limit: 200,
+  });
+
+  return (
+    <main className="max-w-5xl mx-auto px-6 py-8">
+      <div className="mb-8 animate-in">
+        <h1 className="font-display text-2xl font-semibold accent-rule">
+          {t("title")}
+        </h1>
+        <p className="text-sm text-text-secondary mt-3">{t("subtitle")}</p>
+      </div>
+
+      <section className="mb-8 animate-in animate-in-delay-1">
+        <h2 className="text-xs font-semibold uppercase tracking-wider text-text-muted mb-3">
+          {t("currentPeriodHeading")}
+        </h2>
+        <RunningTotalWidget />
+      </section>
+
+      <section className="animate-in animate-in-delay-2">
+        <h2 className="text-xs font-semibold uppercase tracking-wider text-text-muted mb-3">
+          {t("historyHeading")}
+        </h2>
+        <CustomerInvoiceList invoices={invoices} />
+      </section>
+    </main>
+  );
+}

src/app/[locale]/settings/billing/page.tsx

@@ -40,6 +40,7 @@ export default async function BillingSettingsPage() {
         isPersonal={user.isPersonal}
         orgName={user.orgName}
         userName={user.name}
+        userEmail={user.email}
       />
     </main>
   );

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

@@ -33,7 +33,12 @@ export default async function SettingsPage() {
       key: "billing",
       href: "/settings/billing",
       title: t("billingTitle"),
-      description: t("billingDescription"),
+      // Personal customers (B2C) don't have a VAT number; the
+      // description shouldn't mention one. Same pattern used in the
+      // form itself (label/field gating).
+      description: user.isPersonal
+        ? t("billingDescriptionPersonal")
+        : t("billingDescription"),
       // Owners and platform admins can edit billing. `user` role
       // can't even view it — billing details aren't useful to them.
       visible: canMutate(user),

src/app/[locale]/support/[id]/page.tsx

@@ -0,0 +1,103 @@
+import { notFound, redirect } from "next/navigation";
+import { getTranslations, getFormatter } from "next-intl/server";
+import { getSessionUser } from "@/lib/session";
+import {
+  getSupportTicketById,
+  listCommentsForTicket,
+} from "@/lib/db";
+import { Card } from "@/components/ui/card";
+import { BackLink } from "@/components/ui/back-link";
+import { TicketStatusBadge } from "@/components/support/ticket-status-badge";
+import { TicketCategoryLabel } from "@/components/support/ticket-category-label";
+import { TicketThread } from "@/components/support/ticket-thread";
+import { TicketAdminControls } from "@/components/support/ticket-admin-controls";
+import { formatDateTime } from "@/lib/format";
+
+/**
+ * /support/[id] — single ticket detail.
+ *
+ * Same UI for customer and admin; admin gets an extra
+ * `<TicketAdminControls>` block for changing status/category. The
+ * customer side gets a "Close ticket" link if they want to mark it
+ * resolved themselves.
+ *
+ * Authorization mirrors the API: customer sees their own; platform
+ * admin sees any. 404 (not 403) when a customer accesses someone
+ * else's ticket — don't leak existence.
+ */
+export default async function TicketDetailPage({
+  params,
+}: {
+  params: Promise<{ id: string }>;
+}) {
+  const user = await getSessionUser();
+  if (!user) redirect("/login");
+  const { id } = await params;
+  const ticket = await getSupportTicketById(id);
+  if (!ticket) notFound();
+  if (!user.isPlatform && ticket.zitadelUserId !== user.id) {
+    notFound();
+  }
+  const comments = await listCommentsForTicket(id);
+  const t = await getTranslations("support");
+  const f = await getFormatter();
+
+  return (
+    <main className="max-w-3xl mx-auto px-6 py-8">
+      <div className="mb-6 animate-in">
+        <BackLink href="/support" label={t("title")} />
+        <div className="flex items-start justify-between gap-3 mt-2">
+          <h1 className="font-display text-2xl font-semibold">
+            {ticket.title}
+          </h1>
+          <TicketStatusBadge status={ticket.status} />
+        </div>
+        <div className="text-xs text-text-muted mt-2 flex items-center gap-2 flex-wrap">
+          <TicketCategoryLabel category={ticket.category} />
+          <span>·</span>
+          <span>
+            {t("openedBy", {
+              name: ticket.contactName,
+              when: formatDateTime(ticket.createdAt, f),
+            })}
+          </span>
+          <span>·</span>
+          <span className="font-mono">#{ticket.id.slice(0, 8)}</span>
+        </div>
+      </div>
+
+      {/* Original ticket description, rendered as the first message
+          in the thread. Visually distinct via the customer-author
+          styling (handled inside <TicketThread>). */}
+      <div className="space-y-4 animate-in animate-in-delay-1">
+        <Card>
+          <div className="flex items-center justify-between text-xs text-text-muted mb-2">
+            <span className="font-medium text-text-primary">
+              {ticket.contactName}
+            </span>
+            <span>{formatDateTime(ticket.createdAt, f)}</span>
+          </div>
+          <div className="text-sm text-text-primary whitespace-pre-wrap">
+            {ticket.description}
+          </div>
+        </Card>
+
+        <TicketThread
+          ticketId={ticket.id}
+          ticketStatus={ticket.status}
+          comments={comments}
+          isPlatform={user.isPlatform}
+          isOwnTicket={ticket.zitadelUserId === user.id}
+        />
+
+        {user.isPlatform && (
+          <TicketAdminControls
+            ticketId={ticket.id}
+            currentStatus={ticket.status}
+            currentCategory={ticket.category}
+          />
+        )}
+      </div>
+    </main>
+  );
+}

src/app/[locale]/support/new/page.tsx

@@ -0,0 +1,37 @@
+import { redirect } from "next/navigation";
+import { getTranslations } from "next-intl/server";
+import { getSessionUser } from "@/lib/session";
+import { TicketCreateForm } from "@/components/support/ticket-create-form";
+import { BackLink } from "@/components/ui/back-link";
+
+/**
+ * /support/new — create ticket form.
+ *
+ * Platform admins shouldn't open tickets via this UI (they'd be
+ * opening one as if from a customer, which is confusing). Redirect
+ * them back to the queue. Non-admins of any role can create.
+ */
+export default async function NewTicketPage() {
+  const user = await getSessionUser();
+  if (!user) redirect("/login");
+  if (user.isPlatform) redirect("/support");
+  const t = await getTranslations("support");
+
+  return (
+    <main className="max-w-3xl mx-auto px-6 py-8">
+      <div className="mb-8 animate-in">
+        <BackLink href="/support" label={t("title")} />
+        <h1 className="font-display text-2xl font-semibold accent-rule mb-2">
+          {t("newTicketTitle")}
+        </h1>
+        <p className="text-text-secondary text-sm mt-4">
+          {t("newTicketSubtitle")}
+        </p>
+      </div>
+
+      <div className="animate-in animate-in-delay-1">
+        <TicketCreateForm />
+      </div>
+    </main>
+  );
+}

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

@@ -0,0 +1,97 @@
+import { redirect } from "next/navigation";
+import Link from "next/link";
+import { getTranslations, getFormatter } from "next-intl/server";
+import { getSessionUser } from "@/lib/session";
+import {
+  listSupportTicketsForUser,
+  listAllSupportTickets,
+} from "@/lib/db";
+import { Card } from "@/components/ui/card";
+import { formatRelative } from "@/lib/format";
+import { TicketStatusBadge } from "@/components/support/ticket-status-badge";
+import { TicketCategoryLabel } from "@/components/support/ticket-category-label";
+
+/**
+ * /support — ticket list.
+ *
+ * Customers see their own tickets only (per Feature 5: per-user
+ * scope, NOT per-org). Platform admins see the global queue. Same
+ * UI shell, different list source — the rendering logic is
+ * identical because the per-row data is the same shape.
+ *
+ * Sorting: newest activity first (the DB query already orders by
+ * updated_at DESC). Open tickets bubble to the top by virtue of
+ * having recent activity, but we don't sort by status; that's a
+ * filter the admin can add later if the queue grows.
+ */
+export default async function SupportListPage() {
+  const user = await getSessionUser();
+  if (!user) redirect("/login");
+  const t = await getTranslations("support");
+  const f = await getFormatter();
+
+  const tickets = user.isPlatform
+    ? await listAllSupportTickets()
+    : await listSupportTicketsForUser(user.id);
+
+  return (
+    <main className="max-w-5xl mx-auto px-6 py-8">
+      <div className="mb-8 animate-in flex items-end justify-between">
+        <div>
+          <h1 className="font-display text-2xl font-semibold accent-rule">
+            {user.isPlatform ? t("titleAdmin") : t("title")}
+          </h1>
+          <p className="text-sm text-text-secondary mt-3">
+            {user.isPlatform ? t("subtitleAdmin") : t("subtitle")}
+          </p>
+        </div>
+        {!user.isPlatform && (
+          <Link
+            href="/support/new"
+            className="text-sm font-medium px-4 py-2 rounded-lg bg-accent text-white hover:bg-accent/90 transition-colors"
+          >
+            {t("newTicket")}
+          </Link>
+        )}
+      </div>
+
+      {tickets.length === 0 ? (
+        <Card className="animate-in animate-in-delay-1">
+          <p className="text-sm text-text-secondary text-center py-6">
+            {user.isPlatform ? t("emptyAdmin") : t("empty")}
+          </p>
+        </Card>
+      ) : (
+        <div className="space-y-2 animate-in animate-in-delay-1">
+          {tickets.map((tk) => (
+            <Link
+              key={tk.id}
+              href={`/support/${tk.id}`}
+              className="block rounded-xl border border-border bg-surface-1 p-4 hover:border-text-secondary transition-colors"
+            >
+              <div className="flex items-start justify-between gap-3">
+                <div className="min-w-0">
+                  <div className="font-medium text-text-primary truncate">
+                    {tk.title}
+                  </div>
+                  <div className="text-xs text-text-muted mt-1 flex items-center gap-2">
+                    <TicketCategoryLabel category={tk.category} />
+                    <span>·</span>
+                    <span>{formatRelative(tk.updatedAt, f)}</span>
+                    {user.isPlatform && (
+                      <>
+                        <span>·</span>
+                        <span className="font-mono">{tk.contactEmail}</span>
+                      </>
+                    )}
+                  </div>
+                </div>
+                <TicketStatusBadge status={tk.status} />
+              </div>
+            </Link>
+          ))}
+        </div>
+      )}
+    </main>
+  );
+}

src/app/[locale]/tenants/[name]/page.tsx

@@ -3,7 +3,11 @@ import { getTranslations, getFormatter } from "next-intl/server";
 import { redirect, notFound } from "next/navigation";
 import { getTenant } from "@/lib/k8s";
 import { canUserSeeTenant } from "@/lib/visibility";
-import { getPendingResumeRequestForTenant } from "@/lib/db";
+import {
+  getPendingResumeRequestForTenant,
+  listSkillActivationRequestsForTenant,
+  listSkillPricing,
+} from "@/lib/db";
 import { StatusBadge } from "@/components/ui/status-badge";
 import { WarningBadge } from "@/components/ui/warning-badge";
 import { UsageDisplay } from "@/components/dashboard/usage-display";
@@ -13,8 +17,15 @@ import { ChannelUsers } from "@/components/channel-users/channel-users";
 import { AssignedUsersPanel } from "@/components/tenants/assigned-users-panel";
 import { SubscriptionToggle } from "@/components/tenants/subscription-toggle";
 import { formatDateTime, formatRelative } from "@/lib/format";
+import { CHANNEL_PACKAGE_IDS } from "@/lib/packages";
 
-const CHANNEL_PACKAGES = ["telegram", "discord", "email"];
+// CHANNEL_PACKAGES used to be a hardcoded literal here
+// (`["telegram", "discord", "email"]`). It now derives from the
+// portal-side catalog so adding a new channel anywhere only requires
+// editing src/lib/packages.ts. The `email` channel was dropped as
+// part of the Phase A package-model rework — IMAP/SMTP is now the
+// `mail` skill instead.
+const CHANNEL_PACKAGES = CHANNEL_PACKAGE_IDS;
 
 export default async function TenantDetailPage({
   params,
@@ -75,6 +86,17 @@ export default async function TenantDetailPage({
   );
   const channelUsers = tenant.spec.channelUsers || {};
 
+  // Phase 2.5: surface pending and most-recently-rejected skill
+  // activation requests so PackageCard can render the inline
+  // "Manual review pending" / "Activation rejected" states.
+  // Pricing drives the cost-disclosure dialog before enable.
+  // Both fetches are best-effort — an empty list is the safe
+  // fallback if the DB call fails (cards just show normal toggles).
+  const [activationRequests, skillPricing] = await Promise.all([
+    listSkillActivationRequestsForTenant(name).catch(() => []),
+    listSkillPricing().catch(() => []),
+  ]);
+
   // Bug 19 fix: every viewer (customer or admin) passes the tenant
   // name to UsageDisplay. The /api/usage route resolves team+alias
   // from the tenant CR's status and applies the visibility check, so
@@ -199,7 +221,7 @@ export default async function TenantDetailPage({
         <h2 className="text-xs font-semibold uppercase tracking-wider text-text-muted mb-3">
           {t("usage")}
         </h2>
-        <UsageDisplay tenant={name} />
+        <UsageDisplay tenant={name} canEditBudget={canEdit} />
       </section>
 
       {/* Packages */}
@@ -212,6 +234,8 @@ export default async function TenantDetailPage({
           enabledPackages={enabledPackages}
           conditions={tenant.status?.conditions}
           canEdit={canEdit}
+          activationRequests={activationRequests}
+          skillPricing={skillPricing}
         />
       </section>
 
@@ -272,6 +296,8 @@ export default async function TenantDetailPage({
                 ? {
                     id: pendingResumeRequest.id,
                     createdAt: pendingResumeRequest.createdAt,
+                    customerNotes:
+                      pendingResumeRequest.customerNotes ?? null,
                   }
                 : null
             }

src/app/api/admin/billing/backfill/route.ts

@@ -0,0 +1,70 @@
+import { NextResponse } from "next/server";
+import { requirePlatformRole } from "@/lib/session";
+import { listTenants } from "@/lib/k8s";
+import { backfillTenantBillingLifecycle } from "@/lib/db";
+import { safeError } from "@/lib/errors";
+
+/**
+ * POST /api/admin/billing/backfill
+ *
+ * One-off bootstrap that reads every live PiecedTenant CR and
+ * mirrors it into the Phase 1 billing tables:
+ *   - tenant_billing_lifecycle.created_at ← CR's creationTimestamp
+ *   - tenant_skill_events: one 'enabled' event per package in
+ *     spec.packages, anchored at the CR's creationTimestamp
+ *   - tenant_suspension_events: one 'suspended' event if the CR is
+ *     currently suspended (anchored at status.suspendedAt)
+ *
+ * Idempotent — re-running is safe. The helper only inserts rows
+ * for tenants that have no lifecycle row / no events yet; running
+ * twice produces zero additional rows.
+ *
+ * Authorization: platform role only. The body of the request is
+ * ignored.
+ *
+ * Response: counts of rows inserted, mostly for sanity-checking
+ * (expect non-zero on first run, zero on subsequent runs).
+ *
+ * Phase 2 will surface this behind an admin UI button.
+ */
+export async function POST() {
+  try {
+    await requirePlatformRole();
+  } catch {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+
+  try {
+    const tenants = await listTenants();
+    const result = await backfillTenantBillingLifecycle(
+      tenants.map((t) => ({
+        name: t.metadata.name,
+        // Tenants without the org label exist as a pre-Slice-3
+        // artifact; we still record them but with 'unknown' as the
+        // org id, which surfaces them in admin reports for manual
+        // labelling. Per-org billing computation skips rows with
+        // org id = 'unknown'.
+        zitadelOrgId:
+          t.metadata.labels?.["pieced.ch/zitadel-org-id"] ?? "unknown",
+        createdAt: t.metadata.creationTimestamp
+          ? new Date(t.metadata.creationTimestamp)
+          : new Date(),
+        packages: t.spec.packages ?? [],
+        suspendedAt: t.status?.suspendedAt
+          ? new Date(t.status.suspendedAt)
+          : null,
+      }))
+    );
+    return NextResponse.json({
+      message: "Backfill complete.",
+      tenantsExamined: tenants.length,
+      ...result,
+    });
+  } catch (e: any) {
+    console.error("Backfill failed:", e);
+    return NextResponse.json(
+      { error: safeError(e, "Backfill failed") },
+      { status: 500 }
+    );
+  }
+}

src/app/api/admin/billing/generate/route.ts

@@ -0,0 +1,66 @@
+import { NextResponse } from "next/server";
+import { z } from "zod";
+import { requirePlatformRole } from "@/lib/session";
+import { generateInvoice } from "@/lib/billing";
+import { safeError } from "@/lib/errors";
+
+/**
+ * POST /api/admin/billing/generate
+ *
+ * Compute (and optionally commit) an invoice for an (org, year,
+ * month). Platform-only — this is the testing/admin tool.
+ *
+ * Body:
+ *   {
+ *     zitadelOrgId: string,
+ *     year: number (e.g. 2026),
+ *     month: number (1-12),
+ *     locale?: 'de' | 'en' | 'fr' | 'it',  // default: from country
+ *     dryRun?: boolean                      // default: false
+ *   }
+ *
+ * Response on success:
+ *   {
+ *     draft: InvoiceDraft,           // line breakdown + warnings
+ *     invoice: Invoice | null,       // null when dryRun=true
+ *   }
+ *
+ * If an invoice for that (org, period) already exists, returns
+ * 409 with a clear message. Use the delete endpoint first to
+ * regenerate.
+ */
+
+const bodySchema = z.object({
+  zitadelOrgId: z.string().min(1),
+  year: z.number().int().min(2020).max(2100),
+  month: z.number().int().min(1).max(12),
+  locale: z.enum(["de", "en", "fr", "it"]).optional(),
+  dryRun: z.boolean().optional().default(false),
+});
+
+export async function POST(request: Request) {
+  try {
+    await requirePlatformRole();
+  } catch {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+  const body = await request.json().catch(() => ({}));
+  const parsed = bodySchema.safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: "Invalid request", details: parsed.error.flatten() },
+      { status: 400 }
+    );
+  }
+  try {
+    const result = await generateInvoice(parsed.data);
+    return NextResponse.json(result);
+  } catch (e: any) {
+    console.error("Invoice generation failed:", e);
+    const msg = safeError(e, "Generation failed");
+    // Specific 409 for the "already exists" case so the UI can
+    // show a "delete first" link.
+    const status = /already exists/i.test(msg) ? 409 : 500;
+    return NextResponse.json({ error: msg }, { status });
+  }
+}

src/app/api/admin/billing/invoices/[id]/mark-paid/route.ts

@@ -0,0 +1,81 @@
+import { NextResponse } from "next/server";
+import { z } from "zod";
+import { requirePlatformRole, getSessionUser } from "@/lib/session";
+import { markInvoicePaid } from "@/lib/db";
+import { safeError } from "@/lib/errors";
+
+/**
+ * POST /api/admin/billing/invoices/[id]/mark-paid
+ *
+ * Manually mark an open/overdue invoice as paid. Used for the
+ * "pay by invoice" flow where the customer transfers money to
+ * the bank account printed on the PDF and the admin reconciles
+ * by hand.
+ *
+ * Body (all optional):
+ *   {
+ *     paidAt?: ISO timestamp,        // defaults to now
+ *     note?: string                  // free-form, stored in paid_method_detail
+ *   }
+ *
+ * paid_by is set to the admin user's id automatically.
+ * Idempotent: trying to mark an already-paid invoice returns 409.
+ *
+ * Phase 4 will introduce a parallel auto-paid path triggered by
+ * Stripe webhooks; for Phase 2 this is the only way to flip the
+ * status.
+ */
+
+const bodySchema = z.object({
+  paidAt: z.string().datetime().optional(),
+  note: z.string().max(500).optional(),
+});
+
+export async function POST(
+  request: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  let user;
+  try {
+    await requirePlatformRole();
+    user = await getSessionUser();
+  } catch {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  const { id } = await params;
+  const body = await request.json().catch(() => ({}));
+  const parsed = bodySchema.safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: "Invalid request", details: parsed.error.flatten() },
+      { status: 400 }
+    );
+  }
+  try {
+    const detail = parsed.data.note
+      ? `${user.id}: ${parsed.data.note}`
+      : user.id;
+    const invoice = await markInvoicePaid(id, {
+      paidBy: "manual",
+      paidMethodDetail: detail,
+      paidAt: parsed.data.paidAt ? new Date(parsed.data.paidAt) : undefined,
+    });
+    if (!invoice) {
+      // Either not found or status not in {open, overdue}.
+      return NextResponse.json(
+        { error: "Invoice not found, or already paid/void." },
+        { status: 409 }
+      );
+    }
+    return NextResponse.json(invoice);
+  } catch (e) {
+    console.error("Failed to mark invoice paid:", e);
+    return NextResponse.json(
+      { error: safeError(e, "Mark-paid failed") },
+      { status: 500 }
+    );
+  }
+}

src/app/api/admin/billing/invoices/[id]/pdf/route.ts

@@ -0,0 +1,48 @@
+import { NextResponse } from "next/server";
+import { requirePlatformRole } from "@/lib/session";
+import { getInvoicePdf } from "@/lib/db";
+
+/**
+ * GET /api/admin/billing/invoices/[id]/pdf
+ *
+ * Streams the stored PDF bytes for an invoice. The bytea column is
+ * read once and returned as an octet stream; no on-the-fly
+ * re-rendering — PDFs are immutable once issued.
+ *
+ * Phase 3 will add a parallel customer-facing route at
+ * /api/billing/invoices/[id]/pdf with org-scoped authorization.
+ */
+export async function GET(
+  _request: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  try {
+    await requirePlatformRole();
+  } catch {
+    return new NextResponse("Forbidden", { status: 403 });
+  }
+  const { id } = await params;
+  const pdf = await getInvoicePdf(id);
+  if (!pdf) {
+    return new NextResponse("Not found", { status: 404 });
+  }
+  // Web `Response`'s BodyInit accepts BufferSource, which IS satisfied
+  // by a Uint8Array. But the pg-returned Buffer types as
+  // `Uint8Array<ArrayBufferLike>` (the @types/node 22+ generic form),
+  // and lib.dom's BufferSource only accepts `Uint8Array<ArrayBuffer>` —
+  // the narrower concrete form. The variance kills assignability,
+  // even though Buffer extends Uint8Array at runtime.
+  //
+  // `Uint8Array.from(buf)` allocates a fresh typed array; the result
+  // is `Uint8Array<ArrayBuffer>` (concrete generic), which BodyInit
+  // accepts. Copy cost is trivial at PDF sizes.
+  const body = Uint8Array.from(pdf.data);
+  return new NextResponse(body, {
+    status: 200,
+    headers: {
+      "Content-Type": "application/pdf",
+      "Content-Disposition": `inline; filename="${pdf.filename}"`,
+      "Cache-Control": "private, max-age=0, must-revalidate",
+    },
+  });
+}

src/app/api/admin/billing/invoices/[id]/route.ts

@@ -0,0 +1,55 @@
+import { NextResponse } from "next/server";
+import { requirePlatformRole } from "@/lib/session";
+import { deleteInvoice, getInvoiceDetail } from "@/lib/db";
+import { safeError } from "@/lib/errors";
+
+/**
+ * GET /api/admin/billing/invoices/[id]
+ * Detail view: invoice + lines.
+ *
+ * DELETE /api/admin/billing/invoices/[id]
+ * Hard delete (testing tool). Invoice number is consumed — gaps
+ * in the sequence are intentional and documented. Reminders
+ * (and their PDFs) cascade-delete via the FK.
+ */
+export async function GET(
+  _request: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  try {
+    await requirePlatformRole();
+  } catch {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+  const { id } = await params;
+  const detail = await getInvoiceDetail(id);
+  if (!detail) {
+    return NextResponse.json({ error: "Not found" }, { status: 404 });
+  }
+  return NextResponse.json(detail);
+}
+
+export async function DELETE(
+  _request: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  try {
+    await requirePlatformRole();
+  } catch {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+  const { id } = await params;
+  try {
+    const ok = await deleteInvoice(id);
+    if (!ok) {
+      return NextResponse.json({ error: "Not found" }, { status: 404 });
+    }
+    return NextResponse.json({ message: "Deleted." });
+  } catch (e) {
+    console.error("Failed to delete invoice:", e);
+    return NextResponse.json(
+      { error: safeError(e, "Delete failed") },
+      { status: 500 }
+    );
+  }
+}

src/app/api/admin/billing/invoices/route.ts

@@ -0,0 +1,44 @@
+import { NextResponse } from "next/server";
+import { requirePlatformRole } from "@/lib/session";
+import { listInvoices, syncOverdueInvoices } from "@/lib/db";
+import type { InvoiceStatus } from "@/types";
+
+/**
+ * GET /api/admin/billing/invoices
+ *
+ * List invoices for admin. Optional filters:
+ *   ?status=open|paid|overdue|void|uncollectible
+ *   ?orgId=...
+ *   ?month=YYYY-MM
+ *   ?limit=200
+ *
+ * Refreshes overdue status on each call (cheap UPDATE), so the
+ * admin list always reflects the latest due-date math without
+ * needing a cron.
+ */
+export async function GET(request: Request) {
+  try {
+    await requirePlatformRole();
+  } catch {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+
+  await syncOverdueInvoices().catch((e) =>
+    console.error("syncOverdueInvoices failed:", e)
+  );
+
+  const { searchParams } = new URL(request.url);
+  const status = searchParams.get("status") as InvoiceStatus | null;
+  const orgId = searchParams.get("orgId");
+  const month = searchParams.get("month");
+  const limitParam = searchParams.get("limit");
+  const limit = limitParam ? Math.max(1, Math.min(1000, parseInt(limitParam, 10))) : 200;
+
+  const invoices = await listInvoices({
+    status: status ?? undefined,
+    zitadelOrgId: orgId ?? undefined,
+    periodMonth: month ?? undefined,
+    limit,
+  });
+  return NextResponse.json(invoices);
+}

src/app/api/admin/billing/orgs/route.ts

@@ -0,0 +1,80 @@
+import { NextResponse } from "next/server";
+import { requirePlatformRole } from "@/lib/session";
+import { listTenants } from "@/lib/k8s";
+import { getOrgBilling, getOrgOpenBalances } from "@/lib/db";
+
+/**
+ * GET /api/admin/billing/orgs
+ *
+ * Returns the orgs known to the platform via tenant labels, with
+ * their billing-address-on-file status and open balance summary.
+ * Powers the generate form's org dropdown and the billing landing
+ * page's open-balance table.
+ *
+ * Each entry:
+ *   {
+ *     zitadelOrgId: string,
+ *     tenantCount: number,
+ *     hasBillingAddress: boolean,
+ *     companyName: string | null,
+ *     openCount: number,
+ *     overdueCount: number,
+ *     totalOpenChf: number
+ *   }
+ */
+export async function GET() {
+  try {
+    await requirePlatformRole();
+  } catch {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+
+  // Org membership is derived from tenant labels — there's no
+  // separate "orgs" table on the portal. listTenants reads from
+  // K8s, which is the source of truth.
+  const tenants = await listTenants();
+  const orgIdToTenants = new Map<string, string[]>();
+  for (const t of tenants) {
+    const oid = t.metadata.labels?.["pieced.ch/zitadel-org-id"];
+    if (!oid) continue;
+    if (!orgIdToTenants.has(oid)) orgIdToTenants.set(oid, []);
+    orgIdToTenants.get(oid)!.push(t.metadata.name);
+  }
+
+  const balances = await getOrgOpenBalances();
+  const balanceMap = new Map(balances.map((b) => [b.zitadelOrgId, b]));
+
+  // Hydrate billing-address presence + company name per org.
+  const results = await Promise.all(
+    [...orgIdToTenants.entries()].map(async ([orgId, tenantNames]) => {
+      const billing = await getOrgBilling(orgId).catch(() => null);
+      const bal = balanceMap.get(orgId);
+      return {
+        zitadelOrgId: orgId,
+        tenantCount: tenantNames.length,
+        tenantNames,
+        hasBillingAddress: !!billing,
+        companyName: billing?.companyName ?? null,
+        country: billing?.country ?? null,
+        openCount: bal?.openCount ?? 0,
+        overdueCount: bal?.overdueCount ?? 0,
+        totalOpenChf: bal?.totalOpenChf ?? 0,
+      };
+    })
+  );
+
+  // Sort: orgs with overdue first, then open, then by name.
+  results.sort((a, b) => {
+    if (a.overdueCount !== b.overdueCount) {
+      return b.overdueCount - a.overdueCount;
+    }
+    if (a.openCount !== b.openCount) {
+      return b.openCount - a.openCount;
+    }
+    return (a.companyName ?? a.zitadelOrgId).localeCompare(
+      b.companyName ?? b.zitadelOrgId
+    );
+  });
+
+  return NextResponse.json(results);
+}

src/app/api/admin/billing/pricing/route.ts

@@ -0,0 +1,59 @@
+import { NextResponse } from "next/server";
+import { z } from "zod";
+import { requirePlatformRole } from "@/lib/session";
+import { getPlatformPricing, updatePlatformPricing } from "@/lib/db";
+import { safeError } from "@/lib/errors";
+
+/**
+ * GET /api/admin/billing/pricing
+ * Returns the single-row platform pricing config.
+ *
+ * PUT /api/admin/billing/pricing
+ * Updates one or more pricing fields. Missing fields are left
+ * unchanged.
+ *
+ * Both endpoints are platform-role only.
+ */
+
+const updateSchema = z.object({
+  tenantMonthlyFeeChf: z.number().min(0).max(99_999_999).optional(),
+  tenantSetupFeeChf: z.number().min(0).max(99_999_999).optional(),
+  threemaMessageChf: z.number().min(0).max(1000).optional(),
+  vatRateChli: z.number().min(0).max(100).optional(),
+});
+
+export async function GET() {
+  try {
+    await requirePlatformRole();
+  } catch {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+  const pricing = await getPlatformPricing();
+  return NextResponse.json(pricing);
+}
+
+export async function PUT(request: Request) {
+  try {
+    await requirePlatformRole();
+  } catch {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+  const body = await request.json().catch(() => ({}));
+  const parsed = updateSchema.safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: "Invalid pricing payload", details: parsed.error.flatten() },
+      { status: 400 }
+    );
+  }
+  try {
+    const updated = await updatePlatformPricing(parsed.data);
+    return NextResponse.json(updated);
+  } catch (e) {
+    console.error("Failed to update platform pricing:", e);
+    return NextResponse.json(
+      { error: safeError(e, "Update failed") },
+      { status: 500 }
+    );
+  }
+}

src/app/api/admin/billing/skill-pricing/[skill]/route.ts

@@ -0,0 +1,33 @@
+import { NextResponse } from "next/server";
+import { requirePlatformRole } from "@/lib/session";
+import { removeSkillPricing } from "@/lib/db";
+import { safeError } from "@/lib/errors";
+
+/**
+ * DELETE /api/admin/billing/skill-pricing/[skill]
+ * Remove pricing for a skill. Toggle events continue to be
+ * recorded; the skill simply becomes free starting from the next
+ * generated invoice. Historical invoices already issued are
+ * unaffected (they carry frozen line amounts).
+ */
+export async function DELETE(
+  _request: Request,
+  { params }: { params: Promise<{ skill: string }> }
+) {
+  try {
+    await requirePlatformRole();
+  } catch {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+  const { skill } = await params;
+  try {
+    await removeSkillPricing(skill);
+    return NextResponse.json({ message: "Removed." });
+  } catch (e) {
+    console.error("Failed to remove skill pricing:", e);
+    return NextResponse.json(
+      { error: safeError(e, "Remove failed") },
+      { status: 500 }
+    );
+  }
+}

src/app/api/admin/billing/skill-pricing/route.ts

@@ -0,0 +1,80 @@
+import { NextResponse } from "next/server";
+import { z } from "zod";
+import { requirePlatformRole } from "@/lib/session";
+import { listSkillPricing, setSkillPricing } from "@/lib/db";
+import { getPackageDef } from "@/lib/packages";
+import { safeError } from "@/lib/errors";
+
+/**
+ * GET /api/admin/billing/skill-pricing
+ *   List all configured skill prices.
+ *
+ * PUT /api/admin/billing/skill-pricing
+ *   Upsert a daily price for a single skill. Body:
+ *     { skillId: string, dailyPriceChf: number }
+ *
+ * Both endpoints are platform-only.
+ *
+ * Note on skillId validation: we accept any package id that exists
+ * in PACKAGE_CATALOG. The PIN to "skills only" is enforced at the
+ * UI layer, not here, so admins can price a non-skill package in
+ * an emergency without code changes.
+ */
+
+const upsertSchema = z.object({
+  skillId: z.string().min(1).max(100),
+  dailyPriceChf: z.number().min(0).max(1_000_000),
+  // Optional with default 0 so existing API callers keep working.
+  // Setup fee fires once per (tenant, skill); see billing.ts.
+  setupFeeChf: z.number().min(0).max(1_000_000).optional().default(0),
+});
+
+export async function GET() {
+  try {
+    await requirePlatformRole();
+  } catch {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+  const rows = await listSkillPricing();
+  return NextResponse.json(rows);
+}
+
+export async function PUT(request: Request) {
+  try {
+    await requirePlatformRole();
+  } catch {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+  const body = await request.json().catch(() => ({}));
+  const parsed = upsertSchema.safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: "Invalid payload", details: parsed.error.flatten() },
+      { status: 400 }
+    );
+  }
+  // Validate the skill id exists in PACKAGE_CATALOG. Returns null
+  // for unknown ids; we reject those rather than persist a row that
+  // would never match a real toggle event.
+  const pkg = getPackageDef(parsed.data.skillId);
+  if (!pkg) {
+    return NextResponse.json(
+      { error: `Unknown package id: ${parsed.data.skillId}` },
+      { status: 400 }
+    );
+  }
+  try {
+    const row = await setSkillPricing(
+      parsed.data.skillId,
+      parsed.data.dailyPriceChf,
+      parsed.data.setupFeeChf
+    );
+    return NextResponse.json(row);
+  } catch (e) {
+    console.error("Failed to upsert skill pricing:", e);
+    return NextResponse.json(
+      { error: safeError(e, "Upsert failed") },
+      { status: 500 }
+    );
+  }
+}

src/app/api/admin/openclaw/route.ts

@@ -0,0 +1,75 @@
+import { NextRequest, NextResponse } from "next/server";
+import { z } from "zod";
+import { getSessionUser } from "@/lib/session";
+import { getOpenClawDefaults, setOpenClawDefaults } from "@/lib/k8s";
+import { safeError } from "@/lib/errors";
+
+/**
+ * Platform-wide default OpenClaw image tag (admin-only).
+ *
+ * GET — read the current default tag from the
+ * `pieced-openclaw-config` ConfigMap. Can be empty string if no
+ * default is configured; the operator uses its built-in fallback
+ * in that case.
+ *
+ * PATCH — update the tag. Send "" to clear. The operator watches
+ * this ConfigMap and re-enqueues all tenants without a per-tenant
+ * override on change, so existing tenants roll forward to the new
+ * default automatically. Tenants WITH an override are unaffected.
+ *
+ * Tag-only by design — see operator notes.
+ */
+
+const patchSchema = z.object({
+  defaultTag: z.string().trim().max(256),
+});
+
+export async function GET() {
+  const user = await getSessionUser();
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  if (!user.isPlatform) {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+  try {
+    return NextResponse.json(await getOpenClawDefaults());
+  } catch (e: any) {
+    console.error("Failed to read openclaw defaults:", e);
+    return NextResponse.json(
+      { error: safeError(e, "Failed to read defaults") },
+      { status: 500 }
+    );
+  }
+}
+
+export async function PATCH(req: NextRequest) {
+  const user = await getSessionUser();
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  if (!user.isPlatform) {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+  const body = await req.json().catch(() => null);
+  const parsed = patchSchema.safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: "Invalid input", details: parsed.error.flatten() },
+      { status: 400 }
+    );
+  }
+
+  try {
+    const next = await setOpenClawDefaults({
+      defaultTag: parsed.data.defaultTag,
+    });
+    return NextResponse.json(next);
+  } catch (e: any) {
+    console.error("Failed to update openclaw defaults:", e);
+    return NextResponse.json(
+      { error: safeError(e, "Failed to update defaults") },
+      { status: 500 }
+    );
+  }
+}

src/app/api/admin/requests/[id]/approve/route.ts

@@ -4,6 +4,9 @@ import {
   getTenantRequestById,
   updateTenantRequestStatus,
   clearEncryptedSecrets,
+  recordTenantCreated,
+  recordSkillEvents,
+  recordSuspensionEvent,
 } from "@/lib/db";
 import { createTenant, patchTenantSpec, setTenantAnnotation } from "@/lib/k8s";
 import { sendApprovalEmail, sendResumeApprovalEmail } from "@/lib/email";
@@ -85,6 +88,23 @@ export async function POST(
     }
     try {
       await patchTenantSpec(tenantRequest.tenantName, { suspend: false });
+
+      // Billing — Phase 1: record the resume so monthly proration
+      // counts the suspended segment correctly. Best-effort; if
+      // logging fails, the approval still succeeds.
+      try {
+        await recordSuspensionEvent(
+          tenantRequest.tenantName,
+          tenantRequest.zitadelOrgId,
+          "resumed"
+        );
+      } catch (e) {
+        console.error(
+          "billing: failed to record resumed suspension event:",
+          e
+        );
+      }
+
       // Clear the annotation that pauses the operator's 60-day TTL.
       // Best-effort — annotation cleanup is also done by the operator
       // when it sees suspend=false on the next reconcile (it clears
@@ -199,6 +219,35 @@ export async function POST(
       }
     );
 
+    // Billing — Phase 1: record the tenant's creation and initial
+    // package state. Anchored at "now" rather than the CR's
+    // creationTimestamp because we don't get the timestamp back from
+    // createTenant — the few-millisecond skew vs the CR's actual
+    // creationTimestamp is irrelevant for monthly billing.
+    //
+    // Best-effort: tracking failures must never block provisioning.
+    // The backfill helper can repair any gaps later if needed.
+    const billingAnchor = new Date();
+    try {
+      await recordTenantCreated(
+        tenantName,
+        tenantRequest.zitadelOrgId,
+        billingAnchor
+      );
+      await recordSkillEvents(
+        tenantName,
+        tenantRequest.zitadelOrgId,
+        packages,
+        [],
+        billingAnchor
+      );
+    } catch (e) {
+      console.error(
+        "billing: failed to record tenant creation / initial skill events:",
+        e
+      );
+    }
+
     // Step 5: Update request status — clear admin notes on re-approval
     const updated = await updateTenantRequestStatus(id, "provisioning", {
       adminNotes: isReApproval ? null : adminNotes,

src/app/api/admin/skills/pending/[id]/approve/route.ts

@@ -0,0 +1,155 @@
+import { NextResponse } from "next/server";
+import { getSessionUser, requirePlatformRole } from "@/lib/session";
+import {
+  getSkillActivationRequestById,
+  recordSkillEvents,
+  updateSkillActivationRequestStatus,
+} from "@/lib/db";
+import { getTenant, patchTenantSpec } from "@/lib/k8s";
+import { getPackageDef } from "@/lib/packages";
+import { listOrgUsers } from "@/lib/zitadel";
+import { sendSkillActivationApprovalEmail } from "@/lib/email";
+import { safeError } from "@/lib/errors";
+
+/**
+ * POST /api/admin/skills/pending/[id]/approve
+ *
+ * Atomic-ish approval. Ordering:
+ *   1. Load + sanity-check the request (must be pending).
+ *   2. Patch the tenant CR to include the skill in spec.packages.
+ *   3. Record the skill_event (kind=enabled) for billing.
+ *   4. Flip the request row to 'approved'.
+ *   5. Best-effort approval email to the requester.
+ *
+ * Step 2 is the irreversible one — if it succeeds but step 4 fails
+ * we end up with a skill enabled in K8s but a still-pending request
+ * row. That's a manual cleanup task; we log loudly so admin notices
+ * via the queue page (the request would reappear there).
+ *
+ * The request must be in 'pending' status. Approving an already-
+ * approved/rejected request returns 409.
+ *
+ * Body (optional): { adminNotes?: string }
+ */
+export async function POST(
+  request: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  let admin;
+  try {
+    await requirePlatformRole();
+    admin = await getSessionUser();
+  } catch {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+  if (!admin) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  const { id } = await params;
+  const body = await request.json().catch(() => ({}));
+  const adminNotes =
+    typeof body.adminNotes === "string" && body.adminNotes.length <= 1000
+      ? body.adminNotes
+      : null;
+
+  // 1. Load + sanity-check.
+  const req = await getSkillActivationRequestById(id);
+  if (!req) {
+    return NextResponse.json({ error: "Request not found" }, { status: 404 });
+  }
+  if (req.status !== "pending") {
+    return NextResponse.json(
+      { error: `Request is already ${req.status}` },
+      { status: 409 }
+    );
+  }
+
+  // 2. Patch the tenant CR — add the skill if not already present.
+  // Defensive: if the tenant was deleted or the skill was somehow
+  // added by another path, we still proceed without duplicate.
+  let tenant;
+  try {
+    tenant = await getTenant(req.tenantName);
+  } catch (e) {
+    return NextResponse.json(
+      { error: `Tenant ${req.tenantName} not found: ${safeError(e, "")}` },
+      { status: 404 }
+    );
+  }
+  if (!tenant) {
+    return NextResponse.json(
+      { error: `Tenant ${req.tenantName} not found` },
+      { status: 404 }
+    );
+  }
+
+  const currentPackages = new Set<string>(tenant.spec.packages ?? []);
+  const alreadyEnabled = currentPackages.has(req.skillId);
+  if (!alreadyEnabled) {
+    currentPackages.add(req.skillId);
+    try {
+      await patchTenantSpec(req.tenantName, {
+        packages: [...currentPackages],
+      });
+    } catch (e) {
+      return NextResponse.json(
+        { error: `Failed to enable skill on tenant: ${safeError(e, "")}` },
+        { status: 500 }
+      );
+    }
+  }
+
+  // 3. Record skill event (only if we actually added it — re-adding
+  //    would skew the day-count). Best-effort.
+  if (!alreadyEnabled) {
+    try {
+      await recordSkillEvents(req.tenantName, req.zitadelOrgId, [req.skillId], []);
+    } catch (e) {
+      console.error(
+        `Failed to record skill_event after approve (request ${id}):`,
+        e
+      );
+    }
+  }
+
+  // 4. Flip request to approved.
+  const updated = await updateSkillActivationRequestStatus(id, "approved", {
+    reviewedBy: admin.id,
+    adminNotes,
+  });
+  if (!updated) {
+    // Race: another admin tab flipped it between our read and now.
+    // The K8s patch already happened so we don't roll back; log so
+    // the human notices.
+    console.error(
+      `Request ${id} was no longer pending when we tried to mark approved; K8s patch already applied.`
+    );
+    return NextResponse.json(
+      {
+        error:
+          "Request status changed during approval; the skill may have been enabled. Check the queue.",
+      },
+      { status: 409 }
+    );
+  }
+
+  // 5. Email the requester (best-effort). Look up their email via
+  //    ZITADEL since we only stored the userId on the request.
+  try {
+    const orgUsers = await listOrgUsers(req.zitadelOrgId);
+    const requester = orgUsers.find((u) => u.userId === req.zitadelUserId);
+    if (requester?.email) {
+      const def = getPackageDef(req.skillId);
+      await sendSkillActivationApprovalEmail({
+        to: requester.email,
+        contactName: requester.displayName || requester.email,
+        skillName: def?.name ?? req.skillId,
+        tenantName: req.tenantName,
+      });
+    }
+  } catch (e) {
+    console.error(`Failed to send approval email for request ${id}:`, e);
+  }
+
+  return NextResponse.json(updated);
+}

src/app/api/admin/skills/pending/[id]/reject/route.ts

@@ -0,0 +1,129 @@
+import { NextResponse } from "next/server";
+import { z } from "zod";
+import { getSessionUser, requirePlatformRole } from "@/lib/session";
+import {
+  getSkillActivationRequestById,
+  updateSkillActivationRequestStatus,
+} from "@/lib/db";
+import { getPackageDef } from "@/lib/packages";
+import { listOrgUsers } from "@/lib/zitadel";
+import { sendSkillActivationRejectionEmail } from "@/lib/email";
+import { deletePackageSecrets } from "@/lib/openbao";
+
+/**
+ * POST /api/admin/skills/pending/[id]/reject
+ *
+ * Reject a pending activation request with a required reason that
+ * is shown to the customer (mirroring the tenant-request rejection
+ * flow). The skill is NOT added to the tenant spec — it was never
+ * there in the first place — so the customer's enable attempt is
+ * effectively cancelled. They can try again from their tenant
+ * settings after seeing the reason (a new pending row will be
+ * created by their next toggle).
+ *
+ * Body:
+ *   {
+ *     reason: string (1..1000 chars, required),
+ *     adminNotes?: string (optional, not shown to customer)
+ *   }
+ */
+
+const bodySchema = z.object({
+  reason: z.string().min(1).max(1000),
+  adminNotes: z.string().max(1000).optional(),
+});
+
+export async function POST(
+  request: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  let admin;
+  try {
+    await requirePlatformRole();
+    admin = await getSessionUser();
+  } catch {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+  if (!admin) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  const { id } = await params;
+  const body = await request.json().catch(() => ({}));
+  const parsed = bodySchema.safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: "Invalid request", details: parsed.error.flatten() },
+      { status: 400 }
+    );
+  }
+
+  const req = await getSkillActivationRequestById(id);
+  if (!req) {
+    return NextResponse.json({ error: "Request not found" }, { status: 404 });
+  }
+  if (req.status !== "pending") {
+    return NextResponse.json(
+      { error: `Request is already ${req.status}` },
+      { status: 409 }
+    );
+  }
+
+  const updated = await updateSkillActivationRequestStatus(id, "rejected", {
+    reviewedBy: admin.id,
+    rejectionReason: parsed.data.reason,
+    adminNotes: parsed.data.adminNotes ?? null,
+  });
+  if (!updated) {
+    return NextResponse.json(
+      { error: "Request status changed during rejection." },
+      { status: 409 }
+    );
+  }
+
+  // Cleanup: if the package needed customer-provided secrets, the
+  // user submitted them BEFORE the gate fired (handleSubmitSecrets
+  // in PackageCard writes to OpenBao then PATCHes). Those secrets
+  // are now orphaned — the package never made it into spec, won't
+  // be re-attempted unless the user retries with fresh credentials.
+  // Best-effort delete: keep the OpenBao path clean, avoid stale
+  // creds lurking. Idempotent (404 is fine). Failure is logged but
+  // not propagated — the rejection itself already succeeded.
+  //
+  // We deliberately skip customProvisioning packages here. Those
+  // mint platform-side credentials via a dedicated endpoint and
+  // need symmetric deprovisioning (POST /[pkg.id] → DELETE
+  // /[pkg.id]). Calling deletePackageSecrets wouldn't revoke them
+  // — admin handles that path manually if the rejected request had
+  // already minted resources.
+  const def = getPackageDef(req.skillId);
+  if (def?.requiresSecrets && !def.customProvisioning) {
+    try {
+      await deletePackageSecrets(req.tenantName, req.skillId);
+    } catch (e) {
+      console.error(
+        `Failed to delete orphan secrets for ${req.tenantName}/${req.skillId} after reject:`,
+        e
+      );
+    }
+  }
+
+  // Email the requester with the reason — best-effort.
+  try {
+    const orgUsers = await listOrgUsers(req.zitadelOrgId);
+    const requester = orgUsers.find((u) => u.userId === req.zitadelUserId);
+    if (requester?.email) {
+      const def = getPackageDef(req.skillId);
+      await sendSkillActivationRejectionEmail({
+        to: requester.email,
+        contactName: requester.displayName || requester.email,
+        skillName: def?.name ?? req.skillId,
+        tenantName: req.tenantName,
+        reason: parsed.data.reason,
+      });
+    }
+  } catch (e) {
+    console.error(`Failed to send rejection email for request ${id}:`, e);
+  }
+
+  return NextResponse.json(updated);
+}

src/app/api/admin/skills/pending/route.ts

@@ -0,0 +1,22 @@
+import { NextResponse } from "next/server";
+import { requirePlatformRole } from "@/lib/session";
+import { listPendingSkillActivationRequests } from "@/lib/db";
+
+/**
+ * GET /api/admin/skills/pending
+ *
+ * List all pending skill-activation requests across all tenants
+ * and orgs. Powers the admin queue at /admin/skills/pending.
+ *
+ * Platform-role only. Returns up to 500 rows oldest-first so the
+ * queue UI shows the oldest requests at the top (FIFO).
+ */
+export async function GET() {
+  try {
+    await requirePlatformRole();
+  } catch {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+  const rows = await listPendingSkillActivationRequests();
+  return NextResponse.json(rows);
+}

src/app/api/admin/tenants/[name]/delete/route.ts

@@ -4,6 +4,7 @@ import { getTenant, deleteTenant } from "@/lib/k8s";
 import {
   markTenantRequestDeletedByTenantName,
   removeAllAssignmentsForTenant,
+  recordTenantDeleted,
 } from "@/lib/db";
 import { safeError } from "@/lib/errors";
 
@@ -49,6 +50,15 @@ export async function POST(
       console.error("Failed to clean up tenant assignments:", e)
     );
 
+    // Billing — Phase 1: stamp deletion timestamp on the lifecycle
+    // row so the final invoice covering the deletion month can
+    // prorate correctly. Idempotent at the DB layer; a missing
+    // lifecycle row (e.g. pre-Phase-1 tenants that haven't been
+    // backfilled yet) makes this a no-op.
+    await recordTenantDeleted(name).catch((e) =>
+      console.error("billing: failed to stamp tenant deletion:", e)
+    );
+
     return NextResponse.json({
       message: "Tenant deletion initiated. The operator will clean up all resources.",
     });

src/app/api/admin/tenants/[name]/openclaw-image/route.ts

@@ -0,0 +1,78 @@
+import { NextRequest, NextResponse } from "next/server";
+import { z } from "zod";
+import { getSessionUser } from "@/lib/session";
+import { getTenant, patchTenantSpec } from "@/lib/k8s";
+import { safeError } from "@/lib/errors";
+
+/**
+ * Per-tenant OpenClaw image override (admin-only).
+ *
+ * Why admin-only: customers cannot pick OpenClaw versions. This
+ * exists so the platform team can A/B-test new releases on specific
+ * tenants without rolling them out fleet-wide. The endpoint enforces
+ * `user.isPlatform`; even owners of the tenant's org cannot use it.
+ *
+ * PATCH body shapes:
+ *   - { tag: "2026.4.22" } → use this tag
+ *   - { tag: "" } or empty body → clear override (revert to platform
+ *     default)
+ *
+ * Tag-only by design — see operator notes for rationale.
+ */
+
+const patchSchema = z.object({
+  tag: z.string().trim().max(256).optional(),
+});
+
+export async function PATCH(
+  req: NextRequest,
+  { params }: { params: Promise<{ name: string }> }
+) {
+  const user = await getSessionUser();
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  if (!user.isPlatform) {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+
+  const { name } = await params;
+  const tenant = await getTenant(name);
+  if (!tenant) {
+    return NextResponse.json({ error: "Not found" }, { status: 404 });
+  }
+
+  const body = await req.json().catch(() => null);
+  const parsed = patchSchema.safeParse(body ?? {});
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: "Invalid input", details: parsed.error.flatten() },
+      { status: 400 }
+    );
+  }
+
+  const tag = parsed.data.tag ?? "";
+  const isClearing = tag === "";
+
+  // Merge-patch semantics: openClawImage: null removes the field
+  // from the spec; openClawImage: { tag } sets it.
+  const spec: any = isClearing
+    ? { openClawImage: null }
+    : { openClawImage: { tag } };
+
+  try {
+    const updated = await patchTenantSpec(name, spec);
+    return NextResponse.json({
+      message: isClearing
+        ? "Override cleared; tenant follows platform default."
+        : "Override set.",
+      openClawImage: updated.spec.openClawImage ?? null,
+    });
+  } catch (e: any) {
+    console.error("Failed to set tenant openclaw image:", e);
+    return NextResponse.json(
+      { error: safeError(e, "Failed to update tenant image") },
+      { status: 500 }
+    );
+  }
+}

src/app/api/admin/tenants/[name]/suspend/route.ts

@@ -1,6 +1,7 @@
 import { NextResponse } from "next/server";
 import { requirePlatformRole } from "@/lib/session";
 import { getTenant, patchTenantSpec } from "@/lib/k8s";
+import { recordSuspensionEvent } from "@/lib/db";
 import { safeError } from "@/lib/errors";
 
 /**
@@ -29,6 +30,32 @@ export async function POST(
 
   try {
     const updated = await patchTenantSpec(name, { suspend });
+
+    // Billing — Phase 1: record the transition. Mirrors the same
+    // hook in the customer-side suspend route so admin actions
+    // also produce events. Best-effort; logging failures don't
+    // block the response.
+    try {
+      const orgId =
+        tenant.metadata.labels?.["pieced.ch/zitadel-org-id"] ?? null;
+      if (orgId) {
+        await recordSuspensionEvent(
+          name,
+          orgId,
+          suspend ? "suspended" : "resumed"
+        );
+      } else {
+        console.warn(
+          `billing: tenant ${name} has no zitadel-org-id label; suspension event not recorded`
+        );
+      }
+    } catch (e) {
+      console.error(
+        `billing: failed to record suspension event for ${name}:`,
+        e
+      );
+    }
+
     return NextResponse.json({
       message: suspend ? "Tenant suspended." : "Tenant resumed.",
       tenant: updated,

src/app/api/billing/current/route.ts

@@ -0,0 +1,75 @@
+import { NextResponse } from "next/server";
+import { getSessionUser } from "@/lib/session";
+import { computeInvoiceDraft } from "@/lib/billing";
+import { listInvoices } from "@/lib/db";
+
+/**
+ * GET /api/billing/current
+ *
+ * Running total for the current calendar month — what the
+ * customer will be billed if no further activity happens. Uses
+ * the same compute pipeline as the final invoice (LiteLLM spend,
+ * Threema usage, skill day-counting, proration) so the number
+ * the customer sees matches what they'll eventually receive
+ * within the limits of intra-month drift.
+ *
+ * If an invoice has ALREADY been issued for the current month
+ * (e.g. cron ran early, admin manually generated), we return
+ * that issued invoice instead — no point showing a draft that
+ * duplicates a real invoice.
+ *
+ * Returns:
+ *   { issued: Invoice }           // current-month invoice exists
+ *   { draft: InvoiceDraft }       // still accruing
+ *   { error: ... }                // org missing billing config
+ *
+ * Cost: 1 LiteLLM HTTP call + 1 Threema HTTP call + a handful of
+ * DB queries per skill. Sub-second typically. No caching; called
+ * on demand from the customer billing page.
+ */
+export async function GET() {
+  const user = await getSessionUser();
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  // Resolve current calendar month from UTC. Billing is UTC-day
+  // based throughout (see billing.ts iterDays comment), so the
+  // running total inherits that same semantics.
+  const now = new Date();
+  const year = now.getUTCFullYear();
+  const month = now.getUTCMonth() + 1; // 1-12
+  const periodMonth = `${year}-${String(month).padStart(2, "0")}`;
+
+  // 1. Has the current month already been invoiced?
+  const existing = await listInvoices({
+    zitadelOrgId: user.orgId,
+    periodMonth,
+    limit: 1,
+  });
+  if (existing.length > 0) {
+    return NextResponse.json({ issued: existing[0] });
+  }
+
+  // 2. Otherwise compute the draft. Falls through to error if the
+  //    org doesn't have a billing config yet (no Address on file).
+  try {
+    const draft = await computeInvoiceDraft({
+      zitadelOrgId: user.orgId,
+      year,
+      month,
+    });
+    return NextResponse.json({ draft });
+  } catch (e: any) {
+    // Most likely: org_billing row missing. We surface a 200 with a
+    // soft error code rather than 500 — the customer-side widget
+    // displays a helpful "complete your billing details" message
+    // instead of a stack trace.
+    return NextResponse.json(
+      {
+        error: e?.message ?? "Could not compute running total.",
+        code: e?.code ?? "COMPUTE_FAILED",
+      },
+      { status: 200 }
+    );
+  }
+}

src/app/api/billing/invoices/[invoiceNumber]/pay/route.ts

@@ -0,0 +1,105 @@
+import { NextResponse } from "next/server";
+import { getSessionUser } from "@/lib/session";
+import {
+  getInvoiceByNumberForOrg,
+  getOrgBilling,
+} from "@/lib/db";
+import {
+  createCheckoutSessionForInvoice,
+  ensureStripeCustomerForOrg,
+} from "@/lib/stripe";
+import { safeError } from "@/lib/errors";
+
+/**
+ * POST /api/billing/invoices/[invoiceNumber]/pay
+ *
+ * Initiates a Stripe Checkout Session for an open invoice. Returns
+ * `{ url }` — the browser is expected to navigate to that URL,
+ * where Stripe hosts the payment UI.
+ *
+ * Authorization: caller must belong to the invoice's org (the DB
+ * query enforces this — wrong-org returns 404, indistinguishable
+ * from a non-existent invoice).
+ *
+ * Preconditions enforced server-side:
+ *   - Invoice exists for caller's org
+ *   - Invoice status is 'open' or 'overdue' (paid/void/draft/uncollectible
+ *     all reject — already-paid invoices in particular must not
+ *     create a second Checkout Session, even though Stripe would
+ *     deduplicate the actual charge)
+ *
+ * The Stripe Customer for the org is lazily ensured here — first
+ * card click on an org creates the customer; subsequent clicks
+ * reuse the persisted stripe_customer_id.
+ */
+export async function POST(
+  _request: Request,
+  { params }: { params: Promise<{ invoiceNumber: string }> }
+) {
+  const user = await getSessionUser();
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  const { invoiceNumber } = await params;
+
+  const detail = await getInvoiceByNumberForOrg(invoiceNumber, user.orgId);
+  if (!detail) {
+    return NextResponse.json({ error: "Not found" }, { status: 404 });
+  }
+  const inv = detail.invoice;
+  if (inv.status !== "open" && inv.status !== "overdue") {
+    return NextResponse.json(
+      {
+        error:
+          inv.status === "paid"
+            ? "This invoice has already been paid."
+            : `This invoice cannot be paid online (status: ${inv.status}).`,
+      },
+      { status: 409 }
+    );
+  }
+
+  // We need org_billing for the customer creation address. The
+  // invoice has a SNAPSHOT but that's frozen at issue time; for
+  // creating/updating the Stripe customer we want the current
+  // address (which may have been corrected since the invoice).
+  // Snapshot is still authoritative on the invoice PDF and total.
+  const orgBilling = await getOrgBilling(user.orgId);
+  if (!orgBilling) {
+    return NextResponse.json(
+      { error: "Billing details are not configured for your organization." },
+      { status: 400 }
+    );
+  }
+
+  try {
+    const customerId = await ensureStripeCustomerForOrg({
+      zitadelOrgId: user.orgId,
+      companyName: orgBilling.companyName,
+      billingEmail: orgBilling.billingEmail,
+      address: {
+        line1: orgBilling.streetAddress,
+        postalCode: orgBilling.postalCode,
+        city: orgBilling.city,
+        country: orgBilling.country,
+      },
+    });
+    const baseUrl =
+      process.env.APP_BASE_URL ?? "https://app.pieced.ch";
+    const { url } = await createCheckoutSessionForInvoice({
+      invoice: inv,
+      customerId,
+      baseUrl,
+    });
+    return NextResponse.json({ url });
+  } catch (e) {
+    console.error(
+      `Failed to create Checkout Session for invoice ${invoiceNumber}:`,
+      e
+    );
+    return NextResponse.json(
+      { error: safeError(e, "Failed to start card payment.") },
+      { status: 500 }
+    );
+  }
+}

src/app/api/billing/invoices/[invoiceNumber]/pdf/route.ts

@@ -0,0 +1,43 @@
+import { NextResponse } from "next/server";
+import { getSessionUser } from "@/lib/session";
+import { getInvoiceByNumberForOrg, getInvoicePdf } from "@/lib/db";
+
+/**
+ * GET /api/billing/invoices/[invoiceNumber]/pdf
+ *
+ * Customer-facing PDF download. Same Uint8Array.from() variance
+ * fix as the admin route — see /api/admin/billing/invoices/[id]/pdf
+ * for the rationale.
+ *
+ * Authorization: looks up the invoice by number with org scope
+ * baked into the query, then re-fetches the PDF blob by id. A
+ * customer can't probe another org's invoice numbers — they get
+ * 404 either way.
+ */
+export async function GET(
+  _request: Request,
+  { params }: { params: Promise<{ invoiceNumber: string }> }
+) {
+  const user = await getSessionUser();
+  if (!user) {
+    return new NextResponse("Unauthorized", { status: 401 });
+  }
+  const { invoiceNumber } = await params;
+  const detail = await getInvoiceByNumberForOrg(invoiceNumber, user.orgId);
+  if (!detail) {
+    return new NextResponse("Not found", { status: 404 });
+  }
+  const pdf = await getInvoicePdf(detail.invoice.id);
+  if (!pdf) {
+    return new NextResponse("PDF not available", { status: 404 });
+  }
+  const body = Uint8Array.from(pdf.data);
+  return new NextResponse(body, {
+    status: 200,
+    headers: {
+      "Content-Type": "application/pdf",
+      "Content-Disposition": `inline; filename="${pdf.filename}"`,
+      "Cache-Control": "private, max-age=0, must-revalidate",
+    },
+  });
+}

src/app/api/billing/invoices/[invoiceNumber]/route.ts

@@ -0,0 +1,27 @@
+import { NextResponse } from "next/server";
+import { getSessionUser } from "@/lib/session";
+import { getInvoiceByNumberForOrg } from "@/lib/db";
+
+/**
+ * GET /api/billing/invoices/[invoiceNumber]
+ *
+ * Customer-scoped detail lookup by invoice number (the human-
+ * readable YYYY-NNNNN format the customer sees on the PDF). The
+ * org filter is part of the DB query — a customer probing another
+ * org's invoice number gets the same 404 as a non-existent one.
+ */
+export async function GET(
+  _request: Request,
+  { params }: { params: Promise<{ invoiceNumber: string }> }
+) {
+  const user = await getSessionUser();
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  const { invoiceNumber } = await params;
+  const detail = await getInvoiceByNumberForOrg(invoiceNumber, user.orgId);
+  if (!detail) {
+    return NextResponse.json({ error: "Not found" }, { status: 404 });
+  }
+  return NextResponse.json(detail);
+}

src/app/api/billing/invoices/route.ts

@@ -0,0 +1,39 @@
+import { NextResponse } from "next/server";
+import { getSessionUser } from "@/lib/session";
+import { listInvoices, syncOverdueInvoices } from "@/lib/db";
+
+/**
+ * GET /api/billing/invoices
+ *
+ * Customer-scoped list of invoices for the caller's org. Returns
+ * a flat array of Invoice headers (no line items — those are
+ * fetched separately by /[invoiceNumber]).
+ *
+ * Status filter is implicit: we return every invoice the
+ * customer's org has, all statuses (issued/paid/overdue/void)
+ * because the customer wants a single billing-history view.
+ *
+ * Before returning we run syncOverdueInvoices() so the displayed
+ * status reflects the current date — issued invoices past their
+ * due_at flip to 'overdue'. Cheap, idempotent, and avoids needing
+ * a separate cron for this transition.
+ */
+export async function GET() {
+  const user = await getSessionUser();
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  // Personal accounts have an org too — they share the same shape;
+  // their invoices show up under that synthetic org id.
+  try {
+    await syncOverdueInvoices();
+  } catch (e) {
+    // Non-fatal — display stale status rather than 500.
+    console.warn("syncOverdueInvoices failed in /api/billing/invoices:", e);
+  }
+  const invoices = await listInvoices({
+    zitadelOrgId: user.orgId,
+    limit: 200,
+  });
+  return NextResponse.json(invoices);
+}

src/app/api/skills/pricing/route.ts

@@ -0,0 +1,23 @@
+import { NextResponse } from "next/server";
+import { getSessionUser } from "@/lib/session";
+import { listSkillPricing } from "@/lib/db";
+
+/**
+ * GET /api/skills/pricing
+ *
+ * Returns the platform-wide skill pricing (daily price + setup fee
+ * per skill) for display in the customer's cost-disclosure dialog
+ * before they enable a priced skill. Any logged-in user can read
+ * this — pricing isn't org-specific and is effectively public
+ * information for anyone who'd be considering activation.
+ *
+ * Empty array means no skill is currently priced.
+ */
+export async function GET() {
+  const user = await getSessionUser();
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  const rows = await listSkillPricing();
+  return NextResponse.json(rows);
+}

src/app/api/skills/requests/[id]/withdraw/route.ts

@@ -0,0 +1,74 @@
+import { NextResponse } from "next/server";
+import { getSessionUser } from "@/lib/session";
+import {
+  getSkillActivationRequestById,
+  updateSkillActivationRequestStatus,
+} from "@/lib/db";
+import { getPackageDef } from "@/lib/packages";
+import { deletePackageSecrets } from "@/lib/openbao";
+
+/**
+ * POST /api/skills/requests/[id]/withdraw
+ *
+ * The owner of a pending activation request can cancel it. This
+ * doesn't touch K8s (the skill was never enabled) — it just flips
+ * the row to 'withdrawn' so the user's UI clears the pending
+ * state and they can try a different skill or retry later.
+ *
+ * Authorization: only the original requester OR a platform admin
+ * can withdraw a request. We deliberately don't allow other org
+ * members to cancel each other's requests in v1 — the partial
+ * unique index would let one user repeatedly cancel another's
+ * pending request.
+ */
+export async function POST(
+  _request: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const user = await getSessionUser();
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  const { id } = await params;
+  const req = await getSkillActivationRequestById(id);
+  if (!req) {
+    return NextResponse.json({ error: "Request not found" }, { status: 404 });
+  }
+  if (!user.isPlatform && req.zitadelUserId !== user.id) {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+  if (req.status !== "pending") {
+    return NextResponse.json(
+      { error: `Request is already ${req.status}` },
+      { status: 409 }
+    );
+  }
+  const updated = await updateSkillActivationRequestStatus(id, "withdrawn", {
+    reviewedBy: user.id,
+  });
+  if (!updated) {
+    return NextResponse.json(
+      { error: "Request status changed during withdraw." },
+      { status: 409 }
+    );
+  }
+
+  // Cleanup: same logic as reject — the user submitted secrets
+  // before the gate fired, and those are now orphaned in OpenBao.
+  // Best-effort delete; failure logged but not propagated. Skip
+  // customProvisioning packages (their deprovisioning is a
+  // separate, dedicated endpoint).
+  const def = getPackageDef(req.skillId);
+  if (def?.requiresSecrets && !def.customProvisioning) {
+    try {
+      await deletePackageSecrets(req.tenantName, req.skillId);
+    } catch (e) {
+      console.error(
+        `Failed to delete orphan secrets for ${req.tenantName}/${req.skillId} after withdraw:`,
+        e
+      );
+    }
+  }
+
+  return NextResponse.json(updated);
+}

src/app/api/skills/requests/route.ts

@@ -0,0 +1,40 @@
+import { NextResponse } from "next/server";
+import { getSessionUser } from "@/lib/session";
+import { listSkillActivationRequestsForTenant } from "@/lib/db";
+import { canUserSeeTenant } from "@/lib/visibility";
+import { getTenant } from "@/lib/k8s";
+
+/**
+ * GET /api/skills/requests?tenant=<name>
+ *
+ * Returns pending and most-recent-rejected skill activation
+ * requests for the named tenant. Used by the tenant settings page
+ * to render the "Manual review pending" or "Activation rejected"
+ * inline states on PackageCard.
+ *
+ * Authorization: the caller must be able to see the tenant (owner
+ * of its org, assigned user, or platform admin).
+ */
+export async function GET(request: Request) {
+  const user = await getSessionUser();
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  const { searchParams } = new URL(request.url);
+  const tenantName = searchParams.get("tenant");
+  if (!tenantName) {
+    return NextResponse.json(
+      { error: "Missing tenant parameter" },
+      { status: 400 }
+    );
+  }
+  const tenant = await getTenant(tenantName).catch(() => null);
+  if (!tenant) {
+    return NextResponse.json({ error: "Not found" }, { status: 404 });
+  }
+  if (!canUserSeeTenant(user, tenant)) {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+  const requests = await listSkillActivationRequestsForTenant(tenantName);
+  return NextResponse.json(requests);
+}

src/app/api/stripe/webhook/route.ts

@@ -0,0 +1,232 @@
+import { NextResponse } from "next/server";
+import type Stripe from "stripe";
+import { getStripeClient, getWebhookSecret } from "@/lib/stripe";
+import {
+  markInvoicePaid,
+  markStripeEventProcessed,
+  setInvoiceStripePaymentIntent,
+  tryRecordStripeEvent,
+} from "@/lib/db";
+
+/**
+ * POST /api/stripe/webhook
+ *
+ * Receives signed events from Stripe. The lifecycle:
+ *
+ *   1. Read RAW body (request.text(), NOT request.json() — Stripe's
+ *      HMAC is computed over the raw bytes and any JSON re-parse
+ *      will subtly mangle whitespace or property ordering and the
+ *      signature will fail).
+ *   2. Verify signature against the configured webhook secret. If
+ *      verification fails → 400. An attacker forging webhook calls
+ *      could otherwise mark our invoices paid.
+ *   3. Idempotency: INSERT the event id into stripe_events. If the
+ *      INSERT conflicts (duplicate delivery, which is normal — Stripe
+ *      retries failed deliveries for up to 72h), return 200 immediately
+ *      so Stripe doesn't keep retrying.
+ *   4. Process the event based on type. Currently we care about:
+ *        - checkout.session.completed   → flip invoice to paid
+ *        - charge.refunded              → log; void/credit handling is Phase 7
+ *        - payment_intent.payment_failed → log only; the failure is
+ *                                          already shown to the user on
+ *                                          the Stripe page, no action.
+ *      Unknown event types are ack'd with 200 (we may have other
+ *      events enabled at the Stripe end that we don't yet care about,
+ *      and 200 + log is cheaper than 404 + Stripe retries).
+ *   5. Stamp processed_at on success.
+ *
+ * Return contract: 2xx ack → Stripe stops retrying. Any non-2xx →
+ * Stripe retries with exponential backoff up to 72h. We aim for
+ * 200 on every reachable path (verified, deduplicated, or processed),
+ * and only 400 for signature failures (those would never succeed
+ * on retry anyway, so retrying is wasted effort).
+ *
+ * Performance: handlers run synchronously here because PieCed's
+ * event volume is tiny. If/when that changes, the obvious refactor
+ * is to enqueue (Phase 7) and ack first — but at v1 the inline
+ * model is simpler to reason about and harder to lose events with.
+ */
+
+// Next.js: explicitly disable static optimization; this route MUST
+// run on every request and must not be cached.
+export const dynamic = "force-dynamic";
+
+export async function POST(request: Request) {
+  // 1. Raw body — Stripe verifies the signature over these exact bytes.
+  const rawBody = await request.text();
+  const signature = request.headers.get("stripe-signature");
+  if (!signature) {
+    return new NextResponse("Missing stripe-signature header", {
+      status: 400,
+    });
+  }
+
+  // 2. Verify signature.
+  let event: Stripe.Event;
+  try {
+    const stripe = getStripeClient();
+    const secret = getWebhookSecret();
+    event = stripe.webhooks.constructEvent(rawBody, signature, secret);
+  } catch (err) {
+    console.error("Stripe webhook signature verification failed:", err);
+    // 400 — never retry. The webhook configuration is wrong on
+    // either end (rotated secret, wrong endpoint, etc.); retries
+    // won't fix it.
+    return new NextResponse("Invalid signature", { status: 400 });
+  }
+
+  // 3. Idempotency. INSERT event.id → fail-fast on duplicate.
+  let firstDelivery: boolean;
+  try {
+    firstDelivery = await tryRecordStripeEvent(
+      event.id,
+      event.type,
+      event
+    );
+  } catch (err) {
+    console.error(
+      `Failed to record stripe event ${event.id} (${event.type}):`,
+      err
+    );
+    // 5xx so Stripe retries — this is a DB hiccup, not a logic error.
+    return new NextResponse("DB error", { status: 500 });
+  }
+  if (!firstDelivery) {
+    // Already processed; ack happily.
+    return new NextResponse("Duplicate delivery; acknowledged.", {
+      status: 200,
+    });
+  }
+
+  // 4. Process. Each handler is responsible for being safe to run
+  //    exactly once (we already deduplicated by event.id above).
+  try {
+    switch (event.type) {
+      case "checkout.session.completed":
+        await handleCheckoutCompleted(
+          event.data.object as Stripe.Checkout.Session
+        );
+        break;
+      case "charge.refunded":
+        await handleChargeRefunded(event.data.object as Stripe.Charge);
+        break;
+      case "payment_intent.payment_failed":
+        await handlePaymentFailed(
+          event.data.object as Stripe.PaymentIntent
+        );
+        break;
+      default:
+        // Unknown event — log so we notice if Stripe starts sending
+        // something we should handle, but ack so we don't accumulate
+        // retries forever.
+        console.log(
+          `Stripe webhook: ignoring event type ${event.type} (id ${event.id})`
+        );
+    }
+  } catch (err) {
+    console.error(
+      `Stripe webhook handler failed for ${event.type} (id ${event.id}):`,
+      err
+    );
+    // 5xx → Stripe retries. The handler is idempotent because the
+    // stripe_events row already exists, so on the next attempt we'd
+    // short-circuit at step 3. To actually retry the work we'd need
+    // to DELETE the stripe_events row first; for v1 we don't bother
+    // and let a human investigate the logs.
+    return new NextResponse("Handler error", { status: 500 });
+  }
+
+  // 5. Mark processed.
+  try {
+    await markStripeEventProcessed(event.id);
+  } catch (err) {
+    // Non-fatal — the event was already processed, this is just the
+    // bookkeeping flag. Log and move on.
+    console.error(
+      `Failed to mark stripe event ${event.id} processed:`,
+      err
+    );
+  }
+
+  return new NextResponse("OK", { status: 200 });
+}
+
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+
+async function handleCheckoutCompleted(
+  session: Stripe.Checkout.Session
+): Promise<void> {
+  // Defensive: paid sessions are what we want; sessions can also
+  // complete in "unpaid" state (rare for mode=payment, more common
+  // for async/delayed methods like SEPA). Only flip the invoice
+  // when payment actually cleared.
+  if (session.payment_status !== "paid") {
+    console.log(
+      `Checkout session ${session.id} completed but payment_status=${session.payment_status}; waiting for downstream events.`
+    );
+    return;
+  }
+  const invoiceId =
+    session.metadata?.invoice_id ?? session.client_reference_id ?? null;
+  if (!invoiceId) {
+    console.error(
+      `Checkout session ${session.id} completed without invoice_id metadata; cannot link to invoice.`
+    );
+    return;
+  }
+  const paymentIntentId =
+    typeof session.payment_intent === "string"
+      ? session.payment_intent
+      : session.payment_intent?.id;
+
+  // Persist the PaymentIntent id on the invoice for traceability +
+  // future refund correlation.
+  if (paymentIntentId) {
+    await setInvoiceStripePaymentIntent(invoiceId, paymentIntentId);
+  }
+
+  // Flip status. markInvoicePaid is idempotent — re-running on an
+  // already-paid invoice returns null and we log + skip.
+  const updated = await markInvoicePaid(invoiceId, {
+    paidBy: "stripe",
+    paidMethodDetail: paymentIntentId
+      ? `Stripe Checkout (${paymentIntentId})`
+      : "Stripe Checkout",
+    paidAt: session.created ? new Date(session.created * 1000) : undefined,
+  });
+  if (!updated) {
+    // Already paid or void/draft — fine, nothing to do.
+    console.log(
+      `Invoice ${invoiceId} was not in a payable state when Stripe webhook arrived (likely already paid).`
+    );
+    return;
+  }
+  console.log(
+    `Invoice ${invoiceId} marked paid via Stripe (session ${session.id}, intent ${paymentIntentId}).`
+  );
+}
+
+async function handleChargeRefunded(charge: Stripe.Charge): Promise<void> {
+  // v1 scope: log only. Refunds always go through Stripe → admin
+  // initiates them in the dashboard. Updating our invoice status
+  // to 'void' or partial-credit needs more product thinking
+  // (partial refunds? credit notes? VAT corrections?). Phase 7.
+  console.log(
+    `Charge ${charge.id} refunded (amount ${charge.amount_refunded} ${charge.currency}); no portal-side state change.`
+  );
+}
+
+async function handlePaymentFailed(
+  intent: Stripe.PaymentIntent
+): Promise<void> {
+  // The Stripe-hosted page already shows the failure to the user.
+  // We log here for support visibility and to surface in Workbench.
+  // No invoice state change — it stays 'open' until paid.
+  console.log(
+    `PaymentIntent ${intent.id} failed: ${
+      intent.last_payment_error?.message ?? "(no message)"
+    }`
+  );
+}

src/app/api/support/tickets/[id]/comments/route.ts

@@ -0,0 +1,149 @@
+import { NextRequest, NextResponse } from "next/server";
+import { z } from "zod";
+import { getSessionUser } from "@/lib/session";
+import {
+  getSupportTicketById,
+  createSupportTicketComment,
+  updateSupportTicket,
+} from "@/lib/db";
+import {
+  sendSupportTicketReplyEmail,
+  sendSupportAdminNotificationEmail,
+} from "@/lib/email";
+import { safeError } from "@/lib/errors";
+import type { SupportTicketStatus } from "@/types";
+
+/**
+ * Comments on a support ticket (Feature 5). Threaded chronologically;
+ * no nested replies.
+ *
+ * Auto status transitions on comment:
+ *   - Customer reply on a `waiting_for_customer` → `in_progress`
+ *     (the ball is back in admin's court).
+ *   - Customer reply on a `resolved` ticket → `reopened`
+ *     (customer disagreed with the resolution).
+ *   - Admin reply on `open` or `reopened` → `in_progress`
+ *     (signals admin has engaged).
+ *   - Admin reply on `in_progress` → `waiting_for_customer`
+ *     (admin's response, ball is in customer's court).
+ *   - Otherwise no change.
+ *
+ * The auto-bump is opportunistic — caller may pass an explicit
+ * status override via the PATCH endpoint instead. We only auto-bump
+ * here when no comment-side override is provided (the comment POST
+ * doesn't accept a status field).
+ *
+ * Email rules:
+ *   - Customer replies → admin queue gets an "admin notification" email.
+ *   - Admin replies → customer gets a reply email (with the body
+ *     inline so they can read on mobile without clicking).
+ *   - No "you just commented" confirmation back to the author.
+ *
+ * The customer reply path skips the separate status-change email
+ * even when the status auto-bumps, on the principle that one email
+ * per action is enough; the admin will see the reply notification
+ * and the new status in the queue.
+ */
+
+const createSchema = z.object({
+  body: z.string().trim().min(1, "required").max(10_000),
+});
+
+/**
+ * Compute the auto-bumped status (if any) for a comment from a given
+ * author kind. Returns the new status if it should change, or null
+ * if it should stay the same.
+ */
+function autoBumpStatus(
+  current: SupportTicketStatus,
+  authorKind: "customer" | "admin"
+): SupportTicketStatus | null {
+  if (authorKind === "customer") {
+    if (current === "waiting_for_customer") return "in_progress";
+    if (current === "resolved") return "reopened";
+    return null;
+  }
+  // admin
+  if (current === "open" || current === "reopened") return "in_progress";
+  if (current === "in_progress") return "waiting_for_customer";
+  return null;
+}
+
+export async function POST(
+  req: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const user = await getSessionUser();
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  const { id } = await params;
+  const ticket = await getSupportTicketById(id);
+  if (!ticket) {
+    return NextResponse.json({ error: "Not found" }, { status: 404 });
+  }
+  // Same authorization as the GET on the parent resource.
+  if (!user.isPlatform && ticket.zitadelUserId !== user.id) {
+    return NextResponse.json({ error: "Not found" }, { status: 404 });
+  }
+
+  const body = await req.json().catch(() => null);
+  const parsed = createSchema.safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: "Invalid input", details: parsed.error.flatten() },
+      { status: 400 }
+    );
+  }
+
+  const authorKind: "customer" | "admin" = user.isPlatform
+    ? "admin"
+    : "customer";
+
+  try {
+    const comment = await createSupportTicketComment({
+      ticketId: id,
+      authorUserId: user.id,
+      authorName: user.name,
+      authorKind,
+      body: parsed.data.body,
+    });
+
+    // Auto-bump status if the comment changes the ball's court.
+    const nextStatus = autoBumpStatus(ticket.status, authorKind);
+    if (nextStatus) {
+      await updateSupportTicket(id, { status: nextStatus });
+    }
+
+    // Email the other side. Customer's reply → admin queue;
+    // admin's reply → customer.
+    if (authorKind === "customer") {
+      sendSupportAdminNotificationEmail({
+        reason: "replied",
+        ticketId: ticket.id,
+        title: ticket.title,
+        contactName: ticket.contactName,
+        contactEmail: ticket.contactEmail,
+        body: parsed.data.body,
+        category: ticket.category,
+      }).catch((e) => console.error("admin notification:", e));
+    } else {
+      sendSupportTicketReplyEmail({
+        to: ticket.contactEmail,
+        contactName: ticket.contactName,
+        ticketId: ticket.id,
+        title: ticket.title,
+        authorName: user.name,
+        body: parsed.data.body,
+      }).catch((e) => console.error("reply email:", e));
+    }
+
+    return NextResponse.json({ comment }, { status: 201 });
+  } catch (e: any) {
+    console.error("Failed to create support ticket comment:", e);
+    return NextResponse.json(
+      { error: safeError(e, "Failed to add comment") },
+      { status: 500 }
+    );
+  }
+}

src/app/api/support/tickets/[id]/route.ts

@@ -0,0 +1,132 @@
+import { NextRequest, NextResponse } from "next/server";
+import { z } from "zod";
+import { getSessionUser } from "@/lib/session";
+import {
+  getSupportTicketById,
+  listCommentsForTicket,
+  updateSupportTicket,
+} from "@/lib/db";
+import { sendSupportTicketStatusEmail } from "@/lib/email";
+import { safeError } from "@/lib/errors";
+
+/**
+ * Single support ticket detail (Feature 5).
+ *
+ * GET — returns the ticket plus all comments in chronological order.
+ * Authorization: customer sees their own; platform admin sees any.
+ *
+ * PATCH — change status and/or category. Admin only. Sends a status
+ * change email to the customer if status changed, UNLESS the same
+ * call also creates a comment (in that case the comment endpoint
+ * handles the email so the customer doesn't get two messages).
+ *
+ * No DELETE — tickets are durable history. Resolved tickets stay in
+ * the DB for the audit trail.
+ */
+
+const patchSchema = z.object({
+  status: z
+    .enum(["open", "in_progress", "waiting_for_customer", "resolved", "reopened"])
+    .optional(),
+  category: z
+    .enum(["bug", "feature_request", "question", "billing", "other"])
+    .optional(),
+});
+
+export async function GET(
+  _req: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const user = await getSessionUser();
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  const { id } = await params;
+  const ticket = await getSupportTicketById(id);
+  if (!ticket) {
+    return NextResponse.json({ error: "Not found" }, { status: 404 });
+  }
+  // Authorization: customer can see their own; platform admin can
+  // see any. Owners cannot see their org's tickets — confirmed by
+  // Feature 5 visibility design (per-user, not per-org).
+  if (!user.isPlatform && ticket.zitadelUserId !== user.id) {
+    // Don't leak existence — same 404 as if the ticket didn't exist.
+    return NextResponse.json({ error: "Not found" }, { status: 404 });
+  }
+  const comments = await listCommentsForTicket(id);
+  return NextResponse.json({ ticket, comments });
+}
+
+export async function PATCH(
+  req: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const user = await getSessionUser();
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  const { id } = await params;
+  const ticket = await getSupportTicketById(id);
+  if (!ticket) {
+    return NextResponse.json({ error: "Not found" }, { status: 404 });
+  }
+
+  const body = await req.json().catch(() => null);
+  const parsed = patchSchema.safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: "Invalid input", details: parsed.error.flatten() },
+      { status: 400 }
+    );
+  }
+
+  // Authorization: status/category changes are admin-only EXCEPT
+  // the customer can close their own ticket via status='resolved'
+  // (Feature 5 design — gives them an "I figured it out, never mind"
+  // escape hatch). Customer cannot reopen via this endpoint — that
+  // happens automatically when they comment on a resolved ticket
+  // (handled in the comments POST).
+  const isCustomerSelfClose =
+    !user.isPlatform &&
+    ticket.zitadelUserId === user.id &&
+    parsed.data.status === "resolved" &&
+    parsed.data.category === undefined;
+
+  if (!user.isPlatform && !isCustomerSelfClose) {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+
+  try {
+    const previousStatus = ticket.status;
+    const updated = await updateSupportTicket(id, parsed.data);
+    if (!updated) {
+      return NextResponse.json({ error: "Not found" }, { status: 404 });
+    }
+
+    // Email customer when admin (not the customer themselves)
+    // changes status. Skip on customer-self-close — they know what
+    // they did. Skip when status didn't actually change (admin
+    // edited only category).
+    if (
+      user.isPlatform &&
+      parsed.data.status !== undefined &&
+      parsed.data.status !== previousStatus
+    ) {
+      sendSupportTicketStatusEmail({
+        to: ticket.contactEmail,
+        contactName: ticket.contactName,
+        ticketId: ticket.id,
+        title: ticket.title,
+        newStatus: parsed.data.status,
+      }).catch((e) => console.error("status email:", e));
+    }
+
+    return NextResponse.json({ ticket: updated });
+  } catch (e: any) {
+    console.error("Failed to update support ticket:", e);
+    return NextResponse.json(
+      { error: safeError(e, "Failed to update ticket") },
+      { status: 500 }
+    );
+  }
+}

src/app/api/support/tickets/route.ts

@@ -0,0 +1,103 @@
+import { NextRequest, NextResponse } from "next/server";
+import { z } from "zod";
+import { getSessionUser } from "@/lib/session";
+import {
+  createSupportTicket,
+  listSupportTicketsForUser,
+  listAllSupportTickets,
+} from "@/lib/db";
+import {
+  sendSupportTicketCreatedEmail,
+  sendSupportAdminNotificationEmail,
+} from "@/lib/email";
+import { safeError } from "@/lib/errors";
+
+/**
+ * Support tickets API (Feature 5).
+ *
+ * Visibility: tickets are scoped strictly per-user (zitadel_user_id).
+ * Coworkers in the same org cannot see each other's tickets — this
+ * is the team's design choice for privacy. Platform admins see
+ * everything (the admin queue lives at the same UI but pulls from
+ * a different list).
+ *
+ * GET — for platform users, returns all tickets across all users.
+ * For everyone else, returns only the caller's own tickets. The
+ * client decides the rendering based on user role; we just return
+ * the right list.
+ *
+ * POST — creates a ticket, sends a confirmation email to the
+ * customer and a notification email to the admin distribution list.
+ */
+
+const createSchema = z.object({
+  title: z.string().trim().min(3, "required").max(200),
+  description: z.string().trim().min(10, "required").max(10_000),
+  category: z.enum(["bug", "feature_request", "question", "billing", "other"]),
+});
+
+export async function GET() {
+  const user = await getSessionUser();
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  // Platform admins get the global queue; everyone else sees their
+  // own tickets only. Visibility-by-default-deny: even an org owner
+  // doesn't see their coworkers' tickets, by Feature 5 design.
+  const tickets = user.isPlatform
+    ? await listAllSupportTickets()
+    : await listSupportTicketsForUser(user.id);
+  return NextResponse.json({ tickets });
+}
+
+export async function POST(req: NextRequest) {
+  const user = await getSessionUser();
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  const body = await req.json().catch(() => null);
+  const parsed = createSchema.safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: "Invalid input", details: parsed.error.flatten() },
+      { status: 400 }
+    );
+  }
+  try {
+    const ticket = await createSupportTicket({
+      zitadelOrgId: user.orgId,
+      zitadelUserId: user.id,
+      title: parsed.data.title,
+      description: parsed.data.description,
+      category: parsed.data.category,
+      contactName: user.name,
+      contactEmail: user.email,
+    });
+
+    // Fire-and-log email notifications. Both are best-effort;
+    // failure to send doesn't roll back the ticket creation.
+    sendSupportTicketCreatedEmail({
+      to: user.email,
+      contactName: user.name,
+      ticketId: ticket.id,
+      title: ticket.title,
+    }).catch((e) => console.error("ticket created email:", e));
+    sendSupportAdminNotificationEmail({
+      reason: "created",
+      ticketId: ticket.id,
+      title: ticket.title,
+      contactName: user.name,
+      contactEmail: user.email,
+      body: ticket.description,
+      category: ticket.category,
+    }).catch((e) => console.error("admin notification:", e));
+
+    return NextResponse.json({ ticket }, { status: 201 });
+  } catch (e: any) {
+    console.error("Failed to create support ticket:", e);
+    return NextResponse.json(
+      { error: safeError(e, "Failed to create ticket") },
+      { status: 500 }
+    );
+  }
+}

src/app/api/tenants/[name]/budget/route.ts

@@ -0,0 +1,126 @@
+import { NextRequest, NextResponse } from "next/server";
+import { z } from "zod";
+import { getSessionUser, canMutate } from "@/lib/session";
+import { getTenant } from "@/lib/k8s";
+import { canUserSeeTenant } from "@/lib/visibility";
+import { findKeyByAlias, updateKeyBudget } from "@/lib/litellm";
+import { safeError } from "@/lib/errors";
+
+/**
+ * Update the per-tenant budget — operates on the LiteLLM virtual
+ * key, NOT on the team.
+ *
+ * Why per-key
+ * -----------
+ * Each tenant in an org has its own virtual key
+ * (`key_alias = tenant.metadata.name`); the team that owns those
+ * keys is org-scoped and shared across all the org's tenants. A
+ * budget on the team would cap the whole org; a budget on the key
+ * caps just this one tenant. Customers landing on the tenant detail
+ * page reasonably expect "edit budget" to mean "the budget of THIS
+ * tenant" — so we put it on the key.
+ *
+ * The team-level (org-wide) budget is a separate control that lives
+ * in /settings (not yet implemented) — the two coexist: LiteLLM
+ * applies whichever cap is hit first.
+ *
+ * Schema:
+ *   - maxBudget: number > 0 (set a cap), or null (remove the cap).
+ *   - budgetDuration: one of "30d", "1mo", "1y", or null (lifetime).
+ *
+ * Authorization: owners and platform admins.
+ */
+
+const patchSchema = z.object({
+  // > 0 because LiteLLM rejects 0 and a zero cap would lock the key
+  // out instantly. Upper bound 1M as a typo guard.
+  maxBudget: z.number().positive().max(1_000_000).nullable(),
+  budgetDuration: z.enum(["30d", "1mo", "1y"]).nullable(),
+});
+
+export async function PATCH(
+  req: NextRequest,
+  { params }: { params: Promise<{ name: string }> }
+) {
+  const user = await getSessionUser();
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  if (!canMutate(user)) {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+
+  const { name } = await params;
+  const tenant = await getTenant(name);
+  if (!tenant) {
+    return NextResponse.json({ error: "Not found" }, { status: 404 });
+  }
+  if (!(await canUserSeeTenant(user, tenant))) {
+    // Don't leak existence — same 404 a non-visible tenant gets.
+    return NextResponse.json({ error: "Not found" }, { status: 404 });
+  }
+
+  const teamId = tenant.status?.litellmTeamId;
+  if (!teamId) {
+    return NextResponse.json(
+      {
+        error:
+          "Tenant has no LiteLLM team yet. Please wait until provisioning completes.",
+      },
+      { status: 409 }
+    );
+  }
+
+  const body = await req.json().catch(() => null);
+  const parsed = patchSchema.safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: "Invalid input", details: parsed.error.flatten() },
+      { status: 400 }
+    );
+  }
+
+  // Defensive: removing the cap should null out the duration too —
+  // a reset cadence on an unlimited budget is meaningless and would
+  // confuse LiteLLM's bookkeeping.
+  const maxBudget = parsed.data.maxBudget;
+  const budgetDuration =
+    maxBudget === null ? null : parsed.data.budgetDuration;
+
+  // Look up the key by alias (= tenant name). The token returned is
+  // what /key/update wants in the `key` field.
+  let keyInfo;
+  try {
+    keyInfo = await findKeyByAlias(teamId, name);
+  } catch (e: any) {
+    console.error("Failed to look up tenant key:", e);
+    return NextResponse.json(
+      { error: safeError(e, "Failed to look up tenant key") },
+      { status: 500 }
+    );
+  }
+  if (!keyInfo) {
+    return NextResponse.json(
+      {
+        error:
+          "Tenant has no virtual key yet. Please wait until provisioning completes.",
+      },
+      { status: 409 }
+    );
+  }
+
+  try {
+    await updateKeyBudget(keyInfo.token, { maxBudget, budgetDuration });
+    return NextResponse.json({
+      message: maxBudget === null ? "Budget removed." : "Budget updated.",
+      maxBudget,
+      budgetDuration,
+    });
+  } catch (e: any) {
+    console.error("Failed to update key budget:", e);
+    return NextResponse.json(
+      { error: safeError(e, "Failed to update budget") },
+      { status: 500 }
+    );
+  }
+}

src/app/api/tenants/[name]/resume-request/route.ts

@@ -1,4 +1,5 @@
 import { NextRequest, NextResponse } from "next/server";
+import { z } from "zod";
 import { getSessionUser, canMutate } from "@/lib/session";
 import { getTenant, setTenantAnnotation } from "@/lib/k8s";
 import { canUserSeeTenant } from "@/lib/visibility";
@@ -7,8 +8,26 @@ import {
   getPendingResumeRequestForTenant,
   getTenantRequestByTenantName,
 } from "@/lib/db";
+import { sendResumeRequestAdminNotificationEmail } from "@/lib/email";
 import { safeError } from "@/lib/errors";
 
+/**
+ * Body schema. Both fields optional; the customer can submit a
+ * resume request with no body at all (the JS client sends `{}`),
+ * or with a note explaining their reactivation rationale.
+ *
+ * Length cap mirrors `billing_notes` (2000 chars) — same lower
+ * bound for "free-form text we don't want abused".
+ */
+const bodySchema = z.object({
+  customerNotes: z
+    .string()
+    .trim()
+    .max(2000)
+    .optional()
+    .transform((v) => (v && v.length > 0 ? v : undefined)),
+});
+
 /**
  * POST /api/tenants/[name]/resume-request
  *
@@ -82,6 +101,18 @@ export async function POST(
     );
   }
 
+  // Body is optional — the customer can submit a resume request
+  // with no payload at all, or attach a free-form note.
+  const rawBody = await req.json().catch(() => ({}));
+  const parsed = bodySchema.safeParse(rawBody ?? {});
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: "Invalid input", details: parsed.error.flatten() },
+      { status: 400 }
+    );
+  }
+  const customerNotes = parsed.data.customerNotes;
+
   // Already a pending request? Don't duplicate.
   const existing = await getPendingResumeRequestForTenant(name);
   if (existing) {
@@ -110,6 +141,7 @@ export async function POST(
       contactEmail: user.email,
       companyName: provision?.companyName ?? tenant.spec.displayName ?? name,
       agentName: provision?.agentName ?? "Assistant",
+      customerNotes,
     });
 
     // Stamp the annotation so the operator pauses its TTL. If this
@@ -128,6 +160,20 @@ export async function POST(
       );
     }
 
+    // Notify admin distribution. Fire-and-log: failure to email
+    // doesn't roll back the request creation. The customer's note
+    // (if any) is included so admin can triage from the email
+    // without opening the queue.
+    sendResumeRequestAdminNotificationEmail({
+      tenantName: name,
+      companyName: resumeRequest.companyName,
+      contactName: resumeRequest.contactName,
+      contactEmail: resumeRequest.contactEmail,
+      customerNotes,
+    }).catch((e) =>
+      console.error("resume admin notification email failed:", e)
+    );
+
     return NextResponse.json(
       {
         message: "Resume request submitted. An admin will review shortly.",

src/app/api/tenants/[name]/route.ts

@@ -3,6 +3,12 @@ import { getSessionUser, canMutate } from "@/lib/session";
 import { canUserSeeTenant } from "@/lib/visibility";
 import { getTenant, patchTenantSpec } from "@/lib/k8s";
 import { getPackageDef } from "@/lib/packages";
+import {
+  createSkillActivationRequest,
+  getOrgBilling,
+  recordSkillEvents,
+} from "@/lib/db";
+import { sendSkillActivationAdminNotification } from "@/lib/email";
 import { safeError } from "@/lib/errors";
 
 const ALLOWED_WORKSPACE_FILES = ["SOUL.md", "AGENTS.md", "TOOLS.md"];
@@ -68,6 +74,17 @@ export async function PATCH(
 
     const specPatch: Record<string, any> = {};
 
+    // Track manual-setup gate activations created during this PATCH.
+    // We push to the K8s spec only the non-gated skills; the gated
+    // ones live in skill_activation_requests until admin approves
+    // and adds them via the admin endpoint. Platform admins bypass
+    // the gate (direct enable from /admin still applies immediately).
+    let gatedRequests: Array<{
+      skillId: string;
+      requestId: string;
+      skillName: string;
+    }> = [];
+
     // ── Validate packages against catalog ──
     if (body.packages !== undefined) {
       if (!Array.isArray(body.packages) || body.packages.length > 10) {
@@ -84,7 +101,63 @@ export async function PATCH(
           );
         }
       }
-      specPatch.packages = body.packages;
+      // Compute the to-be-added set against the existing spec.
+      const existingPackages = new Set<string>(existing.spec.packages ?? []);
+      const desiredPackages: string[] = body.packages;
+      const newlyAdded = desiredPackages.filter(
+        (p) => !existingPackages.has(p)
+      );
+      // Manual-setup gate. Customer adds get routed to the queue;
+      // platform admins go straight through.
+      if (!user.isPlatform && newlyAdded.length > 0) {
+        const orgIdForGate =
+          existing.metadata.labels?.["pieced.ch/zitadel-org-id"];
+        if (!orgIdForGate) {
+          // Defensive: every customer-visible tenant should have the
+          // org label. Without it we can't attribute the request.
+          return NextResponse.json(
+            { error: "Tenant missing org binding; contact support." },
+            { status: 500 }
+          );
+        }
+        const gatedSet = new Set<string>();
+        for (const skillId of newlyAdded) {
+          const def = getPackageDef(skillId);
+          if (!def?.requiresManualSetup) continue;
+          gatedSet.add(skillId);
+          try {
+            const req = await createSkillActivationRequest({
+              tenantName: name,
+              zitadelOrgId: orgIdForGate,
+              zitadelUserId: user.id,
+              skillId,
+            });
+            gatedRequests.push({
+              skillId,
+              requestId: req.id,
+              skillName: def.name,
+            });
+          } catch (e: any) {
+            if (e?.code === "REQUEST_ALREADY_PENDING") {
+              // Idempotent: a pending row already exists; just keep
+              // the skill out of the K8s spec and surface it as
+              // gated without creating a duplicate.
+              gatedRequests.push({
+                skillId,
+                requestId: "",
+                skillName: def.name,
+              });
+            } else {
+              throw e;
+            }
+          }
+        }
+        // Strip gated skills from the desired spec — they must not
+        // reach K8s until approved.
+        specPatch.packages = desiredPackages.filter((p) => !gatedSet.has(p));
+      } else {
+        specPatch.packages = desiredPackages;
+      }
     }
 
     // ── Validate workspaceFiles ──
@@ -187,7 +260,93 @@ export async function PATCH(
     }
 
     const updated = await patchTenantSpec(name, specPatch);
-    return NextResponse.json(updated);
+
+    // Billing — Phase 1: if packages changed, record enable/disable
+    // events. The diff is computed against the patched CR (the
+    // returned state) rather than `existing` so the events match
+    // what K8s actually committed. Best-effort: a logging failure
+    // never poisons the PATCH response — drift would be reconciled
+    // on the next backfill or by the next normal toggle.
+    //
+    // Note on races: two concurrent PATCHes could each see the
+    // same `existing` and both succeed at the K8s layer (last write
+    // wins for spec.packages, which is replaced wholesale). The
+    // events from the losing PATCH would then describe a transition
+    // that no longer reflects reality. Acceptable trade-off for v1
+    // — the toggle UI sends one request at a time and races would
+    // only matter for adjacent same-day toggles, which the billing
+    // computation collapses to a single billable day anyway.
+    if (specPatch.packages !== undefined) {
+      try {
+        const orgId =
+          existing.metadata.labels?.["pieced.ch/zitadel-org-id"] ?? null;
+        if (orgId) {
+          const oldSet = new Set<string>(existing.spec.packages ?? []);
+          const newSet = new Set<string>(updated.spec.packages ?? []);
+          const added = [...newSet].filter((x) => !oldSet.has(x));
+          const removed = [...oldSet].filter((x) => !newSet.has(x));
+          if (added.length > 0 || removed.length > 0) {
+            await recordSkillEvents(name, orgId, added, removed);
+          }
+        } else {
+          // A tenant without the org label is a pre-Slice-3 artifact
+          // — we can't attribute its skill events to any org. Log
+          // and skip rather than guess.
+          console.warn(
+            `billing: tenant ${name} has no zitadel-org-id label; skill events not recorded`
+          );
+        }
+      } catch (e) {
+        console.error(
+          `billing: failed to record skill events for ${name}:`,
+          e
+        );
+      }
+    }
+
+    // Phase 2.5: notify admin of newly created activation requests.
+    // Best-effort — email failure must not poison the PATCH response.
+    // requestId === "" means an existing-pending row was reused, so
+    // skip the email in that case (admin already knows).
+    if (gatedRequests.length > 0) {
+      const orgIdForEmail =
+        existing.metadata.labels?.["pieced.ch/zitadel-org-id"] ?? null;
+      const companyName = orgIdForEmail
+        ? await getOrgBilling(orgIdForEmail)
+            .then((b) => b?.companyName ?? null)
+            .catch(() => null)
+        : null;
+      for (const g of gatedRequests) {
+        if (!g.requestId) continue;
+        try {
+          await sendSkillActivationAdminNotification({
+            tenantName: name,
+            skillId: g.skillId,
+            skillName: g.skillName,
+            requesterEmail: user.email,
+            requesterName: user.name,
+            companyName,
+          });
+        } catch (e) {
+          console.error(
+            `Failed to send admin notification for skill activation request:`,
+            e
+          );
+        }
+      }
+    }
+
+    return NextResponse.json({
+      ...updated,
+      // Phase 2.5: tells the client which requested-to-enable skills
+      // didn't actually land in the spec because they're awaiting
+      // admin approval. UI uses this to render the "pending review"
+      // state on those skill cards.
+      pendingActivationRequests: gatedRequests.map((g) => ({
+        skillId: g.skillId,
+        skillName: g.skillName,
+      })),
+    });
   } catch (e: any) {
     return NextResponse.json(
       { error: safeError(e, "Failed to update tenant") },

src/app/api/tenants/[name]/suspend/route.ts

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { getSessionUser, canMutate } from "@/lib/session";
 import { getTenant, patchTenantSpec, setTenantAnnotation } from "@/lib/k8s";
 import { canUserSeeTenant } from "@/lib/visibility";
+import { recordSuspensionEvent } from "@/lib/db";
 import { safeError } from "@/lib/errors";
 
 const patchSchema = z.object({
@@ -101,6 +102,33 @@ export async function PATCH(
   try {
     await patchTenantSpec(name, { suspend });
 
+    // Billing — Phase 1: record the transition so monthly proration
+    // can exclude suspended days from the fixed fee. The portal
+    // commands this transition; the operator's status.suspendedAt
+    // lags by a reconcile cycle (seconds), which is irrelevant for
+    // monthly billing. Best-effort: a logging failure never blocks
+    // the suspend/resume itself.
+    try {
+      const orgId =
+        tenant.metadata.labels?.["pieced.ch/zitadel-org-id"] ?? null;
+      if (orgId) {
+        await recordSuspensionEvent(
+          name,
+          orgId,
+          suspend ? "suspended" : "resumed"
+        );
+      } else {
+        console.warn(
+          `billing: tenant ${name} has no zitadel-org-id label; suspension event not recorded`
+        );
+      }
+    } catch (e) {
+      console.error(
+        `billing: failed to record suspension event for ${name}:`,
+        e
+      );
+    }
+
     // On admin-side resume, also clear the pending-resume-request
     // annotation if it exists. Belt-and-suspenders: the admin-approve
     // endpoint already clears it on its happy path, but a platform

src/app/api/tenants/[name]/threema/route.ts

@@ -0,0 +1,168 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getSessionUser, canMutate } from "@/lib/session";
+import { getTenant } from "@/lib/k8s";
+import {
+  writePackageSecrets,
+  deletePackageSecrets,
+} from "@/lib/openbao";
+import { mintToken, revokeToken } from "@/lib/threema-relay";
+import { safeError } from "@/lib/errors";
+
+/**
+ * Threema package provisioning — special-cased because the credentials
+ * are platform-issued (relay mints them), not customer-supplied.
+ *
+ * POST /api/tenants/:name/threema
+ *   - Mints a per-tenant bearer + HMAC secret from the central relay.
+ *   - Writes both to OpenBao under
+ *     secret/data/tenants/<tenant-{name}>/threema-relay so the
+ *     operator's ExternalSecret can sync them into the tenant
+ *     namespace alongside other channel secrets.
+ *   - Returns 200 on success. The caller (PackageCard) then PATCHes
+ *     tenant.spec.packages to add "threema".
+ *
+ * DELETE /api/tenants/:name/threema
+ *   - Revokes the per-tenant token at the relay (cascades to all
+ *     routes — the relay's tokens.deleteToken also deletes routes).
+ *   - Deletes the OpenBao secret so the ExternalSecret/operator can
+ *     converge cleanly.
+ *   - Returns 200 on success even if no token existed (idempotent).
+ *
+ * Failure semantics
+ * -----------------
+ * On POST: if minting succeeds but the OpenBao write fails, we attempt
+ * to revoke the just-minted token before returning the error. That way
+ * the relay doesn't keep an orphan token row that nothing can use.
+ * Best-effort cleanup; if the revoke also fails, the relay admin can
+ * use DELETE /admin/tokens/<name> manually.
+ *
+ * On DELETE: we revoke FIRST, then delete OpenBao. If revoke fails we
+ * return the error and stop — leaving OpenBao alone means the pod's
+ * still-mounted secret keeps working in the brief window between
+ * "customer hits disable" and "operator reconciles spec without threema",
+ * which is more graceful than yanking the secret out from under a
+ * running pod.
+ */
+
+const VAULT_SUFFIX = "threema-relay";
+
+export async function POST(
+  _req: NextRequest,
+  { params }: { params: Promise<{ name: string }> },
+) {
+  const user = await getSessionUser();
+  if (!user) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  if (!canMutate(user))
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+
+  const { name } = await params;
+
+  try {
+    const tenant = await getTenant(name);
+    if (!tenant)
+      return NextResponse.json({ error: "Not found" }, { status: 404 });
+    if (
+      !user.isPlatform &&
+      tenant.metadata.labels?.["pieced.ch/zitadel-org-id"] !== user.orgId
+    ) {
+      return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+    }
+
+    const minted = await mintToken(name);
+    if (!minted.ok) {
+      return NextResponse.json(
+        { error: `Relay mint failed: ${minted.message}` },
+        { status: minted.kind === "http" ? 502 : 503 },
+      );
+    }
+
+    try {
+      await writePackageSecrets(`tenant-${name}`, VAULT_SUFFIX, {
+        token: minted.token,
+        "hmac-secret": minted.hmacSecret,
+      });
+    } catch (e) {
+      // Compensate: revoke the just-minted token so the relay doesn't
+      // hold an orphan. Best-effort — log and continue surfacing the
+      // original error.
+      const revoke = await revokeToken(name);
+      if (!revoke.ok) {
+        console.error(
+          `[threema/provision] Compensating revoke failed for ${name}: ${revoke.message}`,
+        );
+      }
+      return NextResponse.json(
+        { error: `OpenBao write failed: ${safeError(e, "secret store unavailable")}` },
+        { status: 503 },
+      );
+    }
+
+    return NextResponse.json({ ok: true });
+  } catch (e) {
+    console.error("[threema/provision]", e);
+    return NextResponse.json(
+      { error: safeError(e, "Provisioning failed") },
+      { status: 500 },
+    );
+  }
+}
+
+export async function DELETE(
+  _req: NextRequest,
+  { params }: { params: Promise<{ name: string }> },
+) {
+  const user = await getSessionUser();
+  if (!user) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  if (!canMutate(user))
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+
+  const { name } = await params;
+
+  try {
+    const tenant = await getTenant(name);
+    if (!tenant)
+      return NextResponse.json({ error: "Not found" }, { status: 404 });
+    if (
+      !user.isPlatform &&
+      tenant.metadata.labels?.["pieced.ch/zitadel-org-id"] !== user.orgId
+    ) {
+      return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+    }
+
+    const revoke = await revokeToken(name);
+    // 404 from relay = nothing to revoke = idempotent success.
+    if (!revoke.ok && !(revoke.kind === "http" && revoke.status === 404)) {
+      return NextResponse.json(
+        { error: `Relay revoke failed: ${revoke.message}` },
+        { status: revoke.kind === "http" ? 502 : 503 },
+      );
+    }
+
+    // Delete the OpenBao secret. Idempotent — deletePackageSecrets
+    // tolerates 404.
+    try {
+      await deletePackageSecrets(`tenant-${name}`, VAULT_SUFFIX);
+    } catch (e) {
+      // Already revoked at the relay — surface the openbao failure
+      // but keep the partial-success state visible.
+      return NextResponse.json(
+        {
+          error: `Token revoked, but OpenBao delete failed: ${safeError(e, "secret store unavailable")}`,
+          partial: true,
+        },
+        { status: 503 },
+      );
+    }
+
+    return NextResponse.json({
+      ok: true,
+      deletedRoutes: revoke.ok ? revoke.deletedRoutes : 0,
+    });
+  } catch (e) {
+    console.error("[threema/deprovision]", e);
+    return NextResponse.json(
+      { error: safeError(e, "Deprovisioning failed") },
+      { status: 500 },
+    );
+  }
+}

src/app/api/tenants/[name]/threema/routes/route.ts

@@ -0,0 +1,217 @@
+import { NextRequest, NextResponse } from "next/server";
+import { z } from "zod";
+import { getSessionUser, canMutate } from "@/lib/session";
+import { getTenant, patchTenantSpec } from "@/lib/k8s";
+import {
+  createRoute,
+  deleteRoute,
+  isRouteConflictForOtherTenant,
+  isRouteConflictForSameTenant,
+  listRoutes,
+} from "@/lib/threema-relay";
+import { safeError } from "@/lib/errors";
+
+/**
+ * Threema route management — keeps three places in sync:
+ *
+ *   1. Relay DB (`routes` table)         — source of truth for uniqueness
+ *   2. K8s spec.channelUsers.threema     — what the operator sees
+ *   3. Customer UI                       — derived from (2)
+ *
+ * Add (POST) order: relay first (to claim uniqueness atomically), then
+ * K8s. On K8s failure we compensate by deleting the relay route.
+ *
+ * Remove (DELETE) order: K8s first (UI shows it gone immediately, which
+ * is the customer-facing semantic that matters), then relay. On relay
+ * failure we DO NOT rollback K8s — the customer wanted it gone, and
+ * the relay's stale route will be cleaned up on the next retry (deletes
+ * are idempotent at the relay).
+ *
+ * Read-modify-write race: patchTenantSpec uses K8s merge-patch on
+ * spec.channelUsers.threema, which REPLACES the entire array. We GET
+ * the latest array, mutate it, then PATCH. Two concurrent adds from the
+ * same customer's tabs can lose one of them. Acceptable at pilot scale
+ * (single-digit customers, low concurrency); revisit with SSA + field
+ * managers if it ever bites.
+ */
+
+const ROUTE_BODY = z.object({
+  threemaId: z
+    .string()
+    .regex(/^[A-Z0-9]{8}$/, "Threema ID must be 8 uppercase alphanumeric chars (no asterisk)"),
+});
+
+// ---- helpers --------------------------------------------------------------
+
+async function loadTenantOrError(name: string, user: Awaited<ReturnType<typeof getSessionUser>>) {
+  if (!user) return { error: NextResponse.json({ error: "Unauthorized" }, { status: 401 }) };
+  if (!canMutate(user))
+    return { error: NextResponse.json({ error: "Forbidden" }, { status: 403 }) };
+
+  const tenant = await getTenant(name);
+  if (!tenant)
+    return { error: NextResponse.json({ error: "Not found" }, { status: 404 }) };
+  if (
+    !user.isPlatform &&
+    tenant.metadata.labels?.["pieced.ch/zitadel-org-id"] !== user.orgId
+  ) {
+    return { error: NextResponse.json({ error: "Forbidden" }, { status: 403 }) };
+  }
+  return { tenant };
+}
+
+function currentThreemaIds(tenantSpec: any): string[] {
+  const cu = tenantSpec?.channelUsers ?? {};
+  const ids = cu.threema;
+  return Array.isArray(ids) ? ids.filter((x) => typeof x === "string") : [];
+}
+
+// ---- GET ------------------------------------------------------------------
+
+export async function GET(
+  _req: NextRequest,
+  { params }: { params: Promise<{ name: string }> },
+) {
+  const user = await getSessionUser();
+  const { name } = await params;
+  const loaded = await loadTenantOrError(name, user);
+  if (loaded.error) return loaded.error;
+
+  const res = await listRoutes(name);
+  if (!res.ok) {
+    return NextResponse.json(
+      { error: `Relay list failed: ${res.message}` },
+      { status: res.kind === "http" ? 502 : 503 },
+    );
+  }
+  return NextResponse.json({ routes: res.routes });
+}
+
+// ---- POST -----------------------------------------------------------------
+
+export async function POST(
+  req: NextRequest,
+  { params }: { params: Promise<{ name: string }> },
+) {
+  const user = await getSessionUser();
+  const { name } = await params;
+  const loaded = await loadTenantOrError(name, user);
+  if (loaded.error) return loaded.error;
+  const tenant = loaded.tenant;
+
+  const body = await req.json().catch(() => null);
+  const parsed = ROUTE_BODY.safeParse(body);
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: "Invalid threemaId", details: parsed.error.flatten() },
+      { status: 400 },
+    );
+  }
+  const threemaId = parsed.data.threemaId;
+
+  // Step 1: claim at the relay. Uniqueness is enforced here.
+  const claim = await createRoute(name, threemaId);
+  if (!claim.ok) {
+    if (isRouteConflictForOtherTenant(claim, name)) {
+      return NextResponse.json(
+        { error: "This Threema ID is already registered to another tenant" },
+        { status: 409 },
+      );
+    }
+    if (!isRouteConflictForSameTenant(claim, name)) {
+      // Genuine non-409 failure
+      return NextResponse.json(
+        { error: `Relay create failed: ${claim.message}` },
+        { status: claim.kind === "http" ? claim.status : 503 },
+      );
+    }
+    // Idempotent self-claim — continue to step 2 to ensure K8s mirrors it.
+  }
+
+  // Step 2: add to K8s spec.channelUsers.threema (idempotent).
+  const existing = currentThreemaIds(tenant!.spec);
+  if (!existing.includes(threemaId)) {
+    const next = [...existing, threemaId];
+    try {
+      await patchTenantSpec(name, {
+        channelUsers: {
+          ...(tenant!.spec?.channelUsers ?? {}),
+          threema: next,
+        } as Record<string, string[]>,
+      });
+    } catch (e) {
+      // Compensate: drop the relay route so we don't leave an orphan.
+      const compensate = await deleteRoute(name, threemaId);
+      if (!compensate.ok) {
+        console.error(
+          `[threema/routes] Compensating route delete failed for ${name}/${threemaId}: ${compensate.message}`,
+        );
+      }
+      return NextResponse.json(
+        { error: `K8s patch failed: ${safeError(e, "patch failed")}` },
+        { status: 500 },
+      );
+    }
+  }
+
+  return NextResponse.json({ ok: true, threemaId });
+}
+
+// ---- DELETE ---------------------------------------------------------------
+
+export async function DELETE(
+  req: NextRequest,
+  { params }: { params: Promise<{ name: string }> },
+) {
+  const user = await getSessionUser();
+  const { name } = await params;
+  const loaded = await loadTenantOrError(name, user);
+  if (loaded.error) return loaded.error;
+  const tenant = loaded.tenant;
+
+  // threemaId arrives as ?threemaId=... since DELETE bodies are uneven across clients.
+  const threemaId = new URL(req.url).searchParams.get("threemaId") ?? "";
+  const parsed = ROUTE_BODY.safeParse({ threemaId });
+  if (!parsed.success) {
+    return NextResponse.json(
+      { error: "Invalid threemaId", details: parsed.error.flatten() },
+      { status: 400 },
+    );
+  }
+
+  // Step 1: drop from K8s (idempotent).
+  const existing = currentThreemaIds(tenant!.spec);
+  if (existing.includes(parsed.data.threemaId)) {
+    const next = existing.filter((id) => id !== parsed.data.threemaId);
+    try {
+      await patchTenantSpec(name, {
+        channelUsers: {
+          ...(tenant!.spec?.channelUsers ?? {}),
+          threema: next,
+        } as Record<string, string[]>,
+      });
+    } catch (e) {
+      return NextResponse.json(
+        { error: `K8s patch failed: ${safeError(e, "patch failed")}` },
+        { status: 500 },
+      );
+    }
+  }
+
+  // Step 2: drop at relay (also idempotent — 404 is fine).
+  const dropped = await deleteRoute(name, parsed.data.threemaId);
+  if (!dropped.ok && !(dropped.kind === "http" && dropped.status === 404)) {
+    // K8s is already updated; surface but don't rollback. Next time the
+    // user toggles, both will converge.
+    return NextResponse.json(
+      {
+        ok: true,
+        threemaId: parsed.data.threemaId,
+        warning: `Removed from K8s but relay drop failed: ${dropped.message}`,
+      },
+      { status: 200 },
+    );
+  }
+
+  return NextResponse.json({ ok: true, threemaId: parsed.data.threemaId });
+}

src/app/api/usage/route.ts

@@ -2,7 +2,11 @@ import { NextRequest, NextResponse } from "next/server";
 import { getSessionUser } from "@/lib/session";
 import { listTenants } from "@/lib/k8s";
 import { listVisibleTenants } from "@/lib/visibility";
-import { getTeamInfo, getTeamSpendLogsV2 } from "@/lib/litellm";
+import {
+  getTeamInfo,
+  getTeamSpendLogsV2,
+  findKeyByAlias,
+} from "@/lib/litellm";
 import { safeError } from "@/lib/errors";
 
 /**
@@ -126,6 +130,16 @@ export async function GET(req: NextRequest) {
   try {
     const teamInfo = await getTeamInfo(teamId);
 
+    // Per-tenant budget lives on the virtual key, not the team
+    // (Feature 7 fix). When the request is scoped to a specific
+    // tenant (keyAlias provided), look up the key so we can return
+    // the per-tenant cap. Tolerate failure — older LiteLLM builds
+    // or short-lived race conditions during provisioning shouldn't
+    // 500 the whole usage page; we degrade to "no key info".
+    const keyInfo = keyAlias
+      ? await findKeyByAlias(teamId, keyAlias).catch(() => null)
+      : null;
+
     // Page through results — server-side filtered by key_alias when
     // provided. Pagination still needed because LiteLLM caps
     // page_size at 100, and a busy tenant can easily exceed that in
@@ -191,16 +205,37 @@ export async function GET(req: NextRequest) {
         totalSpend,
         requestCount: allRequests.length,
       },
-      // Budget is always team-level (= company budget). Spend reported
-      // here is the team total, not the per-key total — the customer
-      // wants to see "how much of our company budget is left", not
-      // just "how much has this one tenant cost".
-      budget: {
+      // Budget reporting (Feature 7).
+      //
+      // When the caller scopes to a specific tenant (keyAlias set),
+      // we report THAT tenant's per-key budget — that's what the
+      // tenant detail page renders, and what the customer expects
+      // when they see "Budget" on a tenant's page.
+      //
+      // When unscoped (admin / org-wide view), we fall back to the
+      // team budget — that's the org-wide cap, conceptually different
+      // but the only thing meaningful at that scope.
+      //
+      // The two cases display the same way; the editor button gates
+      // on whether we know which tenant we're on (= keyAlias set).
+      budget: keyAlias && keyInfo
+        ? {
+            maxBudget: keyInfo.maxBudget,
+            spend: keyInfo.spend,
+            remaining:
+              keyInfo.maxBudget !== null
+                ? keyInfo.maxBudget - keyInfo.spend
+                : null,
+            budgetDuration: keyInfo.budgetDuration,
+          }
+        : {
             maxBudget: teamInfo?.team_info?.max_budget ?? null,
             spend: teamInfo?.team_info?.spend ?? 0,
             remaining: teamInfo?.team_info?.max_budget
-          ? teamInfo.team_info.max_budget - (teamInfo.team_info.spend ?? 0)
+              ? teamInfo.team_info.max_budget -
+                (teamInfo.team_info.spend ?? 0)
               : null,
+            budgetDuration: teamInfo?.team_info?.budget_duration ?? null,
           },
       rateLimits: {
         rpm: teamInfo?.team_info?.rpm_limit ?? null,

src/components/admin/admin-panel.tsx

@@ -384,6 +384,18 @@ export function AdminPanel({ initialTenants }: AdminPanelProps) {
                               {req.tenantName}
                             </div>
                           )}
+                          {/* Feature 6: customer's reactivation rationale,
+                              shown inline so admin can triage without
+                              opening a detail view. Truncated for
+                              queue density; full content on hover. */}
+                          {req.requestType === "resume" && req.customerNotes && (
+                            <div
+                              className="text-text-secondary text-xs mt-1 max-w-[280px] line-clamp-2 whitespace-pre-wrap"
+                              title={req.customerNotes}
+                            >
+                              {req.customerNotes}
+                            </div>
+                          )}
                         </td>
                         <td className="px-4 py-3">
                           <div className="text-text-primary text-sm">

src/components/admin/billing/generate-form.tsx

@@ -0,0 +1,345 @@
+"use client";
+
+import { useState, Fragment } from "react";
+import { useRouter } from "next/navigation";
+import { useTranslations } from "next-intl";
+import { Card, CardHeader } from "@/components/ui/card";
+import type { InvoiceDraft } from "@/types";
+
+interface OrgEntry {
+  zitadelOrgId: string;
+  tenantNames: string[];
+  companyName: string | null;
+  country: string | null;
+  hasBillingAddress: boolean;
+}
+
+interface Props {
+  orgs: OrgEntry[];
+}
+
+const LOCALE_OPTIONS = [
+  { value: "de", label: "Deutsch" },
+  { value: "en", label: "English" },
+  { value: "fr", label: "Français" },
+  { value: "it", label: "Italiano" },
+];
+
+/**
+ * Two-step flow: preview (dryRun) → commit.
+ *
+ * Preview displays the InvoiceDraft (lines, subtotal, VAT, total)
+ * plus any warnings. Admin reviews and either commits or aborts.
+ * Commit re-runs the generator without dryRun and redirects to the
+ * persisted invoice's detail page.
+ */
+export function GenerateForm({ orgs }: Props) {
+  const t = useTranslations("adminBilling");
+  const router = useRouter();
+
+  // Default to previous calendar month — that's the typical "bill
+  // for last month" use case.
+  const now = new Date();
+  const prevMonth = new Date(now.getFullYear(), now.getMonth() - 1, 1);
+  const [orgId, setOrgId] = useState(orgs[0]?.zitadelOrgId ?? "");
+  const [year, setYear] = useState(String(prevMonth.getFullYear()));
+  const [month, setMonth] = useState(String(prevMonth.getMonth() + 1));
+  const [locale, setLocale] = useState<string>("");
+  const [draft, setDraft] = useState<InvoiceDraft | null>(null);
+  const [error, setError] = useState("");
+  const [busy, setBusy] = useState(false);
+
+  const selectedOrg = orgs.find((o) => o.zitadelOrgId === orgId);
+  // Auto-detect default locale from country if admin hasn't picked
+  // one. Same logic as billing.ts's defaultLocaleForCountry.
+  const effectiveLocale =
+    locale ||
+    (() => {
+      const c = (selectedOrg?.country || "").toUpperCase();
+      if (["CH", "LI", "AT", "DE"].includes(c)) return "de";
+      if (["FR", "BE", "LU"].includes(c)) return "fr";
+      if (c === "IT") return "it";
+      return "en";
+    })();
+
+  const preview = async () => {
+    setError("");
+    setDraft(null);
+    setBusy(true);
+    try {
+      const res = await fetch("/api/admin/billing/generate", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          zitadelOrgId: orgId,
+          year: Number(year),
+          month: Number(month),
+          locale: effectiveLocale,
+          dryRun: true,
+        }),
+      });
+      const j = await res.json();
+      if (!res.ok) throw new Error(j.error || `HTTP ${res.status}`);
+      setDraft(j.draft);
+    } catch (e: any) {
+      setError(e.message);
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const commit = async () => {
+    if (!draft) return;
+    if (!confirm(t("confirmGenerate"))) return;
+    setError("");
+    setBusy(true);
+    try {
+      const res = await fetch("/api/admin/billing/generate", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          zitadelOrgId: orgId,
+          year: Number(year),
+          month: Number(month),
+          locale: effectiveLocale,
+          dryRun: false,
+        }),
+      });
+      const j = await res.json();
+      if (!res.ok) throw new Error(j.error || `HTTP ${res.status}`);
+      // Navigate to the new invoice's detail page.
+      if (j.invoice?.id) {
+        router.push(`/admin/billing/invoices/${j.invoice.id}`);
+      }
+    } catch (e: any) {
+      setError(e.message);
+      setBusy(false);
+    }
+  };
+
+  return (
+    <div className="space-y-6">
+      <Card>
+        <CardHeader>{t("generateFormTitle")}</CardHeader>
+        {orgs.length === 0 ? (
+          <p className="text-sm text-text-muted italic">{t("noOrgsToGenerate")}</p>
+        ) : (
+          <div className="space-y-4">
+            <label className="block">
+              <span className="text-sm text-text-secondary">{t("orgLabel")}</span>
+              <select
+                value={orgId}
+                onChange={(e) => {
+                  setOrgId(e.target.value);
+                  setDraft(null);
+                }}
+                className="mt-1 w-full px-3 py-2 rounded-md border border-border bg-surface-2 text-sm"
+              >
+                {orgs.map((o) => (
+                  <option key={o.zitadelOrgId} value={o.zitadelOrgId}>
+                    {o.companyName ?? o.zitadelOrgId}
+                    {!o.hasBillingAddress ? ` — ${t("noBillingAddrTag")}` : ""}
+                    {` (${o.tenantNames.length} ${t("tenantsLabel")})`}
+                  </option>
+                ))}
+              </select>
+              {selectedOrg && !selectedOrg.hasBillingAddress && (
+                <p className="text-xs text-error mt-1">
+                  {t("noBillingAddrWarning")}
+                </p>
+              )}
+            </label>
+            <div className="grid grid-cols-3 gap-3">
+              <label className="block">
+                <span className="text-sm text-text-secondary">{t("yearLabel")}</span>
+                <input
+                  type="number"
+                  min="2020"
+                  max="2100"
+                  value={year}
+                  onChange={(e) => {
+                    setYear(e.target.value);
+                    setDraft(null);
+                  }}
+                  className="mt-1 w-full px-3 py-2 rounded-md border border-border bg-surface-2 text-sm"
+                />
+              </label>
+              <label className="block">
+                <span className="text-sm text-text-secondary">{t("monthLabel")}</span>
+                <select
+                  value={month}
+                  onChange={(e) => {
+                    setMonth(e.target.value);
+                    setDraft(null);
+                  }}
+                  className="mt-1 w-full px-3 py-2 rounded-md border border-border bg-surface-2 text-sm"
+                >
+                  {Array.from({ length: 12 }, (_, i) => i + 1).map((m) => (
+                    <option key={m} value={m}>
+                      {String(m).padStart(2, "0")}
+                    </option>
+                  ))}
+                </select>
+              </label>
+              <label className="block">
+                <span className="text-sm text-text-secondary">
+                  {t("localeLabel")}
+                </span>
+                <select
+                  value={locale}
+                  onChange={(e) => {
+                    setLocale(e.target.value);
+                    setDraft(null);
+                  }}
+                  className="mt-1 w-full px-3 py-2 rounded-md border border-border bg-surface-2 text-sm"
+                >
+                  <option value="">
+                    {t("localeAuto")} ({effectiveLocale})
+                  </option>
+                  {LOCALE_OPTIONS.map((o) => (
+                    <option key={o.value} value={o.value}>
+                      {o.label}
+                    </option>
+                  ))}
+                </select>
+              </label>
+            </div>
+            <div className="flex items-center gap-3 pt-2">
+              <button
+                onClick={preview}
+                disabled={busy || !selectedOrg?.hasBillingAddress}
+                className="px-4 py-2 rounded-md border border-border text-sm disabled:opacity-50"
+              >
+                {busy && !draft ? t("computing") : t("previewBtn")}
+              </button>
+              {draft && (
+                <button
+                  onClick={commit}
+                  disabled={busy}
+                  className="px-4 py-2 rounded-md bg-accent text-white text-sm disabled:opacity-50"
+                >
+                  {busy ? t("saving") : t("commitBtn")}
+                </button>
+              )}
+              {error && (
+                <span className="text-sm text-error">{error}</span>
+              )}
+            </div>
+          </div>
+        )}
+      </Card>
+
+      {draft && <DraftPreview draft={draft} />}
+    </div>
+  );
+}
+
+function DraftPreview({ draft }: { draft: InvoiceDraft }) {
+  const t = useTranslations("adminBilling");
+
+  // Group lines by tenant for the preview (matches PDF layout).
+  const linesByTenant = new Map<string | null, typeof draft.lines>();
+  for (const ln of draft.lines) {
+    const key = ln.tenantName;
+    if (!linesByTenant.has(key)) linesByTenant.set(key, []);
+    linesByTenant.get(key)!.push(ln);
+  }
+  const tenantOrder = [...linesByTenant.keys()].sort((a, b) => {
+    if (a === null) return 1;
+    if (b === null) return -1;
+    return a.localeCompare(b);
+  });
+
+  return (
+    <Card>
+      <CardHeader>
+        {t("previewTitle")} — {draft.periodStart} → {draft.periodEnd}
+      </CardHeader>
+
+      {draft.warnings.length > 0 && (
+        <div className="mb-4 p-3 rounded-md border border-warning bg-warning/10 text-sm space-y-1">
+          <div className="font-semibold text-warning">{t("warningsTitle")}</div>
+          {draft.warnings.map((w, i) => (
+            <div key={i} className="text-text-secondary">• {w}</div>
+          ))}
+        </div>
+      )}
+
+      <table className="w-full text-sm">
+        <thead className="text-xs text-text-muted text-left">
+          <tr>
+            <th className="pb-2">{t("descCol")}</th>
+            <th className="pb-2 text-right">{t("qtyCol")}</th>
+            <th className="pb-2 text-right">{t("unitPriceCol")}</th>
+            <th className="pb-2 text-right">{t("amountCol")}</th>
+          </tr>
+        </thead>
+        <tbody>
+          {tenantOrder.map((tenantKey) => {
+            const lines = linesByTenant.get(tenantKey)!;
+            return (
+              <Fragment key={tenantKey ?? "_org"}>
+                {tenantKey && (
+                  <tr className="border-t border-border">
+                    <td colSpan={4} className="py-1.5 pt-3">
+                      <span className="text-xs font-semibold text-accent">
+                        {tenantKey}
+                      </span>
+                    </td>
+                  </tr>
+                )}
+                {lines.map((ln, i) => (
+                  <tr
+                    key={`${tenantKey}-${i}`}
+                    className="border-t border-border"
+                  >
+                    <td className="py-1.5">
+                      <div>{ln.description}</div>
+                      <div className="text-xs text-text-muted font-mono">
+                        {ln.kind}
+                      </div>
+                    </td>
+                    <td className="py-1.5 text-right">
+                      {ln.quantity}
+                      {ln.unitLabel ? ` ${ln.unitLabel}` : ""}
+                    </td>
+                    <td className="py-1.5 text-right font-mono text-xs">
+                      {ln.unitPriceChf.toFixed(4)}
+                    </td>
+                    <td className="py-1.5 text-right">
+                      {ln.amountChf.toFixed(2)}
+                    </td>
+                  </tr>
+                ))}
+              </Fragment>
+            );
+          })}
+          {draft.lines.length === 0 && (
+            <tr>
+              <td colSpan={4} className="py-4 text-center text-text-muted italic">
+                {t("noLinesGenerated")}
+              </td>
+            </tr>
+          )}
+        </tbody>
+      </table>
+
+      <div className="mt-4 pt-3 border-t border-border space-y-1 text-sm">
+        <div className="flex justify-between">
+          <span className="text-text-muted">{t("subtotal")}</span>
+          <span>CHF {draft.subtotalChf.toFixed(2)}</span>
+        </div>
+        <div className="flex justify-between">
+          <span className="text-text-muted">
+            {t("vat")} ({draft.vatRate.toFixed(2)}%)
+          </span>
+          <span>CHF {draft.vatAmountChf.toFixed(2)}</span>
+        </div>
+        <div className="flex justify-between pt-1 border-t border-border font-semibold">
+          <span>{t("total")}</span>
+          <span>CHF {draft.totalChf.toFixed(2)}</span>
+        </div>
+      </div>
+    </Card>
+  );
+}

src/components/admin/billing/invoice-detail-view.tsx

@@ -0,0 +1,307 @@
+"use client";
+
+import { useState, Fragment } from "react";
+import { useRouter } from "next/navigation";
+import { useTranslations } from "next-intl";
+import { Card, CardHeader } from "@/components/ui/card";
+import type { InvoiceDetail, InvoiceStatus } from "@/types";
+
+interface Props {
+  detail: InvoiceDetail;
+}
+
+/**
+ * Renders the invoice header (status, totals, action bar) then
+ * line items grouped by tenant, then billing snapshot. Actions are
+ * mark-paid (POST), delete (DELETE), PDF download (link to /pdf).
+ *
+ * On successful action we router.refresh() — the server-side page
+ * re-renders against the new DB state. For delete we navigate
+ * away first.
+ */
+export function InvoiceDetailView({ detail }: Props) {
+  const t = useTranslations("adminBilling");
+  const router = useRouter();
+  const { invoice, lines } = detail;
+
+  const [busyAction, setBusyAction] = useState<null | "mark-paid" | "delete">(
+    null
+  );
+  const [actionError, setActionError] = useState("");
+  const [noteInput, setNoteInput] = useState("");
+  const [noteOpen, setNoteOpen] = useState(false);
+
+  const markPaid = async () => {
+    setActionError("");
+    setBusyAction("mark-paid");
+    try {
+      const res = await fetch(
+        `/api/admin/billing/invoices/${invoice.id}/mark-paid`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ note: noteInput || undefined }),
+        }
+      );
+      const j = await res.json().catch(() => ({}));
+      if (!res.ok) throw new Error(j.error || `HTTP ${res.status}`);
+      setNoteOpen(false);
+      setNoteInput("");
+      router.refresh();
+    } catch (e: any) {
+      setActionError(e.message);
+    } finally {
+      setBusyAction(null);
+    }
+  };
+
+  const deleteInvoice = async () => {
+    if (!confirm(t("confirmDeleteInvoice", { num: invoice.invoiceNumber })))
+      return;
+    setActionError("");
+    setBusyAction("delete");
+    try {
+      const res = await fetch(`/api/admin/billing/invoices/${invoice.id}`, {
+        method: "DELETE",
+      });
+      if (!res.ok) {
+        const j = await res.json().catch(() => ({}));
+        throw new Error(j.error || `HTTP ${res.status}`);
+      }
+      router.push("/admin/billing/invoices");
+    } catch (e: any) {
+      setActionError(e.message);
+      setBusyAction(null);
+    }
+  };
+
+  // Group lines by tenant for display (matches PDF layout).
+  const linesByTenant = new Map<string | null, typeof lines>();
+  for (const ln of lines) {
+    const k = ln.tenantName;
+    if (!linesByTenant.has(k)) linesByTenant.set(k, []);
+    linesByTenant.get(k)!.push(ln);
+  }
+  const tenantOrder = [...linesByTenant.keys()].sort((a, b) => {
+    if (a === null) return 1;
+    if (b === null) return -1;
+    return a.localeCompare(b);
+  });
+
+  return (
+    <div className="space-y-4 animate-in">
+      <div className="flex items-end justify-between flex-wrap gap-3">
+        <div>
+          <h1 className="font-display text-2xl font-semibold accent-rule">
+            {invoice.invoiceNumber}
+          </h1>
+          <div className="flex items-center gap-3 mt-3 text-sm">
+            <StatusPill status={invoice.status} />
+            <span className="text-text-muted">
+              {invoice.periodStart} → {invoice.periodEnd}
+            </span>
+            <span className="text-text-muted">·</span>
+            <span className="text-text-muted">
+              {t("dueOnLabel")}: {invoice.dueAt}
+            </span>
+            <span className="text-text-muted">·</span>
+            <span className="text-text-muted font-mono text-xs">
+              {invoice.locale}
+            </span>
+          </div>
+        </div>
+        <div className="text-right">
+          <div className="text-xs text-text-muted">{t("totalLabel")}</div>
+          <div className="text-2xl font-semibold font-mono">
+            CHF {invoice.totalChf.toFixed(2)}
+          </div>
+        </div>
+      </div>
+
+      {/* Action bar */}
+      <Card>
+        <div className="flex flex-wrap items-center gap-3">
+          {invoice.hasPdf && (
+            <a
+              href={`/api/admin/billing/invoices/${invoice.id}/pdf`}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="px-4 py-2 rounded-md border border-border text-sm hover:bg-surface-2"
+            >
+              {t("downloadPdfBtn")}
+            </a>
+          )}
+          {(invoice.status === "open" || invoice.status === "overdue") && (
+            <>
+              {!noteOpen ? (
+                <button
+                  onClick={() => setNoteOpen(true)}
+                  disabled={busyAction !== null}
+                  className="px-4 py-2 rounded-md bg-accent text-white text-sm disabled:opacity-50"
+                >
+                  {t("markPaidBtn")}
+                </button>
+              ) : (
+                <div className="flex items-center gap-2 flex-grow">
+                  <input
+                    type="text"
+                    placeholder={t("paidNotePlaceholder")}
+                    value={noteInput}
+                    onChange={(e) => setNoteInput(e.target.value)}
+                    className="flex-grow px-3 py-1.5 rounded-md border border-border bg-surface-2 text-sm"
+                    autoFocus
+                  />
+                  <button
+                    onClick={markPaid}
+                    disabled={busyAction !== null}
+                    className="px-3 py-1.5 rounded-md bg-accent text-white text-sm disabled:opacity-50"
+                  >
+                    {busyAction === "mark-paid" ? t("saving") : t("confirm")}
+                  </button>
+                  <button
+                    onClick={() => {
+                      setNoteOpen(false);
+                      setNoteInput("");
+                    }}
+                    className="px-3 py-1.5 rounded-md border border-border text-sm"
+                  >
+                    {t("cancel")}
+                  </button>
+                </div>
+              )}
+            </>
+          )}
+          <button
+            onClick={deleteInvoice}
+            disabled={busyAction !== null}
+            className="ml-auto px-4 py-2 rounded-md border border-error text-error text-sm disabled:opacity-50 hover:bg-error/10"
+            title={t("deleteHint")}
+          >
+            {busyAction === "delete" ? t("deleting") : t("deleteBtn")}
+          </button>
+        </div>
+        {actionError && (
+          <div className="mt-3 text-sm text-error">{actionError}</div>
+        )}
+        {invoice.paidAt && (
+          <div className="mt-3 text-xs text-text-muted">
+            {t("paidOnLabel")}: {invoice.paidAt} · {invoice.paidBy} ·{" "}
+            {invoice.paidMethodDetail}
+          </div>
+        )}
+      </Card>
+
+      {/* Lines */}
+      <Card>
+        <CardHeader>{t("lineItemsTitle")}</CardHeader>
+        <table className="w-full text-sm">
+          <thead className="text-xs text-text-muted text-left">
+            <tr>
+              <th className="pb-2">{t("descCol")}</th>
+              <th className="pb-2 text-right">{t("qtyCol")}</th>
+              <th className="pb-2 text-right">{t("unitPriceCol")}</th>
+              <th className="pb-2 text-right">{t("amountCol")}</th>
+            </tr>
+          </thead>
+          <tbody>
+            {tenantOrder.map((tenantKey) => {
+              const tenantLines = linesByTenant.get(tenantKey)!;
+              return (
+                <Fragment key={tenantKey ?? "_org"}>
+                  {tenantKey && (
+                    <tr>
+                      <td colSpan={4} className="pt-3 pb-1">
+                        <span className="text-xs font-semibold text-accent">
+                          {tenantKey}
+                        </span>
+                      </td>
+                    </tr>
+                  )}
+                  {tenantLines.map((ln) => (
+                    <tr key={ln.id} className="border-t border-border">
+                      <td className="py-1.5">
+                        <div>{ln.description}</div>
+                        <div className="text-xs text-text-muted font-mono">
+                          {ln.kind}
+                        </div>
+                      </td>
+                      <td className="py-1.5 text-right">
+                        {ln.quantity}
+                        {ln.unitLabel ? ` ${ln.unitLabel}` : ""}
+                      </td>
+                      <td className="py-1.5 text-right font-mono text-xs">
+                        {ln.unitPriceChf.toFixed(4)}
+                      </td>
+                      <td className="py-1.5 text-right">
+                        {ln.amountChf.toFixed(2)}
+                      </td>
+                    </tr>
+                  ))}
+                </Fragment>
+              );
+            })}
+          </tbody>
+        </table>
+        <div className="mt-4 pt-3 border-t border-border space-y-1 text-sm">
+          <div className="flex justify-between">
+            <span className="text-text-muted">{t("subtotal")}</span>
+            <span>CHF {invoice.subtotalChf.toFixed(2)}</span>
+          </div>
+          <div className="flex justify-between">
+            <span className="text-text-muted">
+              {t("vat")} ({invoice.vatRate.toFixed(2)}%)
+            </span>
+            <span>CHF {invoice.vatAmountChf.toFixed(2)}</span>
+          </div>
+          <div className="flex justify-between pt-1 border-t border-border font-semibold">
+            <span>{t("total")}</span>
+            <span>CHF {invoice.totalChf.toFixed(2)}</span>
+          </div>
+        </div>
+      </Card>
+
+      {/* Billing snapshot */}
+      <Card>
+        <CardHeader>{t("billToSnapshotTitle")}</CardHeader>
+        <div className="text-sm space-y-1">
+          <div className="font-semibold">
+            {invoice.billingSnapshot.companyName}
+          </div>
+          <div>{invoice.billingSnapshot.streetAddress}</div>
+          <div>
+            {invoice.billingSnapshot.postalCode}{" "}
+            {invoice.billingSnapshot.city}
+          </div>
+          <div>{invoice.billingSnapshot.country}</div>
+          {invoice.billingSnapshot.vatNumber && (
+            <div className="text-text-muted">
+              VAT: {invoice.billingSnapshot.vatNumber}
+            </div>
+          )}
+          <div className="text-text-muted">
+            {invoice.billingSnapshot.billingEmail}
+          </div>
+        </div>
+      </Card>
+    </div>
+  );
+}
+
+function StatusPill({ status }: { status: InvoiceStatus }) {
+  const t = useTranslations("adminBilling");
+  const color =
+    status === "paid"
+      ? "bg-success/15 text-success"
+      : status === "overdue"
+        ? "bg-error/15 text-error"
+        : status === "void" || status === "uncollectible"
+          ? "bg-text-muted/15 text-text-muted"
+          : "bg-accent/15 text-accent";
+  return (
+    <span
+      className={`inline-block px-2 py-0.5 rounded text-xs font-medium ${color}`}
+    >
+      {t(`status_${status}`)}
+    </span>
+  );
+}

src/components/admin/billing/invoices-table.tsx

@@ -0,0 +1,183 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import Link from "next/link";
+import { useTranslations } from "next-intl";
+import { Card } from "@/components/ui/card";
+import type { Invoice, InvoiceStatus } from "@/types";
+
+interface Props {
+  initialInvoices: Invoice[];
+}
+
+const STATUS_FILTERS: (InvoiceStatus | "all")[] = [
+  "all",
+  "open",
+  "overdue",
+  "paid",
+  "void",
+];
+
+/**
+ * Filterable invoice list. Filters live in URL-less local state
+ * (simpler than syncing to query string for a v1 admin tool); a
+ * page refresh resets.
+ *
+ * Re-fetching strategy: when filters change, hit the API directly
+ * rather than router.refresh() so we don't bounce the user through
+ * a full page render.
+ */
+export function InvoicesTable({ initialInvoices }: Props) {
+  const t = useTranslations("adminBilling");
+  const [statusFilter, setStatusFilter] = useState<InvoiceStatus | "all">("all");
+  const [monthFilter, setMonthFilter] = useState("");
+  const [invoices, setInvoices] = useState(initialInvoices);
+  const [busy, setBusy] = useState(false);
+
+  useEffect(() => {
+    // Effect runs after initial render too; skip refetch on mount
+    // when filters are at their defaults — the server already
+    // gave us the right initial set.
+    if (statusFilter === "all" && monthFilter === "") return;
+    let cancelled = false;
+    setBusy(true);
+    const params = new URLSearchParams();
+    if (statusFilter !== "all") params.set("status", statusFilter);
+    if (monthFilter) params.set("month", monthFilter);
+    fetch(`/api/admin/billing/invoices?${params}`)
+      .then((r) => r.json())
+      .then((data) => {
+        if (!cancelled) setInvoices(data);
+      })
+      .catch((e) => console.error("Failed to load invoices:", e))
+      .finally(() => {
+        if (!cancelled) setBusy(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [statusFilter, monthFilter]);
+
+  return (
+    <div className="space-y-4">
+      <Card>
+        <div className="flex flex-wrap items-end gap-4">
+          <label className="block">
+            <span className="text-xs text-text-muted">{t("statusFilterLabel")}</span>
+            <select
+              value={statusFilter}
+              onChange={(e) =>
+                setStatusFilter(e.target.value as InvoiceStatus | "all")
+              }
+              className="mt-1 px-3 py-1.5 rounded-md border border-border bg-surface-2 text-sm"
+            >
+              {STATUS_FILTERS.map((s) => (
+                <option key={s} value={s}>
+                  {s === "all" ? t("allStatuses") : t(`status_${s}`)}
+                </option>
+              ))}
+            </select>
+          </label>
+          <label className="block">
+            <span className="text-xs text-text-muted">{t("monthFilterLabel")}</span>
+            <input
+              type="month"
+              value={monthFilter}
+              onChange={(e) => setMonthFilter(e.target.value)}
+              className="mt-1 px-3 py-1.5 rounded-md border border-border bg-surface-2 text-sm"
+            />
+          </label>
+          {monthFilter && (
+            <button
+              onClick={() => setMonthFilter("")}
+              className="text-xs text-text-muted hover:underline"
+            >
+              {t("clearFilter")}
+            </button>
+          )}
+          {busy && (
+            <span className="text-xs text-text-muted ml-auto">
+              {t("loading")}
+            </span>
+          )}
+        </div>
+      </Card>
+
+      <Card>
+        {invoices.length === 0 ? (
+          <p className="text-sm text-text-muted italic text-center py-6">
+            {t("noInvoicesFound")}
+          </p>
+        ) : (
+          <table className="w-full text-sm">
+            <thead className="text-xs text-text-muted text-left">
+              <tr>
+                <th className="pb-2">{t("invoiceNumberCol")}</th>
+                <th className="pb-2">{t("orgCol")}</th>
+                <th className="pb-2">{t("periodCol")}</th>
+                <th className="pb-2">{t("statusCol")}</th>
+                <th className="pb-2 text-right">{t("totalCol")}</th>
+                <th className="pb-2 text-right">{t("dueCol")}</th>
+              </tr>
+            </thead>
+            <tbody>
+              {invoices.map((inv) => (
+                <tr
+                  key={inv.id}
+                  className="border-t border-border hover:bg-surface-2 cursor-pointer"
+                >
+                  <td className="py-2">
+                    <Link
+                      href={`/admin/billing/invoices/${inv.id}`}
+                      className="font-mono text-xs hover:underline"
+                    >
+                      {inv.invoiceNumber}
+                    </Link>
+                  </td>
+                  <td className="py-2">
+                    <div className="text-xs">
+                      {inv.billingSnapshot.companyName || (
+                        <span className="font-mono">{inv.zitadelOrgId}</span>
+                      )}
+                    </div>
+                  </td>
+                  <td className="py-2 text-xs font-mono">
+                    {inv.periodStart.slice(0, 7)}
+                  </td>
+                  <td className="py-2">
+                    <StatusPill status={inv.status} />
+                  </td>
+                  <td className="py-2 text-right">
+                    CHF {inv.totalChf.toFixed(2)}
+                  </td>
+                  <td className="py-2 text-right text-xs text-text-muted">
+                    {inv.dueAt}
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        )}
+      </Card>
+    </div>
+  );
+}
+
+function StatusPill({ status }: { status: InvoiceStatus }) {
+  const t = useTranslations("adminBilling");
+  const color =
+    status === "paid"
+      ? "bg-success/15 text-success"
+      : status === "overdue"
+        ? "bg-error/15 text-error"
+        : status === "void" || status === "uncollectible"
+          ? "bg-text-muted/15 text-text-muted"
+          : "bg-accent/15 text-accent";
+  return (
+    <span
+      className={`inline-block px-2 py-0.5 rounded text-xs font-medium ${color}`}
+    >
+      {t(`status_${status}`)}
+    </span>
+  );
+}

src/components/admin/billing/pricing-editor.tsx

@@ -0,0 +1,491 @@
+"use client";
+
+import { useState } from "react";
+import { useRouter } from "next/navigation";
+import { useTranslations } from "next-intl";
+import { Card, CardHeader } from "@/components/ui/card";
+import type { PlatformPricing, SkillPricing } from "@/types";
+
+interface CatalogEntry {
+  id: string;
+  name: string;
+  category: string;
+}
+
+interface Props {
+  initialPricing: PlatformPricing;
+  initialSkillPricing: SkillPricing[];
+  catalog: CatalogEntry[];
+}
+
+/**
+ * Two-card layout:
+ *   1. Platform pricing form (4 inputs, save = PUT to /pricing).
+ *   2. Skill pricing table — list of priced skills, "Add skill"
+ *      picker below.
+ *
+ * No optimistic updates — every save round-trips and we
+ * router.refresh() afterwards so the server-side render stays
+ * the source of truth.
+ */
+export function PricingEditor({
+  initialPricing,
+  initialSkillPricing,
+  catalog,
+}: Props) {
+  const t = useTranslations("adminBilling");
+  const tPackages = useTranslations("packages");
+  const router = useRouter();
+
+  // -- Platform pricing form ----------------------------------------------
+  const [monthly, setMonthly] = useState(
+    String(initialPricing.tenantMonthlyFeeChf)
+  );
+  const [setup, setSetup] = useState(String(initialPricing.tenantSetupFeeChf));
+  const [threema, setThreema] = useState(
+    String(initialPricing.threemaMessageChf)
+  );
+  const [vat, setVat] = useState(String(initialPricing.vatRateChli));
+  const [savingPricing, setSavingPricing] = useState(false);
+  const [pricingError, setPricingError] = useState("");
+  const [pricingSaved, setPricingSaved] = useState(false);
+
+  const savePricing = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setSavingPricing(true);
+    setPricingError("");
+    setPricingSaved(false);
+    try {
+      const res = await fetch("/api/admin/billing/pricing", {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          tenantMonthlyFeeChf: Number(monthly),
+          tenantSetupFeeChf: Number(setup),
+          threemaMessageChf: Number(threema),
+          vatRateChli: Number(vat),
+        }),
+      });
+      if (!res.ok) {
+        const j = await res.json().catch(() => ({}));
+        throw new Error(j.error || `HTTP ${res.status}`);
+      }
+      setPricingSaved(true);
+      router.refresh();
+    } catch (e: any) {
+      setPricingError(e.message);
+    } finally {
+      setSavingPricing(false);
+    }
+  };
+
+  // -- Package pricing ----------------------------------------------------
+  // Server is authoritative — we don't keep an editable local copy of the
+  // table; instead each action posts to the API and we router.refresh().
+  //
+  // Naming carry-over: the underlying DB table is `skill_pricing` and the
+  // column is `skill_id`, dating from when only skills were priced. The
+  // model now applies to any PackageDef in the catalog regardless of
+  // category — core, channel, or skill. The state variable names below
+  // (newSkill*, addingSkill, etc.) retain the legacy "skill" prefix
+  // because renaming the entire surface for purely cosmetic reasons
+  // would create churn for no functional gain. Treat "skill" here as
+  // shorthand for "priced package".
+  const [newSkillId, setNewSkillId] = useState(catalog[0]?.id ?? "");
+  const [newSkillPrice, setNewSkillPrice] = useState("0.10");
+  const [newSkillSetupFee, setNewSkillSetupFee] = useState("0");
+  const [addingSkill, setAddingSkill] = useState(false);
+  const [skillError, setSkillError] = useState("");
+
+  // Core upsert — used by both the "add new skill" form and the inline
+  // editors on existing rows. Kept event-free so callers can invoke it
+  // without synthesizing a fake form event. Both `dailyPriceChf` and
+  // `setupFeeChf` are written together because the API does a full
+  // upsert; partial updates would silently zero the other field.
+  const upsertSkillPrice = async (
+    skillId: string,
+    dailyPriceChf: number,
+    setupFeeChf: number
+  ) => {
+    setAddingSkill(true);
+    setSkillError("");
+    try {
+      const res = await fetch("/api/admin/billing/skill-pricing", {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ skillId, dailyPriceChf, setupFeeChf }),
+      });
+      if (!res.ok) {
+        const j = await res.json().catch(() => ({}));
+        throw new Error(j.error || `HTTP ${res.status}`);
+      }
+      router.refresh();
+    } catch (e: any) {
+      setSkillError(e.message);
+    } finally {
+      setAddingSkill(false);
+    }
+  };
+
+  const onAddNewSkill = (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!newSkillId) return;
+    void upsertSkillPrice(
+      newSkillId,
+      Number(newSkillPrice),
+      Number(newSkillSetupFee)
+    );
+  };
+
+  const deleteSkill = async (skillId: string) => {
+    if (!confirm(t("confirmDeleteSkillPrice", { skill: skillId }))) return;
+    setSkillError("");
+    try {
+      const res = await fetch(
+        `/api/admin/billing/skill-pricing/${encodeURIComponent(skillId)}`,
+        { method: "DELETE" }
+      );
+      if (!res.ok) {
+        const j = await res.json().catch(() => ({}));
+        throw new Error(j.error || `HTTP ${res.status}`);
+      }
+      router.refresh();
+    } catch (e: any) {
+      setSkillError(e.message);
+    }
+  };
+
+  // Pricing applies to any catalog entry regardless of category. Grouped
+  // dropdown sorts options by category for visual scanning — core,
+  // channel, and skill in a single picker.
+  const skillCatalogOptions = [...catalog].sort((a, b) => {
+    const order = { core: 0, channel: 1, skill: 2 } as Record<string, number>;
+    const ca = order[a.category] ?? 99;
+    const cb = order[b.category] ?? 99;
+    if (ca !== cb) return ca - cb;
+    return a.name.localeCompare(b.name);
+  });
+  const catalogIndex = new Map(catalog.map((c) => [c.id, c]));
+  const pricedIds = new Set(initialSkillPricing.map((s) => s.skillId));
+
+  return (
+    <div className="space-y-6">
+      <Card>
+        <CardHeader>{t("platformPricingTitle")}</CardHeader>
+        <form onSubmit={savePricing} className="space-y-4">
+          <div className="grid grid-cols-2 gap-4">
+            <label className="block">
+              <span className="text-sm text-text-secondary">
+                {t("monthlyFeeLabel")} (CHF)
+              </span>
+              <input
+                type="number"
+                step="0.01"
+                min="0"
+                value={monthly}
+                onChange={(e) => setMonthly(e.target.value)}
+                className="mt-1 w-full px-3 py-2 rounded-md border border-border bg-surface-2 text-sm"
+                required
+              />
+            </label>
+            <label className="block">
+              <span className="text-sm text-text-secondary">
+                {t("setupFeeLabel")} (CHF)
+              </span>
+              <input
+                type="number"
+                step="0.01"
+                min="0"
+                value={setup}
+                onChange={(e) => setSetup(e.target.value)}
+                className="mt-1 w-full px-3 py-2 rounded-md border border-border bg-surface-2 text-sm"
+                required
+              />
+            </label>
+            <label className="block">
+              <span className="text-sm text-text-secondary">
+                {t("threemaMessageLabel")} (CHF)
+              </span>
+              <input
+                type="number"
+                step="0.0001"
+                min="0"
+                value={threema}
+                onChange={(e) => setThreema(e.target.value)}
+                className="mt-1 w-full px-3 py-2 rounded-md border border-border bg-surface-2 text-sm"
+                required
+              />
+            </label>
+            <label className="block">
+              <span className="text-sm text-text-secondary">
+                {t("vatRateLabel")} (%)
+              </span>
+              <input
+                type="number"
+                step="0.01"
+                min="0"
+                max="100"
+                value={vat}
+                onChange={(e) => setVat(e.target.value)}
+                className="mt-1 w-full px-3 py-2 rounded-md border border-border bg-surface-2 text-sm"
+                required
+              />
+            </label>
+          </div>
+          <div className="flex items-center gap-3">
+            <button
+              type="submit"
+              disabled={savingPricing}
+              className="px-4 py-2 rounded-md bg-accent text-white text-sm disabled:opacity-50"
+            >
+              {savingPricing ? t("saving") : t("save")}
+            </button>
+            {pricingSaved && (
+              <span className="text-sm text-success">{t("savedOk")}</span>
+            )}
+            {pricingError && (
+              <span className="text-sm text-error">{pricingError}</span>
+            )}
+          </div>
+        </form>
+      </Card>
+
+      <Card>
+        <CardHeader>{t("skillPricingTitle")}</CardHeader>
+        <p className="text-sm text-text-muted mb-4">{t("skillPricingDesc")}</p>
+
+        {initialSkillPricing.length > 0 ? (
+          <table className="w-full text-sm mb-6">
+            <thead className="text-xs text-text-muted text-left">
+              <tr>
+                <th className="pb-2">{t("skillCol")}</th>
+                <th className="pb-2 text-right">{t("dailyPriceCol")}</th>
+                <th className="pb-2 text-right">{t("setupFeeCol")}</th>
+                <th className="pb-2 text-right">{t("actionsCol")}</th>
+              </tr>
+            </thead>
+            <tbody>
+              {initialSkillPricing.map((sp) => {
+                const entry = catalogIndex.get(sp.skillId);
+                return (
+                  <tr
+                    key={sp.skillId}
+                    className="border-t border-border align-top"
+                  >
+                    <td className="py-2">
+                      <div className="font-mono text-xs">{sp.skillId}</div>
+                      {entry && (
+                        <div className="text-xs text-text-muted flex items-center gap-2">
+                          <span>{entry.name}</span>
+                          <span className="text-[10px] uppercase tracking-wider bg-surface-3 px-1.5 py-0.5 rounded">
+                            {entry.category}
+                          </span>
+                        </div>
+                      )}
+                    </td>
+                    <td className="py-2 text-right">
+                      {/* Inline edits write daily + setup together (full
+                          upsert on the API side). The other field is
+                          held constant from the snapshot here. */}
+                      <InlinePriceEditor
+                        skillId={sp.skillId}
+                        initialPrice={sp.dailyPriceChf}
+                        decimals={4}
+                        onSave={(price) =>
+                          upsertSkillPrice(sp.skillId, price, sp.setupFeeChf)
+                        }
+                      />
+                    </td>
+                    <td className="py-2 text-right">
+                      <InlinePriceEditor
+                        skillId={`${sp.skillId}-setup`}
+                        initialPrice={sp.setupFeeChf}
+                        decimals={2}
+                        onSave={(fee) =>
+                          upsertSkillPrice(sp.skillId, sp.dailyPriceChf, fee)
+                        }
+                      />
+                    </td>
+                    <td className="py-2 text-right">
+                      <button
+                        onClick={() => deleteSkill(sp.skillId)}
+                        className="text-xs text-error hover:underline"
+                      >
+                        {t("remove")}
+                      </button>
+                    </td>
+                  </tr>
+                );
+              })}
+            </tbody>
+          </table>
+        ) : (
+          <p className="text-sm text-text-muted italic mb-4">{t("noSkillsPriced")}</p>
+        )}
+
+        <form onSubmit={onAddNewSkill} className="flex items-end gap-3">
+          <label className="flex-grow">
+            <span className="text-xs text-text-muted">{t("addSkillLabel")}</span>
+            <select
+              value={newSkillId}
+              onChange={(e) => setNewSkillId(e.target.value)}
+              className="mt-1 w-full px-3 py-2 rounded-md border border-border bg-surface-2 text-sm"
+            >
+              {(() => {
+                // Group available options by category for the picker.
+                // Already-priced packages are filtered out (admin
+                // edits those inline above).
+                const available = skillCatalogOptions.filter(
+                  (c) => !pricedIds.has(c.id)
+                );
+                const byCat = new Map<string, typeof available>();
+                for (const c of available) {
+                  if (!byCat.has(c.category)) byCat.set(c.category, []);
+                  byCat.get(c.category)!.push(c);
+                }
+                // Labels for the optgroups. Reuse the existing
+                // packages.categories.* scope which already has
+                // translations in all four locales.
+                const labels: Record<string, string> = {
+                  core: tPackages("categories.core"),
+                  channel: tPackages("categories.channels"),
+                  skill: tPackages("categories.skills"),
+                };
+                const order: Array<"core" | "channel" | "skill"> = [
+                  "core",
+                  "channel",
+                  "skill",
+                ];
+                return order.map((cat) => {
+                  const items = byCat.get(cat);
+                  if (!items || items.length === 0) return null;
+                  return (
+                    <optgroup key={cat} label={labels[cat] ?? cat}>
+                      {items.map((c) => (
+                        <option key={c.id} value={c.id}>
+                          {c.name} ({c.id})
+                        </option>
+                      ))}
+                    </optgroup>
+                  );
+                });
+              })()}
+            </select>
+          </label>
+          <label className="w-28">
+            <span className="text-xs text-text-muted">
+              {t("dailyPriceLabel")}
+            </span>
+            <input
+              type="number"
+              step="0.01"
+              min="0"
+              value={newSkillPrice}
+              onChange={(e) => setNewSkillPrice(e.target.value)}
+              className="mt-1 w-full px-3 py-2 rounded-md border border-border bg-surface-2 text-sm"
+            />
+          </label>
+          <label className="w-28">
+            <span className="text-xs text-text-muted">
+              {t("skillSetupFeeLabel")}
+            </span>
+            <input
+              type="number"
+              step="0.01"
+              min="0"
+              value={newSkillSetupFee}
+              onChange={(e) => setNewSkillSetupFee(e.target.value)}
+              className="mt-1 w-full px-3 py-2 rounded-md border border-border bg-surface-2 text-sm"
+            />
+          </label>
+          <button
+            type="submit"
+            disabled={addingSkill || !newSkillId}
+            className="px-4 py-2 rounded-md bg-accent text-white text-sm disabled:opacity-50"
+          >
+            {addingSkill ? t("saving") : t("add")}
+          </button>
+        </form>
+        {skillError && (
+          <p className="text-sm text-error mt-2">{skillError}</p>
+        )}
+      </Card>
+    </div>
+  );
+}
+
+/**
+ * Tiny inline editor for a single numeric price/fee. Mounts in
+ * "view" mode showing the current value as a clickable badge;
+ * clicking turns it into an input + save/cancel buttons.
+ *
+ * `decimals` controls the display precision in view mode AND the
+ * step granularity of the input (daily prices use 4dp, setup fees
+ * use 2dp).
+ */
+function InlinePriceEditor({
+  skillId,
+  initialPrice,
+  decimals = 2,
+  onSave,
+}: {
+  skillId: string;
+  initialPrice: number;
+  decimals?: number;
+  onSave: (price: number) => Promise<void> | void;
+}) {
+  const t = useTranslations("adminBilling");
+  const [editing, setEditing] = useState(false);
+  const [value, setValue] = useState(String(initialPrice));
+  const [busy, setBusy] = useState(false);
+  const step = decimals === 4 ? "0.0001" : "0.01";
+
+  if (!editing) {
+    return (
+      <button
+        onClick={() => setEditing(true)}
+        className="text-sm font-mono hover:underline"
+        title={t("clickToEdit")}
+      >
+        CHF {initialPrice.toFixed(decimals)}
+      </button>
+    );
+  }
+  return (
+    <span className="inline-flex items-center gap-1">
+      <input
+        type="number"
+        step={step}
+        min="0"
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+        className="w-20 px-2 py-1 text-sm border border-border bg-surface-2 rounded"
+        autoFocus
+      />
+      <button
+        onClick={async () => {
+          setBusy(true);
+          try {
+            await onSave(Number(value));
+            setEditing(false);
+          } finally {
+            setBusy(false);
+          }
+        }}
+        disabled={busy}
+        className="text-xs px-2 py-1 bg-accent text-white rounded"
+      >
+        {busy ? "…" : "✓"}
+      </button>
+      <button
+        onClick={() => {
+          setValue(String(initialPrice));
+          setEditing(false);
+        }}
+        className="text-xs px-2 py-1 border border-border rounded"
+      >
+        ✕
+      </button>
+    </span>
+  );
+}

src/components/admin/openclaw-admin-panel.tsx

@@ -0,0 +1,277 @@
+"use client";
+
+import { useState } from "react";
+import { useRouter } from "next/navigation";
+import { useTranslations } from "next-intl";
+import { Card } from "@/components/ui/card";
+import type { OpenClawDefaults } from "@/lib/k8s";
+
+interface TenantRow {
+  name: string;
+  displayName: string;
+  phase: string;
+  override: { tag: string } | null;
+}
+
+interface Props {
+  initialDefaults: OpenClawDefaults;
+  tenants: TenantRow[];
+}
+
+/**
+ * Two-section admin UI:
+ *   - Default editor card at the top — single input for the tag.
+ *   - Tenant table below — each row has an inline edit/clear control.
+ *
+ * No optimistic updates: every save round-trips to the API and we
+ * router.refresh() to re-render the server-side state. Keeps the UI
+ * honest about what's actually applied (controller-runtime watch
+ * latency can be a couple of seconds).
+ *
+ * Tag-only by design — see operator notes for rationale.
+ */
+export function OpenClawAdminPanel({ initialDefaults, tenants }: Props) {
+  const t = useTranslations("openclawAdmin");
+  const tCommon = useTranslations("common");
+  const router = useRouter();
+
+  const [defaults, setDefaults] = useState(initialDefaults);
+  const [defaultTag, setDefaultTag] = useState(initialDefaults.defaultTag);
+  const [savingDefault, setSavingDefault] = useState(false);
+  const [defaultError, setDefaultError] = useState("");
+  const [defaultSaved, setDefaultSaved] = useState(false);
+
+  const onSaveDefault = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setSavingDefault(true);
+    setDefaultError("");
+    setDefaultSaved(false);
+    try {
+      const res = await fetch("/api/admin/openclaw", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ defaultTag: defaultTag.trim() }),
+      });
+      if (!res.ok) {
+        const data = await res.json().catch(() => ({}));
+        throw new Error(data.error || t("saveFailed"));
+      }
+      const next = await res.json();
+      setDefaults(next);
+      setDefaultSaved(true);
+    } catch (e: any) {
+      setDefaultError(e.message);
+    } finally {
+      setSavingDefault(false);
+    }
+  };
+
+  return (
+    <div className="space-y-8">
+      {/* Default editor */}
+      <section className="animate-in animate-in-delay-1">
+        <h2 className="text-xs font-semibold uppercase tracking-wider text-text-muted mb-3">
+          {t("defaultSection")}
+        </h2>
+        <Card>
+          <p className="text-sm text-text-secondary mb-4">
+            {t("defaultDescription")}
+          </p>
+          <form onSubmit={onSaveDefault} className="space-y-4">
+            <div>
+              <label className="block text-xs uppercase tracking-wider text-text-muted mb-1">
+                {t("fieldTag")}
+              </label>
+              <input
+                type="text"
+                value={defaultTag}
+                onChange={(e) => setDefaultTag(e.target.value)}
+                placeholder="2026.4.22"
+                className="w-full px-3 py-2 rounded-lg border border-border bg-surface-2 text-text-primary text-sm font-mono focus:outline-none focus:border-text-secondary"
+              />
+              <p className="text-xs text-text-muted mt-1">{t("emptyHint")}</p>
+            </div>
+
+            {defaultError && (
+              <div className="text-xs text-red-400 bg-red-400/10 border border-red-400/20 rounded-lg px-3 py-2">
+                {defaultError}
+              </div>
+            )}
+            {defaultSaved && !defaultError && (
+              <div className="text-xs text-success bg-success/10 border border-success/20 rounded-lg px-3 py-2">
+                {t("defaultSaved")}
+              </div>
+            )}
+
+            <div className="flex justify-end">
+              <button
+                type="submit"
+                disabled={savingDefault}
+                className="text-sm font-medium px-4 py-2 rounded-lg bg-accent text-white hover:bg-accent/90 transition-colors disabled:opacity-50"
+              >
+                {savingDefault ? tCommon("loading") : t("saveDefault")}
+              </button>
+            </div>
+          </form>
+        </Card>
+      </section>
+
+      {/* Tenant overrides */}
+      <section className="animate-in animate-in-delay-2">
+        <h2 className="text-xs font-semibold uppercase tracking-wider text-text-muted mb-3">
+          {t("overridesSection")}
+        </h2>
+        <Card>
+          {tenants.length === 0 ? (
+            <p className="text-sm text-text-secondary text-center py-6">
+              {t("noTenants")}
+            </p>
+          ) : (
+            <div className="space-y-2">
+              {tenants.map((tn) => (
+                <TenantOverrideRow
+                  key={tn.name}
+                  tenant={tn}
+                  platformDefault={defaults}
+                  onChanged={() => router.refresh()}
+                />
+              ))}
+            </div>
+          )}
+        </Card>
+      </section>
+    </div>
+  );
+}
+
+/**
+ * Single row in the tenants table. Collapsed by default; click to
+ * expand the inline editor.
+ */
+function TenantOverrideRow({
+  tenant,
+  platformDefault,
+  onChanged,
+}: {
+  tenant: TenantRow;
+  platformDefault: OpenClawDefaults;
+  onChanged: () => void;
+}) {
+  const t = useTranslations("openclawAdmin");
+  const tCommon = useTranslations("common");
+
+  const [expanded, setExpanded] = useState(false);
+  const [tag, setTag] = useState(tenant.override?.tag ?? "");
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState("");
+
+  const submit = async (clear = false) => {
+    setSaving(true);
+    setError("");
+    try {
+      const res = await fetch(
+        `/api/admin/tenants/${encodeURIComponent(tenant.name)}/openclaw-image`,
+        {
+          method: "PATCH",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(clear ? {} : { tag: tag.trim() }),
+        }
+      );
+      if (!res.ok) {
+        const data = await res.json().catch(() => ({}));
+        throw new Error(data.error || t("saveFailed"));
+      }
+      setExpanded(false);
+      onChanged();
+    } catch (e: any) {
+      setError(e.message);
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const effective = tenant.override?.tag
+    ? tenant.override.tag
+    : platformDefault.defaultTag || t("builtinFallback");
+
+  return (
+    <div className="rounded-lg border border-border bg-surface-2 overflow-hidden">
+      <button
+        type="button"
+        onClick={() => setExpanded((v) => !v)}
+        className="w-full flex items-center justify-between px-4 py-3 text-left hover:bg-surface-1 transition-colors"
+      >
+        <div className="min-w-0 flex-1">
+          <div className="font-medium text-text-primary truncate">
+            {tenant.displayName}
+          </div>
+          <div className="text-xs text-text-muted font-mono truncate mt-0.5">
+            {tenant.name}
+          </div>
+        </div>
+        <div className="text-right ml-4 min-w-0">
+          {tenant.override ? (
+            <span className="inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-full bg-amber-400/15 text-amber-400 border border-amber-400/20">
+              {t("statusOverridden")}
+            </span>
+          ) : (
+            <span className="inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-full bg-blue-400/15 text-blue-400 border border-blue-400/20">
+              {t("statusFollowsDefault")}
+            </span>
+          )}
+          <div className="text-xs text-text-muted font-mono truncate max-w-[260px] mt-1">
+            {effective}
+          </div>
+        </div>
+      </button>
+
+      {expanded && (
+        <div className="px-4 pb-4 pt-1 border-t border-border bg-surface-1">
+          <div className="mb-3">
+            <label className="block text-xs uppercase tracking-wider text-text-muted mb-1">
+              {t("fieldTag")}
+            </label>
+            <input
+              type="text"
+              value={tag}
+              onChange={(e) => setTag(e.target.value)}
+              placeholder={
+                platformDefault.defaultTag
+                  ? `${t("defaultPrefix")} ${platformDefault.defaultTag}`
+                  : ""
+              }
+              className="w-full px-3 py-2 rounded-lg border border-border bg-surface-2 text-text-primary text-sm font-mono focus:outline-none focus:border-text-secondary"
+            />
+          </div>
+
+          {error && (
+            <div className="text-xs text-red-400 bg-red-400/10 border border-red-400/20 rounded-lg px-3 py-2 mb-3">
+              {error}
+            </div>
+          )}
+
+          <div className="flex flex-wrap gap-2 justify-end">
+            {tenant.override && (
+              <button
+                type="button"
+                onClick={() => submit(true)}
+                disabled={saving}
+                className="text-xs px-3 py-1.5 rounded-lg border border-border text-text-secondary hover:text-text-primary transition-colors disabled:opacity-50"
+              >
+                {saving ? tCommon("loading") : t("clearOverride")}
+              </button>
+            )}
+            <button
+              type="button"
+              onClick={() => submit(false)}
+              disabled={saving || !tag.trim()}
+              className="text-xs px-3 py-1.5 rounded-lg bg-accent text-white hover:bg-accent/90 transition-colors disabled:opacity-50"
+            >
+              {saving ? tCommon("loading") : t("saveOverride")}
+            </button>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

src/components/admin/skills/pending-skill-requests.tsx

@@ -0,0 +1,204 @@
+"use client";
+
+import { useState, Fragment } from "react";
+import { useRouter } from "next/navigation";
+import { useTranslations } from "next-intl";
+import { Card } from "@/components/ui/card";
+import type { SkillActivationRequest } from "@/types";
+
+interface RowData extends SkillActivationRequest {
+  skillName: string;
+  companyName: string | null;
+}
+
+interface Props {
+  initialRows: RowData[];
+}
+
+/**
+ * Admin queue table. Each row has Approve and Reject buttons.
+ * Reject opens an inline reason input that must be filled before
+ * the call goes through (the API also enforces this — empty
+ * reasons are 400'd server-side).
+ *
+ * Actions hit the admin API endpoints, then router.refresh() to
+ * re-render the server component with the new state (the row
+ * disappears once flipped to approved/rejected).
+ */
+export function PendingSkillRequests({ initialRows }: Props) {
+  const t = useTranslations("adminSkills");
+  const router = useRouter();
+  const [busyId, setBusyId] = useState<string | null>(null);
+  const [error, setError] = useState("");
+  // Per-row open-reject-input state. Key = request id.
+  const [rejectingId, setRejectingId] = useState<string | null>(null);
+  const [reasonText, setReasonText] = useState("");
+
+  const approve = async (id: string) => {
+    setError("");
+    setBusyId(id);
+    try {
+      const res = await fetch(`/api/admin/skills/pending/${id}/approve`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({}),
+      });
+      if (!res.ok) {
+        const j = await res.json().catch(() => ({}));
+        throw new Error(j.error || `HTTP ${res.status}`);
+      }
+      router.refresh();
+    } catch (e: any) {
+      setError(e.message);
+    } finally {
+      setBusyId(null);
+    }
+  };
+
+  const reject = async (id: string) => {
+    if (!reasonText.trim()) {
+      setError(t("reasonRequired"));
+      return;
+    }
+    setError("");
+    setBusyId(id);
+    try {
+      const res = await fetch(`/api/admin/skills/pending/${id}/reject`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ reason: reasonText }),
+      });
+      if (!res.ok) {
+        const j = await res.json().catch(() => ({}));
+        throw new Error(j.error || `HTTP ${res.status}`);
+      }
+      setRejectingId(null);
+      setReasonText("");
+      router.refresh();
+    } catch (e: any) {
+      setError(e.message);
+    } finally {
+      setBusyId(null);
+    }
+  };
+
+  if (initialRows.length === 0) {
+    return (
+      <Card>
+        <p className="text-sm text-text-muted italic text-center py-6">
+          {t("emptyQueue")}
+        </p>
+      </Card>
+    );
+  }
+
+  return (
+    <Card>
+      {error && (
+        <div className="mb-3 p-3 rounded-md border border-error bg-error/10 text-sm text-error">
+          {error}
+        </div>
+      )}
+      <table className="w-full text-sm">
+        <thead className="text-xs text-text-muted text-left">
+          <tr>
+            <th className="pb-2">{t("requestedAtCol")}</th>
+            <th className="pb-2">{t("skillCol")}</th>
+            <th className="pb-2">{t("tenantCol")}</th>
+            <th className="pb-2">{t("orgCol")}</th>
+            <th className="pb-2 text-right">{t("actionsCol")}</th>
+          </tr>
+        </thead>
+        <tbody>
+          {initialRows.map((row) => (
+            <Fragment key={row.id}>
+              <tr className="border-t border-border align-top">
+                <td className="py-2 text-xs text-text-muted font-mono">
+                  {row.requestedAt.slice(0, 16).replace("T", " ")}
+                </td>
+                <td className="py-2">
+                  <div className="font-medium">{row.skillName}</div>
+                  <div className="text-xs text-text-muted font-mono">
+                    {row.skillId}
+                  </div>
+                </td>
+                <td className="py-2 font-mono text-xs">{row.tenantName}</td>
+                <td className="py-2">
+                  <div className="text-xs">{row.companyName ?? "—"}</div>
+                  <div className="text-xs text-text-muted font-mono">
+                    {row.zitadelOrgId.slice(0, 16)}…
+                  </div>
+                </td>
+                <td className="py-2 text-right">
+                  {rejectingId !== row.id && (
+                    <div className="flex justify-end gap-2">
+                      <button
+                        onClick={() => {
+                          setRejectingId(row.id);
+                          setReasonText("");
+                          setError("");
+                        }}
+                        disabled={busyId !== null}
+                        className="text-xs px-3 py-1.5 rounded-md border border-error text-error hover:bg-error/10 disabled:opacity-50"
+                      >
+                        {t("rejectBtn")}
+                      </button>
+                      <button
+                        onClick={() => approve(row.id)}
+                        disabled={busyId !== null}
+                        className="text-xs px-3 py-1.5 rounded-md bg-accent text-white disabled:opacity-50"
+                      >
+                        {busyId === row.id ? t("working") : t("approveBtn")}
+                      </button>
+                    </div>
+                  )}
+                </td>
+              </tr>
+              {rejectingId === row.id && (
+                <tr className="border-t border-border bg-surface-2">
+                  <td colSpan={5} className="py-3 px-3">
+                    <div className="flex flex-col gap-2">
+                      <label className="text-xs text-text-muted">
+                        {t("reasonLabel")}
+                      </label>
+                      <textarea
+                        value={reasonText}
+                        onChange={(e) => setReasonText(e.target.value)}
+                        rows={3}
+                        maxLength={1000}
+                        placeholder={t("reasonPlaceholder")}
+                        className="w-full px-3 py-2 rounded-md border border-border bg-surface-1 text-sm"
+                        autoFocus
+                      />
+                      <div className="flex justify-end gap-2">
+                        <button
+                          onClick={() => {
+                            setRejectingId(null);
+                            setReasonText("");
+                          }}
+                          disabled={busyId !== null}
+                          className="text-xs px-3 py-1.5 rounded-md border border-border disabled:opacity-50"
+                        >
+                          {t("cancel")}
+                        </button>
+                        <button
+                          onClick={() => reject(row.id)}
+                          disabled={busyId !== null || !reasonText.trim()}
+                          className="text-xs px-3 py-1.5 rounded-md bg-error text-white disabled:opacity-50"
+                        >
+                          {busyId === row.id
+                            ? t("working")
+                            : t("confirmRejectBtn")}
+                        </button>
+                      </div>
+                    </div>
+                  </td>
+                </tr>
+              )}
+            </Fragment>
+          ))}
+        </tbody>
+      </table>
+    </Card>
+  );
+}

src/components/billing/customer-invoice-detail.tsx

@@ -0,0 +1,160 @@
+import { useTranslations, useFormatter } from "next-intl";
+import { Card } from "@/components/ui/card";
+import type { Invoice, InvoiceLine } from "@/types";
+import { PayInvoiceButton } from "./pay-invoice-button";
+import { PaymentStatusBanner } from "./payment-status-banner";
+
+interface Props {
+  invoice: Invoice;
+  lines: InvoiceLine[];
+}
+
+const statusColors: Record<string, string> = {
+  open: "text-text-secondary bg-surface-3",
+  paid: "text-success bg-success/10",
+  overdue: "text-error bg-error/10",
+  void: "text-text-muted bg-surface-3",
+};
+
+/**
+ * Read-only invoice detail. Flat list of lines — no per-tenant
+ * grouping (one invoice per customer; the tenant context is
+ * already embedded in each line description).
+ *
+ * The download link points at /api/billing/invoices/[n]/pdf
+ * which serves the stored PDF blob inline. Customers using a
+ * link from their email will hit the same route via this page.
+ */
+export function CustomerInvoiceDetail({ invoice, lines }: Props) {
+  const t = useTranslations("customerBilling");
+  const fmt = useFormatter();
+
+  return (
+    <div className="space-y-6 animate-in">
+      <PaymentStatusBanner />
+      <div className="flex items-start justify-between gap-4 flex-wrap">
+        <div>
+          <div className="flex items-center gap-3 mb-2">
+            <h1 className="font-display text-2xl font-semibold">
+              {invoice.invoiceNumber}
+            </h1>
+            <span
+              className={`text-[10px] uppercase tracking-wider px-2 py-1 rounded-md font-semibold ${
+                statusColors[invoice.status] ?? "text-text-muted bg-surface-3"
+              }`}
+            >
+              {t(`status.${invoice.status}` as any)}
+            </span>
+          </div>
+          <p className="text-sm text-text-secondary">
+            {fmt.dateTime(new Date(invoice.periodStart), { dateStyle: "long" })}
+            <span className="text-text-muted mx-1">→</span>
+            {fmt.dateTime(new Date(invoice.periodEnd), { dateStyle: "long" })}
+          </p>
+        </div>
+        <div className="flex items-start gap-2 flex-wrap">
+          {/* Phase 4: Pay-with-card available for open + overdue.
+              Paid/void/draft/uncollectible hide the button — the
+              API also enforces this, so client-side hiding is just
+              for the visible affordance. */}
+          {(invoice.status === "open" || invoice.status === "overdue") && (
+            <PayInvoiceButton invoiceNumber={invoice.invoiceNumber} />
+          )}
+          <a
+            href={`/api/billing/invoices/${encodeURIComponent(invoice.invoiceNumber)}/pdf`}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="px-4 py-2 rounded-md bg-surface-3 hover:bg-surface-2 border border-border text-sm font-medium transition-colors"
+          >
+            {t("downloadPdf")}
+          </a>
+        </div>
+      </div>
+
+      <Card>
+        <div className="space-y-2 mb-4">
+          <div className="flex justify-between text-sm">
+            <span className="text-text-muted">{t("billedToLabel")}</span>
+            <span>{invoice.billingSnapshot.companyName}</span>
+          </div>
+          <div className="flex justify-between text-sm">
+            <span className="text-text-muted">{t("issuedAtLabel")}</span>
+            <span>
+              {fmt.dateTime(new Date(invoice.issuedAt), { dateStyle: "medium" })}
+            </span>
+          </div>
+          <div className="flex justify-between text-sm">
+            <span className="text-text-muted">{t("dueAtLabel")}</span>
+            <span>
+              {fmt.dateTime(new Date(invoice.dueAt), { dateStyle: "medium" })}
+            </span>
+          </div>
+          {invoice.status === "paid" && invoice.paidAt && (
+            <div className="flex justify-between text-sm">
+              <span className="text-text-muted">{t("paidAtLabel")}</span>
+              <span>
+                {fmt.dateTime(new Date(invoice.paidAt), { dateStyle: "medium" })}
+              </span>
+            </div>
+          )}
+        </div>
+      </Card>
+
+      <Card>
+        <table className="w-full text-sm">
+          <thead className="text-xs text-text-muted text-left">
+            <tr>
+              <th className="pb-2">{t("descriptionCol")}</th>
+              <th className="pb-2 text-right">{t("qtyCol")}</th>
+              <th className="pb-2 text-right">{t("unitCol")}</th>
+              <th className="pb-2 text-right">{t("amountCol")}</th>
+            </tr>
+          </thead>
+          <tbody>
+            {lines.map((ln) => (
+              <tr key={ln.id} className="border-t border-border align-top">
+                <td className="py-2">{ln.description}</td>
+                <td className="py-2 text-right font-mono text-xs">
+                  {ln.quantity}
+                  {ln.unitLabel ? ` ${ln.unitLabel}` : ""}
+                </td>
+                <td className="py-2 text-right font-mono text-xs">
+                  {ln.unitPriceChf.toFixed(2)}
+                </td>
+                <td className="py-2 text-right font-mono">
+                  {ln.amountChf.toFixed(2)}
+                </td>
+              </tr>
+            ))}
+          </tbody>
+          <tfoot>
+            <tr className="border-t border-border">
+              <td colSpan={3} className="pt-3 text-right text-text-muted">
+                {t("subtotalLabel")}
+              </td>
+              <td className="pt-3 text-right font-mono">
+                {invoice.subtotalChf.toFixed(2)}
+              </td>
+            </tr>
+            <tr>
+              <td colSpan={3} className="pt-1 text-right text-text-muted">
+                {t("vatLabel", { rate: invoice.vatRate.toFixed(2) })}
+              </td>
+              <td className="pt-1 text-right font-mono">
+                {invoice.vatAmountChf.toFixed(2)}
+              </td>
+            </tr>
+            <tr>
+              <td colSpan={3} className="pt-2 text-right font-semibold">
+                {t("totalLabel")}
+              </td>
+              <td className="pt-2 text-right font-mono font-semibold text-base">
+                CHF {invoice.totalChf.toFixed(2)}
+              </td>
+            </tr>
+          </tfoot>
+        </table>
+      </Card>
+    </div>
+  );
+}

src/components/billing/customer-invoice-list.tsx

@@ -0,0 +1,92 @@
+import { useTranslations, useFormatter } from "next-intl";
+import { Link } from "@/i18n/navigation";
+import { Card } from "@/components/ui/card";
+import type { Invoice } from "@/types";
+
+interface Props {
+  invoices: Invoice[];
+}
+
+const statusColors: Record<string, string> = {
+  open: "text-text-secondary bg-surface-3",
+  paid: "text-success bg-success/10",
+  overdue: "text-error bg-error/10",
+  void: "text-text-muted bg-surface-3 line-through",
+};
+
+/**
+ * Customer's invoice history table. Server component — gets a
+ * pre-fetched Invoice[] from /billing/page.tsx. Each row links
+ * to /billing/<invoice-number> for the full detail view.
+ *
+ * Columns: number, period, due date, total, status. Status is
+ * displayed with a colored badge so the customer can scan for
+ * outstanding ones at a glance.
+ */
+export function CustomerInvoiceList({ invoices }: Props) {
+  const t = useTranslations("customerBilling");
+  const fmt = useFormatter();
+
+  if (invoices.length === 0) {
+    return (
+      <Card>
+        <p className="text-sm text-text-muted italic text-center py-8">
+          {t("emptyHistory")}
+        </p>
+      </Card>
+    );
+  }
+
+  return (
+    <Card>
+      <table className="w-full text-sm">
+        <thead className="text-xs text-text-muted text-left">
+          <tr>
+            <th className="pb-2">{t("numberCol")}</th>
+            <th className="pb-2">{t("periodCol")}</th>
+            <th className="pb-2">{t("dueCol")}</th>
+            <th className="pb-2 text-right">{t("totalCol")}</th>
+            <th className="pb-2 text-right">{t("statusCol")}</th>
+          </tr>
+        </thead>
+        <tbody>
+          {invoices.map((inv) => (
+            <tr
+              key={inv.id}
+              className="border-t border-border hover:bg-surface-2 transition-colors"
+            >
+              <td className="py-2">
+                <Link
+                  href={`/billing/${inv.invoiceNumber}`}
+                  className="font-mono text-xs text-accent hover:underline"
+                >
+                  {inv.invoiceNumber}
+                </Link>
+              </td>
+              <td className="py-2 text-xs text-text-secondary">
+                {fmt.dateTime(new Date(inv.periodStart), { dateStyle: "medium" })}
+                <span className="text-text-muted mx-1">→</span>
+                {fmt.dateTime(new Date(inv.periodEnd), { dateStyle: "medium" })}
+              </td>
+              <td className="py-2 text-xs text-text-secondary">
+                {fmt.dateTime(new Date(inv.dueAt), { dateStyle: "medium" })}
+              </td>
+              <td className="py-2 text-right font-mono">
+                CHF {inv.totalChf.toFixed(2)}
+              </td>
+              <td className="py-2 text-right">
+                <span
+                  className={`text-[10px] uppercase tracking-wider px-2 py-1 rounded-md font-semibold ${
+                    statusColors[inv.status] ?? "text-text-muted bg-surface-3"
+                  }`}
+                >
+                  {t(`status.${inv.status}` as any)}
+                </span>
+              </td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </Card>
+  );
+}

src/components/billing/pay-invoice-button.tsx

@@ -0,0 +1,64 @@
+"use client";
+
+import { useState } from "react";
+import { useTranslations } from "next-intl";
+
+interface Props {
+  invoiceNumber: string;
+}
+
+/**
+ * Pay-with-card button. Posts to /api/billing/invoices/[n]/pay,
+ * which returns a Stripe Checkout Session URL; we redirect the
+ * browser there.
+ *
+ * The button is rendered only by the parent for status='open' or
+ * 'overdue' invoices — the API enforces this too, but pre-filtering
+ * UI-side keeps the dead state out of the customer's face.
+ */
+export function PayInvoiceButton({ invoiceNumber }: Props) {
+  const t = useTranslations("customerBilling");
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const onClick = async () => {
+    setBusy(true);
+    setError(null);
+    try {
+      const res = await fetch(
+        `/api/billing/invoices/${encodeURIComponent(invoiceNumber)}/pay`,
+        { method: "POST" }
+      );
+      const data = await res.json().catch(() => ({}));
+      if (!res.ok) {
+        throw new Error(data.error ?? `HTTP ${res.status}`);
+      }
+      if (!data.url) {
+        throw new Error("Payment session URL missing from response.");
+      }
+      // Hard navigation, not Next.js router — Stripe Checkout is a
+      // separate origin and the browser needs to fully leave our app.
+      window.location.href = data.url;
+    } catch (e: any) {
+      setError(e?.message ?? String(e));
+      setBusy(false);
+    }
+  };
+
+  return (
+    <div className="flex flex-col items-end gap-1">
+      <button
+        onClick={onClick}
+        disabled={busy}
+        className="px-4 py-2 rounded-md bg-accent text-white text-sm font-medium hover:bg-accent-dim transition-colors disabled:opacity-50 cursor-pointer"
+      >
+        {busy ? t("redirectingToStripe") : t("payWithCard")}
+      </button>
+      {error && (
+        <span className="text-xs text-error max-w-[260px] text-right">
+          {error}
+        </span>
+      )}
+    </div>
+  );
+}

src/components/billing/payment-status-banner.tsx

@@ -0,0 +1,67 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { useRouter } from "next/navigation";
+import { useTranslations } from "next-intl";
+
+/**
+ * Banner shown after a return from Stripe Checkout.
+ *
+ *   ?paid=1       → green success banner. The webhook may or may
+ *                   not have processed yet, so we phrase the message
+ *                   as "Payment received, status will update shortly"
+ *                   and don't claim the status is already paid. A
+ *                   light auto-refresh after a few seconds nudges
+ *                   the page to pick up the new status badge.
+ *
+ *   ?cancelled=1  → neutral grey banner: "Payment cancelled". The
+ *                   invoice stays in 'open' state.
+ *
+ * The banner cleans up the query params from the URL so a page
+ * reload doesn't repeat the message. We use router.replace() to
+ * keep history clean.
+ */
+export function PaymentStatusBanner() {
+  const router = useRouter();
+  const t = useTranslations("customerBilling");
+  const [state, setState] = useState<"paid" | "cancelled" | null>(null);
+
+  useEffect(() => {
+    const params = new URLSearchParams(window.location.search);
+    if (params.has("paid")) {
+      setState("paid");
+      // The webhook usually arrives before the browser redirect
+      // completes, so the page often renders with status='paid'
+      // on first load and this refresh is a no-op. In the rare
+      // case where it arrives slightly after, a short refresh
+      // picks up the status flip. 1.5s is comfortable for both.
+      const timer = setTimeout(() => {
+        router.refresh();
+      }, 1500);
+      // Strip the query string out of the URL.
+      const cleanUrl = window.location.pathname;
+      window.history.replaceState({}, "", cleanUrl);
+      return () => clearTimeout(timer);
+    } else if (params.has("cancelled")) {
+      setState("cancelled");
+      const cleanUrl = window.location.pathname;
+      window.history.replaceState({}, "", cleanUrl);
+    }
+  }, [router]);
+
+  if (state === "paid") {
+    return (
+      <div className="mb-4 p-3 rounded-md border border-success bg-success/10 text-sm text-success">
+        {t("paymentReceived")}
+      </div>
+    );
+  }
+  if (state === "cancelled") {
+    return (
+      <div className="mb-4 p-3 rounded-md border border-border bg-surface-2 text-sm text-text-secondary">
+        {t("paymentCancelled")}
+      </div>
+    );
+  }
+  return null;
+}

src/components/billing/running-total-widget.tsx

@@ -0,0 +1,162 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { useTranslations, useFormatter } from "next-intl";
+import { Link } from "@/i18n/navigation";
+import { Card } from "@/components/ui/card";
+import type { Invoice, InvoiceDraft } from "@/types";
+
+type CurrentResponse =
+  | { issued: Invoice }
+  | { draft: InvoiceDraft }
+  | { error: string; code?: string };
+
+/**
+ * Live running total for the current calendar month.
+ *
+ * Loads /api/billing/current on mount. Three result shapes:
+ *
+ *   - { issued }   — current-month invoice already exists; we
+ *                    link to it instead of showing a draft total.
+ *   - { draft }    — still accruing; show subtotal+VAT+total and
+ *                    a small line breakdown.
+ *   - { error }    — most likely the org has no billing config
+ *                    yet; show a friendly hint, not a stack trace.
+ *
+ * Client-side because the compute can take a second or two
+ * (LiteLLM + Threema HTTP calls) and we want a loading spinner.
+ * No polling — the page is static enough that an explicit
+ * "refresh" link is good enough if the user wants newer numbers.
+ */
+export function RunningTotalWidget() {
+  const t = useTranslations("customerBilling");
+  const fmt = useFormatter();
+  const [data, setData] = useState<CurrentResponse | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [refreshCounter, setRefreshCounter] = useState(0);
+
+  useEffect(() => {
+    let cancelled = false;
+    setLoading(true);
+    fetch("/api/billing/current")
+      .then(async (res) => {
+        const j = (await res.json()) as CurrentResponse;
+        if (!cancelled) setData(j);
+      })
+      .catch((e) => {
+        if (!cancelled) setData({ error: String(e), code: "FETCH_FAILED" });
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [refreshCounter]);
+
+  if (loading) {
+    return (
+      <Card>
+        <p className="text-sm text-text-muted italic py-4">{t("computing")}</p>
+      </Card>
+    );
+  }
+  if (!data || "error" in data) {
+    return (
+      <Card>
+        <p className="text-sm text-text-secondary py-2">
+          {data && "code" in data && data.code === "COMPUTE_FAILED"
+            ? t("noBillingConfig")
+            : t("currentPeriodError")}
+        </p>
+      </Card>
+    );
+  }
+  if ("issued" in data) {
+    const inv = data.issued;
+    return (
+      <Card>
+        <div className="flex items-start justify-between gap-4 flex-wrap">
+          <div>
+            <p className="text-xs text-text-muted">{t("currentInvoiceIssued")}</p>
+            <Link
+              href={`/billing/${inv.invoiceNumber}`}
+              className="font-mono text-sm text-accent hover:underline"
+            >
+              {inv.invoiceNumber}
+            </Link>
+          </div>
+          <div className="text-right">
+            <p className="text-xs text-text-muted">{t("totalLabel")}</p>
+            <p className="font-mono text-lg font-semibold">
+              CHF {inv.totalChf.toFixed(2)}
+            </p>
+          </div>
+        </div>
+      </Card>
+    );
+  }
+  // draft
+  const draft = data.draft;
+  const periodLabel = `${fmt.dateTime(new Date(draft.periodStart), {
+    dateStyle: "long",
+  })} → ${fmt.dateTime(new Date(draft.periodEnd), { dateStyle: "long" })}`;
+  return (
+    <Card>
+      <div className="flex items-start justify-between gap-4 flex-wrap mb-3">
+        <div>
+          <p className="text-xs text-text-muted">{t("accruedSoFar")}</p>
+          <p className="text-xs text-text-secondary">{periodLabel}</p>
+        </div>
+        <div className="text-right">
+          <p className="text-xs text-text-muted">{t("estimatedTotal")}</p>
+          <p className="font-mono text-2xl font-semibold text-accent">
+            CHF {draft.totalChf.toFixed(2)}
+          </p>
+          <button
+            onClick={() => setRefreshCounter((n) => n + 1)}
+            className="text-[10px] text-text-muted hover:text-text-secondary underline mt-1 cursor-pointer"
+          >
+            {t("refresh")}
+          </button>
+        </div>
+      </div>
+      {draft.lines.length > 0 && (
+        <details className="text-xs">
+          <summary className="cursor-pointer text-text-muted hover:text-text-secondary">
+            {t("breakdownToggle", { count: draft.lines.length })}
+          </summary>
+          <table className="w-full mt-2 text-xs">
+            <tbody>
+              {draft.lines.map((ln, i) => (
+                <tr key={i} className="border-t border-border">
+                  <td className="py-1 pr-2">{ln.description}</td>
+                  <td className="py-1 text-right font-mono">
+                    {ln.amountChf.toFixed(2)}
+                  </td>
+                </tr>
+              ))}
+              <tr className="border-t border-border">
+                <td className="py-1 pr-2 text-text-muted text-right">
+                  {t("subtotalLabel")}
+                </td>
+                <td className="py-1 text-right font-mono">
+                  {draft.subtotalChf.toFixed(2)}
+                </td>
+              </tr>
+              <tr>
+                <td className="py-1 pr-2 text-text-muted text-right">
+                  {t("vatLabel", { rate: draft.vatRate.toFixed(2) })}
+                </td>
+                <td className="py-1 text-right font-mono">
+                  {draft.vatAmountChf.toFixed(2)}
+                </td>
+              </tr>
+            </tbody>
+          </table>
+        </details>
+      )}
+      <p className="text-[10px] text-text-muted mt-3 italic">{t("draftNote")}</p>
+    </Card>
+  );
+}

src/components/channel-users/channel-users.tsx

@@ -3,14 +3,32 @@
 import { useState, useCallback } from "react";
 import { useTranslations } from "next-intl";
 import { useRouter } from "next/navigation";
+import { ThreemaQrModal } from "./threema-qr-modal";
 
 /** Maps channel IDs to the instructions for finding the user ID. */
 const CHANNEL_ID_HELP: Record<string, string> = {
   telegram: "telegramIdHelp",
   discord: "discordIdHelp",
-  email: "emailIdHelp",
+  threema: "threemaIdHelp",
+  // email entry dropped in the Phase A rework — IMAP/SMTP is handled by
+  // the `mail` skill (category=skill, not channel), so it never appears
+  // in `enabledChannels`. If a future channel is added to the catalog,
+  // give it an entry here so the help blurb renders.
 };
 
+/**
+ * Channels whose user list is managed through a dedicated endpoint
+ * instead of the generic PATCH /api/tenants/:name flow.
+ *
+ * Threema is the only one today — adding/removing a Threema ID has to
+ * synchronise with the central pieced-threema-gateway relay's `routes`
+ * table (uniqueness enforced there, not in K8s). The
+ * /api/tenants/:name/threema/routes endpoint owns that two-step
+ * coordination (relay first, then K8s, with compensation on K8s
+ * failure). Other channels just patch the K8s spec directly.
+ */
+const RELAY_MANAGED_CHANNELS = new Set(["threema"]);
+
 interface ChannelUsersProps {
   tenantName: string;
   /** Currently enabled channel packages (e.g. ["telegram", "discord"]) */
@@ -34,6 +52,14 @@ export function ChannelUsers({
   const [inputValues, setInputValues] = useState<Record<string, string>>({});
   const [channelUsers, setChannelUsers] =
     useState<Record<string, string[]>>(initialChannelUsers);
+  /** Which channel's QR helper modal is open, if any. */
+  const [showQrFor, setShowQrFor] = useState<string | null>(null);
+  /**
+   * Tracks channels for which we've already auto-opened the helper
+   * modal on this page load. Prevents the modal from re-popping every
+   * time the user refocuses the input after dismissing it.
+   */
+  const [autoOpened, setAutoOpened] = useState<Set<string>>(() => new Set());
 
   const updateChannelUsers = useCallback(
     async (updated: Record<string, string[]>) => {
@@ -60,6 +86,70 @@ export function ChannelUsers({
     [tenantName, router]
   );
 
+  /**
+   * Threema (and any future relay-managed channel) uses a dedicated
+   * endpoint that synchronises the central relay's routes table with
+   * the K8s spec atomically. We call it per-ID rather than sending the
+   * whole array because uniqueness is enforced ID-by-ID at the relay,
+   * and the error UX of "this ID is taken" is per-add.
+   */
+  const addToRelayChannel = useCallback(
+    async (channel: string, threemaId: string) => {
+      setSaving(true);
+      setError("");
+      try {
+        const res = await fetch(
+          `/api/tenants/${tenantName}/${channel}/routes`,
+          {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ threemaId }),
+          }
+        );
+        if (!res.ok) {
+          const data = await res.json().catch(() => ({}));
+          throw new Error(data.error || `Add failed (HTTP ${res.status})`);
+        }
+        setChannelUsers((prev) => {
+          const current = prev[channel] ?? [];
+          if (current.includes(threemaId)) return prev;
+          return { ...prev, [channel]: [...current, threemaId] };
+        });
+        router.refresh();
+      } catch (e: any) {
+        setError(e.message);
+      } finally {
+        setSaving(false);
+      }
+    },
+    [tenantName, router]
+  );
+
+  const removeFromRelayChannel = useCallback(
+    async (channel: string, threemaId: string) => {
+      setSaving(true);
+      setError("");
+      try {
+        const url = `/api/tenants/${tenantName}/${channel}/routes?threemaId=${encodeURIComponent(threemaId)}`;
+        const res = await fetch(url, { method: "DELETE" });
+        if (!res.ok) {
+          const data = await res.json().catch(() => ({}));
+          throw new Error(data.error || `Remove failed (HTTP ${res.status})`);
+        }
+        setChannelUsers((prev) => {
+          const current = prev[channel] ?? [];
+          return { ...prev, [channel]: current.filter((id) => id !== threemaId) };
+        });
+        router.refresh();
+      } catch (e: any) {
+        setError(e.message);
+      } finally {
+        setSaving(false);
+      }
+    },
+    [tenantName, router]
+  );
+
   const handleAdd = useCallback(
     (channel: string) => {
       const userId = inputValues[channel]?.trim();
@@ -71,18 +161,27 @@ export function ChannelUsers({
         return;
       }
 
+      setInputValues((prev) => ({ ...prev, [channel]: "" }));
+
+      if (RELAY_MANAGED_CHANNELS.has(channel)) {
+        void addToRelayChannel(channel, userId);
+      } else {
         const updated = {
           ...channelUsers,
           [channel]: [...current, userId],
         };
-      setInputValues((prev) => ({ ...prev, [channel]: "" }));
         updateChannelUsers(updated);
+      }
     },
-    [channelUsers, inputValues, updateChannelUsers, t]
+    [channelUsers, inputValues, updateChannelUsers, addToRelayChannel, t]
   );
 
   const handleRemove = useCallback(
     (channel: string, userId: string) => {
+      if (RELAY_MANAGED_CHANNELS.has(channel)) {
+        void removeFromRelayChannel(channel, userId);
+        return;
+      }
       const current = channelUsers[channel] || [];
       const updated = {
         ...channelUsers,
@@ -90,7 +189,7 @@ export function ChannelUsers({
       };
       updateChannelUsers(updated);
     },
-    [channelUsers, updateChannelUsers]
+    [channelUsers, updateChannelUsers, removeFromRelayChannel]
   );
 
   if (enabledChannels.length === 0) return null;
@@ -134,6 +233,39 @@ export function ChannelUsers({
               </span>
             </div>
 
+            {channel === "threema" && (
+              <div className="mb-3 flex flex-col sm:flex-row gap-3 items-start sm:items-center justify-between bg-accent/5 border border-accent/30 rounded-lg p-3">
+                <div className="flex items-start gap-2 flex-1">
+                  <svg
+                    className="w-4 h-4 mt-0.5 text-accent flex-shrink-0"
+                    fill="none"
+                    viewBox="0 0 24 24"
+                    stroke="currentColor"
+                    strokeWidth="2"
+                    aria-hidden="true"
+                  >
+                    <path
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      d="M3 4a1 1 0 011-1h4a1 1 0 011 1v4a1 1 0 01-1 1H4a1 1 0 01-1-1V4zM15 4a1 1 0 011-1h4a1 1 0 011 1v4a1 1 0 01-1 1h-4a1 1 0 01-1-1V4zM3 16a1 1 0 011-1h4a1 1 0 011 1v4a1 1 0 01-1 1H4a1 1 0 01-1-1v-4zM13 13h3v3h-3zM18 13h3v3h-3zM13 18h3v3h-3zM18 18h3v3h-3z"
+                    />
+                  </svg>
+                  <div className="text-xs text-text-secondary leading-relaxed">
+                    <p className="font-medium text-text-primary mb-0.5">
+                      {t("threemaSetup.bannerTitle")}
+                    </p>
+                    <p>{t("threemaSetup.bannerBody")}</p>
+                  </div>
+                </div>
+                <button
+                  onClick={() => setShowQrFor("threema")}
+                  className="self-stretch sm:self-auto px-3 py-2 text-xs font-medium bg-accent text-surface-0 rounded-lg hover:bg-accent-dim transition-colors whitespace-nowrap cursor-pointer shadow-lg shadow-accent/20"
+                >
+                  {t("threemaSetup.bannerButton")}
+                </button>
+              </div>
+            )}
+
             {helpKey && (
               <p className="text-xs text-text-secondary bg-surface-1 border border-border rounded-lg p-3 mb-3 whitespace-pre-line">
                 {t(helpKey)}
@@ -176,6 +308,17 @@ export function ChannelUsers({
                       [channel]: e.target.value,
                     }))
                   }
+                  onFocus={() => {
+                    // For threema specifically, open the QR helper the
+                    // first time the user clicks into the input on this
+                    // page load. We don't repeat after dismiss — the
+                    // "Show QR" button next to the channel name covers
+                    // re-opens on demand.
+                    if (channel === "threema" && !autoOpened.has("threema")) {
+                      setShowQrFor("threema");
+                      setAutoOpened((prev) => new Set(prev).add("threema"));
+                    }
+                  }}
                   onKeyDown={(e) => {
                     if (e.key === "Enter") handleAdd(channel);
                   }}
@@ -194,6 +337,11 @@ export function ChannelUsers({
           </div>
         );
       })}
+
+      <ThreemaQrModal
+        open={showQrFor === "threema"}
+        onClose={() => setShowQrFor(null)}
+      />
     </div>
   );
 }

src/components/channel-users/threema-qr-modal.tsx

@@ -0,0 +1,82 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { useEffect } from "react";
+import { THREEMA_GATEWAY } from "@/lib/threema-gateway-config";
+
+interface ThreemaQrModalProps {
+  open: boolean;
+  onClose: () => void;
+}
+
+/**
+ * On-demand modal showing the QR for adding the assistant on Threema.
+ * Triggered by the "Show QR" button in the threema channel card and
+ * closes on overlay click, ESC, or the close button.
+ *
+ * Uses a plain <img> not next/image — image optimization adds nothing
+ * for a 57KB static PNG and removes a potential source of rendering
+ * bugs in the Next.js standalone build.
+ */
+export function ThreemaQrModal({ open, onClose }: ThreemaQrModalProps) {
+  const t = useTranslations("channelUsers.threemaSetup");
+
+  useEffect(() => {
+    if (!open) return;
+    function onKey(e: KeyboardEvent) {
+      if (e.key === "Escape") onClose();
+    }
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [open, onClose]);
+
+  if (!open) return null;
+
+  return (
+    <div
+      onClick={onClose}
+      className="fixed inset-0 z-50 flex items-center justify-center bg-black/60 backdrop-blur-sm p-4"
+    >
+      <div
+        onClick={(e) => e.stopPropagation()}
+        className="w-full max-w-md bg-surface-1 border border-border rounded-2xl p-6 shadow-2xl shadow-black/40 space-y-4"
+      >
+        <div className="flex items-start justify-between">
+          <h3 className="text-base font-semibold text-text-primary">
+            {t("title")}
+          </h3>
+          <button
+            onClick={onClose}
+            className="text-text-muted hover:text-text-primary text-xl leading-none"
+            aria-label="Close"
+          >
+            ×
+          </button>
+        </div>
+
+        <div className="flex justify-center">
+          <div className="bg-white p-3 rounded-md">
+            {/* eslint-disable-next-line @next/next/no-img-element */}
+            <img
+              src={THREEMA_GATEWAY.qrCodePath}
+              alt={t("qrAlt", { gateway: THREEMA_GATEWAY.displayName })}
+              width={220}
+              height={220}
+              style={{ display: "block" }}
+            />
+          </div>
+        </div>
+
+        <p className="text-center text-xs text-text-muted font-mono">
+          {THREEMA_GATEWAY.displayName}
+        </p>
+
+        <ol className="list-decimal list-inside text-xs text-text-secondary space-y-1.5">
+          <li>{t("step1")}</li>
+          <li>{t("step2")}</li>
+          <li>{t("step3")}</li>
+        </ol>
+      </div>
+    </div>
+  );
+}

src/components/dashboard/budget-editable-card.tsx

@@ -0,0 +1,275 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import { useTranslations } from "next-intl";
+import { Modal } from "@/components/ui/modal";
+
+/**
+ * Format remaining budget as CHF. Same adaptive precision rule as the
+ * usage display: 2 decimals for amounts ≥ 1, 4 for smaller values
+ * so per-request residuals don't round to zero. The currency comes
+ * from LiteLLM via our CHF pricing config — see chf() in
+ * usage-display.tsx for the full reasoning.
+ */
+function formatRemaining(n: number): string {
+  const decimals = Math.abs(n) >= 1 ? 2 : 4;
+  return `CHF ${n.toFixed(decimals)}`;
+}
+
+interface Props {
+  tenantName: string;
+  maxBudget: number | null;
+  remaining: number | null;
+  budgetDuration: string | null;
+  /** Called after a successful save so the parent re-fetches usage. */
+  onSaved: () => void;
+}
+
+/**
+ * Clickable Budget StatCard with edit modal (Feature 7).
+ *
+ * The display side mirrors the read-only StatCard layout exactly so
+ * the grid stays uniform. The "click to edit" hint is implicit via
+ * hover state — a "Set" / "Edit" link in the corner would be louder
+ * but adds clutter on a tile that's already busy. Customers who
+ * mouse over discover it.
+ *
+ * Important UX note shown in the modal: the budget is org-scoped,
+ * not per-tenant. All tenants in the same ZITADEL org share the
+ * underlying LiteLLM team. Without that callout, a customer with
+ * multiple tenants might think they're capping just one.
+ */
+export function BudgetEditableCard({
+  tenantName,
+  maxBudget,
+  remaining,
+  budgetDuration,
+  onSaved,
+}: Props) {
+  const t = useTranslations("usage");
+  const tCommon = useTranslations("common");
+  const [open, setOpen] = useState(false);
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState("");
+
+  // Form state. Mode = "unlimited" | "capped". When unlimited, the
+  // duration dropdown is hidden because LiteLLM's reset cadence is
+  // meaningless without a cap.
+  const [mode, setMode] = useState<"unlimited" | "capped">(
+    maxBudget !== null ? "capped" : "unlimited"
+  );
+  const [budgetInput, setBudgetInput] = useState<string>(
+    maxBudget !== null ? String(maxBudget) : ""
+  );
+  const [duration, setDuration] = useState<"30d" | "1mo" | "1y">(
+    (budgetDuration === "30d" ||
+      budgetDuration === "1mo" ||
+      budgetDuration === "1y")
+      ? budgetDuration
+      : "1mo"
+  );
+
+  // Reset form when modal opens — picks up any change made elsewhere
+  // (e.g. another browser tab) since this card was last re-rendered.
+  useEffect(() => {
+    if (open) {
+      setMode(maxBudget !== null ? "capped" : "unlimited");
+      setBudgetInput(maxBudget !== null ? String(maxBudget) : "");
+      setDuration(
+        (budgetDuration === "30d" ||
+          budgetDuration === "1mo" ||
+          budgetDuration === "1y")
+          ? budgetDuration
+          : "1mo"
+      );
+      setError("");
+    }
+  }, [open, maxBudget, budgetDuration]);
+
+  const onSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setSaving(true);
+    setError("");
+    try {
+      let body: { maxBudget: number | null; budgetDuration: string | null };
+      if (mode === "unlimited") {
+        body = { maxBudget: null, budgetDuration: null };
+      } else {
+        const parsed = parseFloat(budgetInput);
+        if (!Number.isFinite(parsed) || parsed <= 0) {
+          throw new Error(t("budgetInvalid"));
+        }
+        body = { maxBudget: parsed, budgetDuration: duration };
+      }
+      const res = await fetch(
+        `/api/tenants/${encodeURIComponent(tenantName)}/budget`,
+        {
+          method: "PATCH",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(body),
+        }
+      );
+      if (!res.ok) {
+        const data = await res.json().catch(() => ({}));
+        throw new Error(data.error || t("budgetSaveFailed"));
+      }
+      setOpen(false);
+      onSaved();
+    } catch (e: any) {
+      setError(e.message);
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  return (
+    <>
+      <button
+        type="button"
+        onClick={() => setOpen(true)}
+        className="bg-surface-1 border border-accent/40 rounded-xl p-4 text-left hover:border-accent transition-colors cursor-pointer focus:outline-none focus:ring-2 focus:ring-accent/40 group block w-full"
+      >
+        <div className="text-xs text-text-muted mb-1 flex items-center justify-between">
+          <span>{t("budget")}</span>
+          <span className="text-[10px] text-accent inline-flex items-center gap-1">
+            {/* Pencil icon — unambiguous "this is editable" affordance.
+                Visible at all times (was hover-only before, which on
+                touch devices and at-a-glance scanning gave no
+                indication the card was clickable). */}
+            <svg
+              xmlns="http://www.w3.org/2000/svg"
+              width="11"
+              height="11"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="2"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              aria-hidden="true"
+            >
+              <path d="M17 3a2.85 2.83 0 1 1 4 4L7.5 20.5 2 22l1.5-5.5Z" />
+            </svg>
+            {t("budgetEdit")}
+          </span>
+        </div>
+        <div className="text-lg font-semibold text-text-primary tabular-nums">
+          {remaining !== null ? formatRemaining(remaining) : t("noLimit")}
+        </div>
+      </button>
+
+      <Modal open={open} onClose={() => setOpen(false)} ariaLabel={t("budgetEditTitle")}>
+        <h3 className="font-display text-lg font-semibold text-text-primary mb-2">
+          {t("budgetEditTitle")}
+        </h3>
+        <p className="text-sm text-text-secondary mb-5">
+          {t("budgetEditDescription")}
+        </p>
+
+          <form onSubmit={onSubmit} className="space-y-4">
+            {/* Mode toggle: unlimited vs capped. Two radios are
+                clearer than a single "max" field where 0 means
+                unlimited (which would conflict with our zod
+                validation requiring positive). */}
+            <div className="space-y-2">
+              <label className="flex items-start gap-2 text-sm text-text-primary cursor-pointer">
+                <input
+                  type="radio"
+                  name="budget-mode"
+                  checked={mode === "unlimited"}
+                  onChange={() => setMode("unlimited")}
+                  className="mt-1"
+                />
+                <span>
+                  <span className="font-medium">{t("budgetModeUnlimited")}</span>
+                  <span className="block text-xs text-text-muted">
+                    {t("budgetModeUnlimitedDescription")}
+                  </span>
+                </span>
+              </label>
+              <label className="flex items-start gap-2 text-sm text-text-primary cursor-pointer">
+                <input
+                  type="radio"
+                  name="budget-mode"
+                  checked={mode === "capped"}
+                  onChange={() => setMode("capped")}
+                  className="mt-1"
+                />
+                <span>
+                  <span className="font-medium">{t("budgetModeCapped")}</span>
+                  <span className="block text-xs text-text-muted">
+                    {t("budgetModeCappedDescription")}
+                  </span>
+                </span>
+              </label>
+            </div>
+
+            {mode === "capped" && (
+              <div className="grid grid-cols-1 sm:grid-cols-2 gap-3 pt-2">
+                <div>
+                  <label className="block text-xs uppercase tracking-wider text-text-muted mb-1">
+                    {t("budgetAmount")} <span className="text-red-400">*</span>
+                  </label>
+                  <div className="relative">
+                    <span className="absolute left-3 top-2 text-sm text-text-muted font-medium">
+                      CHF
+                    </span>
+                    <input
+                      type="number"
+                      min="0.01"
+                      max="1000000"
+                      step="0.01"
+                      required
+                      value={budgetInput}
+                      onChange={(e) => setBudgetInput(e.target.value)}
+                      className="w-full pl-12 pr-3 py-2 rounded-lg border border-border bg-surface-2 text-text-primary text-sm focus:outline-none focus:border-text-secondary"
+                    />
+                  </div>
+                </div>
+                <div>
+                  <label className="block text-xs uppercase tracking-wider text-text-muted mb-1">
+                    {t("budgetResetCadence")}
+                  </label>
+                  <select
+                    value={duration}
+                    onChange={(e) =>
+                      setDuration(e.target.value as "30d" | "1mo" | "1y")
+                    }
+                    className="w-full px-3 py-2 rounded-lg border border-border bg-surface-2 text-text-primary text-sm focus:outline-none focus:border-text-secondary"
+                  >
+                    <option value="30d">{t("budgetCadence_30d")}</option>
+                    <option value="1mo">{t("budgetCadence_1mo")}</option>
+                    <option value="1y">{t("budgetCadence_1y")}</option>
+                  </select>
+                </div>
+              </div>
+            )}
+
+            {error && (
+              <div className="text-xs text-red-400 bg-red-400/10 border border-red-400/20 rounded-lg px-3 py-2">
+                {error}
+              </div>
+            )}
+
+            <div className="flex justify-end gap-2 pt-2">
+              <button
+                type="button"
+                onClick={() => setOpen(false)}
+                disabled={saving}
+                className="text-sm px-4 py-2 rounded-lg border border-border text-text-secondary hover:text-text-primary transition-colors"
+              >
+                {tCommon("cancel")}
+              </button>
+              <button
+                type="submit"
+                disabled={saving}
+                className="text-sm px-4 py-2 rounded-lg bg-accent text-white hover:bg-accent/90 transition-colors disabled:opacity-50"
+              >
+                {saving ? tCommon("loading") : tCommon("save")}
+              </button>
+            </div>
+          </form>
+        </Modal>
+    </>
+  );
+}

src/components/dashboard/usage-display.tsx

@@ -2,6 +2,7 @@
 
 import { useTranslations } from "next-intl";
 import { useEffect, useState, useCallback } from "react";
+import { BudgetEditableCard } from "@/components/dashboard/budget-editable-card";
 
 interface DailyUsage {
   date: string;
@@ -18,7 +19,17 @@ interface UsageData {
     totalSpend: number;
     requestCount: number;
   };
-  budget: { maxBudget: number | null; spend: number; remaining: number | null };
+  budget: {
+    maxBudget: number | null;
+    spend: number;
+    remaining: number | null;
+    /**
+     * Feature 7: budget reset cadence as stored on LiteLLM.
+     * Strings: "30d" / "1mo" / "1y" / null (no reset). UI maps these
+     * to user-friendly labels.
+     */
+    budgetDuration: string | null;
+  };
   rateLimits: { rpm: number | null; tpm: number | null };
   dailyUsage: DailyUsage[];
 }
@@ -29,8 +40,31 @@ function fmt(n: number): string {
   return n.toString();
 }
 
-function usd(n: number): string {
-  return `$${n.toFixed(4)}`;
+/**
+ * Format a numeric amount as CHF.
+ *
+ * Note on currency labelling: LiteLLM stores raw cost numbers it
+ * receives from upstream (OpenAI/Anthropic), which originate as USD.
+ * The PieCed pricing config (Slice 5) converts those numbers to
+ * CHF before LiteLLM persists them, so the values flowing through
+ * here are already CHF amounts. We label them as such in the UI;
+ * "USD" or "$" anywhere in the customer-facing experience would
+ * be misleading.
+ *
+ * Precision is adaptive:
+ *   - Amounts ≥ 1 CHF: 2 decimals (typical money formatting).
+ *   - Smaller amounts:  4 decimals — per-request inference costs are
+ *                       routinely sub-rappen, and rounding to 2dp
+ *                       would render CHF 0.0042 as "CHF 0.00",
+ *                       which obscures real costs from customers
+ *                       looking at the daily breakdown.
+ *
+ * This is a customer-facing display helper; for storage and
+ * comparisons keep using the raw number.
+ */
+function chf(n: number): string {
+  const decimals = Math.abs(n) >= 1 ? 2 : 4;
+  return `CHF ${n.toFixed(decimals)}`;
 }
 
 function getCurrentMonth(): string {
@@ -69,7 +103,7 @@ function UsageChart({ data }: { data: DailyUsage[] }) {
           const x = i * (barW + 2);
           return (
             <g key={d.date}>
-              <title>{d.date}: {fmt(d.inputTokens)} in / {fmt(d.outputTokens)} out — {usd(d.spend)}</title>
+              <title>{d.date}: {fmt(d.inputTokens)} in / {fmt(d.outputTokens)} out — {chf(d.spend)}</title>
               <rect x={x} y={h - totalH} width={barW} height={totalH - inputH} rx={1} fill="var(--color-accent)" opacity={0.3} />
               <rect x={x} y={h - inputH} width={barW} height={inputH} rx={1} fill="var(--color-accent)" opacity={0.7} />
               {i % 7 === 0 && (
@@ -113,10 +147,18 @@ export function UsageDisplay({
   tenant,
   teamId,
   keyAlias,
+  canEditBudget = false,
 }: {
   tenant?: string | null;
   teamId?: string | null;
   keyAlias?: string | null;
+  /**
+   * Feature 7: when true, the Budget StatCard becomes clickable and
+   * opens the budget editor. Off by default — owners and platform
+   * admins get it on; `user` role customers see the budget read-only.
+   * Server component decides this via canMutate(user).
+   */
+  canEditBudget?: boolean;
 }) {
   const t = useTranslations("usage");
   const [month, setMonth] = useState(getCurrentMonth);
@@ -185,11 +227,25 @@ export function UsageDisplay({
           <div className="grid grid-cols-2 md:grid-cols-4 gap-3">
             <StatCard label={t("inputTokens")} value={fmt(data.currentPeriod.inputTokens)} />
             <StatCard label={t("outputTokens")} value={fmt(data.currentPeriod.outputTokens)} />
-            <StatCard label={t("totalSpend")} value={usd(data.currentPeriod.totalSpend)} accent />
+            <StatCard label={t("totalSpend")} value={chf(data.currentPeriod.totalSpend)} accent />
+            {canEditBudget && tenant ? (
+              <BudgetEditableCard
+                tenantName={tenant}
+                maxBudget={data.budget.maxBudget}
+                remaining={data.budget.remaining}
+                budgetDuration={data.budget.budgetDuration}
+                onSaved={fetchUsage}
+              />
+            ) : (
               <StatCard
                 label={t("budget")}
-              value={data.budget.remaining !== null ? usd(data.budget.remaining) : t("noLimit")}
+                value={
+                  data.budget.remaining !== null
+                    ? chf(data.budget.remaining)
+                    : t("noLimit")
+                }
               />
+            )}
           </div>
 
           <div className="bg-surface-1 border border-border rounded-xl p-5">

src/components/layout/nav-shell.tsx

@@ -74,6 +74,31 @@ function NavBar() {
                   {t("settings")}
                 </NavLink>
               )}
+            {/* Phase 3: Billing visible to anyone signed in. The
+                page is org-scoped server-side — non-owner members
+                see the same invoice history their owner does, but
+                actions like "configure billing details" are gated
+                separately on the settings page. Personal accounts
+                see their own (single-tenant) invoices. */}
+            {user && (
+              <NavLink
+                href="/billing"
+                active={pathname.startsWith("/billing")}
+              >
+                {t("billing")}
+              </NavLink>
+            )}
+            {/* Feature 5: Support is available to every signed-in
+                user. Customers see their own tickets only; platform
+                admins see the queue. */}
+            {user && (
+              <NavLink
+                href="/support"
+                active={pathname.startsWith("/support")}
+              >
+                {t("support")}
+              </NavLink>
+            )}
             {user?.isPlatform && (
               <NavLink href="/admin" active={pathname === "/admin"}>
                 {t("admin")}

src/components/onboarding/wizard.tsx

@@ -3,7 +3,7 @@
 import { useState, useCallback, useEffect, useRef } from "react";
 import { useTranslations } from "next-intl";
 import { Card } from "@/components/ui/card";
-import { PACKAGE_CATALOG, type PackageDef } from "@/lib/packages";
+import { PACKAGE_CATALOG, DEFAULT_PACKAGE_IDS, type PackageDef } from "@/lib/packages";
 import { isPersonalOrgName, displayOrgNameFor } from "@/lib/personal-org";
 import {
   configureStepSchema,
@@ -69,6 +69,7 @@ translation, and general question answering.
 `;
 
 const CATEGORIES = [
+  { key: "core" as const, labelKey: "categories.core" },
   { key: "channel" as const, labelKey: "categories.channels" },
   { key: "skill" as const, labelKey: "categories.skills" },
 ] as const;
@@ -198,7 +199,13 @@ export function OnboardingWizard({
       agentName: "Assistant",
       soulMd: FALLBACK_SOUL.replace("{company}", displayOrgName),
       agentsMd: FALLBACK_AGENTS,
-      packages: [] as string[],
+      // CORE defaults: heartbeat + cron + active-memory pre-selected so
+      // the assistant can be proactive, run scheduled tasks, and recall
+      // stable context out of the box. Customers can untoggle any of
+      // them before submitting. core-voice is fully wired (Phase B)
+      // but stays unselected — opt-in keeps audio spend predictable
+      // for tenants who don't intend to use voice channels.
+      packages: [...DEFAULT_PACKAGE_IDS] as string[],
       billingAddress: {
         // For personal accounts, leave the company field empty — it'll
         // appear on invoices. The user can still type something if they
@@ -691,7 +698,7 @@ export function OnboardingWizard({
                             <button
                               type="button"
                               onClick={() => togglePackage(pkg.id)}
-                              className="w-full flex items-center justify-between px-3 py-2.5 cursor-pointer hover:bg-surface-3/30 transition-colors"
+                              className="w-full flex items-center justify-between px-3 py-2.5 transition-colors cursor-pointer hover:bg-surface-3/30"
                             >
                               <div className="text-left">
                                 <span
@@ -1008,7 +1015,11 @@ export function OnboardingWizard({
                   }))
                 }
                 rows={3}
-                placeholder={t("billingNotesPlaceholder")}
+                placeholder={t(
+                  isPersonal
+                    ? "billingNotesPlaceholderPersonal"
+                    : "billingNotesPlaceholder"
+                )}
                 className="w-full px-3 py-2 bg-surface-2 border border-border rounded-lg text-sm text-text-primary placeholder:text-text-muted focus:outline-none focus:ring-1 focus:ring-accent focus:border-accent transition-colors resize-y"
               />
             </div>
@@ -1113,6 +1124,19 @@ export function OnboardingWizard({
                   </div>
                 }
               />
+              {/* Bug 35: VAT review row. Company customers see this so
+                  they can verify the VAT id they typed before submitting.
+                  Personal customers never see it — they don't have a
+                  VAT number, the form didn't ask, the review hides it. */}
+              {!isPersonal &&
+                config.billingAddress.vatNumber &&
+                config.billingAddress.vatNumber.trim().length > 0 && (
+                  <ReviewRow
+                    label={t("billingVatNumber")}
+                    value={config.billingAddress.vatNumber}
+                    mono
+                  />
+                )}
               <ReviewRow
                 label={t("reviewContactEmail")}
                 value={userEmail || ""}

src/components/packages/package-card.tsx

@@ -1,8 +1,14 @@
 "use client";
 
 import { useTranslations } from "next-intl";
+import { useRouter } from "next/navigation";
 import { useState } from "react";
 import type { PackageDef } from "@/lib/packages";
+import type {
+  SkillActivationRequest,
+  SkillPricing,
+} from "@/types";
+import { SkillCostDialog } from "./skill-cost-dialog";
 
 interface Props {
   pkg: PackageDef;
@@ -12,6 +18,18 @@ interface Props {
   onToggled: () => void;
   /** Slice 5: when false, the enable/disable button is hidden. */
   canEdit?: boolean;
+  /**
+   * Phase 2.5 — most recent non-terminal activation request for this
+   * skill on this tenant, if any. Drives the "Manual review pending"
+   * and "Activation rejected" inline states. Approved/withdrawn rows
+   * never reach the client side.
+   */
+  activationRequest?: SkillActivationRequest | null;
+  /**
+   * Phase 2.5 — pricing for this skill if it has any. Triggers the
+   * cost-disclosure dialog before enable.
+   */
+  pricing?: SkillPricing | null;
 }
 
 export function PackageCard({
@@ -21,15 +39,53 @@ export function PackageCard({
   tenantName,
   onToggled,
   canEdit = true,
+  activationRequest = null,
+  pricing = null,
 }: Props) {
   const t = useTranslations();
+  const router = useRouter();
   const [showModal, setShowModal] = useState(false);
   const [secrets, setSecrets] = useState<Record<string, string>>({});
   const [accepted, setAccepted] = useState(false);
   const [saving, setSaving] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  // Phase 2.5: cost-disclosure flow + activation-request flow.
+  const [showCostDialog, setShowCostDialog] = useState(false);
+  const isPriced =
+    (pricing?.dailyPriceChf ?? 0) > 0 || (pricing?.setupFeeChf ?? 0) > 0;
 
-  async function handleEnable() {
+  function handleEnable() {
+    // Phase 2.5: gate priced skills behind the cost-disclosure dialog.
+    // Confirm → proceedWithEnable. Cancel → bail.
+    if (isPriced) {
+      setError(null);
+      setShowCostDialog(true);
+      return;
+    }
+    void proceedWithEnable();
+  }
+
+  async function proceedWithEnable() {
+    if (pkg.customProvisioning) {
+      // Platform-side provisioning, then add to packages list.
+      setSaving(true);
+      setError(null);
+      try {
+        const provRes = await fetch(`/api/tenants/${tenantName}/${pkg.id}`, {
+          method: "POST",
+        });
+        if (!provRes.ok) {
+          const err = await provRes.json().catch(() => ({}));
+          throw new Error(err.error || `Provisioning failed (HTTP ${provRes.status})`);
+        }
+        await togglePackage(true);
+      } catch (e: any) {
+        setError(e.message);
+      } finally {
+        setSaving(false);
+      }
+      return;
+    }
     if (pkg.requiresSecrets) {
       setShowModal(true);
       setSecrets({});
@@ -40,6 +96,34 @@ export function PackageCard({
     await togglePackage(true);
   }
 
+  async function handleDisable() {
+    setSaving(true);
+    setError(null);
+    try {
+      if (pkg.customProvisioning) {
+        // Revoke platform-side credentials FIRST so the relay drops
+        // routes before the operator removes the channel from the
+        // OpenClaw config. Partial-success (token revoked, OpenBao
+        // delete failed) returns 503 with partial=true and we surface
+        // the error rather than continuing — the secret may still be
+        // valid in OpenBao and rolling back the relay revoke isn't
+        // possible (it cascaded to routes).
+        const deprovRes = await fetch(`/api/tenants/${tenantName}/${pkg.id}`, {
+          method: "DELETE",
+        });
+        if (!deprovRes.ok) {
+          const err = await deprovRes.json().catch(() => ({}));
+          throw new Error(err.error || `Deprovisioning failed (HTTP ${deprovRes.status})`);
+        }
+      }
+      await togglePackage(false);
+    } catch (e: any) {
+      setError(e.message);
+    } finally {
+      setSaving(false);
+    }
+  }
+
   async function togglePackage(enable: boolean) {
     setSaving(true);
     try {
@@ -64,6 +148,39 @@ export function PackageCard({
     }
   }
 
+  // Phase 2.5: withdraw a still-pending activation request. The
+  // request row flips to 'withdrawn' (server-side); router.refresh()
+  // re-renders the tenant page without the pending state, leaving
+  // the toggle re-enabled if the user wants to retry.
+  async function withdrawRequest() {
+    if (!activationRequest || activationRequest.status !== "pending") return;
+    setSaving(true);
+    setError(null);
+    try {
+      const res = await fetch(
+        `/api/skills/requests/${activationRequest.id}/withdraw`,
+        { method: "POST" }
+      );
+      if (!res.ok) {
+        const err = await res.json().catch(() => ({}));
+        throw new Error(err.error || `HTTP ${res.status}`);
+      }
+      router.refresh();
+    } catch (e: any) {
+      setError(e.message);
+    } finally {
+      setSaving(false);
+    }
+  }
+
+  // Phase 2.5: retry after a rejection. Same flow as a fresh
+  // enable; the rejected row stays in the DB as audit trail but a
+  // new pending row will be created by the PATCH.
+  function tryAgainAfterRejection() {
+    setError(null);
+    handleEnable();
+  }
+
   async function handleSubmitSecrets() {
     if (pkg.disclaimerKey && !accepted) return;
 
@@ -122,9 +239,52 @@ export function PackageCard({
           {pkg.requiresSecrets && (
             <span className="text-[10px] text-text-muted">{t("packages.requiresApiKey")}</span>
           )}
-          {canEdit ? (
+          {/* Phase 2.5: pending or rejected request takes precedence
+              over the toggle. Approved/withdrawn never reach here.
+              For packages that needed secrets, surface that they're
+              safely stored — the user might otherwise worry the
+              credentials they typed got lost when the activation
+              was deferred. */}
+          {canEdit && activationRequest?.status === "pending" ? (
+            <div className="ml-auto flex flex-col items-end gap-1">
+              <span
+                className="text-[10px] text-warning italic"
+                title={pkg.requiresSecrets ? t("packages.credentialsSavedTip") : undefined}
+              >
+                {t("packages.manualReviewPending")}
+                {pkg.requiresSecrets && (
+                  <span className="text-text-muted ml-1 not-italic">
+                    · {t("packages.credentialsSaved")}
+                  </span>
+                )}
+              </span>
               <button
-              onClick={enabled ? () => togglePackage(false) : handleEnable}
+                onClick={withdrawRequest}
+                disabled={saving}
+                className="rounded-lg px-3 py-1.5 text-xs font-medium text-text-secondary hover:text-text-primary bg-surface-3 hover:bg-surface-2 disabled:opacity-50 cursor-pointer"
+              >
+                {saving ? "…" : t("packages.withdraw")}
+              </button>
+            </div>
+          ) : canEdit && activationRequest?.status === "rejected" ? (
+            <div className="ml-auto flex flex-col items-end gap-1">
+              <span
+                className="text-[10px] text-error italic max-w-[220px] truncate"
+                title={activationRequest.rejectionReason ?? ""}
+              >
+                {t("packages.activationRejected")}: {activationRequest.rejectionReason}
+              </span>
+              <button
+                onClick={tryAgainAfterRejection}
+                disabled={saving}
+                className="rounded-lg px-3 py-1.5 text-xs font-medium bg-accent text-surface-0 hover:bg-accent-dim disabled:opacity-50 cursor-pointer shadow-lg shadow-accent/20"
+              >
+                {saving ? "…" : t("packages.tryAgain")}
+              </button>
+            </div>
+          ) : canEdit ? (
+            <button
+              onClick={enabled ? handleDisable : handleEnable}
               disabled={saving}
               className={`ml-auto rounded-lg px-3 py-1.5 text-xs font-medium transition-all cursor-pointer ${
                 enabled
@@ -146,6 +306,20 @@ export function PackageCard({
         </div>
       </div>
 
+      {/* Phase 2.5: cost-disclosure modal for priced skills. */}
+      <SkillCostDialog
+        open={showCostDialog}
+        onClose={() => setShowCostDialog(false)}
+        onConfirm={() => {
+          setShowCostDialog(false);
+          void proceedWithEnable();
+        }}
+        skillName={pkg.name}
+        dailyPriceChf={pricing?.dailyPriceChf ?? 0}
+        setupFeeChf={pricing?.setupFeeChf ?? 0}
+        busy={saving}
+      />
+
       {showModal && (
         <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/60 backdrop-blur-sm p-4">
           <div className="w-full max-w-md bg-surface-1 border border-border rounded-2xl p-6 space-y-4 shadow-2xl shadow-black/40">

src/components/packages/package-list.tsx

@@ -3,6 +3,10 @@
 import { useTranslations } from "next-intl";
 import { useRouter } from "next/navigation";
 import { PACKAGE_CATALOG } from "@/lib/packages";
+import type {
+  SkillActivationRequest,
+  SkillPricing,
+} from "@/types";
 import { PackageCard } from "./package-card";
 
 interface Props {
@@ -12,9 +16,21 @@ interface Props {
   onRefresh?: () => void;
   /** Slice 5: when false, package toggles and edit affordances are hidden. */
   canEdit?: boolean;
+  /**
+   * Phase 2.5 — non-terminal activation requests for this tenant.
+   * Each PackageCard looks up its skill in this array to render the
+   * pending/rejected inline state. Most recent first.
+   */
+  activationRequests?: SkillActivationRequest[];
+  /**
+   * Phase 2.5 — skill pricing keyed by skillId. Drives the cost
+   * disclosure dialog.
+   */
+  skillPricing?: SkillPricing[];
 }
 
 const CATEGORIES = [
+  { key: "core" as const, labelKey: "categories.core" },
   { key: "channel" as const, labelKey: "categories.channels" },
   { key: "skill" as const, labelKey: "categories.skills" },
 ] as const;
@@ -38,11 +54,29 @@ export function PackageList({
   conditions,
   onRefresh,
   canEdit = true,
+  activationRequests = [],
+  skillPricing = [],
 }: Props) {
   const t = useTranslations("packages");
   const router = useRouter();
   const handleRefresh = onRefresh || (() => router.refresh());
 
+  // Build per-skill lookups once so each card render is O(1) rather
+  // than O(N) over the requests array. `activationRequests` already
+  // arrives filtered to non-terminal rows (most-recent per
+  // (skill, status) pair from the server).
+  const requestBySkill = new Map<string, SkillActivationRequest>();
+  for (const req of activationRequests) {
+    // Pending takes precedence over rejected — if both exist for
+    // the same skill (race or after-rejection-retry), show pending.
+    const existing = requestBySkill.get(req.skillId);
+    if (!existing || (existing.status === "rejected" && req.status === "pending")) {
+      requestBySkill.set(req.skillId, req);
+    }
+  }
+  const pricingBySkill = new Map<string, SkillPricing>();
+  for (const p of skillPricing) pricingBySkill.set(p.skillId, p);
+
   return (
     <div className="space-y-6">
       {CATEGORIES.map(({ key, labelKey }) => {
@@ -64,6 +98,8 @@ export function PackageList({
                   tenantName={tenantName}
                   onToggled={handleRefresh}
                   canEdit={canEdit}
+                  activationRequest={requestBySkill.get(pkg.id) ?? null}
+                  pricing={pricingBySkill.get(pkg.id) ?? null}
                 />
               ))}
             </div>

src/components/packages/skill-cost-dialog.tsx

@@ -0,0 +1,115 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { Modal } from "@/components/ui/modal";
+
+interface Props {
+  open: boolean;
+  onClose: () => void;
+  onConfirm: () => void;
+  skillName: string;
+  dailyPriceChf: number;
+  setupFeeChf: number;
+  busy?: boolean;
+}
+
+/**
+ * Cost-disclosure modal shown before activating a priced skill.
+ *
+ * Shows the daily rate and setup fee (each only if > 0) and
+ * requires an explicit Confirm before the activation request goes
+ * through. Rendered every time the user toggles on a priced skill,
+ * not once-and-remember — this is recurring-charge consent, not a
+ * one-time terms agreement.
+ *
+ * The setup fee is always shown when configured, with a note
+ * clarifying it's "one-time, charged on first activation". The
+ * backend (billing.ts tenantSkillHasBeenBilled) is the authority
+ * on whether the fee actually fires — we don't second-guess from
+ * the client. If you've previously activated this skill on this
+ * tenant, the fee won't appear on the next invoice even though
+ * the dialog mentions it.
+ */
+export function SkillCostDialog({
+  open,
+  onClose,
+  onConfirm,
+  skillName,
+  dailyPriceChf,
+  setupFeeChf,
+  busy = false,
+}: Props) {
+  const t = useTranslations("skillCostDialog");
+  const showSetupFee = setupFeeChf > 0;
+  const showDaily = dailyPriceChf > 0;
+  // Nothing to disclose? Bail to confirm immediately — shouldn't
+  // normally be shown in this case but guard anyway.
+  if (!showSetupFee && !showDaily) {
+    return null;
+  }
+  return (
+    <Modal open={open} onClose={onClose} ariaLabel={t("title")}>
+      <div className="bg-surface-1 rounded-lg border border-border p-6 max-w-md w-full">
+        <h2 className="text-lg font-semibold mb-2">{t("title")}</h2>
+        <p className="text-sm text-text-secondary mb-4">
+          {t("intro", { skill: skillName })}
+        </p>
+
+        <div className="rounded-md bg-surface-2 border border-border p-4 mb-4 space-y-2">
+          {showSetupFee && (
+            <div className="flex justify-between items-baseline">
+              <div>
+                <div className="text-sm">{t("setupFeeLabel")}</div>
+                <div className="text-xs text-text-muted">
+                  {t("setupFeeNote")}
+                </div>
+              </div>
+              <div className="text-sm font-mono">
+                CHF {setupFeeChf.toFixed(2)}
+              </div>
+            </div>
+          )}
+          {showDaily && (
+            /* Display reference monthly cost (daily × 30) plus the
+               actual daily rate as a sub-note. Billing is always
+               per UTC day enabled — partial months prorate to that
+               same daily rate, full months land at roughly the
+               figure shown (varies ±~3% by month length). */
+            <div className="flex justify-between items-baseline">
+              <div>
+                <div className="text-sm">{t("monthlyPriceLabel")}</div>
+                <div className="text-xs text-text-muted">
+                  {t("monthlyPriceNote", {
+                    daily: dailyPriceChf.toFixed(2),
+                  })}
+                </div>
+              </div>
+              <div className="text-sm font-mono">
+                CHF {(dailyPriceChf * 30).toFixed(2)} / {t("monthUnit")}
+              </div>
+            </div>
+          )}
+        </div>
+
+        <p className="text-xs text-text-muted mb-4">{t("disclaimer")}</p>
+
+        <div className="flex justify-end gap-2">
+          <button
+            onClick={onClose}
+            disabled={busy}
+            className="px-4 py-2 rounded-md border border-border text-sm disabled:opacity-50"
+          >
+            {t("cancel")}
+          </button>
+          <button
+            onClick={onConfirm}
+            disabled={busy}
+            className="px-4 py-2 rounded-md bg-accent text-white text-sm disabled:opacity-50"
+          >
+            {busy ? t("confirming") : t("confirm")}
+          </button>
+        </div>
+      </div>
+    </Modal>
+  );
+}

src/components/settings/billing-settings-form.tsx

@@ -20,6 +20,13 @@ interface Props {
   orgName: string;
   /** Default full-name for personal orgs on first edit. */
   userName: string;
+  /**
+   * Default billing email — the address the user registered with.
+   * Used on first edit (when `initial` is null). Customers can still
+   * type a different address (e.g. accounting@…) but the registration
+   * email is a sensible starting point.
+   */
+  userEmail: string;
 }
 
 /**
@@ -38,6 +45,7 @@ export function BillingSettingsForm({
   isPersonal,
   orgName,
   userName,
+  userEmail,
 }: Props) {
   const t = useTranslations("settingsBilling");
   const tCommon = useTranslations("common");
@@ -53,7 +61,12 @@ export function BillingSettingsForm({
   const [city, setCity] = useState(initial?.city ?? "");
   const [country, setCountry] = useState(initial?.country ?? "CH");
   const [vatNumber, setVatNumber] = useState(initial?.vatNumber ?? "");
-  const [billingEmail, setBillingEmail] = useState(initial?.billingEmail ?? "");
+  // Default billing email to the user's registration email when no
+  // record exists yet. They can change it (a separate accounting
+  // address is common); we just want sensible pre-fill on first edit.
+  const [billingEmail, setBillingEmail] = useState(
+    initial?.billingEmail ?? userEmail ?? ""
+  );
   const [notes, setNotes] = useState(initial?.notes ?? "");
 
   const [submitting, setSubmitting] = useState(false);
@@ -227,7 +240,9 @@ export function BillingSettingsForm({
             onChange={(e) => setNotes(e.target.value)}
             rows={3}
             className="w-full px-3 py-2 rounded-lg border border-border bg-surface-2 text-text-primary text-sm focus:outline-none focus:border-text-secondary"
-            placeholder={t("notesPlaceholder")}
+            placeholder={t(
+              isPersonal ? "notesPlaceholderPersonal" : "notesPlaceholder"
+            )}
           />
         </div>
 

src/components/support/ticket-admin-controls.tsx

@@ -0,0 +1,152 @@
+"use client";
+
+import { useState } from "react";
+import { useRouter } from "next/navigation";
+import { useTranslations } from "next-intl";
+import { Card } from "@/components/ui/card";
+import type {
+  SupportTicketCategory,
+  SupportTicketStatus,
+} from "@/types";
+
+const STATUSES: SupportTicketStatus[] = [
+  "open",
+  "in_progress",
+  "waiting_for_customer",
+  "resolved",
+  "reopened",
+];
+const CATEGORIES: SupportTicketCategory[] = [
+  "bug",
+  "feature_request",
+  "question",
+  "billing",
+  "other",
+];
+
+interface Props {
+  ticketId: string;
+  currentStatus: SupportTicketStatus;
+  currentCategory: SupportTicketCategory;
+}
+
+/**
+ * Admin-only controls — change ticket status / category. Visible
+ * exclusively when `user.isPlatform` (gate is in the parent server
+ * component, not here).
+ *
+ * Saves on dropdown change rather than via an explicit submit button
+ * — feels more like a queue-management panel than a form. Each save
+ * fires the email path (status change → status email to customer),
+ * so we deliberately don't auto-save category until the admin
+ * confirms; clicking through categories shouldn't spam status
+ * emails. (Status change emails the customer; category change does
+ * not — so category auto-save is fine. Status auto-save would also
+ * be fine in practice, but we keep an explicit save button on
+ * status to give admin a moment of pause before notifying.)
+ *
+ * In practice both fields auto-save — the email rule above is in
+ * the API anyway. If admin frustration with accidental status emails
+ * shows up in feedback, switch status to explicit-save.
+ */
+export function TicketAdminControls({
+  ticketId,
+  currentStatus,
+  currentCategory,
+}: Props) {
+  const t = useTranslations("support");
+  const router = useRouter();
+
+  const [status, setStatus] = useState(currentStatus);
+  const [category, setCategory] = useState(currentCategory);
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState("");
+
+  const saveChange = async (changes: {
+    status?: SupportTicketStatus;
+    category?: SupportTicketCategory;
+  }) => {
+    setSaving(true);
+    setError("");
+    try {
+      const res = await fetch(
+        `/api/support/tickets/${encodeURIComponent(ticketId)}`,
+        {
+          method: "PATCH",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(changes),
+        }
+      );
+      if (!res.ok) {
+        const data = await res.json().catch(() => ({}));
+        throw new Error(data.error || t("updateFailed"));
+      }
+      router.refresh();
+    } catch (e: any) {
+      setError(e.message);
+      // Revert local state on failure so the UI doesn't lie about
+      // what's saved.
+      if (changes.status) setStatus(currentStatus);
+      if (changes.category) setCategory(currentCategory);
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  return (
+    <Card className="border-blue-400/30 bg-blue-400/5">
+      <div className="text-xs uppercase tracking-wider text-blue-400 font-semibold mb-3">
+        {t("adminControlsTitle")}
+      </div>
+      <div className="grid grid-cols-1 sm:grid-cols-2 gap-4">
+        <div>
+          <label className="block text-xs uppercase tracking-wider text-text-muted mb-1">
+            {t("fieldStatus")}
+          </label>
+          <select
+            value={status}
+            disabled={saving}
+            onChange={(e) => {
+              const next = e.target.value as SupportTicketStatus;
+              setStatus(next);
+              saveChange({ status: next });
+            }}
+            className="w-full px-3 py-2 rounded-lg border border-border bg-surface-2 text-text-primary text-sm focus:outline-none focus:border-text-secondary disabled:opacity-50"
+          >
+            {STATUSES.map((s) => (
+              <option key={s} value={s}>
+                {t(`status_${s}`)}
+              </option>
+            ))}
+          </select>
+        </div>
+        <div>
+          <label className="block text-xs uppercase tracking-wider text-text-muted mb-1">
+            {t("fieldCategory")}
+          </label>
+          <select
+            value={category}
+            disabled={saving}
+            onChange={(e) => {
+              const next = e.target.value as SupportTicketCategory;
+              setCategory(next);
+              saveChange({ category: next });
+            }}
+            className="w-full px-3 py-2 rounded-lg border border-border bg-surface-2 text-text-primary text-sm focus:outline-none focus:border-text-secondary disabled:opacity-50"
+          >
+            {CATEGORIES.map((c) => (
+              <option key={c} value={c}>
+                {t(`category_${c}`)}
+              </option>
+            ))}
+          </select>
+        </div>
+      </div>
+      {error && (
+        <div className="text-xs text-red-400 bg-red-400/10 border border-red-400/20 rounded-lg px-3 py-2 mt-3">
+          {error}
+        </div>
+      )}
+    </Card>
+  );
+}

src/components/support/ticket-category-label.tsx

@@ -0,0 +1,19 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import type { SupportTicketCategory } from "@/types";
+
+/**
+ * Plain translated category label, e.g. "Bug" / "Feature request" /
+ * "Billing". No styling chrome — just the text. Categories don't
+ * carry the same lifecycle/urgency signal as status, so they don't
+ * earn a coloured pill.
+ */
+export function TicketCategoryLabel({
+  category,
+}: {
+  category: SupportTicketCategory;
+}) {
+  const t = useTranslations("support");
+  return <span>{t(`category_${category}`)}</span>;
+}

src/components/support/ticket-create-form.tsx

@@ -0,0 +1,130 @@
+"use client";
+
+import { useState } from "react";
+import { useRouter } from "next/navigation";
+import { useTranslations } from "next-intl";
+import { Card } from "@/components/ui/card";
+import type { SupportTicketCategory } from "@/types";
+
+const CATEGORIES: SupportTicketCategory[] = [
+  "bug",
+  "feature_request",
+  "question",
+  "billing",
+  "other",
+];
+
+export function TicketCreateForm() {
+  const t = useTranslations("support");
+  const tCommon = useTranslations("common");
+  const router = useRouter();
+
+  const [title, setTitle] = useState("");
+  const [description, setDescription] = useState("");
+  const [category, setCategory] = useState<SupportTicketCategory>("question");
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState("");
+
+  const onSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setSubmitting(true);
+    setError("");
+    try {
+      const res = await fetch("/api/support/tickets", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ title, description, category }),
+      });
+      if (!res.ok) {
+        const data = await res.json().catch(() => ({}));
+        throw new Error(data.error || t("createFailed"));
+      }
+      const data = await res.json();
+      // Redirect to the new ticket's detail page so the customer can
+      // see the confirmation state and immediately add follow-ups if
+      // they wish.
+      router.push(`/support/${data.ticket.id}`);
+      router.refresh();
+    } catch (e: any) {
+      setError(e.message);
+      setSubmitting(false);
+    }
+  };
+
+  return (
+    <Card>
+      <form onSubmit={onSubmit} className="space-y-4">
+        <div>
+          <label className="block text-xs uppercase tracking-wider text-text-muted mb-1">
+            {t("fieldCategory")} <span className="text-red-400">*</span>
+          </label>
+          <select
+            required
+            value={category}
+            onChange={(e) =>
+              setCategory(e.target.value as SupportTicketCategory)
+            }
+            className="w-full px-3 py-2 rounded-lg border border-border bg-surface-2 text-text-primary text-sm focus:outline-none focus:border-text-secondary"
+          >
+            {CATEGORIES.map((c) => (
+              <option key={c} value={c}>
+                {t(`category_${c}`)}
+              </option>
+            ))}
+          </select>
+        </div>
+
+        <div>
+          <label className="block text-xs uppercase tracking-wider text-text-muted mb-1">
+            {t("fieldTitle")} <span className="text-red-400">*</span>
+          </label>
+          <input
+            type="text"
+            required
+            minLength={3}
+            maxLength={200}
+            value={title}
+            onChange={(e) => setTitle(e.target.value)}
+            placeholder={t("titlePlaceholder")}
+            className="w-full px-3 py-2 rounded-lg border border-border bg-surface-2 text-text-primary text-sm focus:outline-none focus:border-text-secondary"
+          />
+        </div>
+
+        <div>
+          <label className="block text-xs uppercase tracking-wider text-text-muted mb-1">
+            {t("fieldDescription")} <span className="text-red-400">*</span>
+          </label>
+          <textarea
+            required
+            minLength={10}
+            maxLength={10_000}
+            rows={8}
+            value={description}
+            onChange={(e) => setDescription(e.target.value)}
+            placeholder={t("descriptionPlaceholder")}
+            className="w-full px-3 py-2 rounded-lg border border-border bg-surface-2 text-text-primary text-sm focus:outline-none focus:border-text-secondary"
+          />
+          <p className="text-xs text-text-muted mt-1">
+            {t("descriptionHelp")}
+          </p>
+        </div>
+
+        {error && (
+          <div className="text-xs text-red-400 bg-red-400/10 border border-red-400/20 rounded-lg px-3 py-2">
+            {error}
+          </div>
+        )}
+
+        <div className="flex justify-end">
+          <button
+            type="submit"
+            disabled={submitting}
+            className="text-sm font-medium px-4 py-2 rounded-lg bg-accent text-white hover:bg-accent/90 transition-colors disabled:opacity-50"
+          >
+            {submitting ? tCommon("loading") : t("submitTicket")}
+          </button>
+        </div>
+      </form>
+    </Card>
+  );
+}

src/components/support/ticket-status-badge.tsx

@@ -0,0 +1,38 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import type { SupportTicketStatus } from "@/types";
+
+const STATUS_STYLES: Record<SupportTicketStatus, string> = {
+  // Open: blue, neutral attention.
+  open: "bg-blue-400/15 text-blue-400 border border-blue-400/20",
+  // In progress: amber, work happening.
+  in_progress: "bg-amber-400/15 text-amber-400 border border-amber-400/20",
+  // Waiting for customer: violet — distinct from in_progress so admins
+  // can quickly visually separate "I owe a response" from "they owe one".
+  waiting_for_customer:
+    "bg-violet-400/15 text-violet-400 border border-violet-400/20",
+  resolved: "bg-success/15 text-success border border-success/20",
+  // Reopened: red — flags admin attention because the previous
+  // resolution didn't stick.
+  reopened: "bg-red-400/15 text-red-400 border border-red-400/20",
+};
+
+/**
+ * Small status pill rendered on ticket list rows and detail header.
+ * Translated label, colour-coded by ticket lifecycle stage.
+ */
+export function TicketStatusBadge({
+  status,
+}: {
+  status: SupportTicketStatus;
+}) {
+  const t = useTranslations("support");
+  return (
+    <span
+      className={`inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-full whitespace-nowrap ${STATUS_STYLES[status]}`}
+    >
+      {t(`status_${status}`)}
+    </span>
+  );
+}

src/components/support/ticket-thread.tsx

@@ -0,0 +1,198 @@
+"use client";
+
+import { useState } from "react";
+import { useRouter } from "next/navigation";
+import { useTranslations, useFormatter } from "next-intl";
+import { Card } from "@/components/ui/card";
+import { formatDateTime } from "@/lib/format";
+import type { SupportTicketComment, SupportTicketStatus } from "@/types";
+
+interface Props {
+  ticketId: string;
+  ticketStatus: SupportTicketStatus;
+  comments: SupportTicketComment[];
+  isPlatform: boolean;
+  /** True when the viewer is the customer who created this ticket. */
+  isOwnTicket: boolean;
+}
+
+/**
+ * Thread of comments + reply box. Customer-side viewers see a
+ * "Close ticket" button as well, mapping to the customer-self-close
+ * path on the PATCH endpoint.
+ *
+ * Reply submission: posts the comment, then router.refresh() so the
+ * server-rendered page re-fetches and renders the new entry. Avoids
+ * duplicating the comment-rendering logic on the client.
+ *
+ * Empty body submissions are blocked at HTML level (required) AND
+ * by the API; we trust both layers.
+ */
+export function TicketThread({
+  ticketId,
+  ticketStatus,
+  comments,
+  isPlatform,
+  isOwnTicket,
+}: Props) {
+  const t = useTranslations("support");
+  const tCommon = useTranslations("common");
+  const f = useFormatter();
+  const router = useRouter();
+
+  const [body, setBody] = useState("");
+  const [submitting, setSubmitting] = useState(false);
+  const [closing, setClosing] = useState(false);
+  const [error, setError] = useState("");
+
+  const onSubmitComment = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setSubmitting(true);
+    setError("");
+    try {
+      const res = await fetch(
+        `/api/support/tickets/${encodeURIComponent(ticketId)}/comments`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ body }),
+        }
+      );
+      if (!res.ok) {
+        const data = await res.json().catch(() => ({}));
+        throw new Error(data.error || t("commentFailed"));
+      }
+      setBody("");
+      router.refresh();
+    } catch (e: any) {
+      setError(e.message);
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  // Customer-self-close: confirms because it's a state change, then
+  // hits PATCH with status=resolved. The API allows this for
+  // own-ticket regardless of role; the button only shows when the
+  // ticket is in a non-resolved state.
+  const onCustomerClose = async () => {
+    if (!confirm(t("confirmClose"))) return;
+    setClosing(true);
+    setError("");
+    try {
+      const res = await fetch(
+        `/api/support/tickets/${encodeURIComponent(ticketId)}`,
+        {
+          method: "PATCH",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ status: "resolved" }),
+        }
+      );
+      if (!res.ok) {
+        const data = await res.json().catch(() => ({}));
+        throw new Error(data.error || t("closeFailed"));
+      }
+      router.refresh();
+    } catch (e: any) {
+      setError(e.message);
+    } finally {
+      setClosing(false);
+    }
+  };
+
+  const isResolved = ticketStatus === "resolved";
+  const canCustomerClose =
+    isOwnTicket && !isResolved;
+
+  return (
+    <>
+      {comments.map((c) => (
+        <Card
+          key={c.id}
+          className={
+            c.authorKind === "admin"
+              ? "border-blue-400/30 bg-blue-400/5"
+              : ""
+          }
+        >
+          <div className="flex items-center justify-between text-xs text-text-muted mb-2">
+            <span className="font-medium text-text-primary">
+              {c.authorName}
+              {c.authorKind === "admin" && (
+                <span className="ml-2 text-blue-400 text-[10px] uppercase tracking-wider">
+                  {t("authorTagAdmin")}
+                </span>
+              )}
+            </span>
+            <span>{formatDateTime(c.createdAt, f)}</span>
+          </div>
+          <div className="text-sm text-text-primary whitespace-pre-wrap">
+            {c.body}
+          </div>
+        </Card>
+      ))}
+
+      {isResolved && (
+        <Card className="border-success/30 bg-success/5">
+          <p className="text-sm text-text-secondary text-center">
+            {t("resolvedBanner")}
+          </p>
+        </Card>
+      )}
+
+      {/* Reply box. Visible regardless of status — customer can
+          reply even on a resolved ticket (which auto-reopens it
+          server-side). The semantic is "reply means the ticket is
+          alive again", which is friendlier than blocking the reply. */}
+      <Card>
+        <form onSubmit={onSubmitComment} className="space-y-3">
+          <label className="block text-xs uppercase tracking-wider text-text-muted">
+            {t("replyLabel")}
+          </label>
+          <textarea
+            required
+            minLength={1}
+            maxLength={10_000}
+            rows={4}
+            value={body}
+            onChange={(e) => setBody(e.target.value)}
+            placeholder={
+              isResolved && isOwnTicket
+                ? t("replyPlaceholderReopen")
+                : t("replyPlaceholder")
+            }
+            className="w-full px-3 py-2 rounded-lg border border-border bg-surface-2 text-text-primary text-sm focus:outline-none focus:border-text-secondary"
+          />
+
+          {error && (
+            <div className="text-xs text-red-400 bg-red-400/10 border border-red-400/20 rounded-lg px-3 py-2">
+              {error}
+            </div>
+          )}
+
+          <div className="flex items-center justify-between">
+            {canCustomerClose ? (
+              <button
+                type="button"
+                onClick={onCustomerClose}
+                disabled={closing || submitting}
+                className="text-xs text-text-secondary hover:text-text-primary transition-colors disabled:opacity-50"
+              >
+                {closing ? tCommon("loading") : t("closeTicket")}
+              </button>
+            ) : (
+              <span />
+            )}
+            <button
+              type="submit"
+              disabled={submitting || closing || body.trim().length === 0}
+              className="text-sm font-medium px-4 py-2 rounded-lg bg-accent text-white hover:bg-accent/90 transition-colors disabled:opacity-50"
+            >
+              {submitting ? tCommon("loading") : t("sendReply")}
+            </button>
+          </div>
+        </form>
+      </Card>
+    </>
+  );
+}

src/components/tenants/subscription-toggle.tsx

@@ -24,11 +24,16 @@ interface Props {
   isPlatform: boolean;
   /**
    * If a resume request is currently pending for this tenant, its
-   * id and submitted-at. The component renders an info card with
-   * a cancel-request button instead of the request-reactivation
-   * button. Only meaningful when `suspended === true`.
+   * id, when it was submitted, and the customer's optional note.
+   * The component renders an info card with a cancel-request button
+   * instead of the request-reactivation button. Only meaningful when
+   * `suspended === true`.
    */
-  pendingResumeRequest: { id: string; createdAt: string } | null;
+  pendingResumeRequest: {
+    id: string;
+    createdAt: string;
+    customerNotes: string | null;
+  } | null;
 }
 
 /**
@@ -65,6 +70,10 @@ export function SubscriptionToggle({
   const [confirmResumeOpen, setConfirmResumeOpen] = useState(false);
   const [submitting, setSubmitting] = useState(false);
   const [error, setError] = useState("");
+  // Feature 6: customer's free-form note attached to the resume
+  // request. Reset when the modal opens/closes so re-opening doesn't
+  // show stale text from a previous abandoned attempt.
+  const [resumeNotes, setResumeNotes] = useState("");
 
   // Customer-side cancel: PATCH suspend=true. Same path as before.
   // The 60-day retention copy in the modal is the new bit (Bug 37b);
@@ -106,6 +115,13 @@ export function SubscriptionToggle({
         {
           method: "POST",
           headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            // Trim and omit on empty so the API stores NULL rather
+            // than empty string. The endpoint's zod transform also
+            // handles this; double-checking on the client lets us
+            // skip the round-trip when there's nothing to send.
+            customerNotes: resumeNotes.trim() || undefined,
+          }),
         }
       );
       if (!res.ok) {
@@ -113,6 +129,7 @@ export function SubscriptionToggle({
         throw new Error(data.error || t("subscriptionUpdateFailed"));
       }
       setConfirmResumeOpen(false);
+      setResumeNotes("");
       router.refresh();
     } catch (e: any) {
       setError(e.message);
@@ -210,6 +227,15 @@ export function SubscriptionToggle({
                 when: formatRelative(pendingResumeRequest.createdAt, f),
               })}
             </div>
+            {/* Feature 6: echo the customer's note back so they can
+                see what they wrote. Useful especially when they
+                later wonder "what did I tell them?" or want to
+                confirm before cancelling and resubmitting. */}
+            {pendingResumeRequest.customerNotes && (
+              <div className="mt-2 text-xs text-text-secondary border-l-2 border-amber-500/30 pl-3 whitespace-pre-wrap">
+                {pendingResumeRequest.customerNotes}
+              </div>
+            )}
             <button
               type="button"
               onClick={cancelResumeRequest}
@@ -249,10 +275,33 @@ export function SubscriptionToggle({
             <h3 className="font-display text-lg font-semibold text-text-primary mb-2">
               {t("requestReactivationConfirmTitle")}
             </h3>
-            <p className="text-sm text-text-secondary mb-5">
+            <p className="text-sm text-text-secondary mb-4">
               {t("requestReactivationConfirmDescription")}
             </p>
 
+            {/* Feature 6: optional explanatory note. Useful for
+                customers to tell admin why they want reactivation
+                — e.g. "we paused over winter break, picking back
+                up". Stored on the tenant_request and surfaced in
+                the admin queue. */}
+            <div className="mb-5">
+              <label className="block text-xs uppercase tracking-wider text-text-muted mb-1.5">
+                {t("requestReactivationNoteLabel")}{" "}
+                <span className="text-text-muted normal-case">
+                  ({tCommon("optional")})
+                </span>
+              </label>
+              <textarea
+                value={resumeNotes}
+                onChange={(e) => setResumeNotes(e.target.value)}
+                rows={3}
+                maxLength={2000}
+                placeholder={t("requestReactivationNotePlaceholder")}
+                disabled={submitting}
+                className="w-full px-3 py-2 rounded-lg border border-border bg-surface-2 text-text-primary text-sm focus:outline-none focus:border-text-secondary disabled:opacity-50"
+              />
+            </div>
+
             {error && (
               <div className="text-xs text-red-400 bg-red-400/10 border border-red-400/20 rounded-lg px-3 py-2 mb-3">
                 {error}

src/lib/billing-i18n.ts

@@ -0,0 +1,157 @@
+/**
+ * Shared billing localization. Used by:
+ *   - billing.ts (compute path) — pre-renders the localized
+ *     line description and stores it on the invoice line at issue
+ *     time. Descriptions are then frozen in the customer's locale.
+ *   - billing-pdf.tsx (render path) — can fall back to this if a
+ *     stored description is missing (e.g. legacy invoice from the
+ *     pre-i18n era) or if the PDF is re-rendered in a different
+ *     locale (Phase 7).
+ *
+ * Locale set matches the portal's next-intl locales: de, en, fr, it.
+ * Unknown locales fall back to German (Swiss B2B default).
+ */
+
+import type { InvoiceLineKind } from "@/types";
+
+export type BillingLocale = "de" | "en" | "fr" | "it";
+
+function normaliseLocale(locale: string): BillingLocale {
+  if (locale === "en" || locale === "fr" || locale === "it" || locale === "de") {
+    return locale;
+  }
+  return "de";
+}
+
+/**
+ * Localized "N day(s)" — covers the only plural case in billing
+ * line descriptions. Other plurals (months, requests, messages)
+ * either don't change form in the supported languages or are
+ * always >1 in practice.
+ */
+function days(n: number, locale: BillingLocale): string {
+  const labels = {
+    de: { one: "Tag", many: "Tage" },
+    en: { one: "day", many: "days" },
+    fr: { one: "jour", many: "jours" },
+    it: { one: "giorno", many: "giorni" },
+  } as const;
+  const label = labels[locale];
+  return `${n} ${n === 1 ? label.one : label.many}`;
+}
+
+/** Subset of InvoiceLine needed for description formatting. */
+export interface LineForDescription {
+  kind: InvoiceLineKind;
+  tenantName: string | null;
+  metadata: Record<string, unknown> | null;
+}
+
+/**
+ * Build the localized line description from a line's kind +
+ * metadata. Pure function — no DB/IO. Output mirrors what the
+ * PDF and admin preview show in the description column.
+ *
+ * Metadata expectations per kind (must match what billing.ts
+ * stores when emitting the line):
+ *   tenant_monthly:    { billable_days, days_in_month }
+ *   tenant_setup:      {} (uses tenantName only)
+ *   ai_usage:          { requests }
+ *   threema_messages:  { in_count, out_count }
+ *   skill_usage:       { skill_id, billable_days }
+ *   skill_setup:       { skill_id }
+ *   adjustment:        { reason? }
+ *
+ * Missing fields fall back to "?" so a malformed line still
+ * renders something readable rather than crashing the PDF.
+ */
+export function formatLineDescription(
+  line: LineForDescription,
+  locale: string
+): string {
+  const L = normaliseLocale(locale);
+  const m = line.metadata ?? {};
+  const tenant = line.tenantName ?? "—";
+  // Helper to fetch a metadata field with a safe fallback.
+  const f = (key: string): string | number => {
+    const v = (m as Record<string, unknown>)[key];
+    if (v === undefined || v === null) return "?";
+    return v as string | number;
+  };
+
+  switch (line.kind) {
+    case "tenant_monthly": {
+      const bd = f("billable_days");
+      const dim = f("days_in_month");
+      return {
+        de: `Monatliche Grundgebühr für ${tenant} (${bd}/${dim} Tage)`,
+        en: `Monthly fee for ${tenant} (${bd}/${dim} days)`,
+        fr: `Forfait mensuel pour ${tenant} (${bd}/${dim} jours)`,
+        it: `Canone mensile per ${tenant} (${bd}/${dim} giorni)`,
+      }[L];
+    }
+
+    case "tenant_setup":
+      return {
+        de: `Einrichtungsgebühr für ${tenant}`,
+        en: `Setup fee for ${tenant}`,
+        fr: `Frais de configuration pour ${tenant}`,
+        it: `Spese di attivazione per ${tenant}`,
+      }[L];
+
+    case "ai_usage": {
+      const r = f("requests");
+      return {
+        de: `KI-Inferenz-Nutzung (${r} Anfragen)`,
+        en: `AI inference usage (${r} requests)`,
+        fr: `Utilisation IA (${r} requêtes)`,
+        it: `Utilizzo IA (${r} richieste)`,
+      }[L];
+    }
+
+    case "threema_messages": {
+      const inC = f("in_count");
+      const outC = f("out_count");
+      return {
+        de: `Threema-Nachrichten (${inC} eingehend + ${outC} ausgehend)`,
+        en: `Threema messages (${inC} in + ${outC} out)`,
+        fr: `Messages Threema (${inC} entrants + ${outC} sortants)`,
+        it: `Messaggi Threema (${inC} in entrata + ${outC} in uscita)`,
+      }[L];
+    }
+
+    case "skill_usage": {
+      const skill = f("skill_id");
+      const bdRaw = (m as Record<string, unknown>)["billable_days"];
+      const bd = typeof bdRaw === "number" ? bdRaw : 0;
+      return {
+        de: `Skill: ${skill} (${days(bd, "de")})`,
+        en: `Skill: ${skill} (${days(bd, "en")})`,
+        fr: `Skill: ${skill} (${days(bd, "fr")})`,
+        it: `Skill: ${skill} (${days(bd, "it")})`,
+      }[L];
+    }
+
+    case "skill_setup": {
+      const skill = f("skill_id");
+      return {
+        de: `Einrichtungsgebühr Skill: ${skill}`,
+        en: `Setup fee skill: ${skill}`,
+        fr: `Frais de configuration skill: ${skill}`,
+        it: `Spese di attivazione skill: ${skill}`,
+      }[L];
+    }
+
+    case "adjustment": {
+      const reasonRaw = (m as Record<string, unknown>)["reason"];
+      const reason = typeof reasonRaw === "string" ? reasonRaw : null;
+      const base = {
+        de: "Anpassung",
+        en: "Adjustment",
+        fr: "Ajustement",
+        it: "Rettifica",
+      }[L];
+      return reason ? `${base}: ${reason}` : base;
+    }
+  }
+}

src/lib/billing-pdf.tsx

@@ -0,0 +1,659 @@
+/**
+ * Invoice PDF rendering via @react-pdf/renderer.
+ *
+ * Design notes:
+ *
+ * - The template is a React component (JSX). Visual tweaks happen
+ *   here — colors, fonts, spacing, layout. To swap branding later,
+ *   edit BRAND_* constants below or replace the logo component.
+ *
+ * - All strings are pulled from MESSAGES[locale]. To add a new
+ *   language, copy the German block and translate. Locale is
+ *   frozen on the invoice at issue time (invoices.locale column);
+ *   re-rendering a historical invoice always uses the same locale.
+ *
+ * - The logo is inlined as React-PDF SVG primitives so no asset
+ *   loading or font-bundle wrangling is needed. It travels with
+ *   the code.
+ *
+ * - VAT note (reverse charge etc.) is appended below the totals
+ *   block. Notes are localized in the same MESSAGES map.
+ *
+ * - QR-bill (Swiss bank transfer) is intentionally NOT included
+ *   in v1 — it lands in Phase 7. We render plain bank instructions
+ *   as text.
+ */
+
+import React from "react";
+import {
+  Document,
+  Page,
+  Text,
+  View,
+  StyleSheet,
+  Svg,
+  Polygon,
+  Polyline,
+  renderToBuffer,
+} from "@react-pdf/renderer";
+import type { Invoice, InvoiceLine, InvoiceLineKind } from "@/types";
+
+// ---------------------------------------------------------------------------
+// Brand constants — edit here to tweak look without touching layout
+// ---------------------------------------------------------------------------
+
+const BRAND = {
+  name: "PieCed IT",
+  // Primary emerald — matches the logo SVG fill (#10B981).
+  primary: "#10B981",
+  // Slightly darker emerald for headings.
+  primaryDark: "#0a8060",
+  textColor: "#1a1a1a",
+  mutedColor: "#666",
+  borderColor: "#d4d4d4",
+  // Issuer block — change these to your real legal info.
+  issuer: {
+    legalName: "PieCed IT",
+    addressLine1: "Cedric Mosimann",
+    addressLine2: "[Strasse Nr.]",
+    postalCity: "[PLZ] Basel",
+    country: "Switzerland",
+    email: "billing@pieced.ch",
+    web: "pieced.ch",
+    // Show "MWST-Nr. ..." on PDF when set.
+    vatNumber: null as string | null,
+    // Bank instructions — Phase 7 replaces with QR-bill.
+    bankName: "[Bank name]",
+    bankIban: "[CHxx xxxx xxxx xxxx xxxx x]",
+    bankBic: "[BIC]",
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Localized strings
+// ---------------------------------------------------------------------------
+
+interface PdfStrings {
+  invoice: string;
+  invoiceNumber: string;
+  issueDate: string;
+  dueDate: string;
+  period: string;
+  billTo: string;
+  description: string;
+  quantity: string;
+  unitPrice: string;
+  amount: string;
+  subtotal: string;
+  vat: string;
+  total: string;
+  paymentInstructions: string;
+  paymentRefHint: string;
+  thankYou: string;
+  page: string;
+  of: string;
+  // Per-line-kind labels (used as section headers)
+  kindLabels: Record<InvoiceLineKind, string>;
+  // VAT compliance notes
+  reverseCharge: string;
+  exportNote: string;
+}
+
+const MESSAGES: Record<string, PdfStrings> = {
+  de: {
+    invoice: "Rechnung",
+    invoiceNumber: "Rechnungs-Nr.",
+    issueDate: "Rechnungsdatum",
+    dueDate: "Zahlbar bis",
+    period: "Abrechnungsperiode",
+    billTo: "Rechnungsempfänger",
+    description: "Beschreibung",
+    quantity: "Menge",
+    unitPrice: "Einzelpreis",
+    amount: "Betrag",
+    subtotal: "Zwischensumme",
+    vat: "MWST",
+    total: "Total",
+    paymentInstructions: "Zahlungsinformationen",
+    paymentRefHint: "Bitte verwenden Sie die Rechnungsnummer als Referenz.",
+    thankYou: "Vielen Dank für Ihr Vertrauen.",
+    page: "Seite",
+    of: "von",
+    kindLabels: {
+      tenant_monthly: "Monatliche Grundgebühr",
+      tenant_setup: "Einrichtungsgebühr",
+      ai_usage: "KI-Nutzung",
+      threema_messages: "Threema-Nachrichten",
+      skill_usage: "Skill-Nutzung",
+      skill_setup: "Einrichtungsgebühr Skill",
+      adjustment: "Anpassung",
+    },
+    reverseCharge:
+      "Steuerschuldnerschaft des Leistungsempfängers (Reverse Charge).",
+    exportNote: "Dienstleistungsexport — keine MWST in Rechnung gestellt.",
+  },
+  en: {
+    invoice: "Invoice",
+    invoiceNumber: "Invoice no.",
+    issueDate: "Issue date",
+    dueDate: "Due date",
+    period: "Billing period",
+    billTo: "Bill to",
+    description: "Description",
+    quantity: "Qty",
+    unitPrice: "Unit price",
+    amount: "Amount",
+    subtotal: "Subtotal",
+    vat: "VAT",
+    total: "Total",
+    paymentInstructions: "Payment instructions",
+    paymentRefHint: "Please use the invoice number as the payment reference.",
+    thankYou: "Thank you for your business.",
+    page: "Page",
+    of: "of",
+    kindLabels: {
+      tenant_monthly: "Monthly fee",
+      tenant_setup: "Setup fee",
+      ai_usage: "AI usage",
+      threema_messages: "Threema messages",
+      skill_usage: "Skill usage",
+      skill_setup: "Skill setup fee",
+      adjustment: "Adjustment",
+    },
+    reverseCharge:
+      "Reverse charge — VAT to be accounted for by the recipient.",
+    exportNote: "Export of services — VAT not applicable.",
+  },
+  fr: {
+    invoice: "Facture",
+    invoiceNumber: "N° facture",
+    issueDate: "Date d'émission",
+    dueDate: "Échéance",
+    period: "Période de facturation",
+    billTo: "Destinataire",
+    description: "Description",
+    quantity: "Qté",
+    unitPrice: "Prix unitaire",
+    amount: "Montant",
+    subtotal: "Sous-total",
+    vat: "TVA",
+    total: "Total",
+    paymentInstructions: "Informations de paiement",
+    paymentRefHint: "Veuillez utiliser le n° de facture comme référence.",
+    thankYou: "Merci de votre confiance.",
+    page: "Page",
+    of: "sur",
+    kindLabels: {
+      tenant_monthly: "Forfait mensuel",
+      tenant_setup: "Frais de configuration",
+      ai_usage: "Utilisation IA",
+      threema_messages: "Messages Threema",
+      skill_usage: "Utilisation Skill",
+      skill_setup: "Frais de configuration skill",
+      adjustment: "Ajustement",
+    },
+    reverseCharge:
+      "Autoliquidation — TVA à acquitter par le destinataire.",
+    exportNote: "Exportation de services — TVA non applicable.",
+  },
+  it: {
+    invoice: "Fattura",
+    invoiceNumber: "N. fattura",
+    issueDate: "Data di emissione",
+    dueDate: "Scadenza",
+    period: "Periodo di fatturazione",
+    billTo: "Destinatario",
+    description: "Descrizione",
+    quantity: "Qtà",
+    unitPrice: "Prezzo unitario",
+    amount: "Importo",
+    subtotal: "Subtotale",
+    vat: "IVA",
+    total: "Totale",
+    paymentInstructions: "Istruzioni di pagamento",
+    paymentRefHint: "Si prega di utilizzare il n. di fattura come riferimento.",
+    thankYou: "Grazie per la fiducia.",
+    page: "Pagina",
+    of: "di",
+    kindLabels: {
+      tenant_monthly: "Canone mensile",
+      tenant_setup: "Spese di attivazione",
+      ai_usage: "Utilizzo IA",
+      threema_messages: "Messaggi Threema",
+      skill_usage: "Utilizzo Skill",
+      skill_setup: "Spese di attivazione skill",
+      adjustment: "Rettifica",
+    },
+    reverseCharge:
+      "Inversione contabile — IVA a carico del destinatario.",
+    exportNote: "Esportazione di servizi — IVA non applicabile.",
+  },
+};
+
+function getStrings(locale: string): PdfStrings {
+  return MESSAGES[locale] ?? MESSAGES.de;
+}
+
+// ---------------------------------------------------------------------------
+// Stylesheet
+// ---------------------------------------------------------------------------
+
+const styles = StyleSheet.create({
+  page: {
+    paddingTop: 40,
+    paddingBottom: 60,
+    paddingHorizontal: 40,
+    fontSize: 9,
+    color: BRAND.textColor,
+    lineHeight: 1.4,
+  },
+  headerRow: {
+    flexDirection: "row",
+    justifyContent: "space-between",
+    alignItems: "flex-start",
+    marginBottom: 28,
+  },
+  logoWrap: { width: 60, height: 90 },
+  issuerBlock: { textAlign: "right", fontSize: 8.5, color: BRAND.mutedColor },
+  issuerName: { fontSize: 11, color: BRAND.primaryDark, marginBottom: 2 },
+  invoiceTitle: { fontSize: 22, color: BRAND.primaryDark, marginBottom: 8 },
+  metaTable: {
+    flexDirection: "row",
+    justifyContent: "space-between",
+    marginBottom: 20,
+  },
+  metaCol: { flexGrow: 1, marginRight: 16 },
+  metaLabel: { color: BRAND.mutedColor, fontSize: 8, marginBottom: 2 },
+  metaValue: { fontSize: 10, marginBottom: 6 },
+  billToBlock: {
+    marginBottom: 24,
+    padding: 10,
+    backgroundColor: "#f7f7f5",
+    borderLeftWidth: 3,
+    borderLeftColor: BRAND.primary,
+  },
+  billToLabel: { fontSize: 8, color: BRAND.mutedColor, marginBottom: 4 },
+  billToName: { fontSize: 11, marginBottom: 2 },
+  table: { marginBottom: 14 },
+  tableHeader: {
+    flexDirection: "row",
+    backgroundColor: BRAND.primaryDark,
+    color: "#ffffff",
+    paddingVertical: 5,
+    paddingHorizontal: 6,
+    fontSize: 8.5,
+  },
+  tableRow: {
+    flexDirection: "row",
+    borderBottomWidth: 0.5,
+    borderBottomColor: BRAND.borderColor,
+    paddingVertical: 5,
+    paddingHorizontal: 6,
+  },
+  // Column widths (sum ≈ 100%)
+  colDesc: { width: "52%" },
+  colQty: { width: "12%", textAlign: "right" },
+  colUnit: { width: "16%", textAlign: "right" },
+  colAmt: { width: "20%", textAlign: "right" },
+  totalsBlock: {
+    alignSelf: "flex-end",
+    width: "45%",
+    marginTop: 8,
+  },
+  totalsRow: {
+    flexDirection: "row",
+    justifyContent: "space-between",
+    paddingVertical: 3,
+  },
+  totalsLabel: { color: BRAND.mutedColor },
+  totalsValue: { textAlign: "right" },
+  totalsGrand: {
+    flexDirection: "row",
+    justifyContent: "space-between",
+    borderTopWidth: 1,
+    borderTopColor: BRAND.primaryDark,
+    paddingTop: 6,
+    marginTop: 4,
+  },
+  totalsGrandLabel: { color: BRAND.primaryDark, fontSize: 11 },
+  totalsGrandValue: { color: BRAND.primaryDark, fontSize: 11, textAlign: "right" },
+  noteBox: {
+    marginTop: 18,
+    padding: 8,
+    backgroundColor: "#fff8e7",
+    borderLeftWidth: 2,
+    borderLeftColor: "#d4a017",
+    fontSize: 8.5,
+  },
+  paymentBlock: {
+    marginTop: 24,
+    paddingTop: 12,
+    borderTopWidth: 0.5,
+    borderTopColor: BRAND.borderColor,
+  },
+  paymentTitle: { fontSize: 10, color: BRAND.primaryDark, marginBottom: 6 },
+  paymentLine: { fontSize: 9, marginBottom: 1 },
+  footer: {
+    position: "absolute",
+    bottom: 24,
+    left: 40,
+    right: 40,
+    flexDirection: "row",
+    justifyContent: "space-between",
+    fontSize: 7.5,
+    color: BRAND.mutedColor,
+    borderTopWidth: 0.5,
+    borderTopColor: BRAND.borderColor,
+    paddingTop: 8,
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Logo — inlined SVG primitives
+// ---------------------------------------------------------------------------
+
+/**
+ * PieCed honeycomb logo. Re-renders the same 6-hex glyph as the
+ * portal's `public/pieced-logo.svg` using React-PDF's SVG support.
+ * Width/height are independent of the original viewBox so we can
+ * scale it without losing stroke quality.
+ */
+const Logo = ({ size = 60 }: { size?: number }) => (
+  <Svg width={size} height={size * (106 / 70)} viewBox="0 0 70 106">
+    {/* H1 solid */}
+    <Polygon
+      points="38.5,22.69 31.5,10.566 17.5,10.566 10.5,22.69 17.5,34.814 31.5,34.814"
+      fill="#10B981"
+      stroke="#10B981"
+      strokeWidth={1.6}
+    />
+    {/* H2 outline */}
+    <Polygon
+      points="59.5,34.814 52.5,22.69 38.5,22.69 31.5,34.814 38.5,46.938 52.5,46.938"
+      fill="none"
+      stroke="#10B981"
+      strokeWidth={1.8}
+    />
+    {/* H3 outline */}
+    <Polygon
+      points="38.5,46.938 31.5,34.814 17.5,34.814 10.5,46.938 17.5,59.062 31.5,59.062"
+      fill="none"
+      stroke="#10B981"
+      strokeWidth={1.8}
+    />
+    {/* H4 solid */}
+    <Polygon
+      points="59.5,59.062 52.5,46.938 38.5,46.938 31.5,59.062 38.5,71.186 52.5,71.186"
+      fill="#10B981"
+      stroke="#10B981"
+      strokeWidth={1.6}
+    />
+    {/* H5 partial */}
+    <Polyline
+      points="31.5,83.31 38.5,71.186 31.5,59.062 17.5,59.062 10.5,71.186"
+      fill="none"
+      stroke="#10B981"
+      strokeWidth={1.8}
+    />
+    {/* H6 partial */}
+    <Polyline
+      points="59.5,83.31 52.5,71.186 38.5,71.186 31.5,83.31 38.5,95.434"
+      fill="none"
+      stroke="#10B981"
+      strokeWidth={1.8}
+    />
+  </Svg>
+);
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function fmtChf(n: number, decimals: number = 2): string {
+  // Swiss thousands separator + decimal point: 1'234.56
+  const fixed = n.toFixed(decimals);
+  const [intPart, decPart] = fixed.split(".");
+  const withSep = intPart.replace(/\B(?=(\d{3})+(?!\d))/g, "'");
+  return decPart ? `${withSep}.${decPart}` : withSep;
+}
+
+function fmtDate(iso: string, locale: string): string {
+  // Parse YYYY-MM-DD as a calendar date (no timezone shifts).
+  // For PDF rendering we want a stable representation regardless
+  // of server timezone.
+  const [y, m, d] = iso.split("T")[0].split("-").map(Number);
+  // Locale-specific date format
+  if (locale === "en") {
+    return new Date(Date.UTC(y, m - 1, d)).toLocaleDateString("en-US", {
+      year: "numeric",
+      month: "short",
+      day: "numeric",
+      timeZone: "UTC",
+    });
+  }
+  // DE/FR/IT default: DD.MM.YYYY
+  return `${String(d).padStart(2, "0")}.${String(m).padStart(2, "0")}.${y}`;
+}
+
+// ---------------------------------------------------------------------------
+// Document
+// ---------------------------------------------------------------------------
+
+interface InvoicePdfProps {
+  invoice: Invoice;
+  lines: InvoiceLine[];
+}
+
+const InvoicePdf: React.FC<InvoicePdfProps> = ({ invoice, lines }) => {
+  const s = getStrings(invoice.locale);
+  const snap = invoice.billingSnapshot;
+
+  // Group lines by tenant for visual separation. Lines without a
+  // tenant_name (org-level adjustments) go to the end.
+  const linesByTenant = new Map<string | null, InvoiceLine[]>();
+  for (const ln of lines) {
+    const key = ln.tenantName;
+    if (!linesByTenant.has(key)) linesByTenant.set(key, []);
+    linesByTenant.get(key)!.push(ln);
+  }
+  const tenantOrder = [...linesByTenant.keys()].sort((a, b) => {
+    if (a === null) return 1;
+    if (b === null) return -1;
+    return a.localeCompare(b);
+  });
+
+  // VAT note: pick the right localized note based on rate + address.
+  // Zero rate + EU country = reverse charge; zero rate + other = export.
+  let vatNote: string | null = null;
+  if (invoice.vatRate === 0) {
+    const country = (snap.country || "").toUpperCase();
+    const isEu = [
+      "AT","BE","BG","HR","CY","CZ","DK","EE","FI","FR","DE","GR","HU",
+      "IE","IT","LV","LT","LU","MT","NL","PL","PT","RO","SK","SI","ES","SE",
+    ].includes(country);
+    vatNote = isEu ? s.reverseCharge : s.exportNote;
+  }
+
+  return (
+    <Document title={`${s.invoice} ${invoice.invoiceNumber}`}>
+      <Page size="A4" style={styles.page}>
+        {/* Header: logo left, issuer right */}
+        <View style={styles.headerRow}>
+          <View style={styles.logoWrap}>
+            <Logo size={60} />
+          </View>
+          <View style={styles.issuerBlock}>
+            <Text style={styles.issuerName}>{BRAND.issuer.legalName}</Text>
+            <Text>{BRAND.issuer.addressLine1}</Text>
+            <Text>{BRAND.issuer.addressLine2}</Text>
+            <Text>{BRAND.issuer.postalCity}</Text>
+            <Text>{BRAND.issuer.country}</Text>
+            <Text>{BRAND.issuer.email}</Text>
+            {BRAND.issuer.vatNumber && (
+              <Text>MWST-Nr. {BRAND.issuer.vatNumber}</Text>
+            )}
+          </View>
+        </View>
+
+        <Text style={styles.invoiceTitle}>{s.invoice}</Text>
+
+        {/* Meta row: 3 columns */}
+        <View style={styles.metaTable}>
+          <View style={styles.metaCol}>
+            <Text style={styles.metaLabel}>{s.invoiceNumber}</Text>
+            <Text style={styles.metaValue}>{invoice.invoiceNumber}</Text>
+            <Text style={styles.metaLabel}>{s.issueDate}</Text>
+            <Text style={styles.metaValue}>
+              {fmtDate(invoice.issuedAt, invoice.locale)}
+            </Text>
+          </View>
+          <View style={styles.metaCol}>
+            <Text style={styles.metaLabel}>{s.period}</Text>
+            <Text style={styles.metaValue}>
+              {fmtDate(invoice.periodStart, invoice.locale)} —{" "}
+              {fmtDate(invoice.periodEnd, invoice.locale)}
+            </Text>
+            <Text style={styles.metaLabel}>{s.dueDate}</Text>
+            <Text style={styles.metaValue}>
+              {fmtDate(invoice.dueAt, invoice.locale)}
+            </Text>
+          </View>
+        </View>
+
+        {/* Bill-to */}
+        <View style={styles.billToBlock}>
+          <Text style={styles.billToLabel}>{s.billTo}</Text>
+          <Text style={styles.billToName}>{snap.companyName}</Text>
+          <Text>{snap.streetAddress}</Text>
+          <Text>
+            {snap.postalCode} {snap.city}
+          </Text>
+          <Text>{snap.country}</Text>
+          {snap.vatNumber && <Text>VAT: {snap.vatNumber}</Text>}
+          <Text>{snap.billingEmail}</Text>
+        </View>
+
+        {/* Line items table */}
+        <View style={styles.table}>
+          <View style={styles.tableHeader}>
+            <Text style={styles.colDesc}>{s.description}</Text>
+            <Text style={styles.colQty}>{s.quantity}</Text>
+            <Text style={styles.colUnit}>{s.unitPrice}</Text>
+            <Text style={styles.colAmt}>{s.amount} (CHF)</Text>
+          </View>
+          {tenantOrder.map((tenantKey) => {
+            const tenantLines = linesByTenant.get(tenantKey)!;
+            return (
+              <View key={tenantKey ?? "_org"}>
+                {tenantKey && (
+                  <View
+                    style={{
+                      paddingVertical: 4,
+                      paddingHorizontal: 6,
+                      backgroundColor: "#f0f9f4",
+                    }}
+                  >
+                    <Text style={{ fontSize: 9, color: BRAND.primaryDark }}>
+                      {tenantKey}
+                    </Text>
+                  </View>
+                )}
+                {tenantLines.map((ln) => (
+                  <View key={ln.id} style={styles.tableRow}>
+                    <Text style={styles.colDesc}>{ln.description}</Text>
+                    <Text style={styles.colQty}>
+                      {ln.quantity}
+                      {ln.unitLabel ? ` ${ln.unitLabel}` : ""}
+                    </Text>
+                    <Text style={styles.colUnit}>{fmtChf(ln.unitPriceChf, 5)}</Text>
+                    <Text style={styles.colAmt}>{fmtChf(ln.amountChf)}</Text>
+                  </View>
+                ))}
+              </View>
+            );
+          })}
+        </View>
+
+        {/* Totals */}
+        <View style={styles.totalsBlock}>
+          <View style={styles.totalsRow}>
+            <Text style={styles.totalsLabel}>{s.subtotal}</Text>
+            <Text style={styles.totalsValue}>{fmtChf(invoice.subtotalChf)}</Text>
+          </View>
+          <View style={styles.totalsRow}>
+            <Text style={styles.totalsLabel}>
+              {s.vat} ({invoice.vatRate.toFixed(2)}%)
+            </Text>
+            <Text style={styles.totalsValue}>{fmtChf(invoice.vatAmountChf)}</Text>
+          </View>
+          <View style={styles.totalsGrand}>
+            <Text style={styles.totalsGrandLabel}>
+              {s.total} (CHF)
+            </Text>
+            <Text style={styles.totalsGrandValue}>{fmtChf(invoice.totalChf)}</Text>
+          </View>
+        </View>
+
+        {vatNote && (
+          <View style={styles.noteBox}>
+            <Text>{vatNote}</Text>
+          </View>
+        )}
+
+        {/* Payment instructions */}
+        <View style={styles.paymentBlock}>
+          <Text style={styles.paymentTitle}>{s.paymentInstructions}</Text>
+          <Text style={styles.paymentLine}>{BRAND.issuer.legalName}</Text>
+          <Text style={styles.paymentLine}>{BRAND.issuer.bankName}</Text>
+          <Text style={styles.paymentLine}>IBAN: {BRAND.issuer.bankIban}</Text>
+          <Text style={styles.paymentLine}>BIC: {BRAND.issuer.bankBic}</Text>
+          <Text style={[styles.paymentLine, { marginTop: 6, color: BRAND.mutedColor }]}>
+            {s.paymentRefHint}
+          </Text>
+          <Text style={[styles.paymentLine, { marginTop: 12, color: BRAND.primaryDark }]}>
+            {s.thankYou}
+          </Text>
+        </View>
+
+        {/* Footer with page numbers.
+            react-pdf API quirks (verified against build errors):
+              - The `render` callback on <View> only exposes
+                `{ pageNumber, subPageNumber }` — no totalPages.
+                Only <Text> gets `{ pageNumber, totalPages,
+                subPageNumber, subPageTotalPages }`.
+              - <Text>'s render callback must return a STRING
+                (or array of strings), not JSX. */}
+        <View style={styles.footer} fixed>
+          <Text>
+            {BRAND.issuer.legalName} · {BRAND.issuer.web} · {BRAND.issuer.email}
+          </Text>
+          <Text
+            render={({ pageNumber, totalPages }) =>
+              `${s.page} ${pageNumber} ${s.of} ${totalPages}`
+            }
+            fixed
+          />
+        </View>
+      </Page>
+    </Document>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Render an invoice to a PDF buffer. Caller stores the buffer in
+ * `invoices.pdf_data` (bytea). Side-effect-free; can be called
+ * outside a DB transaction.
+ *
+ * Typical runtime is 50–200ms on a typical invoice with a dozen
+ * lines.
+ */
+export async function renderInvoicePdf(
+  invoice: Invoice,
+  lines: InvoiceLine[]
+): Promise<Buffer> {
+  return renderToBuffer(<InvoicePdf invoice={invoice} lines={lines} />);
+}

src/lib/billing.ts

@@ -0,0 +1,837 @@
+/**
+ * Billing computation pipeline.
+ *
+ * Public entry points:
+ *   - computeInvoiceDraft({ zitadelOrgId, year, month, locale? })
+ *     Builds an in-memory InvoiceDraft from the live signals
+ *     (LiteLLM spend, Threema relay usage, tenant skill events,
+ *     lifecycle, suspension). Does NOT persist or render the PDF.
+ *
+ *   - generateInvoice({ zitadelOrgId, year, month, locale?, dryRun? })
+ *     Calls computeInvoiceDraft, renders the PDF, persists the
+ *     invoice transactionally. Returns the persisted Invoice
+ *     (or the draft if dryRun=true).
+ *
+ * Design choices:
+ *
+ * - All compute is over UTC calendar days. "Active during day D"
+ *   means the tenant existed and was not fully suspended at some
+ *   moment in [D 00:00 UTC, D+1 00:00 UTC). This matches the
+ *   skill billing rule ("same-day toggle = 1 day") for monthly
+ *   fee proration too.
+ *
+ * - Computation is independent of persistence. Callers can preview
+ *   without committing (the admin generate form does this on first
+ *   click), and the same compute path is reused when committing.
+ *
+ * - The compute path collects warnings rather than throwing on
+ *   recoverable issues (missing LiteLLM team for a tenant, etc.).
+ *   The UI surfaces these to the admin before they confirm.
+ */
+
+import type {
+  Invoice,
+  InvoiceBillingSnapshot,
+  InvoiceDraft,
+  InvoiceLine,
+  InvoiceLineKind,
+  InvoicePaymentMethod,
+  PiecedTenant,
+  PlatformPricing,
+  SkillPricing,
+  TenantBillingLifecycle,
+  TenantSkillEvent,
+  TenantSuspensionEvent,
+} from "@/types";
+import {
+  createInvoice,
+  getInvoiceById,
+  getOrgBilling,
+  getOrgBillingConfig,
+  getPlatformPricing,
+  getTenantBillingLifecycle,
+  listSkillEventsForTenant,
+  listSkillPricing,
+  listSuspensionEventsForTenant,
+  tenantHasSetupFeeBilled,
+  tenantSkillHasBeenBilled,
+  updateInvoicePdf,
+} from "./db";
+import { listTenants } from "./k8s";
+import { getTeamSpendLogsV2 } from "./litellm";
+import { getUsage as getThreemaUsage } from "./threema-relay";
+import { renderInvoicePdf } from "./billing-pdf";
+import { sendInvoiceIssuedEmail } from "./email";
+import { formatLineDescription } from "./billing-i18n";
+
+// ---------------------------------------------------------------------------
+// Period helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the [periodStart, periodEnd] inclusive calendar dates for
+ * the given month, plus the count of days in the month.
+ *
+ * Dates returned as ISO `YYYY-MM-DD` strings (no time). Convertible
+ * to UTC midnight via `new Date(`${date}T00:00:00Z`)`.
+ */
+export function monthBounds(year: number, month: number): {
+  periodStart: string;
+  periodEnd: string;
+  daysInMonth: number;
+} {
+  if (month < 1 || month > 12) throw new Error(`Invalid month: ${month}`);
+  const start = new Date(Date.UTC(year, month - 1, 1));
+  // Day 0 of next month = last day of this month
+  const end = new Date(Date.UTC(year, month, 0));
+  return {
+    periodStart: start.toISOString().split("T")[0],
+    periodEnd: end.toISOString().split("T")[0],
+    daysInMonth: end.getUTCDate(),
+  };
+}
+
+function isoDate(d: Date): string {
+  return d.toISOString().split("T")[0];
+}
+
+function dueDate(periodEnd: string, netDays: number = 30): string {
+  // due_at = period_end + netDays
+  const d = new Date(`${periodEnd}T00:00:00Z`);
+  d.setUTCDate(d.getUTCDate() + netDays);
+  return isoDate(d);
+}
+
+// ---------------------------------------------------------------------------
+// Day-set computation (calendar-day model, UTC)
+// ---------------------------------------------------------------------------
+
+/**
+ * Iterates UTC calendar days in [periodStart, periodEnd] inclusive.
+ * Yields { date: 'YYYY-MM-DD', dayStartMs, dayEndMs } where dayEnd
+ * is exclusive (next-day-midnight UTC).
+ */
+function* iterDays(periodStart: string, periodEnd: string) {
+  const start = new Date(`${periodStart}T00:00:00Z`).getTime();
+  const end = new Date(`${periodEnd}T00:00:00Z`).getTime();
+  for (let t = start; t <= end; t += 86_400_000) {
+    yield {
+      date: isoDate(new Date(t)),
+      dayStartMs: t,
+      dayEndMs: t + 86_400_000,
+    };
+  }
+}
+
+/**
+ * Was the tenant "running" (created, not deleted, not suspended) at
+ * any moment in the half-open interval [dayStartMs, dayEndMs)?
+ *
+ * Inputs: tenant lifecycle and the timeline of suspension events
+ * sorted ascending by occurredAt.
+ *
+ * The state-at-day-start is reconstructed from suspension events
+ * BEFORE the day. If the count of suspension events before the day
+ * is odd, the tenant was suspended at day start (because we record
+ * suspend then resume, so an odd prefix-count means the last
+ * recorded transition is "suspended"). This is robust as long as
+ * events are correctly ordered.
+ *
+ * Actually we use the actual event kinds from the events list,
+ * not the parity heuristic — the heuristic is documentation for
+ * intuition.
+ */
+function activeDuringDay(
+  lifecycle: TenantBillingLifecycle,
+  suspensionEvents: TenantSuspensionEvent[],
+  dayStartMs: number,
+  dayEndMs: number
+): boolean {
+  // Lifecycle gate: tenant must have existed during some part of the day.
+  const createdMs = new Date(lifecycle.createdAt).getTime();
+  const deletedMs = lifecycle.deletedAt
+    ? new Date(lifecycle.deletedAt).getTime()
+    : Infinity;
+  if (createdMs >= dayEndMs) return false;
+  if (deletedMs <= dayStartMs) return false;
+  // Effective existence window within this day
+  const existsFrom = Math.max(createdMs, dayStartMs);
+  const existsTo = Math.min(deletedMs, dayEndMs);
+  if (existsFrom >= existsTo) return false;
+
+  // Determine suspended state at existsFrom by replaying events.
+  // Initial state at lifecycle.createdAt is 'running' (we don't
+  // record an explicit 'created → running' event; this is the
+  // implicit baseline).
+  let suspended = false;
+  for (const e of suspensionEvents) {
+    const ts = new Date(e.occurredAt).getTime();
+    if (ts > existsFrom) break;
+    suspended = e.eventKind === "suspended";
+  }
+
+  // Walk events from existsFrom to existsTo. If at any moment the
+  // tenant is running, the day counts.
+  if (!suspended) return true;
+  for (const e of suspensionEvents) {
+    const ts = new Date(e.occurredAt).getTime();
+    if (ts <= existsFrom) continue;
+    if (ts >= existsTo) break;
+    if (e.eventKind === "resumed") return true;
+  }
+  return false;
+}
+
+/**
+ * Was the skill 'enabled' at any moment in the day?
+ *
+ * Same shape as activeDuringDay but driven by skill events instead
+ * of suspension events.
+ *
+ * Important: callers must include events from before periodStart in
+ * `prevState` (state at day start), since a skill enabled three
+ * months ago and never disabled has no events in the billing
+ * window but is still enabled.
+ */
+function skillActiveDuringDay(
+  events: TenantSkillEvent[],
+  initiallyEnabled: boolean,
+  dayStartMs: number,
+  dayEndMs: number
+): boolean {
+  let enabled = initiallyEnabled;
+  // First, replay events that occurred AT OR BEFORE dayStartMs to
+  // get the state at day start.
+  for (const e of events) {
+    const ts = new Date(e.occurredAt).getTime();
+    if (ts > dayStartMs) break;
+    enabled = e.eventKind === "enabled";
+  }
+  if (enabled) return true;
+  // Walk events in [dayStart, dayEnd). If any 'enabled' event
+  // appears, the day counts.
+  for (const e of events) {
+    const ts = new Date(e.occurredAt).getTime();
+    if (ts <= dayStartMs) continue;
+    if (ts >= dayEndMs) break;
+    if (e.eventKind === "enabled") return true;
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Rounding
+// ---------------------------------------------------------------------------
+
+/** Round to 2dp, half-up. */
+function round2(n: number): number {
+  return Math.round(n * 100) / 100;
+}
+
+// ---------------------------------------------------------------------------
+// VAT logic
+// ---------------------------------------------------------------------------
+
+const EU_COUNTRIES = new Set([
+  "AT", "BE", "BG", "HR", "CY", "CZ", "DK", "EE", "FI", "FR",
+  "DE", "GR", "HU", "IE", "IT", "LV", "LT", "LU", "MT", "NL",
+  "PL", "PT", "RO", "SK", "SI", "ES", "SE",
+]);
+
+/**
+ * Determine VAT rate from billing address and the platform default.
+ * See README for the legal interpretation; this implements the
+ * defaults you confirmed:
+ *
+ *   - CH or LI:        platform_pricing.vat_rate_chli (default 8.10)
+ *   - EU + VAT number: 0% (reverse charge — B2B)
+ *   - EU without VAT:  CH MWST (B2C consumer, we charge our rate)
+ *   - other:           0% (export of services)
+ */
+function vatRateForAddress(
+  snapshot: InvoiceBillingSnapshot,
+  platformPricing: PlatformPricing
+): { rate: number; note: string | null } {
+  const country = snapshot.country?.toUpperCase().trim() ?? "";
+  if (country === "CH" || country === "LI") {
+    return { rate: platformPricing.vatRateChli, note: null };
+  }
+  if (EU_COUNTRIES.has(country)) {
+    if (snapshot.vatNumber && snapshot.vatNumber.trim().length > 0) {
+      return {
+        rate: 0,
+        note:
+          "Steuerschuldnerschaft des Leistungsempfängers / Reverse charge — VAT to be accounted for by the recipient.",
+      };
+    }
+    return { rate: platformPricing.vatRateChli, note: null };
+  }
+  return { rate: 0, note: "Export of services — VAT not applicable." };
+}
+
+// ---------------------------------------------------------------------------
+// Locale default
+// ---------------------------------------------------------------------------
+
+/**
+ * Pick a default invoice locale from the billing country. Admins
+ * can override at generation time. We default to German for
+ * CH/LI/AT/DE; French for FR/BE/LU; Italian for IT; English
+ * otherwise.
+ */
+export function defaultLocaleForCountry(country: string): string {
+  const c = (country || "").toUpperCase().trim();
+  if (["CH", "LI", "AT", "DE"].includes(c)) return "de";
+  if (["FR", "BE", "LU"].includes(c)) return "fr";
+  if (c === "IT") return "it";
+  return "en";
+}
+
+// ---------------------------------------------------------------------------
+// Tenant signal collectors
+// ---------------------------------------------------------------------------
+
+/**
+ * Sum AI usage spend for a tenant over the billing period via
+ * LiteLLM. Returns the CHF total (already in CHF — LiteLLM stores
+ * costs after the platform's USD→CHF conversion) and the request
+ * count for the metadata.
+ *
+ * Tolerates missing litellmTeamId on the tenant: such tenants are
+ * skipped and the warning is surfaced upstream.
+ */
+async function collectAiUsage(
+  tenant: PiecedTenant,
+  periodStart: string,
+  periodEnd: string
+): Promise<{ spendChf: number; requestCount: number } | null> {
+  const teamId = tenant.status?.litellmTeamId;
+  if (!teamId) return null;
+  const keyAlias = tenant.metadata.name;
+  let spendChf = 0;
+  let requestCount = 0;
+  let page = 1;
+  // 50-page cap matches the existing usage route's defensive cap.
+  while (page <= 50) {
+    const result = await getTeamSpendLogsV2(
+      teamId,
+      periodStart,
+      periodEnd,
+      page,
+      100,
+      keyAlias
+    );
+    const rows: any[] = result.data ?? [];
+    for (const r of rows) {
+      spendChf += Number(r.spend ?? 0);
+      requestCount += 1;
+    }
+    if (page >= (result.total_pages || 1)) break;
+    page++;
+  }
+  return { spendChf: round2(spendChf), requestCount };
+}
+
+/**
+ * Sum Threema messages (in + out) for the tenant over the period.
+ * Returns null if the relay refuses or the tenant has no Threema
+ * package — billing is skipped silently in that case.
+ */
+async function collectThreemaUsage(
+  tenant: PiecedTenant,
+  periodStart: string,
+  periodEnd: string
+): Promise<{ inCount: number; outCount: number } | null> {
+  const packages = tenant.spec.packages ?? [];
+  if (!packages.includes("threema")) return null;
+  // threema-relay.getUsage takes Date params, not strings, and
+  // returns a discriminated RelayResult<UsageBreakdown> — the
+  // `ok` discriminant must be checked before reading the totals.
+  // Period end is exclusive in the relay's API; pass the next-day
+  // midnight UTC to capture the full last day of the period.
+  const from = new Date(`${periodStart}T00:00:00Z`);
+  const to = new Date(`${periodEnd}T00:00:00Z`);
+  to.setUTCDate(to.getUTCDate() + 1);
+  const result = await getThreemaUsage(tenant.metadata.name, from, to).catch(
+    () => null
+  );
+  if (!result || !result.ok) return null;
+  return {
+    inCount: Number(result.totals?.in ?? 0),
+    outCount: Number(result.totals?.out ?? 0),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Per-tenant line builders
+// ---------------------------------------------------------------------------
+
+async function buildTenantLines(opts: {
+  tenant: PiecedTenant;
+  periodStart: string;
+  periodEnd: string;
+  daysInMonth: number;
+  platformPricing: PlatformPricing;
+  skillPricing: SkillPricing[];
+  locale: string;
+  warnings: string[];
+  displayOrderOffset: number;
+}): Promise<Omit<InvoiceLine, "id" | "invoiceId">[]> {
+  const {
+    tenant,
+    periodStart,
+    periodEnd,
+    daysInMonth,
+    platformPricing,
+    skillPricing,
+    locale,
+    warnings,
+  } = opts;
+  let displayOrder = opts.displayOrderOffset;
+  const tenantName = tenant.metadata.name;
+  const lines: Omit<InvoiceLine, "id" | "invoiceId">[] = [];
+
+  // Lifecycle & suspension events — required for monthly proration.
+  const lifecycle = await getTenantBillingLifecycle(tenantName);
+  if (!lifecycle) {
+    warnings.push(
+      `Tenant "${tenantName}" has no billing lifecycle row — run the Phase 1 backfill.`
+    );
+    return lines;
+  }
+
+  // Period interval in millis (extended by one day on each side as
+  // buffer for events that occur at month boundaries).
+  const periodStartMs = new Date(`${periodStart}T00:00:00Z`).getTime();
+  const periodEndMs = new Date(`${periodEnd}T00:00:00Z`).getTime() + 86_400_000;
+
+  const suspensionEvents = await listSuspensionEventsForTenant(
+    tenantName,
+    new Date(periodStartMs - 365 * 86_400_000), // look back a year for state-at-start
+    new Date(periodEndMs)
+  );
+
+  // --- tenant_monthly (prorated, suspended days excluded) -------------------
+  if (platformPricing.tenantMonthlyFeeChf > 0) {
+    let billableDays = 0;
+    let suspendedDays = 0;
+    for (const day of iterDays(periodStart, periodEnd)) {
+      if (activeDuringDay(lifecycle, suspensionEvents, day.dayStartMs, day.dayEndMs)) {
+        billableDays++;
+      } else {
+        // Distinguish "not yet existed / deleted" from "suspended"
+        // for the metadata audit trail. Cheap re-check.
+        const createdMs = new Date(lifecycle.createdAt).getTime();
+        const deletedMs = lifecycle.deletedAt
+          ? new Date(lifecycle.deletedAt).getTime()
+          : Infinity;
+        if (createdMs < day.dayEndMs && deletedMs > day.dayStartMs) {
+          suspendedDays++;
+        }
+      }
+    }
+    if (billableDays > 0) {
+      const unit = platformPricing.tenantMonthlyFeeChf / daysInMonth;
+      const amount = round2(unit * billableDays);
+      const metadata = {
+        billable_days: billableDays,
+        suspended_days: suspendedDays,
+        days_in_month: daysInMonth,
+      };
+      lines.push({
+        tenantName,
+        kind: "tenant_monthly",
+        description: formatLineDescription(
+          { kind: "tenant_monthly", tenantName, metadata },
+          locale
+        ),
+        quantity: billableDays,
+        unitLabel: "days",
+        unitPriceChf: round2(unit * 1e5) / 1e5,
+        amountChf: amount,
+        metadata,
+        displayOrder: displayOrder++,
+      });
+    }
+  }
+
+  // --- tenant_setup (first invoice only) -----------------------------------
+  if (platformPricing.tenantSetupFeeChf > 0) {
+    const alreadyBilled = await tenantHasSetupFeeBilled(tenantName);
+    if (!alreadyBilled) {
+      lines.push({
+        tenantName,
+        kind: "tenant_setup",
+        description: formatLineDescription(
+          { kind: "tenant_setup", tenantName, metadata: null },
+          locale
+        ),
+        quantity: 1,
+        unitLabel: null,
+        unitPriceChf: platformPricing.tenantSetupFeeChf,
+        amountChf: round2(platformPricing.tenantSetupFeeChf),
+        metadata: null,
+        displayOrder: displayOrder++,
+      });
+    }
+  }
+
+  // --- ai_usage --------------------------------------------------------------
+  const aiUsage = await collectAiUsage(tenant, periodStart, periodEnd).catch(
+    (e) => {
+      warnings.push(
+        `AI usage fetch failed for ${tenantName}: ${e instanceof Error ? e.message : String(e)}`
+      );
+      return null;
+    }
+  );
+  if (aiUsage === null && tenant.status?.litellmTeamId) {
+    // teamId exists but fetch returned null — already warned above
+  } else if (aiUsage === null) {
+    warnings.push(
+      `Tenant ${tenantName} has no LiteLLM team yet — AI usage skipped.`
+    );
+  } else if (aiUsage.spendChf > 0) {
+    const aiMetadata = {
+      litellm_key_alias: tenantName,
+      spend_chf: aiUsage.spendChf,
+      requests: aiUsage.requestCount,
+    };
+    lines.push({
+      tenantName,
+      kind: "ai_usage",
+      description: formatLineDescription(
+        { kind: "ai_usage", tenantName, metadata: aiMetadata },
+        locale
+      ),
+      quantity: 1,
+      unitLabel: null,
+      unitPriceChf: aiUsage.spendChf,
+      amountChf: aiUsage.spendChf,
+      metadata: aiMetadata,
+      displayOrder: displayOrder++,
+    });
+  }
+
+  // --- threema_messages -----------------------------------------------------
+  if (platformPricing.threemaMessageChf > 0) {
+    const threema = await collectThreemaUsage(tenant, periodStart, periodEnd);
+    if (threema && (threema.inCount + threema.outCount) > 0) {
+      const total = threema.inCount + threema.outCount;
+      const threemaMetadata = {
+        in_count: threema.inCount,
+        out_count: threema.outCount,
+        total_count: total,
+      };
+      lines.push({
+        tenantName,
+        kind: "threema_messages",
+        description: formatLineDescription(
+          { kind: "threema_messages", tenantName, metadata: threemaMetadata },
+          locale
+        ),
+        quantity: total,
+        unitLabel: "msgs",
+        unitPriceChf: platformPricing.threemaMessageChf,
+        amountChf: round2(total * platformPricing.threemaMessageChf),
+        metadata: threemaMetadata,
+        displayOrder: displayOrder++,
+      });
+    }
+  }
+
+  // --- skill_usage ----------------------------------------------------------
+  // For each priced skill, count distinct UTC days the skill was
+  // enabled during the period.
+  if (skillPricing.length > 0) {
+    // Fetch all skill events for the tenant within the period plus
+    // a long lookback so we can determine state-at-period-start.
+    // The state-at-day-start logic in skillActiveDuringDay walks
+    // these events forward.
+    const allEvents = await listSkillEventsForTenant(
+      tenantName,
+      new Date(0),
+      new Date(periodEndMs)
+    );
+    for (const sp of skillPricing) {
+      const skillEvents = allEvents.filter((e) => e.skillId === sp.skillId);
+      // Skip cheaply if no events ever existed for this skill on
+      // this tenant.
+      if (skillEvents.length === 0) continue;
+      // Initial state assumption: false. The very first event is
+      // always 'enabled' (we only record toggles, and the implicit
+      // pre-toggle state for a never-seen skill is 'disabled').
+      let billableDays = 0;
+      for (const day of iterDays(periodStart, periodEnd)) {
+        if (skillActiveDuringDay(skillEvents, false, day.dayStartMs, day.dayEndMs)) {
+          billableDays++;
+        }
+      }
+      if (billableDays > 0) {
+        // Setup fee fires once per (tenant, skill) — before the
+        // usage line so it appears above it on the PDF.
+        if (sp.setupFeeChf > 0) {
+          const alreadyBilled = await tenantSkillHasBeenBilled(
+            tenantName,
+            sp.skillId
+          );
+          if (!alreadyBilled) {
+            const setupMetadata = { skill_id: sp.skillId };
+            lines.push({
+              tenantName,
+              kind: "skill_setup",
+              description: formatLineDescription(
+                { kind: "skill_setup", tenantName, metadata: setupMetadata },
+                locale
+              ),
+              quantity: 1,
+              unitLabel: null,
+              unitPriceChf: sp.setupFeeChf,
+              amountChf: round2(sp.setupFeeChf),
+              metadata: setupMetadata,
+              displayOrder: displayOrder++,
+            });
+          }
+        }
+        const skillMetadata = {
+          skill_id: sp.skillId,
+          billable_days: billableDays,
+          event_count: skillEvents.length,
+        };
+        lines.push({
+          tenantName,
+          kind: "skill_usage",
+          description: formatLineDescription(
+            { kind: "skill_usage", tenantName, metadata: skillMetadata },
+            locale
+          ),
+          quantity: billableDays,
+          unitLabel: "days",
+          unitPriceChf: sp.dailyPriceChf,
+          amountChf: round2(billableDays * sp.dailyPriceChf),
+          metadata: skillMetadata,
+          displayOrder: displayOrder++,
+        });
+      }
+    }
+  }
+
+  return lines;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export async function computeInvoiceDraft(opts: {
+  zitadelOrgId: string;
+  year: number;
+  month: number;
+  locale?: string;
+  paymentMethod?: InvoicePaymentMethod;
+}): Promise<InvoiceDraft> {
+  const { zitadelOrgId, year, month } = opts;
+  const { periodStart, periodEnd, daysInMonth } = monthBounds(year, month);
+  const warnings: string[] = [];
+
+  // 1. Billing address. Required — without it we can't produce a
+  //    valid invoice.
+  const orgBilling = await getOrgBilling(zitadelOrgId);
+  if (!orgBilling) {
+    throw new Error(
+      `Org ${zitadelOrgId} has no billing address on file. ` +
+        `The customer must complete /settings/billing before an invoice can be issued.`
+    );
+  }
+  const snapshot: InvoiceBillingSnapshot = {
+    companyName: orgBilling.companyName,
+    streetAddress: orgBilling.streetAddress,
+    postalCode: orgBilling.postalCode,
+    city: orgBilling.city,
+    country: orgBilling.country,
+    vatNumber: orgBilling.vatNumber ?? null,
+    billingEmail: orgBilling.billingEmail,
+    notes: orgBilling.notes ?? null,
+  };
+
+  // 2. Platform pricing + skill prices.
+  const platformPricing = await getPlatformPricing();
+  const skillPricing = await listSkillPricing();
+
+  // 3. Find all tenants for this org. We list from K8s (source of
+  //    truth) and filter by the zitadel-org-id label.
+  const allTenants = await listTenants();
+  const orgTenants = allTenants.filter(
+    (t) => t.metadata.labels?.["pieced.ch/zitadel-org-id"] === zitadelOrgId
+  );
+  if (orgTenants.length === 0) {
+    warnings.push(`No tenants found for org ${zitadelOrgId}.`);
+  }
+
+  // 4. Build lines, grouped per tenant (display order preserved).
+  // Locale must be resolved before line construction since the
+  // descriptions are localized at compute time.
+  const locale = opts.locale ?? defaultLocaleForCountry(snapshot.country);
+  const lines: Omit<InvoiceLine, "id" | "invoiceId">[] = [];
+  let nextDisplayOrder = 0;
+  // Sort tenants by name for stable line ordering across regenerations.
+  orgTenants.sort((a, b) => a.metadata.name.localeCompare(b.metadata.name));
+  for (const tenant of orgTenants) {
+    const tenantLines = await buildTenantLines({
+      tenant,
+      periodStart,
+      periodEnd,
+      daysInMonth,
+      platformPricing,
+      skillPricing,
+      locale,
+      warnings,
+      displayOrderOffset: nextDisplayOrder,
+    });
+    lines.push(...tenantLines);
+    nextDisplayOrder += tenantLines.length;
+  }
+
+  // 5. Subtotal & VAT.
+  const subtotal = round2(lines.reduce((acc, l) => acc + l.amountChf, 0));
+  const vat = vatRateForAddress(snapshot, platformPricing);
+  const vatAmount = round2((subtotal * vat.rate) / 100);
+  const total = round2(subtotal + vatAmount);
+  if (vat.note) warnings.push(vat.note);
+
+  // 6. Payment method: prefer pay-by-invoice if the admin enabled
+  //    it for the org, otherwise default to invoice. Card payment
+  //    is wired in Phase 4 — for Phase 2 every invoice is 'invoice'.
+  const orgConfig = await getOrgBillingConfig(zitadelOrgId);
+  const paymentMethod: InvoicePaymentMethod =
+    opts.paymentMethod ?? (orgConfig.payByInvoice ? "invoice" : "invoice");
+
+  return {
+    zitadelOrgId,
+    periodStart,
+    periodEnd,
+    dueAt: dueDate(periodEnd, 30),
+    locale,
+    paymentMethod,
+    billingSnapshot: snapshot,
+    lines,
+    subtotalChf: subtotal,
+    vatRate: vat.rate,
+    vatAmountChf: vatAmount,
+    totalChf: total,
+    warnings,
+  };
+}
+
+/**
+ * Compute + render + persist in one step. If dryRun is true, the
+ * draft is returned without persisting and no PDF is rendered (the
+ * preview UI hits this).
+ */
+export async function generateInvoice(opts: {
+  zitadelOrgId: string;
+  year: number;
+  month: number;
+  locale?: string;
+  dryRun?: boolean;
+}): Promise<{ draft: InvoiceDraft; invoice: Invoice | null }> {
+  const draft = await computeInvoiceDraft(opts);
+  if (opts.dryRun) {
+    return { draft, invoice: null };
+  }
+  // Render the PDF first — if it fails, we never touch the DB.
+  // The PDF render needs the invoice number, which is allocated
+  // inside createInvoice's transaction. To keep the PDF rendering
+  // outside the DB transaction (it can be slow), we render with a
+  // placeholder number, allocate the real number inside the tx,
+  // then re-render? No — instead we generate a temporary draft
+  // number for the PDF and accept that the displayed number on
+  // the PDF matches what we'll persist (because the allocator is
+  // serialized).
+  //
+  // Practical approach: render the PDF inside createInvoice's tx,
+  // immediately after allocation. This is fine because react-pdf
+  // is reasonably fast (~50–200 ms for a typical invoice) and
+  // happens once per invoice.
+  //
+  // To avoid restructuring createInvoice, we do this in two
+  // passes: (1) reserve a number via createInvoice with a
+  // placeholder PDF; (2) render with the real number; (3) UPDATE
+  // pdf_data. The trade-off is two write trips but keeps the code
+  // shape simple. We accept it.
+  //
+  // Reasoning behind two-pass: if PDF render is moved inside the
+  // tx and fails (font missing, etc.), the allocated counter rolls
+  // back — good. But it also means the connection is held during
+  // render. At v1 scale that's fine; the choice is reversible.
+
+  // Pass 1: allocate number + persist with empty PDF.
+  const placeholder = await createInvoice(draft, null, null);
+  try {
+    const pdfBuffer = await renderInvoicePdf(
+      placeholder,
+      draft.lines.map((l, i) => ({
+        ...l,
+        id: `tmp-${i}`,
+        invoiceId: placeholder.id,
+      }))
+    );
+    const filename = `${placeholder.invoiceNumber}.pdf`;
+    // Pass 2: store the PDF bytes.
+    await updateInvoicePdf(placeholder.id, pdfBuffer, filename);
+    const finalInvoice = await getInvoiceById(placeholder.id);
+
+    // Phase 3: best-effort notification to the billing contact.
+    // We send AFTER the PDF is fully persisted (so the deep link
+    // in the email immediately resolves to a downloadable PDF) but
+    // BEFORE returning, since the cron caller doesn't otherwise
+    // know to trigger this. Failure is logged, never thrown — a
+    // mail-server hiccup must not roll back an issued invoice.
+    // The recipient is the billing email captured in the invoice
+    // snapshot (immutable; reflects who was on file at issue time).
+    try {
+      const settled = finalInvoice ?? placeholder;
+      const snapshot = settled.billingSnapshot;
+      if (snapshot.billingEmail) {
+        const supportedLocales: Array<"en" | "de" | "fr" | "it"> = [
+          "en", "de", "fr", "it",
+        ];
+        const locale = supportedLocales.includes(settled.locale as any)
+          ? (settled.locale as "en" | "de" | "fr" | "it")
+          : "de";
+        await sendInvoiceIssuedEmail({
+          to: snapshot.billingEmail,
+          contactName: snapshot.companyName, // no separate contact-name field
+          companyName: snapshot.companyName,
+          invoiceNumber: settled.invoiceNumber,
+          totalChf: settled.totalChf,
+          currency: "CHF",
+          dueAt: settled.dueAt,
+          lineCount: draft.lines.length,
+          periodStart: settled.periodStart,
+          periodEnd: settled.periodEnd,
+          locale,
+        });
+      } else {
+        console.warn(
+          `Invoice ${settled.invoiceNumber} issued but billing snapshot has no email — notification skipped.`
+        );
+      }
+    } catch (e) {
+      console.error(
+        `Invoice ${placeholder.invoiceNumber} issued; notification email failed:`,
+        e
+      );
+    }
+
+    return { draft, invoice: finalInvoice ?? placeholder };
+  } catch (e) {
+    // Render failed — leave the persisted row in place so admin can
+    // inspect it, but surface the error.
+    throw new Error(
+      `Invoice ${placeholder.invoiceNumber} persisted but PDF rendering failed: ${
+        e instanceof Error ? e.message : String(e)
+      }. Use the admin "delete invoice" tool to clean up if needed.`
+    );
+  }
+}

src/lib/email.ts

@@ -11,6 +11,17 @@
  *   SMTP_PASS                  — App Password
  *   SMTP_FROM                  — e.g. "PieCed <noreply@pieced.ch>"
  *   ADMIN_NOTIFICATION_EMAIL   — e.g. admin@pieced.ch (optional)
+ *   SUPPORT_CONTACT_EMAIL      — e.g. support@pieced.ch (optional)
+ *                                 Customer-facing address for "have
+ *                                 questions?" follow-ups in
+ *                                 transactional emails. The from
+ *                                 address itself (SMTP_USER) is
+ *                                 typically a noreply mailbox, so we
+ *                                 don't tell customers to "reply to
+ *                                 this email" — instead we point them
+ *                                 at this monitored address. If
+ *                                 unset, the contact-prompt line is
+ *                                 simply omitted from emails.
  */
 
 import nodemailer from "nodemailer";
@@ -42,6 +53,12 @@ function getFrom(): string {
   );
 }
 
+/** Returns the customer-facing support email address, or null if unset. */
+function getSupportContactEmail(): string | null {
+  const v = process.env.SUPPORT_CONTACT_EMAIL?.trim();
+  return v && v.length > 0 ? v : null;
+}
+
 /**
  * Escape HTML entities to prevent injection in HTML emails.
  */
@@ -125,6 +142,21 @@ export async function sendRejectionEmail(
          </div>`
       : "";
 
+    const supportEmail = getSupportContactEmail();
+    // The customer here is rejected pre-onboarding — they don't yet
+    // have a portal account, so we can't send them to /support.
+    // Instead point at the configured support address (if set).
+    // If unset (e.g. early pilot before a support inbox exists), we
+    // omit the follow-up line entirely rather than promise something
+    // that goes nowhere — telling the customer to "reply to this
+    // email" would be misleading because we send from a noreply box.
+    const contactLineText = supportEmail
+      ? `If you have questions or would like to discuss this further, please contact us at ${supportEmail}.`
+      : "";
+    const contactLineHtml = supportEmail
+      ? `<p>If you have questions or would like to discuss this further, please contact us at <a href="mailto:${escapeHtml(supportEmail)}" style="color: #3b82f6;">${escapeHtml(supportEmail)}</a>.</p>`
+      : "";
+
     await getTransporter().sendMail({
       from: getFrom(),
       to,
@@ -134,18 +166,20 @@ export async function sendRejectionEmail(
         "",
         `Thank you for your interest in PieCed IT. Unfortunately, we were unable to approve your onboarding request for ${companyName} at this time.`,
         notesBlock,
-        "If you have questions or would like to discuss this further, please reply to this email.",
+        contactLineText,
         "",
         "Best regards,",
         "PieCed IT",
-      ].join("\n"),
+      ]
+        .filter((s) => s !== "")
+        .join("\n"),
       html: `
         <div style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; max-width: 560px; margin: 0 auto; color: #e0e0e0; background: #1a1a1a; padding: 32px; border-radius: 12px;">
           <h2 style="color: #ffffff; margin-top: 0;">Update on your onboarding request</h2>
           <p>Hello ${safeName},</p>
           <p>Thank you for your interest in PieCed IT. Unfortunately, we were unable to approve your onboarding request for <strong>${safeCompany}</strong> at this time.</p>
           ${notesHtml}
-          <p>If you have questions or would like to discuss this further, please reply to this email.</p>
+          ${contactLineHtml}
           <hr style="border: none; border-top: 1px solid #333; margin: 24px 0;" />
           <p style="color: #666; font-size: 12px;">PieCed IT — Hosted on-premises in Switzerland</p>
         </div>
@@ -237,6 +271,15 @@ export async function sendResumeRejectionEmail(
          </div>`
       : "";
 
+    // The customer has portal access (their tenant exists, they
+    // just had a resume request rejected), so direct them to the
+    // support ticket system for follow-up. We never tell them to
+    // "reply to this email" because the from address is a noreply
+    // mailbox.
+    const contactLineText =
+      "If you have questions, open a support ticket at https://app.pieced.ch/support.";
+    const contactLineHtml = `<p>If you have questions, <a href="https://app.pieced.ch/support" style="color: #3b82f6;">open a support ticket</a>.</p>`;
+
     await getTransporter().sendMail({
       from: getFrom(),
       to,
@@ -248,7 +291,7 @@ export async function sendResumeRejectionEmail(
         notesBlock,
         "Your tenant remains suspended. As a reminder, your data is preserved for 60 days from the original cancellation date, after which it will be permanently deleted. You can submit a new reactivation request at any time before then.",
         "",
-        "If you have questions, please reply to this email.",
+        contactLineText,
         "",
         "Best regards,",
         "PieCed IT",
@@ -260,7 +303,7 @@ export async function sendResumeRejectionEmail(
           <p>Thank you for your reactivation request for <strong>${safeCompany}</strong>. Unfortunately, we were unable to approve it at this time.</p>
           ${notesHtml}
           <p>Your tenant remains suspended. As a reminder, your data is preserved for 60 days from the original cancellation date, after which it will be permanently deleted. You can submit a new reactivation request at any time before then.</p>
-          <p>If you have questions, please reply to this email.</p>
+          ${contactLineHtml}
           <hr style="border: none; border-top: 1px solid #333; margin: 24px 0;" />
           <p style="color: #666; font-size: 12px;">PieCed IT — Hosted on-premises in Switzerland</p>
         </div>
@@ -318,3 +361,656 @@ export async function sendAdminNotificationEmail(
     console.error("Failed to send admin notification email:", err);
   }
 }
+
+// ---------------------------------------------------------------------------
+// Feature 6: resume-request admin notification
+// ---------------------------------------------------------------------------
+
+/**
+ * Notify the admin distribution list that a customer has requested
+ * reactivation of a suspended tenant. Distinct from the onboarding
+ * notification because the action consequences differ (admin
+ * approving a resume just unsuspends an existing tenant; no
+ * provisioning runs), and because the customer's note — explaining
+ * why they want reactivation — is meaningful context for the admin
+ * triaging the queue.
+ *
+ * Skipped silently if ADMIN_NOTIFICATION_EMAIL isn't set, matching
+ * the pattern of the other admin notification functions.
+ */
+export async function sendResumeRequestAdminNotificationEmail(params: {
+  tenantName: string;
+  companyName: string;
+  contactName: string;
+  contactEmail: string;
+  customerNotes?: string | null;
+}): Promise<void> {
+  const adminEmail = process.env.ADMIN_NOTIFICATION_EMAIL;
+  if (!adminEmail) return;
+
+  const safeCompany = escapeHtml(params.companyName);
+  const safeName = escapeHtml(params.contactName);
+  const safeEmail = escapeHtml(params.contactEmail);
+  const safeTenant = escapeHtml(params.tenantName);
+  const safeNotes = params.customerNotes ? escapeHtml(params.customerNotes) : "";
+
+  const noteText = params.customerNotes
+    ? `\nCustomer's note:\n${params.customerNotes}\n`
+    : "";
+  const noteHtml = safeNotes
+    ? `<div style="background: #2a2a2a; border-left: 3px solid #3b82f6; padding: 12px 16px; border-radius: 6px; margin: 16px 0; white-space: pre-wrap;">
+         <p style="color: #ccc; font-size: 13px; margin: 0 0 8px 0;"><strong>Customer's note:</strong></p>
+         <p style="color: #e0e0e0; font-size: 13px; margin: 0;">${safeNotes}</p>
+       </div>`
+    : "";
+
+  try {
+    await getTransporter().sendMail({
+      from: getFrom(),
+      to: adminEmail,
+      subject: `Reactivation request: ${params.companyName}`,
+      text: [
+        `A customer has requested reactivation of a suspended tenant.`,
+        "",
+        `Company: ${params.companyName}`,
+        `Tenant:  ${params.tenantName}`,
+        `Contact: ${params.contactName} (${params.contactEmail})`,
+        noteText,
+        `Review at https://app.pieced.ch/admin`,
+      ]
+        .filter((s) => s !== "")
+        .join("\n"),
+      html: `
+        <div style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; max-width: 560px; margin: 0 auto; color: #e0e0e0; background: #1a1a1a; padding: 32px; border-radius: 12px;">
+          <h2 style="color: #ffffff; margin-top: 0;">Reactivation request</h2>
+          <p>A customer has requested reactivation of a suspended tenant.</p>
+          <table style="color: #ccc; font-size: 14px; margin: 16px 0;">
+            <tr><td style="padding: 4px 12px 4px 0; color: #888;">Company:</td><td>${safeCompany}</td></tr>
+            <tr><td style="padding: 4px 12px 4px 0; color: #888;">Tenant:</td><td style="font-family: monospace;">${safeTenant}</td></tr>
+            <tr><td style="padding: 4px 12px 4px 0; color: #888;">Contact:</td><td>${safeName} (${safeEmail})</td></tr>
+          </table>
+          ${noteHtml}
+          <p>
+            <a href="https://app.pieced.ch/admin" style="display: inline-block; padding: 10px 24px; background: #3b82f6; color: #ffffff; text-decoration: none; border-radius: 8px; font-weight: 500;">
+              Review Request
+            </a>
+          </p>
+          <hr style="border: none; border-top: 1px solid #333; margin: 24px 0;" />
+          <p style="color: #666; font-size: 12px;">PieCed IT — Admin notification</p>
+        </div>
+      `,
+    });
+  } catch (err) {
+    console.error("Failed to send resume request admin notification:", err);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Feature 5: support ticket emails
+// ---------------------------------------------------------------------------
+
+/**
+ * Email subject prefix that helps customers thread tickets in their
+ * mail client. We don't have inbound email processing — replies via
+ * email back to us go nowhere — but the prefix is still useful for
+ * the customer's own organisation. The id is shortened to 8 chars
+ * for human readability; collisions on the truncated form within a
+ * single user's inbox are vanishingly unlikely.
+ */
+function ticketSubjectPrefix(ticketId: string): string {
+  return `[PieCed Support #${ticketId.slice(0, 8)}]`;
+}
+
+const STATUS_LABELS_EN: Record<string, string> = {
+  open: "Open",
+  in_progress: "In progress",
+  waiting_for_customer: "Waiting for your reply",
+  resolved: "Resolved",
+  reopened: "Reopened",
+};
+
+/**
+ * Sent to the customer when they create a ticket — confirmation
+ * that we received it and a copy of the ticket id for their records.
+ */
+export async function sendSupportTicketCreatedEmail(params: {
+  to: string;
+  contactName: string;
+  ticketId: string;
+  title: string;
+}): Promise<void> {
+  const safeName = escapeHtml(params.contactName);
+  const safeTitle = escapeHtml(params.title);
+  const shortId = params.ticketId.slice(0, 8);
+  const subject = `${ticketSubjectPrefix(params.ticketId)} ${params.title}`;
+
+  try {
+    await getTransporter().sendMail({
+      from: getFrom(),
+      to: params.to,
+      subject,
+      text: [
+        `Hello ${params.contactName},`,
+        "",
+        `We've received your support request "${params.title}" (reference #${shortId}).`,
+        "",
+        "Our team will review and respond as soon as possible. You can track the status and reply at https://app.pieced.ch/support.",
+        "",
+        "Best regards,",
+        "PieCed IT",
+      ].join("\n"),
+      html: `
+        <div style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; max-width: 560px; margin: 0 auto; color: #e0e0e0; background: #1a1a1a; padding: 32px; border-radius: 12px;">
+          <h2 style="color: #ffffff; margin-top: 0;">Support request received</h2>
+          <p>Hello ${safeName},</p>
+          <p>We've received your support request <strong>"${safeTitle}"</strong> (reference #${shortId}).</p>
+          <p>Our team will review and respond as soon as possible.</p>
+          <p>
+            <a href="https://app.pieced.ch/support" style="display: inline-block; padding: 10px 24px; background: #3b82f6; color: #ffffff; text-decoration: none; border-radius: 8px; font-weight: 500;">
+              View ticket
+            </a>
+          </p>
+          <hr style="border: none; border-top: 1px solid #333; margin: 24px 0;" />
+          <p style="color: #666; font-size: 12px;">PieCed IT — Hosted on-premises in Switzerland</p>
+        </div>
+      `,
+    });
+  } catch (err) {
+    console.error("Failed to send support ticket creation email:", err);
+  }
+}
+
+/**
+ * Sent to the customer when an admin replies to one of their tickets.
+ * Includes the body of the reply inline so the customer can read it
+ * without clicking through (especially useful on mobile).
+ */
+export async function sendSupportTicketReplyEmail(params: {
+  to: string;
+  contactName: string;
+  ticketId: string;
+  title: string;
+  authorName: string;
+  body: string;
+}): Promise<void> {
+  const safeName = escapeHtml(params.contactName);
+  const safeTitle = escapeHtml(params.title);
+  const safeAuthor = escapeHtml(params.authorName);
+  const safeBody = escapeHtml(params.body);
+  const shortId = params.ticketId.slice(0, 8);
+  const subject = `${ticketSubjectPrefix(params.ticketId)} Re: ${params.title}`;
+
+  try {
+    await getTransporter().sendMail({
+      from: getFrom(),
+      to: params.to,
+      subject,
+      text: [
+        `Hello ${params.contactName},`,
+        "",
+        `${params.authorName} replied to your ticket "${params.title}" (#${shortId}):`,
+        "",
+        params.body,
+        "",
+        "Reply or follow up at https://app.pieced.ch/support.",
+        "",
+        "Best regards,",
+        "PieCed IT",
+      ].join("\n"),
+      html: `
+        <div style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; max-width: 560px; margin: 0 auto; color: #e0e0e0; background: #1a1a1a; padding: 32px; border-radius: 12px;">
+          <h2 style="color: #ffffff; margin-top: 0;">New reply on your ticket</h2>
+          <p>Hello ${safeName},</p>
+          <p><strong>${safeAuthor}</strong> replied to your ticket <strong>"${safeTitle}"</strong> (#${shortId}):</p>
+          <div style="background: #2a2a2a; border-left: 3px solid #3b82f6; padding: 12px 16px; border-radius: 6px; margin: 16px 0; white-space: pre-wrap;">
+            ${safeBody}
+          </div>
+          <p>
+            <a href="https://app.pieced.ch/support" style="display: inline-block; padding: 10px 24px; background: #3b82f6; color: #ffffff; text-decoration: none; border-radius: 8px; font-weight: 500;">
+              View ticket
+            </a>
+          </p>
+          <hr style="border: none; border-top: 1px solid #333; margin: 24px 0;" />
+          <p style="color: #666; font-size: 12px;">PieCed IT — Hosted on-premises in Switzerland</p>
+        </div>
+      `,
+    });
+  } catch (err) {
+    console.error("Failed to send support ticket reply email:", err);
+  }
+}
+
+/**
+ * Sent to the customer when an admin changes status without a comment.
+ * If the same admin action included a comment, they'd get the
+ * reply email instead — caller decides which to send.
+ */
+export async function sendSupportTicketStatusEmail(params: {
+  to: string;
+  contactName: string;
+  ticketId: string;
+  title: string;
+  newStatus: string;
+}): Promise<void> {
+  const safeName = escapeHtml(params.contactName);
+  const safeTitle = escapeHtml(params.title);
+  const statusLabel = STATUS_LABELS_EN[params.newStatus] ?? params.newStatus;
+  const shortId = params.ticketId.slice(0, 8);
+  const subject = `${ticketSubjectPrefix(params.ticketId)} Status: ${statusLabel}`;
+
+  try {
+    await getTransporter().sendMail({
+      from: getFrom(),
+      to: params.to,
+      subject,
+      text: [
+        `Hello ${params.contactName},`,
+        "",
+        `The status of your ticket "${params.title}" (#${shortId}) has been updated to: ${statusLabel}.`,
+        "",
+        "View details and respond if needed at https://app.pieced.ch/support.",
+        "",
+        "Best regards,",
+        "PieCed IT",
+      ].join("\n"),
+      html: `
+        <div style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; max-width: 560px; margin: 0 auto; color: #e0e0e0; background: #1a1a1a; padding: 32px; border-radius: 12px;">
+          <h2 style="color: #ffffff; margin-top: 0;">Ticket status update</h2>
+          <p>Hello ${safeName},</p>
+          <p>The status of your ticket <strong>"${safeTitle}"</strong> (#${shortId}) has been updated to:</p>
+          <p style="font-size: 18px; color: #3b82f6; font-weight: 600;">${escapeHtml(statusLabel)}</p>
+          <p>
+            <a href="https://app.pieced.ch/support" style="display: inline-block; padding: 10px 24px; background: #3b82f6; color: #ffffff; text-decoration: none; border-radius: 8px; font-weight: 500;">
+              View ticket
+            </a>
+          </p>
+          <hr style="border: none; border-top: 1px solid #333; margin: 24px 0;" />
+          <p style="color: #666; font-size: 12px;">PieCed IT — Hosted on-premises in Switzerland</p>
+        </div>
+      `,
+    });
+  } catch (err) {
+    console.error("Failed to send support ticket status email:", err);
+  }
+}
+
+/**
+ * Notify the platform admin distribution list of a new ticket OR a
+ * customer reply. Mirror of sendAdminNotificationEmail's pattern —
+ * uses the same ADMIN_NOTIFICATION_EMAIL env var.
+ *
+ * Two trigger reasons supported:
+ *  - 'created'  → new ticket from a customer
+ *  - 'replied'  → customer replied to existing ticket (we want admin
+ *                 visibility, e.g. to know the ticket needs another
+ *                 round of attention)
+ */
+export async function sendSupportAdminNotificationEmail(params: {
+  reason: "created" | "replied";
+  ticketId: string;
+  title: string;
+  contactName: string;
+  contactEmail: string;
+  body?: string; // The new message content (description on create, comment body on reply)
+  category?: string;
+}): Promise<void> {
+  const adminEmail = process.env.ADMIN_NOTIFICATION_EMAIL;
+  if (!adminEmail) {
+    console.warn(
+      "ADMIN_NOTIFICATION_EMAIL not set; skipping admin support notification"
+    );
+    return;
+  }
+  const safeContact = escapeHtml(params.contactName);
+  const safeContactEmail = escapeHtml(params.contactEmail);
+  const safeTitle = escapeHtml(params.title);
+  const safeBody = params.body ? escapeHtml(params.body) : "";
+  const shortId = params.ticketId.slice(0, 8);
+
+  const subjectVerb = params.reason === "created" ? "New" : "Reply on";
+  const subject = `${ticketSubjectPrefix(params.ticketId)} ${subjectVerb}: ${params.title}`;
+
+  const headlineHtml =
+    params.reason === "created"
+      ? `<h2 style="color: #ffffff; margin-top: 0;">New support ticket</h2>`
+      : `<h2 style="color: #ffffff; margin-top: 0;">Customer replied on ticket</h2>`;
+
+  try {
+    await getTransporter().sendMail({
+      from: getFrom(),
+      to: adminEmail,
+      subject,
+      text: [
+        params.reason === "created"
+          ? "A new support ticket was opened:"
+          : "A customer replied to a support ticket:",
+        "",
+        `From:     ${params.contactName} <${params.contactEmail}>`,
+        `Ticket:   ${params.title} (#${shortId})`,
+        params.category ? `Category: ${params.category}` : "",
+        "",
+        params.body ? "Message:" : "",
+        params.body ?? "",
+        "",
+        `View at https://app.pieced.ch/support/${params.ticketId}`,
+      ]
+        .filter((s) => s !== "")
+        .join("\n"),
+      html: `
+        <div style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; max-width: 560px; margin: 0 auto; color: #e0e0e0; background: #1a1a1a; padding: 32px; border-radius: 12px;">
+          ${headlineHtml}
+          <table style="width:100%; font-size: 13px; color: #aaa; margin-bottom: 16px;">
+            <tr><td style="padding: 4px 0; width: 100px;">From</td><td style="padding: 4px 0; color: #fff;">${safeContact} &lt;${safeContactEmail}&gt;</td></tr>
+            <tr><td style="padding: 4px 0;">Title</td><td style="padding: 4px 0; color: #fff;">${safeTitle} <span style="color: #666;">(#${shortId})</span></td></tr>
+            ${params.category ? `<tr><td style="padding: 4px 0;">Category</td><td style="padding: 4px 0; color: #fff;">${escapeHtml(params.category)}</td></tr>` : ""}
+          </table>
+          ${
+            params.body
+              ? `<div style="background: #2a2a2a; border-left: 3px solid #3b82f6; padding: 12px 16px; border-radius: 6px; margin: 16px 0; white-space: pre-wrap;">${safeBody}</div>`
+              : ""
+          }
+          <p>
+            <a href="https://app.pieced.ch/support/${params.ticketId}" style="display: inline-block; padding: 10px 24px; background: #3b82f6; color: #ffffff; text-decoration: none; border-radius: 8px; font-weight: 500;">
+              Open in admin queue
+            </a>
+          </p>
+          <hr style="border: none; border-top: 1px solid #333; margin: 24px 0;" />
+          <p style="color: #666; font-size: 12px;">PieCed IT — Admin notification</p>
+        </div>
+      `,
+    });
+  } catch (err) {
+    console.error("Failed to send admin support notification:", err);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Skill activation requests — Phase 2.5
+// ---------------------------------------------------------------------------
+//
+// Three notifications:
+//
+//   sendSkillActivationAdminNotification  — to ADMIN_NOTIFICATION_EMAIL
+//                                           when a customer requests a
+//                                           flagged skill.
+//
+//   sendSkillActivationApprovalEmail      — to the customer, on approve.
+//
+//   sendSkillActivationRejectionEmail     — to the customer, on reject,
+//                                           including the admin's reason.
+//
+// All three follow the existing patterns in this file (HTML + plaintext,
+// escaped vars, best-effort with errors logged not thrown).
+
+/**
+ * Notify admin (ADMIN_NOTIFICATION_EMAIL) that a customer has
+ * requested activation of a manual-setup skill. The skill name +
+ * tenant + requester are all included so admin can act without
+ * loading the portal.
+ */
+export async function sendSkillActivationAdminNotification(params: {
+  tenantName: string;
+  skillId: string;
+  skillName: string;
+  requesterEmail: string;
+  requesterName: string;
+  companyName: string | null;
+}): Promise<void> {
+  const adminEmail = process.env.ADMIN_NOTIFICATION_EMAIL;
+  if (!adminEmail) return;
+  const safeTenant = escapeHtml(params.tenantName);
+  const safeSkillId = escapeHtml(params.skillId);
+  const safeSkillName = escapeHtml(params.skillName);
+  const safeRequester = escapeHtml(params.requesterName);
+  const safeRequesterEmail = escapeHtml(params.requesterEmail);
+  const safeCompany = params.companyName
+    ? escapeHtml(params.companyName)
+    : "—";
+  try {
+    await getTransporter().sendMail({
+      from: getFrom(),
+      to: adminEmail,
+      subject: `[PieCed] Skill activation requested — ${params.skillName} on ${params.tenantName}`,
+      text: [
+        "A customer has requested activation of a manual-setup skill.",
+        "",
+        `Skill:       ${params.skillName} (${params.skillId})`,
+        `Tenant:      ${params.tenantName}`,
+        `Organization:${params.companyName ?? "—"}`,
+        `Requested by:${params.requesterName} <${params.requesterEmail}>`,
+        "",
+        "Review and act in the admin queue:",
+        "https://app.pieced.ch/admin/skills/pending",
+      ].join("\n"),
+      html: `
+        <div style="font-family: -apple-system, BlinkMacSystemFont, sans-serif; max-width: 560px; padding: 24px; background: #1a1a1a; color: #e5e5e5;">
+          <h2 style="margin: 0 0 16px; color: #10B981;">Skill activation requested</h2>
+          <p>A customer has requested activation of a manual-setup skill.</p>
+          <table style="width:100%; border-collapse: collapse; margin: 12px 0;">
+            <tr><td style="color:#888; padding:4px 0;">Skill</td><td>${safeSkillName} (<code>${safeSkillId}</code>)</td></tr>
+            <tr><td style="color:#888; padding:4px 0;">Tenant</td><td><code>${safeTenant}</code></td></tr>
+            <tr><td style="color:#888; padding:4px 0;">Organization</td><td>${safeCompany}</td></tr>
+            <tr><td style="color:#888; padding:4px 0;">Requested by</td><td>${safeRequester} &lt;${safeRequesterEmail}&gt;</td></tr>
+          </table>
+          <p>
+            <a href="https://app.pieced.ch/admin/skills/pending" style="display:inline-block; padding:10px 24px; background:#10B981; color:#fff; text-decoration:none; border-radius:8px; font-weight:500;">
+              Open admin queue
+            </a>
+          </p>
+          <hr style="border:none; border-top:1px solid #333; margin:24px 0;" />
+          <p style="color:#666; font-size:12px;">PieCed IT — Admin notification</p>
+        </div>
+      `,
+    });
+  } catch (err) {
+    console.error("Failed to send skill activation admin notification:", err);
+  }
+}
+
+export async function sendSkillActivationApprovalEmail(params: {
+  to: string;
+  contactName: string;
+  skillName: string;
+  tenantName: string;
+}): Promise<void> {
+  const safeName = escapeHtml(params.contactName);
+  const safeSkill = escapeHtml(params.skillName);
+  const safeTenant = escapeHtml(params.tenantName);
+  try {
+    await getTransporter().sendMail({
+      from: getFrom(),
+      to: params.to,
+      subject: `Your skill activation has been approved — ${params.skillName}`,
+      text: [
+        `Hello ${params.contactName},`,
+        "",
+        `Good news — your request to activate "${params.skillName}" on tenant ${params.tenantName} has been approved and the skill is now live.`,
+        "",
+        "You can manage it from your tenant settings.",
+        "",
+        "Best regards,",
+        "PieCed IT",
+      ].join("\n"),
+      html: `
+        <div style="font-family: -apple-system, BlinkMacSystemFont, sans-serif; max-width:560px; padding:24px; background:#1a1a1a; color:#e5e5e5;">
+          <h2 style="margin:0 0 16px; color:#10B981;">Skill approved & activated</h2>
+          <p>Hello ${safeName},</p>
+          <p>Your request to activate <strong>${safeSkill}</strong> on tenant <code>${safeTenant}</code> has been approved and the skill is now live.</p>
+          <p>You can manage it from your tenant settings.</p>
+          <p>
+            <a href="https://app.pieced.ch/tenants/${encodeURIComponent(params.tenantName)}" style="display:inline-block; padding:10px 24px; background:#10B981; color:#fff; text-decoration:none; border-radius:8px; font-weight:500;">
+              Open tenant
+            </a>
+          </p>
+          <hr style="border:none; border-top:1px solid #333; margin:24px 0;" />
+          <p style="color:#666; font-size:12px;">PieCed IT</p>
+        </div>
+      `,
+    });
+  } catch (err) {
+    console.error("Failed to send skill activation approval email:", err);
+  }
+}
+
+export async function sendSkillActivationRejectionEmail(params: {
+  to: string;
+  contactName: string;
+  skillName: string;
+  tenantName: string;
+  reason: string;
+}): Promise<void> {
+  const safeName = escapeHtml(params.contactName);
+  const safeSkill = escapeHtml(params.skillName);
+  const safeTenant = escapeHtml(params.tenantName);
+  const safeReason = escapeHtml(params.reason);
+  try {
+    await getTransporter().sendMail({
+      from: getFrom(),
+      to: params.to,
+      subject: `Update on your skill activation request — ${params.skillName}`,
+      text: [
+        `Hello ${params.contactName},`,
+        "",
+        `We were unable to approve your request to activate "${params.skillName}" on tenant ${params.tenantName}.`,
+        "",
+        "Reason from our team:",
+        params.reason,
+        "",
+        "You can try again from your tenant settings once the matter is resolved.",
+        "",
+        "Best regards,",
+        "PieCed IT",
+      ].join("\n"),
+      html: `
+        <div style="font-family: -apple-system, BlinkMacSystemFont, sans-serif; max-width:560px; padding:24px; background:#1a1a1a; color:#e5e5e5;">
+          <h2 style="margin:0 0 16px; color:#ef4444;">Activation request not approved</h2>
+          <p>Hello ${safeName},</p>
+          <p>We were unable to approve your request to activate <strong>${safeSkill}</strong> on tenant <code>${safeTenant}</code>.</p>
+          <div style="background:#2a2a2a; border-left:3px solid #ef4444; padding:12px 16px; border-radius:6px; margin:16px 0;">
+            <p style="color:#ccc; font-size:13px; margin:0;"><strong>Reason from our team:</strong></p>
+            <p style="color:#aaa; font-size:13px; margin:8px 0 0 0; white-space:pre-wrap;">${safeReason}</p>
+          </div>
+          <p>You can try again from your tenant settings once the matter is resolved.</p>
+          <hr style="border:none; border-top:1px solid #333; margin:24px 0;" />
+          <p style="color:#666; font-size:12px;">PieCed IT</p>
+        </div>
+      `,
+    });
+  } catch (err) {
+    console.error("Failed to send skill activation rejection email:", err);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Invoice issuance — Phase 3
+// ---------------------------------------------------------------------------
+
+/**
+ * Notify the billing contact when a new invoice has been issued.
+ * Includes a brief summary (total + due date + line count) so the
+ * recipient can triage without opening the portal, plus a deep
+ * link to /billing/<invoice number> where they can download the
+ * PDF. The PDF itself is NOT attached — it lives in the portal,
+ * keeps mail payloads small, and avoids the audit-trail headache
+ * of "which copy is authoritative".
+ */
+export async function sendInvoiceIssuedEmail(params: {
+  to: string;
+  contactName: string;
+  companyName: string;
+  invoiceNumber: string;
+  totalChf: number;
+  currency: string; // "CHF" — passed for future-proofing
+  dueAt: string;    // ISO date
+  lineCount: number;
+  periodStart: string; // ISO date
+  periodEnd: string;   // ISO date
+  locale: "de" | "en" | "fr" | "it";
+}): Promise<void> {
+  // All four locales — the email is sent in the invoice's locale,
+  // which was frozen at issue time. No fallback to admin's locale.
+  const L = params.locale;
+  const subjectsByLocale: Record<typeof L, string> = {
+    en: `New invoice ${params.invoiceNumber} from PieCed IT — ${params.currency} ${params.totalChf.toFixed(2)}`,
+    de: `Neue Rechnung ${params.invoiceNumber} von PieCed IT — ${params.currency} ${params.totalChf.toFixed(2)}`,
+    fr: `Nouvelle facture ${params.invoiceNumber} de PieCed IT — ${params.currency} ${params.totalChf.toFixed(2)}`,
+    it: `Nuova fattura ${params.invoiceNumber} da PieCed IT — ${params.currency} ${params.totalChf.toFixed(2)}`,
+  };
+  const greetingsByLocale: Record<typeof L, string> = {
+    en: `Hello ${params.contactName},`,
+    de: `Sehr geehrte/r ${params.contactName},`,
+    fr: `Bonjour ${params.contactName},`,
+    it: `Gentile ${params.contactName},`,
+  };
+  const introByLocale: Record<typeof L, string> = {
+    en: `A new invoice has been issued for ${params.companyName}.`,
+    de: `Für ${params.companyName} wurde eine neue Rechnung ausgestellt.`,
+    fr: `Une nouvelle facture a été émise pour ${params.companyName}.`,
+    it: `È stata emessa una nuova fattura per ${params.companyName}.`,
+  };
+  const labels: Record<typeof L, Record<string, string>> = {
+    en: { number: "Invoice", period: "Period", total: "Total", due: "Due by", lines: "Line items", cta: "View invoice & download PDF", signoff: "Best regards", brand: "PieCed IT" },
+    de: { number: "Rechnung", period: "Zeitraum", total: "Gesamt", due: "Zahlbar bis", lines: "Positionen", cta: "Rechnung ansehen & PDF herunterladen", signoff: "Mit freundlichen Grüssen", brand: "PieCed IT" },
+    fr: { number: "Facture", period: "Période", total: "Total", due: "À régler avant", lines: "Lignes", cta: "Voir la facture & télécharger le PDF", signoff: "Cordialement", brand: "PieCed IT" },
+    it: { number: "Fattura", period: "Periodo", total: "Totale", due: "Scadenza", lines: "Voci", cta: "Visualizza fattura & scarica PDF", signoff: "Cordiali saluti", brand: "PieCed IT" },
+  };
+  const l = labels[L];
+
+  const safeName = escapeHtml(params.contactName);
+  const safeCompany = escapeHtml(params.companyName);
+  const safeNumber = escapeHtml(params.invoiceNumber);
+  const totalFmt = `${params.currency} ${params.totalChf.toFixed(2)}`;
+  const periodFmt = `${params.periodStart.slice(0, 10)} → ${params.periodEnd.slice(0, 10)}`;
+  const dueFmt = params.dueAt.slice(0, 10);
+
+  // Both bodies built in the invoice's locale.
+  const link = `https://app.pieced.ch/billing/${encodeURIComponent(params.invoiceNumber)}`;
+
+  try {
+    await getTransporter().sendMail({
+      from: getFrom(),
+      to: params.to,
+      subject: subjectsByLocale[L],
+      text: [
+        greetingsByLocale[L],
+        "",
+        introByLocale[L],
+        "",
+        `${l.number}:  ${params.invoiceNumber}`,
+        `${l.period}:  ${periodFmt}`,
+        `${l.total}:   ${totalFmt}`,
+        `${l.due}:     ${dueFmt}`,
+        `${l.lines}:   ${params.lineCount}`,
+        "",
+        `${l.cta}:`,
+        link,
+        "",
+        `${l.signoff},`,
+        l.brand,
+      ].join("\n"),
+      html: `
+        <div style="font-family: -apple-system, BlinkMacSystemFont, sans-serif; max-width: 560px; padding: 24px; background: #1a1a1a; color: #e5e5e5;">
+          <h2 style="margin: 0 0 16px; color: #10B981;">${escapeHtml(introByLocale[L])}</h2>
+          <p>${escapeHtml(greetingsByLocale[L])}</p>
+          <p>${escapeHtml(introByLocale[L])}</p>
+          <table style="width:100%; border-collapse:collapse; margin:16px 0; font-size:14px;">
+            <tr><td style="color:#888; padding:6px 0; width:120px;">${l.number}</td><td><strong>${safeNumber}</strong></td></tr>
+            <tr><td style="color:#888; padding:6px 0;">${l.period}</td><td>${escapeHtml(periodFmt)}</td></tr>
+            <tr><td style="color:#888; padding:6px 0;">${l.total}</td><td style="color:#10B981; font-weight:600;">${escapeHtml(totalFmt)}</td></tr>
+            <tr><td style="color:#888; padding:6px 0;">${l.due}</td><td>${escapeHtml(dueFmt)}</td></tr>
+            <tr><td style="color:#888; padding:6px 0;">${l.lines}</td><td>${params.lineCount}</td></tr>
+          </table>
+          <p>
+            <a href="${link}" style="display:inline-block; padding:10px 24px; background:#10B981; color:#fff; text-decoration:none; border-radius:8px; font-weight:500;">
+              ${l.cta}
+            </a>
+          </p>
+          <hr style="border:none; border-top:1px solid #333; margin:24px 0;" />
+          <p style="color:#666; font-size:12px;">${l.brand}</p>
+        </div>
+      `,
+    });
+  } catch (err) {
+    console.error("Failed to send invoice issued email:", err);
+  }
+}

src/lib/k8s.ts

@@ -173,3 +173,115 @@ export async function setTenantAnnotation(
   }
   return res.json() as Promise<PiecedTenant>;
 }
+
+// ---------------------------------------------------------------------------
+// OpenClaw config ConfigMap helpers (admin-only feature: per-tenant version
+// override + platform default).
+//
+// The ConfigMap lives in the operator's namespace (`pieced-system`). The
+// portal's ServiceAccount needs `get/patch` on configmaps in that namespace
+// — rules added in the gitops repo.
+//
+// Tag-only by design — see operator notes for rationale.
+// ---------------------------------------------------------------------------
+
+const OPENCLAW_CONFIGMAP_NAME = "pieced-openclaw-config";
+
+/**
+ * Operator namespace. Reads the env var so the portal can be deployed in
+ * non-default namespaces without code changes; defaults to "pieced-system"
+ * matching the operator's chart default.
+ */
+function getOperatorNamespace(): string {
+  return process.env.OPERATOR_NAMESPACE ?? "pieced-system";
+}
+
+export interface OpenClawDefaults {
+  /** Image tag (e.g. "2026.4.22"). Empty string means unset. */
+  defaultTag: string;
+}
+
+/**
+ * Read the platform-default OpenClaw image tag. Returns empty string
+ * if unset, and `{ defaultTag: "" }` if the ConfigMap doesn't exist yet
+ * — the operator's built-in fallback is invisible to the portal by
+ * design (we don't want the UI to claim "current default: 2026.x" when
+ * it's actually the operator binary's baked-in version; that would be
+ * misleading once the binary updates).
+ */
+export async function getOpenClawDefaults(): Promise<OpenClawDefaults> {
+  const ns = getOperatorNamespace();
+  const url = `${getBaseUrl()}/api/v1/namespaces/${ns}/configmaps/${OPENCLAW_CONFIGMAP_NAME}`;
+  const res = await fetch(url, {
+    headers: { Accept: "application/json", ...getAuthHeaders() },
+  });
+  if (res.status === 404) {
+    return { defaultTag: "" };
+  }
+  if (!res.ok) {
+    const text = await res.text();
+    const err = new Error(
+      `K8s GET configmap ${OPENCLAW_CONFIGMAP_NAME}: ${res.status} ${text}`
+    );
+    (err as any).statusCode = res.status;
+    throw err;
+  }
+  const cm = (await res.json()) as { data?: Record<string, string> };
+  return { defaultTag: cm.data?.defaultTag ?? "" };
+}
+
+/**
+ * Update the platform-default OpenClaw image tag. Empty string clears
+ * the field (operator falls back to its built-in default).
+ *
+ * Creates the ConfigMap if it doesn't exist (PATCH on missing resource
+ * 404s; we retry as POST). Keeps the admin UI usable on a fresh install
+ * where the helm-shipped CM was deleted or never created.
+ */
+export async function setOpenClawDefaults(
+  defaults: OpenClawDefaults
+): Promise<OpenClawDefaults> {
+  const ns = getOperatorNamespace();
+  const url = `${getBaseUrl()}/api/v1/namespaces/${ns}/configmaps/${OPENCLAW_CONFIGMAP_NAME}`;
+  const patch = { data: { defaultTag: defaults.defaultTag } };
+  const res = await fetch(url, {
+    method: "PATCH",
+    headers: {
+      Accept: "application/json",
+      "Content-Type": "application/merge-patch+json",
+      ...getAuthHeaders(),
+    },
+    body: JSON.stringify(patch),
+  });
+  if (res.status === 404) {
+    const createUrl = `${getBaseUrl()}/api/v1/namespaces/${ns}/configmaps`;
+    const createRes = await fetch(createUrl, {
+      method: "POST",
+      headers: {
+        Accept: "application/json",
+        "Content-Type": "application/json",
+        ...getAuthHeaders(),
+      },
+      body: JSON.stringify({
+        apiVersion: "v1",
+        kind: "ConfigMap",
+        metadata: { name: OPENCLAW_CONFIGMAP_NAME, namespace: ns },
+        data: patch.data,
+      }),
+    });
+    if (!createRes.ok) {
+      const text = await createRes.text();
+      throw new Error(
+        `K8s POST configmap ${OPENCLAW_CONFIGMAP_NAME}: ${createRes.status} ${text}`
+      );
+    }
+    return defaults;
+  }
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(
+      `K8s PATCH configmap ${OPENCLAW_CONFIGMAP_NAME}: ${res.status} ${text}`
+    );
+  }
+  return defaults;
+}

src/lib/litellm.ts

@@ -93,6 +93,94 @@ export async function listTeams(): Promise<any[]> {
   return Array.isArray(data) ? data : data?.data ?? data?.teams ?? [];
 }
 
+/**
+ * Find a virtual key on a team by its alias and return its current
+ * state (token, spend, budget cap, reset cadence). Returns null if
+ * the alias doesn't match any key on the team.
+ *
+ * Why we need this
+ * ----------------
+ * Per-tenant budgets live on the virtual key, not the team. The
+ * portal needs to:
+ *   1. Display the current key's `max_budget` / `budget_duration` /
+ *      `spend` on the tenant detail page.
+ *   2. Pass the key's `token` to `/key/update` when the customer
+ *      changes the budget.
+ *
+ * The token is opaque to the customer; the operator's
+ * `FindKeyByAlias` does the same lookup for stale-key cleanup. We
+ * mirror its API call here.
+ */
+export async function findKeyByAlias(
+  teamId: string,
+  keyAlias: string
+): Promise<{
+  token: string;
+  spend: number;
+  maxBudget: number | null;
+  budgetDuration: string | null;
+} | null> {
+  const data = await litellmFetch(
+    `/key/list?team_id=${encodeURIComponent(teamId)}&return_full_object=true&include_team_keys=true`
+  );
+  const keys: any[] = Array.isArray(data?.keys)
+    ? data.keys
+    : Array.isArray(data?.data)
+      ? data.data
+      : Array.isArray(data)
+        ? data
+        : [];
+  for (const k of keys) {
+    if (typeof k !== "object" || k === null) continue;
+    const alias = k.key_alias ?? k.keyAlias;
+    if (alias !== keyAlias) continue;
+    if (typeof k.token !== "string" || !k.token) continue;
+    return {
+      token: k.token,
+      spend: typeof k.spend === "number" ? k.spend : Number(k.spend) || 0,
+      maxBudget:
+        typeof k.max_budget === "number"
+          ? k.max_budget
+          : k.max_budget == null
+            ? null
+            : Number(k.max_budget) || null,
+      budgetDuration:
+        typeof k.budget_duration === "string" ? k.budget_duration : null,
+    };
+  }
+  return null;
+}
+
+/**
+ * Update a virtual key's budget cap and reset duration.
+ *
+ * Pass `maxBudget: null` to remove the cap. Pass `budgetDuration:
+ * null` to make the budget never reset (lifetime cap).
+ *
+ * Identified by `key` parameter — accepts either the raw `sk-...`
+ * token or its hash (LiteLLM accepts both shapes on /key/update).
+ * The portal flow uses the hash returned by `findKeyByAlias`.
+ */
+export async function updateKeyBudget(
+  key: string,
+  changes: {
+    maxBudget?: number | null;
+    budgetDuration?: string | null;
+  }
+): Promise<void> {
+  const body: Record<string, any> = { key };
+  if (changes.maxBudget !== undefined) {
+    body.max_budget = changes.maxBudget;
+  }
+  if (changes.budgetDuration !== undefined) {
+    body.budget_duration = changes.budgetDuration;
+  }
+  await litellmFetch("/key/update", {
+    method: "POST",
+    body: JSON.stringify(body),
+  });
+}
+
 /**
  * Get LiteLLM health status.
  */

src/lib/packages.ts

@@ -1,9 +1,45 @@
+/**
+ * Portal-side package catalog. Hardcoded mirror of the operator-side
+ * catalog ConfigMap (deploy/helm/pieced-operator/templates/catalog-cm.yaml).
+ *
+ * The two have to stay in sync:
+ *   - `id` here must match the catalog key in the ConfigMap.
+ *   - `secrets[].key` here must match the catalog's env_vars[].secret_key
+ *     so that POST /api/tenants/:name/secrets writes to the same OpenBao
+ *     path the operator's ExternalSecret reads from.
+ *   - `requiresSecrets` is true when the catalog declares any env_var
+ *     that is a secret (vault_path_suffix set, no default value).
+ *
+ * Category model (Phase A rework):
+ *   - core    — platform-behaviour toggles (heartbeat, cron,
+ *               active-memory, voice). Mostly no secrets. core-voice is
+ *               fully wired (Phase B): toggling installs the STT / TTS /
+ *               Talk surface via the operator's config_patch, routed
+ *               through LiteLLM (pieced-stt, pieced-tts-inbound,
+ *               pieced-tts-talk).
+ *   - channel — messaging integration.
+ *   - skill   — ClawHub skill install.
+ *
+ * Custom provisioning (Threema):
+ *   The `threema` channel sets `requiresSecrets: false` because its
+ *   credentials are platform-issued, not customer-entered. Enabling
+ *   threema goes through a dedicated endpoint
+ *   (/api/tenants/:name/threema) that mints token + HMAC secret from
+ *   the central pieced-threema-gateway relay and writes them to OpenBao
+ *   at secret/data/tenants/<name>/threema-relay before the package is
+ *   added to spec.packages. Disabling reverses both steps. The
+ *   `customProvisioning` flag here tells the package-card UI to use
+ *   that endpoint instead of the standard /secrets+PATCH dance.
+ */
+
 export interface PackageSecretField {
   key: string;
   labelKey: string;
   placeholderKey: string;
 }
 
+export type PackageCategory = "core" | "channel" | "skill";
+
 export interface PackageDef {
   id: string;
   name: string;
@@ -12,10 +48,72 @@ export interface PackageDef {
   secrets?: PackageSecretField[];
   instructionsKey?: string;
   disclaimerKey?: string;
-  category: "channel" | "skill";
+  category: PackageCategory;
+  /**
+   * When true, enabling/disabling this package goes through
+   * /api/tenants/:name/<id> (POST/DELETE) instead of the generic
+   * /secrets+PATCH flow. The handler at that path does platform-side
+   * provisioning (mint credentials, register with sibling services, etc.)
+   * that the customer is not aware of.
+   */
+  customProvisioning?: boolean;
+  /**
+   * When true, customer-initiated enable requests are routed through
+   * an admin approval queue (skill_activation_requests) instead of
+   * being applied immediately. Platform-side manual work (hardware
+   * provisioning, third-party account setup, DNS, etc.) happens
+   * between request and approval, so we keep the tenant out of the
+   * spec until that work is done and the operator would otherwise
+   * fail to reconcile.
+   *
+   * Platform admins bypass the gate (direct PATCH from /admin still
+   * applies immediately). Disable is always direct — there's no
+   * gate on turning a skill off.
+   *
+   * Orthogonal to `requiresSecrets` and `customProvisioning`. A skill
+   * can have all three: customer provides credentials, the secrets
+   * are stored, the activation request lands in the admin queue,
+   * admin does the manual work, then approves.
+   */
+  requiresManualSetup?: boolean;
 }
 
 export const PACKAGE_CATALOG: PackageDef[] = [
+  // -------------------------------------------------------------------------
+  // CORE
+  // -------------------------------------------------------------------------
+  {
+    id: "core-heartbeat",
+    name: "Heartbeat (Proactive Checks)",
+    descriptionKey: "packages.coreHeartbeat.description",
+    requiresSecrets: false,
+    category: "core",
+  },
+  {
+    id: "core-cron",
+    name: "Scheduled Tasks (Cron)",
+    descriptionKey: "packages.coreCron.description",
+    requiresSecrets: false,
+    category: "core",
+  },
+  {
+    id: "core-active-memory",
+    name: "Active Memory",
+    descriptionKey: "packages.coreActiveMemory.description",
+    requiresSecrets: false,
+    category: "core",
+  },
+  {
+    id: "core-voice",
+    name: "Voice Interaction",
+    descriptionKey: "packages.coreVoice.description",
+    requiresSecrets: false,
+    category: "core",
+  },
+
+  // -------------------------------------------------------------------------
+  // CHANNELS
+  // -------------------------------------------------------------------------
   {
     id: "telegram",
     name: "Telegram",
@@ -43,42 +141,202 @@ export const PACKAGE_CATALOG: PackageDef[] = [
         labelKey: "packages.discord.botTokenLabel",
         placeholderKey: "packages.discord.botTokenPlaceholder",
       },
+      // app-id was missing from the portal catalog historically while the
+      // operator catalog declared DISCORD_APP_ID as a required env var.
+      // Tenants who enabled Discord ended up with the env var blank
+      // because the secrets POST never wrote an `app-id` key to OpenBao
+      // and the operator's ExternalSecret couldn't populate it. Added
+      // here as part of the Phase A rework to close the alignment gap;
+      // not strictly secret (the application ID is visible in the bot's
+      // profile URL) but stored alongside the bot token for convenience.
+      {
+        key: "app-id",
+        labelKey: "packages.discord.appIdLabel",
+        placeholderKey: "packages.discord.appIdPlaceholder",
+      },
     ],
     instructionsKey: "packages.discord.instructions",
     disclaimerKey: "packages.discord.disclaimer",
     category: "channel",
   },
   {
-    id: "email",
-    name: "Email",
-    descriptionKey: "packages.email.description",
-    requiresSecrets: true,
-    secrets: [
-      { key: "smtp-host", labelKey: "packages.email.smtpHostLabel", placeholderKey: "packages.email.smtpHostPlaceholder" },
-      { key: "smtp-user", labelKey: "packages.email.smtpUserLabel", placeholderKey: "packages.email.smtpUserPlaceholder" },
-      { key: "smtp-password", labelKey: "packages.email.smtpPasswordLabel", placeholderKey: "packages.email.smtpPasswordPlaceholder" },
-      { key: "imap-host", labelKey: "packages.email.imapHostLabel", placeholderKey: "packages.email.imapHostPlaceholder" },
-    ],
-    instructionsKey: "packages.email.instructions",
-    disclaimerKey: "packages.email.disclaimer",
+    id: "threema",
+    name: "Threema",
+    descriptionKey: "packages.threema.description",
+    // No customer-entered secrets. The token + hmac secret are minted
+    // server-side by the relay's /admin/tokens endpoint when the
+    // package is enabled, and stored in OpenBao by the portal. The
+    // `customProvisioning` flag steers the PackageCard UI through the
+    // dedicated /api/tenants/:name/threema endpoint instead.
+    requiresSecrets: false,
+    customProvisioning: true,
+    instructionsKey: "packages.threema.instructions",
+    disclaimerKey: "packages.threema.disclaimer",
     category: "channel",
   },
+
+  // -------------------------------------------------------------------------
+  // SKILLS
+  // -------------------------------------------------------------------------
   {
-    id: "web-search",
-    name: "Web Search",
-    descriptionKey: "packages.webSearch.description",
+    id: "git-cli",
+    name: "Git CLI",
+    descriptionKey: "packages.gitCli.description",
     requiresSecrets: false,
     category: "skill",
   },
   {
-    id: "document-processing",
-    name: "Document Processing",
-    descriptionKey: "packages.documentProcessing.description",
+    id: "github",
+    name: "GitHub (gh CLI)",
+    descriptionKey: "packages.github.description",
+    requiresSecrets: true,
+    secrets: [
+      {
+        key: "token",
+        labelKey: "packages.github.tokenLabel",
+        placeholderKey: "packages.github.tokenPlaceholder",
+      },
+    ],
+    instructionsKey: "packages.github.instructions",
+    category: "skill",
+  },
+  {
+    id: "gitea",
+    name: "Gitea",
+    descriptionKey: "packages.gitea.description",
+    requiresSecrets: true,
+    secrets: [
+      {
+        key: "token",
+        labelKey: "packages.gitea.tokenLabel",
+        placeholderKey: "packages.gitea.tokenPlaceholder",
+      },
+    ],
+    instructionsKey: "packages.gitea.instructions",
+    category: "skill",
+  },
+  {
+    id: "whisper-self-hosted",
+    name: "Whisper (Self-Hosted Transcription)",
+    descriptionKey: "packages.whisperSelfHosted.description",
     requiresSecrets: false,
     category: "skill",
   },
+  {
+    id: "searxng-local-search",
+    name: "Web Search (SearXNG)",
+    descriptionKey: "packages.searxngLocalSearch.description",
+    requiresSecrets: false,
+    category: "skill",
+  },
+  {
+    id: "gog",
+    requiresManualSetup: true,
+    name: "Google Workspace (Gog)",
+    descriptionKey: "packages.gog.description",
+    requiresSecrets: true,
+    secrets: [
+      {
+        key: "client-id",
+        labelKey: "packages.gog.clientIdLabel",
+        placeholderKey: "packages.gog.clientIdPlaceholder",
+      },
+      {
+        key: "client-secret",
+        labelKey: "packages.gog.clientSecretLabel",
+        placeholderKey: "packages.gog.clientSecretPlaceholder",
+      },
+      {
+        key: "refresh-token",
+        labelKey: "packages.gog.refreshTokenLabel",
+        placeholderKey: "packages.gog.refreshTokenPlaceholder",
+      },
+    ],
+    instructionsKey: "packages.gog.instructions",
+    disclaimerKey: "packages.gog.disclaimer",
+    category: "skill",
+  },
+  {
+    id: "mail",
+    name: "Email (IMAP / SMTP)",
+    descriptionKey: "packages.mail.description",
+    requiresSecrets: true,
+    secrets: [
+      {
+        key: "imap-host",
+        labelKey: "packages.mail.imapHostLabel",
+        placeholderKey: "packages.mail.imapHostPlaceholder",
+      },
+      {
+        key: "imap-user",
+        labelKey: "packages.mail.imapUserLabel",
+        placeholderKey: "packages.mail.imapUserPlaceholder",
+      },
+      {
+        key: "imap-pass",
+        labelKey: "packages.mail.imapPassLabel",
+        placeholderKey: "packages.mail.imapPassPlaceholder",
+      },
+      {
+        key: "smtp-host",
+        labelKey: "packages.mail.smtpHostLabel",
+        placeholderKey: "packages.mail.smtpHostPlaceholder",
+      },
+      {
+        key: "smtp-user",
+        labelKey: "packages.mail.smtpUserLabel",
+        placeholderKey: "packages.mail.smtpUserPlaceholder",
+      },
+      {
+        key: "smtp-pass",
+        labelKey: "packages.mail.smtpPassLabel",
+        placeholderKey: "packages.mail.smtpPassPlaceholder",
+      },
+    ],
+    instructionsKey: "packages.mail.instructions",
+    disclaimerKey: "packages.mail.disclaimer",
+    category: "skill",
+  },
 ];
 
 export function getPackageDef(id: string): PackageDef | undefined {
   return PACKAGE_CATALOG.find((p) => p.id === id);
 }
+
+/**
+ * IDs of channel-category packages. Derived from the catalog so it
+ * cannot drift from the source of truth (previously hardcoded as
+ * `["telegram", "discord", "email"]` in tenants/[name]/page.tsx —
+ * removed as part of the Phase A package-model rework).
+ *
+ * Consumers: tenant detail page (filter spec.packages to channel set
+ * before rendering the channel-users panel).
+ */
+export const CHANNEL_PACKAGE_IDS: string[] = PACKAGE_CATALOG
+  .filter((p) => p.category === "channel")
+  .map((p) => p.id);
+
+/**
+ * Default packages selected when the wizard opens a fresh onboarding
+ * request. The three CORE behaviours that make the assistant feel
+ * "smart out of the box":
+ *   - heartbeat:     proactive checks (otherwise the assistant is purely
+ *                    reactive).
+ *   - cron:          scheduled tasks (daily briefings, reminders).
+ *   - active-memory: long-term recall of stable preferences and habits.
+ *
+ * Each adds some token cost — active-memory the most (one extra
+ * sub-agent turn per inbound message) — so customers can untoggle any
+ * of them before submitting.
+ *
+ * core-voice is intentionally NOT a default. It is fully wired (Phase B)
+ * and customers can enable it from the wizard, but it incurs separate
+ * audio spend on every inbound voice note (Whisper STT) and every
+ * outbound reply (kani-tts / kokoro-fastapi via LiteLLM). Opt-in keeps
+ * cost predictable for tenants who don't intend to use voice channels.
+ */
+export const DEFAULT_PACKAGE_IDS: string[] = [
+  "core-heartbeat",
+  "core-cron",
+  "core-active-memory",
+];

src/lib/stripe.ts

@@ -0,0 +1,260 @@
+/**
+ * Server-side Stripe client + helpers for Phase 4 (card payments).
+ *
+ * Architecture (see Phase 4 notes):
+ *   1. Customer clicks "Pay with card" on /billing/<number>.
+ *   2. Server creates Stripe Checkout Session (mode='payment') with
+ *      the invoice total as a single line item. We pass `customer`
+ *      to reuse an existing Stripe Customer if the org already has
+ *      one, otherwise we create one and persist its id in
+ *      org_billing_config.stripe_customer_id.
+ *   3. Returns session.url; the browser redirects there.
+ *   4. Customer pays; Stripe redirects to success_url with the
+ *      session id appended.
+ *   5. /api/stripe/webhook receives `checkout.session.completed`,
+ *      verifies signature, looks up the invoice id from metadata,
+ *      flips the invoice to 'paid'.
+ *
+ * Env vars:
+ *   STRIPE_SECRET_KEY          (required) - sk_test_... in sandbox, sk_live_... in prod
+ *   STRIPE_WEBHOOK_SECRET      (required for webhook) - whsec_...
+ *   APP_BASE_URL               (required) - e.g. https://app.pieced.ch
+ *
+ * SDK: stripe@22.x (Node SDK v22), pinned API version 2026-03-25.dahlia.
+ * Pinning the API version means a `npm update` of the SDK won't
+ * silently change request/response shapes; we explicitly bump when
+ * we want a new API version.
+ */
+
+import Stripe from "stripe";
+import type { Invoice } from "@/types";
+
+// Pinned API version. `as const` narrows this to a string-literal
+// type that the Stripe constructor's `apiVersion` field accepts
+// exactly. When the installed SDK bumps to a new pinned version,
+// TypeScript will surface the mismatch at the `new Stripe(...)` call
+// below — bump this string deliberately alongside the SDK upgrade
+// and review the API changelog before doing so.
+const STRIPE_API_VERSION = "2026-04-22.dahlia" as const;
+
+// Cache the client across hot reloads / serverless invocations.
+// We don't instantiate at module load because some build steps run
+// without runtime env vars set — only fail when actually used.
+let cachedClient: Stripe | null = null;
+
+export function getStripeClient(): Stripe {
+  if (cachedClient) return cachedClient;
+  const key = process.env.STRIPE_SECRET_KEY;
+  if (!key) {
+    throw new Error(
+      "STRIPE_SECRET_KEY is not set. Configure it in your environment."
+    );
+  }
+  cachedClient = new Stripe(key, {
+    apiVersion: STRIPE_API_VERSION,
+    // Identify ourselves in Stripe's request logs so support can
+    // distinguish PieCed traffic from other integrations on the
+    // same account.
+    appInfo: {
+      name: "PieCed Portal",
+      version: "1.0.0",
+      url: "https://app.pieced.ch",
+    },
+  });
+  return cachedClient;
+}
+
+/**
+ * Return the configured webhook secret. Separated so the webhook
+ * handler can fail fast with a clear error message rather than the
+ * generic "STRIPE_SECRET_KEY missing" path above.
+ */
+export function getWebhookSecret(): string {
+  const secret = process.env.STRIPE_WEBHOOK_SECRET;
+  if (!secret) {
+    throw new Error(
+      "STRIPE_WEBHOOK_SECRET is not set. Get it from the webhook endpoint in your Stripe dashboard."
+    );
+  }
+  return secret;
+}
+
+/**
+ * Convert a CHF decimal amount (e.g. 123.45) to integer rappen
+ * (e.g. 12345). Stripe API requires integer amounts in the
+ * currency's smallest unit. Centralised so we don't have rounding
+ * drift between callers.
+ */
+export function chfToRappen(amountChf: number): number {
+  // toFixed(2) avoids floating-point ugliness (0.1 + 0.2 = 0.30000000000000004).
+  return Math.round(parseFloat(amountChf.toFixed(2)) * 100);
+}
+
+/**
+ * Look up or create the Stripe Customer for a PieCed org.
+ *
+ * Lazy creation: orgs that only pay by invoice never get a Stripe
+ * Customer. The first "Pay with card" click triggers creation; the
+ * id is persisted in org_billing_config so subsequent invoices
+ * reuse it.
+ *
+ * Returns the Stripe customer id (`cus_...`).
+ */
+export async function ensureStripeCustomerForOrg(params: {
+  zitadelOrgId: string;
+  // Snapshot taken at click-time, NOT at invoice issuance — the
+  // org's current address goes on the Stripe customer object.
+  // Stripe's address on file is independent of any one invoice.
+  companyName: string;
+  billingEmail: string;
+  address: {
+    line1: string;
+    postalCode: string;
+    city: string;
+    country: string; // ISO 3166-1 alpha-2 (e.g. "CH")
+  };
+}): Promise<string> {
+  // Lazy import to avoid pulling pg into edge-runtime modules that
+  // might import this file. Same pattern used elsewhere in lib/.
+  const { getOrgBillingConfig, updateOrgBillingConfig } = await import("./db");
+  const existing = await getOrgBillingConfig(params.zitadelOrgId);
+  if (existing.stripeCustomerId) {
+    return existing.stripeCustomerId;
+  }
+  const stripe = getStripeClient();
+  const customer = await stripe.customers.create({
+    email: params.billingEmail,
+    name: params.companyName,
+    address: {
+      line1: params.address.line1,
+      postal_code: params.address.postalCode,
+      city: params.address.city,
+      country: params.address.country,
+    },
+    metadata: {
+      zitadel_org_id: params.zitadelOrgId,
+    },
+  });
+  await updateOrgBillingConfig(params.zitadelOrgId, {
+    stripeCustomerId: customer.id,
+  });
+  return customer.id;
+}
+
+/**
+ * Create a Checkout Session for paying a single invoice by card.
+ *
+ * Design notes:
+ *
+ * - Single line item with the invoice total (gross, VAT included).
+ *   Our own invoice PDF already breaks down lines + VAT; the Stripe
+ *   page is the checkout, not a duplicate of the invoice.
+ *
+ * - `automatic_tax` is disabled because the invoice already has
+ *   VAT computed by our pipeline. Letting Stripe re-calculate
+ *   would double-charge or contradict our PDF.
+ *
+ * - `payment_method_types` is NOT set, so Stripe surfaces dynamic
+ *   payment methods configured on the account (cards, TWINT for
+ *   Swiss customers, Apple Pay, Google Pay, etc.) automatically.
+ *
+ * - `metadata` and `payment_intent_data.metadata` BOTH carry the
+ *   invoice id. The session-level copy is enough for the
+ *   `checkout.session.completed` webhook; the intent-level copy
+ *   lets us correlate refunds and disputes which fire on the
+ *   PaymentIntent and don't include session metadata.
+ *
+ * - `client_reference_id` is set to our invoice id as a stable
+ *   reference. Visible in the Stripe dashboard, useful for support.
+ *
+ * - `locale` follows the invoice's locale so the customer sees
+ *   the Stripe page in their language (frozen at invoice issue
+ *   time; consistent with PDF + email).
+ */
+export async function createCheckoutSessionForInvoice(params: {
+  invoice: Invoice;
+  customerId: string;
+  baseUrl: string;
+}): Promise<{ url: string; sessionId: string }> {
+  const stripe = getStripeClient();
+  const { invoice, customerId, baseUrl } = params;
+
+  // Stripe Checkout supports a limited set of locales; map our
+  // four to Stripe's codes and fall back to 'auto' if anything
+  // outside the set ever appears.
+  //
+  // We deliberately don't annotate this with
+  // `Stripe.Checkout.SessionCreateParams.Locale` — stripe-node v22
+  // ships with a known type-export regression
+  // (stripe/stripe-node#2662) where params types under namespaced
+  // resources aren't re-exported from the resource barrel. The
+  // `as const` literal narrowing gives the variable the union type
+  // `"de" | "fr" | "it" | "en" | "auto"`, which `sessions.create`
+  // accepts at the call site via its own inline parameter typing.
+  // When the SDK fixes the re-export, we can put the annotation
+  // back without touching the call site.
+  const stripeLocale =
+    invoice.locale === "de"
+      ? ("de" as const)
+      : invoice.locale === "fr"
+      ? ("fr" as const)
+      : invoice.locale === "it"
+      ? ("it" as const)
+      : invoice.locale === "en"
+      ? ("en" as const)
+      : ("auto" as const);
+
+  const successUrl = `${baseUrl}/billing/${encodeURIComponent(invoice.invoiceNumber)}?paid=1&session_id={CHECKOUT_SESSION_ID}`;
+  const cancelUrl = `${baseUrl}/billing/${encodeURIComponent(invoice.invoiceNumber)}?cancelled=1`;
+
+  const session = await stripe.checkout.sessions.create({
+    mode: "payment",
+    customer: customerId,
+    client_reference_id: invoice.id,
+    locale: stripeLocale,
+    line_items: [
+      {
+        quantity: 1,
+        price_data: {
+          currency: "chf",
+          unit_amount: chfToRappen(invoice.totalChf),
+          product_data: {
+            name: `Invoice ${invoice.invoiceNumber}`,
+            description: `PieCed IT — ${invoice.periodStart.slice(0, 10)} → ${invoice.periodEnd.slice(0, 10)}`,
+          },
+        },
+      },
+    ],
+    metadata: {
+      invoice_id: invoice.id,
+      invoice_number: invoice.invoiceNumber,
+      zitadel_org_id: invoice.zitadelOrgId,
+    },
+    payment_intent_data: {
+      // Mirror invoice id at the PaymentIntent level so refunds &
+      // disputes (which fire on the PI, not the session) can be
+      // correlated to our invoice without an extra lookup.
+      metadata: {
+        invoice_id: invoice.id,
+        invoice_number: invoice.invoiceNumber,
+        zitadel_org_id: invoice.zitadelOrgId,
+      },
+      // Statement descriptor shown on the customer's card
+      // statement. Limited to 22 chars total; we use the prefix
+      // since Stripe will prepend the merchant name from the
+      // account anyway. Keep it short and recognisable.
+      description: `Invoice ${invoice.invoiceNumber}`,
+    },
+    success_url: successUrl,
+    cancel_url: cancelUrl,
+    // VAT is already in invoice.totalChf — don't let Stripe touch tax.
+    automatic_tax: { enabled: false },
+  });
+
+  if (!session.url) {
+    throw new Error(
+      `Stripe returned a session without a redirect URL (id=${session.id})`
+    );
+  }
+  return { url: session.url, sessionId: session.id };
+}

src/lib/threema-gateway-config.ts

@@ -0,0 +1,31 @@
+/**
+ * Threema central gateway info shown to customers.
+ *
+ * Today PieCed runs exactly one Threema Gateway account (*AIAGENT) and
+ * every tenant talks to that. The constants below are hardcoded for
+ * that account. The values are intentionally kept here (and not split
+ * across i18n / env / runtime config) so when we move to multiple
+ * gateway accounts there's a single file to refactor.
+ *
+ * To go dynamic (future):
+ *   1. Replace `THREEMA_GATEWAY` constant with a runtime lookup —
+ *      either per-tenant from the relay's admin API, or from an
+ *      env var that lists the active account.
+ *   2. Move the QR PNG into a server-rendered route that takes a
+ *      gateway ID query param.
+ *   3. Update consumers to accept the gateway info as a prop and pass
+ *      it from a server component.
+ */
+
+export const THREEMA_GATEWAY = {
+  /** Technical Threema Gateway ID, with leading asterisk. */
+  id: "*AIAGENT",
+  /**
+   * Display name shown to customers. INCLUDES the leading asterisk —
+   * customers need to recognise this exact string in their Threema
+   * contacts after scanning the QR, so we don't strip it.
+   */
+  displayName: "*AIAGENT",
+  /** Public path to the QR code PNG served from `public/`. */
+  qrCodePath: "/threema/qr_code_AIAGENT.png",
+} as const;

src/lib/threema-relay.ts

@@ -0,0 +1,202 @@
+/**
+ * Admin client for the central pieced-threema-gateway relay.
+ *
+ * All calls authenticate with a static admin bearer (THREEMA_RELAY_ADMIN_TOKEN
+ * from env, sourced from OpenBao at secret/data/threema-gateway/admin). The
+ * portal is the only caller; never expose these functions through a public
+ * HTTP surface.
+ *
+ * Resilience: every method returns a strongly-typed result rather than
+ * throwing. Network errors surface as `{ ok: false, kind: 'network' }`,
+ * 4xx/5xx as `{ ok: false, kind: 'http', status, ... }`. Callers that need
+ * to compensate (e.g. delete a route after a K8s patch failure) can
+ * inspect `kind` to decide whether retry is sensible.
+ */
+
+const RELAY_URL = (process.env.THREEMA_RELAY_URL ?? "").replace(/\/+$/, "");
+const ADMIN_TOKEN = process.env.THREEMA_RELAY_ADMIN_TOKEN ?? "";
+
+function assertConfigured(): void {
+  if (!RELAY_URL) throw new Error("THREEMA_RELAY_URL not set");
+  if (!ADMIN_TOKEN) throw new Error("THREEMA_RELAY_ADMIN_TOKEN not set");
+}
+
+type RelayError =
+  | { ok: false; kind: "network"; message: string }
+  | { ok: false; kind: "http"; status: number; message: string; body?: unknown };
+
+export type RelayResult<T> = ({ ok: true } & T) | RelayError;
+
+async function call<T>(
+  path: string,
+  init: RequestInit,
+): Promise<RelayResult<T>> {
+  assertConfigured();
+  try {
+    const res = await fetch(`${RELAY_URL}${path}`, {
+      ...init,
+      headers: {
+        ...(init.headers ?? {}),
+        Authorization: `Bearer ${ADMIN_TOKEN}`,
+        "Content-Type": "application/json",
+      },
+    });
+    let body: unknown = null;
+    const text = await res.text().catch(() => "");
+    if (text) {
+      try {
+        body = JSON.parse(text);
+      } catch {
+        body = text;
+      }
+    }
+    if (!res.ok) {
+      const message =
+        (body && typeof body === "object" && "error" in body && typeof (body as Record<string, unknown>).error === "string"
+          ? ((body as Record<string, unknown>).error as string)
+          : `HTTP ${res.status}`);
+      return { ok: false, kind: "http", status: res.status, message, body };
+    }
+    return { ok: true, ...(body as Record<string, unknown>) } as RelayResult<T>;
+  } catch (e) {
+    return { ok: false, kind: "network", message: (e as Error).message };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Tokens
+// ---------------------------------------------------------------------------
+
+/** Mint (or rotate) per-tenant bearer + HMAC secret. */
+export function mintToken(
+  tenantName: string,
+): Promise<RelayResult<{ token: string; hmacSecret: string }>> {
+  return call("/admin/tokens", {
+    method: "POST",
+    body: JSON.stringify({ tenantName }),
+  });
+}
+
+/**
+ * Revoke per-tenant token. Cascades — relay also deletes all routes
+ * owned by this tenant.
+ */
+export function revokeToken(
+  tenantName: string,
+): Promise<RelayResult<{ deletedRoutes: number }>> {
+  return call(`/admin/tokens/${encodeURIComponent(tenantName)}`, {
+    method: "DELETE",
+  });
+}
+
+export function tokenExists(
+  tenantName: string,
+): Promise<RelayResult<{ exists: true }>> {
+  return call(`/admin/tokens/${encodeURIComponent(tenantName)}`, {
+    method: "GET",
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Routes
+// ---------------------------------------------------------------------------
+
+export interface RouteRow {
+  threema_id: string;
+  tenant_name: string;
+  created_at: string;
+  created_by: string;
+}
+
+export function listRoutes(
+  tenantName: string,
+): Promise<RelayResult<{ routes: RouteRow[] }>> {
+  return call(`/admin/routes?tenant=${encodeURIComponent(tenantName)}`, {
+    method: "GET",
+  });
+}
+
+/**
+ * Create a route. The relay enforces uniqueness — on conflict returns
+ * status 409 with body `{ ownedBy: <tenantName> | null }`. Callers
+ * should inspect `kind === 'http'` + status 409 + body.ownedBy to
+ * distinguish idempotent self-claim from real conflict.
+ */
+export function createRoute(
+  tenantName: string,
+  threemaId: string,
+): Promise<RelayResult<{ ok: true }>> {
+  return call("/admin/routes", {
+    method: "POST",
+    body: JSON.stringify({ tenantName, threemaId }),
+  });
+}
+
+export function deleteRoute(
+  tenantName: string,
+  threemaId: string,
+): Promise<RelayResult<{ ok: true }>> {
+  return call(
+    `/admin/routes/${encodeURIComponent(threemaId)}?tenant=${encodeURIComponent(tenantName)}`,
+    { method: "DELETE" },
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Usage
+// ---------------------------------------------------------------------------
+
+export interface UsageBreakdown {
+  tenant: string;
+  from: string;
+  to: string;
+  totals: { in: number; out: number };
+  daily: Array<{ day: string; direction: "in" | "out"; count: number }>;
+}
+
+export function getUsage(
+  tenantName: string,
+  from?: Date,
+  to?: Date,
+): Promise<RelayResult<UsageBreakdown>> {
+  const qs = new URLSearchParams({ tenant: tenantName });
+  if (from) qs.set("from", from.toISOString());
+  if (to) qs.set("to", to.toISOString());
+  return call(`/admin/usage?${qs.toString()}`, { method: "GET" });
+}
+
+// ---------------------------------------------------------------------------
+// Health
+// ---------------------------------------------------------------------------
+
+export function health(): Promise<RelayResult<{ credits: number }>> {
+  return call("/admin/health", { method: "GET" });
+}
+
+// ---------------------------------------------------------------------------
+// Helpers for caller code
+// ---------------------------------------------------------------------------
+
+/**
+ * Type guard: did this route-create fail because the ID is owned by
+ * someone else? Distinguishes from "owned by SAME tenant" (idempotent).
+ */
+export function isRouteConflictForOtherTenant(
+  result: RelayResult<{ ok: true }>,
+  tenantName: string,
+): boolean {
+  if (result.ok) return false;
+  if (result.kind !== "http" || result.status !== 409) return false;
+  const body = result.body as { ownedBy?: string | null } | undefined;
+  return !!body?.ownedBy && body.ownedBy !== tenantName;
+}
+
+export function isRouteConflictForSameTenant(
+  result: RelayResult<{ ok: true }>,
+  tenantName: string,
+): boolean {
+  if (result.ok) return false;
+  if (result.kind !== "http" || result.status !== 409) return false;
+  const body = result.body as { ownedBy?: string | null } | undefined;
+  return body?.ownedBy === tenantName;
+}