@cosmicdrift/kumiko-samples 0.392.2 → 0.394.0

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

@@ -316,7 +316,7 @@
     },
     {
       "name": "billing-foundation",
-      "description": "Plugin host for subscription billing. Manages the `read_subscriptions` projection table and exposes 5 domain events (subscription created/updated/canceled, invoice paid/failed) appended by the foundation's own `billing-foundation:write:process-event` write-handler after provider plugins verify and normalize each webhook. Also manages a separate `read_payments` projection table (one row per one-off-payment) fed by its own `payment-received` event and `billing-foundation:write:process-payment-event` write-handler. Also ships `billing-foundation:write:create-checkout-session` and `billing-foundation:write:create-portal-session` write-handlers, a `billing-foundation:query:subscription:list` query handler, and a `createSubscriptionWebhookRoute` factory for the `/api/subscription/webhook/:providerName` extraRoute. `createBillingFoundationFeature({ baseUrl, catalog })` additionally derives a `billing-foundation:query:billing-plans` query, `start-plan-checkout`/`switch-plan` write-handlers, a `plan-switch-preview` query and a dormant billing-plans dashboard screen/panel from the catalog. Several providers can be mounted at once: new checkouts are offered by every enabled provider (enabled means keys set and billingLive on, or simply mounted for plugins without `isBillingEnabled`), the customer picks one in the plan panel and `start-plan-checkout` takes a `providerName`. An existing subscription stays with the provider that stored it, so the plan list and every switch follow that provider. A plan switch is either hosted (`createPlanSwitchSession` answers a url) or in-app (`previewPlanSwitch` shows the proration, `applyPlanSwitch` runs after the customer confirms; `switch-plan` then answers `{ applied: true }` and records the consent). `consumerProtection.providerTexts` overrides the checkout note and the VAT note per provider. Also ships `billing-foundation:write:sync-subscription` (pulls a provider plugin's live subscription state via `retrieveSubscription` and appends drift as a `subscription.updated` event, which catches changes made on the provider's own dashboard that never reached us as a webhook) and the `sync-subscriptions` job (manual-trigger + runOnBoot, perTenant) that dispatches it. Low-level building block: use `subscription-stripe`, `subscription-mollie` or `subscription-dodo` unless you are writing a new payment provider.",
+      "description": "Plugin host for subscription billing. Manages the `read_subscriptions` projection table and exposes 5 domain events (subscription created/updated/canceled, invoice paid/failed) appended by the foundation's own `billing-foundation:write:process-event` write-handler after provider plugins verify and normalize each webhook. Also manages a separate `read_payments` projection table (one row per one-off-payment) fed by its own `payment-received` event and `billing-foundation:write:process-payment-event` write-handler. Also ships `billing-foundation:write:create-checkout-session` and `billing-foundation:write:create-portal-session` write-handlers, a `billing-foundation:query:subscription:list` query handler, and a `createSubscriptionWebhookRoute` factory for the `/api/subscription/webhook/:providerName` extraRoute. `createBillingFoundationFeature({ baseUrl, catalog })` additionally derives a `billing-foundation:query:billing-plans` query, `start-plan-checkout`/`switch-plan` write-handlers, a `plan-switch-preview` query and a dormant billing-plans dashboard screen/panel from the catalog. Several providers can be mounted at once: new checkouts are offered by every enabled provider (enabled means keys set and billingLive on, or simply mounted for plugins without `isBillingEnabled`), the customer picks one in the plan panel and `start-plan-checkout` takes a `providerName`. An existing subscription stays with the provider that stored it, so the plan list and every switch follow that provider. A plan switch is either hosted (`createPlanSwitchSession` answers a url) or in-app (`previewPlanSwitch` shows the proration, `applyPlanSwitch` runs after the customer confirms; `switch-plan` then answers `{ applied: true }` and records the consent). `consumerProtection.providerTexts` overrides the checkout note and the VAT note per provider. Also ships `billing-foundation:write:sync-subscription` (pulls a provider plugin's live subscription state via `retrieveSubscription` and appends drift as a `subscription.updated` event, which catches changes made on the provider's own dashboard that never reached us as a webhook) and the `sync-subscriptions` job (manual-trigger + runOnBoot, perTenant) that dispatches it. Low-level building block: use `subscription-stripe`, `subscription-mollie` or `subscription-paddle` unless you are writing a new payment provider.",
       "toggleableDefault": null,
       "requires": [
         "tenant-lifecycle",
@@ -1421,9 +1421,15 @@
       "configKeys": [],
       "secrets": [],
       "writeHandlers": [
+        "inbound-mail-foundation:write:acknowledge-quarantine",
+        "inbound-mail-foundation:write:attach-message-content",
         "inbound-mail-foundation:write:connect-account",
         "inbound-mail-foundation:write:disconnect-account",
         "inbound-mail-foundation:write:ingest-message",
+        "inbound-mail-foundation:write:mark-credential-stored",
+        "inbound-mail-foundation:write:reactivate-account",
+        "inbound-mail-foundation:write:retry-quarantined-message",
+        "inbound-mail-foundation:write:set-trusted-authserv-id",
         "inbound-mail-foundation:write:update-account"
       ],
       "uiHints": {
@@ -1434,7 +1440,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. 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.",
+      "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 shared mailbox through the \"Connect mailbox\" form on the mail accounts list and members a personal one through the same form on \"My mail accounts\" (`connect-mailbox` and `connect-my-mailbox` check the IMAP login and the SMTP login of the outgoing server first, then creates the account and its credential secret in one transaction; `reconnect-mailbox` does the same check for an existing mailbox with a sign-in error and overwrites its credential secret); 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",
@@ -1453,7 +1459,9 @@
       "configKeys": [],
       "secrets": [],
       "writeHandlers": [
-        "inbound-provider-imap:write:connect-mailbox"
+        "inbound-provider-imap:write:connect-mailbox",
+        "inbound-provider-imap:write:connect-my-mailbox",
+        "inbound-provider-imap:write:reconnect-mailbox"
       ],
       "uiHints": {
         "displayLabel": "Inbound Mail · IMAP",
@@ -2504,8 +2512,34 @@
       }
     },
     {
-      "name": "subscription-dodo",
-      "description": "Dodo Payments provider plugin for `billing-foundation`. Dodo acts as merchant of record: it sells to the customer and issues invoice and VAT, so the consumer-protection texts for this provider come from `consumerProtection.providerTexts`. Reads its API key and webhook secret from system config keys with `backing:\"secrets\"` (envelope-encrypted in the secrets store under the system tenant), plus a `billingLive` master switch and an `environment` key (test | live). `environment` is its own key because Dodo serves test and live mode from different API hosts and a live key must never hit the test host or the other way round; `billingLive` only decides whether checkouts are offered at all. All four are runtime config, so keys rotate and prod goes live without a redeploy, and the `mask` on each derives the sysadmin settings screen and nav. Mount via `createSubscriptionDodoFeature({ priceToTier })`; the optional `apiKey`/`webhookSecret` options are env to secrets bridge fallbacks (`DODO_PAYMENTS_API_KEY`, `DODO_PAYMENTS_WEBHOOK_KEY`). The plugin always mounts; `createCheckoutSession` throws `feature_disabled` unless `billingLive` is true. Webhooks arrive at `/api/subscription/webhook/dodo` and are verified per the Standard Webhooks spec (HMAC-SHA256 over id, timestamp and the raw body, 5 minute tolerance); events for products outside `priceToTier` or without tenant metadata are dropped. Implements hosted checkout, customer portal, cancel and resume, `retrievePrices` (10-minute TTL cache), `retrieveSubscription` for the sync job, and an in-app plan switch: `previewPlanSwitch` shows the proration before the customer confirms, `applyPlanSwitch` changes the plan without a hosted page and waits for the `plan_changed` webhook to move the tier. A plan switch in Dodo requires all plan products to belong to one Product Collection.",
+      "name": "subscription-mollie",
+      "description": "Mollie payment provider plugin for `billing-foundation`, covering the DACH/EU mid-market use case. Mount via `createSubscriptionMollieFeature({ apiKey, webhookUrl, priceToTier, priceToConfig })` — the factory validates that `priceToTier` and `priceToConfig` keys are identical at boot time. Implements `verifyAndParseWebhook` (lazy Mollie-API fetch + heuristic event-type mapping) and `createCheckoutSession` (customer + first-payment with `sequenceType=\"first\"`); `createPortalSession` and `cancelSubscription` are not available because Mollie has no customer portal and requires a `customerId` that the plugin contract does not carry.",
+      "toggleableDefault": null,
+      "requires": [
+        "billing-foundation"
+      ],
+      "optionalRequires": [],
+      "configReads": [],
+      "exposesApis": [],
+      "usesApis": [],
+      "extensionsUsed": [
+        {
+          "extensionName": "subscriptionProvider",
+          "entityName": "mollie"
+        }
+      ],
+      "configKeys": [],
+      "secrets": [],
+      "writeHandlers": [],
+      "uiHints": {
+        "displayLabel": "Billing · Mollie",
+        "category": "billing",
+        "recommended": false
+      }
+    },
+    {
+      "name": "subscription-paddle",
+      "description": "Paddle Billing provider plugin for `billing-foundation`. Paddle acts as merchant of record: it sells to the customer and issues invoice and VAT, so the consumer-protection texts for this provider come from `consumerProtection.providerTexts`. Reads its API key, webhook secret and tenant binding key from system config keys with `backing:\"secrets\"` (envelope-encrypted in the secrets store under the system tenant), the public Paddle.js `client-token`, a `billingLive` master switch and an `environment` key (sandbox | live). `environment` is its own key because Paddle serves sandbox and live from different API hosts and a live key must never hit the sandbox host or the other way round; `billingLive` only decides whether checkouts are offered at all. All of them are runtime config, so keys rotate and prod goes live without a redeploy, and the `mask` on each derives the sysadmin settings screen and nav. Mount via `createSubscriptionPaddleFeature({ priceToTier })`; the optional `apiKey`/`webhookSecret`/`tenantBindingKey`/`clientToken` options are env to config bridge fallbacks (`PADDLE_API_KEY`, `PADDLE_WEBHOOK_SECRET`, `PADDLE_TENANT_BINDING_KEY`, `PADDLE_CLIENT_TOKEN`). The plugin always mounts; `createCheckoutSession` throws `feature_disabled` unless `billingLive` is true, and billing counts as enabled only with API key and binding key present. Webhooks arrive at `/webhooks/subscription/paddle` when mounted through the server-runtime `billing.paddle` boot option, or at `/api/subscription/webhook/paddle` when `createSubscriptionWebhookRoute` is mounted by hand and are verified with the `Paddle-Signature` header (HMAC-SHA256 over `ts:rawBody` keyed with the raw secret, any `h1` may match, 5 minute tolerance). Paddle.js can open checkouts with arbitrary `customData` from the browser, so `custom_data.tenantId` is only trusted together with `tenantBinding`, an HMAC of the tenant id under the binding key; events without a valid binding, for prices outside `priceToTier` or without a tenant are dropped. Rotating the binding key makes the webhooks of existing subscriptions fail that check until they are re-bound. Paddle has no hosted checkout page, so the feature serves the Default Payment Link itself at `/billing/paddle-checkout` (the Default Payment Link in the Paddle dashboard must point to `<APP_BASE_URL>/billing/paddle-checkout`; it is the only source, because checkouts are created without a `checkout.url`). Create subscription prices in the Paddle catalog with quantity minimum and maximum 1; for one-off packs set the quantity limits on purpose, because the payment event carries `quantity` and the app has to multiply its credits by it: an anonymous page with its own CSP that loads Paddle.js from cdn.paddle.com, the one external script this framework allows, and opens the overlay for the transaction. Implements checkout, customer portal, cancel and resume, `retrievePrices` (batched, 10-minute TTL cache), `retrieveSubscription` for the sync job, and an in-app plan switch: `previewPlanSwitch` shows the proration before the customer confirms, `applyPlanSwitch` changes the plan without a hosted page and waits for the `subscription.updated` webhook to move the tier.",
       "toggleableDefault": null,
       "requires": [
         "billing-foundation",
@@ -2519,13 +2553,13 @@
       "extensionsUsed": [
         {
           "extensionName": "subscriptionProvider",
-          "entityName": "dodo"
+          "entityName": "paddle"
         }
       ],
       "configKeys": [
         {
           "key": "api-key",
-          "qualifiedName": "subscription-dodo:config:api-key",
+          "qualifiedName": "subscription-paddle:config:api-key",
           "type": "text",
           "scope": "system",
           "default": null,
@@ -2546,7 +2580,7 @@
         },
         {
           "key": "billing-live",
-          "qualifiedName": "subscription-dodo:config:billing-live",
+          "qualifiedName": "subscription-paddle:config:billing-live",
           "type": "boolean",
           "scope": "system",
           "default": false,
@@ -2566,17 +2600,38 @@
             "SystemAdmin"
           ]
         },
+        {
+          "key": "client-token",
+          "qualifiedName": "subscription-paddle:config:client-token",
+          "type": "text",
+          "scope": "system",
+          "default": null,
+          "encrypted": false,
+          "computed": false,
+          "validated": false,
+          "options": null,
+          "bounds": null,
+          "pattern": null,
+          "writeRoles": [
+            "SystemAdmin"
+          ],
+          "readRoles": [
+            "TenantAdmin",
+            "Admin",
+            "SystemAdmin"
+          ]
+        },
         {
           "key": "environment",
-          "qualifiedName": "subscription-dodo:config:environment",
+          "qualifiedName": "subscription-paddle:config:environment",
           "type": "select",
           "scope": "system",
-          "default": "test",
+          "default": "sandbox",
           "encrypted": false,
           "computed": false,
           "validated": false,
           "options": [
-            "test",
+            "sandbox",
             "live"
           ],
           "bounds": null,
@@ -2591,8 +2646,8 @@
           ]
         },
         {
-          "key": "webhook-secret",
-          "qualifiedName": "subscription-dodo:config:webhook-secret",
+          "key": "tenant-binding-key",
+          "qualifiedName": "subscription-paddle:config:tenant-binding-key",
           "type": "text",
           "scope": "system",
           "default": null,
@@ -2610,38 +2665,33 @@
             "Admin",
             "SystemAdmin"
           ]
-        }
-      ],
-      "secrets": [],
-      "writeHandlers": [],
-      "uiHints": {
-        "displayLabel": "Billing · Dodo Payments",
-        "category": "billing",
-        "recommended": false
-      }
-    },
-    {
-      "name": "subscription-mollie",
-      "description": "Mollie payment provider plugin for `billing-foundation`, covering the DACH/EU mid-market use case. Mount via `createSubscriptionMollieFeature({ apiKey, webhookUrl, priceToTier, priceToConfig })` — the factory validates that `priceToTier` and `priceToConfig` keys are identical at boot time. Implements `verifyAndParseWebhook` (lazy Mollie-API fetch + heuristic event-type mapping) and `createCheckoutSession` (customer + first-payment with `sequenceType=\"first\"`); `createPortalSession` and `cancelSubscription` are not available because Mollie has no customer portal and requires a `customerId` that the plugin contract does not carry.",
-      "toggleableDefault": null,
-      "requires": [
-        "billing-foundation"
-      ],
-      "optionalRequires": [],
-      "configReads": [],
-      "exposesApis": [],
-      "usesApis": [],
-      "extensionsUsed": [
+        },
         {
-          "extensionName": "subscriptionProvider",
-          "entityName": "mollie"
+          "key": "webhook-secret",
+          "qualifiedName": "subscription-paddle:config:webhook-secret",
+          "type": "text",
+          "scope": "system",
+          "default": null,
+          "encrypted": true,
+          "computed": false,
+          "validated": false,
+          "options": null,
+          "bounds": null,
+          "pattern": null,
+          "writeRoles": [
+            "SystemAdmin"
+          ],
+          "readRoles": [
+            "TenantAdmin",
+            "Admin",
+            "SystemAdmin"
+          ]
         }
       ],
-      "configKeys": [],
       "secrets": [],
       "writeHandlers": [],
       "uiHints": {
-        "displayLabel": "Billing · Mollie",
+        "displayLabel": "Billing · Paddle",
         "category": "billing",
         "recommended": false
       }

package/samples/apps/use-all-bundled/kumiko/migrations/0056_inbound-mail-quarantine-retry.rebuild.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "tables": ["read_inbound_messages"]
+}

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

@@ -10,6 +10,7 @@
     "dev": "PORT=4186 bun --env-file=../../../.env run src/app/server.ts",
     "screenshots": "bun x playwright test e2e/screenshots.spec.ts --config=playwright.config.ts",
     "billing-gallery": "bun x playwright test --config=playwright.billing-gallery.config.ts",
+    "docs-guides": "bun x playwright test e2e/docs-guides.screenshots.spec.ts --config=playwright.config.ts && bun x playwright test --config=playwright.billing-docs.config.ts",
     "e2e": "bun x playwright test e2e/mfa-login.spec.ts --config=playwright.config.ts",
     "gen:manifest": "bun run scripts/gen-feature-manifest.ts",
     "gen:sample-index": "bun run scripts/gen-sample-index.ts"

package/samples/apps/use-all-bundled/playwright.billing-docs.config.ts

@@ -0,0 +1,15 @@
+// @runtime test
+// English docs screenshots of the billing plans screen. Boots the gallery server with the docs
+// variant switched on (net prices with a note, gross recurring price in the plan switch); the
+// German review gallery has its own config. Gated by SCREENSHOT_DIR, see the `billing-docs` script.
+import { defineAppE2eConfig, PLAYWRIGHT_DEMO_ENV } from "@cosmicdrift/kumiko-testing/e2e";
+import { E2E_PORTS } from "../../e2e/e2e-ports";
+import { GALLERY_DOCS_VARIANT_ENV } from "./e2e-billing-gallery/gallery-constants";
+
+export default defineAppE2eConfig({
+  port: E2E_PORTS["framework/use-all-bundled-billing-gallery"],
+  env: { ...PLAYWRIGHT_DEMO_ENV, [GALLERY_DOCS_VARIANT_ENV]: "1" },
+  locale: "en",
+  testDir: "./e2e-billing-docs",
+  serverEntry: "e2e-billing-gallery/server.ts",
+});

package/samples/apps/use-all-bundled/src/app/cap-overview-caps.ts

@@ -1,6 +1,7 @@
 import type { CapSpec } from "@cosmicdrift/kumiko-bundled-features/cap-overview";
 import { noteEntryTable } from "@cosmicdrift/kumiko-bundled-features/notes-history";
 import { tagEntity } from "@cosmicdrift/kumiko-bundled-features/tags";
+import { templateResourcesTable } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
 import { tenantMembershipsTable } from "@cosmicdrift/kumiko-bundled-features/tenant";
 
 import { buildEntityTable, selectMany } from "@cosmicdrift/kumiko-framework/db";
@@ -11,10 +12,11 @@ const tagTable = buildEntityTable("tag", tagEntity);
 const NOTE_LIMIT_BY_TIER: Readonly<Record<string, number>> = { free: 10, pro: 100 };
 const TAG_LIMIT_BY_TIER: Readonly<Record<string, number>> = { free: 5, pro: 50 };
 const SEAT_LIMIT_BY_TIER: Readonly<Record<string, number>> = { free: 5, pro: 20 };
+const TEMPLATE_LIMIT_BY_TIER: Readonly<Record<string, number>> = { free: 3, pro: 30 };
 const DEFAULT_LIMIT = 10;
 
-// Four example caps built from entities this sample already mounts
-// (notes-history, tags, tenant-membership) — demonstrates the caller-supplied
+// Five example caps built from entities this sample already mounts
+// (notes-history, tags, tenant-membership, template-resolver) — demonstrates the caller-supplied
 // CapSpec contract cap-overview reads against, the same shape a real app
 // would provide for its own usage tables.
 export const CAP_OVERVIEW_CAPS: readonly CapSpec[] = [
@@ -68,4 +70,16 @@ export const CAP_OVERVIEW_CAPS: readonly CapSpec[] = [
     },
     icon: "gauge",
   },
+  {
+    id: "templates",
+    label: "cap-overview.caps.templates",
+    limit: (tier) => TEMPLATE_LIMIT_BY_TIER[tier] ?? DEFAULT_LIMIT,
+    usage: async (db, tenantId) => {
+      const rows = await selectMany(db, templateResourcesTable, { tenantId: [tenantId] });
+      return rows.length;
+    },
+    // Counter only: the limit stays enforced server-side but is not shown to the tenant.
+    showLimit: false,
+    icon: "file",
+  },
 ];

package/samples/apps/use-all-bundled/src/app/cap-overview-labels-feature.ts

@@ -1,6 +1,6 @@
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 
-// Labels for the four example caps (notes, tags, seats, apiCalls) wired up in
+// Labels for the five example caps (notes, tags, seats, apiCalls, templates) wired up in
 // cap-overview-caps.ts. Cap ids are the app's choice, so their labels are
 // too — cap-overview itself carries no vocabulary for app-owned caps, same
 // reasoning as collection-labels-feature.ts for content collections.
@@ -12,6 +12,7 @@ export const capOverviewLabelsFeature = defineFeature("cap-overview-labels", (r)
       "cap-overview.caps.tags": { de: "Tags", en: "Tags" },
       "cap-overview.caps.seats": { de: "Plätze", en: "Seats" },
       "cap-overview.caps.apiCalls": { de: "API-Aufrufe", en: "API calls" },
+      "cap-overview.caps.templates": { de: "Vorlagen", en: "Templates" },
     },
   });
   return {};

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

@@ -26,6 +26,7 @@ import { customFieldsClient } from "@cosmicdrift/kumiko-bundled-features/custom-
 import { deliveryClient } from "@cosmicdrift/kumiko-bundled-features/delivery/web";
 import { featureTogglesClient } from "@cosmicdrift/kumiko-bundled-features/feature-toggles/web";
 import { foldersClient } from "@cosmicdrift/kumiko-bundled-features/folders/web";
+import { inboundMailFoundationClient } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation/web";
 import { jobsClient } from "@cosmicdrift/kumiko-bundled-features/jobs/web";
 import { sessionsClient } from "@cosmicdrift/kumiko-bundled-features/sessions/web";
 import { tagsClient } from "@cosmicdrift/kumiko-bundled-features/tags/web";
@@ -115,6 +116,7 @@ createKumikoApp({
     userDataRightsClient(),
     customFieldsClient(),
     foldersClient(),
+    inboundMailFoundationClient(),
     complianceProfilesClient(),
     featureTogglesClient(),
     // tag-list management screen (TagManager) + TagSection/TagFilter extension

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

@@ -5,11 +5,13 @@
 // (#1258): an open screen not reachable via nav is no longer an eligible
 // fallback candidate.
 
+import { MAIL_ACCOUNT_LIST_SCREEN_QN } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { ADMIN_NAV_QN, ADMIN_NAV_WORKSPACES } from "./admin-nav-feature";
 
 export const appScreensFeature: FeatureDefinition = defineFeature("app-screens", (r) => {
-  r.describe("App-side nav placement for the user-profile self-service page.");
-  r.requires({ features: ["user-profile"] });
+  r.describe("App-side nav placement for the user-profile self-service page and the mailbox list.");
+  r.requires({ features: ["user-profile", "inbound-mail-foundation"] });
   r.nav({
     id: "profile",
     label: "screen:profile.title",
@@ -29,8 +31,18 @@ export const appScreensFeature: FeatureDefinition = defineFeature("app-screens",
     access: { roles: ["SystemAdmin"] },
     workspaces: ["admin-shell:workspace:platform"],
   });
+  r.nav({
+    id: "mail-accounts",
+    label: "nav:mail-accounts.title",
+    icon: "mail",
+    screen: MAIL_ACCOUNT_LIST_SCREEN_QN,
+    parent: ADMIN_NAV_QN,
+    workspaces: ADMIN_NAV_WORKSPACES,
+    order: 20,
+  });
   r.translations({
     keys: {
+      "nav:mail-accounts.title": { de: "Postfächer", en: "Mailboxes" },
       "screen:profile.title": { de: "Profil", en: "Profile" },
       "nav:content.title": { de: "Inhalte", en: "Content" },
     },

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

@@ -468,10 +468,13 @@ export const seedScreenshotData: SeedFn = async (stack) => {
   // carry whatever the handler derives instead of a hand-built projection.
   // SYSTEM_TENANT, not the dev tenant: the screenshot admin reads the system
   // tenant — the same reason the text-block tree above seeds there.
+  // The real admin, not TestUsers.systemAdmin's id: the seed signs in with a live session row,
+  // and the session list shows that row's user. The sessionChecker re-derives roles from the
+  // admin's global SystemAdmin role, which the collection's access accepts.
   const snippetAuthor: SessionUser = {
     ...TestUsers.systemAdmin,
     tenantId: SYSTEM_TENANT_ID,
-    roles: ["TenantAdmin"],
+    id: devAdminId,
   };
   for (const snippet of [
     {

package/samples/apps/use-all-bundled/src/run-config.ts

@@ -75,8 +75,8 @@ import { createRendererPdfFeature } from "@cosmicdrift/kumiko-bundled-features/r
 import { createSecretsFeature } from "@cosmicdrift/kumiko-bundled-features/secrets";
 import { createSeoFeature } from "@cosmicdrift/kumiko-bundled-features/seo";
 import { createStepDispatcherFeature } from "@cosmicdrift/kumiko-bundled-features/step-dispatcher";
-import { createSubscriptionDodoFeature } from "@cosmicdrift/kumiko-bundled-features/subscription-dodo";
 import { createSubscriptionMollieFeature } from "@cosmicdrift/kumiko-bundled-features/subscription-mollie";
+import { createSubscriptionPaddleFeature } from "@cosmicdrift/kumiko-bundled-features/subscription-paddle";
 import { createSubscriptionStripeFeature } from "@cosmicdrift/kumiko-bundled-features/subscription-stripe";
 import { createTagsFeature } from "@cosmicdrift/kumiko-bundled-features/tags";
 import { createTemplateResolverFeature } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
@@ -212,10 +212,12 @@ export const APP_FEATURES = [
     webhookSecret: "whsec_smoke",
     priceToTier: { price_smoke: "free" },
   }),
-  createSubscriptionDodoFeature({
-    apiKey: "dodo_smoke",
-    webhookSecret: "whsec_smoke",
-    priceToTier: { pdt_smoke: "free" },
+  createSubscriptionPaddleFeature({
+    apiKey: "paddle_smoke",
+    webhookSecret: "pdl_ntfset_smoke",
+    tenantBindingKey: "paddle_smoke_binding_key",
+    clientToken: "test_smoke_client_token",
+    priceToTier: { pri_smoke: "free" },
   }),
   createSubscriptionMollieFeature({
     apiKey: "test_smoke_key",

package/samples/recipes/cross-feature-events/README.md

@@ -26,6 +26,13 @@ Three building blocks:
   external system). With `table`, the apply materializes a persistent
   read model.
 
+- **`r.job(name, { trigger: { on: event.name, catchUp: true } }, run)`**
+  runs a job per stored event. With `catchUp` the job owns its own
+  consumer cursor (`job:<jobQn>`) that starts at the beginning of the
+  event store, so a job added to a running app also processes the
+  events from before its deploy. Each event enqueues at most one run.
+  Without `catchUp` a job only sees events appended after it went live.
+
 ## Flow
 
 ```
@@ -61,3 +68,6 @@ The integration test pins three guarantees:
 ```bash
 bun kumiko test integration samples/cross-feature-events
 ```
+4. **Catch-up job** — `catch-up-job.integration.test.ts` places orders
+   before the first dispatcher pass and checks that the `catchUp` job
+   invoices each of them exactly once.

package/samples/recipes/cross-feature-events/src/feature.ts

@@ -60,6 +60,7 @@ export type CapturedEvent = {
   readonly tenantId: string;
 };
 export const capturedEvents: CapturedEvent[] = [];
+export const invoicedOrderIds: string[] = [];
 
 // --- Feature ---
 
@@ -103,6 +104,19 @@ export const pubsubOrderFeature = defineFeature("pubsubOrders", (r) => {
     access: { roles: ["Admin", "Customer"] },
   });
 
+  // A job can react to the same event. `catchUp: true` gives the job its own
+  // consumer cursor that starts at the beginning of the event store, so a job
+  // added to a running app also processes the orders placed before it existed.
+  // Without catchUp the job only sees events appended after its deploy.
+  r.job(
+    "invoice-order",
+    { trigger: { on: orderPlaced.name, catchUp: true }, runIn: "worker" },
+    async (payload) => {
+      const order = orderPlaced.schema.parse(payload);
+      invoicedOrderIds.push(order.id);
+    },
+  );
+
   // Async consumer — Marten-style. Fires after commit, via the event-
   // dispatcher. No `table` means this MSP is pure side-effect (no state
   // persisted). Delivery is at-least-once and ordered per consumer.

package/samples/recipes/dashboard-stats/README.md

@@ -20,6 +20,14 @@ query and the fields to read, the query does the counting.
   `list` with `filter`, `limit: 1` and `totalCount: true`. The total is counted
   over the whole WHERE clause, so no rows are loaded just to be counted.
 - **Labels are translation keys**: declared with `r.translations`.
+- **Record-bound dashboard**: `ticket-record-dashboard` binds to a record with `record`
+  and embeds the `ticket-card` projectionDetail as a screen panel; the record id
+  becomes its entityId.
+- **Gated toolbar button**: `visibleWhen` on a toolbar action asks a flat
+  capability query; the button is hidden while it loads or fails.
+- **Fallback by reason**: `fallback: { forbidden, notFound }` renders a screen on
+  403/404 of the gate query; other reasons get the default notice or an error
+  banner with retry.
 
 ## When to reach for it
 

package/samples/recipes/dashboard-stats/src/feature.ts

@@ -1,6 +1,8 @@
 // Dashboard Stats Sample
 // Shows: a dashboard screen with a stat-group and a single stat, backed by one
-// query handler that counts in the database.
+// query handler that counts in the database. A second, record-bound dashboard embeds a
+// projectionDetail as a panel, hides a toolbar button behind a capability query, and picks its
+// fallback screen by the reason the gate closed.
 
 import {
   createEntity,
@@ -22,6 +24,7 @@ export const ticketEntity = createEntity({
 });
 
 export const TICKET_STATS_QUERY = "tickets:query:ticket:stats";
+export const TICKET_CAPABILITIES_QUERY = "tickets:query:ticket:capabilities";
 
 const readerRoles = { roles: ["Admin", "User"] } as const;
 
@@ -57,8 +60,51 @@ export const ticketFeature = defineFeature("tickets", (r) => {
     access: readerRoles,
   });
 
+  // Gate for the screens below: a flat answer with one boolean the screens test with `eq`.
+  r.queryHandler({
+    name: "ticket:capabilities",
+    schema: z.object({}),
+    outputSchema: z.object({ canClose: z.boolean() }),
+    handler: async (query) => ({ canClose: query.user.roles.includes("Admin") }),
+    access: readerRoles,
+  });
+
+  r.queryHandler({
+    name: "ticket:card",
+    schema: z.object({ id: z.string() }),
+    handler: async (query, ctx) => {
+      const page = await ticketExecutor.list(
+        { filter: { field: "id", op: "eq", value: query.payload.id }, limit: 1 },
+        query.user,
+        ctx.db,
+      );
+      const ticket = page.rows[0];
+      return { id: query.payload.id, title: ticket?.title ?? "", status: ticket?.status ?? "" };
+    },
+    access: readerRoles,
+  });
+
+  r.queryHandler({
+    name: "ticket:rows",
+    schema: z.object({}),
+    handler: async (query, ctx) => {
+      const page = await ticketExecutor.list({ limit: 50 }, query.user, ctx.db);
+      return { rows: page.rows, nextCursor: null };
+    },
+    access: readerRoles,
+  });
+
   r.translations({
     keys: {
+      "screen:ticket-list.title": { en: "Tickets" },
+      "screen:ticket-card.title": { en: "Ticket" },
+      "screen:ticket-record-dashboard.title": { en: "Ticket overview" },
+      "entity:ticket:field:title": { en: "Title" },
+      "entity:ticket:field:status": { en: "Status" },
+      "entity:__projection-detail__:field:title": { en: "Title" },
+      "entity:__projection-detail__:field:status": { en: "Status" },
+      "tickets.toolbar.close": { en: "Close all done" },
+      "tickets.dashboard.card": { en: "Ticket" },
       "tickets.dashboard.group": { en: "Tickets by status" },
       "tickets.dashboard.open": { en: "Open" },
       "tickets.dashboard.closed": { en: "Closed" },
@@ -101,4 +147,48 @@ export const ticketFeature = defineFeature("tickets", (r) => {
     ],
     access: readerRoles,
   });
+
+  // Three additions: a projectionDetail embedded in a record-bound dashboard, a gated toolbar
+  // button, and a fallback chosen by reason.
+  const gate = { query: TICKET_CAPABILITIES_QUERY, field: "canClose", eq: true } as const;
+
+  // The list doubles as the fallback target: it has no visibleWhen of its own.
+  r.screen({
+    id: "ticket-list",
+    type: "projectionList",
+    query: "tickets:query:ticket:rows",
+    columns: ["title", "status"],
+    access: readerRoles,
+    toolbarActions: [
+      {
+        kind: "writeHandler",
+        id: "close-done",
+        label: "tickets.toolbar.close",
+        handler: "tickets:write:ticket:update",
+        // Live and fail-closed: hidden while the query loads and when it fails.
+        visibleWhen: gate,
+      },
+    ],
+  });
+
+  r.screen({
+    id: "ticket-card",
+    type: "projectionDetail",
+    query: "tickets:query:ticket:card",
+    layout: { sections: [{ title: "tickets.dashboard.card", fields: ["title", "status"] }] },
+    access: readerRoles,
+    visibleWhen: gate,
+    // 403 and 404 on the gate query get their own screen; an unmet condition keeps the
+    // default notice and any other failure shows an error banner with retry.
+    fallback: { forbidden: "ticket-list", notFound: "ticket-list" },
+  });
+
+  // `record` reads the id from the URL; the embedded projectionDetail receives it as its entityId.
+  r.screen({
+    id: "ticket-record-dashboard",
+    type: "dashboard",
+    record: { param: "ticketId", payloadKey: "id" },
+    panels: [{ kind: "screen", id: "card", screen: "ticket-card" }],
+    access: readerRoles,
+  });
 });

package/samples/recipes/env-composition/README.md

@@ -10,7 +10,7 @@ instead of keeping a hand-written copy of every feature's variables.
   `kmsEnvSchema` and `s3EnvSchema`. `composeEnvSchema` collects them and
   records which feature declared each variable.
 - **App-level blocks in `extend`**: `buildInfoEnvSchema`, `demoAdminEnvSchema`,
-  `stripeEnvSchema({ prices })`, `dodoEnvSchema({ prices })` and
+  `stripeEnvSchema({ prices })`, `paddleEnvSchema({ prices })` and
   `createS3EnvSchema({ prefix })` for a
   second bucket. These belong to no mounted feature, so the app adds them.
 - **Typed result**: `parseEnv(composed.schema, …)` returns the merged type,
@@ -27,7 +27,7 @@ instead of keeping a hand-written copy of every feature's variables.
 | `smtpEnvSchema` | `channel-email` | `createChannelEmailFeature()` |
 | `s3EnvSchema`, `createS3EnvSchema({ prefix })` | `file-provider-s3` | `createFileProviderS3Feature({ fromEnv: true })` |
 | `stripeEnvSchema({ prices })` | `subscription-stripe` | app (`extend`); the feature registers the bridge keys |
-| `dodoEnvSchema({ prices })` | `subscription-dodo` | app (`extend`); the feature registers the bridge keys |
+| `paddleEnvSchema({ prices })` | `subscription-paddle` | app (`extend`); the feature registers the bridge keys |
 | `mfaTokenSecretsEnvSchema` | `auth-mfa` | `createAuthMfaFeature()` |
 | `buildInfoEnvSchema`, `demoAdminEnvSchema` | `foundation-shared` | app (`extend`) |
 | `prometheusMetricsEnvSchema` | `framework/observability` | app (`extend`) |

package/samples/recipes/env-composition/src/env.ts

@@ -15,7 +15,7 @@ import {
   demoAdminEnvSchema,
 } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
 import { createSecretsFeature } from "@cosmicdrift/kumiko-bundled-features/secrets";
-import { dodoEnvSchema } from "@cosmicdrift/kumiko-bundled-features/subscription-dodo";
+import { paddleEnvSchema } from "@cosmicdrift/kumiko-bundled-features/subscription-paddle";
 import { stripeEnvSchema } from "@cosmicdrift/kumiko-bundled-features/subscription-stripe";
 import { frameworkCoreEnvSchema } from "@cosmicdrift/kumiko-dev-server/env-schema";
 import { composeEnvSchema } from "@cosmicdrift/kumiko-framework/env";
@@ -37,7 +37,7 @@ const appEnvSchema = z.object({
   ...buildInfoEnvSchema.shape,
   ...demoAdminEnvSchema.shape,
   ...stripeEnvSchema({ prices: ["PRO", "TEAM"] }).shape,
-  ...dodoEnvSchema({ prices: ["PRO", "TEAM"] }).shape,
+  ...paddleEnvSchema({ prices: ["PRO", "TEAM"] }).shape,
   ...createS3EnvSchema({ prefix: "RELEASES_S3_" }).shape,
   APP_PUBLIC_URL: z.url().describe("Public origin of the app, used in mail links."),
 });