@cosmicdrift/kumiko-bundled-features 0.27.0 → 0.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/src/audit/feature.ts

@@ -15,6 +15,9 @@ import { listQuery } from "./handlers/list.query";
 // the framework).
 export function createAuditFeature(): FeatureDefinition {
   return defineFeature("audit", (r) => {
+    r.describe(
+      "Exposes the framework's event store as a paginated, filterable audit log via the `audit:query:list` handler (accessible to `Admin` and `SystemAdmin` roles). No separate table or projection \u2014 the event store is the audit trail by construction: every entity write already records who, when, what entity, and the event payload with PII stripped. Filter by `aggregateType`, `aggregateId`, `eventType`, `userId`, or time range.",
+    );
     const queries = {
       list: r.queryHandler(listQuery),
     };

package/src/auth-email-password/feature.ts

@@ -125,6 +125,9 @@ export function createAuthEmailPasswordFeature(
     opts.emailVerification !== undefined && (opts.emailVerification.mode ?? "strict") === "strict";
 
   return defineFeature("auth-email-password", (r) => {
+    r.describe(
+      "Provides email+password authentication: the always-on handlers are `login`, `changePassword`, and `logout`; optional flows \u2014 password reset, email verification, magic-link self-signup, and tenant invite \u2014 are registered only when you pass their respective option objects (`passwordReset`, `emailVerification`, `signup`, `invite`) to `createAuthEmailPasswordFeature(opts)`. Each opt-in flow uses HMAC-signed or opaque-random tokens delivered via callback (e.g. `sendResetEmail`) so the feature stays transport-agnostic. Requires the `user` and `tenant` features, and declares `JWT_SECRET` (\u2265 32 chars) in `authEmailPasswordEnvSchema` so a missing secret surfaces at boot validation rather than on the first login attempt.",
+    );
     r.requires("user");
     r.requires("tenant");
     r.envSchema(authEmailPasswordEnvSchema);

package/src/billing-foundation/feature.ts

@@ -71,6 +71,9 @@ import {
 } from "./projection";
 
 export const billingFoundationFeature = defineFeature(BILLING_FOUNDATION_FEATURE, (r) => {
+  r.describe(
+    "Plugin host for subscription billing \u2014 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 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 `createSubscriptionWebhookHandler` factory for the `/api/subscription/webhook/:providerName` route. Low-level building block \u2014 use `subscription-stripe` or `subscription-mollie` unless you are writing a new payment provider.",
+  );
   // 5 fine-grained domain-events. Alle 5 nutzen denselben payload-
   // shape (= subscription-state-snapshot); der event-type taggt was
   // passiert ist. Future-consumer (billing-history, accounting)

package/src/billing-foundation/webhook-handler.ts

@@ -7,12 +7,20 @@
 // `/api/subscription/webhook/paypal`. Eine Hono-Route, alle Plugins
 // gleichzeitig aktiv.
 //
-// Beispiel-Verwendung in bin/server.ts:
+// Beispiel-Verwendung in bin/server.ts (runDevApp wie runProdApp liefern
+// `registry` + `dispatchSystemWrite` in den extraRoutes-deps):
 //
 //   await runDevApp({
 //     features: APP_FEATURES,
 //     extraRoutes: (app, deps) => {
-//       const handler = createSubscriptionWebhookHandler(deps);
+//       const handler = createSubscriptionWebhookHandler({
+//         dispatchWrite: ({ handlerQn, payload, tenantId }) =>
+//           deps.dispatchSystemWrite({ handlerQn, payload, tenantId: tenantId as TenantId }),
+//         resolveProvider: (name) =>
+//           deps.registry.getExtensionUsages("subscriptionProvider")
+//             .find((u) => u.entityName === name)?.options as
+//             SubscriptionProviderPlugin | undefined,
+//       });
 //       app.post("/api/subscription/webhook/:providerName", handler);
 //     },
 //   });
@@ -43,8 +51,9 @@ import {
 import type { SubscriptionProviderPlugin } from "./types";
 
 /**
- * Dependencies the App-Owner gibt dem webhook-handler. Identisch zum
- * `extraRoutes`-Callback-Argument-shape von runDevApp/runProdApp.
+ * Dependencies the App-Owner gibt dem webhook-handler — beide direkt aus
+ * den `extraRoutes`-deps ableitbar (`dispatchSystemWrite` + `registry`),
+ * siehe Beispiel im Header.
  */
 export type SubscriptionWebhookDeps = {
   /** Schreibt durch den Standard-Dispatcher mit einem auto-konstruierten

package/src/cap-counter/feature.ts

@@ -60,6 +60,9 @@ import { markSoftWarnedHandler } from "./handlers/mark-soft-warned.write";
 const sysadminAccess = { access: { roles: ["SystemAdmin"] } } as const;
 
 export const capCounterFeature = defineFeature(CAP_COUNTER_FEATURE, (r) => {
+  r.describe(
+    "Tracks per-tenant usage against configurable limits using two complementary storage models: calendar-period counters (one projection row per tenant/capName/period, reset implicitly by period rollover) and rolling-window counters (append-only event stream, no projection). Use `enforceCap` / `enforceRollingCap` (or the `withCapEnforcement` / `withRollingCapEnforcement` handler wrappers) in your write-handlers to check limits with soft-warn and hard-block tolerances; call `enforceCapAndMaybeNotify` when you also want to trigger a delivery notification on soft-threshold hits.",
+  );
   r.entity("cap-counter", capCounterEntity);
 
   // Custom Domain-Event für Rolling-Counter. r.defineEvent registriert

package/src/channel-email/feature.ts

@@ -5,6 +5,9 @@ export function createChannelEmailFeature(options: EmailChannelOptions): Feature
   const channel = createEmailChannel(options);
 
   return defineFeature("channel-email", (r) => {
+    r.describe(
+      "Wires an `EmailTransport` (typically `mail-transport-smtp` in production, `createInMemoryTransport()` in tests) into the delivery system as the `email` channel. Requires `delivery`; pass an `EmailChannelOptions` with a `transport`, a `renderer: NotificationRenderer` (e.g. backed by `renderer-simple`), and a `resolveEmail` function that maps a user ID to their email address.",
+    );
     r.requires("delivery");
 
     r.useExtension("deliveryChannel", "email", {

package/src/channel-in-app/feature.ts

@@ -7,6 +7,9 @@ import { inAppChannel } from "./in-app-channel";
 
 export function createChannelInAppFeature(): FeatureDefinition {
   return defineFeature("channel-in-app", (r) => {
+    r.describe(
+      "Persists notifications to an in-app inbox table so users can retrieve them via `handlers.inbox` and track unread state with `handlers.markRead` / `handlers.markAllRead` and `queries.unreadCount`. Requires `delivery`; no external service needed \u2014 messages are stored in the app's own database.",
+    );
     r.requires("delivery");
 
     // Register as delivery channel via extension system

package/src/channel-push/feature.ts

@@ -5,6 +5,9 @@ export function createChannelPushFeature(options: PushChannelOptions): FeatureDe
   const channel = createPushChannel(options);
 
   return defineFeature("channel-push", (r) => {
+    r.describe(
+      "Delivers push notifications through a `PushTransport` (bring your own FCM/APNs adapter or use `createInMemoryPushTransport()` for tests) registered as the `push` channel in the delivery system. Requires `delivery`; supply a `PushChannelOptions` with a transport and a resolver that maps a user ID to their device token.",
+    );
     r.requires("delivery");
 
     r.useExtension("deliveryChannel", "push", {

package/src/compliance-profiles/feature.ts

@@ -27,6 +27,9 @@ export {
 // Begruendung in schema/profile-selection.ts.
 export function createComplianceProfilesFeature(): FeatureDefinition {
   return defineFeature("compliance-profiles", (r) => {
+    r.describe(
+      "Lets each tenant select a compliance regime (e.g. `eu-dsgvo`, `swiss-dsg`, `de-hr-dsgvo-hgb`) that bundles user-rights grace periods, breach-disclosure deadlines, sub-processor requirements, and audit-retention rules into a single named profile. Tenant admins call `compliance-profiles:write:set-profile` to choose a profile (with optional JSON override for edge cases); other features resolve the effective profile via the `compliance.forTenant` cross-feature API. Required by `user-data-rights` \u2014 mount this feature before it.",
+    );
     // Standalone — kein r.requires noetig: tenantId kommt aus dem User-
     // Context, Profile-Selection ist eigene Entity, sub-processor-Liste
     // sind Constants. Wenn S1.4+ Cross-Feature-Reads dazukommen, kommt

package/src/config/feature.ts

@@ -24,6 +24,9 @@ export type ConfigContext = { readonly config: ConfigAccessor };
 
 export function createConfigFeature(): FeatureDefinition {
   return defineFeature("config", (r) => {
+    r.describe(
+      "Stores per-tenant (and optionally per-user) configuration values with a multi-layer cascade: user-row \u2192 tenant-row \u2192 system-row \u2192 app-override (deploy-time `AppConfigOverrides`) \u2192 computed \u2192 feature default. Access a value in handlers via `ctx.config(handle)`, declare keys with `r.config({ keys: { ... } })` inside a feature's registry callback, and optionally mark them `encrypted: true` to route storage through an `EncryptionProvider`. Use this feature whenever a tenant admin needs to customise behaviour at runtime without a code deploy.",
+    );
     r.systemScope();
 
     // One aggregate stream per (key, scope) pair — the executor handles the

package/src/custom-fields/feature.ts

@@ -84,6 +84,9 @@ function registerCustomFields(
   r: FeatureRegistrar<typeof CUSTOM_FIELDS_FEATURE_NAME>,
   defineTenantHandler: WriteHandlerDef,
 ) {
+  r.describe(
+    "Tenant- and system-scoped custom field definitions with generic value storage on any host entity. Registers the `field-definition` entity (event-sourced CRUD via `define-tenant-field`, `define-system-field`, `delete-tenant-field`, `delete-system-field`) and two value write-handlers (`set-custom-field`, `clear-custom-field`) that emit `custom-fields:event:custom-field-set` / `custom-fields:event:custom-field-cleared` events on the host aggregate's stream. To attach custom fields to your own entity, call `wireCustomFieldsFor(r, entityName, entityTable)` in the host feature — this wires the JSONB projection, `postQuery` flattening hook, and search-payload extension. The host entity must declare a `customFieldsField()` JSONB column.",
+  );
   r.entity("field-definition", fieldDefinitionEntity);
 
   // Event-types — qualified als "custom-fields:event:<short-name>".

package/src/data-retention/feature.ts

@@ -44,6 +44,9 @@ export {
 // pflicht. Das Wiring kommt in Sprint 2.U5.
 export function createDataRetentionFeature(): FeatureDefinition {
   return defineFeature("data-retention", (r) => {
+    r.describe(
+      "Resolves the effective retention policy for any entity using a 3-layer stack: entity-level default \u2192 tenant preset (`dsgvo-basic`, `dsgvo-hgb`, `swiss-dsg`) \u2192 per-tenant override stored in `tenantRetentionOverride`. Other features query the resolved policy via the `retention.policyFor` cross-feature API \u2014 most notably `user-data-rights`, which uses it to decide whether to anonymize instead of hard-delete a record that is still within a mandatory retention window.",
+    );
     r.entity("tenant-retention-override", tenantRetentionOverrideEntity);
 
     // S2.D3: Cross-Feature-API fuer Forget-Flow + Cleanup-Job

package/src/delivery/feature.ts

@@ -14,6 +14,9 @@ import {
 
 export function createDeliveryFeature(): FeatureDefinition {
   return defineFeature("delivery", (r) => {
+    r.describe(
+      "The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). It stores per-user channel preferences in the `notification-preference` entity, logs every attempt to `read_delivery_attempts`, and enforces idempotency and rate-limiting \u2014 add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything.",
+    );
     r.systemScope();
     r.entity("notification-preference", notificationPreferenceEntity);
     r.unmanagedTable(deliveryAttemptsTableMeta, {

package/src/feature-toggles/feature.ts

@@ -37,6 +37,9 @@ export function createFeatureTogglesFeature(
   options: FeatureTogglesOptions = {},
 ): FeatureDefinition {
   return defineFeature("feature-toggles", (r) => {
+    r.describe(
+      'Persists per-feature enabled/disabled state in the `read_global_feature_state` table and exposes a `set` write-handler plus `list`/`registered` query-handlers so operators can flip features at runtime without redeploying. Each API instance keeps an in-memory `GlobalFeatureToggleRuntime` snapshot (initialize it via `createFeatureToggleRuntime`, pass a `() => runtime` accessor to `createFeatureTogglesFeature`) that the dispatcher gate reads on every request; a `toggle-cache-sync` multi-stream projection with `delivery: "per-instance"` syncs the snapshot across instances whenever a `toggle-set` event is appended.',
+    );
     r.systemScope();
 
     // Toggle-change domain event. The event ends up in the events-table

package/src/file-foundation/feature.ts

@@ -90,6 +90,9 @@ export type FileProviderPlugin = {
 // =============================================================================
 
 export const fileFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
+  r.describe(
+    "Defines the `fileProvider` extension point and a per-tenant `provider` config key that selects which registered storage plugin to use at runtime. Call `createFileProviderForTenant(ctx, tenantId)` to get a `FileStorageProvider` \u2014 use this feature together with at least one `file-provider-*` feature; the `files` feature builds on top of it for tracked `FileRef` entities with GDPR hooks.",
+  );
   r.requires("config");
 
   r.extendsRegistrar("fileProvider", {

package/src/file-provider-inmemory/feature.ts

@@ -60,6 +60,9 @@ export function clearStorage(tenantId: string): void {
 // =============================================================================
 
 export const fileProviderInMemoryFeature = defineFeature(FEATURE_NAME, (r) => {
+  r.describe(
+    'Registers an in-process `"inmemory"` provider for `file-foundation` that stores file bytes per tenant in a module-level Map. Use `listKeys(tenantId)` and `clearStorage(tenantId)` in demo apps and tests; not for production (data is lost on restart and grows without bound).',
+  );
   // Kein r.requires("config") + kein r.requires("secrets") — der
   // In-Memory-Provider hat keine Config + kein Secret. Nur die
   // file-foundation muss da sein (Plugin-extension-point).

package/src/file-provider-s3/feature.ts

@@ -38,6 +38,9 @@ const FEATURE_NAME = "file-provider-s3";
 // =============================================================================
 
 export const fileProviderS3Feature = defineFeature(FEATURE_NAME, (r) => {
+  r.describe(
+    'Registers itself as the `"s3"` provider for `file-foundation` and owns the per-tenant config keys (`bucket`, `region`, `endpoint`, `forcePathStyle`, `accessKeyId`) and the encrypted `s3.secretAccessKey` secret. Compatible with any S3-compatible object store (AWS S3, Hetzner Object Storage); set credentials via the admin UI or a seed handler before the first file operation.',
+  );
   r.requires("config");
   r.requires("secrets");
   r.requires("file-foundation");

package/src/jobs/feature.ts

@@ -23,6 +23,9 @@ import { jobRunLogsTable, jobRunLogsTableMeta, jobRunsTable } from "./job-run-ta
 
 export function createJobsFeature(): FeatureDefinition {
   return defineFeature("jobs", (r) => {
+    r.describe(
+      "Persistence and operator tooling for background jobs registered via `r.job(...)`. Every job execution appends `run-started`, `run-completed`, and `run-failed` events to the `jobRun` aggregate stream, which two inline projections materialize into `read_job_runs` (current status + duration) and `read_job_run_logs` (per-line log rows). Exposes `jobs:write:trigger` (manual run) and `jobs:write:retry` (operator retry of a failed run), plus `jobs:query:list` and `jobs:query:details` for the operator UI.",
+    );
     r.systemScope();
     r.unmanagedTable(jobRunLogsTableMeta, {
       reason: "read_side.job_run_logs",

package/src/legal-pages/feature.ts

@@ -60,6 +60,9 @@ export type LegalPagesOptions = {
 export function createLegalPagesFeature(opts: LegalPagesOptions = {}): FeatureDefinition {
   const wrapLayout = opts.wrapLayout ?? wrapInLayout;
   return defineFeature("legal-pages", (r) => {
+    r.describe(
+      "Opt-in wrapper around `text-content` that registers four public HTML routes (`/legal/impressum`, `/legal/datenschutz`, `/legal/imprint`, `/legal/privacy`) with Markdown-to-HTML rendering and a boot-time job that hard-fails in production when the required DE blocks (`imprint/de`, `privacy/de`) are not seeded in `SYSTEM_TENANT`. Requires `anonymousAccess: { defaultTenantId: SYSTEM_TENANT_ID }` and `extraContext.textContent` to be wired at app bootstrap; for per-tenant imprints or a custom layout call `text-content:query:by-slug` directly.",
+    );
     r.requires("text-content");
 
     // 4 Public-HTML-Routes

package/src/mail-foundation/feature.ts

@@ -65,6 +65,9 @@ export type MailTransportPlugin = {
 // =============================================================================
 
 export const mailFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
+  r.describe(
+    "Defines the `mailTransport` extension point and a per-tenant `provider` config key that selects which registered transport plugin to use at runtime. Call `createTransportForTenant(ctx, tenantId)` to get an `EmailTransport` ready for sending \u2014 use this feature together with at least one `mail-transport-*` feature; use `delivery` + `channel-email` instead when you need the full notification pipeline with delivery attempts and user preferences.",
+  );
   r.requires("config");
 
   // Plugin extension-point. Provider-features register here. The

package/src/mail-transport-inmemory/feature.ts

@@ -73,6 +73,9 @@ export function clearInbox(tenantId: string): void {
 // =============================================================================
 
 export const mailTransportInMemoryFeature = defineFeature(FEATURE_NAME, (r) => {
+  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 r.requires("config") + kein r.requires("secrets") — der
   // In-Memory-Transport hat keine Config (nichts zu konfigurieren) und
   // kein Secret. Der einzige hard-require ist mail-foundation, das den

package/src/mail-transport-smtp/feature.ts

@@ -49,6 +49,9 @@ const FEATURE_NAME = "mail-transport-smtp";
 // =============================================================================
 
 export const mailTransportSmtpFeature = defineFeature(FEATURE_NAME, (r) => {
+  r.describe(
+    'Registers itself as the `"smtp"` provider for `mail-foundation` and owns the per-tenant config keys (`host`, `port`, `secure`, `from`, `authUser`) and the encrypted `smtp.password` secret. Tenants set `mail-foundation`\'s `provider` config key to `"smtp"` to activate it; set the SMTP credentials via the admin UI or a seed handler before sending the first mail.',
+  );
   r.requires("config");
   r.requires("secrets");
   r.requires("mail-foundation");

package/src/rate-limiting/feature.ts

@@ -11,6 +11,9 @@ import { rateLimitStatus } from "./handlers/status.query";
 // skip this feature entirely — the resolver still runs.
 export function createRateLimitingFeature() {
   return defineFeature("rate-limiting", (r) => {
+    r.describe(
+      "Adds an ops-side `rate-limiting:query:status` query handler for inspecting current bucket state; the actual request throttling is wired automatically by the dispatcher when any handler declares a `rateLimit` option (e.g. `{ per: 'user', limit: 3, windowSeconds: 60 }`) or when you pass `context.rateLimit` to `buildServer`. Loading this feature is optional if you only need L3 per-handler rate limits and have no need for ops introspection.",
+    );
     r.queryHandler(rateLimitStatus);
   });
 }

package/src/renderer-foundation/feature.ts

@@ -11,6 +11,9 @@ import type { RendererPlugin } from "./types";
 // Konsumenten holen sich Plugin runtime via createRendererForTenant.
 export function createRendererFoundationFeature() {
   return defineFeature("renderer-foundation", (r) => {
+    r.describe(
+      'Plugin registry for content rendering (notification HTML, mail HTML, PDF, images): call `foundation.createRendererForTenant({ tenantId, kind })` at render time to get the right renderer plugin selected by kind, with tenant-level overrides via the `rendererPluginByKind` config key. Requires `template-resolver` (declared via `r.requires`). Low-level building block \u2014 add `renderer-simple` (or write a custom plugin via `r.useExtension("renderer", name, { kinds, render })`) rather than using this feature alone.',
+    );
     r.requires("template-resolver");
 
     r.extendsRegistrar("renderer", {

package/src/renderer-simple/feature.ts

@@ -27,6 +27,9 @@ export async function adaptToFoundation(req: RenderRequest): Promise<RenderRespo
 
 export function createRendererSimpleFeature(): FeatureDefinition {
   return defineFeature("renderer-simple", (r) => {
+    r.describe(
+      'Default renderer plugin for `kind="notification"`: takes a structured `EmailTemplateData` variable map (with `header`, `sections[]` of text/button objects, and optional `footer`; falls back to `title`/`body` if no structured fields are present) and returns rendered HTML with inline CSS. Requires `renderer-foundation`; sufficient for plain notification emails \u2014 swap it for `renderer-mail-html` if you need MJML/Markdown layouts.',
+    );
     r.requires("renderer-foundation");
 
     r.useExtension("renderer", "simple", {

package/src/secrets/feature.ts

@@ -82,6 +82,9 @@ export function requireSecretsContext(
 
 export function createSecretsFeature(): FeatureDefinition {
   return defineFeature("secrets", (r) => {
+    r.describe(
+      "Stores arbitrary per-tenant secrets (API keys, tokens, credentials) encrypted at rest using AES-256 with a KEK loaded from `KUMIKO_SECRETS_MASTER_KEY_V1` (and successive versions for rotation). Read a secret in handlers via `ctx.secrets.get(tenantId, handle)`, which automatically appends a `tenantSecretRead` audit event so every access is traceable. A `rotate` job re-encrypts all envelopes after a KEK version bump.",
+    );
     r.envSchema(secretsEnvSchema);
 
     // ES entity: set/delete go through the executor, `tenantSecret.created/

package/src/sessions/feature.ts

@@ -38,6 +38,9 @@ export type SessionsFeatureOptions = {
 // see rows in the caller's active tenant.
 export function createSessionsFeature(options?: SessionsFeatureOptions): FeatureDefinition {
   return defineFeature("sessions", (r) => {
+    r.describe(
+      "Tracks signed-in clients in the `read_user_sessions` table (one row per JWT, keyed by the `sid`/`jti` claim) and exposes handlers for `mine` (list your sessions), `revoke`, and `revokeAllOthers`. Session creation and revocation on the hot auth path are handled by `createSessionCallbacks()`, wired into `buildServer({ auth: { ... } })` outside the dispatcher; the feature also ships a manual-trigger cleanup job for pruning expired rows and an optional `autoRevokeOnPasswordChange` hook that mass-revokes all sessions for a user whenever their `passwordHash` changes.",
+    );
     r.entity("user-session", userSessionEntity);
 
     const handlers = {

package/src/step-dispatcher/feature.ts

@@ -29,6 +29,9 @@ type DispatchRequestedPayload =
 
 export function createStepDispatcherFeature(): FeatureDefinition {
   return defineFeature("step-dispatcher", (r) => {
+    r.describe(
+      "Internal system feature that drains deferred Tier-2 side-effects (currently `webhook.send` and `mail.send`) after their originating transaction commits. Listens via `r.multiStreamProjection` on the `kumiko:system:step.dispatch-requested` system event, performs the actual HTTP or mail delivery, then appends `kumiko:system:step.dispatched` or `kumiko:system:step.dispatch-failed` back onto the same stream so the outcome is recorded in the event log without a separate status table. Mount this feature explicitly via `createStepDispatcherFeature()` in your app's feature list alongside any features that use `r.step.webhook.send` or `r.step.mail.send`.",
+    );
     r.systemScope();
 
     r.multiStreamProjection({

package/src/subscription-mollie/feature.ts

@@ -146,6 +146,9 @@ export function createSubscriptionMollieFeature(
   );
 
   return defineFeature(SUBSCRIPTION_MOLLIE_FEATURE, (r) => {
+    r.describe(
+      'Mollie payment provider plugin for `billing-foundation`, covering the DACH/EU mid-market use case. Mount via `createSubscriptionMollieFeature({ apiKey, webhookUrl, priceToTier, priceToConfig })` \u2014 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.',
+    );
     r.requires("billing-foundation");
     r.envSchema(subscriptionMollieEnvSchema);
 

package/src/subscription-stripe/feature.ts

@@ -124,6 +124,9 @@ export function createSubscriptionStripeFeature(
   const cancel = createStripeCancelSubscription(stripe);
 
   return defineFeature(SUBSCRIPTION_STRIPE_FEATURE, (r) => {
+    r.describe(
+      "Stripe payment provider plugin for `billing-foundation`. Mount via `createSubscriptionStripeFeature({ webhookSecret, apiKey, priceToTier })` \u2014 a factory function that holds the app-wide credentials in a closure for use before tenant resolution. Implements all four provider methods: `verifyAndParseWebhook` (HMAC signature verification), `createCheckoutSession`, `createPortalSession`, and `cancelSubscription`. The `priceToTier` map connects Stripe price IDs to your tier names.",
+    );
     // Hard-deps: subscription-foundation als plugin-host. KEIN
     // `r.requires("config", "secrets")` — der Plugin nutzt weder
     // tenant-config noch tenant-secrets (alles app-wide via factory-

package/src/template-resolver/feature.ts

@@ -17,6 +17,9 @@ import { templateResourceEntity } from "./table";
 //   - Cross-Feature: requireTemplateResolver(ctx, callerName) — Pattern wie requireTextContent
 export function createTemplateResolverFeature() {
   return defineFeature("template-resolver", (r) => {
+    r.describe(
+      "Stores notification and mail templates in the database with a 4-level fallback: tenant+locale \u2192 system+locale \u2192 tenant+fallback-locale \u2192 system+fallback-locale. Call `ctx.templateResolver.resolveTemplate({ tenantId, slug, kind, locale })` at render time; manage templates via the `upsertSystem`, `upsertTenant`, `publish`, and `archive` write handlers. Tenants can override system-default templates without touching application code.",
+    );
     r.entity("template-resource", templateResourceEntity);
 
     const handlers = {

package/src/tenant/feature.ts

@@ -29,6 +29,9 @@ export { tenantEntity, tenantTable } from "./schema/tenant";
 
 export function createTenantFeature(): FeatureDefinition {
   return defineFeature("tenant", (r) => {
+    r.describe(
+      "Registers the three core multi-tenancy entities \u2014 `tenant`, `tenant-membership`, and `tenant-invitation` (DB tables `read_tenants`, `read_tenant_memberships`, and `read_tenant_invitations`) \u2014 along with write handlers for create/update/disable/addMember/removeMember/updateMemberRoles and the matching queries. It also declares a set of per-tenant config keys (companyName, timezone, locale, SMTP credentials) and system-only keys (priceModel, maxUsers) via `r.config({ keys: { ... } })`. Use this feature in every multi-tenant app; membership resolution and invitation flows depend on it, and `auth-email-password` requires it.",
+    );
     r.systemScope();
     r.requires("config");
     r.entity("tenant", tenantEntity);

package/src/text-content/feature.ts

@@ -23,6 +23,9 @@ import { textBlockEntity } from "./table";
 // Target nutzt. Der Client-side TreeProvider lebt in `web/client-plugin.ts`.
 export function createTextContentFeature() {
   return defineFeature("text-content", (r) => {
+    r.describe(
+      "Generic Markdown text store keyed by `(tenantId, slug, lang)` \u2014 one row per combination in the `read_text_blocks` entity table. Provides `text-content:write:set` (TenantAdmin upsert) and `text-content:query:by-slug` (anonymous-capable read); use `SYSTEM_TENANT_ID` as the tenant for app-wide texts such as imprint, privacy policy, or FAQ. Other features (e.g. `legal-pages`) read blocks without a direct code import via the `createTextContentApi` / `requireTextContent` extraContext pattern.",
+    );
     r.entity("text-block", textBlockEntity);
 
     const handlers = {

package/src/tier-engine/feature.ts

@@ -167,6 +167,9 @@ export function createTierEngineFeature<
   TCaps extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>,
 >(opts: CreateTierEngineOptions<TCaps> = {}): FeatureDefinition {
   return defineFeature(TIER_ENGINE_FEATURE, (r) => {
+    r.describe(
+      "Stores a `tier-assignment` entity per tenant (which pricing tier is active) and, when configured with a `TierMap`, registers itself as the `tenantTierResolver` extension so the dispatcher automatically gates `r.toggleable()` features per tenant based on their assigned tier. Call `createTierEngineFeature({ defaultTier, tierMap })` to get full tier composition \u2014 including an `inTransaction` entity hook that atomically writes the default tier when a new tenant is created \u2014 or use `createTierEngineFeature()` without options for storage-only mode when you manage tier assignment yourself via `composeApp`.",
+    );
     r.requires("config");
     r.requires("tenant");
 

package/src/user/feature.ts

@@ -12,6 +12,9 @@ import { userEntity } from "./schema/user";
 // Membership + tenant-specific roles live in the tenant feature.
 export function createUserFeature(): FeatureDefinition {
   return defineFeature("user", (r) => {
+    r.describe(
+      "Manages the cross-tenant user identity: the `read_users` table holds each user's email, `displayName`, global `roles`, `emailVerified` flag, and lifecycle `status` (active / restricted / deletionRequested / deleted). Because users exist above any individual tenant, the feature runs with `r.systemScope()` \u2014 membership and tenant-specific roles live in the `tenant` feature instead. Add this feature whenever your app needs a persistent, tenant-agnostic user record that auth and GDPR pipelines can reference.",
+    );
     r.systemScope();
     r.entity("user", userEntity);
 

package/src/user-data-rights/feature.ts

@@ -84,6 +84,9 @@ export type UserDataRightsOptions = {
 
 export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): FeatureDefinition {
   return defineFeature("user-data-rights", (r) => {
+    r.describe(
+      'Implements GDPR Art. 15 (access / `my-audit-log` query), Art. 17 (erasure / `request-deletion` + `cancel-deletion` + cron cleanup with grace period), Art. 18 (restriction / `restrict-account` + `lift-restriction`), and Art. 20 (portability / async `request-export` \u2192 ZIP via `file-foundation`, Magic-Link download) as first-class HTTP handlers and cron jobs. Each domain feature opts in by calling `r.useExtension(EXT_USER_DATA, "<entity>", { export, delete })` \u2014 the feature then orchestrates the export and forget pipelines across all registered hooks automatically. Requires `user`, `data-retention`, `compliance-profiles`, and `sessions`.',
+    );
     r.requires("user", "data-retention", "compliance-profiles", "sessions");
     r.usesApi("compliance.forTenant");
     r.usesApi("retention.policyFor");

package/src/user-data-rights-defaults/feature.ts

@@ -39,6 +39,9 @@ export function createUserDataRightsDefaultsFeature(
 ): FeatureDefinition {
   const fileRefDeleteHook = createFileRefDeleteHook(options.storageProvider);
   return defineFeature("user-data-rights-defaults", (r) => {
+    r.describe(
+      "Registers ready-made `EXT_USER_DATA` export and delete hooks for the two core entities: `user` (delete strategy sets email to `deleted-<id>@anonymized.invalid`, nulls `passwordHash`, sets status to `Deleted`; anonymize strategy sets email to `anonymized-<id>@anonymized.invalid` without touching `passwordHash`) and `fileRef` (delete removes both the DB row and the storage binary). Mount this alongside `user-data-rights` for standard GDPR compliance; omit it only if your app needs custom anonymization logic for these entities.",
+    );
     r.requires("user", "files", "user-data-rights");
 
     r.useExtension(EXT_USER_DATA, "user", {