@cosmicdrift/kumiko-framework 0.391.0 → 0.392.0

package/agents/examples/apex-landing.md

@@ -53,7 +53,7 @@ bun run screenshot  # → screenshots/landing.png + lightbox.png
 import { expect, boundaryGuardedTest as test } from "@cosmicdrift/kumiko-testing/e2e";
 import { renderLanding, SAMPLE_PLANS } from "../src/feature";
 
-test("header keeps the page's horizontal padding below 1120px (#2038)", async ({ page }) => {
+test("header keeps the page's horizontal padding below 1120px", async ({ page }) => {
   await page.setViewportSize({ width: 390, height: 844 });
   await page.setContent(renderLanding({ plans: SAMPLE_PLANS }), {
     waitUntil: "domcontentloaded",

package/agents/examples/apex-surface-auth.md

@@ -127,9 +127,9 @@ Proves end-to-end over real `/api/write` without auth:
 ### src/__tests__/feature.integration.test.ts
 
 ```ts
-// Beweist: composeApexAccountApp() bootet (volle Account-Komposition inkl.
-// auth + user-data-rights) UND der anonyme email-verifizierte Deletion-Flow
-// läuft end-to-end durch /api/write OHNE Auth (anonymousAccess).
+// Proves: composeApexAccountApp() boots (full account composition incl.
+// auth + user-data-rights) AND the anonymous email-verified deletion flow
+// runs end to end through /api/write WITHOUT auth (anonymousAccess).
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import {
@@ -224,7 +224,7 @@ describe("apex-surface-auth recipe", () => {
     expect(rows[0]?.status).toBe(USER_STATUS.DeletionRequested);
   });
 
-  test("enumeration-safe: unbekannte Email → success, keine Mail", async () => {
+  test("enumeration-safe: unknown email → success, no email", async () => {
     const res = await stack.http.raw("POST", "/api/write", {
       type: REQUEST_BY_EMAIL,
       payload: { email: "nobody@example.com" },
@@ -238,21 +238,21 @@ describe("apex-surface-auth recipe", () => {
 ### src/feature.ts
 
 ```ts
-// apex-surface-auth Recipe — der evidente Weg für öffentlichen Apex-Content.
+// apex-surface-auth recipe — the evident way for public apex content.
 //
-// Eine Kumiko-App hat eine öffentliche Apex-Präsenz (Landing/Login) UND eine
-// schema-getriebene Admin-UI. Die Admin-UI mountet via createKumikoApp (volles
-// Schema). Die Apex mountet via createPublicSurface — schema-LOS, anonym
-// erreichbar, kein Admin-Nav/Topologie-Leak. Beide teilen Locale + Primitives.
+// A Kumiko app has a public apex presence (landing/login) AND a
+// schema-driven admin UI. The admin UI mounts via createKumikoApp (full
+// schema). The apex mounts via createPublicSurface — schema-LESS, anonymously
+// reachable, no admin nav/topology leak. Both share locale + primitives.
 //
-// Dieses Recipe zeigt:
-//   1. Server: die Feature-Komposition für die 4 Account-Flows + den anonymen,
-//      email-verifizierten Deletion-Flow (Lockout-sicher).
-//   2. Client (Kommentar unten + README): wie createPublicSurface + AuthShell
-//      die Screens in der Apex-Chrome mounten.
+// This recipe shows:
+//   1. Server: the feature composition for the 4 account flows + the anonymous,
+//      email-verified deletion flow (lockout-safe).
+//   2. Client (comment below + README): how createPublicSurface + AuthShell
+//      mount the screens in the apex chrome.
 //
-// CLIENT-WIRING (apex.tsx der App — renderer/web, hier nur als Referenz, da
-// Recipes keine Browser-Deps ziehen):
+// CLIENT-WIRING (the app's apex.tsx — renderer/web, only a reference here, since
+// recipes pull in no browser deps):
 //
 //   import {
 //     ForgotPasswordScreen, SignupScreen, createLoginRoute,
@@ -264,8 +264,8 @@ describe("apex-surface-auth recipe", () => {
 //   } from "@cosmicdrift/kumiko-bundled-features/user-data-rights/web";
 //   import { createPublicSurface } from "@cosmicdrift/kumiko-renderer/web";
 //
-//   // AuthShell: die Auth-Card rendert in der Marketing-Chrome statt
-//   // Fullscreen. Default (ohne Provider) bleibt der Fullscreen-Wrapper.
+//   // AuthShell: the auth card renders inside the marketing chrome instead of
+//   // fullscreen. Default (without a provider) stays the fullscreen wrapper.
 //   const shell = ({ children }) => (
 //     <MarketingChrome>
 //       <AuthShellProvider shell={(card) => <div className="py-12 flex justify-center">{card}</div>}>
@@ -274,12 +274,12 @@ describe("apex-surface-auth recipe", () => {
 //     </MarketingChrome>
 //   );
 //
-//   // createLoginRoute — NICHT LoginScreen direkt rendern: die Route
-//   // braucht die Challenge-Swap-Logik für einen zweiten Faktor. Ohne die
-//   // (z.B. raw <LoginScreen />) bleibt ein MFA-enrolter User beim Login
-//   // hängen, sobald die App irgendwann auth-mfa mountet. Mountet die App
-//   // auth-mfa, `mfaVerifyScreen: MfaVerifyScreen` (aus
-//   // "@cosmicdrift/kumiko-bundled-features/auth-mfa/web") ergänzen.
+//   // createLoginRoute — do NOT render LoginScreen directly: the route
+//   // needs the challenge-swap logic for a second factor. Without it
+//   // (e.g. a raw <LoginScreen />) an MFA-enrolled user gets stuck at login
+//   // as soon as the app mounts auth-mfa at some point. If the app mounts
+//   // auth-mfa, add `mfaVerifyScreen: MfaVerifyScreen` (from
+//   // "@cosmicdrift/kumiko-bundled-features/auth-mfa/web").
 //   const LoginRoute = createLoginRoute({ loginScreenProps: { signupHref: "/signup" } });
 //
 //   createPublicSurface({
@@ -296,8 +296,8 @@ describe("apex-surface-auth recipe", () => {
 //   });
 //
 //
-// SERVER-WIRING: die App aktiviert `anonymousAccess` (defaultTenantId = der
-// Apex-Host-Tenant), damit /api/write die anonymen Deletion-Handler erreicht:
+// SERVER-WIRING: the app enables `anonymousAccess` (defaultTenantId = the
+// apex host tenant) so /api/write reaches the anonymous deletion handlers:
 //
 //   runProdApp({ features: composeApexAccountApp({...}), envSchema,
 //                anonymousAccess: { defaultTenantId: APEX_TENANT_ID } })
@@ -318,20 +318,20 @@ import {
 import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 
 export type ApexAccountAppOptions = {
-  /** HMAC-Secret für das Deletion-Verify-Token. */
+  /** HMAC secret for the deletion verify token. */
   readonly deletionTokenSecret: string;
-  /** Apex-Route des Confirm-Screens; der Handler hängt das Token als
-   *  URL-Fragment an (`#token=`). */
+  /** Apex route of the confirm screen; the handler appends the token as a
+   *  URL fragment (`#token=`). */
   readonly deletionVerifyUrl: string;
-  /** Versand des Verify-Magic-Links. MUSS non-blocking sein (enqueue) — ein
-   *  synchroner Send würde ein Timing-Oracle für Account-Enumeration öffnen. */
+  /** Sending the verify magic link. MUST be non-blocking (enqueue) — a
+   *  synchronous send would open a timing oracle for account enumeration. */
   readonly sendDeletionVerificationEmail: SendDeletionVerificationEmailFn;
 };
 
-// Volle Feature-Komposition für die öffentlichen Account-Flows. Die
-// user-data-rights-Options aktivieren den anonymen Deletion-Flow; die übrigen
-// Features liefern Login/Register/PW (auth-email-password) + die
-// Require-Kette (user-data-rights → data-retention + compliance-profiles +
+// Full feature composition for the public account flows. The
+// user-data-rights options enable the anonymous deletion flow; the remaining
+// features provide login/register/PW (auth-email-password) + the
+// require chain (user-data-rights → data-retention + compliance-profiles +
 // sessions).
 export function composeApexAccountApp(opts: ApexAccountAppOptions): FeatureDefinition[] {
   return [

package/agents/examples/compliance-profiles-demo.md

@@ -168,7 +168,7 @@ describe("compliance-profiles-demo :: cross-tenant isolation", () => {
     expect(result.profile.tenantDestroyGracePeriod).toEqual({ days: 30 });
   });
 
-  test("Tenant B (Schweiz) → swiss-dsg: EDÖB + DE/FR/IT/EN-Sprachen", async () => {
+  test("Tenant B (Switzerland) → swiss-dsg: Swiss data protection authority + DE/FR/IT/EN languages", async () => {
     const result = await stack.http.queryOk<{
       profile: {
         key: string;
@@ -206,7 +206,7 @@ describe("compliance-profiles-demo :: cross-tenant isolation", () => {
     expect(result.profile.subProcessor.worksCouncilApprovalRequired).toBe(true);
   });
 
-  test("Profile-Wechsel auf demselben Tenant zeigt sofort neues Verhalten", async () => {
+  test("Profile switch on the same tenant immediately shows new behavior", async () => {
     // Eigener Tenant D damit der Test reihenfolge-unabhaengig laeuft
     // (Tenant A bleibt auf eu-dsgvo fuer die anderen Tests).
     const tenantDAdmin = createTestUser({
@@ -233,7 +233,7 @@ describe("compliance-profiles-demo :: cross-tenant isolation", () => {
     expect(back.profile.breach.authorityContact).toBe("BlnBDI Berlin");
   });
 
-  test("Tenant-Override merged auf base-profile, andere Felder bleiben", async () => {
+  test("Tenant override merges into base profile; other fields remain", async () => {
     // Eigener Tenant E damit der Override-State Tenant B nicht
     // ueberschreibt (reihenfolge-unabhaengig).
     const tenantEAdmin = createTestUser({
@@ -267,7 +267,7 @@ describe("compliance-profiles-demo :: cross-tenant isolation", () => {
     // Andere userRights aus swiss-dsg bleiben
     expect(result.profile.userRights.portabilityFormat).toEqual(["json"]);
     expect(result.profile.userRights.restrictionAllowed).toBe(true);
-    // Sprachen aus swiss-dsg unverändert
+    // Languages from swiss-dsg unchanged
     expect(result.profile.notifications.languages).toEqual(["de", "fr", "it", "en"]);
   });
 });

package/agents/examples/crypto-shredding-hr.md

@@ -246,7 +246,7 @@ describe("crypto-shredding-hr", () => {
   });
 });
 
-describe("crypto-shredding-hr — blind-index lookups (#818)", () => {
+describe("crypto-shredding-hr — blind-index lookups", () => {
   const employeeTable = buildEntityTable("employee", employeeEntity);
 
   test("equality lookup by email works on the encrypted column — until the key is erased", async () => {

package/agents/examples/designer-demo.md

@@ -29,12 +29,12 @@ No dedicated automated tests in this folder yet — use it as a composition samp
 
 ```ts
 // kumiko-feature-version: 1
-// Demo-Feature für den Designer-Skeleton (C5).
-// Enthält bewusst Patterns aus den 3 hand-rollten View-Kategorien:
-//   - entity      → Tabelle der Fields
-//   - writeHandler → Header + Code-Blocks (schema + handler)
-//   - nav         → ID/Label/Screen-Card
-// Plus optionalRequires + metric als JSON-Dump-Fallback.
+// Demo feature for the designer skeleton (C5).
+// Deliberately contains patterns from the 3 hand-rolled view categories:
+//   - entity      → table of fields
+//   - writeHandler → header + code blocks (schema + handler)
+//   - nav         → ID/label/screen card
+// Plus optionalRequires + metric as a JSON dump fallback.
 
 import { createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";

package/agents/examples/e2e-generator.md

@@ -31,12 +31,12 @@ bun test
 ### src/__tests__/feature.test.ts
 
 ```ts
-// E2E-Generator Sample — Unit-Test.
+// E2E generator sample — unit test.
 //
-// Zweck: zeigt einen realistischen Generator-Run (shop-Feature mit allen
-// unterstützten + ein paar bewusst unsupported Feldtypen). Der Snapshot
-// dokumentiert das Ergebnis; jeder Feature-Autor der den Generator zum
-// ersten Mal anfasst kann hier reinschauen statt in die Implementation.
+// Purpose: shows a realistic generator run (shop feature with all
+// supported + a few deliberately unsupported field types). The snapshot
+// documents the result; any feature author touching the generator for the
+// first time can look here instead of at the implementation.
 
 import { describe, expect, test } from "bun:test";
 import {
@@ -54,11 +54,11 @@ const shop = createShopFeature();
 const registry = createRegistry([shop]);
 
 describe("e2e-generator sample — shop feature", () => {
-  test("validateBoot akzeptiert das Feature", () => {
+  test("validateBoot accepts the feature", () => {
     expect(() => validateBoot([shop])).not.toThrow();
   });
 
-  test("generateE2ESpec liefert alle vier Kinds für das List+Edit-Paar", () => {
+  test("generateE2ESpec returns all four kinds for the List+Edit pair", () => {
     const specs = generateE2ESpec(registry);
     const kinds = specs.map((s) => s.kind).sort();
     expect(kinds).toEqual([
@@ -69,7 +69,7 @@ describe("e2e-generator sample — shop feature", () => {
     ]);
   });
 
-  test("list-has-fixture-row referenziert den Create-Handler + nutzt name als Identifying", () => {
+  test("list-has-fixture-row references the Create handler + uses name as the identifying field", () => {
     const specs = generateE2ESpec(registry);
     const row = specs.find((s) => s.kind === "list-has-fixture-row");
     if (row?.kind !== "list-has-fixture-row") throw new Error("unreachable");
@@ -84,14 +84,14 @@ describe("e2e-generator sample — shop feature", () => {
     expect(row.fixture["listPrice"]).toEqual({ amount: 1, currency: "EUR" });
   });
 
-  test("edit-validates-required listet nur echte required-Felder (name, price)", () => {
+  test("edit-validates-required lists only actual required fields (name, price)", () => {
     const specs = generateE2ESpec(registry);
     const validates = specs.find((s) => s.kind === "edit-validates-required");
     if (validates?.kind !== "edit-validates-required") throw new Error("unreachable");
     expect(validates.requiredFields).toEqual(["name", "price"]);
   });
 
-  test("edit-save-persists mapped Feldtypen auf die richtigen Playwright-Interaktionen", () => {
+  test("edit-save-persists maps field types to the correct Playwright interactions", () => {
     const specs = generateE2ESpec(registry);
     const save = specs.find((s) => s.kind === "edit-save-persists");
     if (save?.kind !== "edit-save-persists") throw new Error("unreachable");
@@ -104,17 +104,17 @@ describe("e2e-generator sample — shop feature", () => {
     // sonst zerschellt Playwright am ersten Dropdown.
     expect(opsByField.get("status")).toBe("select");
     expect(opsByField.get("featured")).toBe("check");
-    // money (listPrice) wird im Form bewusst übersprungen — komplexes
-    // Widget (Betrag + Währung), das der Generator nicht generisch
-    // automatisieren kann. API-Seed nutzt es trotzdem (siehe Test oben).
+    // money (listPrice) is deliberately skipped in the form — a complex
+    // widget (amount + currency) that the generator cannot automate
+    // generically. The API seed uses it anyway (see test above).
     expect(opsByField.has("listPrice")).toBe(false);
   });
 
-  test("Output ist JSON-serialisierbar (Prozess-Grenze zu Playwright-Worker)", () => {
-    // Das Sample-Feature muss sich rundtrippen lassen: TestSpec → JSON.stringify →
-    // JSON.parse. Im produktiven Setup schreibt ein bun-Subprozess (globalSetup)
-    // die JSON auf Platte, der Playwright-Worker liest sie — kein runtime-Import
-    // vom Framework im Test-Prozess (würde mit Playwrights expect kollidieren).
+  test("Output is JSON-serializable (process boundary to Playwright worker)", () => {
+    // The sample feature must round-trip: TestSpec → JSON.stringify →
+    // JSON.parse. In the production setup a bun subprocess (globalSetup) writes
+    // the JSON to disk, the Playwright worker reads it — no runtime import
+    // of the framework in the test process (would collide with Playwright's expect).
     const specs = generateE2ESpec(registry);
     const roundtripped = JSON.parse(JSON.stringify(specs));
     expect(roundtripped).toEqual(specs);

package/agents/examples/encrypted-tenant-config.md

@@ -143,9 +143,9 @@ decrypt fallback until the job has run once, then delete it.
 ### src/__tests__/feature.integration.test.ts
 
 ```ts
-// End-to-End: Tenant-Admin setzt Stripe-API-Key → DB hat ciphertext →
-// charge-handler liest entschlüsselt → caller sieht charge-id, NIE den
-// Key. Plus: zwei Tenants haben getrennte Keys.
+// End to end: tenant admin sets the Stripe API key → DB has ciphertext →
+// the charge handler reads it decrypted → caller sees the charge id, NEVER the
+// key. Plus: two tenants have separate keys.
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
@@ -200,7 +200,7 @@ beforeEach(() => {
 });
 
 describe("encrypted tenant-config: per-tenant Stripe-API-key", () => {
-  test("DB hält ciphertext, NICHT plaintext", async () => {
+  test("DB stores ciphertext, NOT plaintext", async () => {
     const plaintextKey = "sk_live_super_secret_stripe_key_12345";
     await stack.http.writeOk(
       "config:write:set",
@@ -220,7 +220,7 @@ describe("encrypted tenant-config: per-tenant Stripe-API-key", () => {
     expect(stored).not.toContain("super_secret");
   });
 
-  test("config:query:values maskt encrypted-key mit ••••••", async () => {
+  test("config:query:values masks encrypted key with ••••••", async () => {
     await stack.http.writeOk(
       "config:write:set",
       { key: stripeApiKeyHandle.name, value: "sk_live_xyz", scope: "tenant" },
@@ -234,8 +234,8 @@ describe("encrypted tenant-config: per-tenant Stripe-API-key", () => {
     expect(cfg[stripeApiKeyHandle.name]?.value).toBe("••••••");
   });
 
-  test("charge-handler liest den entschlüsselten Key + nutzt ihn", async () => {
-    // Charge ohne gesetzten Key → schlägt mit klarer Error fehl
+  test("charge-handler reads the decrypted key + uses it", async () => {
+    // Charge without a set key → fails with a clear error
     const noKey = await stack.http.write(
       "billing:write:charge",
       { amount: 1000, customerRef: "cust_42" },
@@ -257,16 +257,16 @@ describe("encrypted tenant-config: per-tenant Stripe-API-key", () => {
     expect(ok.chargeId).toContain("cust_42");
   });
 
-  test("Tenant-Isolation: Tenant-A's Key leakt NICHT zu Tenant-B", async () => {
+  test("Tenant isolation: Tenant-A's key does not leak to Tenant-B", async () => {
     await stack.http.writeOk(
       "config:write:set",
       { key: stripeApiKeyHandle.name, value: "sk_live_acme_only", scope: "tenant" },
       acmeAdmin,
     );
 
-    // Tenant-B macht charge OHNE eigenen Key → fehlschlägt (sieht
-    // den acme-Key NICHT). Beweis: per-tenant config-row, nicht globale
-    // Variable.
+    // Tenant B does a charge WITHOUT its own key → fails (does NOT see
+    // the acme key). Proof: per-tenant config row, not a global
+    // variable.
     const res = await stack.http.write(
       "billing:write:charge",
       { amount: 500, customerRef: "globex_cust" },
@@ -310,17 +310,17 @@ describe("encrypted tenant-config: mask derives the configEdit screen", () => {
 ### src/feature.ts
 
 ```ts
-// Encrypted per-tenant config — Stripe-API-key pattern.
+// Encrypted per-tenant config — Stripe API key pattern.
 //
-// Minimal-Showcase: ein dummy "billing"-feature mit einem per-tenant
-// Stripe-API-Key. Der `mask`-Eintrag lässt den configEdit-Screen +
-// Settings-Hub-Nav automatisch entstehen (kein handgeschriebenes
-// r.screen/r.nav mehr). charge-handler liest den Key über ctx.config
-// (entschlüsselt automatisch).
+// Minimal showcase: a dummy "billing" feature with a per-tenant
+// Stripe API key. The `mask` entry makes the configEdit screen +
+// settings hub nav appear automatically (no more hand-written
+// r.screen/r.nav). The charge handler reads the key via ctx.config
+// (decrypted automatically).
 //
-// Production: nicht aufrufen — der echte Stripe-Call ist hier ein Mock.
-// Pattern in produktiven Apps: Strip-API-Key in tenantBillingConfig.key,
-// charge-handler lädt key + ruft tatsächlich Stripe.
+// Production: do not call — the real Stripe call is a mock here.
+// Pattern in productive apps: Stripe API key in tenantBillingConfig.key,
+// the charge handler loads the key + actually calls Stripe.
 
 import {
   access,
@@ -352,8 +352,8 @@ const stripeApiKeyHandle: ConfigKeyHandle<"text"> = {
   type: "text",
 };
 
-// Charge-Handler — nutzt den entschlüsselten API-Key. Caller sieht NUR
-// die charge-id zurück, der Key bleibt server-side.
+// Charge handler — uses the decrypted API key. The caller sees ONLY
+// the charge id back, the key stays server-side.
 const chargeHandler = defineWriteHandler({
   name: "charge",
   schema: z.object({
@@ -378,10 +378,10 @@ const chargeHandler = defineWriteHandler({
       );
     }
 
-    // Mock: real impl würde fetch("https://api.stripe.com/v1/charges",
-    // { headers: { Authorization: `Bearer ${apiKey}` }, ... }) ausführen.
-    // Wichtig: apiKey verlässt den server NICHT — kein log, kein
-    // response-field, kein error-detail.
+    // Mock: a real impl would execute fetch("https://api.stripe.com/v1/charges",
+    // { headers: { Authorization: `Bearer ${apiKey}` }, ... }).
+    // Important: apiKey does NOT leave the server — no log, no
+    // response field, no error detail.
     const chargeId = `ch_${Date.now()}_${event.payload.customerRef}`;
 
     return {
@@ -395,10 +395,10 @@ export const billingFeature = defineFeature(FEATURE, (r) => {
   r.requires({ features: ["config"] });
   r.config("stripe-api-key", stripeApiKeyDef);
   r.writeHandler(chargeHandler);
-  // Kein r.screen/r.nav: der `mask`-Eintrag auf dem Key lässt
-  // buildConfigFeatureSchema den configEdit-Screen (••••••-maskiert,
-  // config:write:set verschlüsselt vor dem write) + den Settings-Hub-Nav
-  // automatisch ableiten.
+  // No r.screen/r.nav: the `mask` entry on the key lets
+  // buildConfigFeatureSchema derive the configEdit screen (••••••-masked,
+  // config:write:set encrypts before the write) + the settings hub nav
+  // automatically.
 
   r.translations({
     keys: {
@@ -408,6 +408,6 @@ export const billingFeature = defineFeature(FEATURE, (r) => {
   });
 });
 
-// Re-exports damit tests die handles ohne re-typing nutzen können.
+// Re-exports so tests can use the handles without re-typing.
 export { stripeApiKeyHandle };
 ```

package/agents/examples/files-post-processing.md

@@ -225,7 +225,7 @@ describe("entry point 3 — public route, default-deny", () => {
     expect(res.headers.get("Content-Type")).toBe("image/webp");
   });
 
-  test("publishing tenant A's photo does not publish tenant B's photo (#1983/1)", async () => {
+  test("publishing tenant A's photo does not publish tenant B's photo", async () => {
     const photoIdA = await createPhoto(user);
     const photoIdB = await createPhoto(userB);
     const fileIdA = await uploadPhoto(

package/agents/examples/inbound-mail-triage.md

@@ -232,7 +232,7 @@ describe("inbound-mail triage sample", () => {
         data: { duplicate: boolean };
       };
       expect(replayBody.data.duplicate).toBe(true);
-      // Trigger-Nachlauf abwarten, dann Idempotenz prüfen.
+      // Wait for the trigger follow-up, then check idempotency.
       await new Promise((resolve) => setTimeout(resolve, 500));
       expect(triageInbox.size).toBe(1);
     } finally {

package/agents/examples/lane-routing.md

@@ -164,11 +164,11 @@ import { z } from "zod";
 export const renderedReceipts: Array<{ customerName: string; amount: number }> = [];
 export const sentConfirmations: Array<{ customerName: string; amount: number }> = [];
 
-// Entity-Dekl sichert den qualified-name-Prefix "orders:write:order:create"
-// für den Write-Handler unten und damit den Job-Trigger auf diesem Event.
-// Persistenz passiert im Custom-Handler nicht (id ist hardcoded für den
-// Sample-Test) — in einer echten App würde ein entityWriteHandler in die DB
-// schreiben.
+// The entity declaration secures the qualified-name prefix "orders:write:order:create"
+// for the write handler below and thereby the job trigger on this event.
+// Persistence does not happen in the custom handler (id is hardcoded for the
+// sample test) — in a real app an entityWriteHandler would write to the
+// DB.
 const orderEntity = createEntity({
   table: "read_orders",
   fields: {

package/agents/examples/legal-pages.md

@@ -267,7 +267,7 @@ beforeAll(async () => {
   await unsafeCreateEntityTable(db, templateResourceEntity);
   await createEventsTable(db);
 
-  // Seed Pflicht-Blocks für SYSTEM_TENANT (DE Impressum + DSE)
+  // Seed required blocks for SYSTEM_TENANT (DE imprint + privacy policy)
   await seedTextBlock(db, {
     tenantId: SYSTEM_TENANT_ID,
     slug: "imprint",
@@ -313,9 +313,9 @@ afterAll(async () => {
 });
 
 describe("legal-pages sample", () => {
-  test("alle LEGAL_ROUTES sind über stack.app erreichbar", async () => {
-    // Smoke-Test: jede Route gibt entweder 200 (gerendert) oder 404
-    // (Block fehlt). Nie 5xx — die Server-Pipeline läuft sauber durch.
+  test("all LEGAL_ROUTES are reachable via stack.app", async () => {
+    // Smoke test: every route returns either 200 (rendered) or 404
+    // (block missing). Never 5xx — the server pipeline runs through cleanly.
     for (const route of LEGAL_ROUTES) {
       const res = await stack.app.request(route.path);
       expect([200, 404]).toContain(res.status);
@@ -337,21 +337,21 @@ describe("legal-pages sample", () => {
     expect(privacyBody).toContain("Datenschutzerklärung");
   });
 
-  test("EN-Variante 404 (nicht geseedet) zeigt hilfreiche Meldung", async () => {
+  test("The EN variant 404 (not seeded) shows a helpful message", async () => {
     const res = await stack.app.request("/legal/imprint");
     expect(res.status).toBe(404);
     const body = await res.text();
     expect(body).toContain("Tenant-Admin");
   });
 
-  test("Markdown-Headings werden zu HTML-h2-Tags", async () => {
+  test("Markdown headings are converted to HTML h2 tags", async () => {
     const res = await stack.app.request("/legal/impressum");
     const body = await res.text();
     expect(body).toContain("<h2>Angaben gemäß § 5 TMG</h2>");
     expect(body).toContain("<strong>Alex Morgan</strong>");
   });
 
-  test("Cache-Header zeigt 60s public-cache", async () => {
+  test("Cache header indicates 60s public caching", async () => {
     const res = await stack.app.request("/legal/impressum");
     expect(res.headers.get("cache-control")).toBe("public, max-age=60, must-revalidate");
   });
@@ -378,40 +378,40 @@ describe("legal-pages sample", () => {
 ### src/feature.ts
 
 ```ts
-// Legal-Pages Sample
+// Legal-pages sample
 //
-// DACH-Apps (DE/AT/CH) sind verpflichtet ein Impressum (TMG/DDG §5) und
-// eine Datenschutzerklärung (DSGVO Art. 13) öffentlich zugänglich zu
-// haben. Das ist 1) für jede App identisch und 2) nervig manuell pro
-// App neu zu basteln.
+// DACH apps (DE/AT/CH) are required to make an imprint (TMG/DDG §5) and
+// a privacy policy (GDPR Art. 13) publicly accessible.
+// That is 1) identical for every app and 2) annoying to build
+// by hand per app.
 //
-// Lösung: zwei opt-in bundled-features kombinieren:
+// Solution: combine two opt-in bundled features:
 //
-//  - `template-resolver` — der Content-Store (Entity `template-resource`,
-//    kind `text-block` mit slug+locale+title+content, scoped per Tenant).
-//    Auch nutzbar für FAQ, About, ToS, Marketing-Snippets — nicht
-//    legal-spezifisch.
+//  - `template-resolver` — the content store (entity `template-resource`,
+//    kind `text-block` with slug+locale+title+content, scoped per tenant).
+//    Also usable for FAQ, About, ToS, marketing snippets — not
+//    legal-specific.
 //
-//  - `legal-pages`   — opt-in-Wrapper darauf, der vier feste Public-
-//    Routes (`/legal/impressum`, `/legal/datenschutz`, `/legal/imprint`,
-//    `/legal/privacy`) registriert und Markdown→HTML rendered. Plus
-//    Boot-Check der in Production hart fehlt wenn die DE-Pflicht-Blocks
-//    fehlen.
+//  - `legal-pages`   — opt-in wrapper on top of it that registers four fixed public
+//    routes (`/legal/impressum`, `/legal/datenschutz`, `/legal/imprint`,
+//    `/legal/privacy`) and renders Markdown→HTML. Plus a
+//    boot check that fails hard in production when the DE required blocks
+//    are missing.
 //
-// Tenant-Modell: 1 App = X Tenants = 1 Impressum. Alle Subdomains
-// teilen sich die SYSTEM_TENANT_ID-Version. Wer pro-Tenant-Impressums
-// braucht, muss sein eigenes Routing davorsetzen oder die by-slug-
-// query mit tenant-specific tenantId nutzen.
+// Tenant model: 1 app = X tenants = 1 imprint. All subdomains
+// share the SYSTEM_TENANT_ID version. If you need per-tenant imprints,
+// you have to put your own routing in front or use the by-slug
+// query with a tenant-specific tenantId.
 //
-// Voraussetzungen für Production:
-//  - `anonymousAccess` muss in runProdApp/runDevApp konfiguriert sein
-//    (defaultTenantId = SYSTEM_TENANT_ID), sonst antworten die
-//    legal-pages-Routes mit 503
-//  - `extraContext.templateResolver = createTemplateResolverApi(db, registry)` muss
-//    gewired sein, sonst wirft der Boot-Check mit Wiring-Hinweis
-//  - Beim ersten Boot müssen die TextBlocks geseedet sein —
-//    template-resolver/seeding `seedTextBlock` oder via API
-//    `template-resolver:write:set` mit TenantAdmin-Token
+// Prerequisites for production:
+//  - `anonymousAccess` must be configured in runProdApp/runDevApp
+//    (defaultTenantId = SYSTEM_TENANT_ID), otherwise the
+//    legal-pages routes answer with 503
+//  - `extraContext.templateResolver = createTemplateResolverApi(db, registry)` must be
+//    wired, otherwise the boot check throws with a wiring hint
+//  - On first boot the TextBlocks must be seeded —
+//    template-resolver/seeding `seedTextBlock` or via API
+//    `template-resolver:write:set` with a TenantAdmin token
 
 import {
   createLegalPagesFeature,
@@ -437,6 +437,6 @@ export const legalPagesFeature = createLegalPagesFeature({
   }),
 });
 
-// Re-exports für Tests + andere Demos
+// Re-exports for tests + other demos
 export { LEGAL_REQUIRED_BLOCKS, LEGAL_ROUTES, LEGAL_TERMS_ROUTES };
 ```