@cosmicdrift/kumiko-bundled-features 0.74.0 → 0.76.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.74.0",
+  "version": "0.76.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>",
@@ -84,11 +84,11 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.74.0",
-    "@cosmicdrift/kumiko-framework": "0.74.0",
-    "@cosmicdrift/kumiko-headless": "0.74.0",
-    "@cosmicdrift/kumiko-renderer": "0.74.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.74.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.76.0",
+    "@cosmicdrift/kumiko-framework": "0.76.0",
+    "@cosmicdrift/kumiko-headless": "0.76.0",
+    "@cosmicdrift/kumiko-renderer": "0.76.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.76.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/nodemailer": "^8.0.0",

package/src/audit/feature.ts

@@ -18,6 +18,11 @@ export function createAuditFeature(): FeatureDefinition {
     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.",
     );
+    r.uiHints({
+      displayLabel: "Audit Log",
+      category: "compliance",
+      recommended: false,
+    });
     const queries = {
       list: r.queryHandler(listQuery),
     };

package/src/auth-email-password/__tests__/auth.integration.test.ts

@@ -2,7 +2,7 @@ import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:tes
 import { randomBytes } from "node:crypto";
 import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
 import { createEncryptionProvider } from "@cosmicdrift/kumiko-framework/db";
-import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { SYSTEM_TENANT_ID, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
   createTestUser,
   setupTestStack,
@@ -255,7 +255,7 @@ describe("scenario 5b: change-password when the aggregate stream tenant != sessi
       `SELECT "tenant_id" AS t FROM "kumiko_events" WHERE "aggregate_id" = $1 AND "aggregate_type" = $2 ORDER BY "version" LIMIT 1`,
       [seed.id, "user"],
     )) as ReadonlyArray<{ t: string }>;
-    expect(streamRows[0]?.t).toBe(systemAdmin.tenantId);
+    expect(streamRows[0]?.t).toBe(SYSTEM_TENANT_ID);
     expect(streamRows[0]?.t).not.toBe(membershipTenant);
 
     const signedIn = createTestUser({ id: seed.id, tenantId: seed.tenantId, roles: ["User"] });

package/src/auth-email-password/__tests__/email-verification.integration.test.ts

@@ -7,7 +7,7 @@ import {
   updateMany,
 } from "@cosmicdrift/kumiko-framework/bun-db";
 import { createEncryptionProvider } from "@cosmicdrift/kumiko-framework/db";
-import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { SYSTEM_TENANT_ID, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
   setupTestStack,
   type TestStack,
@@ -250,7 +250,7 @@ describe("POST /auth/verify-email", () => {
       `SELECT "tenant_id" FROM "kumiko_events" WHERE "aggregate_id" = $1 AND "aggregate_type" = 'user' ORDER BY "version" LIMIT 1`,
       [seed.id],
     )) as ReadonlyArray<{ tenant_id: string }>;
-    expect(streamRows[0]?.tenant_id).toBe(systemAdmin.tenantId);
+    expect(streamRows[0]?.tenant_id).toBe(SYSTEM_TENANT_ID);
 
     const { token } = signVerificationToken(seed.id, 60, verifySecret);
     const res = await post("/api/auth/verify-email", { token });
@@ -407,7 +407,7 @@ describe("verify-email — aggregate stream in a non-membership tenant (sysadmin
       [seed.id],
     )) as ReadonlyArray<{ tenant_id: string; aggregate_type: string }>;
     expect(streamRows[0]?.aggregate_type).toBe("user");
-    expect(streamRows[0]?.tenant_id).toBe(systemAdmin.tenantId);
+    expect(streamRows[0]?.tenant_id).toBe(SYSTEM_TENANT_ID);
     expect(streamRows[0]?.tenant_id).not.toBe(membershipTenant);
 
     const { token } = signVerificationToken(seed.id, 60, verifySecret);

package/src/auth-email-password/__tests__/password-reset.integration.test.ts

@@ -2,7 +2,7 @@ import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:tes
 import { randomBytes } from "node:crypto";
 import { asRawClient, insertOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { createEncryptionProvider } from "@cosmicdrift/kumiko-framework/db";
-import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { SYSTEM_TENANT_ID, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
   setupTestStack,
   type TestStack,
@@ -308,7 +308,7 @@ describe("POST /auth/reset-password", () => {
       `SELECT "tenant_id" FROM "kumiko_events" WHERE "aggregate_id" = $1 AND "aggregate_type" = 'user' ORDER BY "version" LIMIT 1`,
       [seed.id],
     )) as ReadonlyArray<{ tenant_id: string }>;
-    expect(streamRows[0]?.tenant_id).toBe(systemAdmin.tenantId);
+    expect(streamRows[0]?.tenant_id).toBe(SYSTEM_TENANT_ID);
 
     const { token } = signResetToken(seed.id, 15, resetSecret);
     const res = await post("/api/auth/reset-password", {
@@ -390,7 +390,7 @@ describe("POST /auth/reset-password", () => {
       [seed.id],
     )) as ReadonlyArray<{ tenant_id: string; aggregate_type: string }>;
     expect(streamRows[0]?.aggregate_type).toBe("user");
-    expect(streamRows[0]?.tenant_id).toBe(systemAdmin.tenantId);
+    expect(streamRows[0]?.tenant_id).toBe(SYSTEM_TENANT_ID);
     expect(streamRows[0]?.tenant_id).not.toBe(membershipTenant);
 
     const { token } = signResetToken(seed.id, 15, resetSecret);

package/src/cap-counter/feature.ts

@@ -63,6 +63,11 @@ 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.uiHints({
+    displayLabel: "Cap Counter · Usage Limits",
+    category: "operations",
+    recommended: false,
+  });
   r.entity("cap-counter", capCounterEntity);
 
   // Custom Domain-Event für Rolling-Counter. r.defineEvent registriert

package/src/channel-email/feature.ts

@@ -8,6 +8,11 @@ export function createChannelEmailFeature(options: EmailChannelOptions): Feature
     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.uiHints({
+      displayLabel: "Email Channel",
+      category: "notifications",
+      recommended: false,
+    });
     r.requires("delivery");
 
     r.useExtension("deliveryChannel", "email", {

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

@@ -10,6 +10,11 @@ export function createChannelInAppFeature(): FeatureDefinition {
     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.uiHints({
+      displayLabel: "In-App Inbox",
+      category: "notifications",
+      recommended: false,
+    });
     r.requires("delivery");
 
     // Register as delivery channel via extension system

package/src/channel-push/feature.ts

@@ -8,6 +8,11 @@ export function createChannelPushFeature(options: PushChannelOptions): FeatureDe
     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.uiHints({
+      displayLabel: "Push Channel",
+      category: "notifications",
+      recommended: false,
+    });
     r.requires("delivery");
 
     r.useExtension("deliveryChannel", "push", {

package/src/compliance-profiles/feature.ts

@@ -30,6 +30,11 @@ export function createComplianceProfilesFeature(): FeatureDefinition {
     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.",
     );
+    r.uiHints({
+      displayLabel: "Compliance Profiles",
+      category: "compliance",
+      recommended: false,
+    });
     // 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

@@ -29,6 +29,11 @@ export function createConfigFeature(): FeatureDefinition {
     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.uiHints({
+      displayLabel: "Tenant Config Store",
+      category: "infrastructure",
+      recommended: true,
+    });
     r.systemScope();
 
     // One aggregate stream per (key, scope) pair — the executor handles the

package/src/custom-fields/feature.ts

@@ -102,6 +102,11 @@ function registerCustomFields(
   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`, `update-tenant-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.uiHints({
+    displayLabel: "Custom Fields",
+    category: "data",
+    recommended: false,
+  });
   r.entity("field-definition", fieldDefinitionEntity);
 
   // Event-types — qualified als "custom-fields:event:<short-name>".

package/src/data-retention/feature.ts

@@ -47,6 +47,11 @@ export function createDataRetentionFeature(): FeatureDefinition {
     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.uiHints({
+      displayLabel: "Data Retention Policy",
+      category: "compliance",
+      recommended: false,
+    });
     r.entity("tenant-retention-override", tenantRetentionOverrideEntity);
 
     // S2.D3: Cross-Feature-API fuer Forget-Flow + Cleanup-Job

package/src/file-foundation/feature.ts

@@ -99,6 +99,11 @@ 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.uiHints({
+    displayLabel: "File Provider Foundation",
+    category: "storage",
+    recommended: false,
+  });
   r.requires("config");
 
   r.extendsRegistrar("fileProvider", {

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

@@ -63,6 +63,11 @@ 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).',
   );
+  r.uiHints({
+    displayLabel: "File Provider · In-Memory",
+    category: "storage",
+    recommended: false,
+  });
   // 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

@@ -42,6 +42,11 @@ 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.uiHints({
+    displayLabel: "File Provider · S3",
+    category: "storage",
+    recommended: false,
+  });
   r.requires("config");
   r.requires("secrets");
   r.requires("file-foundation");

package/src/jobs/feature.ts

@@ -30,6 +30,11 @@ export function createJobsFeature(): FeatureDefinition {
     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.uiHints({
+      displayLabel: "Jobs · Audit & Operator UI",
+      category: "operations",
+      recommended: false,
+    });
     r.systemScope();
     r.unmanagedTable(jobRunLogsTableMeta, {
       reason: "read_side.job_run_logs",

package/src/legal-pages/feature.ts

@@ -64,6 +64,11 @@ export function createLegalPagesFeature(opts: LegalPagesOptions = {}): FeatureDe
     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.uiHints({
+      displayLabel: "Legal Pages",
+      category: "content",
+      recommended: false,
+    });
     r.requires("text-content");
 
     // 4 Public-HTML-Routes

package/src/mail-foundation/feature.ts

@@ -68,6 +68,11 @@ 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.uiHints({
+    displayLabel: "Mail Transport Foundation",
+    category: "notifications",
+    recommended: false,
+  });
   r.requires("config");
 
   // Plugin extension-point. Provider-features register here. The

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

@@ -53,6 +53,11 @@ 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.uiHints({
+    displayLabel: "Mail Transport · SMTP",
+    category: "notifications",
+    recommended: false,
+  });
   r.requires("config");
   r.requires("secrets");
   r.requires("mail-foundation");

package/src/managed-pages/feature.ts

@@ -144,6 +144,11 @@ export function createManagedPagesFeature(opts: ManagedPagesOptions): FeatureDef
     r.describe(
       "Tenant-editable, server-rendered public pages with per-tenant branding. Stores one Markdown `page` per `(tenantId, slug, lang)` in the `read_pages` entity table with a `published` gate plus `description`/`ogImage` SEO meta. Registers an anonymous `GET {basePath}/:slug` route that resolves the tenant from the request Host via the app-supplied `resolveApexTenant`, serves only published pages (drafts → 404), renders Markdown through the hardened `page-render` core, and isolates per-tenant content with `Vary: Host`. Ships TenantAdmin/SystemAdmin admin screens (`entityList` + `entityEdit`) backed by convention CRUD handlers (`managed-pages:write:page:{create,update,delete}`, `managed-pages:query:page:{list,detail}`); the app wires nav/workspace onto `managed-pages:screen:page-list`. Branding (via `config`, scope tenant): `branding-{title,description,site-url,accent-color,logo-url,layout-preset}` keys with write-time validation (hex color, https URLs), a `configEdit` self-service screen (`managed-pages:screen:branding-settings`), and a `managed-pages:query:branding` read that the render path applies as scoped `:root` CSS vars + a logo/title header. Also exposes `managed-pages:write:set` (idempotent slug-keyed upsert, SystemAdmin cross-tenant via `tenantIdOverride`) as a provisioning API. Requires `config` + `anonymousAccess` wired at app bootstrap.",
     );
+    r.uiHints({
+      displayLabel: "Managed Pages · Public CMS",
+      category: "content",
+      recommended: false,
+    });
     r.requires("config");
     r.entity("page", pageEntity);
 

package/src/rate-limiting/feature.ts

@@ -14,6 +14,11 @@ export function createRateLimitingFeature() {
     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.uiHints({
+      displayLabel: "Rate Limiting · Ops Query",
+      category: "operations",
+      recommended: false,
+    });
     r.queryHandler(rateLimitStatus);
   });
 }

package/src/readiness/feature.ts

@@ -15,6 +15,11 @@ 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.uiHints({
+    displayLabel: "Readiness · Onboarding Probe",
+    category: "operations",
+    recommended: false,
+  });
   r.requires("config");
   r.requires("secrets");
 

package/src/renderer-foundation/feature.ts

@@ -14,6 +14,11 @@ export function createRendererFoundationFeature() {
     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.uiHints({
+      displayLabel: "Renderer Foundation",
+      category: "notifications",
+      recommended: false,
+    });
     r.requires("template-resolver");
 
     r.extendsRegistrar("renderer", {

package/src/renderer-simple/feature.ts

@@ -30,6 +30,11 @@ export function createRendererSimpleFeature(): FeatureDefinition {
     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.uiHints({
+      displayLabel: "Renderer \u00b7 Simple",
+      category: "notifications",
+      recommended: false,
+    });
     r.requires("renderer-foundation");
 
     r.useExtension("renderer", "simple", {

package/src/secrets/feature.ts

@@ -87,6 +87,11 @@ export function createSecretsFeature(): FeatureDefinition {
     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.uiHints({
+      displayLabel: "Tenant Secrets",
+      category: "infrastructure",
+      recommended: true,
+    });
     r.envSchema(secretsEnvSchema);
 
     // ES entity: set/delete go through the executor, `tenantSecret.created/

package/src/step-dispatcher/feature.ts

@@ -32,6 +32,11 @@ export function createStepDispatcherFeature(): FeatureDefinition {
     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.uiHints({
+      displayLabel: "Step Dispatcher · Deferred Side-Effects",
+      category: "infrastructure",
+      recommended: false,
+    });
     r.systemScope();
 
     r.multiStreamProjection({

package/src/subscription-mollie/feature.ts

@@ -149,6 +149,11 @@ export function createSubscriptionMollieFeature(
     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.uiHints({
+      displayLabel: "Billing \u00b7 Mollie",
+      category: "billing",
+      recommended: false,
+    });
     r.requires("billing-foundation");
     r.envSchema(subscriptionMollieEnvSchema);
 

package/src/subscription-stripe/feature.ts

@@ -111,6 +111,11 @@ export function createSubscriptionStripeFeature(
     r.describe(
       'Stripe payment provider plugin for `billing-foundation`. Reads its Stripe API key + webhook secret from system config keys with `backing:"secrets"` (envelope-encrypted in the secrets store under the system tenant) and a `billingLive` **system config** flag — all at runtime, so keys rotate and prod goes live without a redeploy. The `mask` on each key derives the sysadmin settings screen + nav, so no app wires a hand-written config UI. Mount via `createSubscriptionStripeFeature({ priceToTier })`; the optional `apiKey`/`webhookSecret` options are env→secrets bridge fallbacks. The plugin always mounts — `createCheckoutSession` throws `feature_disabled` unless `billingLive` is true, so sk_test_ keys in prod never produce a live checkout. Implements all four provider methods (webhook verify, checkout, portal, cancel).',
     );
+    r.uiHints({
+      displayLabel: "Billing · Stripe",
+      category: "billing",
+      recommended: false,
+    });
     // Hard-deps: billing-foundation (plugin-host) + config (billing-live +
     // backing:"secrets" credentials) + secrets (the store the backing:secrets
     // dispatch reads/writes + its tenant_secrets table).

package/src/tags/feature.ts

@@ -44,6 +44,11 @@ function registerTags(
   r.describe(
     "Generic, host-agnostic tagging for any entity. Owns two event-sourced entities — the per-tenant `tag` catalog (`read_tags`) and `tag-assignment` join rows keyed by (entityType, entityId) (`read_tag_assignments`) — so tagging adds NO column to the host entity and needs no relational pivot or JOIN. Provides write-handlers `create-tag`, `assign-tag` (idempotent), `remove-tag` (idempotent) and list queries for the catalog and the assignments. Read which tags an entity has, or which entities carry a tag, by listing `tag-assignment` filtered on `entityId` or `tagId` and composing in the read-layer. Every path uses one access rule — adopt the host's model with createTagsFeature({ access: { openToAll: true } }) or pin roles with createTagsFeature({ roles }). Pass { toggleable: { default: false } } to make the whole feature tier-gatable via the tier-engine (no host hook).",
   );
+  r.uiHints({
+    displayLabel: "Tags",
+    category: "data",
+    recommended: false,
+  });
 
   // Tier-gating is a framework concern, not a per-app hook: declaring the
   // feature toggleable lets tier-engine/feature-toggles cut it per tenant.

package/src/tags/web/client-plugin.tsx

@@ -1,9 +1,4 @@
 // @runtime client
-// Client-feature factory for tags. Mounted via
-// createKumikoApp({ clientFeatures: [tagsClient()] }) — registers TagSection
-// under TAGS_SECTION_EXTENSION_NAME and contributes the default translations.
-// Required even for standalone <TagSection> use, otherwise its i18n keys render
-// raw.
 
 import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
 import { TAGS_FEATURE_NAME, TAGS_SECTION_EXTENSION_NAME } from "../constants";

package/src/template-resolver/feature.ts

@@ -19,6 +19,11 @@ export function createTemplateResolverFeature() {
     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.uiHints({
+      displayLabel: "Template Resolver",
+      category: "notifications",
+      recommended: false,
+    });
     r.entity("template-resource", templateResourceEntity);
 
     const handlers = {

package/src/text-content/feature.ts

@@ -26,6 +26,11 @@ export function createTextContentFeature() {
     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.uiHints({
+      displayLabel: "Text Content \u00b7 Markdown Store",
+      category: "content",
+      recommended: false,
+    });
     r.entity("text-block", textBlockEntity);
 
     const handlers = {

package/src/tier-engine/feature.ts

@@ -187,6 +187,11 @@ export function createTierEngineFeature<
     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`. A SystemAdmin-only `set-tenant-tier` write plus `get-tenant-tier`/`tier-options` reads let an operator assign a tier to ANY tenant manually \u2014 without a billing purchase \u2014 stamping `source: "manual"` so a future Stripe\u2192tier sync won\'t overwrite the grant. Apps surface this via the `tier-admin` screen.',
     );
+    r.uiHints({
+      displayLabel: "Tier Engine \u00b7 Plan Composition",
+      category: "billing",
+      recommended: false,
+    });
     r.requires("config");
     r.requires("tenant");
 

package/src/user/schema/user.ts

@@ -56,6 +56,9 @@ const USER_STATUS_OPTIONS = [
 export const userEntity = createEntity({
   table: "read_users",
   softDelete: true,
+  // Tenant-independent identity aggregate — its event stream lives on
+  // SYSTEM_TENANT_ID instead of whichever tenant happened to create it (#497).
+  systemStream: true,
   fields: {
     // Identity — anyone who can see the user can read the email, but only
     // privileged roles (SYSTEM auth code, SystemAdmin) may change it.

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

@@ -107,6 +107,11 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
     r.describe(
       'Implements GDPR Art. 15 (access / `my-audit-log` query), Art. 17 (erasure / `request-deletion` + `cancel-deletion`, plus the anonymous email-verified `request-deletion-by-email` + `confirm-deletion-by-token` flow for lockout-safe self-service, + 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.uiHints({
+      displayLabel: "User Data Rights \u00b7 GDPR",
+      category: "compliance",
+      recommended: false,
+    });
     r.requires("user", "data-retention", "compliance-profiles", "sessions");
     r.usesApi("compliance.forTenant");
     r.usesApi("retention.policyFor");

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

@@ -42,6 +42,11 @@ export function createUserDataRightsDefaultsFeature(
     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.uiHints({
+      displayLabel: "User Data Rights · Default Hooks",
+      category: "compliance",
+      recommended: false,
+    });
     r.requires("user", "files", "user-data-rights");
 
     r.useExtension(EXT_USER_DATA, "user", {

package/src/user-profile/feature.ts

@@ -13,6 +13,11 @@ export function createUserProfileFeature(): FeatureDefinition {
         '`type: "custom"` with `__component: "UserProfileScreen"`. Requires `user`, ' +
         "`auth-email-password`, and `user-data-rights`.",
     );
+    r.uiHints({
+      displayLabel: "User Profile · Self-Service",
+      category: "identity",
+      recommended: true,
+    });
     r.requires("user");
     r.requires("auth-email-password");
     r.requires("user-data-rights");