@softr/sdk 0.0.76 → 0.0.78-alpha.0

package/dist/action.d.ts

@@ -264,5 +264,38 @@ type CommentsDefinition<TId extends string> = {
  * const thread = await comments.list(orderComments, { recordId })
  */
 declare function defineComments<const TId extends string>(definition: CommentsDefinition<TId>): CommentsAction<TId>;
+type AiResource = {
+  type: "AI";
+  model: string;
+};
+type AiAction<TId extends string = string> = Action<AiResource> & {
+  id: TId;
+};
+type AiDefinition<TId extends string> = {
+  id: TId;
+  model: string;
+  permissions: ActionPermissions;
+};
+/**
+ * Declares an AI action: a model call run by Softr on its own provider keys and billed to the
+ * workspace's AI credits, so nothing has to be connected. `model` is the id of a model from
+ * Softr's AI catalog, chosen when the app is built: read the catalog with the `list_ai_models`
+ * tool and copy the id exactly. An id outside the catalog is refused when the action is saved.
+ *
+ * Every call spends the workspace's credits, so keep the audience to signed-in users unless a
+ * public page really needs the call.
+ *
+ * Pass the returned object to `ai.generate()` or `ai.stream()` at runtime.
+ *
+ * @example
+ * const summarizeDeal = defineAiAction({
+ *   id: "summarizeDeal",
+ *   model: "anthropic-claude-sonnet-4-6",
+ *   permissions: { userGroupTypes: ["LOGGED_IN_USERS"] },
+ * })
+ *
+ * const answer = await ai.generate(summarizeDeal, { system: "...", prompt: facts })
+ */
+declare function defineAiAction<const TId extends string>(definition: AiDefinition<TId>): AiAction<TId>;
 //#endregion
-export { ActionData, ActionPermissions, ActionRecord, ActionShape, CommentsAction, DatasourceAction, FieldTypeOf, IntegrationAction, ReadOf, ReadShape, SoftrDatasources, WorkflowAction, defineComments, defineIntegration, defineMutation, defineQuery, defineWorkflow };
+export { ActionData, ActionPermissions, ActionRecord, ActionShape, AiAction, CommentsAction, DatasourceAction, FieldTypeOf, IntegrationAction, ReadOf, ReadShape, SoftrDatasources, WorkflowAction, defineAiAction, defineComments, defineIntegration, defineMutation, defineQuery, defineWorkflow };

package/dist/action.js

@@ -81,6 +81,17 @@ function isDatasourceAction(value) {
 	const resource = candidate.resource;
 	return typeof candidate.id === "string" && typeof resource === "object" && resource !== null && resource.type === "DATASOURCE";
 }
+function defineAiAction(definition) {
+	const { id, model, permissions } = definition;
+	return {
+		id,
+		resource: {
+			type: "AI",
+			model
+		},
+		permissions
+	};
+}
 
 //#endregion
-export { defineComments, defineIntegration, defineMutation, defineQuery, defineWorkflow, isDatasourceAction };
+export { defineAiAction, defineComments, defineIntegration, defineMutation, defineQuery, defineWorkflow, isDatasourceAction };

package/dist/core/ai.d.ts

@@ -0,0 +1,62 @@
+import { AiAction } from "../action.js";
+
+//#region src/core/ai.d.ts
+/** A document or image the model reads, by the URL the app holds it under: one of its own uploads, as a rule. */
+interface AiFile {
+  /** An https URL Softr may fetch. */
+  url: string;
+  /** The file's type when the URL does not say, such as `application/pdf`. */
+  mimeType?: string;
+}
+interface AiGenerateInit {
+  /** What the model is and the rules it answers under. */
+  system?: string;
+  /** What it is asked, with the facts it is given. */
+  prompt: string;
+  /**
+   * A JSON schema the answer has to match. With it, the model is asked for JSON only and the
+   * answer comes back parsed in `json` as well as written in `text`.
+   */
+  schema?: Record<string, unknown>;
+  /** Documents and images the model reads alongside the prompt. */
+  files?: ReadonlyArray<AiFile>;
+  /** A cap on the answer's length, in tokens; Softr caps it further. */
+  maxOutputTokens?: number;
+  signal?: AbortSignal;
+}
+interface AiUsage {
+  inputTokens: number;
+  outputTokens: number;
+}
+interface AiAnswer {
+  /** The answer as the model wrote it. */
+  text: string;
+  /** The answer parsed as JSON when `schema` was given and the model kept to it; `null` otherwise. */
+  json: unknown;
+  usage: AiUsage;
+  /** The model that answered. */
+  model: string;
+}
+/**
+ * Thrown when the model call was refused or failed. `status` is the HTTP status Softr answered
+ * with; 402 means the workspace has no AI credits left.
+ */
+declare class AiError extends Error {
+  readonly status: number;
+  constructor(status: number, message: string);
+}
+/** Runs the action once and answers when the model is done. */
+declare function aiGenerate(action: AiAction, init: AiGenerateInit): Promise<AiAnswer>;
+/**
+ * Runs the action and answers while the model writes. The returned `Response` body is a stream of
+ * Server-Sent Events, one JSON object per `data:` line: `{ "text": "..." }` for each piece of the
+ * answer, then `{ "done": true, "usage": {...}, "model": "..." }`, or `{ "error": "..." }` in its
+ * place. Hand it to the browser as a `Response` with `Content-Type: text/event-stream`.
+ */
+declare function aiStream(action: AiAction, init: AiGenerateInit): Promise<Response>;
+declare const ai: {
+  generate: typeof aiGenerate;
+  stream: typeof aiStream;
+};
+//#endregion
+export { AiAnswer, AiError, AiFile, AiGenerateInit, AiUsage, ai };

package/dist/core/ai.js

@@ -0,0 +1,61 @@
+import { fetch } from "../fetch.js";
+import { readSessionToken } from "../auth/session.js";
+import { describeFailure, dsUrl, refererHeader } from "../datasource/record.js";
+
+//#region src/core/ai.ts
+/**
+* Thrown when the model call was refused or failed. `status` is the HTTP status Softr answered
+* with; 402 means the workspace has no AI credits left.
+*/
+var AiError = class extends Error {
+	status;
+	constructor(status, message) {
+		super(message);
+		this.name = "AiError";
+		this.status = status;
+	}
+};
+function body(init) {
+	return JSON.stringify({
+		system: init.system,
+		prompt: init.prompt,
+		schema: init.schema,
+		files: init.files,
+		maxOutputTokens: init.maxOutputTokens
+	});
+}
+async function post(action, path, init) {
+	if (init.signal?.aborted) throw init.signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
+	const res = await fetch(`${dsUrl(action.id)}/${path}`, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			"Authorization": `Bearer ${readSessionToken()}`,
+			...refererHeader()
+		},
+		body: body(init),
+		signal: init.signal
+	});
+	if (!res.ok) throw new AiError(res.status, `AI call "${action.id}" failed: ${await describeFailure(res)}`);
+	return res;
+}
+/** Runs the action once and answers when the model is done. */
+async function aiGenerate(action, init) {
+	return await (await post(action, "ai/generate", init)).json();
+}
+/**
+* Runs the action and answers while the model writes. The returned `Response` body is a stream of
+* Server-Sent Events, one JSON object per `data:` line: `{ "text": "..." }` for each piece of the
+* answer, then `{ "done": true, "usage": {...}, "model": "..." }`, or `{ "error": "..." }` in its
+* place. Hand it to the browser as a `Response` with `Content-Type: text/event-stream`.
+*/
+async function aiStream(action, init) {
+	return post(action, "ai/generate/stream", init);
+}
+const ai = {
+	generate: aiGenerate,
+	stream: aiStream
+};
+
+//#endregion
+export { AiError, ai };

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

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

package/dist/formatting.d.ts

@@ -1,4 +1,4 @@
-import * as react0 from "react";
+import * as react3 from "react";
 import { ReactNode } from "react";
 import { z } from "zod";
 
@@ -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;
-}): react0.FunctionComponentElement<react0.ProviderProps<Scope>>;
+}): react3.FunctionComponentElement<react3.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;
-}): react0.FunctionComponentElement<react0.FragmentProps>;
+}): react3.FunctionComponentElement<react3.FragmentProps>;
 //#endregion
 export { DateOptions, DateParts, DateSeparator, DateValue, FixedDateFormat, FormattedDate, Formatting, FormattingScope, WeekDay, formatDate, formatDateTime, formatNumber, useFormatting };

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 import { SoftrUserGroupId, SoftrUserGroups, User } from "./auth/user.js";
-import { ActionPermissions, SoftrDatasources, defineComments, defineIntegration, defineMutation, defineQuery, defineWorkflow } from "./action.js";
+import { ActionPermissions, SoftrDatasources, defineAiAction, defineComments, defineIntegration, defineMutation, defineQuery, defineWorkflow } from "./action.js";
 import { FileAttachment } from "./core/file-upload.js";
 import { FileItem, useFileUpload } from "./core/use-file-upload.js";
 import { CommentAttachmentInput, CommentMention, CommentThread, CommentView } from "./comments/comments.js";
+import { AiAnswer, AiFile, AiGenerateInit, AiUsage } from "./core/ai.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";
@@ -18,4 +19,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, Audience, type AuthOptions, type AuthSettings, AuthSettingsProvider, type CommentAttachmentInput, type CommentMention, type CommentThread, type CommentView, 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 User, type WeekDay, assertRouteAccess, checkAccess, defineComments, 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 AiUsage, Audience, type AuthOptions, type AuthSettings, AuthSettingsProvider, type CommentAttachmentInput, type CommentMention, type CommentThread, type CommentView, 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 User, type WeekDay, assertRouteAccess, checkAccess, defineAiAction, defineComments, 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,5 +1,5 @@
 import { useFileUpload } from "./core/use-file-upload.js";
-import { defineComments, defineIntegration, defineMutation, defineQuery, defineWorkflow } from "./action.js";
+import { defineAiAction, defineComments, defineIntegration, defineMutation, defineQuery, defineWorkflow } from "./action.js";
 import { checkAccess, defineVisibility, isAuthorized } from "./route/visibility.js";
 import { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError } from "./route/route.js";
 import { definePage, pageHead } from "./route/page.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, defineComments, 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, defineComments, 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_start5 from "@tanstack/react-start";
+import * as _tanstack_react_start0 from "@tanstack/react-start";
 
 //#region src/mcp.d.ts
 
@@ -31,6 +31,6 @@ type SoftrMcpOptions = {
  *   ],
  * }))
  */
-declare function softrMcpMiddleware(options?: SoftrMcpOptions): _tanstack_react_start5.RequestMiddlewareAfterServer<{}, undefined, undefined>;
+declare function softrMcpMiddleware(options?: SoftrMcpOptions): _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>;
 //#endregion
 export { softrMcpMiddleware };

package/dist/package.js

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

package/dist/pwa.d.ts

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

package/dist/server.d.ts

@@ -1,9 +1,10 @@
 import { upload } from "./core/file-upload.js";
 import { comments } from "./comments/comments.js";
+import { AiError, ai } from "./core/ai.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 { type FieldChoice, type RecordOption, type RecordOptions, auth, comments, ds, integration, upload, workflow };
+export { AiError, type FieldChoice, type RecordOption, type RecordOptions, ai, auth, comments, ds, integration, upload, workflow };

package/dist/server.js

@@ -3,7 +3,8 @@ import { ds } from "./datasource/datasource.js";
 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 { comments } from "./comments/comments.js";
 import "@tanstack/react-start/server-only";
 
-export { auth, comments, ds, integration, upload, workflow };
+export { AiError, ai, auth, comments, ds, integration, upload, workflow };

package/package.json

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

package/skills/softr-sdk/SKILL.md

@@ -1,18 +1,14 @@
 ---
 name: softr-sdk
 description: >-
-  Entry point for @softr/sdk, the layer a Softr app uses to reach Softr: the
-  four entrypoints (@softr/sdk, /server, /client, /vite) and the client-server
-  boundary between them, softrAuthMiddleware, getSoftrContext,
-  initialSoftrContext, SoftrContext, and which sub-skill to load for route
-  visibility, the current user, reading records, charts and metrics, writing
-  records, auth, or showing dates and numbers. Load this when unsure which
-  sub-skill applies, or when touching the wiring; each sub-skill stands alone
-  for its own task.
+  Entry point for @softr/sdk: its four entrypoints (@softr/sdk, /server,
+  /client, /vite) and their client-server boundary, softrAuthMiddleware and the
+  Softr context, and which sub-skill covers each task. Load it when unsure which
+  sub-skill applies, or when touching the wiring.
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.76
+  library_version: 0.0.77
 ---
 
 # Softr SDK core
@@ -22,6 +18,7 @@ metadata:
 > **CRITICAL**: The SDK is split across four entrypoints and the split is enforced. `ds` and `auth` exist only on `@softr/sdk/server` and only run inside a `createServerFn` handler. Importing them anywhere else fails the build.
 > **CRITICAL**: Every route file must declare its audience with `defineVisibility` and guard itself with that rule in `beforeLoad`. There is no default and nothing is inherited from a sibling.
 > **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**: `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.
 
 Each sub-skill stands alone for its task and repeats the boundary above, so most work needs **one** sub-skill and not this file. Load this one when you are unsure which sub-skill applies, or when the wiring below is what you are touching. Add a second sub-skill only when the work genuinely crosses that boundary: a page that lists records behind a group restriction needs `record-queries` plus `routes-and-visibility`.
@@ -30,8 +27,8 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 
 | Import | Runs | Holds |
 | --- | --- | --- |
-| `@softr/sdk` | Both | `defineQuery`, `defineMutation`, `defineComments`, `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`, `comments` |
+| `@softr/sdk` | Both | `defineQuery`, `defineMutation`, `defineComments`, `defineAiAction`, `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`, `comments`, `ai` |
 | `@softr/sdk/client` | Browser only | `useFileUpload`, `useCommentComposer` |
 | `@softr/sdk/vite` | Build | `softr()`, already in `vite.config.ts` |
 
@@ -47,7 +44,8 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 | Create, update or delete a record | [record-mutations/SKILL.md](./record-mutations/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) |
-| Call a connected third-party API (Slack, Stripe, Gmail, …) | [integrations/SKILL.md](./integrations/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, …), 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) |
@@ -80,9 +78,15 @@ Triggering a Softr workflow from a button or form?
 Wiring a login, signup, or sign-out?
   load softr-sdk/auth
 
+Asking an AI model for anything: a summary, fields out of a document, a classification, a draft, a chat?
+  load softr-sdk/ai — Softr runs the model on its own keys, nothing to connect; pick the model from ai_list_models
+
 Calling a connected third-party API (Slack, Stripe, Gmail, Google Calendar, …)?
   load softr-sdk/integrations
 
+Running a model on the user's OWN provider account, because they asked for that?
+  load softr-sdk/integrations: its "Calling an AI model" section
+
 Opening the app to an AI assistant over MCP?
   load softr-sdk/mcp
 

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

@@ -0,0 +1,138 @@
+---
+name: ai
+description: >-
+  Run an AI model from the app on Softr's own keys, billed to the workspace's
+  AI credits, with nothing to connect: defineAiAction from @softr/sdk declares
+  the action with the catalog model it runs on and its permissions;
+  ai.generate from @softr/sdk/server runs it with a system text, a prompt, an
+  optional JSON schema for an answer that is data, and optional files;
+  ai.stream runs it for an answer the user watches being written. Load this
+  for a summary, an extraction, a classification, a draft, or a chat the app
+  asks a model for.
+metadata:
+  type: sub-skill
+  library: softr-sdk
+  library_version: 0.0.78-alpha.0
+---
+
+**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.
+
+# AI
+
+An app asks a model through an AI action. Softr runs the call on its own provider keys and bills the workspace's AI credits, so there is no key to ask the user for and nothing to connect. This is the path for every AI feature of the app's own — a summary of a record, fields extracted from a document, a classification, a draft, a chat — unless the user explicitly asked to use their own provider account, which is the `integrations` sub-skill's path.
+
+## Choose the model first
+
+The model is chosen when the app is built and frozen in its code. Before you declare an action, read Softr's catalog with the `ai_list_models` tool. Each entry carries the `id` the action names, the `provider`, and `bestFor`, what to pick it for:
+
+- a summary, a briefing, a draft, reasoning over many facts: the strongest model listed;
+- an extraction or a classification over one document: the cheapest model that reads that document's kind — a PDF needs a model whose `bestFor` says so.
+
+Copy the `id` exactly. An id outside the catalog is refused when the action is saved, and a model spelled from memory never is in it.
+
+## Declare the action
+
+```ts
+const summarizeDeal = defineAiAction({
+  id: 'summarizeDeal',
+  model: 'anthropic-claude-sonnet-4-6',
+  permissions: { userGroupTypes: ['LOGGED_IN_USERS'] },
+})
+```
+
+Write the object inline in `defineAiAction`. Passing it through a variable widens the types.
+
+**Every call spends the workspace's credits.** Keep the audience to `['LOGGED_IN_USERS']`, narrowed with `customGroups` where the feature is for some users only. Open an AI action to visitors only when a public page really needs it, and say so to the user: anyone on the internet can then bill the workspace.
+
+Declare one action per feature — the summary and the extraction are two actions, each with its own `id`, its own model and its own audience.
+
+## Core pattern: an answer the server reads
+
+`ai.generate(action, init)` runs the action and answers when the model is done. `init` takes:
+
+- `prompt` — what the model is asked, with the facts it is given. Required.
+- `system` — what the model is and the rules it answers under.
+- `schema` — a JSON schema the answer has to match. With it the model is asked for JSON only, and the answer comes back parsed in `json` as well as written in `text`.
+- `files` — documents and images the model reads, each as `{ url, mimeType? }`: an `https` URL Softr may fetch, one of the app's own uploads as a rule.
+- `maxOutputTokens` — a cap on the answer's length. Softr caps it further.
+
+The answer is `{ text, json, usage, model }`: `text` as the model wrote it, `json` parsed when a schema was given and the model kept to it, `null` otherwise.
+
+```ts
+const summarize = createServerFn({ method: 'POST' })
+  .validator(z.object({ recordId: z.string() }))
+  .handler(async ({ data }) => {
+    const deal = await ds.get(dealQuery, { id: data.recordId })
+    if (deal === null) throw new Error('This deal no longer exists')
+    const facts = [`Name: ${fieldText(deal.fields.name)}`, `Stage: ${fieldText(deal.fields.stage)}`].join('\n')
+    const answer = await ai.generate(summarizeDeal, {
+      system: 'You brief a sales team. Use only the facts given; say what is missing rather than invent it.',
+      prompt: facts,
+      maxOutputTokens: 800,
+    })
+    return answer.text
+  })
+```
+
+## 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.
+
+```ts
+const InvoiceFields = z.object({ vendor: z.string(), total: z.number(), issuedOn: z.string() })
+
+const extractInvoice = createServerFn({ method: 'POST' })
+  .validator(z.object({ fileUrl: z.string().url() }))
+  .handler(async ({ data }) => {
+    const answer = await ai.generate(readInvoice, {
+      system: 'Read the invoice and answer with its fields. Dates as YYYY-MM-DD, amounts as numbers.',
+      prompt: 'Extract the vendor, the total and the issue date.',
+      schema: {
+        type: 'object',
+        properties: { vendor: { type: 'string' }, total: { type: 'number' }, issuedOn: { type: 'string' } },
+        required: ['vendor', 'total', 'issuedOn'],
+      },
+      files: [{ url: data.fileUrl, mimeType: 'application/pdf' }],
+    })
+    const parsed = InvoiceFields.safeParse(answer.json)
+    if (!parsed.success) throw new Error('The invoice could not be read. Try a clearer scan.')
+    return ds.create(createInvoice, { data: parsed.data })
+  })
+```
+
+The file's URL comes from the app's own upload: load the Softr SDK `file-uploads` guidance for that half. `readInvoice` names a model whose `bestFor` reads PDF documents.
+
+## Streaming: an answer the user watches being written
+
+A chat, an assistant, a long draft shown as it is typed — never buffer these: the user would watch a blank panel until the last token. `ai.stream(action, init)` takes the same `init` and answers with a `Response` whose body is a stream of Server-Sent Events. Hand it to the browser from the server function, unchanged:
+
+```ts
+const draftReply = createServerFn({ method: 'POST' })
+  .validator(z.object({ prompt: z.string() }))
+  .handler(async ({ data }) => {
+    const res = await ai.stream(draftAction, { system: 'You write replies for a support team.', prompt: data.prompt })
+    return new Response(res.body, { headers: { 'Content-Type': 'text/event-stream' } })
+  })
+```
+
+Each event is one JSON object on a `data:` line:
+
+- `{ "text": "..." }` — the next piece of the answer; append it.
+- `{ "done": true, "usage": { "inputTokens", "outputTokens" }, "model": "..." }` — the answer is complete.
+- `{ "error": "..." }` — in place of `done`, when the call ended before its answer: show the message.
+
+On the client, call the server function's URL with `fetch`, read `response.body` with a stream reader, split on blank lines, and parse the JSON after `data:`.
+
+## Failure modes
+
+**Calling from client code.** `ai` is server-only. Importing it into a component or calling it outside a `createServerFn` handler fails the build or has no request context to act on.
+
+**Spelling a model id.** `model` is copied from `ai_list_models`, never written from memory. An id outside the catalog fails the save of the action, so the app cannot be published with it.
+
+**No credits left.** `ai.generate` and `ai.stream` throw an `AiError` whose `status` is `402` when the workspace has no AI credits. Show its message to the user; the workspace owner tops the credits up in Softr. Any other refusal carries its status and reason the same way.
+
+**Trusting `json` without checking it.** A model may stray from the schema; `json` is then `null`, or a shape close to the one asked. Validate it with `zod` before writing it to a record, and keep `text` as the fallback the user can read.
+
+**Reading a streamed body with `res.json()`.** The body of `ai.stream` is an event stream, not one JSON document. Return `res.body` in a `Response` or read it with a stream reader.
+
+**Asking for the user's API key.** An AI feature of the app's own needs none. Only when the user asks to run the app on their own provider account does the call go through a connected integration — load the `integrations` sub-skill then.

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

@@ -1,24 +1,15 @@
 ---
 name: auth
 description: >-
-  Sign a Softr visitor in, out or up from a server function: auth.signIn,
-  signInWithCode, signInWithGoogle, signInWithMagicLink, signUp, confirmSignUp
-  and signOut from @softr/sdk/server, the authenticator-app calls that finish a
-  sign-in (verifyAuthenticator, startAuthenticatorSetup,
-  confirmAuthenticatorSetup, skipAuthenticatorSetup) and the ones that change an
-  authenticator from a settings page (sendAuthenticatorResetCode,
-  resetAuthenticator, removeAuthenticator), updateProfile for the visitor's own
-  name and photo, the emailed password links (requestPasswordReset,
-  checkPasswordLink, setPasswordWithLink), and getAuthSettings,
-  AuthSettingsProvider and useAuthSettings for which sign-in and sign-up methods
-  the app has enabled. Covers the Result shape they answer with and its error
-  codes (invalidCredentials, emailTaken, notAuthenticated, notAnImage and the
-  rest), the two-step sign-up, why a successful sign-in does not always mean the
-  visitor is signed in, and toReturnPath for where to land after signing in.
+  Sign a visitor in, out or up from a server function with auth from
+  @softr/sdk/server: password, code, Google and magic link, sign-up and its
+  confirmation, the authenticator-app steps, password reset links,
+  updateProfile, and getAuthSettings and useAuthSettings for the methods the app
+  enables. Covers the Result shape, its error codes, and toReturnPath.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.76
+  library_version: 0.0.77
 ---
 
 **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

@@ -1,18 +1,15 @@
 ---
 name: charts-and-metrics
 description: >-
-  Aggregate Softr datasource records inside a server function: ds.chart with
-  groupBy, metrics, where and orderBy for chart rows, ds.metric for a single
-  headline number, date bucket intervals, which aggregations each kind of field
-  offers, the two-group-column ceiling, and distinct values for filter controls.
-  Use when drawing a chart, a stat tile or any counted, summed or averaged
-  number, when filling a dropdown from a real column, or when a chart comes back
-  scrambled or with the wrong rows. Aggregation only: fetching individual
-  records is record-queries, and changing them is record-mutations.
+  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.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.76
+  library_version: 0.0.77
 ---
 
 **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.

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

@@ -1,17 +1,14 @@
 ---
 name: comments
 description: >-
-  Comment threads on records: defineComments from @softr/sdk declares which
-  datasource has comments; comments.list, create, update, delete, react,
-  subscription, setSubscription and searchMentions from @softr/sdk/server read
-  and write one record's thread inside a server function; useCommentComposer
-  and useFileUpload from @softr/sdk/client keep a textarea's text, its
-  @mentions and its attachments in step. Bodies come back as sanitised
-  bodyHtml. A null thread means render nothing.
+  Comment threads on records: defineComments, the comments calls from
+  @softr/sdk/server to list, write, react to and mention in one record's thread,
+  and useCommentComposer and useFileUpload from @softr/sdk/client for the
+  composer. Bodies come back as sanitised bodyHtml.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.76
+  library_version: 0.0.77
 ---
 
 **Boundary.** `comments` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler. Importing it into a component fails the build. `useCommentComposer` lives on `@softr/sdk/client` and runs in components. `defineComments` comes from `@softr/sdk` and can be imported anywhere.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.76
+  library_version: 0.0.77
 ---
 
 # The current user

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

@@ -1,16 +1,13 @@
 ---
 name: file-uploads
 description: >-
-  Upload files from a form or edit view: useFileUpload(action) from @softr/sdk
-  does everything — XHR upload with real progress, per-upload cancel, and
-  isUploading to block form submission. No route registration needed; the SDK
-  ships its own server function. For server-side uploads or plain forms, use
-  upload(actionId, file) from @softr/sdk/server. For edit forms pass
-  initialAttachments to pre-load existing attachments.
+  Upload files from a form or edit view: useFileUpload from @softr/sdk, with
+  progress, cancel and isUploading to hold the submit, and initialAttachments
+  for an edit form; upload from @softr/sdk/server for a server-side upload.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.76
+  library_version: 0.0.77
 ---
 
 **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

@@ -2,15 +2,13 @@
 name: formatting
 description: >-
   Show dates, times and numbers in the app's format without hydration
-  mismatches: FormattedDate in JSX, useFormatting with formatDate,
-  formatDateTime and formatNumber in code, FormattingScope and the timeZone
-  option for a zone or locale the user names, parts for a partial date, and why
-  toLocaleDateString, toLocaleString and Intl formatters with the runtime's
-  defaults must never run in render.
+  mismatches: FormattedDate, useFormatting with formatDate, formatDateTime and
+  formatNumber, FormattingScope and timeZone, and why toLocaleDateString and
+  Intl defaults must never run in render.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.76
+  library_version: 0.0.77
 ---
 
 # Dates, times and numbers

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

@@ -1,16 +1,13 @@
 ---
 name: integrations
 description: >-
-  Call a third-party service connected to the app as an integration:
-  defineIntegration from @softr/sdk declares the action with its integrationId,
-  the one HTTP method and endpoint url it allows, and permissions;
-  integration.createFetcher from @softr/sdk/server binds it and returns a
-  fetcher function you call with optional params, query, headers, and body.
-  Check res.ok before res.json().
+  Call a third-party service connected as an integration: defineIntegration from
+  @softr/sdk declares the one method and endpoint it allows, and
+  integration.createFetcher from @softr/sdk/server calls it.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.76
+  library_version: 0.0.77
 ---
 
 **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.
@@ -129,9 +126,9 @@ Do not add an `Authorization` key to `headers` — Softr injects the integration
 
 ## Calling an AI model
 
-A button on one record that hands its fields to the model and shows the answer is the `ai-action` pattern:
-it carries this call and the model id, so write the call by hand only for another shape — a batch, a chat,
-a field the model fills on create. An AI integration is called like any other. For `ANTHROPIC_AI`, the action is `POST` on
+**This is the path for the user's own provider account only.** An AI feature of the app's own — a summary, an extraction, a chat — runs on Softr's keys through an AI action, with nothing to connect and no key to ask for: load the `ai` sub-skill for it. Call a model through an integration only when the user asked to use their own OpenAI, Anthropic or Gemini account, and had it connected.
+
+An AI integration is called like any other. For `ANTHROPIC_AI`, the action is `POST` on
 `https://api.anthropic.com/v1/messages`, the request carries the `anthropic-version` header and a body of
 `model`, `max_tokens`, `system` and `messages`, and the answer's text is in `content[].text`:
 

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.76
+  library_version: 0.0.77
 ---
 
 **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.76
+  library_version: 0.0.77
 ---
 
 # Installing the app

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

@@ -1,17 +1,14 @@
 ---
 name: record-mutations
 description: >-
-  Create, update and delete records in a Softr datasource with defineMutation,
-  ds.create, ds.update and ds.delete: one declaration per operation, the data
-  payload keyed by your own field names, what each field type accepts on a
-  write, and the record each call returns. Use when submitting a form, saving an
-  edit or deleting a record, or when a write throws, writes the wrong field or
-  silently changes nothing. Writes only: fetching records is record-queries, and
-  aggregating them is charts-and-metrics.
+  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.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.76
+  library_version: 0.0.77
 ---
 
 **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.

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

@@ -1,19 +1,15 @@
 ---
 name: record-queries
 description: >-
-  Fetch records from a Softr datasource with defineQuery, ds.list and ds.get:
-  the where and orderBy callbacks, field names of your own choosing, the
-  20-record default and 100-record cap, nextOffset pagination, and scoping a
-  read to the signed-in visitor. Use when putting datasource records on a page,
-  in a table, a list or a detail view, when filtering or sorting them, when
-  filling a filter or form dropdown with all options from a linked table, or
-  when a read comes back empty, unsorted or missing a field. Reads only:
-  creating, updating and deleting records is record-mutations, and aggregating
-  them into totals or chart rows is charts-and-metrics.
+  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.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.76
+  library_version: 0.0.77
 ---
 
 **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.

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

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

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

@@ -1,19 +1,14 @@
 ---
 name: routes-and-visibility
 description: >-
-  Add a route file to a Softr app and declare who may see it: defineVisibility
-  with a userGroupTypes set naming LOGGED_IN_USERS and/or NON_LOGGED_IN_USERS,
-  customGroups, and the ways to apply a rule: guardRoute and assertRouteAccess
-  in a route, isAuthorized and checkAccess anywhere. Covers per-reason
-  overrides, the redirect and throw strategies, rendering an access error with
-  isAccessError, isUnauthenticatedError, isForbiddenError and
-  isAlreadyAuthenticatedError, guarding a layout, and the lint rule that
-  requires a declaration alongside the rules that reject a duplicate, computed
-  or root-level one.
+  Add a route file and declare who may see it: defineVisibility with
+  LOGGED_IN_USERS, NON_LOGGED_IN_USERS and customGroups, guardRoute and
+  assertRouteAccess in a route, isAuthorized and checkAccess anywhere, rendering
+  an access error, and the lint rule that requires the declaration.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.76
+  library_version: 0.0.77
 ---
 
 **Boundary.** `defineVisibility`, the access functions and the error predicates come from `@softr/sdk` and work anywhere.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.76
+  library_version: 0.0.77
 ---
 
 **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.