@cosmicdrift/kumiko-samples 0.391.1 → 0.392.0

package/samples/apps/ui-walkthrough/scripts/emit-e2e-data.ts

@@ -1,8 +1,8 @@
-// Emitter für e2e/.e2e-data.json. Läuft unter bun, lädt die volle
-// framework-runtime, baut die Registry und schreibt generateE2ESpec()-
-// Output als JSON. Playwrights globalSetup ruft dieses Script vor
-// jedem Run als Subprozess — dadurch landet framework-runtime NIE im
-// Playwright-Worker (wo sie mit Playwrights expect kollidiert).
+// Emitter for e2e/.e2e-data.json. Runs under bun, loads the full
+// framework-runtime, builds the registry and writes the generateE2ESpec()
+// output as JSON. Playwright's globalSetup calls this script before
+// every run as a subprocess — so framework-runtime NEVER lands in the
+// Playwright worker (where it collides with Playwright's expect).
 
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";

package/samples/apps/ui-walkthrough/src/app/auth-constants.ts

@@ -1,21 +1,21 @@
-// Reine Konstanten — kein Framework-Import. Wird sowohl von seed.ts
-// (server-Seite, idempotent admin-Anlage) als auch vom E2E-Helper
-// `e2e/_helpers/login.ts` gelesen.
+// Pure constants — no framework import. Read both by seed.ts
+// (server side, idempotent admin creation) and by the E2E helper
+// `e2e/_helpers/login.ts`.
 //
-// Warum getrennt: e2e-Specs laufen im Playwright-Worker, der nichts aus
-// `@cosmicdrift/kumiko-testing/helpers` (zieht `vitest`) oder
-// `@cosmicdrift/kumiko-bundled-features/.../testing` (zieht das ebenfalls) ertragen
-// kann — Vitest's expect redefined Object.prototype-Symbole und kollidiert
-// mit Playwrights expect. Diese Datei bleibt importchain-leer und ist die
-// einzige sichere shared Quelle für die Login-Strings.
+// Why separate: e2e specs run in the Playwright worker, which cannot tolerate anything from
+// `@cosmicdrift/kumiko-testing/helpers` (pulls in `vitest`) or
+// `@cosmicdrift/kumiko-bundled-features/.../testing` (pulls that in too) —
+// Vitest's expect redefines Object.prototype symbols and collides
+// with Playwright's expect. This file stays import-chain-empty and is the
+// only safe shared source for the login strings.
 
 export const ADMIN_EMAIL = "admin@kumiko.dev";
 export const ADMIN_PASSWORD = "kumiko-admin";
 
-// Tenant-IDs gespiegelt zwischen server.ts (TenantId-Cast) und client.tsx
-// (plain string für tenantName-Mapping). Hier zentral als plain strings,
-// da diese Datei framework-frei bleibt — server.ts macht den
-// `as TenantId`-Cast lokal.
+// Tenant IDs mirrored between server.ts (TenantId cast) and client.tsx
+// (plain string for tenantName mapping). Kept centrally here as plain strings
+// since this file stays framework-free — server.ts does the
+// `as TenantId` cast locally.
 export const DEV_TENANT_ID = "00000000-0000-4000-8000-000000000001";
 export const BETA_TENANT_ID = "00000000-0000-4000-8000-000000000002";
 

package/samples/apps/ui-walkthrough/src/app/client.tsx

@@ -1,5 +1,5 @@
-// Browser-Entry. Sammelt nur die ClientFeatures (auth + tasks) und
-// übergibt Shell + clientFeatures an createKumikoApp.
+// Browser entry. Only collects the ClientFeatures (auth + tasks) and
+// hands shell + clientFeatures to createKumikoApp.
 
 import { emailPasswordClient } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/web";
 import { billingFoundationClient } from "@cosmicdrift/kumiko-bundled-features/billing-foundation/web";

package/samples/apps/ui-walkthrough/src/app/server.ts

@@ -1,13 +1,13 @@
 // @runtime dev
 //
-// Dev-Server für ui-walkthrough. runDevApp mischt die Standard-Features
-// (config/user/tenant/auth) automatisch dazu wenn `auth` gesetzt ist und
-// ruft seedAdmin im onAfterSetup. Schema landet als window.__KUMIKO_
-// SCHEMA__-Injection im Browser.
+// Dev server for ui-walkthrough. runDevApp mixes in the standard features
+// (config/user/tenant/auth) automatically when `auth` is set and
+// calls seedAdmin in onAfterSetup. The schema lands in the browser as a
+// window.__KUMIKO_SCHEMA__ injection.
 //
-// Auth-Mode aktiv: Client muss sich über den Login-Screen anmelden,
-// kein Auto-Mint-JWT mehr. Persistent-DB-Modus über KUMIKO_DEV_DB_NAME
-// in der Umgebung.
+// Auth mode active: the client must log in via the login screen,
+// no more auto-mint JWT. Persistent DB mode via KUMIKO_DEV_DB_NAME
+// in the environment.
 
 import { createUnsubscribeRoutes } from "@cosmicdrift/kumiko-bundled-features/delivery";
 import { runDevApp } from "@cosmicdrift/kumiko-dev-server";
@@ -27,17 +27,17 @@ import { seedRental } from "./seed-rental";
 import { seedTemplates } from "./seed-templates";
 import { seedVehicles } from "./seed-vehicles";
 
-// Zwei feste Tenants — Admin ist in beiden Mitglied damit der
-// TenantSwitcher im Sample sichtbar ist (rendert nur bei >1 Tenant).
-// Unterschiedliche Rollen pro Tenant beweisen tenant-isolierte
-// Memberships. TenantId-Cast lokal an der Use-Site (auth-constants.ts
-// bleibt framework-frei für den E2E-Helper-Pfad).
+// Two fixed tenants — the admin is a member of both so the
+// TenantSwitcher is visible in the sample (renders only with >1 tenant).
+// Different roles per tenant prove tenant-isolated
+// memberships. TenantId cast local at the use site (auth-constants.ts
+// stays framework-free for the E2E helper path).
 
 await runDevApp({
   features: [...APP_FEATURES],
   seeds: [seedTasks, seedRental, seedVehicles, seedTemplates, seedPlanTerms],
-  // PORT env-var override für Playwright-e2e-Runs (config zeigt auf 4174);
-  // sonst lokal-Default 4173.
+  // PORT env var override for Playwright e2e runs (config points to 4174);
+  // otherwise local default 4173.
   port: Number.parseInt(process.env["PORT"] ?? "4173", 10),
   // Logo and attachment uploads of the mail editor need a file store.
   files: { storageProvider: createInMemoryFileProvider() },

package/samples/apps/ui-walkthrough/src/app/shell.tsx

@@ -1,6 +1,6 @@
-// AppShell mit Brand und User-Menü im Sidebar-Footer. Tenant-, Sprach- und
-// Theme-Wahl hängen im User-Menü. Tenant-Name-Mapping bleibt im Shell —
-// App-spezifische Logik, kein Framework-Konzept.
+// AppShell with brand and user menu in the sidebar footer. Tenant, language and
+// theme choice live in the user menu. Tenant name mapping stays in the shell —
+// app-specific logic, not a framework concept.
 
 import {
   TenantMenuItems,

package/samples/apps/use-all-bundled/bin/main.ts

@@ -33,11 +33,11 @@ await runProdApp({
   // every bundled feature mounted. Real apps wire createPgKmsAdapter(...).
   kms: new InMemoryKmsAdapter(),
   blindIndexKey: Buffer.alloc(32, 7).toString("base64"),
-  // migrations default ("./kumiko/migrations") — Boot-mode springt vor dem
-  // Schema-Drift-Gate raus, der Pfad ist hier nur der runProdApp-Default.
-  // auth.admin triggert composeFeatures(includeBundled:true) — auto-mounts
-  // config + user + tenant + auth-email-password. Boot-mode exitiert
-  // bevor admin-Seeding läuft, der Wert ist nur ein Stub für die Typen.
+  // migrations default ("./kumiko/migrations") — boot mode exits before the
+  // schema drift gate, the path here is only the runProdApp default.
+  // auth.admin triggers composeFeatures(includeBundled:true) — auto-mounts
+  // config + user + tenant + auth-email-password. Boot mode exits
+  // before admin seeding runs, the value is only a stub for the types.
   auth: {
     admin: {
       email: "smoke@use-all-bundled.local",

package/samples/apps/use-all-bundled/feature-manifest.json

@@ -35,7 +35,7 @@
     },
     {
       "name": "admin-shell",
-      "description": "Registers tenant-admin and platform-admin workspaces with provider nav into owner-feature screens (`tenant:screen:members`, `audit:screen:audit-log`, `audit:screen:audit-log-all-tenants`, `tenant:screen:tenant-list`, `jobs:screen:job-runs`, optional `tier-engine:screen:tier-admin`, optional `cap-overview:screen:my-caps`/`cap-overview:screen:tenant-cap-list`, optional `document-designer` template navs) and the two overview dashboards, built from the metrics list (`metrics` option, default DEFAULT_METRICS). Mount after user, tenant, audit, jobs, metrics and metrics-system; pass `workspaceIds` to match app URL conventions (e.g. Studio `d`/`s`, PublicStatus `admin`/`sysadmin`). Client: `adminShellClient()`, `tenantClient()`, `auditClient()`, `jobsClient()`, optional `tierEngineClient()`.",
+      "description": "Registers tenant-admin and platform-admin workspaces with provider nav into owner-feature screens (`tenant:screen:members`, `audit:screen:audit-log`, `audit:screen:audit-log-all-tenants`, `tenant:screen:tenant-list`, `jobs:screen:job-runs`, optional `tier-engine:screen:tier-admin`, optional `cap-overview:screen:my-caps`/`cap-overview:screen:tenant-cap-list`, optional `document-designer` template navs) and the two overview dashboards (the tenant one can be dropped with `includeTenantOverview: false`), built from the metrics list (`metrics` option, default DEFAULT_METRICS). Mount after user, tenant, audit, jobs, metrics and metrics-system; pass `workspaceIds` to match app URL conventions (e.g. Studio `d`/`s`, PublicStatus `admin`/`sysadmin`). Client: `adminShellClient()`, `tenantClient()`, `auditClient()`, `jobsClient()`, optional `tierEngineClient()`.",
       "toggleableDefault": null,
       "requires": [
         "user",
@@ -452,6 +452,10 @@
       "exposesApis": [],
       "usesApis": [],
       "extensionsUsed": [
+        {
+          "extensionName": "emailAppTransport",
+          "entityName": "app"
+        },
         {
           "extensionName": "deliveryChannel",
           "entityName": "email"
@@ -1390,7 +1394,7 @@
     },
     {
       "name": "inbound-mail-foundation",
-      "description": "Plugin host for inbound e-mail (inbox federation) — provider plugins (inbound-provider-imap, later M365 Graph / Gmail REST) register at the `inboundMailProvider` extension point with verify/fetch and optional oauth/watch (live push). The foundation owns three event-sourced streams (mail-account lifecycle, inbound-message with exactly-once ingest via deterministic aggregate ids, mail-thread rollup) and their projections `read_mail_accounts`/`read_inbound_messages`/`read_mail_threads`; PII fields are envelope-encrypted per tenant subject key before every append (crypto-shredding on tenant destroy). Wire `createInboundMailConnectRoutes` (OAuth connect + anonymous callback outside /api) and `createInboundMailSupervisor` (IDLE watch with backoff + reconciliation poll) in bin/server.ts. Consume `inbound-mail-foundation:event:inbound-message-received` from app features to attach business processes.",
+      "description": "Plugin host for inbound e-mail (inbox federation) — provider plugins (inbound-provider-imap, later M365 Graph / Gmail REST) register at the `inboundMailProvider` extension point with verify/fetch and optional oauth/watch (live push) and send. `sendMailFromAccount(ctx, { accountId, message })` sends from a connected mailbox through its provider (From = the mailbox address, no fallback to the app sender) and answers typed failures (not configured, login rejected, server unreachable, rejected, invalid message); app write handlers call it, it is no endpoint of its own. The foundation owns three event-sourced streams (mail-account lifecycle, inbound-message with exactly-once ingest via deterministic aggregate ids, mail-thread rollup) and their projections `read_mail_accounts`/`read_inbound_messages`/`read_mail_threads`; PII fields are envelope-encrypted per tenant subject key before every append (crypto-shredding on tenant destroy). Wire `createInboundMailConnectRoutes` (OAuth connect + anonymous callback outside /api) and `createInboundMailSupervisor` (IDLE watch with backoff + reconciliation poll) in bin/server.ts. Consume `inbound-mail-foundation:event:inbound-message-received` from app features to attach business processes.",
       "toggleableDefault": null,
       "adoptsBundledLists": true,
       "requires": [
@@ -1430,7 +1434,7 @@
     },
     {
       "name": "inbound-provider-imap",
-      "description": "Registers the `\"imap\"` provider for `inbound-mail-foundation` using imapflow — password/app-password auth covers classic IMAP hosts without any OAuth (plus an XOAUTH2 fallback consuming an access token from the secret slot). Incremental sync via a UIDVALIDITY:lastUid cursor (UIDVALIDITY change triggers a cursor-invalid full resync), initial backfill bounded by the foundation backfill window, and live push via IMAP IDLE for the watch supervisor. Store the per-account connection JSON (host/port/secure/user/password) in the account credential secret slot before the first sync.",
+      "description": "Registers the `\"imap\"` provider for `inbound-mail-foundation` using imapflow — password/app-password auth covers classic IMAP hosts without any OAuth (plus an XOAUTH2 fallback consuming an access token from the secret slot). Incremental sync via a UIDVALIDITY:lastUid cursor (UIDVALIDITY change triggers a cursor-invalid full resync), initial backfill bounded by the foundation backfill window, and live push via IMAP IDLE for the watch supervisor. Tenant admins connect a mailbox through the \"Connect mailbox\" form on the mail accounts list (`connect-mailbox` checks the IMAP login and the SMTP login of the outgoing server first, then creates the account and its credential secret in one transaction); programmatic setups store the per-account connection JSON (host/port/secure/user/password, plus smtpHost/smtpPort for sending) in the account credential secret slot before the first sync. Implements the provider `send`: `sendMailFromAccount` sends over the SMTP server of the mailbox itself (implicit TLS, same login) with the mailbox address as From and stores a copy in its sent folder.",
       "toggleableDefault": null,
       "requires": [
         "inbound-mail-foundation",
@@ -1448,7 +1452,9 @@
       ],
       "configKeys": [],
       "secrets": [],
-      "writeHandlers": [],
+      "writeHandlers": [
+        "inbound-provider-imap:write:connect-mailbox"
+      ],
       "uiHints": {
         "displayLabel": "Inbound Mail · IMAP",
         "category": "notifications",

package/samples/apps/use-all-bundled/kumiko/schema.ts

@@ -1,12 +1,12 @@
 // @runtime dev
-// App-Schema für die `kumiko-schema`-CLI (generate | validate). Komponiert die
-// App-Features einmal und leitet beide CLI-Inputs ab. CLI importiert via
-// dynamic-import.
+// App schema for the `kumiko-schema` CLI (generate | validate). Composes the
+// app features once and derives both CLI inputs. The CLI imports via
+// dynamic import.
 //
-// **Convention:** dieses File exportiert
-//   - `ENTITY_METAS: readonly EntityTableMeta[]`  (Pflicht — generate + validate)
-//   - `FEATURES: readonly FeatureDefinition[]`    (optional — aktiviert
-//     `kumiko-schema validate`s validateBoot-Layer; ohne wird er übersprungen)
+// **Convention:** this file exports
+//   - `ENTITY_METAS: readonly EntityTableMeta[]`  (required — generate + validate)
+//   - `FEATURES: readonly FeatureDefinition[]`    (optional — activates
+//     the validateBoot layer of `kumiko-schema validate`; without it that layer is skipped)
 
 import { collectTableMetas, type EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
 import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";

package/samples/apps/use-all-bundled/scripts/check-coverage.ts

@@ -1,17 +1,17 @@
 #!/usr/bin/env bun
-// biome-ignore-all lint/suspicious/noConsole: CLI-Script, console ist Feature.
+// biome-ignore-all lint/suspicious/noConsole: CLI script, console is the feature.
 //
-// Coverage lint. Diffs die Top-Level-Exports von bundled-features gegen die Features, die
-// use-all-bundled mountet (FEATURES aus kumiko/schema.ts: APP_FEATURES plus die von
-// composeFeatures ergänzten Auth-/Signup-Features). Fängt drei Drifts:
+// Coverage lint. Diffs the top-level exports of bundled-features against the features that
+// use-all-bundled mounts (FEATURES from kumiko/schema.ts: APP_FEATURES plus the auth/signup
+// features added by composeFeatures). Catches three drifts:
 //
-//   1. Ein Export, der weder gemountet ist noch in EXPECTED_HELD_BACK steht
-//   2. Ein EXPECTED_HELD_BACK-Eintrag, der kein Export mehr ist
-//   3. Ein EXPECTED_HELD_BACK-Eintrag, der inzwischen gemountet ist (stale)
+//   1. An export that is neither mounted nor listed in EXPECTED_HELD_BACK
+//   2. An EXPECTED_HELD_BACK entry that is no longer an export
+//   3. An EXPECTED_HELD_BACK entry that has since been mounted (stale)
 //
 // Usage:
 //   bun samples/apps/use-all-bundled/scripts/check-coverage.ts
-// Exit 0 wenn alles in Sync, exit 1 wenn Drift.
+// Exit 0 if everything is in sync, exit 1 on drift.
 
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
@@ -20,11 +20,11 @@ import { FEATURES } from "../kumiko/schema";
 const ROOT = resolve(import.meta.dir, "..");
 const FRAMEWORK_ROOT = resolve(ROOT, "..", "..", "..");
 
-// Held-back exports: existieren in bundled-features, sind aber nicht
-// als runtime-feature in use-all-bundled mountbar.
+// Held-back exports: exist in bundled-features, but cannot be mounted
+// as a runtime feature in use-all-bundled.
 //
-// Nur Utilities ohne defineFeature (foundation-shared ist pure helpers)
-// und scaffold-only Features. Gemountete Features gehören nicht hierher.
+// Only utilities without defineFeature (foundation-shared is pure helpers)
+// and scaffold-only features. Mounted features do not belong here.
 const EXPECTED_HELD_BACK = new Set([
   "foundation-shared", // utilities (requireDefined/requireNonEmpty), kein feature
   "page-render", // shared HTML render/cache helpers (legal/managed-pages), kein defineFeature
@@ -32,16 +32,16 @@ const EXPECTED_HELD_BACK = new Set([
 ]);
 
 // Sub-paths in bundled-features's package.json exports (./tenant/seeding,
-// ./auth-email-password/web, …) sind keine Features, nur utilities.
-// Wir interessieren uns nur für top-level-paths. Nicht-Feature-Exports
-// (Root ".", package.json, Asset-Endungen) sind ausgeschlossen, damit ein
-// künftiger ./styles.css o.ä. nicht fälschlich als unreferenced Feature
-// einen CI-Fail auslöst.
+// ./auth-email-password/web, …) are not features, only utilities.
+// We only care about top-level paths. Non-feature exports
+// (root ".", package.json, asset extensions) are excluded so that a
+// future ./styles.css or similar does not wrongly trigger a CI fail as an
+// unreferenced feature.
 function isFeatureExportPath(path: string): boolean {
   if (!path.startsWith("./")) return false;
   const segment = path.slice(2);
   if (segment.length === 0) return false;
-  // Top-level only: kein weiterer "/" nach dem ersten Segment.
+  // Top-level only: no further "/" after the first segment.
   if (segment.includes("/")) return false;
   // Feature-Export-Pfade sind extension-frei (./audit, ./feature-toggles).
   // Asset-/Manifest-Exports (./package.json, ./styles.css) haben einen "."
@@ -68,8 +68,8 @@ const mounted = new Set<string>(FEATURES.map((feature) => feature.name));
 const unreferenced = [...exports].filter(
   (name) => !mounted.has(name) && !EXPECTED_HELD_BACK.has(name),
 );
-// Ohne diese Prüfungen hätte der Guard in seiner eigenen Konfig einen Blind-Spot: ein
-// umbenanntes oder entferntes Feature bliebe still in der Liste, ein gemountetes ebenso.
+// Without these checks the guard would have a blind spot in its own config: a
+// renamed or removed feature would silently stay in the list, as would a mounted one.
 const staleHeldBack = [...EXPECTED_HELD_BACK].filter((name) => !exports.has(name));
 const mountedHeldBack = [...EXPECTED_HELD_BACK].filter((name) => mounted.has(name));
 

package/samples/apps/use-all-bundled/src/app/auth-constants.ts

@@ -1,7 +1,7 @@
-// Reine Konstanten — kein Framework-Import, damit der E2E-Login-Helper
-// (Playwright-Worker) sie lesen kann, ohne die vitest-Importchain aus
-// `@cosmicdrift/kumiko-testing/helpers` mitzuziehen (kollidiert mit
-// Playwrights expect über Object.prototype-Symbole).
+// Pure constants — no framework import, so the E2E login helper
+// (Playwright worker) can read them without pulling in the vitest import chain from
+// `@cosmicdrift/kumiko-testing/helpers` (collides with
+// Playwright's expect via Object.prototype symbols).
 
 export const ADMIN_EMAIL = "admin@kumiko.dev";
 export const ADMIN_PASSWORD = "kumiko-admin";

package/samples/apps/use-all-bundled/src/app/client.tsx

@@ -6,10 +6,10 @@
 // APP_TRANSLATIONS overrides here.
 //
 // APP_TRANSLATIONS: die entity-backed Admin-Screens (tenant/user/managed-pages)
-// haben kein /web-Plugin, das ihre Spalten-Labels mitbrächte. Sie nutzen die
-// `<feature>:entity:<e>:field:*`-Convention und überlassen die Labels bewusst
-// der App (siehe user/screens.ts). use-all-bundled IST diese App.
-//
+// APP_TRANSLATIONS: the entity-backed admin screens (tenant/user/managed-pages)
+// have no /web plugin that would bring their column labels. They use the
+// `<feature>:entity:<e>:field:*` convention and deliberately leave the labels
+// to the app (see user/screens.ts). use-all-bundled IS that app.
 // adminShellClient + tenant/audit/jobs/config: WorkspaceShell needs the
 // admin-shell overview components and Settings-Hub i18n; mirror admin-console
 // client registration for features that run-config already mounts server-side.

package/samples/apps/use-all-bundled/src/app/dev-app-options.ts

@@ -1,14 +1,14 @@
 // @runtime dev
 //
-// Dev-/Screenshot-Server für das use-all-bundled Sample. runDevApp mischt im
-// auth-Mode die 4 Standard-Features (config/user/tenant/auth) automatisch via
-// composeFeatures(includeBundled) dazu — exakt die 4, die APP_FEATURES bewusst
-// auslässt — und seedet den Admin im onAfterSetup. So rendert EINE App alle
-// bundled-feature-Screens für die Doku-Previews.
+// Dev/screenshot server for the use-all-bundled sample. In auth mode runDevApp
+// mixes in the 4 standard features (config/user/tenant/auth) automatically via
+// composeFeatures(includeBundled) — exactly the 4 that APP_FEATURES deliberately
+// omits — and seeds the admin in onAfterSetup. That way ONE app renders all
+// bundled feature screens for the docs previews.
 //
-// globalRoles SystemAdmin: schaltet die Plattform-Screens frei (tenant-list,
-// user-list, tier-admin, GDPR-Inspector). anonymousAccess + extraContext.text
-// Content: die öffentlichen legal-pages-Routen (/legal/*).
+// globalRoles SystemAdmin: unlocks the platform screens (tenant-list,
+// user-list, tier-admin, GDPR inspector). anonymousAccess + extraContext.text
+// content: the public legal-pages routes (/legal/*).
 
 import { createTemplateResolverApi } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
 import type { RunDevAppOptions } from "@cosmicdrift/kumiko-dev-server";
@@ -21,10 +21,10 @@ import { notesFeature } from "./notes-feature";
 import { appScreensFeature } from "./screens-feature";
 import { seedScreenshotData } from "./seed";
 
-// tier-admin rendert mit dem bare createTierEngineFeature() (aus APP_FEATURES) den
-// ehrlichen Empty-State ("no TierMap configured"). Eine konfigurierte tierMap
-// würde den Resolver auf jedem Write aktivieren (inkl. Login) und braucht
-// per-Tenant Tier-Assignments — disproportional für einen Preview-Screenshot.
+// tier-admin renders the honest empty state ("no TierMap configured") with the
+// bare createTierEngineFeature() (from APP_FEATURES). A configured tierMap
+// would activate the resolver on every write (incl. login) and needs
+// per-tenant tier assignments — disproportionate for a preview screenshot.
 
 export const devAppOptions = {
   // notesFeature is dev-only (app-owned tag host) — see notes-feature.ts for why

package/samples/apps/use-all-bundled/src/app/seed.ts

@@ -1,9 +1,9 @@
 // @runtime dev
-// Seed-Daten für die Feature-Reference-Screenshots: damit die entity-Listen
-// nicht leer rendern und die öffentlichen Legal-Routes Inhalt haben. Läuft
-// nach dem Admin (runDevApp seeds-Hook), idempotent über die seed-Helper.
-// Dev-only (importiert die dev-only notes-feature) — wird nur von server.ts
-// (runDevApp) als Screenshot-Seed genutzt, nie im Prod-Boot.
+// Seed data for the feature reference screenshots: so the entity lists
+// do not render empty and the public legal routes have content. Runs
+// after the admin (runDevApp seeds hook), idempotent via the seed helpers.
+// Dev-only (imports the dev-only notes feature) — used only by server.ts
+// (runDevApp) as the screenshot seed, never in the prod boot.
 
 import { seedPage } from "@cosmicdrift/kumiko-bundled-features/managed-pages/seeding";
 import { NotesHistoryHandlers } from "@cosmicdrift/kumiko-bundled-features/notes-history";
@@ -329,7 +329,7 @@ export const seedScreenshotData: SeedFn = async (stack) => {
   const devTenant = DEV_TENANT_ID as TenantId;
   const betaTenant = BETA_TENANT_ID as TenantId;
 
-  // managed-pages — zwei Seiten im Dev-Tenant für den page-list Screen.
+  // managed-pages — two pages in the dev tenant for the page-list screen.
   await seedPage(stack.db, {
     tenantId: devTenant,
     slug: "about",

package/samples/apps/user-data-rights-demo/src/feature.ts

@@ -1,29 +1,29 @@
 // kumiko-feature-version: 1
 //
-// todos — Demo-Domain-Feature, das ueber EXT_USER_DATA in user-data-
-// rights integriert. Ein App-Author registriert pro Domain-Entity einen
-// (export, delete)-Hook — das war es. Forget-Cron, Export-Bundle und
-// DSGVO-Endpoints kommen vollstaendig aus user-data-rights.
+// todos — demo domain feature that integrates into user-data-
+// rights via EXT_USER_DATA. An app author registers one
+// (export, delete) hook per domain entity — that's it. Forget cron, export bundle and
+// GDPR endpoints come entirely from user-data-rights.
 //
-// Dieses Feature zeigt:
-//   - r.entity({ name: "todo", ...todoEntity })  → Drizzle-Tabelle wird gebaut
-//   - r.writeHandler({ name: "create", … })      → User legt Todo an
-//   - r.queryHandler({ name: "list", … })        → User sieht seine Todos
-//   - r.useExtension(EXT_USER_DATA, "todo")      → Forget + Export integration
+// This feature shows:
+//   - r.entity({ name: "todo", ...todoEntity })  → Drizzle table is built
+//   - r.writeHandler({ name: "create", … })      → user creates a todo
+//   - r.queryHandler({ name: "list", … })        → user sees their todos
+//   - r.useExtension(EXT_USER_DATA, "todo")      → forget + export integration
 //
-// Was passiert wenn der User dann request-export aufruft:
-//   1. user-data-rights.request-export.write triggert einen Job
-//   2. Worker iteriert alle EXT_USER_DATA-Provider (user, fileRef, todo)
-//   3. todoExportHook liest alle Rows mit author_id = userId aus
-//      ALLEN Tenants des Users
-//   4. Bundle wird als ZIP an einen signed-Magic-Link gepackt + per
-//      Email verschickt
+// What happens when the user then calls request-export:
+//   1. user-data-rights.request-export.write triggers a job
+//   2. The worker iterates all EXT_USER_DATA providers (user, fileRef, todo)
+//   3. todoExportHook reads all rows with author_id = userId from
+//      ALL of the user's tenants
+//   4. The bundle is packed as a ZIP behind a signed magic link and sent by
+//      email
 //
-// Was passiert wenn der User request-deletion aufruft:
-//   1. user-data-rights setzt status=DeletionRequested + grace
-//   2. Nach Ablauf laeuft der run-forget-cleanup-Cron
-//   3. todoDeleteHook DELETEt alle Rows mit author_id = userId
-//   4. user wird anonymisiert (display_name="(deleted)", email=null)
+// What happens when the user calls request-deletion:
+//   1. user-data-rights sets status=DeletionRequested + grace
+//   2. After it expires the run-forget-cleanup cron runs
+//   3. todoDeleteHook DELETEs all rows with author_id = userId
+//   4. The user is anonymized (display_name="(deleted)", email=null)
 
 import { UserDataRightsScreens } from "@cosmicdrift/kumiko-bundled-features/user-data-rights";
 import {
@@ -51,8 +51,8 @@ export const todoEntity = createEntity({
   table: "store_todos",
   idType: "uuid",
   fields: {
-    // nullable: bei DSGVO-anonymize wird authorId auf null gesetzt
-    // (Row bleibt, Personenbezug raus). Pattern matched fileRef.
+    // nullable: on GDPR anonymize authorId is set to null
+    // (row stays, personal reference removed). Pattern matches fileRef.
     authorId: createTextField({ personal: "ref" }),
     title: createTextField({
       personal: false,

package/samples/apps/workspaces/playwright.config.ts

@@ -1,9 +1,9 @@
 // @runtime test
-// Playwright-Config für den workspaces-Sample. Startet den echten dev-
-// server als webServer-Fixture (Port aus samples/e2e/e2e-ports.ts).
-// Pattern ist 1:1 wie der ui-
-// walkthrough-Sample — wenn das Pattern nochmal gebraucht wird, lohnt
-// sich eine Extraktion.
+// Playwright config for the workspaces sample. Starts the real dev
+// server as a webServer fixture (port from samples/e2e/e2e-ports.ts).
+// The pattern is 1:1 as in the ui-
+// walkthrough sample — if the pattern is needed again, an extraction
+// is worthwhile.
 
 import { defineAppE2eConfig, PLAYWRIGHT_DEMO_ENV } from "@cosmicdrift/kumiko-testing/e2e";
 import { E2E_PORTS } from "../../e2e/e2e-ports";

package/samples/apps/workspaces/src/app/auth-constants.ts

@@ -1,6 +1,6 @@
-// Reine Konstanten — kein Framework-Import. seed.ts braucht sie auf
-// dem Server, client.tsx kann sie ggf. zur Anzeige verwenden, später
-// ggf. auch ein E2E-Helper (siehe ui-walkthrough/auth-constants.ts).
+// Pure constants — no framework import. seed.ts needs them on
+// the server, client.tsx may use them for display, later possibly
+// also an E2E helper (see ui-walkthrough/auth-constants.ts).
 
 export const ADMIN_EMAIL = "admin@kumiko.dev";
 export const ADMIN_PASSWORD = "kumiko-admin";

package/samples/apps/workspaces/src/app/server.ts

@@ -1,15 +1,15 @@
 // @runtime dev
 //
-// Dev-server für den workspaces Sample. Auth-Mode aktiv: der Client
-// muss sich über den Login-Screen anmelden. WorkspaceShell filtert dann
-// nach `user.roles` aus der Session — Admin sieht alle drei, andere
-// Rollen nur ihre.
+// Dev server for the workspaces sample. Auth mode active: the client
+// must log in via the login screen. WorkspaceShell then filters
+// by `user.roles` from the session — admin sees all three, other
+// roles only theirs.
 //
-// runDevApp mischt die Standard-Features (config/user/tenant/auth)
-// automatisch dazu wenn `auth` gesetzt ist und ruft seedAdmin im
-// onAfterSetup. Der Client lädt das Schema selbst über die
-// authentifizierte GET /api/schema, kein hand-geschriebener
-// clientSchema-Spiegel.
+// runDevApp mixes in the standard features (config/user/tenant/auth)
+// automatically when `auth` is set and calls seedAdmin in
+// onAfterSetup. The client loads the schema itself via the
+// authenticated GET /api/schema, no hand-written
+// clientSchema mirror.
 
 import { runDevApp } from "@cosmicdrift/kumiko-dev-server";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
@@ -17,17 +17,17 @@ import { demoFeature } from "../features/demo";
 import { driverFeature } from "../features/demo-driver";
 import { ADMIN_EMAIL, ADMIN_PASSWORD } from "./auth-constants";
 
-// Ein Dev-Tenant reicht — die Workspaces filtern nach `roles` (nicht
-// nach Tenant). Wer Tenant-Switching demoen will, schaut in den
-// ui-walkthrough-Sample.
+// One dev tenant is enough — the workspaces filter by `roles` (not
+// by tenant). To demo tenant switching, look at the
+// ui-walkthrough sample.
 const DEV_TENANT_ID = "00000000-0000-4000-8000-000000000010" as TenantId;
 
 import { localeDe } from "@cosmicdrift/kumiko-locale-de";
 
 await runDevApp({
   features: [localeDe(), demoFeature, driverFeature],
-  // PORT env-var override für Playwright-e2e-Runs (config zeigt auf 4175);
-  // sonst lokal-Default 4174.
+  // PORT env var override for Playwright e2e runs (config points to 4175);
+  // otherwise local default 4174.
   port: Number.parseInt(process.env["PORT"] ?? "4174", 10),
   clientEntry: "./src/app/client.tsx",
   htmlPath: "./public/index.html",
@@ -37,8 +37,8 @@ await runDevApp({
       email: ADMIN_EMAIL,
       password: ADMIN_PASSWORD,
       displayName: "Admin",
-      // Admin-Rolle gibt Zugriff auf alle drei Workspaces (admin/dispatch/
-      // driver). Realwelt-Apps würden weitere Rollen + User definieren.
+      // The admin role grants access to all three workspaces (admin/dispatch/
+      // driver). Real-world apps would define further roles + users.
       memberships: [
         { tenantId: DEV_TENANT_ID, tenantKey: "dev", tenantName: "Dev Tenant", roles: ["Admin"] },
       ],

package/samples/apps/workspaces/src/app/shell.tsx

@@ -1,5 +1,5 @@
-// AppShell mit WorkspaceShell statt DefaultAppShell — Multi-Persona-
-// App mit URL-driven Workspace-Switch und Nav-Tree-Filter pro Rolle.
+// AppShell with WorkspaceShell instead of DefaultAppShell — multi-persona
+// app with URL-driven workspace switch and nav tree filter per role.
 
 import {
   DefaultTopbarActions,

package/samples/apps/workspaces/src/features/demo/schema/order.ts

@@ -1,7 +1,7 @@
-// Entity + Screen-Definitionen. WIRD vom Server in feature.ts via
-// r.entity/r.screen registriert; die Browser-seitige Spiegelung
-// (clientSchema mit navs/workspaces) ist obsolet — der Client lädt das
-// aufgelöste AppSchema selbst über die authentifizierte GET /api/schema.
+// Entity + screen definitions. IS registered by the server in feature.ts via
+// r.entity/r.screen; the browser-side mirror
+// (clientSchema with navs/workspaces) is obsolete — the client loads the
+// resolved AppSchema itself via the authenticated GET /api/schema.
 
 import type {
   EntityDefinition,

package/samples/apps/workspaces/src/features/demo-driver/feature.ts

@@ -1,8 +1,8 @@
-// Cross-Feature-Demo: demo-driver registriert eine Nav die sich
-// selber zur driver-Workspace von `demo` zuweist. Beweist dass
-// r.nav.workspaces QNs über Feature-Grenzen hinweg auflöst — nützlich
-// für Teams die pro Persona ein eigenes Package haben und die an einen
-// gemeinsamen Core anflanschen.
+// Cross-feature demo: demo-driver registers a nav that assigns
+// itself to the driver workspace of `demo`. Proves that
+// r.nav.workspaces resolves QNs across feature boundaries — useful
+// for teams that have their own package per persona and dock onto a
+// shared core.
 
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import type { TranslationValue } from "@cosmicdrift/kumiko-framework/ui-types";