@softr/sdk 0.0.39 → 0.0.41-alpha.0

package/dist/cli.js

@@ -8,8 +8,9 @@ import path from "node:path";
 //#region src/cli.ts
 const OUTPUT = "softr-env.d.ts";
 async function generate() {
-	writeFileSync(path.resolve(process.cwd(), OUTPUT), renderSoftrEnv(await fetchSoftrEnvInput(metadataSourceFromEnv()), version), "utf8");
-	console.log(`[softr] wrote ${OUTPUT}`);
+	const input = await fetchSoftrEnvInput(metadataSourceFromEnv());
+	writeFileSync(path.resolve(process.cwd(), OUTPUT), renderSoftrEnv(input, version), "utf8");
+	console.log(`[softr] wrote ${OUTPUT} (${input.datasources.length} datasources)`);
 }
 const [command] = process.argv.slice(2);
 if (command === "generate") await generate();

package/dist/index.d.ts

@@ -3,8 +3,8 @@ import { ActionPermissions, SoftrDatasources, defineIntegration, defineMutation,
 import { FileAttachment } from "./core/file-upload.js";
 import { FileItem, useFileUpload } from "./core/use-file-upload.js";
 import { SoftrContext } from "./auth/context.js";
-import { defineVisibility, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError } from "./routes/visibility.js";
+import { defineVisibility, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError } from "./routes/visibility.js";
 import { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser, usePermissions } from "./auth/isomorphic.js";
 import { useUserTimezone } from "./timezone.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
-export { type ActionPermissions, DefaultErrorOverlay, type FileAttachment, type FileItem, type SoftrContext, type SoftrDatasources, type SoftrUserGroupId, type SoftrUserGroups, type User, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, initialSoftrContext, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, useCurrentUser, useFileUpload, usePermissions, useUserTimezone };
+export { type ActionPermissions, DefaultErrorOverlay, type FileAttachment, type FileItem, type SoftrContext, type SoftrDatasources, type SoftrUserGroupId, type SoftrUserGroups, type User, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, useCurrentUser, useFileUpload, usePermissions, useUserTimezone };

package/dist/index.js

@@ -1,8 +1,8 @@
 import { useFileUpload } from "./core/use-file-upload.js";
 import { defineIntegration, defineMutation, defineQuery, defineWorkflow } from "./action.js";
-import { defineVisibility, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError } from "./routes/visibility.js";
+import { defineVisibility, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError } from "./routes/visibility.js";
 import { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser, usePermissions } from "./auth/isomorphic.js";
 import { useUserTimezone } from "./timezone.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
 
-export { DefaultErrorOverlay, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, initialSoftrContext, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, useCurrentUser, useFileUpload, usePermissions, useUserTimezone };
+export { DefaultErrorOverlay, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, useCurrentUser, useFileUpload, usePermissions, useUserTimezone };

package/dist/package.js

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

package/dist/routes/visibility.d.ts

@@ -24,9 +24,9 @@ type RouteVisibility = {
  *
  * - `unauthenticated` — the route needs a signed-in visitor and there is none.
  * - `forbidden` — signed in, but in none of the groups the route names.
- * - `alreadySignedIn` — the route is for signed-out visitors only.
+ * - `alreadyAuthenticated` — the route is for signed-out visitors only.
  */
-declare const ACCESS_REASONS: readonly ["unauthenticated", "forbidden", "alreadySignedIn"];
+declare const ACCESS_REASONS: readonly ["unauthenticated", "forbidden", "alreadyAuthenticated"];
 type AccessReason = (typeof ACCESS_REASONS)[number];
 /**
  * What a guard does when it refuses a visitor: redirect to a path, or throw an
@@ -78,7 +78,7 @@ declare function isUnauthenticatedError(error: unknown): error is AccessError;
 /** True for an access error thrown because the visitor was in none of the groups. */
 declare function isForbiddenError(error: unknown): error is AccessError;
 /** True for an access error thrown because a signed-out-only route saw a user. */
-declare function isAlreadySignedInError(error: unknown): error is AccessError;
+declare function isAlreadyAuthenticatedError(error: unknown): error is AccessError;
 type Narrowed<R extends RouteVisibility> = R extends {
   userGroup: "LOGGED_IN_USERS";
 } ? AccessContext & {
@@ -139,4 +139,4 @@ type VisibilityHandle<R extends RouteVisibility = RouteVisibility> = {
  */
 declare function defineVisibility<const R extends RouteVisibility>(rule: R): VisibilityHandle<R>;
 //#endregion
-export { defineVisibility, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError };
+export { defineVisibility, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError };

package/dist/routes/visibility.js

@@ -1,3 +1,4 @@
+import { panic } from "../assertions.js";
 import { redirect } from "@tanstack/react-router";
 
 //#region src/routes/visibility.ts
@@ -6,12 +7,12 @@ import { redirect } from "@tanstack/react-router";
 *
 * - `unauthenticated` — the route needs a signed-in visitor and there is none.
 * - `forbidden` — signed in, but in none of the groups the route names.
-* - `alreadySignedIn` — the route is for signed-out visitors only.
+* - `alreadyAuthenticated` — the route is for signed-out visitors only.
 */
 const ACCESS_REASONS = [
 	"unauthenticated",
 	"forbidden",
-	"alreadySignedIn"
+	"alreadyAuthenticated"
 ];
 /** Decides whether a visitor passes a visibility rule, without throwing. */
 function checkAccess(rule, context) {
@@ -20,7 +21,7 @@ function checkAccess(rule, context) {
 		case "ALL_USERS": return { ok: true };
 		case "NON_LOGGED_IN_USERS": return user === null ? { ok: true } : {
 			ok: false,
-			reason: "alreadySignedIn"
+			reason: "alreadyAuthenticated"
 		};
 		case "LOGGED_IN_USERS": {
 			if (user === null) return {
@@ -63,23 +64,12 @@ function isForbiddenError(error) {
 	return isReason(error, "forbidden");
 }
 /** True for an access error thrown because a signed-out-only route saw a user. */
-function isAlreadySignedInError(error) {
-	return isReason(error, "alreadySignedIn");
+function isAlreadyAuthenticatedError(error) {
+	return isReason(error, "alreadyAuthenticated");
 }
-const DEFAULT_ACCESS_BEHAVIOUR = {
-	unauthenticated: {
-		strategy: "redirect",
-		to: "/login"
-	},
-	forbidden: { strategy: "throw" },
-	alreadySignedIn: {
-		strategy: "redirect",
-		to: "/"
-	}
-};
 /** What a guard throws for a reason: a redirect, or an {@link AccessError}. */
 function thrownFor(reason, overrides) {
-	const behaviour = overrides?.[reason] ?? DEFAULT_ACCESS_BEHAVIOUR[reason];
+	const behaviour = overrides?.[reason] ?? (typeof __SOFTR_CONFIG__ === "undefined" ? panic("softr.json is missing, so no guard behaviour is configured") : __SOFTR_CONFIG__.auth.guard[reason]);
 	const resolved = typeof behaviour === "string" ? {
 		strategy: "redirect",
 		to: behaviour
@@ -122,4 +112,4 @@ function defineVisibility(rule) {
 }
 
 //#endregion
-export { defineVisibility, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError };
+export { defineVisibility, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError };

package/dist/softr-config.js

@@ -0,0 +1,19 @@
+import { z } from "zod";
+
+//#region src/softr-config.ts
+const AccessBehaviour = z.union([
+	z.string(),
+	z.object({
+		strategy: z.literal("redirect"),
+		to: z.string()
+	}),
+	z.object({ strategy: z.literal("throw") })
+], { error: "must be a path like \"/login\", { \"strategy\": \"redirect\", \"to\": \"/login\" } or { \"strategy\": \"throw\" }" });
+const SoftrConfigSchema = z.object({ auth: z.strictObject({ guard: z.strictObject({
+	unauthenticated: AccessBehaviour,
+	forbidden: AccessBehaviour,
+	alreadyAuthenticated: AccessBehaviour
+}) }) });
+
+//#endregion
+export { SoftrConfigSchema };

package/dist/vite.d.ts

@@ -1,7 +1,6 @@
 import { PluginOption } from "vite";
 
 //#region src/vite.d.ts
-/** Everything Softr adds to an app's Vite config: the studio edit engine, when there is a pod. */
 declare function softr(): PluginOption[];
 //#endregion
 export { softr };

package/dist/vite.js

@@ -1,10 +1,45 @@
+import { assert, panic } from "./assertions.js";
+import { SoftrConfigSchema } from "./softr-config.js";
+import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
+import { z } from "zod";
 import { pathToFileURL } from "node:url";
 
 //#region src/vite.ts
-/** Everything Softr adds to an app's Vite config: the studio edit engine, when there is a pod. */
+const SOFTR_CONFIG_FILE = "softr.json";
 function softr() {
-	return [editEngine()];
+	return [softrConfig(), editEngine()];
+}
+function softrConfig() {
+	let root;
+	return {
+		name: "softr:config",
+		config(userConfig) {
+			root = path.resolve(userConfig.root ?? process.cwd());
+			return { define: { __SOFTR_CONFIG__: JSON.stringify(loadSoftrConfig(root)) } };
+		},
+		configureServer(server) {
+			const file = path.join(root, SOFTR_CONFIG_FILE);
+			server.watcher.add(file);
+			server.watcher.on("change", (changed) => {
+				if (changed === file) server.restart();
+			});
+		}
+	};
+}
+function loadSoftrConfig(root) {
+	const file = path.join(root, SOFTR_CONFIG_FILE);
+	assert(existsSync(file), `${SOFTR_CONFIG_FILE} is missing from ${root}`);
+	const source = readFileSync(file, "utf8");
+	let parsed;
+	try {
+		parsed = JSON.parse(source);
+	} catch (error) {
+		panic(`${SOFTR_CONFIG_FILE} is not valid JSON: ${error instanceof Error ? error.message : error}`);
+	}
+	const result = SoftrConfigSchema.safeParse(parsed);
+	if (!result.success) panic(`${SOFTR_CONFIG_FILE} does not match the schema:\n\n${z.prettifyError(result.error)}`);
+	return result.data;
 }
 /**
 * The edit engine is provided by the pod runtime rather than an app dependency: it is never in the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.39",
+  "version": "0.0.41-alpha.0",
   "type": "module",
   "exports": {
     ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
@@ -9,7 +9,7 @@
     "./vite": { "types": "./dist/vite.d.ts", "import": "./dist/vite.js" }
   },
   "bin": { "softr-sdk": "./dist/cli.js" },
-  "files": ["dist", "skills", "!skills/_artifacts"],
+  "files": ["dist", "schema", "skills", "!skills/_artifacts"],
   "publishConfig": { "access": "public" },
   "scripts": {
     "build": "tsdown",

package/schema/softr.schema.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "softr.json",
+  "type": "object",
+  "properties": {
+    "auth": {
+      "type": "object",
+      "description": "Authentication. Written in this repo and read by the app's build.",
+      "properties": {
+        "guard": {
+          "type": "object",
+          "description": "What a route guard does when it denies a visitor. A route's own overrides win over these.",
+          "properties": {
+            "unauthenticated": {
+              "$ref": "#/$defs/accessBehaviour",
+              "description": "The route needs a signed-in visitor and there is none. Defaults to a redirect to /login."
+            },
+            "alreadyAuthenticated": {
+              "$ref": "#/$defs/accessBehaviour",
+              "description": "The route is for signed-out visitors only. Defaults to a redirect to /."
+            },
+            "forbidden": {
+              "$ref": "#/$defs/accessBehaviour",
+              "description": "Signed in, but in none of the groups the route names. Defaults to throwing, for the route's errorComponent to render."
+            }
+          },
+          "required": ["unauthenticated", "alreadyAuthenticated", "forbidden"],
+          "additionalProperties": false
+        }
+      },
+      "required": ["guard"],
+      "additionalProperties": false
+    }
+  },
+  "required": ["auth"],
+  "$defs": {
+    "accessBehaviour": {
+      "oneOf": [
+        { "type": "string", "description": "A path to redirect to." },
+        {
+          "type": "object",
+          "properties": {
+            "strategy": { "const": "redirect" },
+            "to": { "type": "string" }
+          },
+          "required": ["strategy", "to"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": { "strategy": { "const": "throw" } },
+          "required": ["strategy"],
+          "additionalProperties": false
+        }
+      ]
+    }
+  }
+}

package/skills/softr-sdk/SKILL.md

@@ -11,7 +11,7 @@ description: >-
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.39
+  library_version: 0.0.41-alpha.0
 ---
 
 # Softr SDK core

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

@@ -16,7 +16,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.39
+  library_version: 0.0.41-alpha.0
 ---
 
 **Boundary.** `auth` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineVisibility`, the hooks and every type come from `@softr/sdk`. The app is already wired (`src/start.ts`, `src/router.tsx`, `src/routes/__root.tsx`); never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
@@ -353,5 +353,5 @@ After a reset, enrol the new app with `startAuthenticatorSetup` and `confirmAuth
 ## References
 
 - [current-user/SKILL.md](../current-user/SKILL.md): reading the visitor these calls establish
-- [routes-and-visibility/SKILL.md](../routes-and-visibility/SKILL.md): `NON_LOGGED_IN_USERS` and the `alreadySignedIn` redirect that keeps a signed-in visitor off a login page
+- [routes-and-visibility/SKILL.md](../routes-and-visibility/SKILL.md): `NON_LOGGED_IN_USERS` and the `alreadyAuthenticated` redirect that keeps a signed-in visitor off a login page
 - `src/routes/_auth/login.tsx` and `signup.tsx` in your own app: the implementations it was scaffolded with

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.39
+  library_version: 0.0.41-alpha.0
 ---
 
 **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. The app is already wired (`src/start.ts`, `src/router.tsx`, `src/routes/__root.tsx`); never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.

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

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.39
+  library_version: 0.0.41-alpha.0
 ---
 
 **Boundary.** `useCurrentUser`, `usePermissions` and every type come from `@softr/sdk` and work anywhere; `ds` and `auth` live on `@softr/sdk/server` and run only inside a `createServerFn` handler. The app is already wired — `src/start.ts` registers `softrAuthMiddleware`, `src/routes/__root.tsx` publishes the visitor as route context — never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.

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

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.39
+  library_version: 0.0.41-alpha.0
 ---
 
 **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. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.

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

@@ -11,7 +11,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.39
+  library_version: 0.0.41-alpha.0
 ---
 
 **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. The app is already wired (`src/start.ts`, `src/router.tsx`, `src/routes/__root.tsx`); never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
@@ -133,6 +133,10 @@ await ds.update(updateProject, {
 
 A read answers a SELECT as `{ id, label }` and a write takes `{ id }`, so pass the id through rather than the whole value.
 
+### Form dropdowns for linked record fields
+
+A form select for a `LINKED_RECORD` field needs its options from the linked table, not from the record being edited. Query the linked table with its own `defineQuery` and `ds.list`; each result's `id` is what you pass to the write payload. See [record-queries](../record-queries/SKILL.md).
+
 ### What a write accepts
 
 Each key of `data` accepts exactly what its field takes (see [record-queries](../record-queries/SKILL.md#typing)):

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

@@ -5,14 +5,15 @@ description: >-
   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, 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.
+  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.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.39
+  library_version: 0.0.41-alpha.0
 ---
 
 **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. The app is already wired (`src/start.ts`, `src/router.tsx`, `src/routes/__root.tsx`); never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
@@ -146,6 +147,38 @@ const listMyInvoices = createServerFn().handler(async ({ context }) => {
 
 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:
+
+```ts
+// "status" on the products table is a LINKED_RECORD pointing to the Product Statuses table
+const productStatuses = defineQuery({
+  id: 'productStatuses',
+  datasourceId: '00000000-0000-0000-0000-000000000001', // the linked table's datasource id
+  fields: { name: 'fZk3Qm9pLw2Xa1' },
+  permissions: { userGroup: 'ALL_USERS' },
+})
+
+const listProductStatuses = createServerFn().handler(async () => {
+  return await ds.list(productStatuses).limit(100)
+})
+```
+
+Each returned record is one option: `record.id` is the value a `where` filter and a mutation payload take; `record.fields.name` is what you display.
+
+```tsx
+// Filter dropdown
+{statuses.map((s) => (
+  <option key={s.id} value={s.id}>{s.fields.name}</option>
+))}
+
+// Filtering the main table by the selected linked record
+ds.list(products).where((q) => q.status.is(selectedStatusId))
+```
+
+Skip this request when the options are predefined and fixed — hardcode them instead.
+
 A read the datasource turns down throws rather than coming back empty, and it throws a plain `Error` carrying the status. 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.
 
 ## Typing

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

@@ -6,13 +6,13 @@ description: >-
   four ways to enforce a rule (guard, assert, isAuthorized, check). Covers
   per-reason overrides, the redirect and throw strategies, rendering an access
   error with isAccessError, isUnauthenticatedError, isForbiddenError and
-  isAlreadySignedInError, guarding a layout, and the lint rule that requires a
+  isAlreadyAuthenticatedError, guarding a layout, and the lint rule that requires a
   declaration alongside the rules that reject a duplicate, computed or
   root-level one.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.39
+  library_version: 0.0.41-alpha.0
 ---
 
 **Boundary.** `defineVisibility`, the error predicates and every type come from `@softr/sdk` and work anywhere; `ds` and `auth` live on `@softr/sdk/server` and run only inside a `createServerFn` handler. The app is already wired — `src/start.ts` registers `softrAuthMiddleware`, `src/routes/__root.tsx` publishes the visitor as route context — never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
@@ -82,7 +82,7 @@ export const Route = createFileRoute('/_app')({
 
 The whole match chain runs, so a layout guards everything beneath it. Sibling routes do not guard each other. `/admin/index.tsx` does nothing for `/admin/users.tsx` unless an `admin.tsx` layout exists. Routes below a guarded layout still declare their own rule, because the declaration is what Studio reads.
 
-A thrown error renders in place of the guarded route's component. The template's `_app.tsx` shell is guarded with `LOGGED_IN_USERS`, whose default for a signed-out visitor is a redirect, so nothing ever renders there. A rule that can *throw* — a `userGroupIds` rule, whose `forbidden` default is throw — should not sit on the shell itself, or the refusal replaces the nav and chrome. Put it on a layout inside the shell, or on the restricted routes, so the refusal renders inside the chrome.
+A thrown error renders in place of the guarded route's component. A shell layout guarded with `LOGGED_IN_USERS`, where `unauthenticated` redirects, sends a signed-out visitor away before anything renders there. A rule that can *throw* — a `userGroupIds` rule with `forbidden` set to throw — should not sit on the shell itself, or the error replaces the nav and chrome. Put it on a layout inside the shell, or on the restricted routes, so the error renders inside the chrome.
 
 ### Change what a denied visitor gets
 
@@ -99,15 +99,30 @@ beforeLoad: visibility.guard({
 
 The long redirect form and the bare string do the same thing.
 
-The defaults, when no override is given:
+Every app declares where a denied visitor goes in `softr.json`, at the app root, and every app has one:
+
+```json
+{
+  "$schema": "./node_modules/@softr/sdk/schema/softr.schema.json",
+  "auth": {
+    "guard": {
+      "unauthenticated": "/login",
+      "alreadyAuthenticated": "/",
+      "forbidden": { "strategy": "throw" }
+    }
+  }
+}
+```
+
+All three reasons are required, because nothing fills in a reason the file leaves out:
 
-| Reason | Condition | Default |
-| --- | --- | --- |
-| `unauthenticated` | Route needs a visitor, none present | Redirect to `/login` |
-| `forbidden` | Signed in, in none of the named groups | Throw, renders in place |
-| `alreadySignedIn` | Signed-in visitor on a signed-out-only route | Redirect to `/` |
+| Reason | Condition |
+| --- | --- |
+| `unauthenticated` | Route needs a visitor, none present |
+| `forbidden` | Signed in, in none of the named groups |
+| `alreadyAuthenticated` | Signed-in visitor on a signed-out-only route |
 
-`ALL_USERS` admits everyone, so it never redirects and never throws. Only `strategy: 'throw'` reaches an `errorComponent`. A redirect navigates away and the route never renders.
+That file covers every route at once; a route's own `guard()` overrides win over it. `ALL_USERS` admits everyone, so it never redirects and never throws. Only `strategy: 'throw'` reaches an `errorComponent`. A redirect navigates away and the route never renders.
 
 ### Render the error in place
 
@@ -133,11 +148,11 @@ export const Route = createFileRoute('/_app/billing')({
 
 The error carries a `type` discriminant and its `reason`, nothing else. It never names the groups the route wanted, which would hand that list to the one visitor who was just turned away.
 
-Use the predicates: `isAccessError` for any of the three, and `isUnauthenticatedError`, `isForbiddenError`, `isAlreadySignedInError` for one each. The error is plain data rather than an `Error` subclass, so `instanceof` never matches and there is no `message` to read. That is also why the parameter is annotated `error: unknown`. The router types it as `Error`, and the wider annotation is what lets the predicates narrow it. Leave it as it is.
+Use the predicates: `isAccessError` for any of the three, and `isUnauthenticatedError`, `isForbiddenError`, `isAlreadyAuthenticatedError` for one each. The error is plain data rather than an `Error` subclass, so `instanceof` never matches and there is no `message` to read. That is also why the parameter is annotated `error: unknown`. The router types it as `Error`, and the wider annotation is what lets the predicates narrow it. Leave it as it is.
 
 ### Run the check and then keep going
 
-`guard()` covers almost everything. When a route needs its own logic afterwards, `assert()` applies the same rule and throws the same access error, using the default behaviour for each reason. It takes no overrides.
+`guard()` covers almost everything. When a route needs its own logic afterwards, `assert()` applies the same rule and throws the same access error, using `softr.json` for each reason. It takes no overrides.
 
 `assert()` guarantees the visitor at runtime but does not narrow `context.user` for the compiler. `isAuthorized()` is the one that narrows. It is a type predicate, so inside its `true` branch `context.user` is `User` under `LOGGED_IN_USERS` and `null` under `NON_LOGGED_IN_USERS`.
 

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.39
+  library_version: 0.0.41-alpha.0
 ---
 
 **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. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.