Threema QR: on-demand modal + auto-open on first add

.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,66 @@
-# PieCed Portal
+# Threema UX v2 — QR available on demand
 
-Customer self-service portal for the PieCed IT multi-tenant OpenClaw platform.
+Replaces the previous attempt that had the QR rendering inline above
+the channel help text. That placement didn't work for you in practice
+because it wasn't visible when you actually wanted it.
 
-## Stack
+## What this does instead
 
-| 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` |
+1. **"Show QR" link** next to the channel title in the threema card —
+   visible at all times, clickable any time you want the QR.
 
-## Setup
+2. **Auto-opens the modal** the first time you focus the add-ID input
+   on the page (so a new user adding their first ID sees it without
+   needing to click "Show QR" themselves). Doesn't re-pop after
+   dismissal — the link covers re-opens.
 
-### 1. ZITADEL Application
+3. **Modal** with QR + 3-step instructions + "AIAGENT" label. Plain
+   `<img>` (no next/image), closes on ESC / overlay click / × button.
 
-In ZITADEL console (`auth.pieced.ch`), project "OpenClaw Platform":
+The earlier `threema-setup.tsx` component file is removed — replaced by
+`threema-qr-modal.tsx`.
 
-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
+## Files
 
-### 2. OpenBao Secrets
+```
+src/lib/threema-gateway-config.ts                      # unchanged from before — central gateway constants
+src/components/channel-users/threema-qr-modal.tsx      # NEW — the modal
+src/components/channel-users/channel-users.tsx         # MODIFIED — Show QR button + focus auto-open + modal mount
+deploy/patch-i18n-threema.mjs                          # adds threemaSetup.showQr label in 4 langs
+public/threema/qr_code_AIAGENT.png                     # unchanged
+```
+
+## Apply
 
 ```bash
-bao kv put pieced/portal/oidc \
-  client_id="<from step 1>" \
-  client_secret="<from step 1>" \
-  nextauth_secret="$(openssl rand -base64 32)"
+cd /path/to/pieced-portal
+
+# Remove the old inline component if you applied the previous archive
+rm -f src/components/channel-users/threema-setup.tsx
+
+# Drop new + modified files
+unzip -o /path/to/threema-ux-v2.zip
+
+# Update messages
+node deploy/patch-i18n-threema.mjs
+
+# TS check
+npx tsc --noEmit
+
+git add -A
+git commit -m "Threema QR: on-demand modal + auto-open on first add"
+git push
 ```
 
-### 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
+After redeploy, the threema card under Authorized Users shows:
 
 ```
-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
+threema    [Show QR]                              0 users
+            ────────────────────
+            <help text: 'Enter your own Threema ID...'>
+            ────────────────────
+            [ input: A8K2P3X7    ] [ Add ]
+            ^^^ focusing this opens the QR modal the first time
 ```
 
-## Session Roadmap
-
-- **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)
+Clicking "Show QR" or focusing the input → modal with QR + steps.

deploy/patch-i18n-threema.mjs

@@ -2,11 +2,20 @@
 /**
  * Run: node deploy/patch-i18n-threema.mjs
  *
- * Idempotently injects:
+ * Idempotently injects (or overwrites) customer-facing Threema texts:
  *   - packages.threema.{description, instructions, disclaimer}
  *   - channelUsers.threemaIdHelp
+ *   - channelUsers.threemaSetup.{title, step1, step2, step3, qrAlt}
  *
- * into all four message files. Run from the pieced-portal repo root.
+ * 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";
 
@@ -14,50 +23,82 @@ const i18n = {
   en: {
     pkg: {
       description:
-        "Threema messaging routed through the PieCed central gateway. No Gateway account of your own required — PieCed mints credentials when you enable this package.",
+        "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 — PieCed provisions a central-gateway slot for your tenant.\n2. Add the Threema IDs you want to talk to under Authorized Users → threema.\n3. Each Threema ID can only belong to one PieCed tenant; if a registration fails, that ID is already in use elsewhere.",
+        "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 are end-to-end encrypted at the Threema boundary by the PieCed central gateway. Inbound and outbound message counts are logged per tenant for billing.",
+        "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 the 8-character Threema ID (uppercase letters and digits, no asterisk) of the person you want to talk to. The * prefix is for Gateway accounts, which PieCed manages on your behalf.",
+      "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",
+      showQr: "Show QR",
+    },
   },
   de: {
     pkg: {
       description:
-        "Threema-Messaging über das zentrale PieCed-Gateway. Sie benötigen kein eigenes Gateway-Konto — PieCed stellt die Anmeldedaten beim Aktivieren dieses Pakets bereit.",
+        "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 — PieCed richtet einen zentralen Gateway-Slot für Ihren Tenant ein.\n2. Fügen Sie die Threema-IDs, mit denen Sie kommunizieren wollen, unter Autorisierte Benutzer → threema hinzu.\n3. Jede Threema-ID kann nur einem PieCed-Tenant zugeordnet sein; wenn die Registrierung fehlschlägt, ist die ID bereits anderweitig vergeben.",
+        "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:
-        "Die Nachrichten werden am Threema-Übergang vom zentralen PieCed-Gateway Ende-zu-Ende verschlüsselt. Eingehende und ausgehende Nachrichten werden pro Tenant für die Abrechnung gezählt.",
+        "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 die 8-stellige Threema-ID (Großbuchstaben und Ziffern, ohne Sternchen) der Person ein, mit der Sie kommunizieren möchten. Das *-Präfix gehört zu Gateway-Konten, die PieCed für Sie verwaltet.",
+      "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",
+      showQr: "QR anzeigen",
+    },
   },
   fr: {
     pkg: {
       description:
-        "Messagerie Threema via la passerelle centrale PieCed. Aucun compte Gateway personnel requis — PieCed génère les identifiants à l'activation du package.",
+        "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 — PieCed approvisionne un slot de passerelle centrale pour votre tenant.\n2. Ajoutez les identifiants Threema avec lesquels vous souhaitez échanger sous Utilisateurs autorisés → threema.\n3. Chaque identifiant Threema ne peut appartenir qu'à un seul tenant PieCed ; si l'enregistrement échoue, l'identifiant est déjà utilisé ailleurs.",
+        "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 sont chiffrés de bout en bout côté Threema par la passerelle centrale PieCed. Les volumes entrant et sortant sont consignés par tenant pour la facturation.",
+        "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 l'identifiant Threema à 8 caractères (lettres majuscules et chiffres, sans astérisque) de la personne avec qui vous souhaitez communiquer. Le préfixe * concerne les comptes Gateway, gérés par PieCed pour vous.",
+      "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",
+      showQr: "Afficher le QR",
+    },
   },
   it: {
     pkg: {
       description:
-        "Messaggistica Threema instradata tramite il gateway centrale PieCed. Non è necessario un account Gateway proprio — PieCed crea le credenziali quando attivi il pacchetto.",
+        "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 — PieCed predispone uno slot del gateway centrale per il tuo tenant.\n2. Aggiungi gli ID Threema con cui vuoi comunicare sotto Utenti autorizzati → threema.\n3. Ogni ID Threema può appartenere a un solo tenant PieCed; se la registrazione fallisce, l'ID è già usato altrove.",
+        "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 sono cifrati end-to-end al confine con Threema dal gateway centrale PieCed. I conteggi di messaggi in ingresso e uscita vengono registrati per tenant ai fini della fatturazione.",
+        "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 l'ID Threema di 8 caratteri (lettere maiuscole e cifre, senza asterisco) della persona con cui vuoi comunicare. Il prefisso * appartiene agli account Gateway, gestiti da PieCed per te.",
+      "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",
+      showQr: "Mostra QR",
+    },
   },
 };
 
@@ -74,7 +115,8 @@ for (const [lang, entries] of Object.entries(i18n)) {
 
   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} — added packages.threema and channelUsers.threemaIdHelp`);
+  console.log(`Patched ${path}`);
 }

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

@@ -3,6 +3,7 @@
 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> = {
@@ -51,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[]>) => {
@@ -216,9 +225,19 @@ export function ChannelUsers({
             className="bg-surface-2 border border-border rounded-lg p-4"
           >
             <div className="flex items-center justify-between mb-3">
-              <h4 className="text-sm font-medium text-text-primary capitalize">
-                {channel}
-              </h4>
+              <div className="flex items-center gap-2">
+                <h4 className="text-sm font-medium text-text-primary capitalize">
+                  {channel}
+                </h4>
+                {channel === "threema" && (
+                  <button
+                    onClick={() => setShowQrFor("threema")}
+                    className="text-xs font-medium text-accent hover:text-accent-dim cursor-pointer underline underline-offset-2"
+                  >
+                    {t("threemaSetup.showQr")}
+                  </button>
+                )}
+              </div>
               <span className="text-xs text-text-muted tabular-nums">
                 {users.length} {t("users")}
               </span>
@@ -266,6 +285,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);
                   }}
@@ -284,6 +314,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/lib/threema-gateway-config.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 (today only ThreemaSetup) to accept the
+ *      gateway info as a prop and pass it from a server component.
+ *
+ * In display contexts we strip the leading asterisk from the Threema
+ * ID — customers don't understand the `*X` prefix convention used for
+ * Gateway accounts, and the QR code carries the real value anyway. We
+ * keep the asterisk only for places where the technical value matters
+ * (server-side message routing, debug logs).
+ */
+
+export const THREEMA_GATEWAY = {
+  /** Technical Threema Gateway ID, with leading asterisk. */
+  id: "*AIAGENT",
+  /** Display name shown to customers (no asterisk). */
+  displayName: "AIAGENT",
+  /** Public path to the QR code PNG served from `public/`. */
+  qrCodePath: "/threema/qr_code_AIAGENT.png",
+} as const;

src/messages/de.json

@@ -306,6 +306,11 @@
       "smtpPassPlaceholder": "••••••••",
       "instructions": "1. Für Gmail: Aktivieren Sie die 2-Faktor-Authentifizierung, erstellen Sie dann unter https://myaccount.google.com/apppasswords ein App-Passwort und verwenden Sie es als IMAP- und SMTP-Passwort.\n2. Für Outlook / Microsoft 365 mit MFA: Generieren Sie ein App-Passwort in den Sicherheitseinstellungen Ihres Kontos.\n3. Für andere Anbieter: Konsultieren Sie deren IMAP/SMTP-Dokumentation für Hostnamen und Ports.\n4. Typische IMAP-Hosts: imap.gmail.com, outlook.office365.com.\n5. Typische SMTP-Hosts: smtp.gmail.com, smtp.office365.com.",
       "disclaimer": "Der Assistent erhält Lese- und Schreibzugriff auf das von Ihnen konfigurierte Postfach. Verwenden Sie eine dedizierte Adresse anstelle eines persönlichen Postfachs, wenn Sie den Umfang einschränken möchten."
+    },
+    "threema": {
+      "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."
     }
   },
   "admin": {
@@ -390,7 +395,16 @@
     "remove": "Entfernen",
     "alreadyAdded": "Diese Benutzer-ID ist bereits autorisiert.",
     "telegramIdHelp": "So finden Sie Ihre Telegram-Benutzer-ID:\n1. Öffnen Sie Telegram und schreiben Sie @userinfobot\n2. Der Bot antwortet sofort mit Ihrer numerischen ID\n3. Geben Sie diese Nummer hier ein",
-    "discordIdHelp": "So finden Sie Ihre Discord-Benutzer-ID:\n1. Aktivieren Sie den Entwicklermodus in den Discord-Einstellungen (Erweitert)\n2. Rechtsklick auf Ihren Namen → Benutzer-ID kopieren\n3. Geben Sie diese Nummer hier ein"
+    "discordIdHelp": "So finden Sie Ihre Discord-Benutzer-ID:\n1. Aktivieren Sie den Entwicklermodus in den Discord-Einstellungen (Erweitert)\n2. Rechtsklick auf Ihren Namen → Benutzer-ID kopieren\n3. Geben Sie diese Nummer hier ein",
+    "threemaIdHelp": "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.",
+    "threemaSetup": {
+      "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",
+      "showQr": "QR anzeigen"
+    }
   },
   "team": {
     "title": "Team",

src/messages/en.json

@@ -306,6 +306,11 @@
       "smtpPassPlaceholder": "••••••••",
       "instructions": "1. For Gmail: enable 2-Step Verification, then create an App Password at https://myaccount.google.com/apppasswords and use it as both IMAP and SMTP password.\n2. For Outlook / Microsoft 365 with MFA: generate an app password in your account's security settings.\n3. For other providers: refer to their IMAP/SMTP documentation for host names and ports.\n4. Typical IMAP hosts: imap.gmail.com, outlook.office365.com.\n5. Typical SMTP hosts: smtp.gmail.com, smtp.office365.com.",
       "disclaimer": "The assistant gains read/write access to the mailbox you configure. Consider using a dedicated address rather than a personal inbox if you want to limit scope."
+    },
+    "threema": {
+      "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."
     }
   },
   "admin": {
@@ -390,7 +395,16 @@
     "remove": "Remove",
     "alreadyAdded": "This user ID is already authorized.",
     "telegramIdHelp": "To find your Telegram user ID:\n1. Open Telegram and message @userinfobot\n2. It instantly replies with your numeric ID\n3. Enter that number here",
-    "discordIdHelp": "To find your Discord user ID:\n1. Enable Developer Mode in Discord settings (Advanced)\n2. Right-click your name → Copy User ID\n3. Enter that number here"
+    "discordIdHelp": "To find your Discord user ID:\n1. Enable Developer Mode in Discord settings (Advanced)\n2. Right-click your name → Copy User ID\n3. Enter that number here",
+    "threemaIdHelp": "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.",
+    "threemaSetup": {
+      "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",
+      "showQr": "Show QR"
+    }
   },
   "team": {
     "title": "Team",

src/messages/fr.json

@@ -306,6 +306,11 @@
       "smtpPassPlaceholder": "••••••••",
       "instructions": "1. Pour Gmail : activez la validation en deux étapes, puis créez un mot de passe d'application sur https://myaccount.google.com/apppasswords et utilisez-le comme mot de passe IMAP et SMTP.\n2. Pour Outlook / Microsoft 365 avec MFA : générez un mot de passe d'application dans les paramètres de sécurité de votre compte.\n3. Pour les autres fournisseurs : consultez leur documentation IMAP/SMTP pour les noms d'hôte et les ports.\n4. Hôtes IMAP typiques : imap.gmail.com, outlook.office365.com.\n5. Hôtes SMTP typiques : smtp.gmail.com, smtp.office365.com.",
       "disclaimer": "L'assistant obtient un accès en lecture/écriture à la boîte aux lettres que vous configurez. Envisagez d'utiliser une adresse dédiée plutôt qu'une boîte personnelle si vous souhaitez limiter la portée."
+    },
+    "threema": {
+      "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."
     }
   },
   "admin": {
@@ -390,7 +395,16 @@
     "remove": "Supprimer",
     "alreadyAdded": "Cet identifiant est déjà autorisé.",
     "telegramIdHelp": "Pour trouver votre identifiant Telegram :\n1. Ouvrez Telegram et envoyez un message à @userinfobot\n2. Il répond instantanément avec votre identifiant numérique\n3. Entrez ce numéro ici",
-    "discordIdHelp": "Pour trouver votre identifiant Discord :\n1. Activez le mode développeur dans les paramètres Discord (Avancé)\n2. Clic droit sur votre nom → Copier l'identifiant\n3. Entrez ce numéro ici"
+    "discordIdHelp": "Pour trouver votre identifiant Discord :\n1. Activez le mode développeur dans les paramètres Discord (Avancé)\n2. Clic droit sur votre nom → Copier l'identifiant\n3. Entrez ce numéro ici",
+    "threemaIdHelp": "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.",
+    "threemaSetup": {
+      "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",
+      "showQr": "Afficher le QR"
+    }
   },
   "team": {
     "title": "Équipe",

src/messages/it.json

@@ -306,6 +306,11 @@
       "smtpPassPlaceholder": "••••••••",
       "instructions": "1. Per Gmail: abilita la verifica in due passaggi, quindi crea una password per app su https://myaccount.google.com/apppasswords e usala come password IMAP e SMTP.\n2. Per Outlook / Microsoft 365 con MFA: genera una password per app nelle impostazioni di sicurezza del tuo account.\n3. Per altri provider: consulta la loro documentazione IMAP/SMTP per nomi host e porte.\n4. Host IMAP tipici: imap.gmail.com, outlook.office365.com.\n5. Host SMTP tipici: smtp.gmail.com, smtp.office365.com.",
       "disclaimer": "L'assistente ottiene accesso in lettura/scrittura alla casella di posta che configuri. Valuta l'uso di un indirizzo dedicato anziché di una casella personale se vuoi limitare la portata."
+    },
+    "threema": {
+      "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."
     }
   },
   "admin": {
@@ -390,7 +395,16 @@
     "remove": "Rimuovi",
     "alreadyAdded": "Questo ID utente è già autorizzato.",
     "telegramIdHelp": "Per trovare il tuo ID Telegram:\n1. Apri Telegram e invia un messaggio a @userinfobot\n2. Risponde istantaneamente con il tuo ID numerico\n3. Inserisci quel numero qui",
-    "discordIdHelp": "Per trovare il tuo ID Discord:\n1. Attiva la Modalità sviluppatore nelle impostazioni Discord (Avanzate)\n2. Clic destro sul tuo nome → Copia ID utente\n3. Inserisci quel numero qui"
+    "discordIdHelp": "Per trovare il tuo ID Discord:\n1. Attiva la Modalità sviluppatore nelle impostazioni Discord (Avanzate)\n2. Clic destro sul tuo nome → Copia ID utente\n3. Inserisci quel numero qui",
+    "threemaIdHelp": "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.",
+    "threemaSetup": {
+      "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",
+      "showQr": "Mostra QR"
+    }
   },
   "team": {
     "title": "Team",