@softr/sdk 0.0.24 → 0.0.26-alpha-0

package/skills/softr-sdk/charts-and-metrics/references/aggregations.md

@@ -0,0 +1,76 @@
+# Buckets, aggregations and chart rules
+
+## Group columns
+
+A bare handle in `groupBy` groups by the field's value. What the column reads back as depends on the field's declared type:
+
+| Field type | Column value |
+| --- | --- |
+| SELECT, LINKED_RECORD, CREATED_BY, UPDATED_BY | `string \| null`, the display label, not the id |
+| Text fields | `string \| null` |
+| Number fields | `number \| null` |
+| CHECKBOX | `boolean \| null` |
+| DATE, DATETIME, CREATED_AT, UPDATED_AT | `string \| null`, or a bucket leaf below |
+| Multi-value (`SELECT[]` and friends), ATTACHMENT, DATE_RANGE | Cannot group |
+
+`null` is always the bucket of records with no value. A multi-value field can neither group nor aggregate: exploding it would count each record once per value and inflate every metric.
+
+## Date buckets
+
+Leaves on every date and datetime handle, `q.closedAt.byMonth` style:
+
+| Leaf | Groups by | Column value |
+| --- | --- | --- |
+| `.byDay` | Calendar day | `"2025-06-14"` |
+| `.byWeek` | Calendar week | The ISO date of the week's Monday |
+| `.byMonth` | Calendar month | `"2025-06"` |
+| `.byQuarter` | Calendar quarter | `"Q2 2025"`, a display string, not a parseable date |
+| `.byYear` | Calendar year | The year as a `number` |
+| `.byHourOfDay` | Hour of day | `0`–`23`. DATETIME fields only, not DATE |
+| `.byDayOfWeek` | Day of week | `1`–`7`, 1 is Sunday |
+| `.byMonthOfYear` | Month of year | `1`–`12` |
+| `.byQuarterOfYear` | Quarter of year | `1`–`4` |
+
+Every bucket value is `| null` for the empty bucket. The cyclic buckets come back as bare numbers; the app supplies the labels.
+
+`byWeek` is Monday-based while `byDayOfWeek` counts from Sunday, so the two cannot be lined up by arithmetic alone.
+
+## Aggregations
+
+Handles in `metrics`, and the second argument of `ds.metric`:
+
+| Handle | Available on | Comes back as |
+| --- | --- | --- |
+| `.sum` | Number fields | `number \| null` |
+| `.avg` | Number fields | `number \| null`, rounded to two decimals |
+| `.min` / `.max` | Number fields | `number \| null` |
+| `.min` / `.max` | Date fields | `string \| null`, as `"2025-06-14"` |
+| `.distinct` | Number and date fields | `number`, the count of distinct values |
+| `q.$count` | No field: counts rows | `number` |
+
+Number fields: NUMBER, PERCENT, CURRENCY, PROGRESS, RATING, DURATION, COUNT, AUTONUMBER. Date fields: DATE, DATETIME, CREATED_AT, UPDATED_AT.
+
+Every other field offers no aggregations at all. `q.$count` is the only measure that touches no field, so a text or choice column is measured by grouping on it and counting rows.
+
+`sum`, `avg`, `min` and `max` are `null` for a group with no values. `$count` and `distinct` are plain `number`.
+
+## Rules
+
+- `groupBy` takes one or two columns, is required, and is called once. A third column, and a chart with no group columns, are compile errors.
+- Each group column is a different field, and a field cannot be grouped and aggregated in the same chart.
+- `metrics` is optional and called at most once. A metric key may not reuse a group key, and two metrics may not ask for the same aggregation of the same field.
+- `orderBy` names the chart's own keys, group and metric alike. Call it last: it only sees keys already declared.
+- Left unsorted, rows come back by the first bucket column ascending; with no bucket, by the first metric descending; with neither, by the first group ascending.
+- There is no row limit. A top-N is a client-side `slice` of the sorted rows.
+
+## Errors
+
+| Message | Cause |
+| --- | --- |
+| `a chart needs at least one column to group by` | Awaiting a chart whose `groupBy` produced no columns |
+| `a chart may group by at most two columns` | Three or more group columns, on an untyped action |
+| `a chart may group by a field only once` | The same field twice in `groupBy` |
+| `a field cannot be grouped and aggregated in one chart` | One field in both `groupBy` and `metrics` |
+| `two metrics ask for the same value` | The same aggregation of the same field under two keys |
+| `"..." is not a column of this chart` | An `orderBy` key that is neither a group nor a metric key |
+| `a chart column must come from the callback a chart hands you` | A hand-built object where a handle belongs |

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

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.24
+  library_version: 0.0.25
 ---
 
 **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/data-mutations/SKILL.md

@@ -2,13 +2,14 @@
 name: data-mutations
 description: >-
   Create, update and delete records in a Softr datasource from inside a server
-  function: ds.create, ds.update and ds.delete from @softr/sdk/server, the data
-  payload key, select field aliasing on the way in and out, and what each call
-  returns or throws. Writes only. Reads, metrics and chart data are not covered.
+  function: declaring a write with defineAction, ds.create, ds.update and
+  ds.delete from @softr/sdk/server, the data payload keyed by the action's
+  aliases, what each field type accepts on a write, and the record each call
+  returns. Writes only. Reads, charts and metrics are not covered.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.24
+  library_version: 0.0.25
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `q` 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.
@@ -22,93 +23,101 @@ metadata:
 ```ts
 import { createServerFn } from '@tanstack/react-start'
 import { z } from 'zod'
+import { defineAction } from '@softr/sdk'
 import { ds } from '@softr/sdk/server'
-import { q } from '@softr/sdk'
 ```
 
-Pass a zod schema straight to `.validator`. Start accepts it and types `data` from it.
+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.
 
-Every `ds` call names its datasource by an 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 never derived from the table's name. Field ids are opaque too (`fZk3Qm9pLw2Xa1`, not `fld_<name>`) and come from the table's schema.
+## Declare the write
 
-**The datasource id must be a string literal at the call site.**
+Every `ds` call takes an action, and an action declares one operation. A create action 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 = defineAction({
+  id: 'createProject',
+  datasource: 'c9a51f22-3b8e-4d17-a6c0-5e92d84b7f31',
+  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 action, spelled out in [reading-records](../reading-records/SKILL.md): `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; everything sits at module scope with every property a literal.
+
+The action's `fields` bound the write: `data` can only name them, and the returned record only carries them. A delete action declares no `fields`; giving it some is a type error.
 
 ## Core Patterns
 
 ### Create a record
 
 ```ts
-const NewProject = z.object({ name: z.string(), status: z.string() })
+const NewProject = z.object({ name: z.string(), dueDate: z.string() })
 
-const createProject = createServerFn({ method: 'POST' })
+const addProject = createServerFn({ method: 'POST' })
   .validator(NewProject)
   .handler(async ({ data }) =>
-    ds.create('8ffb4814-b028-4496-b679-7face2167ebc', {
-      data,
-      select: q.select({ name: 'fZk3Qm9pLw2Xa1', status: 'Ru7bVx2cNq0Ed9' }),
+    ds.create(createProject, {
+      data: { name: data.name, dueDate: data.dueDate, status: { id: 'draft' } },
     }),
   )
 ```
 
-Resolves to `{ id, fields }`, and on a Softr table `fields` holds **only the keys you wrote** — not the rest of the record. See "What a write answers with" below.
-
-**The payload key is `data`, not `fields`.** A record answers with `fields`, which is where the confusion comes from, but the option you pass is `data`. `CreateOptions` requires it, so a call keyed by `fields` does not type-check.
-
-**`data` speaks whatever `select` maps.** The keys above are the schema's own names because `select` maps them to field ids, which is why the validated input can go straight through. With no `select`, `data` has to be keyed by raw field ids instead.
+Returns the created record as `{ id, fields }`, with `fields` keyed by the action'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 Rename = z.object({ id: z.string(), name: z.string() })
-
-const renameProject = createServerFn({ method: 'POST' })
-  .validator(Rename)
+const updateProject = defineAction({
+  id: 'updateProject',
+  datasource: 'c9a51f22-3b8e-4d17-a6c0-5e92d84b7f31',
+  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('8ffb4814-b028-4496-b679-7face2167ebc', {
-      id: data.id,
-      data: { name: data.name },
-      select: q.select({ name: 'fZk3Qm9pLw2Xa1' }),
-    }),
+    ds.update(updateProject, { id: data.id, data: { status: { id: 'archived' } } }),
   )
 ```
 
-The record id is its own option, so keep it out of `data`.
-
-`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. An empty `id` throws.
-
-### What a write answers with
-
-`create` and `update` resolve to `{ id, fields }`, but `fields` is **not the record**. On a Softr table it carries only the keys you sent, aliased through `select`; a status change answers with `{ id, fields: { status } }` and nothing else. (Other datasource types may answer with more. Rely on neither.)
+The record id is its own option; keep it out of `data`. An empty `id` throws.
 
-So the answer is a receipt, not a replacement for what the page holds. Putting it where a loader-fetched record was blanks every column you did not write. Two honest ways to show the result:
-
-- **A quick change to one field** — a status select, a card dragged to another column, an archive toggle — is optimistic: change that one field in your own state immediately, keep the rest of the record as the loader gave it, save in the background, and on a rejected write restore the old value with a clear message. Do not `router.invalidate()` or re-fetch after a successful write; the local change is already what the user sees.
-- **A saved form, or anything that changes several fields**, refreshes the route's data — `router.invalidate()`, see `@tanstack/router-core#router-core/data-loading` — so the list or detail re-reads through its own `select`.
-
-Do not re-read the one record with `ds.get` for either: it takes no `select`, so it answers with raw field ids.
-
-### Writing a choice field
-
-A `SELECT` or `LINKED_RECORD` field reads back as `{ id, label }` (see [field-types](../reading-records/references/field-types.md)). Writing one accepts the option's `id`, its `label`, or `{ id, label }`, matched case-insensitively.
-
-**A value that matches no option is not an error — it silently adds a new option to the field.** A typo'd label leaves a junk choice in the schema. So write `{ label }` (or the `{ id, label }` you read), copy labels from the table's schema verbatim, and never invent one.
+`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 RecordId = z.object({ id: z.string() })
-
-const deleteProject = createServerFn({ method: 'POST' })
-  .validator(RecordId)
-  .handler(async ({ data }) => ds.delete('8ffb4814-b028-4496-b679-7face2167ebc', data.id))
+const deleteProject = defineAction({
+  id: 'deleteProject',
+  datasource: 'c9a51f22-3b8e-4d17-a6c0-5e92d84b7f31',
+  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 })
+  })
 ```
 
-**`delete` takes the record id as a positional argument**, unlike `create` and `update`, which take an options object. It resolves to nothing.
+Resolves to nothing. A record that cannot be deleted throws.
 
-### Naming fields with `select`
+### What a write accepts
 
-`select` works in both directions on a write. Going in, it turns your names into Softr field ids. Coming back, it turns the returned field ids into your names. Without it, `data` has to be keyed by raw field ids and the returned record answers with them too.
+With `softr-env.d.ts` in place (see [reading-records](../reading-records/SKILL.md#typing)), each key of `data` accepts exactly what its field takes:
 
-The map has to cover every key in `data`. A key it does not map is not translated, so the write does not land on the field you meant.
+- 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.
 
 ### Writing on behalf of the visitor
 
@@ -116,6 +125,16 @@ Stamping a record with who created it, or scoping an update to the person making
 
 ## Failure Modes
 
+**A write with the wrong action.** Each operation needs an action declared for it. `ds.update` with a read action throws `action "..." is declared as read, not update` at the first call, not at build time.
+
+**A payload keyed `fields`.** The option is `data`. A record answers with `fields`, which is where the confusion comes from, but the option you pass is `data`, and the options type requires it.
+
+**A SELECT or LINKED_RECORD written as a bare string.** The write shape is `{ id }`. Writing `status: 'archived'` where `status: { id: 'archived' }` belongs is a type error with codegen in place and a silent misfire without it.
+
+**Feeding a read value back into a write.** A read returns `{ id, label }`; a write takes `{ id }` only. Strip the label before writing the value back.
+
+**A field missing from the action.** `data` can only name the action's own `fields`. A field you need to write must be declared on the action, and a delete action declares none.
+
 **A datasource id built from a name.** `'ds_projects'`, the table id, or the table's name glued to a uuid are not datasource ids. The id is the opaque UUID assigned when the table was registered on the application; copy it from there. Anything else fails at request time as not found or forbidden.
 
 **A datasource id stored in a variable.** Pass the UUID as a string literal directly at the call site. The lint rule `@softr/ds-no-computed-id` catches this at development time.
@@ -134,5 +153,6 @@ Stamping a record with who created it, or scoping an update to the person making
 
 ## References
 
-- [reading-records/SKILL.md](../reading-records/SKILL.md): fetching the record a write is about to change
+- [reading-records/SKILL.md](../reading-records/SKILL.md): declaring actions, fetching the record a write is about to change, and the codegen the types come from
+- [reading-records/references/field-types.md](../reading-records/references/field-types.md): the value shape every field reads back as
 - [current-user/SKILL.md](../current-user/SKILL.md): reading the visitor off `context` to stamp or scope a write

package/skills/softr-sdk/reading-records/SKILL.md

@@ -1,16 +1,15 @@
 ---
 name: reading-records
 description: >-
-  Fetch records from a Softr datasource inside a server function: ds.list and
-  ds.get from @softr/sdk/server, the q query builder (q.text, q.number,
-  q.boolean, q.date, q.array, q.and, q.or, q.asc, q.desc), q.select field
-  aliasing, filtering, sorting, the 20-record default and 100-record cap, and
-  nextOffset pagination. Reads only. Mutations, workflows, integrations, metrics
-  and chart data are not covered.
+  Fetch records from a Softr datasource inside a server function: declaring a
+  read with defineAction, ds.list and ds.get from @softr/sdk/server, the where
+  and orderBy callbacks, field aliases, the 20-record default and 100-record
+  cap, and nextOffset pagination. Reads only. Mutations, workflows,
+  integrations, charts and metrics are not covered.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.24
+  library_version: 0.0.25
 ---
 
 **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. `q` 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.
@@ -23,53 +22,37 @@ metadata:
 
 ```ts
 import { createServerFn } from '@tanstack/react-start'
+import { defineAction } from '@softr/sdk'
 import { ds } from '@softr/sdk/server'
-import { q } from '@softr/sdk'
 ```
 
-Every `ds` call names its datasource by an 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 it is never derived from the table's name — `'ds_posts'` or a name glued to a uuid fails at request time as not found or forbidden.
+`ds` is server-only. `defineAction` only declares data operations, so it ships on the root entrypoint and the declaration can sit anywhere.
 
-**The datasource id must be a string literal at the call site.** Do not assign it to a variable and pass the variable. Write the UUID directly as the first argument:
+## Declare the read
 
-```ts
-// correct
-ds.list('8ffb4814-b028-4496-b679-7face2167ebc', { ... })
-
-// wrong
-const POSTS = '8ffb4814-b028-4496-b679-7face2167ebc'
-ds.list(POSTS, { ... })
-```
-
-A record comes back as `{ id: string; fields: Record<string, unknown> }`. When you write a TypeScript type for the fields, the shape of each value depends on the Softr field type — see [references/field-types.md](./references/field-types.md) for the full mapping.
-
-## Typing record fields
-
-Declare a local type for the records you fetch using `SoftrRecord<Fields>`. Use the shapes from the field-types reference, not guesses from the field name. The most common mistake is treating SELECT and LINKED_RECORD fields as strings — they are objects:
+Every `ds` call takes an action: which datasource, which fields, who may run it.
 
 ```ts
-import type { SoftrRecord } from '@softr/sdk'
-
-type Product = SoftrRecord<{
-  name: string                            // SINGLE_LINE_TEXT
-  price: number | null                    // CURRENCY
-  category: { id: string; label: string } // SELECT — not a string
-  supplier: { id: string; label: string } // LINKED_RECORD — not a string
-}>
+const publishedPosts = defineAction({
+  id: 'publishedPosts',
+  datasource: '8ffb4814-b028-4496-b679-7face2167ebc',
+  operation: 'read',
+  fields: {
+    title: 'fZk3Qm9pLw2Xa1',      // SINGLE_LINE_TEXT
+    published: 'Ru7bVx2cNq0Ed9',  // CHECKBOX
+    publishedAt: 'Xp2dLh6vKz9Fa3',// DATETIME
+    views: 'mB4kQ8yTn1sWc7',      // NUMBER
+  },
+  permission: { userGroup: 'ALL_USERS' },
+})
 ```
 
-`SoftrRecord<Fields>` is shorthand for `{ id: string; fields: Fields }` — the `Fields` type parameter constrains every value to `JsonValue`, so TypeScript rejects non-serializable types like `Date` objects.
-
-Cast at the `ds.list` call using the `ListResult` generic so the type flows through the loader automatically:
+- `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. `'ds_posts'` or a name glued to a uuid fails at request time as not found or forbidden.
+- The keys of `fields` are names you choose. The values are field ids, opaque strings copied from `softr-env.d.ts` (see [Typing](#typing)) or the table's schema. Everything downstream speaks your names: the returned records, `where`, `orderBy`.
+- `permission` declares who may run the action.
+- Declare at module scope, every property a literal. The build reads the declaration without executing it, so a computed id, a shared constant or a spread does not work.
 
-```ts
-import type { ListResult, SoftrRecord } from '@softr/sdk'
-
-const fetchProducts = createServerFn().handler(() =>
-  ds.list('3c1e8a52-6f0d-4b7e-9a21-5d84c0f7b2e6', { select, limit: 100 }) as Promise<ListResult<Product>>
-)
-```
-
-`loaderData` is then already typed as `ListResult<Product>` — no second cast needed in the component. All the shapes in [references/field-types.md](./references/field-types.md) satisfy the `JsonValue` constraint.
+An action 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.
 
 ## Core Patterns
 
@@ -77,73 +60,62 @@ const fetchProducts = createServerFn().handler(() =>
 
 ```ts
 const listPublishedPosts = createServerFn().handler(async () => {
-  return await ds.list('8ffb4814-b028-4496-b679-7face2167ebc', {
-    select: q.select({
-      title: 'fZk3Qm9pLw2Xa1',
-      author: 'mB4kQ8yTn1sWc7',
-      published: 'Ru7bVx2cNq0Ed9',
-      publishedAt: 'Xp2dLh6vKz9Fa3',
-    }),
-    where: q.boolean('published').is(true),
-    orderBy: q.desc('publishedAt'),
-    limit: 50,
-  })
+  return await ds
+    .list(publishedPosts)
+    .where((q) => q.published.is(true))
+    .orderBy((q) => q.publishedAt.desc)
+    .limit(50)
 })
 ```
 
-Returns `{ records, total, nextOffset }`. `ds.list(POSTS)` on its own returns the first 20 records with their raw field ids. `limit` defaults to 20 and is clamped to 100. A larger number is silently reduced, so more than a hundred records means paginating.
-
-**Filtering or sorting requires a `select`, and it has to cover every field you name.** `where` and `orderBy` speak aliases, so without a map to translate through they throw at request time. That is why `published` is in the map above even though the table never displays it.
+Returns `{ records, total, nextOffset }`. Each record is `{ id, fields }`, with `fields` keyed by the action's own names: every declared field is present, `null` when empty, and a field the action does not declare is not returned. `ds.list(publishedPosts)` with no calls chained returns the first 20 records. `limit` is clamped to 100; a larger number is silently reduced, so more than a hundred records means paginating.
 
-### Name the fields with `select`
+### Filter with the `where` callback
 
-Softr field ids are opaque strings (`fZk3Qm9pLw2Xa1`), copied from the table's schema. `q.select` maps your own names onto them, and those names are what the rest of the call speaks:
+The callback is handed one handle per declared field, carrying only the operators that field's type supports, plus `$and` and `$or`:
 
 ```ts
-const select = q.select({ title: 'fZk3Qm9pLw2Xa1', views: 'Ru7bVx2cNq0Ed9' })
-
-await ds.list('8ffb4814-b028-4496-b679-7face2167ebc', {
-  select,
-  where: q.number('views').gt(100),   // alias, not Ru7bVx2cNq0Ed9
-  orderBy: q.asc('title'),            // alias here too
-})
-// records[0].fields is { title: ..., views: ... }
+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')),
+  ),
+)
 ```
 
-Once `select` is present it is the whole vocabulary. The returned record carries exactly those keys, and any field you filter or sort on must appear in the map.
+Calling `.where` more than once ands the filters together, which is how a fixed scope and a user-supplied filter combine. Only the action's own fields can be filtered or sorted on; a field you need in a `where` must be in the action's `fields`, even when the page never displays it. The full operator matrix is in [references/query-builder.md](./references/query-builder.md).
 
-### Get one record
+### Sort
 
 ```ts
-const post = await ds.get('8ffb4814-b028-4496-b679-7face2167ebc', { id: postId })
-if (post === null) throw notFound()
+.orderBy((q) => q.publishedAt.desc)
+.orderBy((q) => [q.views.desc, q.title.asc])   // array for tie-breakers
 ```
 
-A record that does not exist comes back as `null`, not an error.
+### Get one record
 
-The type also accepts `{ where }` instead of `{ id }`, but there is no way to pass a `select` alongside it, so the filter cannot be translated and the call throws. Fetch one record by id, or use `ds.list` with a `limit` of 1 when you need to find it by a field.
+```ts
+const post = await ds.get(publishedPosts, { id: postId })
+if (post === null) throw notFound()
+```
 
-### Filter with `q`
+A record that does not exist comes back as `null`, not an error. A chained `.where` narrows which record the id may resolve to. A record that does not match reads as `null`, the same as one that does not exist:
 
 ```ts
-where: q.and(
-  q.text('status').is('active'),
-  q.number('amount').gte(100),
-  q.or(
-    q.text('owner').is(user.id),
-    q.array('collaborators').hasAllOf([user.id]),
-  ),
-)
+const post = await ds
+  .get(publishedPosts, { id: postId })
+  .where((q) => q.published.is(true))
 ```
 
-Five field types, `q.text`, `q.number`, `q.boolean`, `q.date` and `q.array`, combined with `q.and` and `q.or`. The full operator matrix is in [references/query-builder.md](./references/query-builder.md).
+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('8ffb4814-b028-4496-b679-7face2167ebc', { limit: 50 })
+const first = await ds.list(publishedPosts).limit(50)
 if (first.nextOffset !== null) {
-  const second = await ds.list('8ffb4814-b028-4496-b679-7face2167ebc', { limit: 50, offset: first.nextOffset })
+  const second = await ds.list(publishedPosts).limit(50).offset(first.nextOffset)
 }
 ```
 
@@ -152,13 +124,18 @@ if (first.nextOffset !== null) {
 ### Scope the read to the visitor
 
 ```ts
+const myInvoices = defineAction({
+  id: 'myInvoices',
+  datasource: 'e4b7c2a1-9d3f-4e68-b05a-7f1c6d2e8a93',
+  operation: 'read',
+  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')
-
-  return await ds.list('e4b7c2a1-9d3f-4e68-b05a-7f1c6d2e8a93', {
-    select: q.select({ owner: 'Gq5wNt8rJy3Hb1', amount: 'Vk9cXm2pSz6Ld4' }),
-    where: q.text('owner').is(context.user.id),
-  })
+  const userId = context.user.id
+  return await ds.list(myInvoices).where((q) => q.owner.is(userId))
 })
 ```
 
@@ -168,9 +145,16 @@ A server function is its own endpoint, reachable whether or not the visitor ever
 
 A read the visitor is not allowed to make 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
+
+Records, filters and sorts are typed from `softr-env.d.ts`, the generated file at the app root describing every datasource registered on the application. Regenerate it with `npx @softr/sdk generate` after the data changes. With it in place, field ids autocomplete inside `fields`, each `where` handle offers only its field's operators, and `records[0].fields` carries real value types with no cast anywhere. Without it everything still runs, but field values type as `unknown` and every handle offers every operator.
+
+What each Softr field type reads back as is in [references/field-types.md](./references/field-types.md). The two most commonly mistyped: SELECT and LINKED_RECORD values are `{ id, label }` objects, never plain strings. Render the `label`; filter by the `id`.
+
 ## References
 
-- [references/field-types.md](./references/field-types.md): TypeScript shape for every Softr field type
-- [references/query-builder.md](./references/query-builder.md): every `q` field type and operator
+- [references/query-builder.md](./references/query-builder.md): every filter operator, by field type
+- [references/field-types.md](./references/field-types.md): the value shape every Softr field type reads back as
 - [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