@softr/sdk 0.0.97-alpha.1 → 0.0.97

package/dist/action.d.ts

@@ -234,50 +234,6 @@ type IntegrationDefinition<TId extends string> = {
  * const res = await listEvents({ query: { timeMin: now, singleEvents: "true" } })
  */
 declare function defineIntegration<const TId extends string>(definition: IntegrationDefinition<TId>): IntegrationAction<TId>;
-type EmailInputs = {
-  senderId?: string;
-  to?: ReadonlyArray<string>;
-  cc?: ReadonlyArray<string>;
-  bcc?: ReadonlyArray<string>;
-  replyTo?: string;
-};
-type EmailResource = {
-  type: "SOFTR_EMAIL";
-  inputs: EmailInputs;
-};
-type EmailAction<TId extends string = string> = Action<EmailResource> & {
-  id: TId;
-};
-type EmailDefinition<TId extends string> = EmailInputs & {
-  id: TId;
-  permissions: ActionPermissions;
-};
-/**
- * Declares an email action: who may send it, and the fields every email it sends keeps whatever the
- * call says. Softr sends it from the app's email sender and bills the workspace's workflow credits.
- *
- * - `to`, `cc`, `bcc`: addresses. An element may be a whole `{LOGGED_IN_USER:EMAIL}` or
- *   `{LOGGED_IN_USER:<field>}` placeholder, filled in for the signed-in sender.
- * - `replyTo`: an address or one such placeholder.
- * - `senderId`: one of the workspace's email senders, for an email that must come from that address.
- *   Left out, the app's sender is used. The call can never choose the sender.
- *
- * A field declared here wins over the call's, and declaring `to` also ignores the call's `cc` and
- * `bcc`. Fix the recipients whenever the use case allows,
- * because anyone in the audience can otherwise send any email to anyone.
- *
- * Pass the returned object to `email.send()` at runtime.
- *
- * @example
- * const notifyOwner = defineEmailAction({
- *   id: "notifyOwner",
- *   to: ["owner@acme.com"],
- *   permissions: { userGroupTypes: ["NON_LOGGED_IN_USERS", "LOGGED_IN_USERS"] },
- * })
- *
- * await email.send(notifyOwner, { subject: "New submission", body: html, replyTo: data.email })
- */
-declare function defineEmailAction<const TId extends string>(definition: EmailDefinition<TId>): EmailAction<TId>;
 type AiResource = {
   type: "SOFTR_AI";
   model: string;
@@ -312,4 +268,4 @@ type AiDefinition<TId extends string> = {
  */
 declare function defineAiAction<const TId extends string>(definition: AiDefinition<TId>): AiAction<TId>;
 //#endregion
-export { ActionData, ActionPermissions, ActionRecord, ActionShape, AiAction, DatasourceAction, EmailAction, FieldTypeOf, IntegrationAction, ReadOf, ReadShape, SoftrDatasources, WorkflowAction, defineAiAction, defineEmailAction, defineIntegration, defineMutation, defineQuery, defineWorkflow };
+export { ActionData, ActionPermissions, ActionRecord, ActionShape, AiAction, DatasourceAction, FieldTypeOf, IntegrationAction, ReadOf, ReadShape, SoftrDatasources, WorkflowAction, defineAiAction, defineIntegration, defineMutation, defineQuery, defineWorkflow };

package/dist/action.js

@@ -50,42 +50,6 @@ function defineIntegration(definition) {
 		permissions
 	};
 }
-/**
-* Declares an email action: who may send it, and the fields every email it sends keeps whatever the
-* call says. Softr sends it from the app's email sender and bills the workspace's workflow credits.
-*
-* - `to`, `cc`, `bcc`: addresses. An element may be a whole `{LOGGED_IN_USER:EMAIL}` or
-*   `{LOGGED_IN_USER:<field>}` placeholder, filled in for the signed-in sender.
-* - `replyTo`: an address or one such placeholder.
-* - `senderId`: one of the workspace's email senders, for an email that must come from that address.
-*   Left out, the app's sender is used. The call can never choose the sender.
-*
-* A field declared here wins over the call's, and declaring `to` also ignores the call's `cc` and
-* `bcc`. Fix the recipients whenever the use case allows,
-* because anyone in the audience can otherwise send any email to anyone.
-*
-* Pass the returned object to `email.send()` at runtime.
-*
-* @example
-* const notifyOwner = defineEmailAction({
-*   id: "notifyOwner",
-*   to: ["owner@acme.com"],
-*   permissions: { userGroupTypes: ["NON_LOGGED_IN_USERS", "LOGGED_IN_USERS"] },
-* })
-*
-* await email.send(notifyOwner, { subject: "New submission", body: html, replyTo: data.email })
-*/
-function defineEmailAction(definition) {
-	const { id, permissions,...inputs } = definition;
-	return {
-		id,
-		resource: {
-			type: "SOFTR_EMAIL",
-			inputs
-		},
-		permissions
-	};
-}
 function isDatasourceAction(value) {
 	if (typeof value !== "object" || value === null) return false;
 	const candidate = value;
@@ -105,4 +69,4 @@ function defineAiAction(definition) {
 }
 
 //#endregion
-export { defineAiAction, defineEmailAction, defineIntegration, defineMutation, defineQuery, defineWorkflow, isDatasourceAction };
+export { defineAiAction, defineIntegration, defineMutation, defineQuery, defineWorkflow, isDatasourceAction };

package/dist/default-error-overlay.d.ts

@@ -1,4 +1,4 @@
-import * as react0 from "react";
+import * as react6 from "react";
 
 //#region src/default-error-overlay.d.ts
 type Props = {
@@ -8,6 +8,6 @@ type Props = {
 declare function DefaultErrorOverlay({
   error,
   reset
-}: Props): react0.JSX.Element;
+}: Props): react6.JSX.Element;
 //#endregion
 export { DefaultErrorOverlay };

package/dist/formatting.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import * as react3 from "react";
+import * as react0 from "react";
 import { ReactNode } from "react";
 
 //#region src/formatting.d.ts
@@ -94,7 +94,7 @@ declare function FormattingScope({
   /** A BCP 47 locale, such as `de-DE`. It drops the app's fixed date format inside the scope. */
   locale?: string;
   children?: ReactNode;
-}): react3.FunctionComponentElement<react3.ProviderProps<Scope>>;
+}): react0.FunctionComponentElement<react0.ProviderProps<Scope>>;
 /**
  * A date in the app's format, safe to render on the server. A timestamp whose
  * zone is not known yet renders `fallback` until the browser supplies it, so
@@ -115,6 +115,6 @@ declare function FormattedDate({
   time?: boolean;
   /** What renders while the visitor's zone is unknown. */
   fallback?: ReactNode;
-}): react3.FunctionComponentElement<react3.FragmentProps>;
+}): react0.FunctionComponentElement<react0.FragmentProps>;
 //#endregion
 export { DateOptions, DateParts, DateSeparator, DateValue, FixedDateFormat, FormattedDate, Formatting, FormattingScope, WeekDay, formatDate, formatDateTime, formatNumber, useFormatting };

package/dist/index.d.ts

@@ -1,9 +1,8 @@
 import { SoftrUserGroupId, SoftrUserGroups, SoftrUserProperties, User } from "./auth/user.js";
-import { ActionPermissions, SoftrDatasources, defineAiAction, defineEmailAction, defineIntegration, defineMutation, defineQuery, defineWorkflow } from "./action.js";
+import { ActionPermissions, SoftrDatasources, defineAiAction, defineIntegration, defineMutation, defineQuery, defineWorkflow } from "./action.js";
 import { FileAttachment } from "./core/file-upload.js";
 import { FileItem, useFileUpload } from "./core/use-file-upload.js";
 import { AiAnswer, AiFile, AiGenerateInit, AiMessage, AiUsage } from "./core/ai.js";
-import { EmailSendInit, EmailSent } from "./core/email.js";
 import { DateOptions, DateParts, DateSeparator, DateValue, FixedDateFormat, FormattedDate, Formatting, FormattingScope, WeekDay, formatDate, formatDateTime, formatNumber, useFormatting } from "./formatting.js";
 import { SoftrContext } from "./auth/context.js";
 import { AuthSettings } from "./auth/platform.js";
@@ -19,4 +18,4 @@ import { useUserTimezone } from "./timezone.js";
 import { PwaInstall, PwaPlatform, SoftrPwaHead, usePwaInstall } from "./pwa.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
 import { Audience } from "./route/audience.js";
-export { type ActionPermissions, type AiAnswer, type AiFile, type AiGenerateInit, type AiMessage, type AiUsage, Audience, type AuthOptions, type AuthSettings, AuthSettingsProvider, type DateOptions, type DateParts, type DateSeparator, type DateValue, DefaultErrorOverlay, type EmailSendInit, type EmailSent, type FieldShape, type FileAttachment, type FileItem, type FixedDateFormat, FormattedDate, type Formatting, FormattingScope, type Page, type PageSettings, type PwaInstall, type PwaPlatform, type SoftrContext, type SoftrDatasources, type SoftrFieldRegistry, SoftrPwaHead, type SoftrUserGroupId, type SoftrUserGroups, type SoftrUserProperties, type User, type WeekDay, assertRouteAccess, checkAccess, defineAiAction, defineEmailAction, defineIntegration, defineMutation, definePage, defineQuery, defineVisibility, defineWorkflow, fieldShape, formatDate, formatDateTime, formatDuration, formatField, formatNumber, formatValue, getAuthSettings, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, pageHead, registerSoftrFields, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, useAuthSettings, useCurrentUser, useFileUpload, useFormatting, useOverrides, usePwaInstall, useUserTimezone };
+export { type ActionPermissions, type AiAnswer, type AiFile, type AiGenerateInit, type AiMessage, type AiUsage, Audience, type AuthOptions, type AuthSettings, AuthSettingsProvider, type DateOptions, type DateParts, type DateSeparator, type DateValue, DefaultErrorOverlay, type FieldShape, type FileAttachment, type FileItem, type FixedDateFormat, FormattedDate, type Formatting, FormattingScope, type Page, type PageSettings, type PwaInstall, type PwaPlatform, type SoftrContext, type SoftrDatasources, type SoftrFieldRegistry, SoftrPwaHead, type SoftrUserGroupId, type SoftrUserGroups, type SoftrUserProperties, type User, type WeekDay, assertRouteAccess, checkAccess, defineAiAction, defineIntegration, defineMutation, definePage, defineQuery, defineVisibility, defineWorkflow, fieldShape, formatDate, formatDateTime, formatDuration, formatField, formatNumber, formatValue, getAuthSettings, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, pageHead, registerSoftrFields, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, useAuthSettings, useCurrentUser, useFileUpload, useFormatting, useOverrides, usePwaInstall, useUserTimezone };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { defineAiAction, defineEmailAction, defineIntegration, defineMutation, defineQuery, defineWorkflow } from "./action.js";
+import { defineAiAction, defineIntegration, defineMutation, defineQuery, defineWorkflow } from "./action.js";
 import { useFileUpload } from "./core/use-file-upload.js";
 import { checkAccess, defineVisibility, isAuthorized } from "./route/visibility.js";
 import { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError } from "./route/route.js";
@@ -14,4 +14,4 @@ import { useUserTimezone } from "./timezone.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
 import { Audience } from "./route/audience.js";
 
-export { Audience, AuthSettingsProvider, DefaultErrorOverlay, FormattedDate, FormattingScope, SoftrPwaHead, assertRouteAccess, checkAccess, defineAiAction, defineEmailAction, defineIntegration, defineMutation, definePage, defineQuery, defineVisibility, defineWorkflow, fieldShape, formatDate, formatDateTime, formatDuration, formatField, formatNumber, formatValue, getAuthSettings, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, pageHead, registerSoftrFields, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, useAuthSettings, useCurrentUser, useFileUpload, useFormatting, useOverrides, usePwaInstall, useUserTimezone };
+export { Audience, AuthSettingsProvider, DefaultErrorOverlay, FormattedDate, FormattingScope, SoftrPwaHead, assertRouteAccess, checkAccess, defineAiAction, defineIntegration, defineMutation, definePage, defineQuery, defineVisibility, defineWorkflow, fieldShape, formatDate, formatDateTime, formatDuration, formatField, formatNumber, formatValue, getAuthSettings, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, pageHead, registerSoftrFields, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, useAuthSettings, useCurrentUser, useFileUpload, useFormatting, useOverrides, usePwaInstall, useUserTimezone };

package/dist/mcp.d.ts

@@ -1,5 +1,5 @@
 import { DatasourceAction } from "./action.js";
-import * as _tanstack_react_start0 from "@tanstack/react-start";
+import * as _tanstack_react_start7 from "@tanstack/react-start";
 
 //#region src/mcp.d.ts
 
@@ -31,6 +31,6 @@ type SoftrMcpOptions = {
  *   ],
  * }))
  */
-declare function softrMcpMiddleware(options?: SoftrMcpOptions): _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>;
+declare function softrMcpMiddleware(options?: SoftrMcpOptions): _tanstack_react_start7.RequestMiddlewareAfterServer<{}, undefined, undefined>;
 //#endregion
 export { softrMcpMiddleware };

package/dist/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.0.97-alpha.1";
+var version = "0.0.97";
 
 //#endregion
 export { version };

package/dist/pwa.d.ts

@@ -1,4 +1,4 @@
-import * as react1 from "react";
+import * as react4 from "react";
 import "@tanstack/react-start";
 
 //#region src/pwa.d.ts
@@ -23,7 +23,7 @@ import "@tanstack/react-start";
  *   )
  * }
  */
-declare function SoftrPwaHead(): react1.FunctionComponentElement<react1.FragmentProps>;
+declare function SoftrPwaHead(): react4.FunctionComponentElement<react4.FragmentProps>;
 type PwaPlatform = "ios" | "android" | "desktop";
 type PwaInstall = {
   available: false;

package/dist/server.d.ts

@@ -1,10 +1,9 @@
 import { upload } from "./core/file-upload.js";
 import { AiError, ai } from "./core/ai.js";
-import { EmailError, EmailErrorCode, email } from "./core/email.js";
 import { auth } from "./auth/server.js";
 import { FieldChoice, RecordOption, RecordOptions } from "./core/options.js";
 import { ds } from "./datasource/datasource.js";
 import { workflow } from "./core/workflow.js";
 import { integration } from "./core/integration.js";
 import "@tanstack/react-start/server-only";
-export { AiError, EmailError, type EmailErrorCode, type FieldChoice, type RecordOption, type RecordOptions, ai, auth, ds, email, integration, upload, workflow };
+export { AiError, type FieldChoice, type RecordOption, type RecordOptions, ai, auth, ds, integration, upload, workflow };

package/dist/server.js

@@ -4,7 +4,6 @@ import { auth } from "./auth/server.js";
 import { workflow } from "./core/workflow.js";
 import { integration } from "./core/integration.js";
 import { AiError, ai } from "./core/ai.js";
-import { EmailError, email } from "./core/email.js";
 import "@tanstack/react-start/server-only";
 
-export { AiError, EmailError, ai, auth, ds, email, integration, upload, workflow };
+export { AiError, ai, auth, ds, integration, upload, workflow };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.97-alpha.1",
+  "version": "0.0.97",
   "type": "module",
   "exports": {
     ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },

package/skills/softr-sdk/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.97-alpha.1
+  library_version: 0.0.97
 ---
 
 # Softr SDK core
@@ -22,8 +22,6 @@ metadata:
 >
 > **CRITICAL**: The app is already wired. `src/start.ts`, `src/router.tsx` and `src/routes/__root.tsx` register `softrAuthMiddleware` and resolve the session. Do not add a second registration of it. `softrMcpMiddleware` is the one thing an app adds to `src/start.ts` itself — load the `softr-sdk/mcp` sub-skill before doing so.
 >
-> **CRITICAL**: `email.send` lives on `@softr/sdk/server` and only runs inside a `createServerFn` handler. Use `defineEmailAction` from `@softr/sdk` to declare who may send it and the recipients it fixes. An email the app sends itself needs no workflow and no connected mail service. Load the `softr-sdk/email` sub-skill for the full pattern.
->
 > **CRITICAL**: `ai.generate` and `ai.stream` live on `@softr/sdk/server` and only run inside a `createServerFn` handler. Use `defineAiAction` from `@softr/sdk` to declare the action with the model it runs on, an id copied from the `ai_list_models` tool. Softr runs the model on its own keys; never ask the user for an API key for the app's own AI feature. Load the `softr-sdk/ai` sub-skill for the full pattern.
 >
 > **CRITICAL**: `workflow.trigger` lives on `@softr/sdk/server` and only runs inside a `createServerFn` handler. Use `defineWorkflow` from `@softr/sdk` to declare the action, then pass it to `workflow.trigger`. Load the `softr-sdk/workflows` sub-skill for the full pattern.
@@ -34,8 +32,8 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 
 | Import | Runs | Holds |
 | --- | --- | --- |
-| `@softr/sdk` | Both | `defineQuery`, `defineMutation`, `defineEmailAction`, `defineAiAction`, `definePage`, `pageHead`, `defineVisibility`, `guardRoute`, `assertRouteAccess`, `isAuthorized`, `checkAccess`, `Audience`, `useCurrentUser`, `useUserTimezone`, `FormattedDate`, `FormattingScope`, `useFormatting`, `formatDate`, `formatDateTime`, `formatNumber`, `formatValue`, `formatField`, `fieldShape`, `registerSoftrFields`, `useOverrides`, `SoftrPwaHead`, `usePwaInstall`, `getSoftrContext`, `initialSoftrContext`, `softrAuthMiddleware`, the error predicates, and every type |
-| `@softr/sdk/server` | Server only | `ds`, `auth`, `email`, `EmailError`, `workflow`, `integration`, `ai` |
+| `@softr/sdk` | Both | `defineQuery`, `defineMutation`, `defineAiAction`, `definePage`, `pageHead`, `defineVisibility`, `guardRoute`, `assertRouteAccess`, `isAuthorized`, `checkAccess`, `Audience`, `useCurrentUser`, `useUserTimezone`, `FormattedDate`, `FormattingScope`, `useFormatting`, `formatDate`, `formatDateTime`, `formatNumber`, `formatValue`, `formatField`, `fieldShape`, `registerSoftrFields`, `useOverrides`, `SoftrPwaHead`, `usePwaInstall`, `getSoftrContext`, `initialSoftrContext`, `softrAuthMiddleware`, the error predicates, and every type |
+| `@softr/sdk/server` | Server only | `ds`, `auth`, `workflow`, `integration`, `ai` |
 | `@softr/sdk/client` | Browser only | `useFileUpload` |
 | `@softr/sdk/vite` | Build | `softr()`, already in `vite.config.ts` |
 
@@ -49,11 +47,10 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 | Fetch records from a datasource | [record-queries/SKILL.md](./record-queries/SKILL.md) |
 | Chart, aggregate or count records | [charts-and-metrics/SKILL.md](./charts-and-metrics/SKILL.md) |
 | Create, update or delete a record | [record-mutations/SKILL.md](./record-mutations/SKILL.md) |
-| Send an email from the app: a form that emails the owner, a confirmation, staff emailing a client | [email/SKILL.md](./email/SKILL.md) |
 | Trigger a Softr workflow | [workflows/SKILL.md](./workflows/SKILL.md) |
 | Sign a visitor in, out, or up | [auth/SKILL.md](./auth/SKILL.md) |
 | Ask an AI model: a summary, an extraction from a document, a classification, a draft, a chat | [ai/SKILL.md](./ai/SKILL.md) |
-| Call a connected third-party API (Slack, Stripe, Gmail from the user's own mailbox, …), or an AI model on the user's own provider account | [integrations/SKILL.md](./integrations/SKILL.md) |
+| Call a connected third-party API (Slack, Stripe, Gmail, …), or an AI model on the user's own provider account | [integrations/SKILL.md](./integrations/SKILL.md) |
 | Open the app to AI assistants over MCP | [mcp/SKILL.md](./mcp/SKILL.md) |
 | Let visitors install the app on their home screen | [pwa/SKILL.md](./pwa/SKILL.md) |
 | Show a date, a time or a number | [formatting/SKILL.md](./formatting/SKILL.md) |
@@ -79,9 +76,6 @@ Drawing a chart, a stat tile, or any aggregated number?
 Submitting a form, editing a record, or deleting one?
   load softr-sdk/record-mutations
 
-Sending an email when a form is submitted or a button is pressed?
-  load softr-sdk/email — no workflow, no connected mail service
-
 Triggering a Softr workflow from a button or form?
   load softr-sdk/workflows
 

package/skills/softr-sdk/ai/SKILL.md

@@ -13,7 +13,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.97-alpha.1
+  library_version: 0.0.97
 ---
 
 **Boundary.** `ai` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineAiAction` and every type come from `@softr/sdk` and can be imported anywhere.
@@ -102,6 +102,8 @@ const summarize = createServerFn({ method: 'POST' })
   })
 ```
 
+The record id comes from the browser, so it can name any deal. The read of `dealQuery` takes the table's scope, like every other read of the table. Where reps see only their own deals, a read without it briefs anyone on any deal: see [record-queries](../record-queries/SKILL.md#keep-each-visitor-to-their-own-records).
+
 ## Extraction: an answer that is data
 
 A document dropped on the app, fields pulled out of it, a record created — the model reads the file and answers in the shape the record needs. Give it the schema and the file; validate the parsed answer before writing it, since a model may stray from the shape.

package/skills/softr-sdk/auth/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.97-alpha.1
+  library_version: 0.0.97
 ---
 
 **Boundary.** `auth` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build.

package/skills/softr-sdk/charts-and-metrics/SKILL.md

@@ -3,13 +3,13 @@ name: charts-and-metrics
 description: >-
   Aggregate records in a server function: ds.chart with groupBy, metrics, where,
   orderBy and date buckets for chart rows, ds.metric for one number, and
-  distinct values for filter controls. Use for a chart, a stat tile or any
-  counted, summed or averaged number, or when a chart comes back wrong. Single
-  records are record-queries.
+  distinct values for filter controls, scoped to the records the visitor may
+  read. Use for a chart, a stat tile or any counted, summed or averaged number,
+  or when a chart comes back wrong. Single records are record-queries.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.97-alpha.1
+  library_version: 0.0.97
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler or a server-side route hook — importing it into a component fails the build. `defineQuery` and every type come from `@softr/sdk` and can be imported anywhere.
@@ -166,6 +166,23 @@ const loadDashboard = createServerFn().handler(async () => {
 
 Each tile and panel is its own request, fired in parallel from one handler.
 
+### Scope a figure like the records behind it
+
+A chart or a metric reads the same records as a list, so it takes the same scope as every read of the table (see [record-queries](../record-queries/SKILL.md#keep-each-visitor-to-their-own-records)). Without it, a "my revenue" tile adds up everyone's sales, and a chart grouped by a person shows the names of people the visitor may not see. Here a rep sees only their own sales, and `usersQuery` is the app's query on the Users table:
+
+```ts
+import { auth, ds } from '@softr/sdk/server'
+
+const myRevenue = createServerFn().handler(async ({ context }) => {
+  const me = await auth.currentUserRow(context.user, usersQuery, 'email')
+  if (me === null) return null
+  const { value } = await ds
+    .metric(sales, (q) => q.amount.sum)
+    .where((q) => q.rep.isOneOf([me.id]))
+  return value
+})
+```
+
 ## Order of calls
 
 `groupBy` comes first and exactly once; a chart cannot be awaited before it. `metrics` follows, at most once, or not at all for distinct values. `where` can be chained anywhere, repeatedly, and calling it more than once ands the filters together. `orderBy` sorts by the chart's own keys, group and metric alike, and only sees the keys declared so far, so call it last.

package/skills/softr-sdk/current-user/SKILL.md

@@ -4,12 +4,12 @@ description: >-
   Read the signed-in Softr visitor: useCurrentUser and the User type,
   context.user in a route's beforeLoad, and context.user inside a server
   function handler, where Start types it from the app's registered request
-  middleware. Covers the null guest and the generated SoftrUserGroups that
-  narrows group ids to the app's own.
+  middleware. Covers the null guest, the generated SoftrUserGroups that narrows
+  group ids to the app's own, and reading the visitor's role on the server.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.97-alpha.1
+  library_version: 0.0.97
 ---
 
 # The current user
@@ -92,6 +92,19 @@ const getMyInvoices = createServerFn().handler(async ({ context }) => {
 
 `context.user` is typed. Start derives a handler's context from the app's registered request middleware as well as the server function's own, so there is nothing to import and nothing to cast.
 
+### The visitor's role, in a server function
+
+A server function that answers by role reads the role from `context.user.userGroupIds`, never from an argument. Use it to pick which query and which scope the role reads, as [record-queries](../record-queries/SKILL.md#keep-each-visitor-to-their-own-records) shows:
+
+```ts
+if (!context.user) throw new Error('Not signed in')
+if (context.user.userGroupIds.includes('00000000-0000-0000-0000-00000000000a')) {
+  // read with the staff query and the staff scope
+}
+```
+
+`context.user.id` is the visitor's account id, not their row in the Users table. A link to Users holds the row id, so a filter on such a link takes the row that `auth.currentUserRow` finds.
+
 ### Group ids are the app's own
 
 For every group's name and id, read `docs/user-groups.md`. It lists every group the app has, the predefined ones included. Copy an id from there; never derive one from a group's name.

package/skills/softr-sdk/file-uploads/SKILL.md

@@ -7,7 +7,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.97-alpha.1
+  library_version: 0.0.97
 ---
 
 **Boundary.** `upload` lives on `@softr/sdk/server` and runs inside server functions. `useFileUpload` and `FileItem` live on `@softr/sdk` and run in components. `FileAttachment` comes from `@softr/sdk` and can be imported anywhere.

package/skills/softr-sdk/formatting/SKILL.md

@@ -8,7 +8,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.97-alpha.1
+  library_version: 0.0.97
 ---
 
 # Dates, times and numbers

package/skills/softr-sdk/integrations/SKILL.md

@@ -7,7 +7,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.97-alpha.1
+  library_version: 0.0.97
 ---
 
 **Boundary.** `integration` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineIntegration` and every type come from `@softr/sdk` and can be imported anywhere.
@@ -16,8 +16,6 @@ metadata:
 
 `integration.createFetcher` calls a third-party API through Softr's authenticated proxy. It adds the connected account's credentials automatically — you never set API keys or auth headers yourself. **Every call acts as that one account, whoever the visitor is**, so take what a call reaches, such as a customer or a channel, from the session or a record the server read, never from the arguments the browser sends.
 
-An email the app sends is the `email` sub-skill, with nothing to connect. Send through a connected Gmail or Outlook only when the user wants the email to come from their own mailbox.
-
 ## Setup
 
 ```ts

package/skills/softr-sdk/mcp/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.97-alpha.1
+  library_version: 0.0.97
 ---
 
 **Boundary.** `softrMcpMiddleware` lives on `@softr/sdk` and is registered once, in `src/start.ts`. The actions you hand it are the same `defineQuery` / `defineMutation` values the app's own pages use — declared wherever they already live, not duplicated for MCP.

package/skills/softr-sdk/pwa/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.97-alpha.1
+  library_version: 0.0.97
 ---
 
 # Installing the app

package/skills/softr-sdk/record-mutations/SKILL.md

@@ -2,13 +2,14 @@
 name: record-mutations
 description: >-
   Create, update and delete records with defineMutation, ds.create, ds.update
-  and ds.delete: the payload keyed by your own field names and what each field
-  type accepts. Use when submitting a form, saving an edit or deleting a record,
-  or when a write fails or changes nothing. Reads are record-queries.
+  and ds.delete: the payload keyed by your own field names, what each field type
+  accepts, and keeping an update or a delete to the records the visitor may
+  read. Use when submitting a form, saving an edit or deleting a record, or when
+  a write fails or changes nothing. Reads are record-queries.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.97-alpha.1
+  library_version: 0.0.97
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineMutation` and every type come from `@softr/sdk` and can be imported anywhere.
@@ -111,6 +112,42 @@ const removeProject = createServerFn({ method: 'POST' })
 
 Resolves to nothing. A record that cannot be deleted throws.
 
+### Change only the records the visitor may read
+
+When a role reads only some records of a table, it updates and deletes only those records. `permissions` decides who may run the mutation, not which record. The id comes from the browser, so it can name any record. Before the write, read the record through the same query and scope as every read of the table (see [record-queries](../record-queries/SKILL.md#keep-each-visitor-to-their-own-records)). Refuse the write when that read answers `null`, with the same error as a missing record, so the visitor cannot find out which ids exist. Keep the field that the scope filters on, such as the owner, out of the update's `fields`. If it is in `fields`, a visitor can move a record to another person.
+
+Below, `bookings` is the query every read of bookings uses, and `usersQuery` is the app's query on the Users table. `updateBooking` declares `status` only, not `client`.
+
+```ts
+import { auth, ds } from '@softr/sdk/server'
+
+const cancelBooking = createServerFn({ method: 'POST' })
+  .validator(z.object({ id: z.string() }))
+  .handler(async ({ context, data }) => {
+    const me = await auth.currentUserRow(context.user, usersQuery, 'email')
+    if (me === null) throw new Error('Booking not found')
+    const booking = await ds.get(bookings, { id: data.id }).where((q) => q.client.isOneOf([me.id]))
+    if (booking === null) throw new Error('Booking not found')
+    await ds.update(updateBooking, { id: booking.id, data: { status: { id: 'cancelled' } } })
+  })
+```
+
+A delete takes the same read before `ds.delete`. A create into a table that takes its parent's scope, such as a message in a chat, reads the parent through its scope before `ds.create` (see [record-queries](../record-queries/SKILL.md#a-table-with-no-link-to-users-takes-its-parents-scope)).
+
+### Only the roles that change a table
+
+Often fewer roles change a table than read it. A mutation's `customGroups` names only the roles that may change the table, also when more roles read it. In a barber app, every client reads the free hours, but only barbers open or close them. So the slot update names the barbers' group only, and a barber still changes only their own slots, through the read above:
+
+```ts
+const updateSlot = defineMutation({
+  id: 'updateSlot',
+  datasourceId: '00000000-0000-0000-0000-000000000004',
+  operation: 'update',
+  fields: { open: 'Wd5nKp2xRb8Tc3' },
+  permissions: { userGroupTypes: ['LOGGED_IN_USERS'], customGroups: ['00000000-0000-0000-0000-00000000000b'] },
+})
+```
+
 ### Edit an existing record
 
 An edit form needs both halves: a `defineQuery` to load the record and a `defineMutation` to save it. They are separate declarations over the same table, so give both the fields the form touches, and read the loaded values off the query's names.

package/skills/softr-sdk/record-queries/SKILL.md

@@ -2,14 +2,15 @@
 name: record-queries
 description: >-
   Fetch records with defineQuery, ds.list and ds.get: where and orderBy, field
-  names of your own choosing, pagination and its limits, and scoping a read to
-  the signed-in visitor. Use to put records on a page or fill a dropdown, or
-  when a read comes back empty, unsorted or missing a field. Writes are
-  record-mutations; totals and chart rows are charts-and-metrics.
+  names of your own choosing, pagination and its limits, and keeping each
+  visitor to their own records and to the fields their role may see. Use to put
+  records on a page or fill a dropdown, to write any server function that reads
+  a table, or when a read comes back empty, unsorted or missing a field. Writes
+  are record-mutations; totals and chart rows are charts-and-metrics.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.97-alpha.1
+  library_version: 0.0.97
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler or a server-side route hook — importing it into a component fails the build. The same holds for any helper that calls `ds`: declare it inside the handler. A function at module level that calls `ds` keeps the server-only import in the browser bundle, and every page stops loading until it moves. `defineQuery` and every type come from `@softr/sdk` and can be imported anywhere.
@@ -125,37 +126,6 @@ if (first.nextOffset !== null) {
 
 `nextOffset` is `null` when there are no more pages. `total` is the count of all matching records, not the count returned.
 
-### Scope the read to the visitor
-
-```ts
-const myInvoices = defineQuery({
-  id: 'myInvoices',
-  datasourceId: '00000000-0000-0000-0000-000000000001',
-  fields: { owner: 'Gq5wNt8rJy3Hb1', amount: 'Vk9cXm2pSz6Ld4' },
-  permissions: { userGroupTypes: ['LOGGED_IN_USERS'] },
-})
-
-const listMyInvoices = createServerFn().handler(async ({ context }) => {
-  if (!context.user) throw new Error('Not signed in')
-  const userId = context.user.id
-  return await ds.list(myInvoices).where((q) => q.owner.is(userId))
-})
-```
-
-When the owner is a link to the Users table, the row to match is the visitor's own row there, not `context.user.id`. `auth.currentUserRow(context.user, usersQuery, 'email')` finds it by email, or answers `null` when they are signed out or have no row:
-
-```ts
-import { auth, ds } from '@softr/sdk/server'
-
-const listMyDeals = createServerFn().handler(async ({ context }) => {
-  const me = await auth.currentUserRow(context.user, usersQuery, 'email')
-  if (me === null) return { records: [], nextOffset: null }
-  return await ds.list(deals).where((q) => q.owner.isOneOf([me.id]))
-})
-```
-
-The SDK enforces `permissions`, so a visitor outside the declared audience never reaches the records. Which of those records belong to one visitor is a separate question, and the `where` above answers it: a group says nothing about who owns a row, so a per-visitor read filters on `context.user`. See [current-user](../current-user/SKILL.md) for how the visitor gets onto `context`.
-
 ### Populate a control from a linked table
 
 A `LINKED_RECORD` field on a record answers with `{ id, label }` — the label is the linked record's primary field, and the id is what a write or a `where` filter takes. To fill a filter dropdown or form select with **all** options from the linked table (not just the values already referenced by existing records), query the linked table's own datasource:
@@ -194,6 +164,8 @@ const loadProductStatuses = createServerFn()
   .handler(({ data }) => ds.options(productStatuses, { label: 'name', ...data }))
 ```
 
+`ds.options` takes no `where`, so use it only over a table with no scope. A picker over a scoped table reads with `ds.list` and the scope: see [A picker over a scoped table](#a-picker-over-a-scoped-table).
+
 Skip this request when the options are predefined and fixed — hardcode them instead.
 
 A `SELECT` field's options are its choices, and the builder can add and rename them in Studio after the app is built. When a dropdown should follow those changes, read them with `ds.choices`. When the app means a fixed choice, such as a "Done" tab, use its id directly. A mistyped id is not caught at compile time, and a write with an id the field lacks adds it as a new choice. `ds.choices` takes any query or mutation that declares the field and answers `[{ id, label, color }]` as the field holds them now. Each `id` is what a `where` and a write take, for a filter dropdown and a form select alike:
@@ -205,6 +177,130 @@ const loadCategories = createServerFn().handler(() => ds.choices(products, 'cate
 
 A read the datasource turns down throws rather than coming back empty, and it throws a plain `Error` carrying the status, followed by the reason the datasource gives when it sends one. There is no typed predicate to narrow it with. Handle it where you would handle any other failed fetch: an `errorComponent` on the route, or a check in the handler.
 
+## Keep each visitor to their own records
+
+`permissions` decides who may run a query. It does not decide which rows they get, and it does not hide a field the query declares. A visitor can call every server function with any arguments, so one read that skips a rule opens the table to them. The examples below use `bookings`, a query over a table where a client sees only their own bookings, and `usersQuery`, the app's query on the Users table.
+
+### One scope per table, in every read
+
+A privacy rule from the builder's prompt, such as "clients see only their own bookings", belongs to the table, not to the page where it came up. Every server function that reads the table applies the same `where`: the list, the get by id, a search, a picker, a count and a chart. Keep these server functions beside the table's queries, so the copies of the filter stay together and a new read is written next to them. A get by id takes the same `where`, so an id outside the scope reads as `null`.
+
+```ts
+// Bookings are private: a client reads only the bookings linked to their own Users row.
+// Every read of bookings applies this filter.
+const getMyBooking = createServerFn()
+  .validator(z.object({ id: z.string() }))
+  .handler(async ({ context, data }) => {
+    const me = await auth.currentUserRow(context.user, usersQuery, 'email')
+    if (me === null) return null
+    return await ds.get(bookings, { id: data.id }).where((q) => q.client.isOneOf([me.id]))
+  })
+```
+
+The filter matches the field that holds the owner. A link to the Users table holds the visitor's row there, not `context.user.id`. `auth.currentUserRow(context.user, usersQuery, 'email')` finds that row by email, or answers `null` when they are signed out or have no row. A `USER` field holds the account itself, so it filters on `context.user.id` after a check for a signed-out visitor. See [current-user](../current-user/SKILL.md) for how the visitor gets onto `context`.
+
+### A picker over a scoped table
+
+`ds.options` takes no `where`, so a picker over a scoped table reads with `ds.list` and the scope, and maps the records to the `{ id, label }` the picker takes. Here `title` is the field of `bookings` the picker shows:
+
+```ts
+const loadMyBookings = createServerFn()
+  .validator(z.object({ term: z.string(), offset: z.number().nullable() }))
+  .handler(async ({ context, data }) => {
+    const me = await auth.currentUserRow(context.user, usersQuery, 'email')
+    if (me === null) return { options: [], nextOffset: null }
+    const term = data.term.trim()
+    let list = ds.list(bookings).where((q) => q.client.isOneOf([me.id]))
+    if (term !== '') list = list.where((q) => q.title.contains(term))
+    const page = await list.offset(data.offset).limit(20)
+    return {
+      options: page.records.map((record) => ({ id: record.id, label: record.fields.title ?? '' })),
+      nextOffset: page.nextOffset,
+    }
+  })
+```
+
+### Server functions you add use the same scope
+
+A server function you write for a new page or widget applies the table's scope too. When it needs other fields, it may declare its own query over the table, but every query over a scoped table takes the same scope. A query read without it is a second path to the same rows.
+
+```ts
+const nextBookings = defineQuery({
+  id: 'nextBookings',
+  datasourceId: '00000000-0000-0000-0000-000000000002',
+  fields: { date: 'Xp2dLh6vKz9Fa3', client: 'Pc8vNm3kTq6Wz2' },
+  permissions: { userGroupTypes: ['LOGGED_IN_USERS'] },
+})
+
+// Wrong: read with no scope. Every client sees every booking.
+const loadNext = createServerFn().handler(() => ds.list(nextBookings).limit(3))
+
+// Right: the same scope as every other read of bookings.
+const loadNext = createServerFn().handler(async ({ context }) => {
+  const me = await auth.currentUserRow(context.user, usersQuery, 'email')
+  if (me === null) return { records: [], total: 0, nextOffset: null }
+  return await ds
+    .list(nextBookings)
+    .where((q) => q.client.isOneOf([me.id]))
+    .orderBy((q) => q.date.asc)
+    .limit(3)
+})
+```
+
+The scope filters on `client`, so `nextBookings` declares it, also when the page does not show it.
+
+### A table with no link to Users takes its parent's scope
+
+Some tables have no link to Users. Chat messages belong to a chat, and the browser sends the chat id. If a server function reads the messages by that id alone, any chat id reads its messages. The same goes for a game room read by its code. Such a table takes its parent's scope: read the parent through its own scope first. Read or post the children only when that read answers, and filter them on the parent that it answered. Here `chats` has a `members` link to Users, and `messages` has a `chat` link to chats:
+
+```ts
+const listMessages = createServerFn()
+  .validator(z.object({ chatId: z.string() }))
+  .handler(async ({ context, data }) => {
+    const me = await auth.currentUserRow(context.user, usersQuery, 'email')
+    if (me === null) throw new Error('Chat not found')
+    const chat = await ds.get(chats, { id: data.chatId }).where((q) => q.members.isOneOf([me.id]))
+    if (chat === null) throw new Error('Chat not found')
+    return await ds
+      .list(messages)
+      .where((q) => q.chat.isOneOf([chat.id]))
+      .orderBy((q) => q.sentAt.asc)
+      .limit(100)
+  })
+```
+
+A server function that posts a message reads the chat the same way before `ds.create`.
+
+### Other people's records show only what the role needs
+
+A read returns every field its query declares, and everything a server function returns reaches the browser, also when the page does not show it. A list of other people, such as a directory or the members of a chat, declares only the fields its role needs, so no email or phone unless the role needs them. A `USER` field reads back with the person's email, so a list that must not show emails does not declare one either. When roles need different fields, declare one query per role, each with its own `fields` and `permissions`, and pick the query on the server by the visitor's groups:
+
+```ts
+const peopleForMembers = defineQuery({
+  id: 'peopleForMembers',
+  datasourceId: '00000000-0000-0000-0000-000000000003',
+  fields: { name: 'Hn4tRw8kPz2Mc5', jobTitle: 'Lb7yQe3vXa9Ns1' },
+  permissions: { userGroupTypes: ['LOGGED_IN_USERS'] },
+})
+
+const peopleForStaff = defineQuery({
+  id: 'peopleForStaff',
+  datasourceId: '00000000-0000-0000-0000-000000000003',
+  fields: { name: 'Hn4tRw8kPz2Mc5', jobTitle: 'Lb7yQe3vXa9Ns1', email: 'Td2kWm6pFs8Jq4' },
+  permissions: { userGroupTypes: ['LOGGED_IN_USERS'], customGroups: ['00000000-0000-0000-0000-00000000000a'] },
+})
+
+const listPeople = createServerFn().handler(async ({ context }) => {
+  if (!context.user) throw new Error('Not signed in')
+  if (context.user.userGroupIds.includes('00000000-0000-0000-0000-00000000000a')) {
+    return await ds.list(peopleForStaff).limit(100)
+  }
+  return await ds.list(peopleForMembers).limit(100)
+})
+```
+
+A role that may change only some rows changes only the rows it can read: see [record-mutations](../record-mutations/SKILL.md). A count or a chart over the table takes the same scope: see [charts-and-metrics](../charts-and-metrics/SKILL.md).
+
 ## Typing
 
 Queries you write are type safe and a type error is shown when there's a mistake. The records a read returns are typed the same way, so never validate them again with a zod schema of your own. A schema guesses each field's shape, and one value it misses, such as a person with no email, throws for the whole read and the page stops loading. Show each field with a fallback instead: `record.fields.owner?.name ?? '—'`. For an in depth reference on what fields every datasource has, read `docs/datasources/README.md` first — it lists every registered datasource with a link to its file. Follow those links to get field ids, types, and constraints. Do not guess filenames from table names.

package/skills/softr-sdk/region-visibility/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.97-alpha.1
+  library_version: 0.0.97
 ---
 
 **Boundary.** `Audience` and `defineVisibility` come from `@softr/sdk` and work anywhere.

package/skills/softr-sdk/routes-and-visibility/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.97-alpha.1
+  library_version: 0.0.97
 ---
 
 **Boundary.** `definePage`, `pageHead`, the access functions and the error predicates come from `@softr/sdk` and work anywhere.
@@ -73,7 +73,7 @@ Everyone is both audiences, as in the first line above. A set names each audienc
 
 Take every id in `customGroups` from `docs/user-groups.md`, which lists each group the app has with its name and id. An id the app does not have is a type error.
 
-**`visibility` guards the page, not the server functions it calls.** A call can reach them without the page and with any arguments, so the queries and mutations behind a page carry its groups in their own `permissions` and reach only the rows the visitor's role allows.
+**`visibility` guards the page, not the server functions it calls.** A call can reach them without the page and with any arguments, so the queries and mutations behind a page carry its groups in their own `permissions`. `permissions` decide who may run them, not which rows they reach: each server function filters the rows itself, as [record-queries](../record-queries/SKILL.md#keep-each-visitor-to-their-own-records) shows.
 
 ## Core Patterns
 

package/skills/softr-sdk/workflows/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.97-alpha.1
+  library_version: 0.0.97
 ---
 
 **Boundary.** `workflow` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineWorkflow` and every type come from `@softr/sdk` and can be imported anywhere.
@@ -18,8 +18,6 @@ metadata:
 
 `workflow.trigger` fires a Softr workflow and waits for it to finish. It resolves to `void`.
 
-An email the app sends itself, when a form is submitted or a button is pressed, needs no workflow: load the `email` sub-skill. Fire a workflow for what the workflow's own steps do, such as updating a CRM or posting to a connected service.
-
 ## Setup
 
 ```ts
@@ -33,15 +31,15 @@ import { workflow } from '@softr/sdk/server'
 Every trigger needs a workflow action: which workflow, which trigger step, who may run it, and any data that is always sent. The workflow must have a **Run custom workflow** trigger — no other trigger type can be fired from app code.
 
 ```ts
-const syncNewLead = defineWorkflow({
-  id: 'syncNewLead',
+const sendWelcomeEmail = defineWorkflow({
+  id: 'sendWelcomeEmail',
   workflowId: 'c9d8e7f6-a5b4-4c3d-8e2f-1a0b9c8d7e6f',
   triggerId: '926da496-749f-4006-999c-197d8a556122',
   permissions: { userGroupTypes: ['LOGGED_IN_USERS'] },
   body: {
     email: '{LOGGED_IN_USER:EMAIL}',  // resolved server-side from the signed-in user
     name: '{LOGGED_IN_USER:NAME}',
-    source: 'website',                // any hardcoded value — always sent, never overridden at runtime
+    plan: 'enterprise',               // any hardcoded value — always sent, never overridden at runtime
   },
 })
 ```
@@ -72,7 +70,7 @@ These placeholders are resolved server-side when the workflow runs:
 const runWorkflow = createServerFn({ method: 'POST' })
   .validator(z.object({ message: z.string() }))
   .handler(async ({ data }) => {
-    await workflow.trigger(syncNewLead, { message: data.message })
+    await workflow.trigger(sendWelcomeEmail, { message: data.message })
   })
 ```
 
@@ -84,7 +82,7 @@ const runWorkflow = createServerFn({ method: 'POST' })
 
 ```ts
 const run = createServerFn({ method: 'POST' }).handler(async () => {
-  await workflow.trigger(syncNewLead)
+  await workflow.trigger(sendWelcomeEmail)
 })
 ```
 
@@ -96,11 +94,11 @@ Omit the second argument when the action's `body` already carries everything the
 
 ```ts
 // Wrong: calling from a click handler
-<button onClick={() => workflow.trigger(syncNewLead)}>Run</button>
+<button onClick={() => workflow.trigger(sendWelcomeEmail)}>Run</button>
 
 // Correct: server function, called from the button
 const run = createServerFn({ method: 'POST' }).handler(() =>
-  workflow.trigger(syncNewLead),
+  workflow.trigger(sendWelcomeEmail),
 )
 // …
 const submit = useServerFn(run)

package/dist/core/email.d.ts

@@ -1,46 +0,0 @@
-import { EmailAction } from "../action.js";
-
-//#region src/core/email.d.ts
-declare const EMAIL_ERROR_CODES: readonly ["NOT_FOUND", "INVALID_INPUT", "PLAN_RESTRICTED", "CREDITS_EXHAUSTED", "RATE_LIMITED", "PROVIDER_REJECTED", "UNAVAILABLE", "TIMEOUT"];
-type EmailErrorCode = (typeof EMAIL_ERROR_CODES)[number];
-interface EmailSendInit {
-  /** Ignored when the action declares its own. */
-  to?: ReadonlyArray<string>;
-  /** Ignored when the action declares its own `cc` or `to`. */
-  cc?: ReadonlyArray<string>;
-  /** Ignored when the action declares its own `bcc` or `to`. */
-  bcc?: ReadonlyArray<string>;
-  /** Ignored when the action declares its own. */
-  replyTo?: string;
-  subject: string;
-  /** Plain text or HTML. */
-  body: string;
-}
-interface EmailSent {
-  /** Null when the mail provider did not report one; the email was still sent. */
-  messageId: string | null;
-}
-/**
- * Thrown when Softr did not send the email. `code` says why:
- *
- * - `NOT_FOUND`: no such action, or the caller is not in its audience.
- * - `INVALID_INPUT`: the call's inputs were refused; the message says which.
- * - `PLAN_RESTRICTED`: the workspace's plan does not include sending this email.
- * - `CREDITS_EXHAUSTED`: the workspace has no workflow credits left.
- * - `RATE_LIMITED`: the app sent too many emails lately; try again later.
- * - `PROVIDER_REJECTED`: the mail provider refused the email.
- * - `UNAVAILABLE`: Softr could not send it right now, or could not be reached.
- * - `TIMEOUT`: no answer in time. It may still have been sent.
- */
-declare class EmailError extends Error {
-  readonly status: number;
-  readonly code: EmailErrorCode;
-  constructor(status: number, code: EmailErrorCode, message: string);
-}
-/** Sends one email through the action. Never retries by itself. */
-declare function sendEmail(action: EmailAction, init: EmailSendInit): Promise<EmailSent>;
-declare const email: {
-  send: typeof sendEmail;
-};
-//#endregion
-export { EmailError, EmailErrorCode, EmailSendInit, EmailSent, email };

package/dist/core/email.js

@@ -1,96 +0,0 @@
-import { assert } from "../assertions.js";
-import { softrApiUrl } from "../softr-api.js";
-import { fetch } from "../fetch.js";
-import { sessionConfig } from "../auth/config.js";
-import { readSessionToken } from "../auth/session.js";
-
-//#region src/core/email.ts
-/** Longer than Softr waits for the send itself, so its own timeout answers first. */
-const TIMEOUT_MS = 12e4;
-const EMAIL_ERROR_CODES = [
-	"NOT_FOUND",
-	"INVALID_INPUT",
-	"PLAN_RESTRICTED",
-	"CREDITS_EXHAUSTED",
-	"RATE_LIMITED",
-	"PROVIDER_REJECTED",
-	"UNAVAILABLE",
-	"TIMEOUT"
-];
-/**
-* Thrown when Softr did not send the email. `code` says why:
-*
-* - `NOT_FOUND`: no such action, or the caller is not in its audience.
-* - `INVALID_INPUT`: the call's inputs were refused; the message says which.
-* - `PLAN_RESTRICTED`: the workspace's plan does not include sending this email.
-* - `CREDITS_EXHAUSTED`: the workspace has no workflow credits left.
-* - `RATE_LIMITED`: the app sent too many emails lately; try again later.
-* - `PROVIDER_REJECTED`: the mail provider refused the email.
-* - `UNAVAILABLE`: Softr could not send it right now, or could not be reached.
-* - `TIMEOUT`: no answer in time. It may still have been sent.
-*/
-var EmailError = class extends Error {
-	status;
-	code;
-	constructor(status, code, message) {
-		super(message);
-		this.name = "EmailError";
-		this.status = status;
-		this.code = code;
-	}
-};
-/** Sends one email through the action. Never retries by itself. */
-async function sendEmail(action, init) {
-	const { to, cc, bcc, replyTo, subject, body } = init;
-	const sessionToken = readSessionToken();
-	let res;
-	try {
-		res = await fetch(`${softrApiUrl("SOFTR_PLATFORM_API_URL")}/v1/vibe/applications/${sessionConfig().applicationId}/actions/${action.id}/email`, {
-			method: "POST",
-			headers: {
-				...sessionToken ? { Authorization: `Bearer ${sessionToken}` } : {},
-				"Content-Type": "application/json"
-			},
-			body: JSON.stringify({ input: {
-				to,
-				cc,
-				bcc,
-				replyTo,
-				subject,
-				body
-			} }),
-			signal: AbortSignal.timeout(TIMEOUT_MS)
-		});
-	} catch (error) {
-		if (error instanceof DOMException && error.name === "TimeoutError") throw new EmailError(504, "TIMEOUT", `Email "${action.id}" got no answer in time. It may still have been sent.`);
-		throw new EmailError(502, "UNAVAILABLE", `Email "${action.id}" could not reach Softr: ${error instanceof Error ? error.message : String(error)}`);
-	}
-	if (res.ok) {
-		const sent = await res.json();
-		assert(typeof sent === "object" && sent !== null && "messageId" in sent && (typeof sent.messageId === "string" || sent.messageId === null), "the send answered without a messageId");
-		return { messageId: sent.messageId };
-	}
-	const { code, message } = await readFailure(res, `Email "${action.id}" failed with HTTP ${res.status}`);
-	throw new EmailError(res.status, code, message);
-}
-/** The code and message of a send Softr refused, read from its answer; `fallbackMessage` when it sent none. */
-async function readFailure(res, fallbackMessage) {
-	const failure = await res.json().catch(() => null);
-	const known = typeof failure === "object" && failure !== null ? failure : {};
-	return {
-		code: ("code" in known ? EMAIL_ERROR_CODES.find((errorCode) => errorCode === known.code) : void 0) ?? codeOfStatus(res.status),
-		message: "message" in known && typeof known.message === "string" && known.message !== "" ? known.message : fallbackMessage
-	};
-}
-function codeOfStatus(status) {
-	switch (status) {
-		case 400: return "INVALID_INPUT";
-		case 404: return "NOT_FOUND";
-		case 429: return "RATE_LIMITED";
-		default: return "UNAVAILABLE";
-	}
-}
-const email = { send: sendEmail };
-
-//#endregion
-export { EmailError, email };

package/skills/softr-sdk/email/SKILL.md

@@ -1,129 +0,0 @@
----
-name: email
-description: >-
-  Send an email from the app itself, with nothing to connect and no workflow:
-  defineEmailAction from @softr/sdk declares who may send it and the fields it
-  fixes (to, cc, bcc, replyTo, and an optional senderId); email.send from
-  @softr/sdk/server sends one with a subject and a text or HTML body, and throws
-  an EmailError with a code when Softr does not send it. Load this for a contact
-  form that emails the owner, a confirmation to the signed-in user, staff
-  emailing a client, or any email the app sends while handling what a person
-  does in it.
-metadata:
-  type: sub-skill
-  library: softr-sdk
-  library_version: 0.0.97-alpha.1
----
-
-**Boundary.** `email` and `EmailError` live on `@softr/sdk/server` and run only inside a `createServerFn` handler — importing them into a component fails the build. `defineEmailAction` and every type come from `@softr/sdk` and can be imported anywhere.
-
-# Email
-
-An app sends an email through an email action. Softr sends it from the app's email sender and bills the workspace's **workflow credits**, so there is no mail service to connect and no workflow to build. Use it for every email the app sends while it handles something a person does in it: a form submitted, a button pressed, a record saved through the app.
-
-A workflow is still the answer for an email on a schedule ("every Monday") or on a change made outside the app (a record edited in the table): load `automate-with-workflows` for those. A connected Gmail or Outlook is the answer only when the user wants the email to come from their own mailbox, through the `integrations` sub-skill.
-
-`defineEmailAction` missing from `@softr/sdk`? The app was built on an older version. Upgrade `@softr/sdk` to the latest version first, then write the action.
-
-## Who can send it, and to whom
-
-The action's `permissions` is its audience: everyone in it can send an email through it, directly, without the app's own code. The app's code is not a guard. Only what the declaration fixes holds whatever the caller sends.
-
-- **Fix the recipients whenever the use case allows.** A contact form that emails the owner fixes `to` to the owner. "Email me this report" fixes `to` to `{LOGGED_IN_USER:EMAIL}`. Then nobody can send the app's email to anyone else.
-- **When people pick the recipients, narrow the audience.** "Staff email a client" leaves `to` open and keeps the action to the staff group with `customGroups`. An action with open recipients for all signed-in users lets anyone who signs up send any email to anyone from the app's address, up to the workspace's credits. Build that only when the user asks for it, and tell them so in one line. An action open to visitors must fix `to`: one that fixes only `cc` or `bcc` is not stored.
-
-## The sender
-
-Every email comes from the app's email sender, unless the action names one of the workspace's senders with `senderId`. With no sender set, they come from the app's default `@softr.app` address, the one its sign-in emails use.
-
-- Read the app's sender with `application_get` before you say where the emails come from, and name it. Never write "if no sender is set": read it. With no sender set, that tool shows the app's default `@softr.app` address: name that one. Say in your closing message when no sender is set, and that the app should get its own sender before real users rely on its emails.
-- When the app has no sender of its own, list the workspace's senders with `workspace_list_email_senders` and offer the confirmed ones by name: for this email (`senderId`, nothing else changes) or as the app's sender. Never pick one yourself.
-- Changing the app's sender also changes the address its sign-in emails come from. Ask the user before you call `application_configure_email_sender`, and name both effects. A workspace whose plan has no custom senders is refused; then say that sending from their own address needs the Professional plan.
-- Set `senderId` only when the user wants this email from a specific address, such as `billing@`. Pick it from `workspace_list_email_senders`, copied exactly. A sender the mail provider has not confirmed makes every send fail until it is confirmed. That confirmation is all an email action needs; the domain's DNS records (DKIM, Return-Path) are needed only before Studio lets the app pick the address as its own sender, and they help the emails stay out of spam.
-
-## What it costs
-
-Every email costs **5 workflow credits per recipient**, from the workspace's monthly workflow credits, which its workflows spend too. You do not know the workspace's plan, so never name one or count how many emails it covers. The plan and the closing message give the cost and where to watch it, for example: "Each submission emails you, at 5 workflow credits per email. Track them in Settings → Billing → Workflow usage, where this app has its own row."
-
-Emails sent from the preview are real and charged, and the actions in the code reach the live app as soon as they are saved. Send at most one test email, and only when the user asks for one. Never send emails in a loop to try something out.
-
-## Declare the action
-
-```ts
-const notifyOwner = defineEmailAction({
-  id: 'notifyOwner',
-  to: ['owner@acme.com'],
-  permissions: { userGroupTypes: ['NON_LOGGED_IN_USERS', 'LOGGED_IN_USERS'] },
-})
-
-const emailClient = defineEmailAction({
-  id: 'emailClient',
-  replyTo: '{LOGGED_IN_USER:EMAIL}',
-  permissions: { userGroupTypes: ['LOGGED_IN_USERS'], customGroups: ['<the staff group id>'] },
-})
-```
-
-- `id` is a name you choose, unique across the app.
-- `to`, `cc`, `bcc`: arrays of addresses. Each one declared here replaces the call's, and declaring `to` also ignores the call's `cc` and `bcc`. An element may be a whole placeholder for the signed-in sender: `{LOGGED_IN_USER:EMAIL}`, or `{LOGGED_IN_USER:<field>}` for an email field of their user record. Never part of a string, never in the call.
-- `replyTo`: an address or one such placeholder.
-- `senderId`: one of the workspace's senders, as above. The call can never set the sender.
-- `permissions`: who may send it, as for queries and mutations.
-
-Write the object inline in `defineEmailAction`, every value a literal. A declaration that cannot be read is not stored, and the check reports it.
-
-Declare one action per kind of email: the owner's notification and the client's confirmation are two actions, each with its own recipients and audience.
-
-## Core pattern
-
-```ts
-const submit = createServerFn({ method: 'POST' })
-  .validator(contactSchema)
-  .handler(async ({ data }) => {
-    const saved = await ds.create(saveSubmission, { data })
-    try {
-      await email.send(notifyOwner, {
-        subject: `New message from ${data.name}`,
-        body: renderSubmission(data),  // the app's own HTML, with what the visitor typed escaped
-        replyTo: data.email,
-      })
-    } catch (error) {
-      if (error instanceof EmailError) return { saved: true, emailed: false, reason: error.message }
-      throw error
-    }
-    return { saved: true, emailed: true }
-  })
-```
-
-`email.send(action, init)` takes:
-
-- `subject` and `body`. Required. `body` is plain text or HTML. Escape what visitors typed before you put it into HTML.
-- `to`, `cc`, `bcc`, `replyTo`: each used only where the action does not fix it, and `cc` and `bcc` never when it fixes `to`. Each entry is one address. At most 50 recipients per email.
-
-It answers `{ messageId }` once the email is sent. The answer never lists the recipients. An email carries no attachments: link to the file instead.
-
-Every call is a new email. Disable the button while the request runs, so a double click does not send twice.
-
-## Failure modes
-
-**Not handling `EmailError`.** `email.send` throws an `EmailError` from `@softr/sdk/server`, with `status`, `code` and `message` when the email was not sent, and never retries by itself. Catch it, keep what the request already saved, and show the person a line they can act on: "Saved, but the email could not be sent." The codes:
-
-| `code` | Meaning |
-| --- | --- |
-| `NOT_FOUND` | No such action, or the caller is not in its audience |
-| `INVALID_INPUT` | No subject or body, an entry or placeholder that is not exactly one address, or more than 50 recipients |
-| `PLAN_RESTRICTED` | The workspace's plan does not allow this email |
-| `CREDITS_EXHAUSTED` | The workspace has no workflow credits left |
-| `RATE_LIMITED` | The app sent too often lately. Tell the person to try again later |
-| `PROVIDER_REJECTED` | The mail provider refused the email, for example from an unconfirmed sender |
-| `UNAVAILABLE` | Softr could not send it right now or could not be reached |
-| `TIMEOUT` | No answer in time. It may still have been sent, so never send it again by yourself |
-
-**Letting a mistyped address reach Softr.** An address the person typed (the reply-to of a contact form, a client's email) that is not one address is refused with `INVALID_INPUT`, which reads as a vague failure. Check its format in the validator and tell them which field is wrong.
-
-**Calling from client code.** `email` is server-only. Wrap the send in a `createServerFn` and call that from the form or the button.
-
-**Taking recipients from the request when they could be fixed.** A `to` the browser sends is a `to` any caller can change. Fix it in the declaration, or read it on the server from the record the email is about.
-
-**Placeholders in the call.** `{LOGGED_IN_USER:EMAIL}` is filled only in the declaration. In the call it is sent as written and fails.
-
-**Building a workflow for an email the app sends itself.** A "Run custom workflow" trigger plus a "Send email" step does the same at more cost to the user: a workflow to keep published. Use the email action; keep workflows for schedules and table events.