@softr/sdk 0.0.50-alpha.0 → 0.0.50-alpha.1

package/dist/auth/user.d.ts

@@ -3,20 +3,13 @@ import { z } from "zod";
 //#region src/auth/user.d.ts
 
 /**
- * Declare this interface in your app to narrow every group id the SDK takes and
- * returns. Without a declaration, a group id is a plain `string`.
- *
- * @example
- * declare module "@softr/sdk" {
- *   interface SoftrUserGroups {
- *     ids:
- *       | "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
- *       | "f9e8d7c6-5b4a-4938-8271-605f4e3d2c1b"
- *   }
- * }
+ * The app's group ids. The app's generated types declare them, the predefined
+ * groups included. Every group id the SDK takes and returns narrows to them.
+ * Never declare it by hand: a second declaration does not merge with the
+ * generated one.
  */
 interface SoftrUserGroups {}
-/** A Softr user group id, narrowed to your own ids if you declare {@link SoftrUserGroups}. */
+/** A Softr user group id, narrowed to the app's own ids by {@link SoftrUserGroups}. */
 type SoftrUserGroupId = SoftrUserGroups extends {
   ids: infer Id extends string;
 } ? Id : string;

package/dist/cli.js

@@ -2,7 +2,9 @@
 import { version } from "./package.js";
 import { requireDefined } from "./assertions.js";
 import { fetchSoftrEnvInput, metadataSourceFromEnv } from "./codegen/fetch-metadata.js";
+import { renderUserGroupsDoc } from "./codegen/user-groups.js";
 import { renderSoftrEnv } from "./codegen/softr-env.js";
+import { writeIfChanged } from "./codegen/write-if-changed.js";
 import { writeDatasourceDocs } from "./codegen/write-datasource-docs.js";
 import { writeFileSync } from "node:fs";
 import path from "node:path";
@@ -11,26 +13,44 @@ import { parseArgs } from "node:util";
 //#region src/cli.ts
 const OUTPUT = "softr-env.d.ts";
 const DOCS_DIR = "docs/datasources";
+const USER_GROUPS_DOC = "docs/user-groups.md";
 async function generate({ json }) {
 	if (json) console.info = console.error;
 	const input = await fetchSoftrEnvInput(metadataSourceFromEnv());
 	writeFileSync(path.resolve(process.cwd(), OUTPUT), renderSoftrEnv(input, version), "utf8");
-	const docFiles = writeDatasourceDocs(input.datasources, path.resolve(process.cwd(), DOCS_DIR));
-	const report = {
+	const report = writeDocs(input);
+	if (json) {
+		process.stdout.write(`${JSON.stringify(report)}\n`);
+		return;
+	}
+	printReport(report);
+}
+function writeDocs(input) {
+	const datasourceDocs = writeDatasourceDocs(input.datasources, path.resolve(process.cwd(), DOCS_DIR));
+	return {
 		types: OUTPUT,
-		docsIndex: `${DOCS_DIR}/README.md`,
+		docs: [{
+			subject: "datasources",
+			path: `${DOCS_DIR}/README.md`,
+			changed: datasourceDocs.changed
+		}, {
+			subject: "user groups",
+			path: USER_GROUPS_DOC,
+			changed: writeIfChanged(path.resolve(process.cwd(), USER_GROUPS_DOC), renderUserGroupsDoc(input.userGroups))
+		}],
 		datasources: input.datasources.map(({ id, name }) => ({
 			id,
 			name,
-			doc: `${DOCS_DIR}/${requireDefined(docFiles.get(id))}`
+			doc: `${DOCS_DIR}/${requireDefined(datasourceDocs.fileNames.get(id))}`
 		}))
 	};
-	if (json) {
-		process.stdout.write(`${JSON.stringify(report)}\n`);
-		return;
-	}
+}
+function printReport(report) {
 	console.log(`[softr] wrote ${report.types}`);
-	console.log(`[softr] wrote ${report.docsIndex}`);
+	for (const doc of report.docs) {
+		const state = doc.changed ? "updated" : "unchanged";
+		console.log(`[softr] ${state} ${doc.path} for ${doc.subject}`);
+	}
 	for (const datasource of report.datasources) console.log(`[softr] wrote ${datasource.doc} for ${datasource.name} (${datasource.id})`);
 }
 const { positionals, values } = parseArgs({

package/dist/codegen/fetch-metadata.js

@@ -19,7 +19,7 @@ function metadataSourceFromEnv(env = process.env) {
 }
 async function fetchSoftrEnvInput(source) {
 	const { studioApiUrl, datasourceApiUrl, applicationId, token } = source;
-	const registered = await apiFetch(`${studioApiUrl}/v1/applications/${applicationId}/datasources`, token);
+	const [registered, userGroups] = await Promise.all([apiFetch(`${studioApiUrl}/v1/applications/${applicationId}/datasources`, token), apiFetch(`${studioApiUrl}/v1/applications/${applicationId}/access-control/user-groups`, token)]);
 	return {
 		datasources: await Promise.all(registered.map(async ({ name, datasource }) => {
 			return {
@@ -28,7 +28,7 @@ async function fetchSoftrEnvInput(source) {
 				name
 			};
 		})),
-		userGroupIds: null
+		userGroups
 	};
 }
 async function apiFetch(url, token) {

package/dist/codegen/softr-env.js

@@ -13,7 +13,8 @@ function renderSoftrEnv(input, sdkVersion) {
 		"",
 		"declare module \"@softr/sdk\" {",
 		indent(interfaces),
-		...input.userGroupIds === null ? [] : ["", indent(renderUserGroups(input.userGroupIds))],
+		"",
+		indent(renderUserGroups(input.userGroups)),
 		"}",
 		""
 	].join("\n");
@@ -33,10 +34,11 @@ function header(sdkVersion) {
  * THIS FILE IS AUTO GENERATED, DO NOT EDIT THIS MANUALLY
  *
  * This file exists for type checking. See docs/datasources/ for field reference
- * and guide how to use it.
+ * and guide how to use it, and docs/user-groups.md for the app's user groups.
  *
  * Generated by @softr/sdk@${sdkVersion}
  * This file is regenerated automatically when a change is made to the datasource
+ * or to the app's user groups
  */
 
 export {};`;

package/dist/codegen/user-groups.js

@@ -1,11 +1,32 @@
 //#region src/codegen/user-groups.ts
-function renderUserGroups(ids) {
+const DOC_NOTE = "> This document is generated automatically when a change is made in the app's user groups.";
+function renderUserGroups(groups) {
 	return [
 		"interface SoftrUserGroups {",
-		`  ids: ${ids.length === 0 ? "never" : ids.map((id) => JSON.stringify(id)).join(" | ")};`,
+		`  ids: ${groups.length === 0 ? "never" : groups.map(({ id }) => JSON.stringify(id)).join(" | ")};`,
 		"}"
 	].join("\n");
 }
+function renderUserGroupsDoc(groups) {
+	const heading = [
+		"# User groups",
+		"",
+		DOC_NOTE,
+		""
+	];
+	if (groups.length === 0) return [
+		...heading,
+		"This app has no user groups.",
+		""
+	].join("\n");
+	return [
+		...heading,
+		"User groups available in this app:",
+		"",
+		...groups.map(({ id, name, type }) => `- ${name} (${id}), ${type.toLowerCase()}`),
+		""
+	].join("\n");
+}
 
 //#endregion
-export { renderUserGroups };
+export { renderUserGroups, renderUserGroupsDoc };

package/dist/codegen/write-datasource-docs.js

@@ -1,24 +1,26 @@
 import { requireDefined } from "../assertions.js";
 import { renderDatasourceDoc, renderDatasourceIndex } from "./datasource-docs.js";
 import { docFileNames } from "./doc-file-names.js";
-import { mkdirSync, writeFileSync } from "node:fs";
+import { writeIfChanged } from "./write-if-changed.js";
 import path from "node:path";
 
 //#region src/codegen/write-datasource-docs.ts
 /**
 * Writes the index and one file per datasource, and touches nothing else in
 * `docsDir`: the caller resolves it against `process.cwd()`, which can be any
-* directory a developer ran the bin from.
+* directory a developer ran the bin from. `changed` is true when any file it
+* wrote now reads differently.
 */
 function writeDatasourceDocs(datasources, docsDir) {
 	const context = {
 		datasources: new Map(datasources.map((datasource) => [datasource.id, datasource])),
 		fileNames: docFileNames(datasources)
 	};
-	mkdirSync(docsDir, { recursive: true });
-	writeFileSync(path.join(docsDir, "README.md"), renderDatasourceIndex(datasources, context), "utf8");
-	for (const datasource of datasources) writeFileSync(path.join(docsDir, requireDefined(context.fileNames.get(datasource.id))), renderDatasourceDoc(datasource, context), "utf8");
-	return context.fileNames;
+	const writes = [writeIfChanged(path.join(docsDir, "README.md"), renderDatasourceIndex(datasources, context)), ...datasources.map((datasource) => writeIfChanged(path.join(docsDir, requireDefined(context.fileNames.get(datasource.id))), renderDatasourceDoc(datasource, context)))];
+	return {
+		fileNames: context.fileNames,
+		changed: writes.includes(true)
+	};
 }
 
 //#endregion

package/dist/codegen/write-if-changed.js

@@ -0,0 +1,22 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+//#region src/codegen/write-if-changed.ts
+/** Returns whether it had to write. */
+function writeIfChanged(file, content) {
+	if (readOrNull(file) === content) return false;
+	mkdirSync(path.dirname(file), { recursive: true });
+	writeFileSync(file, content, "utf8");
+	return true;
+}
+function readOrNull(file) {
+	try {
+		return readFileSync(file, "utf8");
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return null;
+		throw error;
+	}
+}
+
+//#endregion
+export { writeIfChanged };

package/dist/default-error-overlay.js

@@ -1,23 +1,10 @@
-import { useEffect, useRef, useState, useSyncExternalStore } from "react";
-import { useRouter } from "@tanstack/react-router";
+import { useRef, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 
 //#region src/default-error-overlay.tsx
-function subscribeToAgentTurn(listener) {
-	const observer = new MutationObserver(listener);
-	observer.observe(document.documentElement, {
-		attributes: true,
-		attributeFilter: ["data-agent-turn"]
-	});
-	return () => observer.disconnect();
-}
-function isAgentTurnRunning() {
-	return document.documentElement.dataset.agentTurn === "running";
-}
 function DefaultErrorOverlay({ error, reset }) {
 	if (process.env.NODE_ENV === "production") return /* @__PURE__ */ jsx("div", {
 		style: s.overlay,
-		"data-softr-error-overlay": "error",
 		children: /* @__PURE__ */ jsxs("div", {
 			style: s.card,
 			children: [
@@ -39,33 +26,8 @@ function DefaultErrorOverlay({ error, reset }) {
 	});
 }
 function DevView({ error, reset }) {
-	const running = useSyncExternalStore(subscribeToAgentTurn, isAgentTurnRunning, () => false);
-	const [caughtDuringTurn, setCaughtDuringTurn] = useState(running);
-	const router = useRouter();
-	useEffect(() => {
-		if (running) {
-			setCaughtDuringTurn(true);
-			return;
-		}
-		if (!caughtDuringTurn) return;
-		const showError = () => setCaughtDuringTurn(false);
-		const timer = setTimeout(() => {
-			router.invalidate().then(() => {
-				reset?.();
-				showError();
-			}, showError);
-		}, 1e3);
-		return () => clearTimeout(timer);
-	}, [
-		running,
-		caughtDuringTurn,
-		reset,
-		router
-	]);
-	if (running || caughtDuringTurn) return /* @__PURE__ */ jsx(UpdatingView, {});
 	return /* @__PURE__ */ jsx("div", {
 		style: s.overlay,
-		"data-softr-error-overlay": "error",
 		children: /* @__PURE__ */ jsxs("div", {
 			style: s.card,
 			children: [
@@ -94,39 +56,6 @@ function DevView({ error, reset }) {
 		})
 	});
 }
-function UpdatingView() {
-	return /* @__PURE__ */ jsx("div", {
-		style: s.overlay,
-		"data-softr-error-overlay": "updating",
-		children: /* @__PURE__ */ jsxs("div", {
-			style: s.card,
-			children: [/* @__PURE__ */ jsx("div", {
-				style: s.pending,
-				children: /* @__PURE__ */ jsxs("svg", {
-					style: icon.md,
-					viewBox: "0 0 24 24",
-					fill: "none",
-					stroke: "currentColor",
-					strokeWidth: "2",
-					strokeLinecap: "round",
-					strokeLinejoin: "round",
-					children: [
-						/* @__PURE__ */ jsx("path", { d: "M3 12a9 9 0 0 1 9-9 9.75 9.75 0 0 1 6.74 2.74L21 8" }),
-						/* @__PURE__ */ jsx("path", { d: "M21 3v5h-5" }),
-						/* @__PURE__ */ jsx("path", { d: "M21 12a9 9 0 0 1-9 9 9.75 9.75 0 0 1-6.74-2.74L3 16" }),
-						/* @__PURE__ */ jsx("path", { d: "M8 16H3v5" })
-					]
-				})
-			}), /* @__PURE__ */ jsxs("div", { children: [/* @__PURE__ */ jsx("h1", {
-				style: s.heading,
-				children: "Updating the app…"
-			}), /* @__PURE__ */ jsx("p", {
-				style: s.body,
-				children: "The agent is still working on this change. The preview will recover once it is complete."
-			})] })]
-		})
-	});
-}
 function cleanStack(stack) {
 	return stack.split("\n").slice(1).filter((line) => line.trim().startsWith("at ") && !line.includes("/node_modules/")).map((line) => line.replace(/https?:\/\/[^/]+\//, "").replace(/\?[^):]+/g, "")).join("\n");
 }
@@ -299,17 +228,6 @@ const s = {
 		color: "var(--destructive, oklch(0.577 0.245 27.325))",
 		flexShrink: 0
 	},
-	pending: {
-		display: "flex",
-		alignItems: "center",
-		justifyContent: "center",
-		width: "2.5rem",
-		height: "2.5rem",
-		borderRadius: "var(--radius, 0.625rem)",
-		background: "var(--muted, oklch(0.97 0 0))",
-		color: "var(--muted-foreground, oklch(0.556 0 0))",
-		flexShrink: 0
-	},
 	heading: {
 		margin: 0,
 		fontSize: "1rem",
@@ -349,7 +267,7 @@ const s = {
 		border: "1px solid var(--input, oklch(0.922 0 0))",
 		borderRadius: "var(--radius, 0.625rem)",
 		background: "var(--input-fill, oklch(1 0 0))",
-		color: "var(--foreground, oklch(0.145 0 0))",
+		color: "var(--primary-foreground, oklch(0.985 0 0))",
 		fontFamily: "inherit",
 		fontSize: "0.875rem",
 		fontWeight: 500,

package/dist/package.js

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

package/package.json

@@ -1,37 +1,16 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.50-alpha.0",
+  "version": "0.0.50-alpha.1",
   "type": "module",
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./client": {
-      "types": "./dist/client.d.ts",
-      "import": "./dist/client.js"
-    },
-    "./server": {
-      "types": "./dist/server.d.ts",
-      "import": "./dist/server.js"
-    },
-    "./vite": {
-      "types": "./dist/vite.d.ts",
-      "import": "./dist/vite.js"
-    }
-  },
-  "bin": {
-    "softr-sdk": "./dist/cli.js"
-  },
-  "files": [
-    "dist",
-    "schema",
-    "skills",
-    "!skills/_artifacts"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
+    "./client": { "types": "./dist/client.d.ts", "import": "./dist/client.js" },
+    "./server": { "types": "./dist/server.d.ts", "import": "./dist/server.js" },
+    "./vite": { "types": "./dist/vite.d.ts", "import": "./dist/vite.js" }
+  },
+  "bin": { "softr-sdk": "./dist/cli.js" },
+  "files": ["dist", "schema", "skills", "!skills/_artifacts"],
+  "publishConfig": { "access": "public" },
   "scripts": {
     "build": "tsdown",
     "test": "node --import ./src/test-utils/setup.ts --test",
@@ -63,9 +42,7 @@
       "optional": true
     }
   },
-  "keywords": [
-    "tanstack-intent"
-  ],
+  "keywords": ["tanstack-intent"],
   "intent": {
     "version": 1,
     "repo": "@softr/sdk",

package/skills/softr-sdk/SKILL.md

@@ -11,7 +11,7 @@ description: >-
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.50
+  library_version: 0.0.50-alpha.1
 ---
 
 # Softr SDK core
@@ -137,6 +137,6 @@ type User = {
   id: string
   email: string
   fullName: string
-  userGroupIds: Array<SoftrUserGroupId>   // plain string unless you declare your ids
+  userGroupIds: Array<SoftrUserGroupId>   // the app's own group ids
 }
 ```

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

@@ -16,7 +16,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.50
+  library_version: 0.0.50-alpha.1
 ---
 
 **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

@@ -12,7 +12,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.50
+  library_version: 0.0.50-alpha.1
 ---
 
 **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/current-user/SKILL.md

@@ -4,11 +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.
+  middleware. Covers the null guest and the generated SoftrUserGroups that
+  narrows group ids to the app's own.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.50
+  library_version: 0.0.50-alpha.1
 ---
 
 # The current user
@@ -29,7 +30,7 @@ type User = {
   id: string
   email: string
   fullName: string
-  userGroupIds: Array<SoftrUserGroupId>   // plain string unless you declare your ids
+  userGroupIds: Array<SoftrUserGroupId>   // the app's own group ids
 }
 ```
 
@@ -83,6 +84,14 @@ 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.
 
+### Group ids are the app's own
+
+The generated `softr-env.d.ts` declares `SoftrUserGroups` with every group id the app has, the predefined groups included. So `user.userGroupIds` and every `userGroupIds` the SDK accepts narrow to those ids, and an id the app does not have stops compiling. A new group appears there once it exists on the app.
+
+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.
+
+Never declare `SoftrUserGroups` yourself. A second declaration does not merge with the generated one. TypeScript keeps one of the two without an error, so the ids you wrote are either ignored or hide the real ones.
+
 ## References
 
 - [routes-and-visibility/SKILL.md](../routes-and-visibility/SKILL.md): `isAuthorized` narrows `context.user` while applying the route's rule

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

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.50
+  library_version: 0.0.50-alpha.1
 ---
 
 **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/integrations/SKILL.md

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.50
+  library_version: 0.0.50-alpha.1
 ---
 
 **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.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.50
+  library_version: 0.0.50-alpha.1
 ---
 
 **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/record-mutations/SKILL.md

@@ -11,7 +11,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.50
+  library_version: 0.0.50-alpha.1
 ---
 
 **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

@@ -13,7 +13,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.50
+  library_version: 0.0.50-alpha.1
 ---
 
 **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.
@@ -51,8 +51,8 @@ const publishedPosts = defineQuery({
 ```
 
 - `id` is the name the person building the app sees, so `publishedPosts`, not `q1`. It must be unique across the app: no two declarations may share one, queries and mutations counted together.
-- `datasourceId` is the opaque UUID from the table's registration on the application (Softr Studio's Data tab, or the `register_application_data_source` tool when an agent does it). It is not the table id and is never derived from the table's name.
-- The keys of `fields` are names you choose. The values are field ids, opaque strings the table's schema gives you: `get_table` returns them for a Softr table, `list_data_source_table_fields` for a table on a connected database. Everything downstream speaks your names: the returned records, `where`, `orderBy`.
+- `datasourceId` is the opaque UUID from the table's registration on the application (Softr Studio's Data tab, or the `application_register_data_source` tool when an agent does it). It is not the table id and is never derived from the table's name.
+- The keys of `fields` are names you choose. The values are field ids, opaque strings the table's schema gives you: `database_get_table` returns them for a Softr table, `integration_list_table_fields` for a table on a connected database. Everything downstream speaks your names: the returned records, `where`, `orderBy`.
 - `permissions` declares who may run the query, and the SDK enforces it:
   - `{ userGroup: 'ALL_USERS' }`: everyone, signed out included.
   - `{ userGroup: 'NON_LOGGED_IN_USERS' }`: signed-out visitors only.

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

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

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

@@ -12,7 +12,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.50
+  library_version: 0.0.50-alpha.1
 ---
 
 **Boundary.** `defineVisibility`, the access functions and the error predicates come from `@softr/sdk` and work anywhere.
@@ -64,6 +64,8 @@ defineVisibility({                                      // those groups only
 
 Absent or empty `userGroupIds` means **any** signed-in visitor, not "nobody".
 
+Take every id in `userGroupIds` 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.
+
 ## Core Patterns
 
 ### Guard a whole section with one layout route

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.50
+  library_version: 0.0.50-alpha.1
 ---
 
 **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.
@@ -45,7 +45,7 @@ const sendWelcomeEmail = defineWorkflow({
 ```
 
 - `id` is a name you choose, unique across the app.
-- `workflowId` and `triggerId` are opaque UUIDs identifying the workflow and its **Run custom workflow** trigger. `list_workflows` returns both. Pass them as inline string literals — never derive them at runtime.
+- `workflowId` and `triggerId` are opaque UUIDs identifying the workflow and its **Run custom workflow** trigger. `workflow_list` returns both. Pass them as inline string literals — never derive them at runtime.
 - `permissions` declares who may run the trigger. Uses the same format as queries and mutations.
 - `body` is hardcoded data the server resolves before calling the workflow. It is **not** passed by the caller at runtime — the workflow always receives it. Template values draw from the signed-in user and the current time (see table below).