@softr/sdk 0.0.28 → 0.0.30-alpha.0

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

@@ -0,0 +1,149 @@
+---
+name: record-mutations
+description: >-
+  Create, update and delete records in a Softr datasource with defineMutation,
+  ds.create, ds.update and ds.delete: one declaration per operation, the data
+  payload keyed by your own field names, what each field type accepts on a
+  write, and the record each call returns. Use when submitting a form, saving an
+  edit or deleting a record, or when a write throws, writes the wrong field or
+  silently changes nothing. Writes only: fetching records is record-queries, and
+  aggregating them is charts-and-metrics.
+metadata:
+  type: sub-skill
+  library: softr-sdk
+  library_version: 0.0.29
+---
+
+**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.
+
+# Writing records
+
+`ds` writes records to a Softr datasource, from the server only.
+
+## Setup
+
+```ts
+import { createServerFn } from '@tanstack/react-start'
+import { z } from 'zod'
+import { defineMutation } from '@softr/sdk'
+import { ds } from '@softr/sdk/server'
+```
+
+A write's input arrives from the client, so validate it. Pass a zod schema straight to `.validator`; Start accepts it and types `data` from it.
+
+## Declare the write
+
+A mutation declares exactly one operation, and each of the three needs its own declaration. One datasource carries as many mutations as the app needs, alongside its queries. A create mutation only works with `ds.create`; hand it to `ds.update` and the call throws `action "createProject" is declared as create, not update`.
+
+```ts
+const createProject = defineMutation({
+  id: 'createProject',
+  datasource: '00000000-0000-0000-0000-000000000000',
+  operation: 'create',
+  fields: {
+    name: 'fZk3Qm9pLw2Xa1',    // SINGLE_LINE_TEXT
+    status: 'Ru7bVx2cNq0Ed9',  // SELECT, choice ids 'draft' | 'active' | 'archived'
+    dueDate: 'Xp2dLh6vKz9Fa3', // DATETIME
+  },
+  permission: { userGroup: 'LOGGED_IN_USERS' },
+})
+```
+
+The declaration follows the same rules as a read, spelled out in [record-queries](../record-queries/SKILL.md): `id` reads like a name and is unique across the app, queries counted alongside mutations; `datasource` is the opaque UUID from the table's registration, never derived from its name; the keys of `fields` are names you choose and the values are opaque field ids; `permission` declares who may run the mutation, from the same three choices, and the SDK enforces it; and the object is written inline, because passing it through a variable or a spread widens the field ids and the types stop checking.
+
+The mutation's `fields` bound the write: `data` can only name them, and the returned record only carries them. A delete mutation declares no `fields`, and giving it some is a type error.
+
+## Core Patterns
+
+### Create a record
+
+```ts
+const NewProject = z.object({ name: z.string(), dueDate: z.string() })
+
+const addProject = createServerFn({ method: 'POST' })
+  .validator(NewProject)
+  .handler(async ({ data }) =>
+    ds.create(createProject, {
+      data: { name: data.name, dueDate: data.dueDate, status: { id: 'draft' } },
+    }),
+  )
+```
+
+Returns the created record as `{ id, fields }`, with `fields` keyed by the mutation's names and holding the same value shapes a read returns. Every key in `data` is optional. A field left out, or written as `null`, gets the datasource's default.
+
+### Update a record
+
+```ts
+const updateProject = defineMutation({
+  id: 'updateProject',
+  datasource: '00000000-0000-0000-0000-000000000000',
+  operation: 'update',
+  fields: { status: 'Ru7bVx2cNq0Ed9', dueDate: 'Xp2dLh6vKz9Fa3' },
+  permission: { userGroup: 'LOGGED_IN_USERS' },
+})
+
+const archiveProject = createServerFn({ method: 'POST' })
+  .validator(z.object({ id: z.string() }))
+  .handler(async ({ data }) =>
+    ds.update(updateProject, { id: data.id, data: { status: { id: 'archived' } } }),
+  )
+```
+
+The record id is its own option; keep it out of `data`. An empty `id` throws.
+
+`update` writes the keys in `data` and leaves every other field alone, so a field you leave out is a field you are not writing. On an update, `null` clears the field, where on a create it reached the default. Returns the updated record.
+
+### Delete a record
+
+```ts
+const deleteProject = defineMutation({
+  id: 'deleteProject',
+  datasource: '00000000-0000-0000-0000-000000000000',
+  operation: 'delete',
+  permission: { userGroup: 'LOGGED_IN_USERS' },
+})
+
+const removeProject = createServerFn({ method: 'POST' })
+  .validator(z.object({ id: z.string() }))
+  .handler(async ({ data }) => {
+    await ds.delete(deleteProject, { id: data.id })
+  })
+```
+
+Resolves to nothing. A record that cannot be deleted throws.
+
+### Edit an existing record
+
+An edit form needs both halves: a `defineQuery` to load the record and a `defineMutation` to save it. They are separate declarations over the same table, so give both the fields the form touches, and read the loaded values off the query's names.
+
+```ts
+const projectDetail = defineQuery({
+  id: 'projectDetail',
+  datasource: '00000000-0000-0000-0000-000000000000',
+  fields: { status: 'Ru7bVx2cNq0Ed9', dueDate: 'Xp2dLh6vKz9Fa3' },
+  permission: { userGroup: 'LOGGED_IN_USERS' },
+})
+
+const project = await ds.get(projectDetail, { id })
+await ds.update(updateProject, {
+  id,
+  data: { status: { id: project.fields.status.id } },
+})
+```
+
+A read answers a SELECT as `{ id, label }` and a write takes `{ id }`, so pass the id through rather than the whole value.
+
+### What a write accepts
+
+Each key of `data` accepts exactly what its field takes (see [record-queries](../record-queries/SKILL.md#typing)):
+
+- SELECT and LINKED_RECORD take `{ id }`. Not a bare string, and not the `{ id, label }` a read returns; the label is display data and a write does not accept it. A generated SELECT narrows the id to the field's own choices.
+- CHECKBOX takes a boolean. Dates take ISO strings, never `Date` instances.
+- ATTACHMENT takes `{ url }`, optionally with `filename`, `id` and `type`.
+- A multi-entry field takes an array of the value.
+
+## References
+
+- [record-queries/SKILL.md](../record-queries/SKILL.md): declaring the read half of an edit form, and the codegen the write types come from. Load it alongside this skill for any screen that shows a record before changing it.
+- [record-queries/references/field-types.md](../record-queries/references/field-types.md): the value shape every field reads back as. Load it when you are unsure what a field accepts.
+- [current-user/SKILL.md](../current-user/SKILL.md): reading the visitor off `context`

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

@@ -0,0 +1,163 @@
+---
+name: record-queries
+description: >-
+  Fetch records from a Softr datasource with defineQuery, ds.list and ds.get:
+  the where and orderBy callbacks, field names of your own choosing, the
+  20-record default and 100-record cap, nextOffset pagination, and scoping a
+  read to the signed-in visitor. Use when putting datasource records on a page,
+  in a table, a list or a detail view, when filtering or sorting them, 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.29
+---
+
+**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.
+
+# Reading records
+
+`ds` reads records out of a Softr datasource, from the server only.
+
+## Setup
+
+```ts
+import { createServerFn } from '@tanstack/react-start'
+import { defineQuery } from '@softr/sdk'
+import { ds } from '@softr/sdk/server'
+```
+
+`ds` is server-only. `defineQuery` only declares a read, so it ships on the root entrypoint and the declaration can sit anywhere.
+
+## Declare the read
+
+Every read takes a query: which datasource, which fields, who it is for.
+
+```ts
+const publishedPosts = defineQuery({
+  id: 'publishedPosts',
+  datasource: '00000000-0000-0000-0000-000000000000',
+  fields: {
+    title: 'fZk3Qm9pLw2Xa1',      // SINGLE_LINE_TEXT
+    published: 'Ru7bVx2cNq0Ed9',  // CHECKBOX
+    publishedAt: 'Xp2dLh6vKz9Fa3',// DATETIME
+    views: 'mB4kQ8yTn1sWc7',      // NUMBER
+  },
+  permission: { userGroup: 'ALL_USERS' },
+})
+```
+
+- `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.
+- `datasource` 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`.
+- `permission` 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.
+  - `{ userGroup: 'LOGGED_IN_USERS' }`: any signed-in visitor, narrowed to particular groups with `userGroupIds: ['00000000-0000-0000-0000-00000000000a']`.
+- Write the object inline in the `defineQuery` call. Passing the declaration or its `fields` through a variable, or spreading one in, widens the field ids to `string` and the types stop checking.
+
+A query fixes the table and the columns, not the rows: filters, sorting and paging stay at the call site, because a list screen changes them as the user types. Declare as many queries over one datasource as the app needs, each carrying the fields its own screen touches.
+
+## Core Patterns
+
+### List records
+
+```ts
+const listPublishedPosts = createServerFn().handler(async () => {
+  return await ds
+    .list(publishedPosts)
+    .where((q) => q.published.is(true))
+    .orderBy((q) => q.publishedAt.desc)
+    .limit(50)
+})
+```
+
+Returns `{ records, total, nextOffset }`. Each record is `{ id, fields }`, with `fields` keyed by the query's own names: every declared field is present, `null` when empty, and a field the query does not declare is not returned. `ds.list(publishedPosts)` with no calls chained returns the first 20 records. `limit` is clamped to 100, so more than a hundred records means paginating.
+
+### Filter with the `where` callback
+
+`q` is the argument the callback is handed, not an import. It carries one handle per declared field, offering only the operators that field's type supports, plus `$and` and `$or`:
+
+```ts
+await ds.list(publishedPosts).where((q) =>
+  q.$and(
+    q.published.is(true),
+    q.views.gte(100),
+    q.$or(q.title.contains('cafe'), q.title.startsWith('The')),
+  ),
+)
+```
+
+Calling `.where` more than once ands the filters together, which is how a fixed scope and a user-supplied filter combine. Only the query's own fields can be filtered or sorted on, so a field you need in a `where` belongs in `fields` even when the page never displays it. Load [references/filters-and-sorting.md](./references/filters-and-sorting.md) when you need an operator this page does not show, or when a filter is rejected.
+
+### Sort
+
+```ts
+.orderBy((q) => q.publishedAt.desc)
+.orderBy((q) => [q.views.desc, q.title.asc])   // array for tie-breakers
+```
+
+### Get one record
+
+```ts
+const post = await ds.get(publishedPosts, { id: postId })
+if (post === null) throw notFound()
+```
+
+A record that does not exist comes back as `null`, not an error. A chained `.where` narrows which record the id may resolve to, and a record that does not match reads as `null` too:
+
+```ts
+const post = await ds
+  .get(publishedPosts, { id: postId })
+  .where((q) => q.published.is(true))
+```
+
+There is no `orderBy`, `limit` or `offset` on a get. To find a record by a field instead of its id, use `ds.list` with a `limit` of 1.
+
+### Paginate
+
+```ts
+const first = await ds.list(publishedPosts).limit(50)
+if (first.nextOffset !== null) {
+  const second = await ds.list(publishedPosts).limit(50).offset(first.nextOffset)
+}
+```
+
+`nextOffset` is `null` when there are no more pages. `total` is the count of all matching records, not the count returned.
+
+### Scope the read to the visitor
+
+```ts
+const myInvoices = defineQuery({
+  id: 'myInvoices',
+  datasource: '00000000-0000-0000-0000-000000000001',
+  fields: { owner: 'Gq5wNt8rJy3Hb1', amount: 'Vk9cXm2pSz6Ld4' },
+  permission: { userGroup: 'LOGGED_IN_USERS' },
+})
+
+const listMyInvoices = createServerFn().handler(async ({ context }) => {
+  if (!context.user) throw new Error('Not signed in')
+  const userId = context.user.id
+  return await ds.list(myInvoices).where((q) => q.owner.is(userId))
+})
+```
+
+The SDK enforces `permission`, 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`.
+
+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
+
+`softr-env.d.ts`, the generated file at the app root, types records, filters and sorts from every registered datasource. It follows the data on its own: nothing to run, nothing to edit. It checks the ids you wrote rather than handing them to you, so ask the schema for a field id and open the file only when a declaration will not compile.
+
+
+## References
+
+- [references/filters-and-sorting.md](./references/filters-and-sorting.md): every filter operator by field type, group nesting and the sort handles. Load it when the operator you want is not in this file, or when a filter is rejected.
+- [references/field-types.md](./references/field-types.md): the value shape every Softr field type reads back as. Load it when rendering a field whose shape you are unsure of, or when a value is not the string you expected.
+- [current-user/SKILL.md](../current-user/SKILL.md): reading the visitor off `context` to scope a query
+- [routes-and-visibility/SKILL.md](../routes-and-visibility/SKILL.md): deciding who sees the page the records land on
+- [charts-and-metrics/SKILL.md](../charts-and-metrics/SKILL.md): aggregating records instead of listing them
+- [record-mutations/SKILL.md](../record-mutations/SKILL.md): creating, updating and deleting them

package/skills/softr-sdk/record-queries/references/field-types.md

@@ -0,0 +1,63 @@
+# Softr field types and what their values look like
+
+The generated `softr-env.d.ts` is the authority for your own tables: it types every field of every registered datasource, choice ids included, with the field's name and constraints in a docstring. This reference is the general mapping behind it, for reading a record's values without opening that file.
+
+Three rules cover nullability:
+
+- Every field reads back present, `null` when it is empty. Nothing is optional.
+- A multi-entry field is an array, empty rather than `null`.
+- A `CHECKBOX` is a boolean, `false` rather than `null`.
+
+```ts
+// Strings
+SINGLE_LINE_TEXT, LONG_TEXT, ADDRESS, LOCATION, BUTTON, RECORD_ID: string
+EMAIL, PHONE, URL: string
+DATETIME: string            // ISO timestamp, or an ISO date at date precision
+CREATED_AT, UPDATED_AT: string
+TIME: string                // '09:30:00'
+CREATED_BY, UPDATED_BY: string
+
+// Numbers
+NUMBER, PERCENT, CURRENCY, PROGRESS, DURATION, COUNT, RATING, AUTONUMBER: number
+
+// Booleans
+CHECKBOX: boolean
+
+// Objects. These are NOT plain strings
+SELECT: { id: string; label: string | null }          // generated with literal id and label unions
+LINKED_RECORD: { id: string; label: string | null }   // label is the linked record's primary field
+DATE_RANGE: { from: string; to: string }
+USER: { id: string; name: string; email: string; avatarUrl: string | null }
+ATTACHMENT: {
+  id: string | null
+  filename: string | null
+  type: string | null
+  url: string
+  expiresAt: string | null
+  size?: number
+  thumbnails?: Array<{ size: 'small' | 'medium' | 'large'; url: string }>
+}
+
+// Computed fields read as whatever they return
+FORMULA, LOOKUP, ROLLUP: the returned field's shape, resolved in softr-env.d.ts
+```
+
+Every scalar above is `| null` on the record unless the field allows multiple entries, in which case the value is an `Array<...>` of the scalar.
+
+## The non-obvious ones
+
+**SELECT and LINKED_RECORD** are the most commonly mistyped. They are never a plain string, always an `{ id, label }` object. To display the value, use `.label`. To filter or compare, use `.id`. A generated SELECT narrows both to the field's own choices as literal unions.
+
+```tsx
+// Correct
+<td>{record.fields.status?.label}</td>
+
+// Wrong: status is not a string
+<td>{record.fields.status}</td>
+```
+
+**DURATION** is seconds, whatever format the field displays in.
+
+**DATETIME at date precision** is generated as a `DATE` field and holds `'2026-03-14'`, not a timestamp.
+
+**LOOKUP and FORMULA** take the shape of what they resolve to, so two lookups on one table can have entirely different types. Read the generated type rather than guessing from the field name.

package/skills/softr-sdk/record-queries/references/filters-and-sorting.md

@@ -0,0 +1,146 @@
+# Filters and sorting
+
+Every filter and sort is built inside the callback `where` or `orderBy` hands you. A filter built any other way is rejected at request time.
+
+- [Shape](#shape)
+- [Operators by field type](#operators-by-field-type): [text](#text-fields), [number](#number-fields), [checkbox](#checkbox-fields), [date](#date-fields), [choice](#choice-fields), [multi-value](#multi-value-fields), [user](#user-fields), [attachment and date range](#attachment-and-date-range-fields)
+- [Combining](#combining)
+- [Sorting](#sorting)
+- [Errors](#errors)
+
+## Shape
+
+```ts
+await ds
+  .list(publishedPosts)
+  .where((q) => q.status.is('active'))        // one filter, or a $and/$or of filters
+  .orderBy((q) => q.title.asc)                // or an array of handles
+  .limit(20)                                  // default 20, clamped to 100
+  .offset(null)                               // a previous result's nextOffset
+```
+
+A `where` callback returns exactly one value. For more than one condition, wrap them in `q.$and(...)` or `q.$or(...)`, or call `.where` again: repeated calls are anded.
+
+## Operators by field type
+
+The handle for each field carries the operators its declared type supports, taken from the generated `softr-env.d.ts`.
+
+### Text fields
+
+`SINGLE_LINE_TEXT`, `LONG_TEXT`, `URL`, `EMAIL`, `PHONE`, `ADDRESS`, `LOCATION`, `TIME`, `BUTTON`, `RECORD_ID`.
+
+| Call | Meaning |
+| --- | --- |
+| `.is(value: string)` | Exactly equal |
+| `.isNot(value: string)` | Not equal |
+| `.contains(value: string)` | Substring match |
+| `.startsWith(value: string)` | Prefix match |
+| `.endsWith(value: string)` | Suffix match |
+| `.isOneOf(values: string[])` | Equal to any of |
+| `.isNoneOf(values: string[])` | Equal to none of |
+| `.isEmpty()` / `.isNotEmpty()` | No value / has a value |
+
+### Number fields
+
+`NUMBER`, `PERCENT`, `CURRENCY`, `PROGRESS`, `RATING`, `DURATION`, `COUNT`, `AUTONUMBER`.
+
+| Call | Meaning |
+| --- | --- |
+| `.is(value: number)` / `.isNot(value: number)` | Equal / not equal |
+| `.gt(value)` / `.gte(value)` / `.lt(value)` / `.lte(value)` | Comparisons |
+| `.between(start: number, end: number)` | Inclusive range |
+| `.isEmpty()` / `.isNotEmpty()` | No value / has a value |
+
+### Checkbox fields
+
+| Call | Meaning |
+| --- | --- |
+| `.is(value: boolean)` / `.isNot(value: boolean)` | Equal / not equal |
+| `.isEmpty()` / `.isNotEmpty()` | No value / has a value |
+
+### Date fields
+
+`DATE`, `DATETIME`, `CREATED_AT`, `UPDATED_AT`.
+
+| Call | Meaning |
+| --- | --- |
+| `.is(value: string)` / `.isNot(value: string)` | On / not on that date |
+| `.gt(value)` / `.gte(value)` | After / on or after |
+| `.lt(value)` / `.lte(value)` | Before / on or before |
+| `.between(start, end)` | Inclusive range |
+| `.isNotBetween(start, end)` | Outside the range |
+| `.isEmpty()` / `.isNotEmpty()` | No value / has a value |
+
+Every value is an ISO date string, either `'2026-01-31'` or a full timestamp. A `Date` instance is not accepted. Call `.toISOString()` first.
+
+### Choice fields
+
+`SELECT`, `LINKED_RECORD`, `CREATED_BY`, `UPDATED_BY`.
+
+| Call | Meaning |
+| --- | --- |
+| `.is(value)` / `.isNot(value)` | Equal / not equal |
+| `.isOneOf(values)` / `.isNoneOf(values)` | Any of / none of |
+| `.isEmpty()` / `.isNotEmpty()` | No value / has a value |
+
+Values are choice ids, never labels. A generated SELECT narrows the argument to the field's own choice ids, so a label or a typo is a type error. A LINKED_RECORD compares against the linked record's id.
+
+### Multi-value fields
+
+Any generated type with a `[]` suffix: multi-selects, multi-entry linked records.
+
+| Call | Meaning |
+| --- | --- |
+| `.is(values: string[])` | Exactly this set |
+| `.isOneOf(values: string[])` | Contains at least one of |
+| `.isNoneOf(values: string[])` | Contains none of |
+| `.hasAllOf(values: string[])` | Contains all of |
+| `.isEmpty()` / `.isNotEmpty()` | Empty / non-empty |
+
+Values are the members' ids, as with choice fields.
+
+### User fields
+
+`USER` offers `.is`, `.isNot`, `.contains`, `.isEmpty` and `.isNotEmpty`.
+
+### Attachment and date range fields
+
+`ATTACHMENT` and `DATE_RANGE` have no single value to compare, so they offer only `.isEmpty()` and `.isNotEmpty()`.
+
+## Combining
+
+```ts
+q.$and(...filters)   // all must match
+q.$or(...filters)    // any may match
+```
+
+Both take filters or nested groups:
+
+```ts
+.where((q) =>
+  q.$and(
+    q.status.is('active'),
+    q.$or(q.amount.gte(1000), q.title.contains('priority')),
+  ),
+)
+```
+
+Nesting goes two levels, a group inside a group. A third level throws `Cannot nest filter groups more than three levels deep.` Flatten by distributing the outer condition rather than nesting further.
+
+## Sorting
+
+```ts
+.orderBy((q) => q.title.asc)
+.orderBy((q) => [q.publishedAt.desc, q.title.asc])
+```
+
+Each field carries `.asc` and `.desc` handles and nothing else. An array applies sorts in order. Repeated `.orderBy` calls append.
+
+## Errors
+
+| Message | Cause |
+| --- | --- |
+| `a filter must come from the callback a read hands you` | A `where` value built as a plain object |
+| `a sort must come from the callback a read hands you` | An `orderBy` value not from the callback's `.asc` / `.desc` handles |
+| `Cannot nest filter groups more than three levels deep.` | A group nested one level too far |
+| A `TypeError` reading an operator off `undefined` | Filtering or sorting on a field the query does not declare |

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.28
+  library_version: 0.0.29
 ---
 
 **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.
@@ -57,7 +57,7 @@ defineVisibility({ userGroup: 'NON_LOGGED_IN_USERS' })  // signed-out only: logi
 defineVisibility({ userGroup: 'LOGGED_IN_USERS' })      // any signed-in visitor
 defineVisibility({                                      // those groups only
   userGroup: 'LOGGED_IN_USERS',
-  userGroupIds: ['b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d'],
+  userGroupIds: ['00000000-0000-0000-0000-00000000000a'],
 })
 ```
 
@@ -117,7 +117,7 @@ import { defineVisibility, isAccessError, isForbiddenError } from '@softr/sdk'
 
 const visibility = defineVisibility({
   userGroup: 'LOGGED_IN_USERS',
-  userGroupIds: ['b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d'],
+  userGroupIds: ['00000000-0000-0000-0000-00000000000a'],
 })
 
 export const Route = createFileRoute('/_app/billing')({
@@ -156,5 +156,5 @@ Reach for `assert()` when the route wants the error thrown for it, and `check(co
 ## References
 
 - [current-user/SKILL.md](../current-user/SKILL.md): reading the visitor a guard has just admitted
-- [reading-records/SKILL.md](../reading-records/SKILL.md): a guard covers the page, not the server function behind it
+- [record-queries/SKILL.md](../record-queries/SKILL.md): a guard covers the page, not the server function behind it
 - [auth/SKILL.md](../auth/SKILL.md): `NON_LOGGED_IN_USERS` and the sign-in flow it fronts