@softr/sdk 0.0.38 → 0.0.40

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/core/file-upload.js

@@ -19,14 +19,11 @@ async function upload(action, file) {
 		body: formData
 	});
 	if (!res.ok) throw new Error(`File upload failed: ${res.status}`);
-	const rawUrl = await res.json();
-	const parsed = new URL(rawUrl);
-	const fileId = parsed.searchParams.get("fileId") || randomUUID();
-	parsed.searchParams.delete("fileId");
+	const resultJSON = await res.json();
 	return {
-		url: parsed.toString(),
-		filename: file.name || "Untitled file",
-		id: fileId
+		url: resultJSON.url,
+		filename: resultJSON.filename || "Untitled file",
+		id: resultJSON.id || randomUUID()
 	};
 }
 

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 import { SoftrUserGroupId, SoftrUserGroups, User } from "./auth/user.js";
 import { ActionPermissions, SoftrDatasources, defineIntegration, defineMutation, defineQuery, defineWorkflow } from "./action.js";
 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 SoftrContext, type SoftrDatasources, type SoftrUserGroupId, type SoftrUserGroups, type User, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, initialSoftrContext, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, useCurrentUser, 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,7 +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, 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.38";
+var version = "0.0.40";
 
 //#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.38",
+  "version": "0.0.40",
   "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.38
+  library_version: 0.0.40
 ---
 
 # 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.38
+  library_version: 0.0.40
 ---
 
 **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.38
+  library_version: 0.0.40
 ---
 
 **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.38
+  library_version: 0.0.40
 ---
 
 **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

@@ -1,7 +1,7 @@
 ---
 name: file-uploads
 description: >-
-  Upload files from a form or edit view: useFileUpload(action) from @softr/sdk/client does
+  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.
@@ -9,10 +9,10 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.38
+  library_version: 0.0.40
 ---
 
-**Boundary.** `upload` lives on `@softr/sdk/server` and runs inside server functions. `useFileUpload` and `FileItem` live on `@softr/sdk/client` and run only in components. `FileAttachment` comes from `@softr/sdk` and can be imported anywhere.
+**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.
 
 # File uploads
 
@@ -21,9 +21,8 @@ metadata:
 ## Setup
 
 ```ts
-import { defineMutation, type FileAttachment } from '@softr/sdk'
+import { defineMutation, type FileAttachment, useFileUpload, type FileItem } from '@softr/sdk'
 import { ds } from '@softr/sdk/server'
-import { useFileUpload, type FileItem } from '@softr/sdk/client'
 ```
 
 ## Core pattern

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

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

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

@@ -12,7 +12,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.38
+  library_version: 0.0.40
 ---
 
 **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/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.38
+  library_version: 0.0.40
 ---
 
 **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.38
+  library_version: 0.0.40
 ---
 
 **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.