@cosmicdrift/kumiko-bundled-features 0.236.0 → 0.237.0

package/src/compliance-profiles/handlers/for-tenant.query.ts

@@ -20,6 +20,8 @@ export const forTenantQuery = defineQueryHandler({
   name: "for-tenant",
   schema: z.object({}),
   access: { openToAll: true },
+  description:
+    "Returns the effective compliance profile for the caller's tenant with any tenant override merged in, falling back to minimal-no-region plus a no-profile-selected warning when the tenant has not picked one yet.",
   handler: async (query, ctx): Promise<EffectiveComplianceProfile> => {
     const row = (await fetchOne(ctx.db, tenantComplianceProfileTable, {
       tenantId: query.user.tenantId,

package/src/compliance-profiles/handlers/list-profiles.query.ts

@@ -17,6 +17,8 @@ export const listProfilesQuery = defineQueryHandler({
   name: "list-profiles",
   schema: z.object({}),
   access: { openToAll: true },
+  description:
+    "Lists the compliance profiles a tenant can choose from (key, region, label, supervisory-authority contact, notification languages), for rendering the onboarding profile picker; the minimal-no-region fallback is excluded because it is not selectable.",
   handler: async (): Promise<{ profiles: readonly ComplianceProfileSummary[] }> => {
     return {
       profiles: SELECTABLE_PROFILE_KEYS.map(toSummary),

package/src/compliance-profiles/handlers/needs-profile.query.ts

@@ -29,6 +29,8 @@ export function createNeedsProfileQuery(pickerReachableRoles: readonly string[])
     name: "needs-profile",
     schema: z.object({}),
     access: { roles: [ROLES.TenantAdmin] },
+    description:
+      "Answers whether the calling tenant admin still has to pick a compliance profile, for the onboarding banner in their own tenant; reports needsSelection false once a profile exists or when the caller's roles cannot reach the picker screen.",
     handler: async (query, ctx): Promise<NeedsProfileResponse> => {
       const row = (await fetchOne(ctx.db, tenantComplianceProfileTable, {
         tenantId: query.user.tenantId,

package/src/compliance-profiles/handlers/set-profile.write.ts

@@ -59,6 +59,8 @@ export const setProfileWrite = defineWriteHandler({
   // SystemAdmin kann Profile fuer Customer-Setup setzen (Plattform-
   // Operator-Pfad). TenantAdmin nur fuer eigenen Tenant.
   access: { roles: access.admin },
+  description:
+    "Sets or replaces a tenant's compliance profile key plus an optional JSON override, for onboarding or a later region change; a system admin may target a different tenant through tenantIdOverride.",
   handler: async (event, ctx) => {
     const tenantOverride = event.payload.tenantIdOverride;
     const overrideDenied = crossTenantOverrideDenied(

package/src/compliance-profiles/handlers/sub-processors.query.ts

@@ -25,6 +25,8 @@ export const subProcessorsQuery = defineQueryHandler({
   name: "sub-processors",
   schema: z.object({}),
   access: { roles: ["anonymous", "Member", "User", "TenantAdmin", "SystemAdmin"] },
+  description:
+    "Returns the publicly readable Kumiko sub-processor list split into active and planned entries, for the GDPR Art. 28(2) disclosure a privacy policy or data-processing agreement links to.",
   handler: async (): Promise<SubProcessorListResponse> => {
     return {
       active: [...getActiveSubProcessors()],

package/src/compliance-profiles-ops/handlers/tenants-missing-profile.query.ts

@@ -20,6 +20,8 @@ export const tenantsMissingProfileQuery = defineQueryHandler({
   name: "tenants-missing-profile",
   schema: z.object({}),
   access: { roles: [ROLES.SystemAdmin] },
+  description:
+    "Lists every enabled tenant that has never selected a compliance profile, for the platform operator sweeping the whole installation; needs-profile answers the same question but only for the caller's own tenant.",
   handler: async (_query, ctx): Promise<TenantsMissingProfileResponse> => {
     if (!ctx.systemDb) {
       throw new InternalError({

package/src/config/handlers/cascade.query.ts

@@ -11,6 +11,8 @@ import { hasConfigAccess } from "../write-helpers";
 
 export const cascadeQuery = defineQueryHandler({
   name: "cascade",
+  description:
+    "Shows, per config key the caller may read, the value at every cascade level (user, tenant, system, app override, default) and which level won; use it to explain where a setting's current value comes from.",
   schema: z.object({
     keys: z.array(z.string()).optional(),
   }),

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

@@ -127,6 +127,8 @@ export async function collectMissingRequiredConfig(
 // about secrets. readiness:query:status (readiness feature) rolls both up.
 export const readinessQuery = defineQueryHandler({
   name: "readiness",
+  description:
+    "Lists the required config keys that are still unset for the caller's tenant, each with its scope and type; use it to find out what is missing before a feature can run.",
   schema: z.object({}),
   // Per-key read access enforced via hasConfigAccess inside the handler.
   access: { openToAll: true },

package/src/config/handlers/reset.write.ts

@@ -18,6 +18,9 @@ const executor = createEventStoreExecutor(configValuesTable, configValueEntity,
 
 export const resetWrite = defineWriteHandler({
   name: "reset",
+  description:
+    "Removes the stored config value for one key at the given scope so the key falls back to the next cascade level, and permanently deletes the stored credential for secrets-backed keys.",
+  agent: { risk: "high" },
   schema: z.object({
     key: z.string(),
     scope: scopeEnum.optional(),

package/src/config/handlers/schema.query.ts

@@ -4,6 +4,8 @@ import { hasConfigAccess } from "../write-helpers";
 
 export const schemaQuery = defineQueryHandler({
   name: "schema",
+  description:
+    "Returns the definitions of all config keys the caller may read (scope, type, default, bounds, required flag) without any values; use it to discover which settings exist and how they may be set.",
   schema: z.object({}),
   // Per-key read access enforced via hasConfigAccess inside the handler.
   access: { openToAll: true },

package/src/config/handlers/set.write.ts

@@ -36,6 +36,8 @@ const executor = createEventStoreExecutor(configValuesTable, configValueEntity,
 
 export const setWrite = defineWriteHandler({
   name: "set",
+  description:
+    "Stores a config value for one key at the requested scope (user, tenant or system) after type, bounds and pattern validation, encrypting it when the key declares that; use it to change a setting.",
   schema: z.object({
     key: z.string(),
     value: z.union([z.string(), z.number(), z.boolean()]),

package/src/config/handlers/values.query.ts

@@ -12,6 +12,8 @@ import { hasConfigAccess } from "../write-helpers";
 
 export const valuesQuery = defineQueryHandler({
   name: "values",
+  description:
+    "Returns the effective value, scope and winning source for every config key the caller may read, with encrypted and secret-backed values masked; use it to inspect the current settings.",
   schema: z.object({}),
   // Per-key read access enforced via hasConfigAccess inside the handler.
   access: { openToAll: true },

package/src/crypto-shredding/handlers/forget-subject.write.ts

@@ -187,6 +187,9 @@ export const forgetSubjectWrite = defineWriteHandler({
   name: "forget-subject",
   schema: forgetSubjectSchema,
   access: { roles: [ROLES.DataProtectionOfficer, ROLES.SystemAdmin] },
+  description:
+    "Irreversibly crypto-shreds one user or tenant subject by erasing its encryption key, nulling its blind indexes, purging its search documents and closing the user's login, for supervisory-authority requests and operator recovery outside the automated Art. 17 cleanup pipeline.",
+  agent: { risk: "high" },
   handler: async (event, ctx) => {
     const kms = configuredPiiSubjectKms();
     if (!kms) {

package/src/custom-fields/entity.ts

@@ -36,6 +36,8 @@ import {
 //     columns + events.
 export const fieldDefinitionEntity = createEntity({
   table: "read_custom_field_definitions",
+  description:
+    "One custom-field definition: the host entity it extends, the field key, its type and required/searchable flags, a display order, and the serialized field builder that carries the type options, default value and labels. Rows owned by the system tenant apply to every tenant; all others belong to the tenant that defined them.",
   // softDelete is required, NOT cosmetic: the aggregate-id is deterministic
   // (uuidv5(tenantId|entityName|fieldKey)), so deleting a definition leaves a
   // (created+deleted) event stream under that id. A hard delete would force the

package/src/custom-fields/feature.ts

@@ -163,6 +163,8 @@ function registerCustomFields(
   r.queryHandler(
     defineEntityListHandler("field-definition", fieldDefinitionEntity, {
       access: { roles: variant.fieldDefinitionListRoles },
+      description:
+        "Lists the custom-field definitions of the caller's own tenant; use it to discover which extra fields an entity accepts before setting or clearing a value on it.",
     }),
   );
 

package/src/custom-fields/handlers/clear-custom-field.write.ts

@@ -27,6 +27,8 @@ export const clearCustomFieldHandler: WriteHandlerDef = {
   name: "clear-custom-field",
   schema: clearCustomFieldPayloadSchema,
   access: { roles: DEFAULT_VALUE_WRITE_ROLES },
+  description:
+    "Removes the stored value of one custom field from a single host entity row after re-checking that field's per-field write roles; use it to blank a field the user emptied instead of writing a null value.",
   handler: async (event, ctx) => {
     const payload = event.payload as ClearCustomFieldPayload; // @cast-boundary engine-payload
 

package/src/custom-fields/handlers/define-system-field.write.ts

@@ -19,6 +19,8 @@ export const defineSystemFieldHandler: WriteHandlerDef = {
   name: "define-system-field",
   schema: defineFieldPayloadSchema,
   access: { roles: ["SystemAdmin"] },
+  description:
+    "Creates a custom-field definition under the system tenant so every tenant inherits the field on the named entity; use it for platform-mandated fields that individual tenants may fill in but never edit or delete.",
   handler: async (event, ctx) => {
     const payload = event.payload as DefineFieldPayload; // @cast-boundary engine-payload
 

package/src/custom-fields/handlers/define-tenant-field.write.ts

@@ -53,6 +53,8 @@ export function createDefineTenantFieldHandler(
     name: "define-tenant-field",
     schema: defineFieldPayloadSchema,
     access: { roles: opts.roles ?? DEFAULT_FIELD_DEFINITION_WRITE_ROLES },
+    description:
+      "Creates a custom-field definition owned by the caller's own tenant on the named entity, rejecting the write once the tenant's definition quota is reached; use it when one tenant needs an extra field the other tenants must not see.",
     handler: async (event, ctx) => {
       const payload = event.payload as DefineFieldPayload; // @cast-boundary engine-payload
       const tenantId = event.user.tenantId;

package/src/custom-fields/handlers/delete-system-field.write.ts

@@ -14,6 +14,9 @@ export const deleteSystemFieldHandler: WriteHandlerDef = {
   name: "delete-system-field",
   schema: deleteFieldPayloadSchema,
   access: { roles: ["SystemAdmin"] },
+  description:
+    "Deletes a system-tenant custom-field definition and cascades an event that strips the now-orphaned values out of every tenant's host rows; use it to retire a platform-wide field for all tenants at once.",
+  agent: { risk: "high" },
   handler: async (event, ctx) => {
     const payload = event.payload as DeleteFieldPayload; // @cast-boundary engine-payload
 

package/src/custom-fields/handlers/delete-tenant-field.write.ts

@@ -31,6 +31,9 @@ export function createDeleteTenantFieldHandler(
     name: "delete-tenant-field",
     schema: deleteFieldPayloadSchema,
     access: { roles: opts.roles ?? DEFAULT_FIELD_DEFINITION_WRITE_ROLES },
+    description:
+      "Deletes one of the caller's own tenant's custom-field definitions and cascades an event that strips its orphaned values out of that tenant's host rows; use it to retire a field this tenant defined itself.",
+    agent: { risk: "high" },
     handler: async (event, ctx) => {
       const payload = event.payload as DeleteFieldPayload; // @cast-boundary engine-payload
       const tenantId = event.user.tenantId;

package/src/custom-fields/handlers/set-custom-field.write.ts

@@ -50,6 +50,8 @@ export const setCustomFieldHandler: WriteHandlerDef = {
   name: "set-custom-field",
   schema: setCustomFieldPayloadSchema,
   access: { roles: DEFAULT_VALUE_WRITE_ROLES },
+  description:
+    "Stores one custom-field value on a single host entity row after validating it against the field definition's declared type and per-field write roles; use it to save what a user entered into a custom field.",
   handler: async (event, ctx) => {
     const payload = event.payload as SetCustomFieldPayload; // @cast-boundary engine-payload
 

package/src/custom-fields/handlers/update-tenant-field.write.ts

@@ -43,6 +43,8 @@ export function createUpdateTenantFieldHandler(
     name: "update-tenant-field",
     schema: updateFieldPayloadSchema,
     access: { roles: opts.roles ?? DEFAULT_FIELD_DEFINITION_WRITE_ROLES },
+    description:
+      "Replaces a tenant-owned custom-field definition with a complete new spec while refusing any change to the field's type; use it to relabel or re-constrain an existing field rather than to create or remove one.",
     handler: async (event, ctx) => {
       const payload = event.payload as UpdateFieldPayload; // @cast-boundary engine-payload
       const tenantId = event.user.tenantId;

package/src/data-retention/handlers/policy-for.query.ts

@@ -23,6 +23,8 @@ export const policyForQuery = defineQueryHandler({
     entityName: z.string().min(1).max(100),
   }),
   access: { openToAll: true },
+  description:
+    "Resolves the effective retention policy for one entity name in the caller's tenant (keep-for duration plus delete or anonymize strategy) by layering the entity default, tenant preset and tenant override, so a forget flow or cleanup job knows how that data may be removed.",
   handler: async (query, ctx): Promise<EffectiveRetentionPolicy> => {
     const entityName = query.payload.entityName;
 

package/src/delivery/handlers/log.query.ts

@@ -75,6 +75,8 @@ export const logQuery = definePagedQueryHandler({
     sortDirection: z.enum(["asc", "desc"]).optional(),
   }),
   access: { roles: access.admin },
+  description:
+    "Pages through recorded delivery attempts (notification type, channel, recipient, status, error, priority) for the caller's tenant, or across all tenants for a SystemAdmin; use it to investigate whether and why a notification reached someone.",
   handler: async (query, ctx) => {
     if (!ctx.systemDb) {
       throw new InternalError({ message: "delivery log handler requires ctx.systemDb" });

package/src/delivery/handlers/preferences.query.ts

@@ -8,6 +8,8 @@ export const preferencesQuery = defineQueryHandler({
   name: "preferences",
   schema: z.object({}),
   access: { openToAll: true },
+  description:
+    "Returns the calling user's notification preference rows for their own tenant; use it to show which notification types and channels that user has enabled or muted.",
   handler: async (query, ctx) => {
     // delivery runs in system-scope, so ctx.db is not auto-tenant-filtered —
     // userId alone is not tenant-unique, so a userId-only filter here leaked preferences cross-tenant.

package/src/delivery/handlers/set-preference.write.ts

@@ -12,6 +12,8 @@ export const setPreferenceWrite = defineWriteHandler({
   }),
   // Every user manages their own preferences; tenant+user scoping is on the WHERE.
   access: { openToAll: true },
+  description:
+    "Enables or disables one notification type and channel combination for the calling user, where either side may be the wildcard * as a catch-all; use it when a user changes their own notification settings.",
   handler: async (event, ctx) => {
     const { notificationType, channel, enabled } = event.payload;
     const { id: userId, tenantId } = event.user;

package/src/feature-toggles/handlers/list.query.ts

@@ -10,6 +10,8 @@ import { globalFeatureStateTable } from "../global-feature-state-table";
 // effective state (registered features + their current override, if any).
 export const listQuery = defineQueryHandler({
   name: "list",
+  description:
+    "Lists only the features that carry an explicit platform-wide on/off override, with who flipped it and when; use it to see which toggles were changed away from their default.",
   schema: z.object({}),
   access: { roles: ["SystemAdmin"] },
   handler: async (_event, ctx) => {

package/src/feature-toggles/handlers/registered.query.ts

@@ -20,6 +20,8 @@ function formatFlag(value: boolean | null): string {
 
 export const registeredQuery = defineQueryHandler({
   name: "registered",
+  description:
+    "Lists every registered feature with whether it is toggleable, its default, its explicit override, its dependencies and its effective on/off state; use it as the full feature inventory.",
   schema: z.object({}),
   access: { roles: ["SystemAdmin"] },
   handler: async (_event, ctx) => {

package/src/feature-toggles/handlers/set.write.ts

@@ -34,6 +34,8 @@ import type { GlobalFeatureToggleRuntime } from "../toggle-runtime";
 export function createSetWriteHandler(getRuntime: (() => GlobalFeatureToggleRuntime) | undefined) {
   return defineWriteHandler({
     name: "set",
+    description:
+      "Turns one registered, toggleable feature on or off platform-wide and applies the flip immediately; use it to enable or disable a feature for the whole installation.",
     schema: z.object({
       featureName: z.string().min(1),
       enabled: z.boolean(),

package/src/file-derivatives/handlers/public-variant.query.ts

@@ -75,6 +75,7 @@ export const publicVariantQuery = defineQueryHandler({
     variant: z.string().min(1).max(64),
   }),
   access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
+  agent: { expose: false },
   // ponytail: "ip" trusts the first x-forwarded-for hop (buildRequestContextData
   // in request-id-middleware.ts) — this is the ONLY throttle on an anonymous,
   // internet-facing render/storage-cost route, so it assumes the deployment's

package/src/folders/entity.ts

@@ -7,6 +7,8 @@ import { createEntity, createTextField } from "@cosmicdrift/kumiko-framework/eng
 // tenant-scoped.
 export const folderEntity = createEntity({
   table: "read_folders",
+  description:
+    "One folder of a tenant's hierarchical catalog: a name plus an optional parentId pointing at another folder, so the rows together form a tree whose roots have no parent.",
   fields: {
     name: createTextField({ required: true, maxLength: 64 }),
     // Parent folder id, or absent for a root folder. No FK (event-sourced); a
@@ -32,6 +34,8 @@ export const folderEntity = createEntity({
 //   - entities in a folder  → list assignments filter { field: "folderId", op: "eq" }
 export const folderAssignmentEntity = createEntity({
   table: "read_folder_assignments",
+  description:
+    "The membership row recording which folder one host entity, addressed by entityType and entityId, is filed in. At most one row exists per entity, so filing it elsewhere changes this row's folderId rather than adding a second.",
   softDelete: true,
   fields: {
     folderId: createTextField({ required: true, maxLength: 64 }),

package/src/folders/feature.ts

@@ -58,18 +58,48 @@ function registerFolders(
 
   // Folder catalog — plain CRUD, no custom logic. update is rename (and, in a
   // later stage, reparent: it accepts changes.parentId, optimistic-locked).
-  r.writeHandler(defineEntityCreateHandler("folder", folderEntity, { access }));
-  r.writeHandler(defineEntityUpdateHandler("folder", folderEntity, { access }));
+  r.writeHandler(
+    defineEntityCreateHandler("folder", folderEntity, {
+      access,
+      description:
+        "Creates a folder in the caller's tenant folder tree, optionally nested under a parent folder; use it to grow the folder catalog, not to file an entity into a folder.",
+    }),
+  );
+  r.writeHandler(
+    defineEntityUpdateHandler("folder", folderEntity, {
+      access,
+      description:
+        "Renames a folder or moves it under a different parent folder; use it to reorganise the catalog itself, which leaves the entities filed in that folder where they are.",
+    }),
+  );
   // Custom, not defineEntityDeleteHandler: blocks the delete when folder-
   // assignments still point at this folder (658/1) — see delete-folder.write.ts.
   r.writeHandler(createDeleteFolderHandler(access));
-  r.queryHandler(defineEntityListHandler("folder", folderEntity, { access }));
-  r.queryHandler(defineEntityDetailHandler("folder", folderEntity, { access }));
+  r.queryHandler(
+    defineEntityListHandler("folder", folderEntity, {
+      access,
+      description:
+        "Lists the caller's tenant folders with their names and parent ids so the whole folder tree can be reassembled; use it to render a folder tree or to let a user pick a folder.",
+    }),
+  );
+  r.queryHandler(
+    defineEntityDetailHandler("folder", folderEntity, {
+      access,
+      description:
+        "Reads one folder of the caller's tenant by id, returning its name and parent id; use it to confirm a folder id is real before filing something into it.",
+    }),
+  );
 
   // Single-membership assignment — hand-written (deterministic id + move/restore).
   r.writeHandler(createSetFolderHandler(access));
   r.writeHandler(createClearFolderHandler(access));
-  r.queryHandler(defineEntityListHandler("folder-assignment", folderAssignmentEntity, { access }));
+  r.queryHandler(
+    defineEntityListHandler("folder-assignment", folderAssignmentEntity, {
+      access,
+      description:
+        "Lists the folder-membership rows of the caller's tenant; filter on entityId to learn which folder one entity sits in, or on folderId to list everything filed into a folder.",
+    }),
+  );
 }
 
 export const foldersFeature = defineFeature(FOLDERS_FEATURE_NAME, (r) =>

package/src/folders/handlers/clear-folder.write.ts

@@ -14,6 +14,8 @@ export function createClearFolderHandler(
     name: "clear-folder",
     schema: clearFolderPayloadSchema,
     access,
+    description:
+      "Unfiles a host entity so it sits in no folder at all, reporting success when it was already unfiled; use it to take an entity out of its folder without touching the folder itself.",
     handler: async (event, ctx) => {
       const payload = event.payload as ClearFolderPayload; // @cast-boundary engine-payload
       const id = folderAssignmentAggregateId(

package/src/folders/handlers/delete-folder.write.ts

@@ -20,6 +20,9 @@ export function createDeleteFolderHandler(
     name: "folder:delete",
     schema: deleteFolderPayloadSchema,
     access,
+    description:
+      "Deletes a folder from the tenant catalog and refuses while any entity is still filed in it; use it once that folder's contents have been unfiled or moved elsewhere.",
+    agent: { risk: "high" },
     handler: async (event, ctx) => {
       const payload = event.payload as { id: string }; // @cast-boundary engine-payload
       const assigned = await folderAssignmentExecutor.list(

package/src/folders/handlers/set-folder.write.ts

@@ -30,6 +30,8 @@ export function createSetFolderHandler(
     name: "set-folder",
     schema: setFolderPayloadSchema,
     access,
+    description:
+      "Files a host entity into one existing folder and moves it out of whatever folder it was in, since an entity belongs to at most one folder; use it for both the first filing and every later move.",
     handler: async (event, ctx) => {
       const payload = event.payload as SetFolderPayload; // @cast-boundary engine-payload
       const id = folderAssignmentAggregateId(

package/src/form-draft/handlers/discard.write.ts

@@ -27,6 +27,9 @@ export const discardDraftWrite = defineWriteHandler({
   name: "discard",
   schema: discardDraftPayloadSchema,
   access: FORM_DRAFT_ACCESS,
+  description:
+    "Deletes the calling user's draft for one draftKey and, when releaseFiles is set, hard-deletes the file references that draft alone uploaded; use it after a successful submit or when the user abandons the form.",
+  agent: { risk: "high" },
   handler: async (event, ctx) => {
     const ownerId = event.user.id;
     const existing = await lookupDraft(

package/src/form-draft/handlers/get.query.ts

@@ -14,6 +14,8 @@ export const getDraftQuery = defineQueryHandler({
   name: "get",
   schema: getDraftPayloadSchema,
   access: FORM_DRAFT_ACCESS,
+  description:
+    "Returns the calling user's saved draft blob (form values and step index) for one draftKey, or null when they have no such draft; use it to resume an in-progress form.",
   handler: async (query, ctx): Promise<GetDraftResult> => {
     const row = await lookupDraft(
       ctx.db,

package/src/form-draft/handlers/list.query.ts

@@ -29,6 +29,8 @@ export const listDraftsQuery = defineQueryHandler({
   name: "list",
   schema: listDraftsPayloadSchema,
   access: FORM_DRAFT_ACCESS,
+  description:
+    "Lists the calling user's open drafts for one screenId as id, draftKey, stepIndex and savedAt (newest first, without the form values); use it to let a user pick which draft to resume when the client lost the draftId.",
   handler: async (query, ctx): Promise<ListDraftsResult> => {
     const rows = await listDraftsByScreen(
       ctx.db,

package/src/form-draft/handlers/save.write.ts

@@ -35,6 +35,8 @@ export const saveDraftWrite = defineWriteHandler({
   name: "save",
   schema: saveDraftPayloadSchema,
   access: FORM_DRAFT_ACCESS,
+  description:
+    "Upserts the calling user's draft for one draftKey with the given form values and step index, stamping savedAt server-side and refusing a brand-new draft once the per-owner draft cap is reached; use it to persist an in-progress form before the real entity exists.",
   handler: async (event, ctx) => {
     const ownerId = event.user.id;
     const { draftKey, values, stepIndex } = event.payload;

package/src/inbound-mail-foundation/handlers/connect-account.write.ts

@@ -57,6 +57,8 @@ export const connectAccountHandler: WriteHandlerDef = {
   name: "connect-account",
   schema: connectAccountSchema,
   access: { roles: ["SystemAdmin", "TenantAdmin"] },
+  description:
+    "Registers a mailbox for the tenant (provider, auth method, display name, encrypted address, shared or personal) and returns the new accountId that also keys its credential slot; use it to start a mail connection, credentials and the first connection test happen outside this call.",
   handler: async (event, ctx) => {
     // @cast-boundary engine-payload — dispatcher-zod-validated payload
     const payload = event.payload as ConnectAccountPayload;

package/src/inbound-mail-foundation/handlers/disconnect-account.write.ts

@@ -29,6 +29,9 @@ export const disconnectAccountHandler: WriteHandlerDef = {
   name: "disconnect-account",
   schema: disconnectAccountSchema,
   access: { roles: ["SystemAdmin", "TenantAdmin"] },
+  description:
+    "Puts a connected mailbox into the final disconnected state so the watch supervisor stops fetching it, keeping the stream for audit and requiring a fresh connect to resume; use it to stop mail ingestion for one mailbox.",
+  agent: { risk: "high" },
   handler: async (event, ctx) => {
     // @cast-boundary engine-payload — dispatcher-zod-validated payload
     const payload = event.payload as DisconnectAccountPayload;

package/src/inbound-mail-foundation/handlers/ingest-message.write.ts

@@ -110,6 +110,7 @@ export const ingestMessageHandler: WriteHandlerDef = {
   name: "ingest-message",
   schema: ingestMessageSchema,
   access: { roles: ["SystemAdmin"] },
+  agent: { expose: false },
   handler: async (event, ctx) => {
     // @cast-boundary engine-payload — dispatcher-zod-validated payload
     const payload = event.payload as IngestMessagePayload;

package/src/inbound-mail-foundation/handlers/list-accounts.query.ts

@@ -25,6 +25,8 @@ export const listAccountsQuery: QueryHandlerDef = {
   name: "account:list",
   schema: listAccountsSchema,
   access: { roles: ["SystemAdmin", "TenantAdmin", "User"] },
+  description:
+    "Lists the connected mailboxes of the caller's tenant with the mailbox address decrypted, hiding personal mailboxes the caller neither owns nor administers; use it for the mail connect and settings views.",
   handler: async (_query, ctx) => {
     const allRows = await selectMany(ctx.db.raw, mailAccountsProjectionTable, {
       tenantId: ctx.user.tenantId,

package/src/inbound-mail-foundation/handlers/list-messages.query.ts

@@ -32,6 +32,8 @@ export const listMessagesQuery: QueryHandlerDef = {
   name: "message:list",
   schema: listMessagesSchema,
   access: { roles: ["SystemAdmin", "TenantAdmin", "User"] },
+  description:
+    "Lists received mail of the caller's tenant with sender, recipients, subject and snippet decrypted, optionally narrowed to one account, thread or folder scope and hiding messages of personal mailboxes the caller neither owns nor administers; use it to read an inbox or a conversation.",
   handler: async (query, ctx) => {
     // @cast-boundary engine-payload — dispatcher-zod-validated payload
     const payload = query.payload as ListMessagesPayload;

package/src/inbound-mail-foundation/handlers/update-account.write.ts

@@ -37,6 +37,8 @@ export const updateAccountHandler: WriteHandlerDef = {
   name: "update-account",
   schema: updateAccountSchema,
   access: { roles: ["SystemAdmin", "TenantAdmin"] },
+  description:
+    "Records a status, watch-state or display-name change on a connected mailbox as a new snapshot with an audit reason, rejecting any change to an already disconnected mailbox; use it to flag an auth error or to re-activate a mailbox after fixing its credentials.",
   handler: async (event, ctx) => {
     // @cast-boundary engine-payload — dispatcher-zod-validated payload
     const payload = event.payload as UpdateAccountPayload;

package/src/jobs/feature.ts

@@ -114,6 +114,8 @@ export function createJobsFeature(options: JobsFeatureOptions = {}): FeatureDefi
       id: JOB_RUNS_SCREEN_ID,
       type: "custom",
       renderer: { react: { __component: "JobRunsScreen" } },
+      description:
+        "Operator table of recent job runs with status filters, plus a panel to trigger a manual job with a payload; open it to monitor background jobs and start one.",
       access: systemAdminAccess,
     });
     // kumiko-lint-ignore app-feature-structure Phase-3 conversion tracked in #2312
@@ -121,6 +123,8 @@ export function createJobsFeature(options: JobsFeatureOptions = {}): FeatureDefi
       id: JOB_RUN_DETAIL_SCREEN_ID,
       type: "custom",
       renderer: { react: { __component: "JobRunDetailScreen" } },
+      description:
+        "Detail view of one job run with status, timings, error and log lines, and a retry action for failed runs; reached from a row of the job-runs list.",
       listScreenId: JOB_RUNS_SCREEN_ID,
       access: systemAdminAccess,
     });

package/src/jobs/handlers/catalog.query.ts

@@ -22,6 +22,8 @@ function payloadSchemaJson(job: JobDefinition): Record<string, unknown> | null {
 /** SystemAdmin catalog of jobs that may be started via `jobs:write:trigger`. */
 export const catalogQuery = defineQueryHandler({
   name: "catalog",
+  description:
+    "Lists the jobs that may be started manually, each with its per-tenant flag and payload JSON Schema; use it to find out which job can be triggered and what payload it expects.",
   schema: z.object({}),
   access: { roles: ["SystemAdmin"] },
   handler: async (_query, ctx): Promise<{ rows: readonly ManualJobCatalogEntry[] }> => {

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

@@ -12,6 +12,8 @@ const KMS_POOL_CONCURRENCY = 4;
 
 export const detailQuery = defineQueryHandler({
   name: "details",
+  description:
+    "Returns one job run across all tenants by its run id with status, timings, decrypted payload, error and its full log lines; use it to investigate why a run failed.",
   // Post-ES: runId is the uuid aggregate-id of the jobRun event-stream.
   // Pre-ES callers passed the serial row-id; the migration is breaking
   // for API callers (intentional — jobs is framework-ops, no external

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

@@ -23,6 +23,8 @@ async function decryptRunRow<T extends Record<string, unknown>>(row: T): Promise
 
 export const listQuery = defineQueryHandler({
   name: "list",
+  description:
+    "Lists job runs across all tenants newest-first, optionally filtered by job name and status; use it to check whether a job ran and whether it succeeded.",
   schema: z.object({
     jobName: z.string().optional(),
     status: z.enum(["queued", "running", "completed", "failed"]).optional(),

package/src/jobs/handlers/retry.write.ts

@@ -23,6 +23,8 @@ type JobRunRow = {
 
 export const retryWrite = defineWriteHandler({
   name: "retry",
+  description:
+    "Re-dispatches a failed job run with its original payload and triggering user; use it to rerun a job that failed for a transient reason.",
   // Post-ES: runId is the uuid aggregate-id. See detail.query for the
   // rationale — jobs is framework-ops, callers are admin tooling only.
   schema: z.object({ runId: z.uuid() }),

package/src/jobs/handlers/trigger.write.ts

@@ -13,6 +13,8 @@ import { isManualTrigger } from "../is-manual-trigger";
 
 export const triggerWrite = defineWriteHandler({
   name: "trigger",
+  description:
+    "Starts one manually-triggerable job with the given payload after validating it against the job's schema; use it to run a maintenance or import job on demand.",
   schema: z.object({
     jobName: z.string(),
     payload: z.record(z.string(), z.unknown()).optional(),

package/src/ledger/entity.ts

@@ -16,6 +16,8 @@ import { ACCOUNT_TYPES, SCHEDULE_INTERVALS, TRANSACTION_STATUS } from "./constan
 // tenantId is a base column set by the framework → each tenant has its own books.
 export const accountEntity = createEntity({
   table: "read_ledger_accounts",
+  description:
+    "One node of a tenant's chart of accounts: a name, an asset/liability/equity/income/expense type that decides how reports read its balance, an optional account code and an optional parent account forming the account tree; balances are derived from postings, never stored here.",
   fields: {
     name: createTextField({ required: true, maxLength: 120 }),
     type: createSelectField({ options: ACCOUNT_TYPES, required: true }),
@@ -38,6 +40,8 @@ export const accountEntity = createEntity({
 // `status` carries draft|posted for the later Soll/Ist work — Phase 0 posts only.
 export const transactionEntity = createEntity({
   table: "read_ledger_transactions",
+  description:
+    "One journal entry: a booking date, a narration, an optional reference (a reversal points at the entry it corrects), a draft/posted status and the embedded posting lines of accountId plus signed minor-unit amount that must sum to zero; posted entries are immutable and corrected only by a reversing entry.",
   fields: {
     date: createDateField({ required: true }),
     // Journal narration ("Miete Januar", "Storno: …") is accounting data, not
@@ -76,6 +80,8 @@ export const transactionEntity = createEntity({
 // amount is stored positive (minor units); the confirm handler assigns the signs.
 export const scheduleEntity = createEntity({
   table: "read_ledger_schedules",
+  description:
+    "One recurring booking template: book a positive minor-unit amount from a debit account to a credit account each interval between a start date and an optional open end; it holds no bookings itself, periods become real entries only when confirmed.",
   fields: {
     description: createTextField({
       required: true,