@cosmicdrift/kumiko-samples 0.386.0 → 0.388.0

package/packages/bundled-features/src/mail-foundation/feature.ts

@@ -2,34 +2,33 @@
 //
 // mail-foundation as a Kumiko bundled feature.
 //
-// **Was diese Feature liefert:**
-//   1. **Plugin-API** für Mail-Transport-Provider via `r.extendsRegistrar
-//      ("mailTransport", ...)`. Provider-Features (mail-transport-smtp,
-//      mail-transport-brevo-api, ...) registrieren sich namentlich.
-//   2. **Tenant-Config-key** `provider`: select-Wert der zur Runtime
-//      bestimmt welcher registrierte Plugin verwendet wird.
-//   3. **createTransportForTenant(ctx, tenantId)** Factory die den
-//      gewählten Plugin im Registry sucht und seine `build`-Methode
-//      aufruft.
+// **What this feature provides:**
+//   1. **Plugin API** for mail transport providers via `r.extendsRegistrar
+//      ("mailTransport", ...)`. Provider features (mail-transport-smtp,
+//      mail-transport-brevo-api, ...) register by name.
+//   2. **Tenant config key** `provider`: a selection value that determines at
+//      runtime which registered plugin is used.
+//   3. **createTransportForTenant(ctx, tenantId)** factory that looks up the
+//      selected plugin in the registry and calls its `build` method.
 //
-// **Was diese Foundation NICHT mehr macht (im Vergleich zur ersten
-// Iteration):**
-//   - Keine SMTP/Brevo/Postmark-spezifischen Config-Keys mehr in
-//     mail-foundation. Provider-spezifische Config (host/port/from/
-//     authUser für SMTP, apiUrl/accountId für Brevo etc.) lebt im
-//     jeweiligen Provider-Plugin-Feature.
-//   - Kein direkter Import von `createSmtpTransport`. Die Foundation
-//     kennt nur das `EmailTransport`-Interface (Type-Import, kein
-//     runtime-coupling), nicht die konkrete Implementation.
+// **What this foundation no longer does (compared with the first
+// iteration):**
+//   - No SMTP/Brevo/Postmark-specific config keys in mail-foundation.
+//     Provider-specific config (host/port/from/authUser for SMTP,
+//     apiUrl/accountId for Brevo, etc.) lives in the respective provider
+//     plugin feature.
+//   - No direct import of `createSmtpTransport`. The foundation knows only
+//     the `EmailTransport` interface (type import, no runtime coupling), not
+//     the concrete implementation.
 //
-// **Pattern-Vorbild:** identisch zu `delivery` + `channel-email`. Die
-// delivery-feature deklariert `r.extendsRegistrar("deliveryChannel")`,
-// channel-email registriert sich via `r.useExtension("deliveryChannel",
-// "email", {...})`. Selbe Trennung Foundation ↔ Provider.
+// **Pattern precedent:** identical to `delivery` + `channel-email`. The
+// delivery feature declares `r.extendsRegistrar("deliveryChannel")`, and
+// channel-email registers via `r.useExtension("deliveryChannel",
+// "email", {...})`. The foundation ↔ provider separation is the same.
 //
-// **Standalone:** Foundation ist ohne tier-engine nutzbar. Existing
-// `channel-email` (App-wide-Mail-Sender via delivery) bleibt unangetastet
-// — additive Feature.
+// **Standalone:** The foundation can be used without tier-engine. Existing
+// `channel-email` (app-wide mail sender via delivery) remains unchanged—an
+// additive feature.
 
 import {
   type EmailTransport,
@@ -76,9 +75,9 @@ export const MAIL_TRANSPORT_EXTENSION = "mailTransport" as const;
  *   config      — tenant config reads (the plugin's host/port/from/...)
  *   registry    — extension lookup in the factory (not plugin-internal)
  *   secrets     — tenant secret reads (smtp.password)
- *   auditUserId — audit identity for secret reads. Handler path: the
- *                 dispatcher sets the caller's user id; worker path: the
- *                 r.job wrap sets a system identity.
+ *   auditUserId — audit identity for secret reads. Handler path: unset,
+ *                 requireSecretsContext falls back to ctx.user.id; worker path:
+ *                 the r.job wrap sets a system identity.
  */
 export type MailTransportContext = {
   readonly config?: ConfigAccessor;
@@ -97,8 +96,8 @@ export type MailTransportContext = {
  * an EmailTransport. Per-call construction so a tenant editing config
  * sees the change on the next mail.
  *
- * **Plugin-Author-Warnung:** `ctx` ist EXPLIZIT ein MailTransportContext,
- * nicht ein voller HandlerContext (siehe MailTransportContext-Doc).
+ * **Plugin-author warning:** `ctx` is EXPLICITLY a MailTransportContext,
+ * not a full HandlerContext (see the MailTransportContext doc).
  */
 export type MailTransportPlugin = {
   readonly build: (ctx: MailTransportContext, tenantId: string) => Promise<EmailTransport>;
@@ -277,6 +276,8 @@ export type TenantMailTransportScope = {
 export function tenantMailTransport(
   scope: TenantMailTransportScope,
 ): Promise<EmailTransport | null> {
+  // Without a tenant config the provider cannot be read: use the app transport.
+  if (scope.config === undefined) return Promise.resolve(null);
   return createTransportForTenantIfConfigured(
     {
       config: scope.config,

package/packages/bundled-features/src/mail-transport-inmemory/feature.ts

@@ -1,25 +1,25 @@
 // kumiko-feature-version: 1
 //
-// mail-transport-inmemory — In-Memory-EmailTransport für die mail-
-// foundation Plugin-API. Sammelt Mails in einem per-Tenant-Buffer
-// statt sie über einen echten SMTP-Server zu senden. Designed für
-// Demos, Sample-Apps und Tests die ohne Mailpit/Mailcrab/echten SMTP
-// laufen sollen.
+// mail-transport-inmemory — In-memory email transport for the mail-
+// foundation plugin API. Collects emails in a per-tenant buffer
+// instead of sending them through a real SMTP server. Designed for
+// demos, sample apps, and tests that should run without Mailpit,
+// Mailcrab, or real SMTP.
 //
-// **Was diese Feature liefert:**
-//   1. Plugin-Registration via `r.useExtension("mailTransport",
-//      "inmemory", { build })`. Tenants setzen
-//      "mail-foundation:config:provider" auf "inmemory" und kriegen
-//      die buffered-Variante.
-//   2. **Pro-Tenant Inbox.** Jeder Tenant hat einen eigenen
-//      Mail-Buffer (Map<tenantId, EmailMessage[]>). Demo-Apps können
-//      die Inbox via `getInbox(tenantId)` lesen + UI rendern.
+// **What this feature provides:**
+//   1. Plugin registration via `r.useExtension("mailTransport",
+//      "inmemory", { build })`. Tenants set
+//      "mail-foundation:config:provider" to "inmemory" and receive
+//      the buffered variant.
+//   2. **Per-tenant inbox.** Each tenant has its own mail buffer
+//      (Map<tenantId, EmailMessage[]>). Demo apps can read the inbox
+//      via `getInbox(tenantId)` and render a UI.
 //
-// **Pattern-Vorbild:** mirrors mail-transport-smtp.
+// **Pattern reference:** mirrors mail-transport-smtp.
 //
-// **NICHT für Production.** Buffer ist im Process-Memory, geht beim
-// Restart verloren. Cap-Counter / Audit-Trail bleiben trotzdem korrekt
-// — die hängen am event-store, nicht am Transport.
+// **NOT for production.** The buffer is in process memory and is lost
+// on restart. Cap counters and the audit trail remain correct because
+// they are tied to the event store, not the transport.
 
 import type {
   EmailMessage,
@@ -39,9 +39,9 @@ const FEATURE_NAME = "mail-transport-inmemory";
 // Per-tenant in-memory buffer
 // =============================================================================
 //
-// Module-level Map weil der Plugin-build-call pro Send einen neuen
-// Transport-Wrapper baut, aber wir wollen dass alle Wrapper für
-// denselben Tenant auf denselben Buffer zeigen. Map<tenantId,
+// The module-level Map is needed because the plugin build call creates
+// a new transport wrapper for each send, while all wrappers for the
+// same tenant must point to the same buffer. Map<tenantId,
 // InMemoryTransport>.
 
 const transportsByTenant = new Map<string, ReturnType<typeof createInMemoryTransport>>();
@@ -56,16 +56,16 @@ function getOrCreateTransportForTenant(tenantId: string) {
 }
 
 /**
- * Demo/Test-Helper: lies die "versendeten" Mails eines Tenants. Im
- * Sample-App rendert ein query-Handler darauf die Inbox-UI.
+ * Demo/test helper: reads the emails "sent" for a tenant. A query
+ * handler in the sample app uses this to render the inbox UI.
  */
 export function getInbox(tenantId: string): readonly EmailMessage[] {
   return transportsByTenant.get(tenantId)?.sent ?? [];
 }
 
 /**
- * Demo/Test-Helper: clear einen Tenant-Buffer (z.B. zwischen Test-
- * Szenarien).
+ * Demo/test helper: clears a tenant's buffer, for example between
+ * test scenarios.
  */
 export function clearInbox(tenantId: string): void {
   const t = transportsByTenant.get(tenantId);
@@ -82,10 +82,9 @@ export function createMailTransportInMemoryFeature() {
       r.describe(
         'Registers an in-process `"inmemory"` provider for `mail-foundation` that buffers sent mails per tenant instead of contacting an SMTP server. Use `getInbox(tenantId)` and `clearInbox(tenantId)` in demo apps and tests; not for production (buffer is process-memory, lost on restart).',
       );
-      // Kein requires auf "config" oder "secrets" — der
-      // In-Memory-Transport hat keine Config (nichts zu konfigurieren) und
-      // kein Secret. Der einzige hard-require ist mail-foundation, das den
-      // extension-point "mailTransport" definiert.
+      // No `config` or `secrets` requirement: the in-memory transport has
+      // no configuration and no secret. The only hard requirement is
+      // mail-foundation, which defines the "mailTransport" extension point.
       r.requires({ features: ["mail-foundation"] });
 
       const plugin: MailTransportPlugin = {

package/packages/bundled-features/src/mail-transport-smtp/feature.ts

@@ -1,29 +1,29 @@
 // kumiko-feature-version: 1
 //
-// mail-transport-smtp — concrete SMTP-implementation for the
-// mail-foundation plugin-API.
+// mail-transport-smtp — concrete SMTP implementation for the
+// mail-foundation plugin API.
 //
-// **Was diese Feature liefert:**
-//   1. Provider-spezifische Tenant-Config (host/port/secure/from/authUser)
-//      und Secret (smtp.password). Self-contained — mail-foundation kennt
-//      diese Schlüssel nicht; wenn ein App-Owner zwischen SMTP und Brevo-
-//      API wechseln will, hat er pro-Plugin eigenständige Config-Sets.
-//   2. **Plugin-Registration** via `r.useExtension("mailTransport",
-//      "smtp", { build })`. Beim Boot kennt mail-foundation's
-//      Factory-Lookup damit den name "smtp" ↔ build-Funktion.
-//   3. `build(ctx, tenantId)` liest die config-keys + secret und ruft
-//      `createSmtpTransport()` aus channel-email auf. Das ist der
-//      EINZIGE Cross-Feature-Import dieses Plugins — bewusst lokal
-//      gehalten, mail-foundation bleibt provider-frei.
+// **What this feature provides:**
+//   1. Provider-specific tenant config (host/port/secure/from/authUser)
+//      and secret (smtp.password). Self-contained — mail-foundation does not
+//      know these keys; when an app owner switches between SMTP and the Brevo
+//      API, each plugin has its own independent config sets.
+//   2. **Plugin registration** via `r.useExtension("mailTransport",
+//      "smtp", { build })`. At boot, mail-foundation's factory lookup maps
+//      the name "smtp" to the build function.
+//   3. `build(ctx, tenantId)` reads the config keys and secret, then calls
+//      `createSmtpTransport()` from channel-email. This is the plugin's
+//      ONLY cross-feature import, deliberately kept local so
+//      mail-foundation remains provider-independent.
 //
-// **Pattern-Vorbild:** mirrors `channel-email` registering itself for
-// `delivery`. Diese Feature ist analog: registriert sich für
-// mail-foundation's "mailTransport"-Extension-Point.
+// **Pattern reference:** mirrors `channel-email` registering itself for
+// `delivery`. This feature is analogous: it registers for
+// mail-foundation's "mailTransport" extension point.
 //
-// **Boot-Dependencies:**
+// **Boot dependencies:**
 //   - `mail-foundation` — extension-point owner
-//   - `config` — für die Tenant-Config-Keys
-//   - `secrets` — für das verschlüsselte SMTP-Password
+//   - `config` — for the tenant config keys
+//   - `secrets` — for the encrypted SMTP password
 
 import type { lookup } from "node:dns/promises";
 import {

package/packages/bundled-features/src/managed-pages/branding.ts

@@ -20,13 +20,13 @@ import { type BrandingTokens, EMPTY_BRANDING } from "../page-render/index.ts";
 // `write: access.withSystem(access.admin)` — tenant admins self-service via
 // configEdit AND the system actor (ctx.systemWriteAs) may provision/migrate
 // these keys. The scope default (`access.admin`, admin-only) has no system
-// path, so a continuity migration could not set them (issue #396). Adding
-// SYSTEM_ROLE keeps the keys human-writable (checkWriteAccess collapses to
+// path, so a continuity migration could not set them. Adding SYSTEM_ROLE
+// keeps the keys human-writable (checkWriteAccess collapses to
 // system-only only when system is the SOLE writer), so self-service survives.
 //
-// CONTINUITY (Phase 5 — Prod trap): these keys land under
+// CONTINUITY (Prod trap): these keys land under
 // `managed-pages:config:branding-*`, NOT the live `publicstatus:config:
-// branding-*`. The publicstatus consumer (Phase 5) MUST migrate the existing
+// branding-*`. The publicstatus consumer MUST migrate the existing
 // read_config_values rows to the new QNs per tenant BEFORE switching the read
 // path, or every tenant resets to defaults on deploy. The migration is
 // deliberately NOT built here — the source QNs belong to the consumer app.
@@ -37,7 +37,7 @@ import { type BrandingTokens, EMPTY_BRANDING } from "../page-render/index.ts";
 // also renders. text keys carry an explicit length cap too — `validateType`
 // only checks the JS type, and the configEdit `maxLength` is client-side, so a
 // direct config:write:set would otherwise be unbounded (the page body is
-// likewise capped in Phase 2).
+// likewise capped).
 const HEX_PATTERN = {
   regex: "^$|^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
 } as const;
@@ -67,7 +67,7 @@ export const MANAGED_PAGES_CSS_FEATURE = "managed-pages-css";
 // site-url`. BRANDING_QN below is the single source those QN strings are read
 // from (configEdit screen + render read); the integration test pins write-
 // target == read-source end-to-end.
-// Admin self-service + system provisioning (see write-access note above, #396).
+// Admin self-service + system provisioning.
 const BRANDING_WRITE = access.withSystem(access.admin);
 
 export const BRANDING_KEYS = {

package/packages/bundled-features/src/managed-pages/feature.ts

@@ -23,13 +23,13 @@ import { MANAGED_PAGES_I18N } from "./web/i18n.ts";
 // 60s-shared-cache saves the origin-revalidate roundtrip; CMS edits are live within 60s.
 const PUBLIC_PAGE_CACHE = { kind: "revalidate", maxAgeSeconds: 60 } as const;
 
-// QN-Konstante als dokumentierter Public-Contract — der Render-Pfad ruft
-// die by-slug-Query via systemQuery in-process (kein Code-Import des
-// Handlers, symmetrisch zum legal-pages-Muster).
+// QN constant as a documented public contract — the render path calls
+// the by-slug query in-process via systemQuery (without importing the
+// handler's code, symmetrically with the legal-pages pattern).
 const BY_SLUG_QN = "managed-pages:query:by-slug";
 
-// Raw Handler-Return von bySlugQuery (published-only) — systemQuery dispatcht
-// direkt gegen den Handler, keine `{data}`-Envelope wie am /api/query-Wire.
+// Raw handler return from bySlugQuery (published-only) — systemQuery dispatches
+// directly to the handler, without the `{data}` envelope used on the /api/query wire.
 type BySlugQueryResult = {
   title: string;
   body: string;
@@ -83,61 +83,61 @@ export type ManagedPagesWrapLayout = (opts: {
 }) => string;
 
 export type ManagedPagesOptions = {
-  /** Host → tenantId für anonyme per-Tenant-Auslieferung. NULL → 404 (kein
-   *  Tenant für diesen Host). Apex-/Marketing-Apps geben hier ihre Subdomain-
-   *  /Custom-Domain-Auflösung rein; single-tenant gibt konstant einen
-   *  tenantId (oder SYSTEM_TENANT_ID) zurück. Erforderlich, weil der Apex-
-   *  Host keinen ambient ctx.tenantId hat. */
+  /** Host → tenantId for anonymous per-tenant delivery. NULL → 404 (no
+   *  tenant for this host). Apex/marketing apps provide their subdomain or
+   *  custom-domain resolution here; single-tenant apps return a constant
+   *  tenantId (or SYSTEM_TENANT_ID). Required because the apex host has no
+   *  ambient ctx.tenantId. */
   readonly resolveApexTenant: (host: string) => Promise<string | null> | string | null;
-  /** Custom Layout-Wrapper (Branding/Chrome). Default: minimaler
-   *  page-render-Skeleton. Erhält slug + SEO-Meta zur freien Nutzung.
-   *  **`branding` ist RAW, untrusted tenant input.** `title`/`description`
-   *  sind am Write nur längen-gecappt, NICHT HTML-escaped; `customCss` ist
-   *  ungesanitet. Der Wrapper MUSS sie über die Boundary-Helper emittieren
-   *  (alle re-exported von `@cosmicdrift/kumiko-bundled-features/managed-pages`):
-   *  `brandingHeaderHtml(branding)` + `brandingStyleBlock(branding)` (escapen
-   *  Header/Theme) und — mit allowCustomCss — `tenantStyleBlock(branding.
-   *  customCss)` ins `<head>` plus `TENANT_CONTENT_ATTR` am Body-Container. Ein
-   *  Custom-Wrapper der `branding.title` selbst interpoliert ist stored XSS;
-   *  der Default-Wrapper nutzt durchweg die Helper. */
+  /** Custom layout wrapper (branding/chrome). Default: a minimal page-render
+   *  skeleton. Receives slug + SEO meta for free use.
+   *  **`branding` is RAW, untrusted tenant input.** `title`/`description`
+   *  are only length-capped on write, NOT HTML-escaped; `customCss` is
+   *  unsanitized. The wrapper MUST emit them through the boundary helpers
+   *  (all re-exported from `@cosmicdrift/kumiko-bundled-features/managed-pages`):
+   *  `brandingHeaderHtml(branding)` + `brandingStyleBlock(branding)` (which
+   *  escape header/theme) and, with allowCustomCss, `tenantStyleBlock(branding.
+   *  customCss)` in the `<head>` plus `TENANT_CONTENT_ATTR` on the body
+   *  container. A custom wrapper that interpolates `branding.title` itself is
+   *  stored XSS; the default wrapper uses the helpers throughout. */
   readonly wrapLayout?: ManagedPagesWrapLayout;
-  /** Basis-Pfad der Page-Routes. Default "/p" → GET /p/:slug. */
+  /** Base path for page routes. Default "/p" → GET /p/:slug. */
   readonly basePath?: string;
-  /** Default-Sprache wenn `?lang=` fehlt. Default "en". */
+  /** Default language when `?lang=` is missing. Default "en". */
   readonly defaultLang?: string;
-  /** Aktiviert die per-Tenant Custom-CSS-Capability (raw, untrusted): ein
-   *  `branding-custom-css` Config-Key + ein CSS-Feld im Branding-Editor + die
-   *  Render-Emission als scoped, allowlist-sanitized `<style data-tenant-css>`.
-   *  Default **false** (fail-closed — opt-in für untrusted-Tenant-Input). Auch
-   *  wenn true, wird die Emission zusätzlich per-Tenant über das
-   *  `managed-pages-css`-Toggle (createManagedPagesCssFeature) gegated, sobald
-   *  ein feature-toggles/tier-engine-Runtime verdrahtet ist. Der Render-time-
-   *  Sanitizer (page-render/css-sanitize) ist der Safety-Boundary. */
+  /** Enables the per-tenant custom CSS capability (raw, untrusted): a
+   *  `branding-custom-css` config key + a CSS field in the branding editor +
+   *  render emission as a scoped, allowlist-sanitized `<style data-tenant-css>`.
+   *  Default **false** (fail-closed — opt-in for untrusted tenant input). Even
+   *  when true, emission is additionally gated per tenant by the
+   *  `managed-pages-css` toggle (createManagedPagesCssFeature) once a
+   *  feature-toggles/tier-engine runtime is wired. The render-time sanitizer
+   *  (page-render/css-sanitize) is the safety boundary. */
   readonly allowCustomCss?: boolean;
 };
 
-// managed-pages — vom Tenant editierbare, server-gerenderte Public-Pages.
-// Generalisiert das legal-pages-Render-Muster: eine dynamische Slug-Route
-// (`GET /p/:slug`), die den Tenant aus dem Host auflöst (resolveApexTenant),
-// die published Page lädt, Markdown gehärtet rendert (page-render) und über
-// einen optionalen wrapLayout in Chrome legt. Drafts → 404. Per-Tenant-
-// Content wird per `Vary: Host` cache-isoliert.
+// managed-pages — tenant-editable, server-rendered public pages.
+// Generalizes the legal-pages rendering pattern: a dynamic slug route
+// (`GET /p/:slug`) that resolves the tenant from the Host (resolveApexTenant),
+// loads the published page, renders hardened Markdown (page-render), and wraps
+// it in chrome through an optional wrapLayout. Drafts → 404. Per-tenant
+// content is cache-isolated through `Vary: Host`.
 //
-// Admin-Authoring: registriert entityList + entityEdit für `page` (TenantAdmin/
-// SystemAdmin) + die Convention-CRUD-Handler die der Renderer per Konvention
-// dispatcht. Die Screens MÜSSEN hier liegen (Boot-Validator verlangt entity-Ref
-// same-feature); Nav/Workspace bleibt App-Sache.
+// Admin authoring: registers entityList + entityEdit for `page` (TenantAdmin/
+// SystemAdmin) and the convention CRUD handlers dispatched by the renderer.
+// The screens MUST live here (the boot validator requires the entity reference
+// in the same feature); navigation/workspace remains the app's responsibility.
 //
-// Voraussetzungen am App-Bootstrap:
-//   • anonymousAccess so verdrahtet, dass der X-Tenant-Header honoriert wird
-//     — Multi-Tenant nutzt einen tenantResolver (oder keinen defaultTenantId).
-//     Ein fixer defaultTenantId lockt Single-Tenant und lehnt den per-Page
-//     gesetzten X-Tenant mit 400 tenant_mismatch ab.
-//   • Admin-UI: die App zeigt via `r.nav({ screen: "managed-pages:screen:
-//     page-list" })` + Workspace-Eintrag auf die hier deklarierten Screens
-//     (cross-feature Nav→Screen ist global-validiert) und grantet ihren Admins
-//     TenantAdmin. Ohne Nav bleiben die Screens dormant — kein Leak in
-//     flat-nav-Apps die managed-pages nur zum Public-Render nutzen.
+// App bootstrap requirements:
+//   • anonymousAccess must be wired to honor the X-Tenant header
+//     — multi-tenant apps use a tenantResolver (or no defaultTenantId).
+//     A fixed defaultTenantId locks the app to single-tenant mode and rejects
+//     the per-page X-Tenant with 400 tenant_mismatch.
+//   • Admin UI: the app exposes these screens via `r.nav({ screen:
+//     "managed-pages:screen:page-list" })` plus a workspace entry
+//     (cross-feature Nav→Screen is globally validated) and grants its admins
+//     TenantAdmin. Without navigation, the screens remain dormant — no leak in
+//     flat-nav apps that use managed-pages only for public rendering.
 export function createManagedPagesFeature(opts: ManagedPagesOptions): FeatureDefinition {
   const wrapLayout: ManagedPagesWrapLayout =
     opts.wrapLayout ??
@@ -192,8 +192,8 @@ export function createManagedPagesFeature(opts: ManagedPagesOptions): FeatureDef
       path: `${basePath}/:slug`,
       anonymous: true,
       handler: async (c, { systemQuery }) => {
-        // `param("slug")` ist string|undefined, weil `path` ein computed
-        // Template ist (Hono inferiert `:slug` nur aus String-Literalen).
+        // `param("slug")` is string|undefined because `path` is a computed
+        // template (Hono infers `:slug` only from string literals).
         const slug = c.req.param("slug");
         if (!slug) return c.text("not found", 404);
         const lang = c.req.query("lang") || defaultLang;
@@ -204,13 +204,13 @@ export function createManagedPagesFeature(opts: ManagedPagesOptions): FeatureDef
         const tenantId = await opts.resolveApexTenant(host);
         if (!tenantId) return c.text("not found", 404);
 
-        // Page + branding read in parallel, beide über systemQuery in-
-        // process gegen den host-resolved tenantId erzwungen (kein X-Tenant-
-        // Header-Trick über app.fetch — der sähe für einen host-basierten
-        // anonymousAccess-Resolver wie ein Client-Override aus und würde
-        // von resolverTrust: "authoritative" zurecht abgelehnt; siehe
-        // systemQuery's Doc in http-route.ts). Branding ist Deko → ein
-        // Fehlschlag degradiert zum unbranded Default, blockt nie die Page.
+        // Page and branding are read in parallel, both forced through systemQuery
+        // in-process for the host-resolved tenantId (no X-Tenant header trick
+        // through app.fetch — for a host-based anonymousAccess resolver, that
+        // would look like a client override and would rightly be rejected by
+        // resolverTrust: "authoritative"; see systemQuery's documentation in
+        // http-route.ts). Branding is decorative → a failure degrades to the
+        // unbranded default and never blocks the page.
         let pageSettled: { ok: true; data: BySlugQueryResult } | { ok: false };
         let brandingResult: BrandingTokens;
         try {
@@ -246,8 +246,8 @@ export function createManagedPagesFeature(opts: ManagedPagesOptions): FeatureDef
           "content-type": "text/html; charset=utf-8",
           vary: "Host",
         } as const;
-        // 304 (Revision unverändert) und HEAD überspringen beide das
-        // Markdown-Rendern — der Body wird ohnehin verworfen.
+        // 304 (unchanged revision) and HEAD both skip Markdown rendering — the body
+        // would be discarded anyway.
         if (etagMatches(c.req.raw.headers.get("if-none-match"), etag) || c.req.method === "HEAD") {
           return cachedSecurePageResponse(c.req.raw, {
             body: null,

package/packages/bundled-features/src/managed-pages/handlers/by-slug.query.ts

@@ -3,12 +3,11 @@ import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { type PageRow, pagesTable } from "../table.ts";
 
-// Public-Read by (tenantId, slug, lang). Anonymous-capable (Landing-/
-// Marketing-Pages). Tenant kommt aus query.user.tenantId — am Render-Pfad
-// via X-Tenant = Host-resolved-tenant gesetzt. Liefert NUR published Pages
-// mit Body: Drafts + leere Pages sind für anonyme Besucher unsichtbar
-// (Route → 404). Admin-Editing nutzt die Entity-List/Edit-Screens, nicht
-// diese Query.
+// Public read by (tenantId, slug, lang), including anonymous access for landing and
+// marketing pages. The tenant comes from query.user.tenantId, set on the render path
+// via X-Tenant = Host-resolved-tenant. Returns ONLY published pages with a body:
+// drafts and empty pages are invisible to anonymous visitors (the route returns 404).
+// Admin editing uses the entity list/edit screens instead of this query.
 export const bySlugQuery = defineQueryHandler({
   name: "by-slug",
   schema: z.object({

package/packages/bundled-features/src/managed-pages/handlers/by-tenant-published.query.ts

@@ -3,12 +3,12 @@ import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { type PageRow, pagesTable } from "../table.ts";
 
-// Public-Read aller published Pages eines Tenants — Discovery-Quelle für
-// sitemap.xml/llms.txt (siehe seo-Feature). Anders als by-slug (single-row,
-// nur der angefragte Slug) listet dies alle published Slugs auf einmal, SQL-
-// seitig auf `published = true` gefiltert (Drafts nie im Ergebnis, kein
-// Body-Content — Discovery-Zweck braucht nur Slug/Title/updatedAt).
-// Anonymous: explizit in roles, symmetrisch zu text-content's by-tenant.
+// Public read of all published pages for a tenant, used to discover URLs for
+// sitemap.xml/llms.txt (see the seo feature). Unlike by-slug, which fetches one
+// slug's content, this lists all published slugs in one query, filtered in SQL
+// with `published = true`; drafts never appear, and only slug/title/updatedAt are
+// returned because discovery does not require body content.
+// Anonymous access is explicit in roles, matching text-content's by-tenant.
 export type PublishedPageSummary = {
   readonly slug: string;
   readonly lang: string;
@@ -19,8 +19,8 @@ export type PublishedPageSummary = {
 export const byTenantPublishedQuery = defineQueryHandler({
   name: "by-tenant-published",
   schema: z.object({
-    /** Optional cross-tenant read — nur für SystemAdmin. Symmetrisch zur
-     *  by-slug.query Override-Logik. */
+    /** Optional cross-tenant read — only for SystemAdmin. Matches the override
+     *  logic in by-slug.query. */
     tenantIdOverride: z.string().min(1).optional(),
   }),
   access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },

package/packages/bundled-features/src/managed-pages/handlers/set.write.ts

@@ -18,12 +18,10 @@ const langSchema = z
 
 const executor = createEventStoreExecutor(pagesTable, pageEntity, { entityName: "page" });
 
-// Upsert einer Page — eine Operation pro (tenantId, slug, lang). Tenant-
-// Scope default aus event.user; SystemAdmin kann via `tenantIdOverride`
-// für einen anderen Tenant schreiben (typisch SYSTEM_TENANT_ID für app-
-// weite Pages). published/description/ogImage werden bei Update preserved
-// wenn im Payload weggelassen (undefined) — damit ein Publish-Toggle nicht
-// den Body überschreiben muss und umgekehrt.
+// Upserts one page per (tenantId, slug, lang). The tenant scope defaults to event.user;
+// SystemAdmin can write to another tenant via `tenantIdOverride` (typically SYSTEM_TENANT_ID
+// for app-wide pages). On update, omitted published/description/ogImage values are preserved
+// so a publish toggle does not overwrite the body, and vice versa.
 export const setWrite = defineWriteHandler({
   name: "set",
   schema: z.object({
@@ -34,7 +32,7 @@ export const setWrite = defineWriteHandler({
     description: z.string().max(500).nullable().optional(),
     ogImage: z.string().max(2000).nullable().optional(),
     published: z.boolean().optional(),
-    /** Cross-tenant write — nur SystemAdmin (z.B. SYSTEM_TENANT_ID-Pages). */
+    /** Cross-tenant write — only SystemAdmin (for example, SYSTEM_TENANT_ID pages). */
     tenantIdOverride: z.string().min(1).optional(),
   }),
   access: { roles: ["TenantAdmin", "SystemAdmin"] },

package/packages/bundled-features/src/managed-pages/screens/page-screens.ts

@@ -3,14 +3,14 @@ import type {
   EntityListScreenDefinition,
 } from "@cosmicdrift/kumiko-framework/engine";
 
-// Admin-Authoring-Screens für die `page`-Entity. Reine Daten (JSON-safe) —
-// der generische DataTable-/Form-Renderer mountet sie, kein React-Component
-// nötig. Beide MÜSSEN im managed-pages-Feature registriert werden (nicht in
-// der App): der Boot-Validator verlangt, dass `entity: "page"` im selben
-// Feature deklariert ist wie der Screen. Nav/Workspace bleibt App-Sache
-// (placement-spezifisch, `default`-Workspace ist ein App-Singleton) — die
-// App zeigt via `r.nav({ screen: "managed-pages:screen:page-list" })` darauf
-// (cross-feature Nav→Screen ist gegen den globalen Screen-QN-Set validiert).
+// Admin authoring screens for the `page` entity. These are JSON-safe data only —
+// the generic DataTable/form renderer mounts them, so no React component is
+// needed. Both MUST be registered in the managed-pages feature (not in the
+// app): the boot validator requires `entity: "page"` to be declared in the
+// same feature as the screen. Navigation and workspace placement remain app-
+// specific (`default` workspace is an app singleton) — the app points to this
+// via `r.nav({ screen: "managed-pages:screen:page-list" })`.
+// Cross-feature Nav→Screen is validated against the global screen QN set.
 
 const ADMIN_ROLES = ["TenantAdmin", "SystemAdmin"] as const;
 
@@ -72,9 +72,9 @@ export const pageEditScreen: EntityEditScreenDefinition = {
           { field: "title", span: 2 },
           { field: "description", span: 2 },
           { field: "ogImage", span: 2 },
-          // Publish/Unpublish: der `published`-Toggle hier IST der
-          // Publish-Mechanismus (kein separater One-Click-List-Action —
-          // rowAction-payload kann keine Konstanten injizieren).
+          // Publish/Unpublish: the `published` toggle here IS the publishing
+          // mechanism (there is no separate one-click list action —
+          // rowAction-payload cannot inject constants).
           { field: "published", span: 1 },
         ],
       },