@cosmicdrift/kumiko-bundled-features 0.236.0 → 0.237.0

package/src/tags/handlers/delete-tag.write.ts

@@ -24,6 +24,9 @@ export function createDeleteTagHandler(
     name,
     schema: deleteTagPayloadSchema,
     access,
+    description:
+      "Deletes a catalog tag and cascades a detach over every assignment still carrying it, so the tag disappears from all entities at once; this is the legacy name the TagManager dispatches.",
+    agent: { risk: "high" },
     handler: async (event, ctx) => {
       const payload = event.payload as DeleteTagPayload; // @cast-boundary engine-payload
 

package/src/tags/handlers/remove-tag.write.ts

@@ -12,6 +12,8 @@ export function createRemoveTagHandler(access: AccessRule = DEFAULT_TAG_ACCESS):
     name: "remove-tag",
     schema: removeTagPayloadSchema,
     access,
+    description:
+      "Detaches one catalog tag from one host entity, reporting success when it was not attached; use it to untag a single record while the tag itself stays in the catalog.",
     handler: async (event, ctx) => {
       const payload = event.payload as RemoveTagPayload; // @cast-boundary engine-payload
       const id = tagAssignmentAggregateId(

package/src/tags/handlers/update-tag.write.ts

@@ -16,6 +16,8 @@ export function createUpdateTagHandler(
     name,
     schema: updateTagPayloadSchema,
     access,
+    description:
+      "Renames, recolours or re-scopes a catalog tag from a flat optimistic-locked payload, leaving omitted fields untouched; this is the legacy name the TagManager dispatches, unlike the entity-edit alias that takes a changes envelope.",
     handler: async (event, ctx) => {
       const payload = event.payload as UpdateTagPayload; // @cast-boundary engine-payload
       const changes: Record<string, unknown> = {};

package/src/template-resolver/handlers/by-slug.query.ts

@@ -28,6 +28,8 @@ export const bySlugQuery = defineQueryHandler({
     tenantIdOverride: z.string().min(1).optional(),
   }),
   access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
+  description:
+    "Reads one text-block of a tenant by slug and locale together with its body and format; it is pinned to the text-block kind so mail templates and AI prompts in the same table stay unreachable through this anonymous-capable path.",
   handler: async (query, ctx) => {
     const override = query.payload.tenantIdOverride;
     const overrideDenied = crossTenantOverrideDenied(

package/src/template-resolver/handlers/by-tenant.query.ts

@@ -33,6 +33,8 @@ export const byTenantQuery = defineQueryHandler({
     tenantIdOverride: z.string().min(1).optional(),
   }),
   access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
+  description:
+    "Lists every text-block of a tenant with slug, locale, title and body so a public content tree can be rendered in one call; use it for the whole sidebar, and by-slug when only one block is needed.",
   handler: async (query, ctx) => {
     const override = query.payload.tenantIdOverride;
     const overrideDenied = crossTenantOverrideDenied(

package/src/template-resolver/handlers/collection-item.query.ts

@@ -25,6 +25,10 @@ export function makeCollectionItemQuery(collection: ContentCollectionDefinition)
       tenantIdOverride: z.string().min(1).optional(),
     }),
     access: collection.access ?? DEFAULT_COLLECTION_ACCESS,
+    description:
+      collection.ownership === "user"
+        ? `Reads one of the caller's own "${collection.id}" entries by slug and locale, returning null when that user has none; use it to open a single entry in the editor rather than to list the collection.`
+        : `Reads one tenant-wide "${collection.id}" entry by slug and locale, returning null when it does not exist; use it to open a single entry in the editor rather than to list the collection.`,
     handler: async (query, ctx) => {
       const override = query.payload.tenantIdOverride;
       const overrideDenied = crossTenantOverrideDenied(

package/src/template-resolver/handlers/collection-list.query.ts

@@ -30,6 +30,10 @@ export function makeCollectionListQuery(collection: ContentCollectionDefinition)
       tenantIdOverride: z.string().min(1).optional(),
     }),
     access: collection.access ?? DEFAULT_COLLECTION_ACCESS,
+    description:
+      collection.ownership === "user"
+        ? `Lists the caller's own entries in the "${collection.id}" content collection (${collection.kind} content) with slug, locale, title and body; entries other users keep in this collection are never returned.`
+        : `Lists the tenant-wide entries of the "${collection.id}" content collection (${collection.kind} content) with slug, locale, title and body; every caller who may reach this collection sees the same shared set.`,
     handler: async (query, ctx) => {
       const override = query.payload.tenantIdOverride;
       const overrideDenied = crossTenantOverrideDenied(

package/src/template-resolver/handlers/collection-set.write.ts

@@ -36,6 +36,10 @@ export function makeCollectionSetWrite(collection: ContentCollectionDefinition)
       tenantIdOverride: z.string().min(1).optional(),
     }),
     access: collection.access ?? DEFAULT_COLLECTION_ACCESS,
+    description:
+      collection.ownership === "user"
+        ? `Creates or overwrites the caller's own "${collection.id}" entry at a slug and locale, live on save with no draft stage; it always writes the acting user's entry, never another user's.`
+        : `Creates or overwrites the tenant-wide "${collection.id}" entry at a slug and locale, live on save with no draft stage; the change is visible to everyone who may reach this shared collection.`,
     handler: async (event, ctx) => {
       const db = ctx.db;
       const override = event.payload.tenantIdOverride;

package/src/template-resolver/handlers/find-by-id.query.ts

@@ -12,6 +12,8 @@ export const findByIdQuery = defineQueryHandler({
   name: "find-by-id",
   schema: z.object({ id: z.string().min(1) }),
   access: { roles: ["TenantAdmin", "SystemAdmin", "User"] },
+  description:
+    "Reads one template resource by row id with its content, variable schema, scope and draft/archived status, but only when it belongs to the caller's tenant or is a system default; use it to load a template into the admin editor.",
   handler: async (query, ctx) => {
     const row = await fetchOne<TemplateResourceRow>(ctx.db, templateResourcesTable, {
       id: query.payload.id,

package/src/template-resolver/handlers/list.query.ts

@@ -16,6 +16,8 @@ export const listQuery = defineQueryHandler({
     includeSystem: z.boolean().default(true),
   }),
   access: { roles: ["TenantAdmin", "SystemAdmin", "User"] },
+  description:
+    "Lists template resources of the caller's tenant alongside the system defaults as summaries without content, filterable by kind, locale and status; use it to browse the catalogue, then find-by-id to read one row.",
   handler: async (query, ctx) => {
     const where: Record<string, unknown> = {};
 

package/src/template-resolver/handlers/set.write.ts

@@ -47,6 +47,8 @@ export const setWrite = defineWriteHandler({
   // SystemAdmin is a global role, TenantAdmin is per tenant-membership — both
   // paths are needed explicitly, otherwise nobody can set SYSTEM_TENANT texts.
   access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  description:
+    "Creates or overwrites one content-tree resource addressed by slug, kind and locale, carrying a title and folder and going live on save with no draft stage; a SystemAdmin may target the system tenant, where shared legal and marketing copy lives.",
   handler: async (event, ctx) => {
     const db = ctx.db;
     const override = event.payload.tenantIdOverride;

package/src/template-resolver/handlers/toggle-status.write.ts

@@ -8,11 +8,12 @@ import { executor } from "./shared";
 
 type TemplateStatus = "active" | "archived";
 
-function createStatusUpdateHandler(name: string, status: TemplateStatus) {
+function createStatusUpdateHandler(name: string, status: TemplateStatus, description: string) {
   return defineWriteHandler({
     name,
     schema: z.object({ id: z.string().min(1) }),
     access: { roles: ["TenantAdmin", "SystemAdmin"] },
+    description,
     handler: async (event, ctx) => {
       // ctx.db is tenant-scoped: a foreign tenant's id reads as absent → NotFound.
       // Cross-tenant toggling needs SystemAdmin with tenantIdOverride.
@@ -33,5 +34,13 @@ function createStatusUpdateHandler(name: string, status: TemplateStatus) {
   });
 }
 
-export const archiveWrite = createStatusUpdateHandler("archive", "archived");
-export const publishWrite = createStatusUpdateHandler("publish", "active");
+export const archiveWrite = createStatusUpdateHandler(
+  "archive",
+  "archived",
+  "Sets one template resource of the caller's tenant to archived so the resolver stops serving it while the row and its content survive; use it to retire a template reversibly instead of deleting it.",
+);
+export const publishWrite = createStatusUpdateHandler(
+  "publish",
+  "active",
+  "Sets one template resource of the caller's tenant to active so the resolver starts serving it; use it to release a draft written by upsert-tenant, or to bring an archived template back.",
+);

package/src/template-resolver/handlers/upsert-system.write.ts

@@ -16,6 +16,8 @@ export const upsertSystemWrite = defineWriteHandler({
   name: "upsert-system",
   schema: upsertPayloadSchema,
   access: { roles: ["SystemAdmin"] },
+  description:
+    "Creates or overwrites a system-default template under the system tenant with its full variable schema and linked resources, active straight away with no draft stage; SystemAdmin only, since tenants shadow these defaults through upsert-tenant instead.",
   handler: async (event, ctx) => {
     const db = ctx.db;
     // @cast-boundary engine-payload — SYSTEM_TENANT_ID is a UUID literal,

package/src/template-resolver/handlers/upsert-tenant.write.ts

@@ -23,6 +23,8 @@ export const upsertTenantWrite = defineWriteHandler({
     status: z.enum(["draft", "active"]).default("draft"),
   }),
   access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  description:
+    "Creates or overwrites a tenant-scoped template override with its variable schema, landing as a draft that only publish makes live; it refuses a system-tenant target, which is what upsert-system is for.",
   handler: async (event, ctx) => {
     const db = ctx.db;
     const override = event.payload.tenantIdOverride;

package/src/tenant/feature.ts

@@ -144,13 +144,25 @@ export function createTenantFeature(options?: TenantFeatureOptions): FeatureDefi
     // update by convention, so these are added alongside (no rename = no break
     // for existing callers). Cross-tenant because the feature is systemScope.
     r.queryHandler(
-      defineEntityListHandler("tenant", tenantEntity, { access: { roles: ["SystemAdmin"] } }),
+      defineEntityListHandler("tenant", tenantEntity, {
+        access: { roles: ["SystemAdmin"] },
+        description:
+          "Lists tenants under the entity-convention name the generated SystemAdmin tenant-list screen resolves; tenant:query:list is the hand-written equivalent.",
+      }),
     );
     r.queryHandler(
-      defineEntityDetailHandler("tenant", tenantEntity, { access: { roles: ["SystemAdmin"] } }),
+      defineEntityDetailHandler("tenant", tenantEntity, {
+        access: { roles: ["SystemAdmin"] },
+        description:
+          "Loads a single tenant by id under the entity-convention name the generated SystemAdmin tenant-edit screen resolves.",
+      }),
     );
     r.writeHandler(
-      defineEntityUpdateHandler("tenant", tenantEntity, { access: { roles: ["SystemAdmin"] } }),
+      defineEntityUpdateHandler("tenant", tenantEntity, {
+        access: { roles: ["SystemAdmin"] },
+        description:
+          "Saves edits to a tenant's own fields under the entity-convention name the generated SystemAdmin tenant-edit screen resolves; tenant:write:update is the hand-written equivalent.",
+      }),
     );
     r.screen(tenantListScreen);
     r.screen(tenantEditScreen);

package/src/tenant/handlers/active-tenant-ids.query.ts

@@ -12,6 +12,8 @@ export const activeTenantIdsQuery = defineQueryHandler({
   name: "activeTenantIds",
   schema: z.object({}),
   access: { roles: [SYSTEM_ROLE, "SystemAdmin"] },
+  description:
+    "Returns the ids of every tenant that is currently enabled, platform-wide; use it to drive work that has to fan out over all live tenants.",
   handler: async (_query, ctx) => {
     if (!ctx.systemDb) {
       throw new InternalError({

package/src/tenant/handlers/add-member.write.ts

@@ -19,6 +19,8 @@ export const addMemberWrite = defineWriteHandler({
     roles: z.array(z.string()).min(1),
   }),
   access: { roles: ["SystemAdmin"] },
+  description:
+    "Grants an existing user membership in a tenant with the given roles, refusing reserved role names and a user who is already a member; use it to add someone to a workspace without going through an invitation.",
   handler: async (event, ctx) => {
     if (!ctx.systemDb) {
       throw new InternalError({

package/src/tenant/handlers/cancel-invitation.write.ts

@@ -35,6 +35,8 @@ export const cancelInvitationWrite = defineWriteHandler({
   name: "cancel-invitation",
   schema: CancelInvitationSchema,
   access: { roles: access.admin },
+  description:
+    "Withdraws a still-pending invitation of the caller's own tenant and invalidates its link, answering successfully as a no-op when it was already accepted, cancelled or expired.",
   handler: async (event, ctx) => {
     if (!ctx.systemDb) {
       throw new InternalError({

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

@@ -22,6 +22,8 @@ export const createWrite = defineWriteHandler({
   // (roles=["system"]) as the executor; "SystemAdmin" stays the real
   // human-operator path via the UI.
   access: { roles: ["system", "SystemAdmin"] },
+  description:
+    "Creates a new tenant from a key and display name, optionally under a caller-chosen id for seeds or external provisioning; use it when onboarding a new customer or workspace.",
   handler: async (event, ctx) => {
     if (!ctx.systemDb) {
       throw new InternalError({

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

@@ -23,6 +23,8 @@ export const invitationsQuery = defineQueryHandler({
   name: "invitations",
   schema: z.object({}),
   access: { roles: access.admin },
+  description:
+    "Lists the still-pending invitations of the caller's own tenant with their email and inviter decrypted; accepted, cancelled and expired ones are left out.",
   handler: async (query, ctx) => {
     if (!ctx.systemDb) {
       throw new InternalError({

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

@@ -14,6 +14,8 @@ export const listQuery = defineQueryHandler({
     search: z.string().optional(),
   }),
   access: { roles: ["SystemAdmin"] },
+  description:
+    "Pages through every tenant on the platform with an optional search term, for a SystemAdmin browsing the tenant roster.",
   handler: async (query, ctx) => {
     if (!ctx.systemDb) {
       throw new InternalError({

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

@@ -10,6 +10,8 @@ export const meQuery = defineQueryHandler({
   name: "me",
   schema: z.object({}),
   access: { openToAll: true },
+  description:
+    "Returns the record of the tenant the caller is currently signed in to, or null if it is gone; use it whenever the active tenant's own name, key or settings are needed.",
   handler: async (query, ctx) => {
     if (!ctx.systemDb) {
       throw new InternalError({

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

@@ -24,6 +24,8 @@ export const membersQuery = defineQueryHandler({
     userId: z.string().min(1).optional(),
   }),
   access: { roles: access.admin },
+  description:
+    "Lists the memberships of the caller's own tenant with each member's decrypted email, display name and roles, optionally narrowed to a single user id.",
   handler: async (query, ctx) => {
     if (!ctx.systemDb) {
       throw new InternalError({

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

@@ -12,6 +12,8 @@ export const membershipsQuery = defineQueryHandler({
   // Called via ctx.queryAs(systemUser, ...) during login/switch-tenant, or
   // directly by tenant admins managing memberships in the admin UI.
   access: { roles: [SYSTEM_ROLE, "SystemAdmin"] },
+  description:
+    "Resolves which tenants a given user belongs to and with which roles, labelled by tenant name and key and skipping disabled tenants; sign-in and tenant switching build their options from it.",
   handler: async (query, ctx) => {
     if (!ctx.systemDb) {
       throw new InternalError({

package/src/tenant/handlers/remove-member.write.ts

@@ -24,6 +24,9 @@ export const removeMemberWrite = defineWriteHandler({
   name: "removeMember",
   schema: z.object({ userId: z.string(), tenantId: z.string() }),
   access: { roles: ["SystemAdmin"] },
+  description:
+    "Removes a user's membership in a tenant and signs their sessions in that tenant out, refusing to strip the tenant's last TenantAdmin; use it when someone should lose access to a workspace.",
+  agent: { risk: "high" },
   handler: async (event, ctx) => {
     if (!ctx.systemDb) {
       throw new InternalError({

package/src/tenant/handlers/resolve-user-ids.query.ts

@@ -14,6 +14,7 @@ export const resolveUserIdsQuery = defineQueryHandler({
     userId: z.string().optional(),
   }),
   access: { roles: [SYSTEM_ROLE] },
+  agent: { expose: false },
   handler: async (query, ctx) => {
     if (!ctx.systemDb) {
       throw new InternalError({

package/src/tenant/handlers/team-list.query.ts

@@ -99,6 +99,8 @@ export const teamListQuery = definePagedQueryHandler({
       .optional(),
   }),
   access: { roles: access.admin },
+  description:
+    "Pages through the caller's tenant team as one list of active members and pending invitations, with email, display name, roles, last-seen time and a status of active or pending, sortable and filterable by status.",
   handler: async (query, ctx) => {
     if (!ctx.systemDb) {
       throw new InternalError({

package/src/tenant/handlers/toggle-enabled.write.ts

@@ -14,6 +14,9 @@ function createToggleTenantHandler(enable: boolean) {
     name: verbName,
     schema: z.object({ id: z.uuid() }),
     access: { roles: ["SystemAdmin"] },
+    description: enable
+      ? "Re-enables a disabled tenant so its members can sign in and switch to it again; this is the undo for tenant:write:disable."
+      : "Marks a tenant disabled so it stops counting as a membership — its members can no longer sign in to it or switch to it — while leaving all of its data in place.",
     handler: async (event, ctx) => {
       if (!ctx.systemDb) {
         throw new InternalError({

package/src/tenant/handlers/update-member-roles.write.ts

@@ -54,6 +54,8 @@ export const updateMemberRolesWrite = defineWriteHandler({
   // manage memberships cross-tenant (payload.tenantId). TenantAdmin and Admin
   // are session-scoped (event.user.tenantId).
   access: { roles: ["system", ...access.admin] },
+  description:
+    "Replaces the roles a user holds in a tenant, rejecting reserved role names and any grant that would raise the target above the caller; admins act on their own tenant, SystemAdmins on any.",
   handler: async (event, ctx) => {
     if (!ctx.systemDb) {
       throw new InternalError({

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

@@ -22,6 +22,8 @@ export const updateWrite = defineWriteHandler({
     changes: z.object({ name: z.string().min(1).max(200).optional() }),
   }),
   access: { roles: ["Admin", "SystemAdmin"] },
+  description:
+    "Renames a tenant against the version the caller read; an Admin may only rename their own tenant, a SystemAdmin any of them.",
   handler: async (event, ctx) => {
     if (!ctx.systemDb) {
       throw new InternalError({

package/src/tenant/schema/tenant.ts

@@ -18,6 +18,8 @@ export const TENANT_LIFECYCLE_STATUSES = [
 export type TenantLifecycleStatus = (typeof TENANT_LIFECYCLE_STATUSES)[number];
 
 export const tenantEntity = createEntity({
+  description:
+    "A tenant, the isolated workspace every other record belongs to, holding its key and display name, whether it is enabled, and its destruction-lifecycle state.",
   table: "read_tenants",
   // tenant.id IS the tenantId-value that every other table references as FK.
   // Alle tenantId-Spalten sind UUID (Migration 2026-04-16) → tenant.id muss

package/src/tenant-lifecycle/handlers/cancel-destruction.write.ts

@@ -19,6 +19,8 @@ export const cancelDestructionWrite = defineWriteHandler({
   name: "cancel-destruction",
   schema: z.object({}),
   access: { roles: ["TenantOwner", "Admin"] },
+  description:
+    "Returns a tenant whose destruction was requested back to active and clears the grace period; use it to undo a close-account request while the grace period is still running.",
   handler: async (event, ctx) => {
     const tenantId = event.user.tenantId;
     const row = await fetchOne<TenantLifecycleRow>(ctx.db.raw, tenantTable, { id: tenantId });

package/src/tenant-lifecycle/handlers/request-destruction.write.ts

@@ -22,6 +22,9 @@ export const requestDestructionWrite = defineWriteHandler({
   name: "request-destruction",
   schema: z.object({}),
   access: { roles: ["TenantOwner", "Admin"] },
+  description:
+    "Puts the caller's own tenant into destroyRequested, starts the compliance-profile grace period after which its data is erased, and revokes every session in the tenant; use it when an account owner asks to close their account.",
+  agent: { risk: "high" },
   handler: async (event, ctx) => {
     const tenantId = event.user.tenantId;
     const row = await fetchOne<TenantLifecycleRow>(ctx.db.raw, tenantTable, { id: tenantId });

package/src/tier-engine/entity.ts

@@ -24,6 +24,8 @@ import { createEntity, createTextField } from "@cosmicdrift/kumiko-framework/eng
 //   - Caps-Werte: pro-Tier-Cap-Definitionen leben in der TierMap der App.
 export const tierAssignmentEntity = createEntity({
   table: "read_tier_assignments",
+  description:
+    "The pricing tier currently assigned to a tenant, plus where the assignment came from (manual grant, billing sync or signup default) — one row per tenant.",
   fields: {
     tier: createTextField({ required: true, maxLength: 50 }),
     // Woher das Assignment stammt: "manual" (Admin-Grant via tier-admin-Screen),

package/src/tier-engine/feature.ts

@@ -200,11 +200,29 @@ export function createTierEngineFeature<
     r.entity("tier-assignment", tierAssignmentEntity);
 
     // Standard-CRUD via Helper.
-    r.writeHandler(defineEntityCreateHandler("tier-assignment", tierAssignmentEntity, writeAccess));
-    r.writeHandler(defineEntityUpdateHandler("tier-assignment", tierAssignmentEntity, writeAccess));
+    r.writeHandler(
+      defineEntityCreateHandler("tier-assignment", tierAssignmentEntity, {
+        ...writeAccess,
+        description:
+          "Creates the tier-assignment row of the caller's tenant with a tier name and its source; prefer `set-tenant-tier`, which upserts and refreshes the feature gate.",
+      }),
+    );
+    r.writeHandler(
+      defineEntityUpdateHandler("tier-assignment", tierAssignmentEntity, {
+        ...writeAccess,
+        description:
+          "Updates an existing tier-assignment row by id; prefer `set-tenant-tier`, which resolves the tenant's row itself and refreshes the feature gate.",
+      }),
+    );
 
     // Reads.
-    r.queryHandler(defineEntityListHandler("tier-assignment", tierAssignmentEntity, adminAccess));
+    r.queryHandler(
+      defineEntityListHandler("tier-assignment", tierAssignmentEntity, {
+        ...adminAccess,
+        description:
+          "Lists the tier-assignment rows visible to the caller with tier name and assignment source; use it to see which plan is stored for a tenant.",
+      }),
+    );
     r.queryHandler(getActiveTierQuery);
 
     // \u2500\u2500 Manueller Tier-Grant (SystemAdmin, ohne Billing) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
@@ -226,6 +244,8 @@ export function createTierEngineFeature<
     r.queryHandler(
       defineQueryHandler({
         name: "tier-options",
+        description:
+          "Returns the tier names the application defines in its tier map; use it to find out which values `set-tenant-tier` accepts.",
         schema: z.object({}),
         access: { roles: ["SystemAdmin"] },
         handler: async () => ({ tiers: opts.tierMap ? Object.keys(opts.tierMap) : [] }),
@@ -242,6 +262,8 @@ export function createTierEngineFeature<
       id: TIER_ADMIN_SCREEN_ID,
       type: "custom",
       renderer: { react: { __component: "TierAdminScreen" } },
+      description:
+        "Operator form that picks a tenant, shows its current tier and assigns a new one as a manual grant without a billing purchase.",
       access: { roles: ["SystemAdmin"] },
     });
 

package/src/tier-engine/handlers/active-tier.query.ts

@@ -12,6 +12,8 @@ import { z } from "zod";
 // tier-assignment-Row.
 export const getActiveTierQuery: QueryHandlerDef = {
   name: "get-active-tier",
+  description:
+    "Returns the tier-assignment row currently active for the caller's own tenant, or null when none is assigned; use it to answer which plan the caller is on.",
   schema: z.object({}),
   access: { roles: ["TenantAdmin", "SystemAdmin"] },
   handler: async (_query, ctx) => {

package/src/tier-engine/handlers/get-tenant-tier.query.ts

@@ -17,6 +17,8 @@ const tierAssignmentTable = buildEntityTable("tier-assignment", tierAssignmentEn
 
 export const getTenantTierQuery = defineQueryHandler({
   name: "get-tenant-tier",
+  description:
+    "Returns the tier-assignment of any given tenant including where it came from (manual grant, billing sync or signup default), or null; use it to look up another tenant's plan.",
   schema: z.object({ tenantId: z.string().min(1) }),
   access: { roles: ["SystemAdmin"] },
   handler: async (query, ctx) => {

package/src/tier-engine/handlers/set-tenant-tier.write.ts

@@ -55,6 +55,8 @@ export type SetTenantTierOptions = {
 export function createSetTenantTierWrite(opts: SetTenantTierOptions = {}) {
   return defineWriteHandler({
     name: "set-tenant-tier",
+    description:
+      "Assigns a tier to any tenant as a manual grant without a billing purchase, marking it so a later billing sync will not overwrite it, and applies the new feature set immediately.",
     schema: z.object({
       tenantId: z.string().min(1),
       tier: z

package/src/user/handlers/create.write.ts

@@ -46,6 +46,8 @@ export const createWrite = defineWriteHandler({
     roles: rolesInputSchema.optional(),
   }),
   access: { roles: ["system", "SystemAdmin"] },
+  description:
+    "Creates a tenant-agnostic identity record from email, display name, optional locale, timezone and global roles, refusing an email that a live user already holds; the auth features and SystemAdmins use it to onboard a person.",
   handler: async (event, ctx) => {
     if (!ctx.systemDb) {
       throw new InternalError({ message: "user:create requires r.systemScope()" });

package/src/user/handlers/detail.query.ts

@@ -11,6 +11,8 @@ import { attachTenantLabels, dbForList } from "./list.query";
 // bound to their own tenant's memberships (served by the tenant feature).
 const baseDetail = defineEntityDetailHandler("user", userEntity, {
   access: { roles: access.systemAdmin },
+  description:
+    "Loads one identity record by id for a SystemAdmin, enriched with the same derived `tenants` membership label as the user list; tenant-level admins do not reach it.",
 });
 
 // Same tenants enrichment as user:list — derived field placeholder is "".

package/src/user/handlers/find-for-auth.query.ts

@@ -28,6 +28,7 @@ export const findForAuthQuery = defineQueryHandler({
       { message: "exactly one of email or id must be set" },
     ),
   access: { roles: access.system },
+  agent: { expose: false },
   handler: async (query, ctx) => {
     // Soft-deleted rows can now share an email with a live row (the partial
     // bidx unique index covers live rows only), so the email arm must resolve

package/src/user/handlers/list.query.ts

@@ -13,6 +13,8 @@ import { userEntity } from "../schema/user";
 
 const baseList = defineEntityListHandler("user", userEntity, {
   access: { roles: access.systemAdmin },
+  description:
+    "Lists identity records across every tenant for a SystemAdmin roster, each row carrying a derived `tenants` label naming the tenants the user belongs to and their roles there.",
 });
 
 type MembershipRow = { userId: unknown; tenantId: unknown; roles?: unknown };

package/src/user/handlers/me.query.ts

@@ -12,6 +12,8 @@ export const meQuery = defineQueryHandler({
   name: "user:me",
   schema: z.object({}),
   access: { openToAll: true },
+  description:
+    "Returns the signed-in caller's own identity record, with the password hash stripped by field-level read access; use it whenever the current user's own profile data is needed.",
   handler: async (query, ctx) => {
     if (!ctx.systemDb) {
       throw new InternalError({ message: "user:me requires r.systemScope()" });

package/src/user/handlers/update.write.ts

@@ -41,6 +41,8 @@ export const updateWrite = defineWriteHandler({
     }),
   }),
   access: { openToAll: true },
+  description:
+    "Changes a user's display name, locale, timezone, email, verification flag, last active tenant or global roles against the version the caller read; callers may edit themselves, while editing someone else or granting roles needs a privileged actor.",
   handler: async (event, ctx) => {
     const isSelf = event.payload.id === event.user.id;
     const isPrivileged = hasAccess(event.user, { roles: access.privileged });

package/src/user/schema/user.ts

@@ -58,6 +58,8 @@ const USER_STATUS_OPTIONS = [
 // User entity — tenant-agnostic. A single user can belong to multiple tenants
 // via tenantMemberships. No tenantId column on this table.
 export const userEntity = createEntity({
+  description:
+    "A person's platform-wide identity: login email and credentials, display name, locale and time zone, account status and global roles, shared across every tenant they belong to.",
   table: "read_users",
   softDelete: true,
   // Tenant-independent identity aggregate — its event stream lives on

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

@@ -299,6 +299,8 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
       renderer: { react: { __component: "PrivacyCenterScreen" } },
       access: { openToAll: true },
       dormant: true,
+      description:
+        "Logged-in GDPR self-service page where a user requests and downloads a data export (Art. 20), restricts processing of their account (Art. 18) and requests its deletion (Art. 17).",
     });
 
     // Magic-link path (anonymous): the email link carries the token as a

package/src/user-data-rights/handlers/cancel-deletion.write.ts

@@ -21,6 +21,8 @@ export const cancelDeletionWrite = defineWriteHandler({
   name: "cancel-deletion",
   schema: z.object({}),
   access: { openToAll: true },
+  description:
+    "Withdraws the calling user's own pending account-deletion request and puts the account back to active, accepted only while the grace period is still running.",
   handler: async (event, ctx) => {
     // ctx.db.raw (kein TenantDb-Wrapper) weil User-Entity tenant-agnostisch
     // ist — siehe request-deletion.write.ts fuer die Begruendung. Cancel

package/src/user-data-rights/handlers/confirm-deletion-by-token.write.ts

@@ -50,6 +50,7 @@ export function createConfirmDeletionByTokenHandler(opts: ConfirmDeletionByToken
     name: "confirm-deletion-by-token",
     schema: z.object({ token: z.string().min(1) }),
     access: { roles: ["anonymous", "Member", "User", "TenantAdmin", "SystemAdmin"] },
+    agent: { expose: false },
     rateLimit: { per: "ip", limit: 10, windowSeconds: 60 },
     handler: async (event, ctx) => {
       if (!opts.deletionTokenSecret) return writeFailure(invalidToken());

package/src/user-data-rights/handlers/download-attempt-list.query.ts

@@ -7,5 +7,10 @@ import { downloadAttemptEntity } from "../schema/download-attempt";
 export const downloadAttemptListQuery = defineEntityListHandler(
   "download-attempt",
   downloadAttemptEntity,
-  { access: { roles: access.systemAdmin }, crossTenant: true },
+  {
+    access: { roles: access.systemAdmin },
+    crossTenant: true,
+    description:
+      "Lists invalid export-download attempts across every tenant for the system-admin inspector screen; list-download-attempts is the filterable view scoped to a single tenant.",
+  },
 );

package/src/user-data-rights/handlers/download-by-job.query.ts

@@ -61,6 +61,8 @@ export const downloadByJobQuery = defineQueryHandler({
     jobId: z.string().min(1, "jobId required"),
   }),
   access: { openToAll: true }, // openToAll = auth-required, kein anonymous
+  description:
+    "Returns a short-lived signed download URL for the calling user's own finished data-export job named by job id, backing the download button in the privacy center once export-status reports the job done.",
   handler: async (query, ctx) => {
     const T = getTemporal();
     const now = T.Now.instant();

package/src/user-data-rights/handlers/download-by-token.query.ts

@@ -74,6 +74,7 @@ export const downloadByTokenQuery = defineQueryHandler({
       .optional(),
   }),
   access: { roles: ["anonymous", "Member", "User", "TenantAdmin", "SystemAdmin"] },
+  agent: { expose: false },
   // Brute-Force-Schutz fuer Token-Hash-Probing. Anonymous-Endpoint mit
   // 32-byte-Random-Token = 256 Bit Search-Space, aber rate-limit als
   // defense-in-depth + Schutz gegen Storm-Patterns die DB-Last erzeugen.