@cosmicdrift/kumiko-bundled-features 0.236.1 → 0.237.1

package/src/ledger/feature.ts

@@ -60,26 +60,86 @@ function registerLedger(
   // Chart of accounts — plain CRUD, no custom logic. No delete in v1: removing an
   // account that has postings would orphan them; a posting-aware guard lands with
   // the postings projection (Phase 1).
-  r.writeHandler(defineEntityCreateHandler("account", accountEntity, { access }));
-  r.writeHandler(defineEntityUpdateHandler("account", accountEntity, { access }));
-  r.queryHandler(defineEntityListHandler("account", accountEntity, { access }));
-  r.queryHandler(defineEntityDetailHandler("account", accountEntity, { access }));
+  r.writeHandler(
+    defineEntityCreateHandler("account", accountEntity, {
+      access,
+      description:
+        "Adds an account to the tenant's chart of accounts with a name, a type of asset, liability, equity, income or expense, an optional code and an optional parent account; use it before booking anything against that account.",
+    }),
+  );
+  r.writeHandler(
+    defineEntityUpdateHandler("account", accountEntity, {
+      access,
+      description:
+        "Changes an existing chart-of-accounts entry's name, type, code or parent; use it to rename or re-file an account, its balance is derived from postings and never edited here.",
+    }),
+  );
+  r.queryHandler(
+    defineEntityListHandler("account", accountEntity, {
+      access,
+      description:
+        "Lists the tenant's chart of accounts with name, type, code and parent; use it to browse the account tree or to look up the account id a booking needs.",
+    }),
+  );
+  r.queryHandler(
+    defineEntityDetailHandler("account", accountEntity, {
+      access,
+      description:
+        "Returns one chart-of-accounts entry by id with its name, type, code and parent; use it to inspect a single account.",
+    }),
+  );
 
   // Journal entries — immutable. Only create (balanced) + reverse (Storno). No
   // update/delete handler is registered, so a posted entry cannot be mutated.
   r.writeHandler(createCreateTransactionHandler(access));
   r.writeHandler(createReverseTransactionHandler(access));
-  r.queryHandler(defineEntityListHandler("transaction", transactionEntity, { access }));
-  r.queryHandler(defineEntityDetailHandler("transaction", transactionEntity, { access }));
+  r.queryHandler(
+    defineEntityListHandler("transaction", transactionEntity, {
+      access,
+      description:
+        "Lists the tenant's journal entries with date, description, reference, status and their embedded posting lines; use it to browse the books or to find the entry a reversal should target.",
+    }),
+  );
+  r.queryHandler(
+    defineEntityDetailHandler("transaction", transactionEntity, {
+      access,
+      description:
+        "Returns one journal entry by id including every posting line; use it to inspect a single booking.",
+    }),
+  );
 
   // Recurring schedules — CRUD catalog plus confirm-schedule-period, which books
   // one projected period as a balanced, idempotent + reversal-aware entry. The
   // Soll (forecast) is a pure projection (projectSchedule); only confirming writes.
-  r.writeHandler(defineEntityCreateHandler("schedule", scheduleEntity, { access }));
-  r.writeHandler(defineEntityUpdateHandler("schedule", scheduleEntity, { access }));
+  r.writeHandler(
+    defineEntityCreateHandler("schedule", scheduleEntity, {
+      access,
+      description:
+        "Creates a recurring booking template that names a debit and a credit account, a positive amount, an interval and a start plus optional end date; use it to set up a standing order, it books nothing on its own.",
+    }),
+  );
+  r.writeHandler(
+    defineEntityUpdateHandler("schedule", scheduleEntity, {
+      access,
+      description:
+        "Changes a recurring booking template's description, accounts, amount, interval or date window; use it when a standing order's terms change, already confirmed periods stay booked as they were.",
+    }),
+  );
   r.writeHandler(createConfirmSchedulePeriodHandler(access));
-  r.queryHandler(defineEntityListHandler("schedule", scheduleEntity, { access }));
-  r.queryHandler(defineEntityDetailHandler("schedule", scheduleEntity, { access }));
+  r.queryHandler(
+    defineEntityListHandler("schedule", scheduleEntity, {
+      access,
+      description:
+        "Lists the tenant's recurring booking templates with their accounts, amount, interval and date window; use it to see which standing orders exist and forecast upcoming periods.",
+    }),
+  );
+  r.queryHandler(
+    defineEntityDetailHandler("schedule", scheduleEntity, {
+      access,
+      description:
+        "Returns one recurring booking template by id with its accounts, amount, interval and date window; use it to inspect a single standing order before confirming a period.",
+    }),
+  );
 
   // Reports — pure aggregations over the posted entries (account balances,
   // GuV, Bilanz with the current result folded into equity).

package/src/ledger/handlers/confirm-schedule-period.write.ts

@@ -32,6 +32,8 @@ export function createConfirmSchedulePeriodHandler(
     name: "confirm-schedule-period",
     schema: confirmSchedulePeriodPayloadSchema,
     access,
+    description:
+      "Turns one month of a recurring schedule into a posted balanced entry between its debit and credit account, returning the existing booking instead when that period is already booked and not reversed; use it to move a forecast period into the actual books.",
     handler: async (event, ctx) => {
       const payload = event.payload as ConfirmSchedulePeriodPayload; // @cast-boundary engine-payload
 

package/src/ledger/handlers/create-transaction.write.ts

@@ -17,6 +17,8 @@ export function createCreateTransactionHandler(
     name: "create-transaction",
     schema: createTransactionPayloadSchema,
     access,
+    description:
+      "Books one balanced journal entry from a date, description and at least two posting lines summing to zero, after verifying every named account exists; use it to record any financial movement in the tenant's books.",
     handler: async (event, ctx) => {
       const payload = event.payload as CreateTransactionPayload; // @cast-boundary engine-payload
 

package/src/ledger/handlers/reports.query.ts

@@ -38,6 +38,8 @@ export function createBalancesReportHandler(
     name: "report:balances",
     schema: periodSchema,
     access,
+    description:
+      "Returns the per-account balance in its natural sign plus the trial balance over an optional from/to period; use it for a trial balance or to read one account's standing.",
     handler: async (query, ctx) => {
       const period = periodSchema.parse(query);
       const { accounts, entries } = await loadBooks(ctx);
@@ -54,6 +56,8 @@ export function createIncomeStatementHandler(
     name: "report:income-statement",
     schema: periodSchema,
     access,
+    description:
+      "Returns income minus expense over an optional from/to period; use it for a profit-and-loss statement.",
     handler: async (query, ctx) => {
       const period = periodSchema.parse(query);
       const { accounts, entries } = await loadBooks(ctx);
@@ -70,6 +74,8 @@ export function createBalanceSheetHandler(
     name: "report:balance-sheet",
     schema: periodSchema,
     access,
+    description:
+      "Returns assets, liabilities and equity as of the optional `to` date with the period result folded into equity so the sheet balances; use it for a balance sheet at a point in time.",
     handler: async (query, ctx) => {
       const period = periodSchema.parse(query);
       const { accounts, entries } = await loadBooks(ctx);

package/src/ledger/handlers/reverse-transaction.write.ts

@@ -24,6 +24,8 @@ export function createReverseTransactionHandler(
     name: "reverse-transaction",
     schema: reverseTransactionPayloadSchema,
     access,
+    description:
+      "Books the mirror image of a posted journal entry as a new entry referencing the original, refusing entries that are not posted or already reversed; use it as the only way to correct a booking, since entries themselves are immutable.",
     handler: async (event, ctx) => {
       const payload = event.payload as ReverseTransactionPayload; // @cast-boundary engine-payload
 

package/src/managed-pages/feature.ts

@@ -1,13 +1,5 @@
 import { computeRevisionEtag, etagMatches } from "@cosmicdrift/kumiko-framework/api";
-import {
-  defineEntityCreateHandler,
-  defineEntityDeleteHandler,
-  defineEntityDetailHandler,
-  defineEntityListHandler,
-  defineEntityUpdateHandler,
-  defineFeature,
-  type FeatureDefinition,
-} from "@cosmicdrift/kumiko-framework/engine";
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import {
   type BrandingTokens,
   cachedSecurePageResponse,
@@ -20,17 +12,13 @@ import { BRANDING_KEYS, BRANDING_QUERY_QN, CUSTOM_CSS_KEY, coerceBranding } from
 import { createBrandingQuery } from "./handlers/branding.query";
 import { bySlugQuery } from "./handlers/by-slug.query";
 import { byTenantPublishedQuery } from "./handlers/by-tenant-published.query";
+import { pageCrudQueries, pageCrudWrites } from "./handlers/page-crud";
 import { setWrite } from "./handlers/set.write";
 import { MANAGED_PAGES_I18N } from "./i18n";
 import { createBrandingSettingsScreen } from "./screens/branding-screen";
 import { pageEditScreen, pageListScreen } from "./screens/page-screens";
 import { pageEntity } from "./table";
 
-// Admin-Authoring läuft als TenantAdmin (self-service) oder SystemAdmin
-// (app-weite Pages). Spiegelt set.write's ACL — Apps mit eigenem Rollen-
-// Alias (publicstatus = "Admin") müssen TenantAdmin granten/mappen.
-const ADMIN_ACCESS = { roles: ["TenantAdmin", "SystemAdmin"] } as const;
-
 // 60s-shared-cache saves the origin-revalidate roundtrip; CMS edits are live within 60s.
 const PUBLIC_PAGE_CACHE = { kind: "revalidate", maxAgeSeconds: 60 } as const;
 
@@ -186,15 +174,8 @@ export function createManagedPagesFeature(opts: ManagedPagesOptions): FeatureDef
       branding: r.queryHandler(createBrandingQuery({ allowCustomCss })),
     };
 
-    // Convention-CRUD hinter den Admin-Screens: entityEdit/entityList
-    // dispatchen per Konvention `managed-pages:write:page:{create,update,
-    // delete}` + `managed-pages:query:page:{list,detail}`. `set` (oben)
-    // wird davon NICHT genutzt und bleibt als Provisioning-API erhalten.
-    r.writeHandler(defineEntityCreateHandler("page", pageEntity, { access: ADMIN_ACCESS }));
-    r.writeHandler(defineEntityUpdateHandler("page", pageEntity, { access: ADMIN_ACCESS }));
-    r.writeHandler(defineEntityDeleteHandler("page", pageEntity, { access: ADMIN_ACCESS }));
-    r.queryHandler(defineEntityListHandler("page", pageEntity, { access: ADMIN_ACCESS }));
-    r.queryHandler(defineEntityDetailHandler("page", pageEntity, { access: ADMIN_ACCESS }));
+    for (const def of pageCrudWrites) r.writeHandler(def);
+    for (const def of pageCrudQueries) r.queryHandler(def);
 
     r.screen(pageListScreen);
     r.screen(pageEditScreen);

package/src/managed-pages/handlers/branding.query.ts

@@ -19,6 +19,8 @@ export function createBrandingQuery(opts: { readonly allowCustomCss: boolean })
     name: "branding",
     schema: z.object({}),
     access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
+    description:
+      "Reads the tenant's public branding values for the rendered page shell, adding the raw custom CSS only when the app opted in and the per-tenant CSS toggle is on; anonymous callers may read it because it dresses public pages.",
     handler: async (_query, ctx) => {
       const base = await readBranding(ctx.config);
       if (

package/src/managed-pages/handlers/by-slug.query.ts

@@ -16,6 +16,8 @@ export const bySlugQuery = defineQueryHandler({
     lang: z.string().min(2).max(8),
   }),
   access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
+  description:
+    "Reads the body and metadata of one published managed page of the caller's tenant by slug and language, returning null for drafts and bodyless pages; use it to render a public page, not to load one for editing.",
   handler: async (query, ctx) => {
     const row = await fetchOne<PageRow>(ctx.db, pagesTable, {
       tenantId: query.user.tenantId,

package/src/managed-pages/handlers/by-tenant-published.query.ts

@@ -28,6 +28,8 @@ export const byTenantPublishedQuery = defineQueryHandler({
     tenantIdOverride: z.string().min(1).optional(),
   }),
   access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
+  description:
+    "Lists every published page of a tenant with slug, language, title and last-change time but no body; use it to enumerate the public pages for sitemap.xml or llms.txt, rather than by-slug which fetches one page's content.",
   handler: async (query, ctx) => {
     const override = query.payload.tenantIdOverride;
     const overrideDenied = crossTenantOverrideDenied(

package/src/managed-pages/handlers/page-crud.ts

@@ -0,0 +1,49 @@
+import {
+  defineEntityCreateHandler,
+  defineEntityDeleteHandler,
+  defineEntityDetailHandler,
+  defineEntityListHandler,
+  defineEntityUpdateHandler,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { pageEntity } from "../table";
+
+// Admin authoring runs as TenantAdmin (self-service) or SystemAdmin (app-wide
+// pages). Mirrors set.write's ACL — an app with its own role alias
+// (publicstatus = "Admin") has to grant or map TenantAdmin.
+const ADMIN_ACCESS = { roles: ["TenantAdmin", "SystemAdmin"] } as const;
+
+// Convention CRUD behind the admin screens: entityEdit/entityList dispatch
+// `managed-pages:write:page:{create,update,delete}` +
+// `managed-pages:query:page:{list,detail}` by convention. The `set` write
+// handler in feature.ts is NOT used by them and stays the provisioning API.
+export const pageCrudWrites = [
+  defineEntityCreateHandler("page", pageEntity, {
+    access: ADMIN_ACCESS,
+    description:
+      "Creates a managed page from the admin form's field values, failing if that slug and language already exist; use it from the page catalog screen, whereas managed-pages:write:set upserts a page addressed by slug and language.",
+  }),
+  defineEntityUpdateHandler("page", pageEntity, {
+    access: ADMIN_ACCESS,
+    description:
+      "Updates one managed page addressed by row id from the admin form's `{ id, version, changes }` envelope; use it from the page edit screen, whereas managed-pages:write:set addresses a page by slug and language instead.",
+  }),
+  defineEntityDeleteHandler("page", pageEntity, {
+    access: ADMIN_ACCESS,
+    description:
+      "Deletes one managed page by row id so its URL stops resolving entirely; use it to retire a page for good, not to take it offline temporarily — that is a published:false write through managed-pages:write:set.",
+    agent: { risk: "high" },
+  }),
+];
+
+export const pageCrudQueries = [
+  defineEntityListHandler("page", pageEntity, {
+    access: ADMIN_ACCESS,
+    description:
+      "Lists the tenant's managed pages for the admin catalog, drafts included; use it to browse or search pages for editing, unlike by-tenant-published which only enumerates the publicly visible ones.",
+  }),
+  defineEntityDetailHandler("page", pageEntity, {
+    access: ADMIN_ACCESS,
+    description:
+      "Reads one managed page by row id including its body and draft state; use it to load a page into the admin edit screen, whereas by-slug serves the public render path.",
+  }),
+];

package/src/managed-pages/handlers/set.write.ts

@@ -43,6 +43,8 @@ export const setWrite = defineWriteHandler({
     tenantIdOverride: z.string().min(1).optional(),
   }),
   access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  description:
+    "Creates or overwrites one managed page addressed by slug and language, keeping the existing published flag, description and OG image when the payload omits them; use it for content edits and publish toggles, and as SystemAdmin to write another tenant's pages.",
   handler: async (event, ctx) => {
     const db = ctx.db;
     const override = event.payload.tenantIdOverride;

package/src/managed-pages/table.ts

@@ -13,6 +13,8 @@ import {
 // Tenant-eigene Pages (Host → tenantId via resolveApexTenant am Render-Pfad).
 export const pageEntity = createEntity({
   table: "read_pages",
+  description:
+    "One tenant-editable public web page, unique per slug and language, holding a markdown body plus the title, SEO description and OG image, with a published flag that decides whether anonymous visitors are served it or get a 404.",
   fields: {
     slug: createTextField({ required: true, maxLength: 64, sortable: true, searchable: true }),
     lang: createTextField({ required: true, maxLength: 8, sortable: true }),

package/src/notes-history/entity.ts

@@ -32,6 +32,8 @@ import {
 export function createNoteEntryEntity(access?: EntityDefinition["access"]) {
   return createEntity({
     table: "read_note_entries",
+    description:
+      "One note attached to a host entity by entityType and entityId, holding the note body plus the id and the display name of the author as it stood when the note was written. Rows are append-only: a correction is a further note, never an edit of this one.",
     access,
     fields: {
       entityType: createTextField({ required: true, maxLength: 64 }),

package/src/notes-history/feature.ts

@@ -44,7 +44,13 @@ function registerNotesHistory(
   r.entity("note-entry", entity);
 
   r.writeHandler(createAddNoteHandler(access));
-  r.queryHandler(defineEntityListHandler("note-entry", entity, { access }));
+  r.queryHandler(
+    defineEntityListHandler("note-entry", entity, {
+      access,
+      description:
+        "Lists note-history entries of the caller's tenant with their text, author and timestamp; filter on entityId to read the full note trail of one record.",
+    }),
+  );
 
   r.translations({ keys: NOTES_HISTORY_FEATURE_I18N });
 }

package/src/notes-history/handlers/add-note.write.ts

@@ -18,6 +18,8 @@ export function createAddNoteHandler(
     name: "add-note",
     schema: addNotePayloadSchema,
     access,
+    description:
+      "Appends a note to one host entity's history, stamping the author from the authenticated caller rather than the payload; use it for every remark and correction alike, because entries can never be edited or removed afterwards.",
     handler: async (event, ctx) => {
       const payload = event.payload as AddNotePayload; // @cast-boundary engine-payload
 

package/src/personal-access-tokens/feature.ts

@@ -156,6 +156,8 @@ export function createPersonalAccessTokensFeature(
       renderer: { react: { __component: "PatTokensScreen" } },
       access: { openToAll: true },
       dormant: true,
+      description:
+        "Self-service screen where a signed-in user reviews their personal access tokens, mints a new one by picking a permission level per scope domain and an expiry, and revokes tokens they no longer need.",
     });
     r.translations({ keys: PAT_FEATURE_I18N });
 

package/src/personal-access-tokens/handlers/available-scopes.query.ts

@@ -11,6 +11,8 @@ export function buildAvailableScopesQuery(scopes: PatScopeConfig) {
     name: "available-scopes",
     schema: z.object({}),
     access: { openToAll: true },
+    description:
+      "Lists the API scope domains this deployment declares, each with its display label and whether it offers write access, for choosing what a new personal access token may do.",
     handler: async () =>
       Object.entries(scopes).map(([name, def]) => ({
         name,

package/src/personal-access-tokens/handlers/create.write.ts

@@ -58,6 +58,8 @@ export function createPatCreateHandler(opts: CreatePatOptions = {}) {
       mfaCode: z.string().optional(),
     }),
     access: { openToAll: true },
+    description:
+      "Mints a personal access token for the calling user after re-verifying their password (and MFA code when enrolled) and returns the plaintext token exactly once; use it when a user needs a long-lived API credential.",
     handler: async (event, ctx) => {
       const systemUser = createSystemUser(event.user.tenantId);
       const me = (await ctx.queryAs(systemUser, UserQueries.findForAuth, {

package/src/personal-access-tokens/handlers/list.query.ts

@@ -11,6 +11,8 @@ export const listPatQuery = defineQueryHandler({
   name: "mine",
   schema: z.object({}),
   access: { openToAll: true },
+  description:
+    "Lists the calling user's personal access tokens with metadata only (name, key prefix, scopes, created/expiry/revoked timestamps, including revoked ones) and never the token secret.",
   handler: async (query, ctx) => {
     const rows = await selectMany<{
       id: string;

package/src/personal-access-tokens/handlers/revoke.write.ts

@@ -14,6 +14,9 @@ export const revokePatWrite = defineWriteHandler({
   name: "revoke",
   schema: z.object({ id: z.uuid() }),
   access: { openToAll: true },
+  description:
+    "Permanently revokes one of the caller's own personal access tokens so it stops authenticating; use it when a token leaked or is no longer needed.",
+  agent: { risk: "high" },
   handler: async (event, ctx) => {
     const updated = await updateMany(
       ctx.db,

package/src/rate-limiting/handlers/status.query.ts

@@ -22,6 +22,8 @@ export const rateLimitStatus = defineQueryHandler({
   // when the feature is registered. Passing the qualified form here would
   // double-prefix it and the handler wouldn't be reachable.
   name: "status",
+  description:
+    "Peeks at one rate-limit bucket and returns its remaining tokens, window and next reset without consuming a token; use it to explain why a caller is being throttled.",
   schema: z.object({
     bucket: z.string().min(1),
     limit: z.number().int().positive(),

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

@@ -13,6 +13,8 @@ export type ReadinessMissingSecret = { readonly key: string };
 // query can't see secrets, this feature requires both — so it may verdict.
 export const statusQuery = defineQueryHandler({
   name: "status",
+  description:
+    "Reports whether the caller's tenant is fully configured, naming every required config key and every required secret that is still unset; use it to answer what is missing before go-live.",
   schema: z.object({}),
   // Same gate as secrets:query:list — the response names missing secrets.
   access: { roles: ["TenantAdmin"] },

package/src/secrets/handlers/delete.write.ts

@@ -7,6 +7,9 @@ import { requireSecretsContext } from "../feature";
 export function createDeleteHandler(access: AccessRule = DEFAULT_SECRETS_ACCESS) {
   return defineWriteHandler({
     name: "delete",
+    description:
+      "Permanently removes the stored secret under the given key for the caller's tenant, breaking every feature that depends on that credential.",
+    agent: { risk: "high" },
     schema: z.object({
       key: z.string().min(1).max(100),
     }),

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

@@ -10,6 +10,8 @@ import { tenantSecretsTable } from "../table";
 export function createListHandler(access: AccessRule = DEFAULT_SECRETS_ACCESS) {
   return defineQueryHandler({
     name: "list",
+    description:
+      "Lists the secrets stored for the caller's tenant by key with a redacted preview, hint, key version and rotation date — never the plaintext; use it to check which credentials are set.",
     schema: z.object({}),
     access,
     handler: async (event, ctx) => {

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

@@ -6,6 +6,8 @@ import { requireSecretsContext } from "../feature";
 export function createSetHandler(access: AccessRule = DEFAULT_SECRETS_ACCESS) {
   return defineWriteHandler({
     name: "set",
+    description:
+      "Stores or replaces one encrypted secret for the caller's tenant under the given key, together with a redacted preview and optional hint; use it to enter or rotate a credential.",
     schema: z.object({
       key: z.string().min(1).max(100),
       value: z.string(),

package/src/secrets/table.ts

@@ -47,6 +47,8 @@ export type StoredMetadata = {
 // doesn't weaken the threat model vs. the pre-ES tenant_secrets column.
 export const tenantSecretEntity = createEntity({
   table: "read_tenant_secrets",
+  description:
+    "One encrypted secret per tenant and key, holding the sealed envelope, the key-encryption-key version it was sealed under and its last rotation time; plaintext values are never stored or returned.",
   fields: {
     key: createTextField({ required: true }),
     kekVersion: createNumberField({ required: true, integer: true }),

package/src/seo/handlers/seo-config.query.ts

@@ -18,6 +18,8 @@ export const seoConfigQuery = defineQueryHandler({
   name: "config",
   schema: z.object({}),
   access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
+  description:
+    "Reads the tenant's SEO metadata settings — organization name and logo URL, Twitter site handle, LLMs summary and default OG image — as plain strings; use it to inspect what the sitemap, llms.txt and page meta tags will publish.",
   handler: async (_query, ctx) => {
     const read = async (qualifiedKey: string): Promise<string> => {
       if (!ctx.config) return "";

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

@@ -20,6 +20,8 @@ export const detailQuery = defineQueryHandler({
   name: "user-session:detail",
   schema: z.object({ id: z.uuid() }),
   access: { roles: access.admin },
+  description:
+    "Loads one session of the active tenant by its id with owner, timestamps and decrypted IP/user-agent; use it when an admin investigates a specific session found through the session list.",
   outputSchema: sessionRowSchema.nullable(),
   handler: async (query, ctx) => {
     const row = await fetchOne<{

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

@@ -33,6 +33,8 @@ export const listQuery = definePagedQueryHandler({
     sortDirection: z.enum(["asc", "desc"]).optional(),
   }),
   access: { roles: access.admin },
+  description:
+    "Lists every session in the active tenant, live and revoked, sortable by id, user, creation, expiry or revocation, for an admin auditing who is signed in.",
   outputSchema: z.object({
     rows: z.array(
       z.object({

package/src/sessions/handlers/mine.query.ts

@@ -11,6 +11,8 @@ export const mineQuery = defineQueryHandler({
   name: "user-session:mine",
   schema: z.object({}),
   access: { openToAll: true },
+  description:
+    "Lists the calling user's own still-live sessions, newest first, each flagged whether it is the one making the request; use it to show a user their signed-in devices.",
   handler: async (query, ctx) => {
     const rows = await selectMany<{
       id: string;

package/src/sessions/handlers/revoke-all-for-user.write.ts

@@ -34,6 +34,9 @@ export const revokeAllForUserWrite = defineWriteHandler({
     tenantId: z.string().min(1).optional(),
   }),
   access: { roles: access.privileged },
+  description:
+    "Irreversibly signs a named user out of all their live sessions, across every tenant unless a tenantId narrows it; use it for operator actions such as freezing or banning an account.",
+  agent: { risk: "high" },
   handler: async (event, ctx) => {
     const updated = await updateMany<{ id: string }>(
       ctx.db.raw,

package/src/sessions/handlers/revoke-all-others.write.ts

@@ -16,6 +16,9 @@ export const revokeAllOthersWrite = defineWriteHandler({
   name: "user-session:revoke-all-others",
   schema: z.object({}),
   access: { openToAll: true },
+  description:
+    'Irreversibly signs the calling user out of every session except the one making the request and reports how many were dropped; use it for a "sign out everywhere else" action after a suspected compromise.',
+  agent: { risk: "high" },
   handler: async (event, ctx) => {
     const keepSid = event.user.sid;
     if (!keepSid) {

package/src/sessions/handlers/revoke.write.ts

@@ -29,6 +29,9 @@ export const revokeWrite = defineWriteHandler({
     id: z.uuid(),
   }),
   access: { openToAll: true },
+  description:
+    "Irreversibly signs one of the caller's own sessions out by id; use it when a user wants to drop a single device, and note that revoking their current session logs them out.",
+  agent: { risk: "high" },
   handler: async (event, ctx) => {
     const updated = await updateMany(
       ctx.db,

package/src/tags/entity.ts

@@ -9,6 +9,8 @@ import {
 // events. tenantId is a base column set by the framework → tenant-scoped.
 export const tagEntity = createEntity({
   table: "read_tags",
+  description:
+    "One entry of a tenant's tag catalog: a name plus an optional colour hint for rendering and an optional entityType scope that limits which entities a picker offers the tag on. Names are not unique, and a tag carries no link to the entities it is attached to.",
   fields: {
     // Catalog labels ("urgent", "billing"), not user-identifying content —
     // `personal: false` silences the user-content heuristic (456/5). A tag
@@ -56,6 +58,8 @@ export const tagEntity = createEntity({
 export function createTagAssignmentEntity(access?: EntityDefinition["access"]) {
   return createEntity({
     table: "read_tag_assignments",
+    description:
+      "The join row recording that one catalog tag is attached to one host entity, addressed by tagId, entityType and entityId, with exactly one row per pair. An entity may carry many tags, unlike the single-folder membership rows.",
     softDelete: true,
     access,
     fields: {

package/src/tags/feature.ts

@@ -79,13 +79,46 @@ function registerTags(
   // (payloadMode=values); update must accept the {id,version,changes} envelope
   // entityEdit sends (legacy update-tag stays for TagManager). delete stays
   // legacy so assignment cascade is preserved (convention delete would orphan).
-  r.writeHandler(createCreateTagHandler(access, "tag:create"));
-  r.writeHandler(defineEntityUpdateHandler("tag", tagEntity, { access }));
-  r.writeHandler(createDeleteTagHandler(access, "tag:delete"));
+  r.writeHandler({
+    ...createCreateTagHandler(access, "tag:create"),
+    description:
+      "Adds a tag to the caller's tenant tag catalog and mints its id; this is the convention name the declarative tag catalog screens dispatch, with the same effect as the legacy create-tag.",
+  });
+  r.writeHandler(
+    defineEntityUpdateHandler("tag", tagEntity, {
+      access,
+      description:
+        "Renames, recolours or re-scopes a catalog tag from the entity-edit `{ id, version, changes }` envelope; this is the convention name the tag edit screen submits, unlike the flat-payload legacy update-tag.",
+    }),
+  );
+  r.writeHandler({
+    ...createDeleteTagHandler(access, "tag:delete"),
+    description:
+      "Deletes a catalog tag and detaches it from every entity carrying it; this is the convention name the tag catalog list screen's delete row-action dispatches, with the same cascade as the legacy delete-tag.",
+    agent: { risk: "high" },
+  });
 
-  r.queryHandler(defineEntityListHandler("tag", tagEntity, { access }));
-  r.queryHandler(defineEntityListHandler("tag-assignment", tagAssignmentEntity, { access }));
-  r.queryHandler(defineEntityDetailHandler("tag", tagEntity, { access }));
+  r.queryHandler(
+    defineEntityListHandler("tag", tagEntity, {
+      access,
+      description:
+        "Lists the caller's tenant tag catalog with each tag's name, colour and scope; use it to render the catalog or to offer a user the tags they can attach.",
+    }),
+  );
+  r.queryHandler(
+    defineEntityListHandler("tag-assignment", tagAssignmentEntity, {
+      access,
+      description:
+        "Lists the tag-to-entity assignment rows of the caller's tenant; filter on entityId to get one record's tags, or on tagId to get every record carrying a tag.",
+    }),
+  );
+  r.queryHandler(
+    defineEntityDetailHandler("tag", tagEntity, {
+      access,
+      description:
+        "Reads one catalog tag by id with its name, colour and scope; use it to load a single tag into an edit form rather than to find which entities carry it.",
+    }),
+  );
 
   // Standalone catalog: entityList + entityEdit. App navs via
   // r.nav("tags:screen:tag-list"). TagManager stays for picker/section only.

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

@@ -26,6 +26,8 @@ export function createAssignTagHandler(access: AccessRule = DEFAULT_TAG_ACCESS):
     name: "assign-tag",
     schema: assignTagPayloadSchema,
     access,
+    description:
+      "Attaches an existing catalog tag to one host entity addressed by its type and id, reporting success when the tag was already attached; use it to tag a record, not to create the tag.",
     handler: async (event, ctx) => {
       const payload = event.payload as AssignTagPayload; // @cast-boundary engine-payload
       const id = tagAssignmentAggregateId(

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

@@ -15,6 +15,8 @@ export function createCreateTagHandler(
     name,
     schema: createTagPayloadSchema,
     access,
+    description:
+      "Adds a tag to the caller's tenant tag catalog from a flat payload and mints its id; this is the legacy name the TagManager and TagPicker widgets dispatch, and it does not attach the new tag to anything.",
     handler: async (event, ctx) => {
       const payload = event.payload as CreateTagPayload; // @cast-boundary engine-payload
       return tagExecutor.create(payload, event.user, ctx.db);