@k2b/cloud 0.19.0 → 0.21.0

package/src/access/PermissionEditor.tsx

@@ -2,10 +2,11 @@ import { mutation } from "@k2b/stdlib/solid";
 import { IconButton, Placeholder, prompts, SelectChip, Tooltip, useLocale } from "@k2b/ui";
 import { createSignal, For, Show } from "solid-js";
 import { CloudAvatar } from "../account/Avatar";
-import type { AccessEntry, PermissionLevel, Principal } from "../contracts/shared";
+import type { AccessEntry, PermissionLevel, Principal, ServiceAccountKind } from "../contracts/shared";
 import { groupDisplayName } from "../shared/account-display";
 import { accessMessages } from "./messages";
 import PrincipalPicker from "./PrincipalPicker";
+import { serviceAccountKindDisplay } from "./service-account-kind";
 
 // ─────────────────────────────────────────────────────────────────────────
 // Public API
@@ -31,8 +32,13 @@ type PermissionEditorProps = {
   canEdit?: boolean;
 
   /** Grant access. The caller closes over the resource id. The optional
-   *  display metadata lets deferred form drafts retain the selected name. */
-  grantAccess: (principal: Principal, permission: GrantableLevel, display?: { displayName: string }) => Promise<AccessEntry>;
+   *  display metadata lets deferred form drafts retain the selected name
+   *  and, for service accounts, the kind shown in the row. */
+  grantAccess: (
+    principal: Principal,
+    permission: GrantableLevel,
+    display?: { displayName: string; serviceAccountKind?: ServiceAccountKind },
+  ) => Promise<AccessEntry>;
 
   /** Update an existing entry's permission level. */
   updateAccess: (accessId: string, permission: GrantableLevel) => Promise<void>;
@@ -122,14 +128,14 @@ const getEntryDisplayName = (entry: AccessEntry, t: ReturnType<typeof accessMess
   return entry.principal.groupId;
 };
 
-const getPrincipalIcon = (principal: Principal): string => {
-  switch (principal.type) {
+const getPrincipalIcon = (entry: AccessEntry, t: ReturnType<typeof accessMessages.resolve>["t"]): string => {
+  switch (entry.principal.type) {
     case "user":
       return "ti-user";
     case "group":
       return "ti-users-group";
     case "service_account":
-      return "ti-key";
+      return entry.serviceAccountKind ? serviceAccountKindDisplay(entry.serviceAccountKind, t).icon : "ti-key";
     case "authenticated":
       return "ti-lock-open-2";
     case "public":
@@ -162,8 +168,11 @@ export default function PermissionEditor(props: PermissionEditorProps) {
   }
 
   const grantMut = mutation.create({
-    mutation: async (data: { principal: Principal; permission: GrantableLevel; display: { displayName: string } }) =>
-      props.grantAccess(data.principal, data.permission, data.display),
+    mutation: async (data: {
+      principal: Principal;
+      permission: GrantableLevel;
+      display: { displayName: string; serviceAccountKind?: ServiceAccountKind };
+    }) => props.grantAccess(data.principal, data.permission, data.display),
     onSuccess: (newEntry) => {
       setEntries([...entries(), newEntry as AccessEntry]);
     },
@@ -288,7 +297,7 @@ function AccessEntryRow(props: {
         when={props.entry.principal.type === "user"}
         fallback={
           <div class="flex h-7 w-7 shrink-0 items-center justify-center rounded-full bg-zinc-200 text-zinc-600 dark:bg-zinc-700 dark:text-zinc-300">
-            <i class={`ti ${getPrincipalIcon(props.entry.principal)} text-sm`} />
+            <i class={`ti ${getPrincipalIcon(props.entry, t())} text-sm`} />
           </div>
         }
       >
@@ -301,11 +310,21 @@ function AccessEntryRow(props: {
         />
       </Show>
 
-      {/* Display name */}
-      <div class="min-w-0 flex-1">
+      {/* Display name. Name and label share one line so every row keeps its height on phones:
+          when both do not fit, each gets an equal share and the shorter one stays whole. */}
+      <div class="grid min-w-0 flex-1 auto-cols-[minmax(0,max-content)] grid-flow-col items-baseline gap-1">
         <span class="truncate text-sm">{displayName()}</span>
         <Show when={props.entry.principal.type === "public"}>
-          <span class="ml-1 text-xs text-dimmed">({t().anyoneWithLink})</span>
+          <span class="truncate text-xs text-dimmed">({t().anyoneWithLink})</span>
+        </Show>
+        <Show
+          when={
+            props.entry.principal.type === "service_account" &&
+            props.entry.serviceAccountKind &&
+            serviceAccountKindDisplay(props.entry.serviceAccountKind, t()).label
+          }
+        >
+          {(label) => <span class="truncate text-xs text-dimmed">({label()})</span>}
         </Show>
       </div>
 

package/src/access/PrincipalPicker.tsx

@@ -1,7 +1,8 @@
 import { Combobox, type ComboboxOption, useLocale } from "@k2b/ui";
-import type { Principal } from "../contracts/shared";
+import type { Principal, ServiceAccountKind } from "../contracts/shared";
 import { groupDisplayName } from "../shared/account-display";
 import { accessMessages } from "./messages";
+import { serviceAccountKindDisplay } from "./service-account-kind";
 
 export const principalKey = (p: Principal) =>
   p.type === "user"
@@ -19,7 +20,7 @@ type Entity =
       serviceAccount: {
         id: string;
         name: string;
-        kind: string;
+        kind: ServiceAccountKind;
         appId: string | null;
         resourceType: string | null;
         resourceId: string | null;
@@ -32,13 +33,15 @@ export default function PrincipalPicker(props: {
   allowAuthenticated?: boolean;
   allowServiceAccounts?: boolean;
   disabled?: boolean;
-  onSelect: (principal: Principal, display: { displayName: string }) => void;
+  /** `serviceAccountKind` is set for service accounts so a new row can show the same kind as the result. */
+  onSelect: (principal: Principal, display: { displayName: string; serviceAccountKind?: ServiceAccountKind }) => void;
 }) {
   const locale = useLocale(),
     t = () => accessMessages.resolve([locale()]).t;
-  let principals = new Map<string, Principal>();
+  type Entry = { principal: Principal; label: string; icon: string; description?: string; serviceAccountKind?: ServiceAccountKind };
+  let selectable = new Map<string, Entry>();
   const load = async (search: string, signal: AbortSignal): Promise<ComboboxOption[]> => {
-    const entries: { principal: Principal; label: string; icon: string; description?: string }[] = [];
+    const entries: Entry[] = [];
     if (props.allowAuthenticated !== false)
       entries.push({ principal: { type: "authenticated" }, label: t().allUsers, icon: "ti ti-lock-open-2" });
     if (props.allowPublic) entries.push({ principal: { type: "public" }, label: t().public, icon: "ti ti-world" });
@@ -71,26 +74,27 @@ export default function PrincipalPicker(props: {
             icon: "ti ti-users-group",
             description: e.group.description ?? undefined,
           });
-        else
+        else {
+          const account = e.serviceAccount;
+          const kind = serviceAccountKindDisplay(account.kind, t());
           entries.push({
-            principal: { type: "service_account", serviceAccountId: e.serviceAccount.id },
-            label: e.serviceAccount.name,
+            principal: { type: "service_account", serviceAccountId: account.id },
+            label: account.name,
+            // Resource-bound accounts often share a name; their binding tells them apart.
             description:
-              e.serviceAccount.kind === "user_delegated"
-                ? t().userBoundServiceAccount
-                : e.serviceAccount.kind === "agent"
-                  ? t().agentServiceAccount
-                  : e.serviceAccount.kind === "standalone"
-                    ? t().standaloneServiceAccount
-                    : [e.serviceAccount.appId, e.serviceAccount.resourceType, e.serviceAccount.resourceId].filter(Boolean).join(" · "),
-            icon: e.serviceAccount.kind === "agent" ? "ti ti-robot" : "ti ti-key",
+              account.kind === "resource_bound"
+                ? [account.appId, account.resourceType, account.resourceId].filter(Boolean).join(" · ")
+                : kind.label,
+            icon: `ti ${kind.icon}`,
+            serviceAccountKind: account.kind,
           });
+        }
       }
     }
     const existing = new Set(props.existing?.map(principalKey));
     const filtered = entries.filter((e) => !existing.has(principalKey(e.principal)));
     if (signal.aborted) return [];
-    principals = new Map(filtered.map((e) => [principalKey(e.principal), e.principal]));
+    selectable = new Map(filtered.map((e) => [principalKey(e.principal), e]));
     return filtered.map((e) => ({ id: principalKey(e.principal), label: e.label, icon: e.icon, description: e.description }));
   };
   return (
@@ -107,8 +111,8 @@ export default function PrincipalPicker(props: {
       }
       fetchData={load}
       onSelect={(option) => {
-        const principal = principals.get(option.id);
-        if (principal) props.onSelect(principal, { displayName: option.label });
+        const entry = selectable.get(option.id);
+        if (entry) props.onSelect(entry.principal, { displayName: entry.label, serviceAccountKind: entry.serviceAccountKind });
       }}
     />
   );

package/src/access/messages.ts

@@ -15,6 +15,7 @@ export const accessMessages = i18n.define({
       removeAccessConfirm: ({ name }: { name: string }) => `Remove access for ${name}?`,
       removeAccess: "Remove access",
       userBoundServiceAccount: "User-bound service account",
+      resourceBoundServiceAccount: "Resource-bound service account",
       standaloneServiceAccount: "Service account",
       agentServiceAccount: "Agent",
       noDirectGrants: "No direct access granted yet.",
@@ -74,6 +75,7 @@ export const accessMessages = i18n.define({
       removeAccessConfirm: ({ name }) => `Zugriff für ${name} entfernen?`,
       removeAccess: "Zugriff entfernen",
       userBoundServiceAccount: "Benutzergebundenes Dienstkonto",
+      resourceBoundServiceAccount: "Ressourcengebundenes Dienstkonto",
       standaloneServiceAccount: "Dienstkonto",
       agentServiceAccount: "Agent",
       noDirectGrants: "Noch kein direkter Zugriff erteilt.",

package/src/access/service-account-kind.ts

@@ -0,0 +1,28 @@
+import type { ServiceAccountKind } from "../contracts/shared";
+import type { accessMessages } from "./messages";
+
+/**
+ * The one icon and label for each service-account kind, shared by the
+ * permission editor rows, the principal picker, and entity search so the same
+ * account never appears under different names.
+ *
+ * Apps bundle their own copy of this mapping, so a kind added later by Core
+ * falls back to the key icon without a label instead of breaking the list.
+ */
+export const serviceAccountKindDisplay = (
+  kind: ServiceAccountKind,
+  t: ReturnType<typeof accessMessages.resolve>["t"],
+): { icon: string; label?: string } => {
+  switch (kind) {
+    case "agent":
+      return { icon: "ti-robot", label: t.agentServiceAccount };
+    case "user_delegated":
+      return { icon: "ti-user-key", label: t.userBoundServiceAccount };
+    case "resource_bound":
+      return { icon: "ti-box", label: t.resourceBoundServiceAccount };
+    case "standalone":
+      return { icon: "ti-key", label: t.standaloneServiceAccount };
+    default:
+      return { icon: "ti-key" };
+  }
+};

package/src/account/EntitySearch.tsx

@@ -2,6 +2,8 @@ import { timed } from "@k2b/stdlib/solid";
 import { Button, ScrollArea, TextInput, useLocale } from "@k2b/ui";
 import type { JSX } from "solid-js";
 import { createSignal, For, Show } from "solid-js";
+import { accessMessages } from "../access/messages";
+import { serviceAccountKindDisplay } from "../access/service-account-kind";
 import { groupDisplayName } from "../shared/account-display";
 import { CloudAvatar } from "./Avatar";
 
@@ -115,6 +117,8 @@ const EntitySearch = (props: EntitySearchProps) => {
   const [groups, setGroups] = createSignal<ApiGroup[]>([]);
   const [serviceAccounts, setServiceAccounts] = createSignal<ApiServiceAccount[]>([]);
   const [loading, setLoading] = createSignal(false);
+  const serviceAccountKind = (serviceAccount: ApiServiceAccount) =>
+    serviceAccountKindDisplay(serviceAccount.kind, accessMessages.resolve([locale()]).t);
 
   // Defensive dev-warning: at least one principal kind must be enabled,
   // otherwise the component is decorative-only and the caller probably
@@ -290,16 +294,13 @@ const EntitySearch = (props: EntitySearchProps) => {
             <For each={serviceAccounts()}>
               {(serviceAccount) => (
                 <ResultRow
-                  icon={serviceAccount.kind === "agent" ? "ti-robot" : "ti-key"}
+                  icon={serviceAccountKind(serviceAccount).icon}
                   title={serviceAccount.name}
                   subtitle={
-                    serviceAccount.kind === "user_delegated"
-                      ? "User-bound service account"
-                      : serviceAccount.kind === "agent"
-                        ? "Agent"
-                        : serviceAccount.kind === "standalone"
-                          ? "Service account"
-                          : [serviceAccount.appId, serviceAccount.resourceType, serviceAccount.resourceId].filter(Boolean).join(" · ")
+                    // Resource-bound accounts often share a name; their binding tells them apart.
+                    serviceAccount.kind === "resource_bound"
+                      ? [serviceAccount.appId, serviceAccount.resourceType, serviceAccount.resourceId].filter(Boolean).join(" · ")
+                      : serviceAccountKind(serviceAccount).label
                   }
                   disabled={props.disabled}
                   onSelect={() =>

package/src/ai/chat-quotas.ts

@@ -1,11 +1,18 @@
 import type { AccessSubject } from "../server/services/access";
 import { hasBillableAiPricing } from "../shared/ai-costs";
-import type { AiChatQuotaSnapshot } from "../shared/ai-quotas";
+import type { AiChatQuotaBalance, AiChatQuotaSnapshot, AiQuotaBalance } from "../shared/ai-quotas";
 import { listAssistantAiModels } from "./assistant-models";
 import { aiQuotas } from "./quotas";
 import { readAiSettingsState } from "./settings";
 
-/** Own allowances only. Grant identities and unavailable model profiles stay private. */
+/** Reduces a balance to what the chat shows. Amounts, limits, and the unit never leave the server on this path. */
+const usage = (b: AiQuotaBalance): AiChatQuotaBalance => {
+  if (b.bypassed || b.limit === null) return { scope: b.scope, unlimited: true, usedPercent: null, resetsAt: null };
+  const usedPercent = b.unknown ? null : b.used >= b.limit ? 100 : Math.max(0, Math.min(99, Math.floor((100 * b.used) / b.limit)));
+  return { scope: b.scope, unlimited: false, usedPercent, resetsAt: b.resetsAt };
+};
+
+/** Own allowances only, as usage shares. Grant identities and unavailable model profiles stay private. */
 export async function getAiChatQuotas(subject: AccessSubject): Promise<AiChatQuotaSnapshot> {
   const config = await aiQuotas.config();
   if (!config.enabled) return { enabled: false, balances: [] };
@@ -14,12 +21,9 @@ export async function getAiChatQuotas(subject: AccessSubject): Promise<AiChatQuo
   const profiles = (await readAiSettingsState()).profiles;
   return {
     enabled: snapshot.enabled,
-    unit: config.unit ?? "EUR",
     unlimitedModels: models
       .filter((model) => !hasBillableAiPricing(profiles.find((profile) => profile.id === model.id)?.pricing))
       .map((model) => model.id),
-    balances: snapshot.balances
-      .filter((b) => b.scope === "*" || models.some((m) => m.id === b.scope))
-      .map(({ sources: _sources, sourceDetails: _sourceDetails, ...balance }) => balance),
+    balances: snapshot.balances.filter((b) => b.scope === "*" || models.some((m) => m.id === b.scope)).map(usage),
   };
 }

package/src/ai/code-mode-skill.ts

@@ -4,7 +4,7 @@ import type { AiSkillTemplate } from "./skills";
 
 export const ASSISTANT_CODE_MODE_SKILL = {
   "key": "assistant:code-mode",
-  "version": 55,
+  "version": 56,
   "name": "assistant-code-mode",
   "description": "Inspect and transform unfamiliar data, analyze files, compare results across Cloud apps, or build and improve interactive and agent-only Apps in Assistant Studio. Use for quick code experiments, data analysis, file generation, resource SQL queries and combining discovered Cloud capabilities. For plain arithmetic or date offsets, answer directly or use calculate.",
   "instructions": "# Assistant code mode\n\nChoose the smallest useful result: one-off answer, exported file, or reusable\nStudio App. Apps may expose agent actions, a display-only dashboard, or both.\nPersistence is optional. One-off scripts stay in their chat and cannot be shared. Reuse an\nexisting Cloud feature when it fits. For a\nquick reading of an uploaded PDF or Office document, `read_file` can return\nMarkdown; use code for exact cells, calculations, original PDF text or positions.\n\n## Start from the contract\n\nLoad the needed `code_*` tools individually through `load_tools` and read their\ninput schemas. They are Assistant tools, not capabilities or functions inside\ncode. Discover other Cloud operations before using `capabilities.run`.\n\nRuntime namespaces are globals: no imports or package installation are needed.\nOnly relative imports of the resource's own source files are supported. There is\nno DOM or native network access. Before using a namespace, read its reference\nbelow for signatures, options and return values. Do not invent methods or infer\nan API from a familiar library. For discovered Cloud capabilities and external\nAPIs, obtain their actual contracts separately.\n\nInspect supplied data before joining, filtering or calculating: column names,\ntypes, units, date ranges and missing values. Ask only for decisions or inputs\nthat cannot be established from available evidence. For several real steps,\nkeep a short `todo_write` plan and update it as work changes; skip ceremony for a\nsmall experiment. A failed experiment should change the next hypothesis.\n\n## First file script\n\nPass exact current-chat manifest paths as `code_run.inputPaths`, and this entry\nas `code_run.code` for a small CSV:\n\n```js\nexport default async () => {\n  const [input] = await files.list();\n  if (!input) throw new Error(\"Select a CSV input.\");\n  const rows = await sheet.fromCsv(await files.read(input.name));\n  return { rows: rows.length, columns: Object.keys(rows[0] ?? {}), sample: rows.slice(0, 3) };\n};\n```\n\n`input.name` is the full path, such as `/sales.csv`; pass it unchanged to\n`files.read`, which returns a `File`. CSV rows are objects keyed by headers:\n`rows[0]` is already data. Do not drop it. For older Excel CSVs, use\n`sheet.fromCsv(file, {encoding:\"windows-1252\"})`. Inspect actual headings first.\nFor a tiny experiment without files, `export default () => ({answer:42})` suffices.\nEach run has fresh variables. No saved resource or UI is required.\n\n## Reference routing\n\nRead only the rows relevant to the task. Each link describes its own complete\nsupported surface; links within references add related workflows when needed.\n\n| Task / API | Read |\n| --- | --- |\n| Source entry, input/output files, pickers, CSV, IDs | [Runtime and files](/skills/assistant-code-mode/references/runtime.md) |\n| Inspect PDF pages, read PDF text/positions or XLSX/ODS cells, write ODS | [Documents](/skills/assistant-code-mode/references/documents.md) |\n| Generate a PDF, save one in Files, embed attachments, combine invoice HTML and XML | [PDF generation](/skills/assistant-code-mode/references/pdf.md) |\n| Exact amounts, taxes, allocation, localized money | [Money](/skills/assistant-code-mode/references/money.md) |\n| Export DATEV bookings or SEPA transfers | [DATEV and SEPA](/skills/assistant-code-mode/references/finance.md) |\n| Parse a CAMT bank report | [Bank reports](/skills/assistant-code-mode/references/camt.md) |\n| Calculate, create or read electronic invoices/XML/PDF attachments | [Electronic invoices](/skills/assistant-code-mode/references/einvoice.md) |\n| Controls, layouts and dialogs | [UI and dialogs](/skills/assistant-code-mode/references/ui.md), [Analytics UI](/skills/assistant-code-mode/references/analytics.md) |\n| Chart types, series and axes | [Charts](/skills/assistant-code-mode/references/charts.md) |\n| Long processing, progress, cancellation | [Background work](/skills/assistant-code-mode/references/work.md) |\n| Persist JSON or files locally/shared | [Storage](/skills/assistant-code-mode/references/storage.md) |\n| Copy files between stores; list and download Filesv2 beside Grids documents | [File transfers](/skills/assistant-code-mode/references/files.md) |\n| Resource SQL, schema, row CRUD, imports | [Database](/skills/assistant-code-mode/references/database.md) |\n| Generate text, classify data or extract structured fields | [AI calculations](/skills/assistant-code-mode/references/ai.md) |\n| Discovered Cloud queries/actions | [Capability calls](/skills/assistant-code-mode/references/capabilities.md) |\n| External HTTPS and personal secrets | [HTTP and secrets](/skills/assistant-code-mode/references/http.md) |\n| Call a published App action; declare handlers | [App actions](/skills/assistant-code-mode/references/app-actions.md) |\n| Reuse work across chats, create or edit an App | [Source workflow](/skills/assistant-code-mode/references/source-workflow.md) |\n| Publish, restore, copy | [Publishing](/skills/assistant-code-mode/references/publishing.md) |\n| Find recipients or change App/Skill sharing | [Access](/skills/assistant-code-mode/references/access.md) |\n| Inspect, export, clear server data, or delete an App | [Management](/skills/assistant-code-mode/references/management.md) |\n| Execute, inspect, interact, export, stop, diagnose errors | [Run and debug](/skills/assistant-code-mode/references/debugging.md) |\n| Unfamiliar inputs or cross-app investigation | [Investigation](/skills/assistant-code-mode/references/investigation.md) |\n| Complete app starters | [Examples](/skills/assistant-code-mode/references/examples.md) |\n\nFor a new app, read Source workflow and the closest complete example before\nwriting source, plus only the API references it uses. For analytical reports or\ndashboards, also load `assistant-data-analysis` for metrics and source validation.\n\n## Choose the delivery\n\nFor a one-off chart, calculator, or interactive analysis in this conversation,\nuse `code_run({code,inputPaths})`, test the controls, then\n`code_present({runId,title})`. Read [Chat visualizations](/skills/assistant-code-mode/references/chat.md).\nA successful run is visible to the agent only; present it before saying the\nuser can see it. No saved App or chat file is necessary.\n\nUse a Studio App when the user needs an independently accessible, reusable\napplication. Use `files.save`, `code_export`, and `present` when the requested\nresult is a file. These are separate delivery choices.\n\n## Verify and deliver\n\nRun the actual source (the saved revision for Apps) and test relevant controls with IDs returned by\n`code_run`/`code_interact`, including invalid inputs and picker fixtures. Creating,\ncompiling or saving source does not verify behavior. If `work.status` is\n`running`, wait with `code_inspect({runId,waitMs:30000})`; do not restart the job.\nInspect only when the returned snapshot needs more detail. Errors and\n`outputTruncated` are not successful complete results.\n\nFor a CSV, call `await files.save(sheet.toCsv(rows), \"result.csv\")` inside code;\nfor a spreadsheet, `await files.save(await sheet.toOds(sheets), \"result.ods\")`.\nThen call the **tool** `code_export` with the returned `runId` and captured file\nname, and `present` its returned chat path. `files.save` returns no path.\nReuse exported data via its path/version rather than retyping truncated output.\nReconcile row counts, exclusions and totals before reporting findings.\n\nOpen GUI apps with `code_open`. Saving or testing does\nnot replace a user's already-running app. Stop runs no longer needed that retain\nUI, jobs or output files. Never claim an unexecuted result is verified.\n\nAgent execution runs independently of the user's tab. Agent local storage is\ntemporary; shared storage, database writes and external actions are real, even\nin tests. Cancellation and source restore do not undo them. Apps select local\nfiles explicitly; they never gain implicit access to chat attachments. Use\n`code_secret` for credentials, never chat or app controls. Honor normal access\nand approval decisions; availability is not authorization for unrelated actions.",
@@ -56,7 +56,7 @@ export const ASSISTANT_CODE_MODE_SKILL = {
     },
     {
       "path": "references/einvoice.md",
-      "content": "# Electronic invoices\n\n`einvoice` is a global. These methods return Results: inspect `ok`, then use\n`data` or `error: {code,status,message,issues}`. Issue entries contain\n`{code,path,message,line?,column?}`; paths have zero-based row indices.\n\n| Call | Successful `data` |\n| --- | --- |\n| `einvoice.validate(input)` | `Invoice` |\n| `einvoice.calculate(lines)` | `InvoiceCalculation` |\n| `einvoice.serialize(invoice, {format: \"zugferd-2.5-en16931\"})` | `{format, xml: string, bytes: Uint8Array}` |\n| `einvoice.parseXml(xml, options?)` | `ParsedInvoice` |\n| `await einvoice.parsePdf(bytes, options?)` | `ParsedInvoice` |\n| `einvoice.parseXml(xml, {mode: \"incoming\"})` | `ParsedIncomingInvoice` |\n| `await einvoice.parsePdf(bytes, {mode: \"incoming\"})` | `ParsedIncomingInvoice` |\n\nAll calls except `parsePdf` are synchronous. `parsePdf` takes a `Uint8Array`,\nfor example `new Uint8Array(await file.arrayBuffer())`. It reads embedded XML,\nnot scanned pages or arbitrary visual invoice layouts. For those, use the\n[local PDF text reader](documents.md) or the agent's document/vision tools.\n\nThe supported slice covers EUR CII EN16931 invoices, credit notes and self-billing,\nVAT categories S/Z/E/AE/K/G/O, units C62/HUR/DAY/KGM. Generation does not\nsupport UBL, XRechnung, discounts or prepayments. Readers preserve declared totals;\nparsing is not arithmetic verification. Validation is not XSD or Schematron\ncertification. No XSD validator is exposed.\n\n## Complete input and result shapes\n\nType descriptions only; no imports are needed. All fields are required unless\nmarked `?`; unknown fields are rejected.\n\n```ts\ntype Party = {\n  name: string; id?: string; vatId: string; // \"\" when the party has no VAT ID\n  address: {line1: string; city: string; postalCode: string; countryCode: string};\n};\ntype Tax = {\n  taxCategory?: \"S\" | \"Z\" | \"E\" | \"AE\" | \"K\" | \"G\" | \"O\"; // default \"S\"\n  taxRate: string; taxExemptionReason?: string; taxExemptionReasonCode?: string;\n};\ntype InvoiceLine = Tax & {\n  id: string; name: string; description?: string;\n  quantity: string; unitPrice: string; unitCode: \"C62\" | \"HUR\" | \"DAY\" | \"KGM\";\n  netAmount?: string;\n};\ntype InvoiceTotals = {\n  netAmount: string; taxAmount: string; grossAmount: string; dueAmount: string;\n  taxGroups: (Tax & {netAmount: string; taxAmount: string})[];\n};\ntype Invoice = {\n  kind: \"invoice\" | \"creditNote\" | \"selfBilling\";\n  number: string; invoiceDate: string; serviceDate: string; dueDate: string;\n  currency: \"EUR\"; seller: Party & {taxRegistrationId?: string}; buyer: Party;\n  deliverToCountryCode?: string; buyerReference: string;\n  notes?: string[];\n  precedingInvoice?: {number: string; invoiceDate: string};\n  payment: {iban: string; accountName: string};\n  lines: InvoiceLine[]; totals?: InvoiceTotals;\n};\ntype InvoiceCalculation = InvoiceTotals & {\n  lines: (InvoiceLine & {netAmount: string})[];\n};\ntype ParsedInvoice = {\n  format: \"zugferd-2.5-en16931\"; profile: string; xml: string;\n  invoice: Invoice; filename?: string;\n};\ntype ParseOptions = {maxCharacters?: number; maxElements?: number; maxDepth?: number};\ntype PdfOptions = ParseOptions & {maxPdfBytes?: number};\n```\n\nXML options default to 10 Mi UTF-16 code units, 100,000 elements, depth 64.\nPDF input defaults to 25 MiB. Overrides must be positive safe integers.\nA parser result's business fields are under **`data.invoice`**. Calculated\namounts are directly under **`data.netAmount`**, etc., with no `data.totals` wrapper.\n\n- Dates are real `YYYY-MM-DD` dates; `dueDate` cannot precede `invoiceDate`.\n  Credit notes require `precedingInvoice`, whose date cannot be later than the\n  credit note; other kinds cannot supply it. Credit-note amounts stay unsigned.\n- Lines: 1–1000, unique IDs. Quantities are positive, prices nonnegative,\n  VAT rates at most 100. Decimal strings allow up to four\n  fractional digits and no leading zeros. Totals/net amounts require exactly\n  two fractional digits; do not convert through JavaScript Number.\n- Country codes: two uppercase letters. `payment.iban` must be valid.\n  Required text is nonblank valid XML text. Limits: number/reference/line ID/VAT ID\n  100; names/address line/accountName 200; city 100; postalCode 20;\n  line description and each note 4000; at most 100 notes.\n- Category S needs a positive rate; every other category uses `taxRate: \"0\"`\n  and zero tax. E/AE/K/G/O need `taxExemptionReason` or a VATEX\n  `taxExemptionReasonCode`; S/Z forbid both. O cannot be mixed with other\n  categories and requires `vatId: \"\"` for both parties. A seller without a VAT\n  ID needs `seller.id` and, outside O, `seller.taxRegistrationId`. AE/K need a\n  buyer VAT ID, K/G a seller VAT ID, and K `deliverToCountryCode`.\n- `calculate` rounds each line half up to cents, then VAT per category and rate. It recalculates\n  line `netAmount`; `serialize` also rejects supplied line/totals values that\n  disagree. Render these calculated amounts in HTML instead of another arithmetic path.\n\n## Minimal supported invoice\n\nUse real business data and an app-owned invoice number. This illustrative\nfixture demonstrates the required fields; it is not a document to issue.\n\n```js\nconst invoice = {\n  kind: \"invoice\",\n  number: \"EXAMPLE-42\",\n  invoiceDate: \"2026-09-15\",\n  serviceDate: \"2026-09-15\",\n  dueDate: \"2026-09-30\",\n  currency: \"EUR\",\n  seller: {\n    name: \"Example Seller\", vatId: \"DE123456789\",\n    address: { line1: \"Street 1\", city: \"Ulm\", postalCode: \"89073\", countryCode: \"DE\" },\n  },\n  buyer: {\n    name: \"Example Buyer\", vatId: \"DE987654321\",\n    address: { line1: \"Street 2\", city: \"Berlin\", postalCode: \"10115\", countryCode: \"DE\" },\n  },\n  buyerReference: \"ORDER-42\",\n  payment: { iban: \"DE89370400440532013000\", accountName: \"Example Seller\" },\n  lines: [{ id: \"1\", name: \"Service\", quantity: \"2.0000\", unitPrice: \"50.0000\", unitCode: \"HUR\", taxRate: \"19.00\" }],\n};\nconst result = einvoice.serialize(invoice, { format: \"zugferd-2.5-en16931\" });\nif (!result.ok) throw new Error(JSON.stringify(result.error));\nawait files.save(new Blob([result.data.bytes], { type: \"application/xml\" }), \"invoice.xml\");\n```\n\nNever infer a missing VAT identifier, tax category, exemption reason, account\nor business reference merely to satisfy input validation.\n\n## Reading received invoices\n\n`{mode: \"incoming\"}` (plus the same limits) reads a broader separate model:\nalso XRechnung 3.0/2.3 CII, other currencies, discounts, prepayments, all\npayment means and optional references. `data` is\n`{format: \"cii-en16931\", profile, xml, invoice, unmapped, filename?}`.\nAmounts are declared strings, never recalculated; O lines have no `taxRate`.\n`unmapped` lists supplementary XML elements and attributes with their paths; review it before\naccounting. Do not pass this `invoice` to `validate` or `serialize`.\n\nFor an invoice PDF, pass `serialized.data.xml` to\n[`pdf.facturX`](pdf.md) with profile `\"EN 16931\"` and matching HTML.\nNumbering, business mapping, issuance and persistence belong to the app.\n"
+      "content": "# Electronic invoices\n\n`einvoice` is a global. These methods return Results: inspect `ok`, then use\n`data` or `error: {code,status,message,issues}`. Issue entries contain\n`{code,path,message,line?,column?}`; paths have zero-based row indices.\n\n| Call | Successful `data` |\n| --- | --- |\n| `einvoice.validate(input)` | `Invoice` |\n| `einvoice.calculate(lines)` | `InvoiceCalculation` |\n| `einvoice.serialize(invoice, {format: \"zugferd-2.5-en16931\"})` | `{format, xml: string, bytes: Uint8Array}` |\n| `einvoice.parseXml(xml, options?)` | `ParsedInvoice` |\n| `await einvoice.parsePdf(bytes, options?)` | `ParsedInvoice` |\n| `einvoice.parseXml(xml, {mode: \"incoming\"})` | `ParsedIncomingInvoice` |\n| `await einvoice.parsePdf(bytes, {mode: \"incoming\"})` | `ParsedIncomingInvoice` |\n\nAll calls except `parsePdf` are synchronous. `parsePdf` takes a `Uint8Array`,\nfor example `new Uint8Array(await file.arrayBuffer())`. It reads embedded XML,\nnot scanned pages or arbitrary visual invoice layouts. For those, use the\n[local PDF text reader](documents.md) or the agent's document/vision tools.\n\nThe supported slice covers EUR CII EN16931 invoices, credit notes, self-billing\nand self-billed credit notes, VAT categories S/Z/E/AE/K/G/O, units\nC62/HUR/DAY/KGM, and payment by credit transfer, cash, online service or\nclearing, or no payment means. Generation does not support UBL, XRechnung,\ndiscounts or prepayments. Readers preserve declared totals; parsing is not\narithmetic verification. Validation is not XSD or Schematron certification.\nNo XSD validator is exposed.\n\n## Complete input and result shapes\n\nType descriptions only; no imports are needed. All fields are required unless\nmarked `?`; unknown fields are rejected.\n\n```ts\ntype Party = {\n  name: string; id?: string; vatId: string; // \"\" when the party has no VAT ID\n  address: {line1: string; city: string; postalCode: string; countryCode: string};\n};\ntype Tax = {\n  taxCategory?: \"S\" | \"Z\" | \"E\" | \"AE\" | \"K\" | \"G\" | \"O\"; // default \"S\"\n  taxRate: string; taxExemptionReason?: string; taxExemptionReasonCode?: string;\n};\ntype InvoiceLine = Tax & {\n  id: string; name: string; description?: string;\n  quantity: string; unitPrice: string; unitCode: \"C62\" | \"HUR\" | \"DAY\" | \"KGM\";\n  netAmount?: string;\n};\ntype InvoiceTotals = {\n  netAmount: string; taxAmount: string; grossAmount: string; dueAmount: string;\n  taxGroups: (Tax & {netAmount: string; taxAmount: string})[];\n};\ntype Invoice = {\n  kind: \"invoice\" | \"creditNote\" | \"selfBilling\" | \"selfBillingCreditNote\";\n  number: string; invoiceDate: string; dueDate: string;\n  serviceDate?: string; period?: {startDate?: string; endDate?: string};\n  currency: \"EUR\"; seller: Party & {taxRegistrationId?: string}; buyer: Party;\n  deliverToCountryCode?: string; buyerReference: string;\n  notes?: string[];\n  precedingInvoice?: {number: string; invoiceDate: string};\n  payment?: {\n    typeCode?: \"10\" | \"30\" | \"58\" | \"68\" | \"97\"; // default \"58\"\n    information?: string; iban?: string; accountName?: string;\n  };\n  lines: InvoiceLine[]; totals?: InvoiceTotals;\n};\ntype InvoiceCalculation = InvoiceTotals & {\n  lines: (InvoiceLine & {netAmount: string})[];\n};\ntype ParsedInvoice = {\n  format: \"zugferd-2.5-en16931\"; profile: string; xml: string;\n  invoice: Invoice; filename?: string;\n};\ntype ParseOptions = {maxCharacters?: number; maxElements?: number; maxDepth?: number};\ntype PdfOptions = ParseOptions & {maxPdfBytes?: number};\n```\n\nXML options default to 10 Mi UTF-16 code units, 100,000 elements, depth 64.\nPDF input defaults to 25 MiB. Overrides must be positive safe integers.\nA parser result's business fields are under **`data.invoice`**. Calculated\namounts are directly under **`data.netAmount`**, etc., with no `data.totals` wrapper.\nA parsed invoice carries `serviceDate`, `period`, `payment` and the account\nfields only when the XML does: check each before reading it, for example\n`invoice.payment?.iban`. A parsed `payment` always has its `typeCode`.\n\n- Dates are real `YYYY-MM-DD` dates; `dueDate` cannot precede `invoiceDate`.\n  `serviceDate` (delivery date) and `period` (invoicing period) are optional\n  and can be combined. A `period` needs a start or an end, and its end cannot\n  precede its start.\n- `creditNote` and `selfBillingCreditNote` require `precedingInvoice`; every\n  kind may supply it, and its date cannot be later than `invoiceDate`.\n  Credit-note amounts stay unsigned.\n- `payment.typeCode`: `\"58\"` SEPA credit transfer, `\"30\"` credit transfer,\n  `\"10\"` cash, `\"68\"` online payment service, `\"97\"` clearing between\n  partners. 30 and 58 require `iban`; `accountName` is optional. The other\n  codes forbid both. `information` is free text for any code. Omit `payment`\n  when no payment means applies. Any other code fails both writing and the\n  default reader; read such invoices with `{mode: \"incoming\"}`.\n- Lines: 1–1000, unique IDs. Quantities are positive, prices nonnegative,\n  VAT rates at most 100. Decimal strings allow up to four\n  fractional digits and no leading zeros. Totals/net amounts require exactly\n  two fractional digits; do not convert through JavaScript Number.\n- Country codes: two uppercase letters. A supplied `payment.iban` must be valid.\n  Required text is nonblank valid XML text. Limits: number/reference/line ID/VAT ID\n  100; names/address line/accountName 200; city 100; postalCode 20;\n  line description, `payment.information` and each note 4000; at most 100 notes.\n- Category S needs a positive rate; every other category uses `taxRate: \"0\"`\n  and zero tax. E/AE/K/G/O need `taxExemptionReason` or a VATEX\n  `taxExemptionReasonCode`; S/Z forbid both. O cannot be mixed with other\n  categories and requires `vatId: \"\"` for both parties. A seller without a VAT\n  ID needs `seller.id` and, outside O, `seller.taxRegistrationId`. AE/K need a\n  buyer VAT ID, K/G a seller VAT ID, and K `deliverToCountryCode` plus a\n  `serviceDate` or `period`.\n- `calculate` rounds each line half up to cents, then VAT per category and rate. It recalculates\n  line `netAmount`; `serialize` also rejects supplied line/totals values that\n  disagree. Render these calculated amounts in HTML instead of another arithmetic path.\n\n## Example invoice\n\nUse real business data and an app-owned invoice number. This illustrative\nfixture is a credit-transfer invoice with a delivery date; it is not a\ndocument to issue.\n\n```js\nconst invoice = {\n  kind: \"invoice\",\n  number: \"EXAMPLE-42\",\n  invoiceDate: \"2026-09-15\",\n  serviceDate: \"2026-09-15\",\n  dueDate: \"2026-09-30\",\n  currency: \"EUR\",\n  seller: {\n    name: \"Example Seller\", vatId: \"DE123456789\",\n    address: { line1: \"Street 1\", city: \"Ulm\", postalCode: \"89073\", countryCode: \"DE\" },\n  },\n  buyer: {\n    name: \"Example Buyer\", vatId: \"DE987654321\",\n    address: { line1: \"Street 2\", city: \"Berlin\", postalCode: \"10115\", countryCode: \"DE\" },\n  },\n  buyerReference: \"ORDER-42\",\n  payment: { iban: \"DE89370400440532013000\", accountName: \"Example Seller\" },\n  lines: [{ id: \"1\", name: \"Service\", quantity: \"2.0000\", unitPrice: \"50.0000\", unitCode: \"HUR\", taxRate: \"19.00\" }],\n};\nconst result = einvoice.serialize(invoice, { format: \"zugferd-2.5-en16931\" });\nif (!result.ok) throw new Error(JSON.stringify(result.error));\nawait files.save(new Blob([result.data.bytes], { type: \"application/xml\" }), \"invoice.xml\");\n```\n\nNever infer a missing VAT identifier, tax category, exemption reason, delivery\ndate, account or business reference merely to satisfy input validation.\n\n## Reading received invoices\n\n`{mode: \"incoming\"}` (plus the same limits) reads a broader separate model:\nalso XRechnung 3.0/2.3 CII, other currencies, discounts, prepayments, all\npayment means and optional references. `data` is\n`{format: \"cii-en16931\", profile, xml, invoice, unmapped, filename?}`.\nAmounts are declared strings, never recalculated; O lines have no `taxRate`.\n`unmapped` lists supplementary XML elements and attributes with their paths; review it before\naccounting. Do not pass this `invoice` to `validate` or `serialize`.\n\nFor an invoice PDF, pass `serialized.data.xml` to\n[`pdf.facturX`](pdf.md) with profile `\"EN 16931\"` and matching HTML.\nNumbering, business mapping, issuance and persistence belong to the app.\n"
     },
     {
       "path": "references/examples.md",

package/src/ai/inference-calls.ts

@@ -98,7 +98,7 @@ export async function beginAiCall(
           return {
             error: new AiQuotaError(
               "quota_usage_unknown",
-              "Chat costs could not be measured. Reset the allowance or wait for the next window.",
+              "Chat usage could not be measured. Reset the allowance or wait for the next window.",
             ),
           };
         const rule = config.rules.find((rule) => rule.scope === balance.scope)!;
@@ -127,7 +127,7 @@ export async function beginAiCall(
           error:
             context.kind === "background"
               ? new AiBackgroundAdmissionError(backgroundHeadroom !== undefined && inputCost + outputPrice <= backgroundHeadroom)
-              : new AiQuotaError("quota_exhausted", "Chat cost limit reached."),
+              : new AiQuotaError("quota_exhausted", "Chat usage limit reached."),
         };
       const reserveOutput = Math.min(requestedOutput ?? outputBound ?? affordable, affordable);
       // Preserve adapter defaults unless an explicit maximum or budget requires a cap.

package/src/ai/model-access.ts

@@ -1,6 +1,6 @@
 import { sql } from "bun";
 import { z } from "zod";
-import { type AccessEntry, type Principal, PrincipalSchema } from "../contracts/shared";
+import { type AccessEntry, type Principal, PrincipalSchema, type ServiceAccountKind } from "../contracts/shared";
 import { type AccessSubject, buildAccessPrincipalCondition, createAccess } from "../server/services/access";
 import { toPgTextArray } from "../services/postgres";
 import type { AiSettingsError } from "./types";
@@ -114,11 +114,13 @@ export const aiModelAccess = {
         service_account_id: string | null;
         authenticated_only: boolean | null;
         display_name: string | null;
+        service_account_kind: ServiceAccountKind | null;
       }[]
     >`
       SELECT resource.profile_id, resource.revision, access.id, access.created_at,
         access.user_id, access.group_id, access.service_account_id, access.authenticated_only,
-        COALESCE(users.display_name, groups.name, service_accounts.name) AS display_name
+        COALESCE(users.display_name, groups.name, service_accounts.name) AS display_name,
+        service_accounts.kind AS service_account_kind
       FROM ai.model_access_resources resource LEFT JOIN ai.model_access model ON model.profile_id = resource.profile_id
       LEFT JOIN auth.access access ON access.id = model.access_id
       LEFT JOIN auth.users users ON users.id = access.user_id
@@ -146,6 +148,7 @@ export const aiModelAccess = {
         permission: "read",
         createdAt: row.created_at.toISOString(),
         ...(row.display_name ? { displayName: row.display_name } : {}),
+        ...(row.service_account_kind ? { serviceAccountKind: row.service_account_kind } : {}),
       });
     }
     return Object.fromEntries(result);

package/src/ai/projects.ts

@@ -1,6 +1,6 @@
 import { type SQL, type SQLQuery, sql } from "bun";
 import type { CloudResourceRef } from "../contracts/capabilities";
-import { AuthenticatedPrincipalSchema } from "../contracts/shared";
+import { AuthenticatedPrincipalSchema, type ServiceAccountKind } from "../contracts/shared";
 import type { AccessSubject } from "../server";
 import {
   buildAccessPrincipalCondition,
@@ -82,6 +82,8 @@ export type AiProjectAccess = {
   principal: Principal;
   permission: AiProjectPermission;
   displayName?: string;
+  /** Kind of a `service_account` principal; presentation only. */
+  serviceAccountKind?: ServiceAccountKind;
   createdAt: string;
 };
 
@@ -155,6 +157,7 @@ type ProjectAccessRow = {
   permission: AiProjectPermission;
   created_at: Date | string;
   display_name: string | null;
+  service_account_kind: ServiceAccountKind | null;
 };
 
 type AdminProjectRow = ProjectRow & {
@@ -257,6 +260,7 @@ const toProjectAccess = (row: ProjectAccessRow): AiProjectAccess => ({
           : { type: "public" },
   permission: row.permission,
   displayName: row.display_name ?? undefined,
+  serviceAccountKind: row.service_account_kind ?? undefined,
   createdAt: iso(row.created_at),
 });
 
@@ -287,7 +291,8 @@ const listProjectAccess = async (projectId: string, db: SQL = sql): Promise<AiPr
     SELECT project_access.short_id, access.user_id, access.group_id, access.service_account_id, access.authenticated_only,
            access.permission, access.created_at,
            COALESCE(users.display_name, groups.name, service_accounts.name,
-             CASE WHEN access.authenticated_only THEN 'All authenticated users' ELSE 'Public' END) AS display_name
+             CASE WHEN access.authenticated_only THEN 'All authenticated users' ELSE 'Public' END) AS display_name,
+           service_accounts.kind AS service_account_kind
     FROM ai.project_access project_access
     JOIN auth.access access ON access.id = project_access.access_id
     LEFT JOIN auth.users users ON users.id = access.user_id

package/src/ai/quota-report.ts

@@ -18,7 +18,12 @@ export async function quotaAdminConfig() {
       ...rule,
       grants: rule.grants.map(() => {
         const grant = grants[offset++]!;
-        return { principal: grant.principal, limit: grant.limit, displayName: grant.displayName };
+        return {
+          principal: grant.principal,
+          limit: grant.limit,
+          displayName: grant.displayName,
+          serviceAccountKind: grant.serviceAccountKind,
+        };
       }),
     })),
   };

package/src/ai/quotas.ts

@@ -124,7 +124,7 @@ export const aiQuotas = {
           "quota_usage_unknown",
           "Chat usage could not be measured. Contact an administrator or wait for the quota reset.",
         );
-      if (b.used >= b.limit) throw new AiQuotaError("quota_exhausted", `Chat cost limit reached. Resets at ${b.resetsAt}.`);
+      if (b.used >= b.limit) throw new AiQuotaError("quota_exhausted", `Chat usage limit reached. Resets at ${b.resetsAt}.`);
     }
     return snapshot.balances.some((b) => !b.bypassed && b.limit !== null);
   },

package/src/ai/skills.ts

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { type SQL, type SQLQuery, sql } from "bun";
-import { AuthenticatedPrincipalSchema } from "../contracts/shared";
+import { AuthenticatedPrincipalSchema, type ServiceAccountKind } from "../contracts/shared";
 import type { AccessSubject } from "../server";
 import {
   buildAccessPrincipalCondition,
@@ -58,6 +58,8 @@ export type AiSkillAccess = {
   principal: Principal;
   permission: AiSkillPermission;
   displayName?: string;
+  /** Kind of a `service_account` principal; presentation only. */
+  serviceAccountKind?: ServiceAccountKind;
   createdAt: string;
 };
 
@@ -128,6 +130,7 @@ type SkillAccessRow = {
   permission: AiSkillPermission;
   created_at: Date | string;
   display_name: string | null;
+  service_account_kind: ServiceAccountKind | null;
 };
 
 type SkillSummaryRow = Pick<SkillRow, "id" | "short_id" | "name" | "description" | "revision" | "created_at" | "updated_at"> & {
@@ -282,7 +285,8 @@ const listSkillAccess = async (skillId: string, db: SQL = sql): Promise<AiSkillA
     SELECT skill_access.short_id, access.user_id, access.group_id, access.service_account_id, access.authenticated_only,
            access.permission, access.created_at,
            COALESCE(users.display_name, groups.name, service_accounts.name,
-             CASE WHEN access.authenticated_only THEN 'All authenticated users' ELSE 'Public' END) AS display_name
+             CASE WHEN access.authenticated_only THEN 'All authenticated users' ELSE 'Public' END) AS display_name,
+           service_accounts.kind AS service_account_kind
     FROM ai.skill_access skill_access
     JOIN auth.access access ON access.id = skill_access.access_id
     LEFT JOIN auth.users users ON users.id = access.user_id
@@ -305,6 +309,7 @@ const listSkillAccess = async (skillId: string, db: SQL = sql): Promise<AiSkillA
             : { type: "public" },
     permission: row.permission,
     displayName: row.display_name ?? undefined,
+    serviceAccountKind: row.service_account_kind ?? undefined,
     createdAt: iso(row.created_at),
   }));
 };

package/src/cli/access.ts

@@ -238,6 +238,7 @@ const entryTypeLabel = (entry: AccessEntry): string => {
   if (entry.principal.type !== "service_account") return entry.principal.type;
   if (entry.serviceAccountKind === "agent") return "agent";
   if (entry.serviceAccountKind === "resource_bound") return "resource-bound";
+  if (entry.serviceAccountKind === "user_delegated") return "user-bound";
   return "service account";
 };
 

package/src/config/env.ts

@@ -72,6 +72,11 @@ const registry = defineEnv({
     example: "localhost:3000",
     doc: "Public Cloud URL used to bootstrap the `app.url` setting; the stored setting wins once written.",
   },
+  GOTENBERG_URL: {
+    schema: z.string(),
+    example: "http://localhost:3001",
+    doc: "Internal Gotenberg base URL used to bootstrap the `gotenberg.url` PDF rendering setting; the stored setting wins once written.",
+  },
   APP_SECRET: {
     schema: z.string(),
     default: "",

package/src/server/locale.ts

@@ -9,20 +9,33 @@ type LocaleContext = {
   req: { raw: { headers: Headers } };
 };
 
+/**
+ * Languages Cloud ships platform catalogs for and offers in its language
+ * picker. `Accept-Language` negotiation prefers a tag in one of these.
+ */
+const CATALOG_LANGUAGES = new Set(["en", "de"]);
+
 /**
  * The caller's explicit locale preference, or `undefined` when the request
  * carries none. Precedence: `x-cloud-locale` transport metadata, then the
- * `cloud.locale` cookie, then `Accept-Language` in quality order. Every
- * candidate is canonicalized; invalid tags fall through to the next source.
+ * `cloud.locale` cookie, then `Accept-Language`. Every candidate is
+ * canonicalized; invalid tags fall through to the next source.
+ *
+ * `Accept-Language` picks the first tag in quality order whose language has a
+ * catalog, keeping its region (`de-CH`, `en-GB`) for formatting. Without such a
+ * tag, the first valid tag still wins so formatting follows the browser.
  */
 export const preferredLocale = (headers: Headers): string | undefined => {
   const explicit = canonicalLocale(headers.get(LOCALE_HEADER)) ?? canonicalLocale(readCookie(headers, LOCALE_COOKIE));
   if (explicit) return explicit;
+  let firstValid: string | undefined;
   for (const tag of i18n.parseAcceptLanguage(headers.get("Accept-Language"))) {
     const candidate = canonicalLocale(tag);
-    if (candidate) return candidate;
+    if (!candidate) continue;
+    if (CATALOG_LANGUAGES.has(new Intl.Locale(candidate).language)) return candidate;
+    firstValid ??= candidate;
   }
-  return undefined;
+  return firstValid;
 };
 
 /**