@cosmicdrift/kumiko-bundled-features 0.236.0 → 0.237.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.236.0",
+  "version": "0.237.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>",
@@ -130,12 +130,12 @@
     "./workflow-runner": "./src/workflow-runner/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.236.0",
-    "@cosmicdrift/kumiko-framework": "0.236.0",
-    "@cosmicdrift/kumiko-headless": "0.236.0",
-    "@cosmicdrift/kumiko-renderer": "0.236.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.236.0",
-    "@cosmicdrift/kumiko-types": "0.236.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.237.0",
+    "@cosmicdrift/kumiko-framework": "0.237.0",
+    "@cosmicdrift/kumiko-headless": "0.237.0",
+    "@cosmicdrift/kumiko-renderer": "0.237.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.237.0",
+    "@cosmicdrift/kumiko-types": "0.237.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -164,7 +164,7 @@
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
     "@types/qrcode": "^1.5.5",
-    "@cosmicdrift/kumiko-locale-de": "0.236.0",
-    "@cosmicdrift/kumiko-locale-es": "0.236.0"
+    "@cosmicdrift/kumiko-locale-de": "0.237.0",
+    "@cosmicdrift/kumiko-locale-es": "0.237.0"
   }
 }

package/src/admin-shell/feature.ts

@@ -77,6 +77,8 @@ export function createAdminShellFeature(options: CreateAdminShellOptions = {}):
       type: "custom",
       renderer: { react: { __component: "TenantOverviewScreen" } },
       access: { roles: access.admin },
+      description:
+        "Landing page of the tenant-admin workspace, showing pending invitation, member and missing-config counts for the caller's own tenant so an operator sees what needs attention there.",
     });
     r.nav({
       id: "tenant-overview",
@@ -92,6 +94,8 @@ export function createAdminShellFeature(options: CreateAdminShellOptions = {}):
       type: "custom",
       renderer: { react: { __component: "PlatformOverviewScreen" } },
       access: { roles: access.systemAdmin },
+      description:
+        "Landing page of the platform-admin workspace, showing installation-wide tenant, user and failed-job counts so a system admin sees the health of the whole deployment at a glance.",
     });
     r.nav({
       id: "platform-overview",

package/src/agent-tools/__tests__/agent-doc-lint.test.ts

@@ -1,5 +1,9 @@
 import { describe, expect, test } from "bun:test";
-import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  defineFeature,
+  defineWriteHandler,
+  resolveAgentExposure,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 import { AgentDocGapKinds, findAgentDocGaps, formatAgentDocGap } from "../agent-doc-lint";
 
@@ -53,6 +57,54 @@ describe("findAgentDocGaps", () => {
     expect(findAgentDocGaps([feature])).toHaveLength(0);
   });
 
+  // defineWriteHandler rebuilds its return value from an explicit field
+  // whitelist, so a slot it forgets to copy is invisible here even though the
+  // author wrote it — that regression hid 37 bundled descriptions.
+  test("R1: description authored through defineWriteHandler survives the def rebuild", () => {
+    const feature = defineFeature("doc-gap-demo", (r) => {
+      r.writeHandler(
+        defineWriteHandler({
+          name: "do-a",
+          schema: z.object({}),
+          access: OPEN_ACCESS,
+          description: "Does A.",
+          handler: noopWriteHandler,
+        }),
+      );
+    });
+
+    expect(findAgentDocGaps([feature])).toHaveLength(0);
+  });
+
+  test("R1: agent hints authored through defineWriteHandler reach the resolved exposure", () => {
+    const optedOut = defineWriteHandler({
+      name: "do-internal",
+      schema: z.object({}),
+      access: OPEN_ACCESS,
+      agent: { expose: false },
+      handler: noopWriteHandler,
+    });
+    const destructive = defineWriteHandler({
+      name: "do-destroy",
+      schema: z.object({}),
+      access: OPEN_ACCESS,
+      description: "Destroys the thing.",
+      agent: { risk: "high" },
+      handler: noopWriteHandler,
+    });
+
+    expect(resolveAgentExposure(optedOut, "write").expose).toBe(false);
+    expect(resolveAgentExposure(destructive, "write").risk).toBe("high");
+    expect(
+      findAgentDocGaps([
+        defineFeature("doc-gap-demo", (r) => {
+          r.writeHandler(optedOut);
+          r.writeHandler(destructive);
+        }),
+      ]),
+    ).toHaveLength(0);
+  });
+
   test("R2: custom screen without description -> exactly one gap with the correct QN", () => {
     const feature = defineFeature("doc-gap-demo", (r) => {
       r.screen({ id: "widget-editor", type: "custom", renderer: { react: "stub" } });

package/src/audit/feature.ts

@@ -44,6 +44,8 @@ export function createAuditFeature(): FeatureDefinition {
       id: AUDIT_LOG_SCREEN_ID,
       type: "custom",
       renderer: { react: { __component: "AuditLogScreen" } },
+      description:
+        "Admin table of the tenant's audit-trail events with actor names and event-type/date filters; open it to browse recent changes and drill into a single event.",
       access: { roles: access.admin },
     });
     // kumiko-lint-ignore app-feature-structure Phase-3 conversion tracked in #2312
@@ -51,6 +53,8 @@ export function createAuditFeature(): FeatureDefinition {
       id: AUDIT_LOG_DETAIL_SCREEN_ID,
       type: "custom",
       renderer: { react: { __component: "AuditLogDetailScreen" } },
+      description:
+        "Read-only detail view of one audit event showing actor, timestamp, aggregate and the raw event payload and metadata; reached from a row of the audit log.",
       listScreenId: AUDIT_LOG_SCREEN_ID,
       access: { roles: access.admin },
     });

package/src/audit/handlers/details.query.ts

@@ -9,6 +9,8 @@ import { z } from "zod";
 
 export const detailsQuery = defineQueryHandler({
   name: "details",
+  description:
+    "Returns one audit-trail event of the caller's tenant by its event-store id, with full payload and metadata; use it to inspect the exact change behind a row of the audit log list.",
   schema: z.object({
     id: z.string().regex(/^[1-9]\d*$/, "id must be a positive integer"),
   }),

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

@@ -21,6 +21,8 @@ const MAX_LIMIT = 100;
 
 export const listQuery = defineQueryHandler({
   name: "list",
+  description:
+    "Lists the tenant's audit-trail events newest-first with cursor paging, filterable by aggregate type, aggregate id, event type, actor and time range; use it to answer who changed what and when.",
   schema: z
     .object({
       before: z.string().regex(/^\d+$/, "cursor must be a positive integer").optional(),

package/src/auth-email-password/handlers/change-password.write.ts

@@ -21,6 +21,8 @@ export const changePasswordWrite = defineWriteHandler({
     newPassword: passwordSchema,
   }),
   access: { roles: access.authenticated },
+  description:
+    "Replaces the signed-in caller's own password after re-checking the current one; use it for a self-service password change rather than the emailed reset flow.",
   handler: async (event, ctx) => {
     const systemUser = createSystemUser(event.user.tenantId);
 

package/src/auth-email-password/handlers/confirm-account-unlock.write.ts

@@ -30,6 +30,7 @@ export function createConfirmAccountUnlockHandler(opts: ConfirmAccountUnlockOpti
       token: z.string().min(1),
     }),
     access: { roles: ["all"] },
+    agent: { expose: false },
     handler: async (event, ctx) => {
       if (!opts.hmacSecret) {
         return writeFailure(

package/src/auth-email-password/handlers/invite-accept-with-login.write.ts

@@ -116,6 +116,7 @@ export function createInviteAcceptWithLoginHandler(opts: InviteAcceptWithLoginOp
     name: "invite-accept-with-login",
     schema: InviteAcceptWithLoginSchema,
     access: { roles: ["all"] },
+    agent: { expose: false },
     // kumiko-lint-ignore complexity-budget reuses login.write.ts's gate chain (lockout/password/email/status/membership/mfa) plus invite-specific branches (email match, already-member check, invitation update, unburn-on-failure) — splitting would scatter gate order across functions without reducing risk
     handler: async (event, ctx) => {
       if (!ctx.redis) {

package/src/auth-email-password/handlers/invite-accept.write.ts

@@ -75,6 +75,7 @@ export function createInviteAcceptHandler() {
     // nutzen `roles: ["all"]` weil dort GUEST_USER mit ["all"]-role
     // dispatched wird.
     access: { openToAll: true },
+    agent: { expose: false },
     // kumiko-lint-ignore complexity-budget invite branches (auth/anon/burn) stay in one handler
     handler: async (event, ctx) => {
       if (!ctx.redis) {

package/src/auth-email-password/handlers/invite-create.write.ts

@@ -94,6 +94,8 @@ export function createInviteCreateHandler(opts: InviteCreateOptions) {
     name: "invite-create",
     schema: InviteCreateSchema,
     access: { roles: access.admin },
+    description:
+      "Invites an email address into the caller's tenant with a chosen membership role, creating or reusing the invitation and mailing the invitee a fresh accept link; re-inviting the same address invalidates the previous link.",
     handler: async (event, ctx) => {
       if (!ctx.redis) {
         return writeFailure(

package/src/auth-email-password/handlers/invite-signup-complete.write.ts

@@ -86,6 +86,7 @@ export function createInviteSignupCompleteHandler() {
     name: "invite-signup-complete",
     schema: InviteSignupCompleteSchema,
     access: { roles: ["all"] },
+    agent: { expose: false },
     handler: async (event, ctx) => {
       if (!ctx.redis) {
         return writeFailure(

package/src/auth-email-password/handlers/login.write.ts

@@ -263,6 +263,8 @@ export function createLoginHandler(opts: LoginHandlerOptions = {}) {
       password: z.string().min(1),
     }),
     access: { roles: ["all"] },
+    description:
+      "Signs a user in with email and password, running the lockout, email-verification, account-status, tenant-membership and MFA gates, and answering with a session or with an MFA challenge or setup requirement.",
     handler: async (event, ctx): Promise<WriteResult<LoginResult>> => {
       const systemUser = createSystemUser(SYSTEM_USER_ID);
 

package/src/auth-email-password/handlers/logout.write.ts

@@ -8,6 +8,8 @@ export const logoutWrite = defineWriteHandler({
   name: "logout",
   schema: z.object({}),
   access: { roles: access.authenticated },
+  description:
+    "Acknowledges a sign-out for the authenticated caller so the client can discard its token; the JWT is stateless, so no server-side session state changes here.",
   perform: stepsPipeline(({ r }) => [
     r.step.return({ isSuccess: true, data: { kind: "logged-out" } }),
   ]),

package/src/auth-email-password/handlers/request-account-unlock.write.ts

@@ -21,6 +21,8 @@ export function createRequestAccountUnlockHandler(opts: RequestAccountUnlockOpti
     {
       handlerName: "request-account-unlock",
       successKind: "unlock-requested",
+      description:
+        "Mails an address a signed, time-limited link that lets a user clear a failed-login lockout without an operator; it applies whether or not the account is locked right now, and answers identically for unknown addresses.",
       defaultTtlMinutes: AUTH_UNLOCK_DEFAULT_TTL_MINUTES,
       sign: signUnlockToken,
       notConfiguredError: AuthErrors.unlockNotConfigured,

package/src/auth-email-password/handlers/request-email-verification.write.ts

@@ -19,6 +19,8 @@ export function createRequestEmailVerificationHandler(opts: RequestEmailVerifica
     {
       handlerName: "request-email-verification",
       successKind: "verification-requested",
+      description:
+        "Mails an address a signed, time-limited link to confirm it owns the mailbox; an already-verified address is skipped silently, and the answer looks the same for unknown addresses either way.",
       defaultTtlMinutes: AUTH_VERIFY_DEFAULT_TTL_MINUTES,
       sign: signVerificationToken,
       notConfiguredError: AuthErrors.verificationNotConfigured,

package/src/auth-email-password/handlers/request-password-reset.write.ts

@@ -21,6 +21,8 @@ export function createRequestPasswordResetHandler(opts: RequestPasswordResetOpti
     {
       handlerName: "request-password-reset",
       successKind: "reset-requested",
+      description:
+        "Starts the emailed password-reset flow for an address by minting a signed, time-limited reset token and mailing the reset link, for any existing non-deleted account regardless of its verification state; the answer is identical for unknown addresses, so it never reveals whether an account exists.",
       defaultTtlMinutes: AUTH_RESET_DEFAULT_TTL_MINUTES,
       sign: signResetToken,
       notConfiguredError: AuthErrors.resetNotConfigured,

package/src/auth-email-password/handlers/reset-password.write.ts

@@ -26,6 +26,7 @@ export function createResetPasswordHandler(opts: ResetPasswordOptions) {
       newPassword: passwordSchema,
     }),
     access: { roles: ["all"] },
+    agent: { expose: false },
     handler: async (event, ctx) => {
       if (!opts.hmacSecret) {
         return writeFailure(

package/src/auth-email-password/handlers/self-registration-status.query.ts

@@ -14,6 +14,8 @@ export const selfRegistrationStatusQuery = defineQueryHandler({
   name: "signup-registration-status",
   schema: z.object({}),
   access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
+  description:
+    "Reports whether self-registration is currently switched on, readable without signing in, so a signup page can hide its own form instead of collecting an address that would be silently ignored.",
   handler: async (_query, ctx) => {
     // Same fail-open reasoning as signup-request.write.ts (#1468): only
     // report disabled when the toggle feature is actually composed.

package/src/auth-email-password/handlers/signup-confirm.write.ts

@@ -65,6 +65,7 @@ export function createSignupConfirmHandler() {
     name: "signup-confirm",
     schema: SignupConfirmSchema,
     access: { roles: ["all"] },
+    agent: { expose: false },
     handler: async (event, ctx) => {
       if (!ctx.redis) {
         return writeFailure(

package/src/auth-email-password/handlers/signup-request.write.ts

@@ -76,6 +76,8 @@ export function createSignupRequestHandler(opts: SignupRequestOptions) {
     name: "signup-request",
     schema: SignupRequestSchema,
     access: { roles: ["all"] },
+    description:
+      "Starts magic-link self-registration by mailing a fresh activation link to an address and invalidating any link still outstanding for it; the answer looks the same whether or not the address is already registered.",
     handler: async (event, ctx) => {
       // Silent no-op when off, matching the route's own always-200
       // anti-enumeration contract (registerTokenRequestRoute swallows every

package/src/auth-email-password/handlers/token-request-handler.ts

@@ -42,6 +42,9 @@ export type TokenRequestData<K extends string> = TokenRequestSuccess<K> | TokenR
 export type TokenRequestSpec<TName extends string, TSuccessKind extends string> = {
   readonly handlerName: TName;
   readonly successKind: TSuccessKind;
+  // Per-flow, never derived here — a shared sentence would describe the
+  // mechanism instead of the flow the agent is picking between.
+  readonly description: string;
   readonly defaultTtlMinutes: number;
   // Feature-specific sign function. Signature matches both signResetToken
   // and signVerificationToken (thin wrappers over signed-token.ts).
@@ -92,6 +95,7 @@ export function createTokenRequestHandler<TName extends string, TSuccessKind ext
     name: spec.handlerName,
     schema: RequestTokenSchema,
     access: { roles: ["all"] },
+    description: spec.description,
     handler: async (event, ctx) => {
       if (!opts.hmacSecret) {
         // Feature-factory guards this at boot; defensive here for lazy-

package/src/auth-email-password/handlers/verify-email.write.ts

@@ -27,6 +27,7 @@ export function createVerifyEmailHandler(opts: VerifyEmailOptions) {
     name: "verify-email",
     schema: VerifyEmailSchema,
     access: { roles: ["all"] },
+    agent: { expose: false },
     handler: async (event, ctx) => {
       if (!opts.hmacSecret) {
         return writeFailure(

package/src/auth-mfa/feature.ts

@@ -137,6 +137,8 @@ export function createAuthMfaFeature(opts: AuthMfaFeatureOptions): FeatureDefini
       renderer: { react: { __component: "MfaEnableScreen" } },
       access: { openToAll: true },
       dormant: true,
+      description:
+        "Self-service screen where a signed-in user enrolls in TOTP two-factor authentication: it shows the QR code and manual secret, reveals the recovery codes once, and confirms enrollment with a code from their authenticator app.",
     });
     r.translations({ keys: AUTH_MFA_FEATURE_I18N });
 

package/src/auth-mfa/handlers/disable.write.ts

@@ -31,6 +31,9 @@ export function createDisableHandler(opts: DisableOptions) {
     name: "disable",
     schema: z.object({ code: z.string().min(6).max(9) }),
     access: { openToAll: true },
+    description:
+      "Removes the caller's TOTP enrollment for good after they prove possession with a TOTP or recovery code, and signs their other sessions and access tokens out; use it when a user wants two-factor authentication turned off.",
+    agent: { risk: "high" },
     handler: async (event, ctx) => {
       const row = await findUserMfaRow(ctx.db, event.user);
       if (!row) return mfaNotEnabled();

package/src/auth-mfa/handlers/enable-confirm-preauth.write.ts

@@ -64,6 +64,8 @@ export function createEnableConfirmPreauthHandler(opts: EnableConfirmPreauthOpti
       code: z.string().length(6),
     }),
     access: { roles: ["all"] },
+    description:
+      "Completes the enrollment that unblocks a sign-in forced into two-factor setup: verifies the code against the pre-auth setup token, stores the factor and derives the session the blocked login never got.",
     handler: async (event, ctx) => {
       const verify = verifyMfaSetupToken(event.payload.setupToken, opts.setupTokenSecret);
       if (!verify.ok) return invalidSetupToken();

package/src/auth-mfa/handlers/enable-confirm.write.ts

@@ -38,6 +38,8 @@ export function createEnableConfirmHandler(opts: EnableConfirmOptions) {
       code: z.string().length(6),
     }),
     access: { openToAll: true },
+    description:
+      "Completes TOTP enrollment for the signed-in user by checking a code against the secret carried in the setup token from enable-start, then storing the factor and signing every other session and access token out.",
     handler: async (event, ctx) => {
       const verify = verifyMfaSetupToken(event.payload.setupToken, opts.setupTokenSecret);
       if (!verify.ok) return invalidSetupToken();

package/src/auth-mfa/handlers/enable-start-preauth.write.ts

@@ -35,6 +35,8 @@ export function createEnableStartPreauthHandler(opts: EnableStartPreauthOptions)
       accountLabel: z.string().min(1).max(200),
     }),
     access: { roles: ["all"] },
+    description:
+      "Begins TOTP enrollment for a user whose sign-in was blocked because the tenant requires two-factor authentication, taking identity from the pre-auth token login issued instead of from a session.",
     handler: async (event, ctx) => {
       const verified = verifyMfaPreauthSetupToken(
         event.payload.preauthSetupToken,

package/src/auth-mfa/handlers/enable-start.write.ts

@@ -30,6 +30,8 @@ export function createEnableStartHandler(opts: EnableStartOptions) {
       accountLabel: z.string().min(1).max(200),
     }),
     access: { openToAll: true },
+    description:
+      "Begins TOTP enrollment for the signed-in user by generating a secret plus recovery codes and returning them as a short-lived setup token, an otpauth:// URI and the one-time plaintext recovery codes; nothing is persisted until enable-confirm.",
     handler: async (event, ctx) => {
       const existing = await findUserMfaRow(ctx.db, event.user);
       if (existing) return mfaAlreadyEnabled();

package/src/auth-mfa/handlers/regenerate-recovery.write.ts

@@ -27,6 +27,9 @@ export function createRegenerateRecoveryHandler(opts: RegenerateRecoveryOptions)
     name: "regenerate-recovery",
     schema: z.object({ code: z.string().min(6).max(9) }),
     access: { openToAll: true },
+    description:
+      "Destroys every existing recovery code of the caller, including unused ones, and returns a fresh set once in plaintext; use it when recovery codes may have leaked but TOTP itself should stay enrolled.",
+    agent: { risk: "high" },
     handler: async (event, ctx) => {
       const row = await findUserMfaRow(ctx.db, event.user);
       if (!row) return mfaNotEnabled();

package/src/auth-mfa/handlers/status.query.ts

@@ -14,6 +14,8 @@ export const mfaStatusQuery = defineQueryHandler({
   name: "user-mfa:status",
   schema: z.object({}),
   access: { openToAll: true },
+  description:
+    "Reports whether the calling user has TOTP two-factor authentication enrolled; use it before offering either the enrollment flow or the disable and recovery-code actions.",
   handler: async (query, ctx) => {
     const row = await fetchOne<{ id: string }>(ctx.db, userMfaTable, {
       userId: query.user.id,

package/src/auth-mfa/handlers/verify.write.ts

@@ -46,6 +46,8 @@ export function createMfaVerifyHandler(opts: MfaVerifyOptions) {
     name: "verify",
     schema: z.object({ challengeToken: z.string().min(1), code: z.string().min(6).max(9) }),
     access: { roles: ["all"] },
+    description:
+      "Finishes a two-step sign-in by checking a TOTP or recovery code against the challenge token that login handed back, under a per-account attempt cap, and derives the resulting session.",
     handler: async (event, ctx) => {
       const verified = verifyMfaChallengeToken(
         event.payload.challengeToken,

package/src/auth-mfa/schema/user-mfa.ts

@@ -11,6 +11,8 @@ import {
 // mfa.enabled/disabled fall out of the event stream instead of being
 // manually emitted.
 export const userMfaEntity = createEntity({
+  description:
+    "One user's TOTP two-factor enrollment: the encrypted shared secret, the hashed recovery codes and when the factor was enabled and last used; the row exists only while the user has MFA on.",
   table: "read_user_mfa",
   fields: {
     // FK to the user row, not content — PII-naming heuristic would flag

package/src/billing-foundation/handlers/create-checkout-session.write.ts

@@ -37,6 +37,8 @@ type CreateCheckoutSessionPayload = z.infer<typeof createCheckoutSessionSchema>;
 
 export const createCheckoutSessionHandler: WriteHandlerDef = {
   name: "create-checkout-session",
+  description:
+    "Opens a hosted checkout page at the named subscription provider for the caller's tenant and returns its URL; use it when a tenant admin wants to subscribe or switch to a paid plan.",
   schema: createCheckoutSessionSchema,
   // Tenant-Admin-only — der Tenant muss bewusst seine Subscription
   // konfigurieren. SystemAdmin als Fallback für Operator-Initiated-Flows.

package/src/billing-foundation/handlers/create-portal-session.write.ts

@@ -30,6 +30,8 @@ type CreatePortalSessionPayload = z.infer<typeof createPortalSessionSchema>;
 
 export const createPortalSessionHandler: WriteHandlerDef = {
   name: "create-portal-session",
+  description:
+    "Returns a hosted billing-portal URL at the provider that already holds the tenant's subscription; use it when a tenant admin wants to change payment method, see invoices or cancel.",
   schema: createPortalSessionSchema,
   access: { roles: ["TenantAdmin", "SystemAdmin"] },
   handler: async (event, ctx) => {

package/src/billing-foundation/handlers/list-subscriptions.query.ts

@@ -17,6 +17,8 @@ const listSchema = z.object({}).strict();
 
 export const listSubscriptionsQuery: QueryHandlerDef = {
   name: "subscription:list",
+  description:
+    "Returns the tenant's subscription rows with provider, status, tier and current period end (provider ids decrypted); use it to answer what plan a tenant is on and until when.",
   schema: listSchema,
   access: { roles: ["SystemAdmin", "TenantAdmin"] },
   handler: async (_query, ctx) => {

package/src/billing-foundation/handlers/process-event.write.ts

@@ -85,6 +85,7 @@ const NORMALIZED_TO_ES_EVENT: Readonly<Record<string, string>> = {
 // Tenant-Admin direkt.
 export const processEventHandler: WriteHandlerDef = {
   name: "process-event",
+  agent: { expose: false },
   schema: processEventSchema,
   access: { roles: ["SystemAdmin"] },
   handler: async (event, ctx) => {

package/src/cap-counter/entity.ts

@@ -39,6 +39,8 @@ import {
 //     auslöst).
 export const capCounterEntity = createEntity({
   table: "read_cap_counters",
+  description:
+    "One usage counter per tenant, cap name and calendar period, holding the accumulated value and the timestamp of the last soft-limit warning.",
   fields: {
     capName: createTextField({ required: true, maxLength: 100, sortable: true, searchable: true }),
     value: createBigIntField({ required: true, default: 0 }),

package/src/cap-counter/feature.ts

@@ -98,7 +98,13 @@ export const capCounterFeature = defineFeature(CAP_COUNTER_FEATURE, (r) => {
   // single-row via get-counter. Detail-by-id-handler bewusst weggelassen
   // (kein Use-Case; der natürliche Lookup ist über capName + period, nicht
   // über aggregate-id).
-  r.queryHandler(defineEntityListHandler("cap-counter", capCounterEntity, sysadminAccess));
+  r.queryHandler(
+    defineEntityListHandler("cap-counter", capCounterEntity, {
+      ...sysadminAccess,
+      description:
+        "Lists usage-counter rows across all tenants with cap name, current value, period start and soft-warn timestamp; use it as the operator view of who is consuming which quota.",
+    }),
+  );
   r.queryHandler(getCounterQuery);
 
   r.screen({

package/src/cap-counter/handlers/get-counter.query.ts

@@ -18,6 +18,8 @@ const getCounterSchema = z.object({
 
 export const getCounterQuery: QueryHandlerDef = {
   name: "get-counter",
+  description:
+    "Returns the calendar-period usage counter row of the caller's tenant for one cap name and period start, or null when nothing was counted yet; use it to show remaining quota.",
   schema: getCounterSchema,
   access: { roles: ["TenantAdmin", "SystemAdmin"] },
   handler: async (query, ctx) => {

package/src/cap-counter/handlers/increment-rolling.write.ts

@@ -47,6 +47,7 @@ export const rollingIncrementedSchema = incrementRollingSchema;
 // store atomar ermittelt.
 export const incrementRollingCapHandler: WriteHandlerDef = {
   name: "increment-rolling",
+  agent: { expose: false },
   schema: incrementRollingSchema,
   // Internal handler — System-Caller (Plattform-foundations nach
   // erfolgreichem Side-Effect) ruft das auf. Tenant-end-users niemals

package/src/cap-counter/handlers/increment.write.ts

@@ -38,6 +38,7 @@ type IncrementPayload = z.infer<typeof incrementSchema>;
 // not this handler.
 export const incrementCapHandler: WriteHandlerDef = {
   name: "increment",
+  agent: { expose: false },
   schema: incrementSchema,
   // Internal handler — only system-callers (Plattform-foundations after
   // a successful side-effect) drive this. Tenant-end-users never call

package/src/cap-counter/handlers/mark-soft-warned.write.ts

@@ -21,6 +21,7 @@ const markSoftWarnedSchema = z.object({
 
 export const markSoftWarnedHandler: WriteHandlerDef = {
   name: "mark-soft-warned",
+  agent: { expose: false },
   schema: markSoftWarnedSchema,
   access: { roles: ["SystemAdmin"] },
   handler: async (event, ctx) => {

package/src/cap-overview/handlers/caps-usage.query.ts

@@ -19,6 +19,8 @@ const tierAssignmentTable = buildEntityTable("tier-assignment", tierAssignmentEn
 export function createCapsUsageQuery(caps: readonly CapSpec[]): QueryHandlerDefinition {
   return defineQueryHandler({
     name: "caps:usage",
+    description:
+      "Returns one tenant's configured caps with used amount, tier limit and utilisation fraction; use it to answer how close a tenant is to its quota (SystemAdmin may target another tenant via tenantId).",
     schema: z.object({ tenantId: z.string().min(1).optional() }),
     access: { roles: access.admin },
     handler: async (query, ctx) => {

package/src/cap-overview/handlers/tenant-caps-list.query.ts

@@ -95,6 +95,8 @@ export function createTenantCapsListQuery(caps: readonly CapSpec[], listCaps: re
 
   return definePagedQueryHandler({
     name: "tenant-caps:list",
+    description:
+      "Lists every tenant on the platform with its tier, billing provider/status and per-cap usage, paged, searchable by name and filterable by tier; use it as the operator-wide capacity overview.",
     schema: z.object({
       cursor: z.string().optional(),
       limit: z.number().int().min(1).max(MAX_LIST_LIMIT).default(50),

package/src/cap-overview/handlers/tenant-options.query.ts

@@ -8,6 +8,8 @@ type TenantRow = { readonly id: string; readonly name: string };
 
 export const tenantOptionsQuery = defineQueryHandler({
   name: "tenant-options",
+  description:
+    "Returns all tenants as id/name option pairs sorted by name; use it to populate the tenant picker of a platform-wide overview.",
   schema: z.object({}),
   access: { roles: ["SystemAdmin"] },
   handler: async (_query, ctx) => {

package/src/channel-in-app/handlers/inbox.query.ts

@@ -10,6 +10,8 @@ export const inboxQuery = defineQueryHandler({
     unreadOnly: z.boolean().default(false),
   }),
   access: { openToAll: true },
+  description:
+    "Lists the calling user's own in-app notification messages newest-first, optionally only the unread ones; use it to show or inspect a user's notification inbox.",
   handler: async (query, ctx) => {
     const where: Record<string, unknown> = { userId: query.user.id };
     if (query.payload.unreadOnly) where["isRead"] = false;

package/src/channel-in-app/handlers/mark-all-read.write.ts

@@ -7,6 +7,8 @@ export const markAllReadWrite = defineWriteHandler({
   name: "markAllRead",
   schema: z.object({}),
   access: { openToAll: true },
+  description:
+    "Marks every unread in-app message of the calling user as read and returns how many rows were touched; use it for a mark-all-as-read action.",
   handler: async (event, ctx) => {
     const rows = await updateMany(
       ctx.db,

package/src/channel-in-app/handlers/mark-read.write.ts

@@ -11,6 +11,8 @@ export const markReadWrite = defineWriteHandler({
     id: z.number().int(),
   }),
   access: { openToAll: true },
+  description:
+    "Marks one in-app message of the calling user as read by its numeric id, failing with not-found when no such message belongs to the caller; use it when a user opens a single notification.",
   handler: async (event, ctx) => {
     const rows = await updateMany(
       ctx.db,

package/src/channel-in-app/handlers/unread-count.query.ts

@@ -7,6 +7,8 @@ export const unreadCountQuery = defineQueryHandler({
   name: "unreadCount",
   schema: z.object({}),
   access: { openToAll: true },
+  description:
+    "Counts the calling user's unread in-app notification messages; use it for an inbox badge or to check whether a user has pending notifications.",
   handler: async (query, ctx) => {
     // bun-db hat keinen aggregate-helper — selectMany alle matching rows,
     // count() in JS. Pragma: unread-counts sind low-cardinality (user-