@cosmicdrift/kumiko-bundled-features 0.27.0 → 0.31.0

package/src/readiness/feature.ts

@@ -0,0 +1,26 @@
+// kumiko-feature-version: 1
+//
+// readiness — one-call tenant-onboarding rollup above config + secrets.
+//
+// `config:query:readiness` lists required config keys without a usable
+// value; `secrets:query:list` lists set secrets. Neither can verdict
+// "tenant is ready" alone. This feature requires both, so its status
+// query may roll up missing config + missing required secrets + a single
+// `ready` boolean — the settings-checklist call for admin UIs.
+
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { statusQuery } from "./handlers/status.query";
+
+export const readinessFeature = defineFeature("readiness", (r) => {
+  r.describe(
+    "One-call tenant-onboarding probe: `readiness:query:status` rolls up every config key and secret declared `required: true` across all mounted features and reports which still lack a usable value for the calling tenant, plus a single `ready` boolean. Provider-features under an `r.extensionSelector`-declared extension point count only while their provider is the selected one — a tenant on the inmemory mail transport is not blocked by unset SMTP keys. Mount it (together with `config` and `secrets`) when an admin UI needs a settings checklist before the first mail-send or file-write; the per-concern lists stay available via `config:query:readiness` and `secrets:query:list`.",
+  );
+  r.requires("config");
+  r.requires("secrets");
+
+  const queries = {
+    status: r.queryHandler(statusQuery),
+  };
+
+  return { queries };
+});

package/src/readiness/handlers/status.query.ts

@@ -0,0 +1,48 @@
+import {
+  buildProviderSelectionGate,
+  collectMissingRequiredConfig,
+} from "@cosmicdrift/kumiko-bundled-features/config";
+import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { ReadinessQueries } from "../constants";
+
+export type ReadinessMissingSecret = { readonly key: string };
+
+// The one-call rollup config:query:readiness deliberately refused: that
+// query can't see secrets, this feature requires both — so it may verdict.
+export const statusQuery = defineQueryHandler({
+  name: "status",
+  schema: z.object({}),
+  // Same gate as secrets:query:list — the response names missing secrets.
+  access: { roles: ["TenantAdmin"] },
+  handler: async (query, ctx) => {
+    // One gate for both halves: required keys/secrets of provider-features
+    // count only while their provider is the selected one (r.extensionSelector).
+    const gate = await buildProviderSelectionGate(ctx, ReadinessQueries.status, query.user);
+    const missingConfig = await collectMissingRequiredConfig(
+      ctx,
+      ReadinessQueries.status,
+      query.user,
+      gate,
+    );
+
+    // has() is metadata-only: no decryption, no read-audit event — a
+    // readiness probe must not pollute the credential-read trail.
+    const secrets = requireSecretsContext(ctx, ReadinessQueries.status);
+    const missingSecrets: ReadinessMissingSecret[] = [];
+    for (const [qualifiedName, keyDef] of ctx.registry.getAllSecretKeys()) {
+      if (keyDef.required !== true) continue;
+      if (!gate(qualifiedName)) continue;
+      if (!(await secrets.has(query.user.tenantId, qualifiedName))) {
+        missingSecrets.push({ key: qualifiedName });
+      }
+    }
+
+    return {
+      missingConfig,
+      missingSecrets,
+      ready: missingConfig.length === 0 && missingSecrets.length === 0,
+    };
+  },
+});

package/src/readiness/index.ts

@@ -0,0 +1,3 @@
+export { READINESS_FEATURE, ReadinessQueries } from "./constants";
+export { readinessFeature } from "./feature";
+export type { ReadinessMissingSecret } from "./handlers/status.query";

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/__tests__/require-secrets-context.test.ts

@@ -20,6 +20,7 @@ import { requireSecretsContext } from "../feature";
 function makeRawSecretsContext(): SecretsContext {
   return {
     get: mock(),
+    has: mock(),
     set: mock(),
     delete: mock(),
   };

package/src/secrets/feature.ts

@@ -75,6 +75,8 @@ export function requireSecretsContext(
   return {
     get: (tenantId, key, overrideAudit) =>
       raw.get(tenantId, key, overrideAudit ?? { userId, handlerName }),
+    // No audit injection: has() is metadata-only and never logs a read.
+    has: raw.has.bind(raw),
     set: raw.set.bind(raw),
     delete: raw.delete.bind(raw),
   };
@@ -82,6 +84,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/secrets/secrets-context.ts

@@ -179,6 +179,14 @@ export function createSecretsContext(opts: SecretsContextOptions): SecretsContex
       return createSecret(plaintext);
     },
 
+    async has(tenantId, keyOrHandle) {
+      // Row-existence only — no decrypt, no DEK unwrap, no read-audit
+      // event. The audit table logs credential reads; a readiness probe
+      // never sees the value, so logging it would dilute the trail.
+      const existing = await lookup(tenantId, resolveKey(keyOrHandle));
+      return existing !== undefined;
+    },
+
     async set(tenantId, keyOrHandle, value, setOpts = {}) {
       const key = resolveKey(keyOrHandle);
       const envelope = await encryptValue(value, masterKeyProvider);

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/__tests__/multi-tenant.integration.test.ts

@@ -205,6 +205,14 @@ describe("multi-tenant user", () => {
     const tenantIds = memberships.map((m: Record<string, unknown>) => m["tenantId"]);
     expect(tenantIds).toContain(testTenantId(1));
     expect(tenantIds).toContain(testTenantId(2));
+
+    // tenantName/tenantKey machen die Memberships im UI unterscheidbar
+    // (Tenant-Switcher) — die Query reichert sie aus der tenants-Tabelle an.
+    const acme = memberships.find(
+      (m: Record<string, unknown>) => m["tenantId"] === testTenantId(1),
+    );
+    expect(acme["tenantName"]).toBe("ACME");
+    expect(acme["tenantKey"]).toBe("acme");
   });
 
   test("user has different roles per tenant", async () => {
@@ -231,6 +239,14 @@ describe("multi-tenant user", () => {
     const body = await res.json();
     expect(body.tenants.length).toBe(2);
     expect(body.activeTenantId).toBe(testTenantId(1));
+
+    // name/key kommen bis in die HTTP-Response durch (Tenant-Switcher-Label).
+    const names = body.tenants.map((t: Record<string, unknown>) => t["name"]);
+    expect(names).toContain("ACME");
+    expect(names).toContain("Beta Inc");
+    const keys = body.tenants.map((t: Record<string, unknown>) => t["key"]);
+    expect(keys).toContain("acme");
+    expect(keys).toContain("beta");
   });
 
   test("POST /auth/switch-tenant issues new JWT with different tenant", async () => {
@@ -276,3 +292,55 @@ describe("perTenant jobs", () => {
     }
   });
 });
+
+// --- Scenario 6: disabled tenant verschwindet aus allen Auth-Flächen ---
+//
+// tenant:write:disable legt den Tenant still: memberships-Query filtert ihn,
+// damit listet /auth/tenants ihn nicht mehr (Switcher), switch-tenant lehnt
+// ab (not_a_member) und der Login wählt ihn nicht. active-tenant-ids lässt
+// ihn ebenfalls aus (perTenant-Jobs). enable macht alles rückgängig.
+// Läuft bewusst NACH den perTenant-Job-Tests — die erwarten 2 aktive Tenants.
+
+describe("disabled tenant", () => {
+  const user = createTestUser({ id: 10 });
+
+  test("disable removes the tenant from memberships, /auth/tenants and switch-tenant", async () => {
+    const r = await writeApi(systemAdmin, TenantHandlers.disable, { id: testTenantId(2) });
+    expect(r.isSuccess).toBe(true);
+
+    const result = await queryApi(systemAdmin, TenantQueries.memberships, {
+      userId: "11111111-0000-4000-8000-000000000010",
+    });
+    const tenantIds = result.data.map((m: Record<string, unknown>) => m["tenantId"]);
+    expect(tenantIds).toEqual([testTenantId(1)]);
+
+    const res = await getApi(user, "/auth/tenants");
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.tenants.map((t: Record<string, unknown>) => t["tenantId"])).toEqual([
+      testTenantId(1),
+    ]);
+
+    const switchRes = await postApi(user, "/auth/switch-tenant", { tenantId: testTenantId(2) });
+    expect(switchRes.status).toBe(403);
+
+    const activeIds = await queryApi(systemAdmin, TenantQueries.activeTenantIds, {});
+    expect(activeIds.data).toEqual([testTenantId(1)]);
+  });
+
+  test("enable restores membership, switcher and active-tenant-ids", async () => {
+    const r = await writeApi(systemAdmin, TenantHandlers.enable, { id: testTenantId(2) });
+    expect(r.isSuccess).toBe(true);
+
+    const result = await queryApi(systemAdmin, TenantQueries.memberships, {
+      userId: "11111111-0000-4000-8000-000000000010",
+    });
+    expect(result.data.length).toBe(2);
+
+    const switchRes = await postApi(user, "/auth/switch-tenant", { tenantId: testTenantId(2) });
+    expect(switchRes.status).toBe(200);
+
+    const activeIds = await queryApi(systemAdmin, TenantQueries.activeTenantIds, {});
+    expect(activeIds.data).toContain(testTenantId(2));
+  });
+});

package/src/tenant/__tests__/tenant.integration.test.ts

@@ -145,6 +145,22 @@ describe("scenario 4: tenant.disable", () => {
       "SystemAdmin",
     ]);
   });
+
+  test("SystemAdmin can re-enable a disabled tenant", async () => {
+    const me = await stack.http.queryOk<Record<string, unknown>>(TenantQueries.me, {}, systemAdmin);
+    const tenantId = me["id"] as string;
+
+    const data = await stack.http.writeOk(TenantHandlers.enable, { id: tenantId }, systemAdmin);
+    expect(data!["data"]).toMatchObject({
+      isEnabled: true,
+    });
+  });
+
+  test("enable handler requires SystemAdmin role", async () => {
+    expect(rolesOf(stack.registry.getWriteHandler(TenantHandlers.enable)?.access)).toEqual([
+      "SystemAdmin",
+    ]);
+  });
 });
 
 // --- Scenario 5: tenant.list ---

package/src/tenant/constants.ts

@@ -12,6 +12,7 @@ export const TenantHandlers = {
   create: "tenant:write:create",
   update: "tenant:write:update",
   disable: "tenant:write:disable",
+  enable: "tenant:write:enable",
   addMember: "tenant:write:add-member",
   removeMember: "tenant:write:remove-member",
   updateMemberRoles: "tenant:write:update-member-roles",

package/src/tenant/feature.ts

@@ -10,6 +10,7 @@ import { addMemberWrite } from "./handlers/add-member.write";
 import { cancelInvitationWrite } from "./handlers/cancel-invitation.write";
 import { createWrite } from "./handlers/create.write";
 import { disableWrite } from "./handlers/disable.write";
+import { enableWrite } from "./handlers/enable.write";
 import { invitationsQuery } from "./handlers/invitations.query";
 import { listQuery } from "./handlers/list.query";
 import { meQuery } from "./handlers/me.query";
@@ -29,6 +30,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/enable/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);
@@ -87,6 +91,7 @@ export function createTenantFeature(): FeatureDefinition {
       create: r.writeHandler(createWrite),
       update: r.writeHandler(updateWrite),
       disable: r.writeHandler(disableWrite),
+      enable: r.writeHandler(enableWrite),
       addMember: r.writeHandler(addMemberWrite),
       removeMember: r.writeHandler(removeMemberWrite),
       updateMemberRoles: r.writeHandler(updateMemberRolesWrite),

package/src/tenant/handlers/enable.write.ts

@@ -0,0 +1,20 @@
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { tenantEntity, tenantTable } from "../schema/tenant";
+
+const crud = createEventStoreExecutor(tenantTable, tenantEntity, { entityName: "tenant" });
+
+// Recovery-Gegenstück zu disable — ohne enable wäre ein Fehlklick des
+// Operators nur per Event-Hack reversibel.
+export const enableWrite = defineWriteHandler({
+  name: "enable",
+  schema: z.object({ id: z.uuid() }),
+  access: { roles: ["SystemAdmin"] },
+  // Admin flip: last-writer-wins is fine. SystemAdmin is the only caller and
+  // there's no meaningful concurrent-edit race on this single boolean.
+  handler: async (event, ctx) =>
+    crud.update({ id: event.payload.id, changes: { isEnabled: true } }, event.user, ctx.db, {
+      skipOptimisticLock: true,
+    }),
+});

package/src/tenant/handlers/memberships.query.ts

@@ -1,8 +1,9 @@
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { defineQueryHandler, SYSTEM_ROLE } from "@cosmicdrift/kumiko-framework/engine";
 import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
 import { z } from "zod";
 import { tenantMembershipsTable } from "../membership-table";
+import { tenantTable } from "../schema/tenant";
 
 export const membershipsQuery = defineQueryHandler({
   name: "memberships",
@@ -13,9 +14,31 @@ export const membershipsQuery = defineQueryHandler({
   handler: async (query, ctx) => {
     const rows = await selectMany(ctx.db, tenantMembershipsTable, { userId: query.payload.userId });
 
-    return rows.map((row) => ({
-      ...row,
-      roles: parseRoles(row["roles"]),
-    }));
+    // tenantName/tenantKey machen Memberships in der UI unterscheidbar
+    // (Tenant-Switcher zeigte sonst nur das UUID-Präfix — bei Seed-Tenants
+    // mit 00000000-…-Präfix sind die ununterscheidbar). Eine Handvoll
+    // Memberships pro User → Einzel-Fetches sind ok.
+    const enriched = await Promise.all(
+      rows.map(async (row) => {
+        const tenant = await fetchOne<{ name?: unknown; key?: unknown; isEnabled?: unknown }>(
+          ctx.db,
+          tenantTable,
+          { id: row["tenantId"] },
+        );
+        // Disabled Tenants (tenant:write:disable) zählen nicht als Membership:
+        // Login wählt sie nicht, /auth/tenants listet sie nicht, switch-tenant
+        // antwortet not_a_member. Nur das explizite false filtert — eine
+        // fehlende tenant-Row (Projektions-Drift) soll keinen Login-Lockout
+        // aller Member auslösen.
+        if (tenant !== undefined && tenant.isEnabled === false) return null;
+        return {
+          ...row,
+          roles: parseRoles(row["roles"]),
+          ...(typeof tenant?.name === "string" && { tenantName: tenant.name }),
+          ...(typeof tenant?.key === "string" && { tenantKey: tenant.key }),
+        };
+      }),
+    );
+    return enriched.filter((m) => m !== null);
   },
 });

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", {