@softr/sdk 0.0.64 → 0.0.65

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

@@ -7,16 +7,19 @@ description: >-
   sign-in (verifyAuthenticator, startAuthenticatorSetup,
   confirmAuthenticatorSetup, skipAuthenticatorSetup) and the ones that change an
   authenticator from a settings page (sendAuthenticatorResetCode,
-  resetAuthenticator, removeAuthenticator). Covers the Result shape they answer
-  with ({ success, data } | { success, error }) and its codes
-  invalidCredentials, tooManyAttempts, emailTaken, invalidDetails, invalidCode
-  and notAuthenticated, the two-step sign-up, and why a successful sign-in does
-  not always mean the visitor is signed in. The blank template already ships
-  working login and signup pages.
+  resetAuthenticator, removeAuthenticator), 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 codes invalidCredentials, tooManyAttempts, emailTaken,
+  invalidDetails, invalidCode, notAuthenticated, emailDomainNotAllowed and
+  linkExpired, 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.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.64
+  library_version: 0.0.65
 ---
 
 **Boundary.** `auth` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build.
@@ -25,6 +28,12 @@ metadata:
 
 `auth` is what changes who the visitor is.
 
+Reading how the app signs people in:
+
+| Call | Does |
+| --- | --- |
+| `auth.settings()` | Returns the sign-in and sign-up settings the builder chose in Studio |
+
 Signing in:
 
 | Call | Does |
@@ -42,6 +51,14 @@ Signing up:
 | `auth.signUp({ email, name? })` | Emails a verification code, creates no account |
 | `auth.confirmSignUp({ email, code, name?, password? })` | Creates the account and signs the visitor in |
 
+Setting a password from an emailed link, for a password reset or an invitation:
+
+| Call | Does |
+| --- | --- |
+| `auth.requestPasswordReset({ email })` | Emails a link to set a new password |
+| `auth.checkPasswordLink({ token })` | Returns the `email` the link was sent to, and leaves the link usable |
+| `auth.setPasswordWithLink({ token, password })` | Sets the password and signs the visitor in |
+
 Signing out:
 
 | Call | Does |
@@ -65,8 +82,6 @@ Changing an authenticator from a settings page:
 | `auth.resetAuthenticator({ code })` | Unpairs the app, so a new one can be enrolled |
 | `auth.removeAuthenticator({ code })` | Turns the authenticator off |
 
-**The blank template already ships a working login page and signup page.** Read `src/routes/_auth/login.tsx` before writing anything new. Most tasks are an edit to those, not a new flow.
-
 ## Setup
 
 `auth` is server-only, so every call sits inside a `createServerFn` handler:
@@ -107,29 +122,73 @@ type AuthErrorCode =
   | 'invalidCredentials'   // signIn, signInWithGoogle, signInWithMagicLink: wrong password, or a token Softr would not take
   | 'tooManyAttempts'      // any call: rate limited
   | 'emailTaken'           // signUp, confirmSignUp: that email already has an account
-  | 'invalidDetails'       // signUp, sendSignInCode: details Softr rejected
+  | 'invalidDetails'       // signUp, sendSignInCode, setPasswordWithLink: details Softr rejected
   | 'invalidCode'          // any call that takes a code: wrong or expired
   | 'notAuthenticated'     // a call that needs a signed-in visitor, made by one who is not
+  | 'emailDomainNotAllowed' // signUp, signInWithGoogle: the app lets only some email domains sign up, and this is not one
+  | 'linkExpired'          // checkPasswordLink, setPasswordWithLink: the link is used, expired or no longer valid
 ```
 
 Branch on `error.code` with a `switch` and write your own wording. Never put `error.message` in front of the visitor.
 
 `code` is typed as every code the SDK produces, not the ones a given call can answer, so a `switch` needs a `default` even when the cases above it are complete. Give it a message rather than leaving it out.
 
+## Render only the methods the app has enabled
+
+`getAuthSettings` from `@softr/sdk` loads which ways in the app offers. Call it in the loader of a route that sits above every page needing it, and wrap that route's children in `AuthSettingsProvider`. If the auth pages share a layout route, that route is the usual place:
+
+```tsx
+import { AuthSettingsProvider, getAuthSettings } from '@softr/sdk'
+
+// in the route options
+loader: () => getAuthSettings(),
+staleTime: 60_000,
+
+// in the route's component
+const authSettings = Route.useLoaderData()
+return (
+  <AuthSettingsProvider value={authSettings}>
+    <Outlet />
+  </AuthSettingsProvider>
+)
+```
+
+Any page or component below it reads them with `useAuthSettings()`, which needs the provider above it:
+
+```tsx
+const options = useAuthSettings()
+return options.password && <PasswordForm />
+```
+
+Each field names the `auth` call it unlocks:
+
+| Field | When on, offer |
+| --- | --- |
+| `password` | the password form, `auth.signIn` |
+| `emailCode` | sign-in with a code, `auth.sendSignInCode` |
+| `magicLink` | the route that calls `auth.signInWithMagicLink` |
+| `google` | a Google button started with `google.clientId`. `null` means no Google. Never hardcode a client id. |
+| `signUp` | sign-up, `auth.signUp` |
+| `strongPasswords` | the strong-password rules, on every form that sets a new password. Check the password against them before submitting. |
+
+When the builder turns sign-in off, every field is off.
+
+Render nothing for a field that is off. A page for a flow that is off answers 404 from its loader. Throw `notFound()` there, never from the component: a component that renders nothing answers 200 with an empty page. `auth.settings()` returns the full settings, for a server function that needs more than these.
+
 ## A successful sign-in is not always a session
 
-`signIn`, `signInWithCode`, `signInWithGoogle`, `signInWithMagicLink` and `confirmSignUp` all answer the same two ways:
+`signIn`, `signInWithCode`, `signInWithGoogle`, `signInWithMagicLink`, `setPasswordWithLink` and `confirmSignUp` all answer the same two ways:
 
 ```ts
 { status: 'signedIn', user }
 { status: 'authenticatorRequired', step: 'verify' | 'setup' | 'setupOptional' }
 ```
 
-`signedIn` is a session. Redirect into the app.
+`signedIn` is a session. Send the visitor to the return target, see [Landing after sign-in](#landing-after-sign-in).
 
 `authenticatorRequired` is not. The app asks for an authenticator app as well, and the visitor has no session until they produce one. Redirecting into the app here sends them to a page they cannot see, and a guarded page bounces them back to the login form with nothing on screen explaining why.
 
-Send them on by `step`:
+Show the second factor as the next step of the page that signed them in, not on a page of its own. Pick what it shows by `step`:
 
 | `step` | Show them | Finish with |
 | --- | --- | --- |
@@ -141,6 +200,27 @@ Those calls take only what the visitor typed. The sign-in they finish is the one
 
 An app with no authenticator app configured never answers `authenticatorRequired`. The type still has both arms either way, so `result.data.user` does not exist until you have narrowed on `status`.
 
+## Landing after sign-in
+
+A guard that turns a signed-out visitor away sends them to the page `softr.json` names for that, usually the login page. The page they wanted rides along in the search param named for the login page. `toReturnPath` from `@softr/sdk` reads it back:
+
+```tsx
+import { useLocation, useNavigate } from '@tanstack/react-router'
+import { toReturnPath } from '@softr/sdk'
+
+const location = useLocation()
+const navigate = useNavigate()
+
+// once the visitor is signed in
+await navigate(toReturnPath(location))
+```
+
+A loader that signs the visitor in throws it instead: `throw redirect(toReturnPath(location))`, with the loader's own `location`.
+
+It goes to the page they wanted when that is a path on this app. Otherwise it goes where `auth.guard.alreadyAuthenticated` in `softr.json` points, or to `/` when that setting throws. It reloads the page, so the app sees the visitor as signed in. Pass its answer as is. Never read the param yourself: anyone can put a link to another site in it.
+
+Every page that ends a sign-in lands there: login, sign-up, the magic link, a password link and the second-factor step. A link from one auth page to another keeps the search param, or the target is lost on the way.
+
 ## Core Patterns
 
 ### Sign in
@@ -162,24 +242,27 @@ const signIn = createServerFn({ method: 'POST' })
       }
     }
 
-    if (result.data.status === 'authenticatorRequired') {
-      throw redirect({ to: '/verify', search: { step: result.data.step } })
-    }
-
-    throw redirect({ to: '/' })
+    return { message: null, outcome: result.data }
   })
 ```
 
-Three exits: a message for the form to render, a redirect to the second factor, a redirect into the app.
-
-Call it from the component with `useServerFn`:
+The component takes it from there:
 
 ```tsx
 import { useServerFn } from '@tanstack/react-start'
 
 const submit = useServerFn(signIn)
+
+const answer = await submit({ data: { email, password } })
+if (answer.message !== null) return setMessage(answer.message)
+if (answer.outcome.status === 'authenticatorRequired') {
+  return setStep({ name: 'secondFactor', opensOn: answer.outcome.step })
+}
+await navigate({ href: target })
 ```
 
+Three exits: a message for the form to render, the second-factor step, the return target.
+
 A server function that throws `redirect` needs the hook. Call the imported function directly and the throw never reaches the router, so a successful sign-in leaves the visitor on the form.
 
 A login page is a `NON_LOGGED_IN_USERS` route, which is what keeps an already-signed-in visitor off it. See [routes-and-visibility](../routes-and-visibility/SKILL.md).
@@ -221,6 +304,25 @@ const result = await auth.signInWithMagicLink({ token })
 
 The token keeps working after it is used, so anyone holding the link can sign in as that visitor. Never log it, and redirect away from the URL that carried it.
 
+### Set a password from an emailed link
+
+A password reset and an invitation both email a link with a token. The same two calls redeem either.
+
+```ts
+// The forgot-password form. Succeeds whether or not the address has an account.
+const sent = await auth.requestPasswordReset({ email })
+
+// The loader of the page the link opens. Show an expired message on linkExpired, before any form.
+const link = await auth.checkPasswordLink({ token })
+
+// The form's submit. Same two-armed result as signIn.
+const result = await auth.setPasswordWithLink({ token, password })
+```
+
+Say "check your email" after `requestPasswordReset` either way, and never branch the UI on it.
+
+`setPasswordWithLink` uses up the link on any success, `authenticatorRequired` included, and signs the visitor out everywhere else.
+
 ### Sign out
 
 ```ts
@@ -249,6 +351,8 @@ const startSignUp = createServerFn({ method: 'POST' })
           return { message: 'That email already has an account.' }
         case 'invalidDetails':
           return { message: 'Please check the details and try again.' }
+        case 'emailDomainNotAllowed':
+          return { message: 'Sign-up is open only to some email domains, and yours is not one.' }
         case 'tooManyAttempts':
           return { message: 'Too many attempts. Please try again in a few minutes.' }
         default:
@@ -276,11 +380,7 @@ const finishSignUp = createServerFn({ method: 'POST' })
       }
     }
 
-    if (result.data.status === 'authenticatorRequired') {
-      throw redirect({ to: '/verify', search: { step: result.data.step } })
-    }
-
-    throw redirect({ to: '/' })
+    return { message: null, outcome: result.data }   // handled as sign-in's is
   })
 ```
 
@@ -307,7 +407,7 @@ const verify = createServerFn({ method: 'POST' })
           return { message: 'Could not check that code. Please try again.' }
       }
     }
-    throw redirect({ to: '/' })
+    return { message: null }   // signed in: the component goes to the target
   })
 ```
 
@@ -329,11 +429,12 @@ Neither of those enrols anybody. `confirmAuthenticatorSetup` does, once it accep
 ```ts
 const done = await auth.confirmAuthenticatorSetup({ code })
 if (done.success) {
-  done.data.backupCodes  // returned once. Render them now, nothing fetches them again.
-  throw redirect({ to: '/' })
+  return { backupCodes: done.data.backupCodes }  // returned once. Render them now, nothing fetches them again.
 }
 ```
 
+The visitor is signed in while the codes are on screen, often on a page only signed-out visitors may see. Invalidating the router or navigating re-runs that page's guard, which sends them away and the codes are gone. Do neither until they click "Continue", then go to the target.
+
 Call `startAuthenticatorSetup` again to hand back a fresh QR code, for a visitor who lost the first one. Only the newest one enrols them.
 
 `skipAuthenticatorSetup` finishes the sign-in without enrolling, and only on `setupOptional`. Later sign-ins stop asking.
@@ -353,5 +454,4 @@ 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 `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
+- [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

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.64
+  library_version: 0.0.65
 ---
 
 **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

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

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

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.64
+  library_version: 0.0.65
 ---
 
 **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

@@ -4,13 +4,13 @@ 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.
+  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.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.64
+  library_version: 0.0.65
 ---
 
 # Dates, times and numbers

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

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.64
+  library_version: 0.0.65
 ---
 
 **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

@@ -5,11 +5,11 @@ description: >-
   @softr/sdk, registered in src/start.ts ahead of softrAuthMiddleware, turns the
   actions you list into tools an assistant can call as the signed-in visitor.
   The list is explicit — an action left out is invisible over MCP. The app's own
-  login must honour a `redirect` search param, or the approval step dead-ends.
+  login must land on toReturnPath, or the approval step dead-ends.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.64
+  library_version: 0.0.65
 ---
 
 **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.
@@ -59,18 +59,11 @@ Reads first. Add a write only when the user asked for one, and name it back to t
 
 ## The login round trip
 
-Connecting starts with an approval page the app serves. Most people hit it signed out, and that page cannot sign anyone in. It sends them to the app's sign-in page with a `redirect` search param holding where to come back to. That page is `/login` unless you pass `loginPath`:
+Connecting starts with an approval page the app serves. Most people hit it signed out, and that page cannot sign anyone in. It sends them to the login page named in `softr.json` (`auth.routes.login.path`), with the approval page in the search param named there (`auth.routes.login.redirectParam`).
 
-```ts
-softrMcpMiddleware({ actions: [listCafes], loginPath: '/sign-in' })
-```
-
-**The app's login has to honour that param.** Carry it through every exit that ends a sign-in, the second-factor step included, and send the visitor there instead of the home page. Drop it anywhere along the way and the approval dies quietly: they land on the home page, the assistant never gets its answer, nothing reports an error.
-
-Validate it before following it. A path on this app and nothing else. Ask the URL parser rather than checking prefixes: resolve the value against a placeholder origin and reject it unless the origin survives. Browsers read `\` as `/` and drop tabs and newlines, so a value that does not start with `//` can still leave the app. The whole flow starts with a link someone was sent, so this is the one redirect an attacker can reliably aim.
-
-The blank template does this in `src/routes/_auth/login.tsx`, `src/routes/verify.tsx` and `src/lib/after-auth.ts`. Read those before writing your own.
+**The app's login has to send them back.** Every exit that ends a sign-in, the second-factor step included, goes to `toReturnPath(location)` instead of the home page. See [auth/SKILL.md](../auth/SKILL.md). Lose the search param anywhere along the way and the approval dies quietly: they land on the home page, the assistant never gets its answer, nothing reports an error.
 
+`toReturnPath` only ever goes to a path on this app. Never follow the param without it. The whole flow starts with a link someone was sent, so this is the one redirect an attacker can reliably aim.
 ## Failure modes
 
 **Registering with no actions.** `softrMcpMiddleware()` is valid and serves an endpoint with nothing on it. The assistant connects, lists tools, finds only `whoami`. Pass the actions.
@@ -79,9 +72,9 @@ The blank template does this in `src/routes/_auth/login.tsx`, `src/routes/verify
 
 **Handing over the app's URL as the MCP URL.** The origin is where the app's pages are. Without `/_softr/mcp` on the end the assistant has nothing to talk to, and the owner is left comparing a URL that looks right against a connection that never works.
 
-**A login that drops `redirect`.** Sign-in works, approval doesn't. The most common break, and silent — test the connect flow signed out, not only signed in.
+**A login that drops the return target.** Sign-in works, approval doesn't. The most common break, and silent — test the connect flow signed out, not only signed in.
 
-**Following `redirect` unchecked, or checked by prefix.** Anything that is not a path on this app is someone else's page, and `/\evil.test` is one of them. Let the URL parser decide, and fall back to `/`.
+**Following the param without `toReturnPath`.** Anything that is not a path on this app is someone else's page, and `/\evil.test` is one of them. A prefix check misses it.
 
 ## References
 

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

@@ -4,12 +4,12 @@ description: >-
   Let visitors install the app on their home screen: SoftrPwaHead for the
   manifest and icon links, usePwaInstall to decide whether to show an install
   button and which platform's steps to show, the PwaInstall and PwaPlatform
-  types, and how to check that the app is installable. The manifest and icon
-  are already served; never write them.
+  types, and how to check that the app is installable. The manifest and icon are
+  already served; never write them.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.64
+  library_version: 0.0.65
 ---
 
 # Installing the app

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

@@ -11,7 +11,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.64
+  library_version: 0.0.65
 ---
 
 **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.64
+  library_version: 0.0.65
 ---
 
 **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.64
+  library_version: 0.0.65
 ---
 
 **Boundary.** `Audience` and `defineVisibility` come from `@softr/sdk` and work anywhere.

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

@@ -13,7 +13,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.64
+  library_version: 0.0.65
 ---
 
 **Boundary.** `defineVisibility`, the access functions and the error predicates come from `@softr/sdk` and work anywhere.
@@ -115,6 +115,12 @@ Every app declares where a denied visitor goes in `softr.json`, at the app root,
 {
   "$schema": "./node_modules/@softr/sdk/schema/softr.schema.json",
   "auth": {
+    "routes": {
+      "login": { "path": "/login", "redirectParam": "redirect" },
+      "resetPassword": { "path": "/reset-password", "tokenParam": "token" },
+      "acceptInvitation": { "path": "/accept-invitation", "tokenParam": "token" },
+      "magicLink": { "path": "/magic-authentication", "tokenParam": "magic-token" }
+    },
     "guard": {
       "unauthenticated": "/login",
       "alreadyAuthenticated": "/",
@@ -124,13 +130,17 @@ Every app declares where a denied visitor goes in `softr.json`, at the app root,
 }
 ```
 
-All three reasons are required, because nothing fills in a reason the file leaves out:
+Every key is required, because nothing fills in one the file leaves out:
 
-| 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 |
+| Reason | Condition | Goes to |
+| --- | --- | --- |
+| `unauthenticated` | Route needs a visitor, none present | `guard.unauthenticated` |
+| `forbidden` | Signed in, in none of the named groups | `guard.forbidden` |
+| `alreadyAuthenticated` | Signed-in visitor on a signed-out-only route | `guard.alreadyAuthenticated` |
+
+`guard.unauthenticated` is where signed-out visitors go. It is usually the same as `routes.login.path`, but it can be another page, such as a public landing page. Every `unauthenticated` redirect, an override's included, carries the page they wanted under `routes.login.redirectParam`. The login page reads it back with `toReturnPath`. See [auth/SKILL.md](../auth/SKILL.md).
+
+`auth.routes` names the app's sign-in pages. To move one, rename its route file and edit its `path` in `auth.routes` to match. When `guard.unauthenticated` points at the login page, edit it too.
 
 That file covers every route at once; a route's own overrides win over it. A rule naming both audiences with no `customGroups` admits everyone, so it never redirects and never throws. Only `strategy: 'throw'` reaches an `errorComponent`. A redirect navigates away and the route never renders.
 
@@ -162,20 +172,22 @@ Use the predicates: `isAccessError` for any of the three, and `isUnauthenticated
 
 ### Run the check and then keep going
 
-`guardRoute` covers almost everything. When a route needs its own logic afterwards, `assertRouteAccess(visibility, context)` applies the same rule and throws the same access error, using the default behaviour for each reason. It takes no overrides.
+`guardRoute` covers almost everything. When a route needs its own logic afterwards, `assertRouteAccess(visibility, opts)` applies the same rule to the whole `beforeLoad` argument and throws the same access error, using the default behaviour for each reason. It takes no overrides.
 
-It also narrows `context.user` for the rest of the handler, where the set names one audience and no other: `User` under `['LOGGED_IN_USERS']`, `null` under `['NON_LOGGED_IN_USERS']`. A set naming both admits either kind of visitor, so it narrows to neither. `guardRoute` cannot, because it hands `beforeLoad` a function rather than running inside one.
+It also narrows `opts.context.user` for the rest of the handler, where the set names one audience and no other: `User` under `['LOGGED_IN_USERS']`, `null` under `['NON_LOGGED_IN_USERS']`. A set naming both admits either kind of visitor, so it narrows to neither. `guardRoute` cannot, because it hands `beforeLoad` a function rather than running inside one.
 
 ```ts
 import { redirect } from '@tanstack/react-router'
 import { assertRouteAccess } from '@softr/sdk'
 
-beforeLoad: ({ context }) => {
-  assertRouteAccess(visibility, context)
-  if (context.user.email.endsWith('@example.com')) throw redirect({ to: '/internal' })
+beforeLoad: (opts) => {
+  assertRouteAccess(visibility, opts)
+  if (opts.context.user.email.endsWith('@example.com')) throw redirect({ to: '/internal' })
 },
 ```
 
+Take `opts` whole. A `context` destructured in the parameter list does not narrow.
+
 Reach for `assertRouteAccess` when the route wants the error thrown for it, `isAuthorized(visibility, context)` when it wants the same narrowing without a throw, and `checkAccess(visibility, context)` when it needs to branch on why. `checkAccess` returns `{ ok: true } | { ok: false, reason }` and throws nothing. All of them are synchronous and make no request.
 
 `guardRoute` and `assertRouteAccess` throw router redirects, so they belong in a route and nowhere else. That is what `Route` in their names marks. `isAuthorized` and `checkAccess` throw nothing and answer anywhere, in a loader, a component or a server function.

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

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