@softr/sdk 0.0.25 → 0.0.26-alpha-0

package/dist/routes/visibility.d.ts

@@ -139,4 +139,4 @@ type VisibilityHandle<R extends RouteVisibility = RouteVisibility> = {
  */
 declare function defineVisibility<const R extends RouteVisibility>(rule: R): VisibilityHandle<R>;
 //#endregion
-export { AccessBehaviour, AccessCheck, AccessError, AccessReason, RouteVisibility, VisibilityHandle, defineVisibility, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError };
+export { defineVisibility, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError };

package/dist/server.d.ts

@@ -1,5 +1,5 @@
 import { auth } from "./auth/server.js";
-import { ds } from "./core/datasource.js";
+import { ds } from "./datasource/datasource.js";
 import { workflow } from "./core/workflow.js";
 import { integration } from "./core/integration.js";
 import "@tanstack/react-start/server-only";

package/dist/server.js

@@ -1,5 +1,5 @@
 import { auth } from "./auth/server.js";
-import { ds } from "./core/datasource.js";
+import { ds } from "./datasource/datasource.js";
 import { workflow } from "./core/workflow.js";
 import { integration } from "./core/integration.js";
 import "@tanstack/react-start/server-only";

package/package.json

@@ -1,15 +1,36 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.25",
+  "version": "0.0.26-alpha-0",
   "type": "module",
   "exports": {
-    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
-    "./client": { "types": "./dist/client.d.ts", "import": "./dist/client.js" },
-    "./server": { "types": "./dist/server.d.ts", "import": "./dist/server.js" },
-    "./vite": { "types": "./dist/vite.d.ts", "import": "./dist/vite.js" }
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "import": "./dist/vite.js"
+    }
+  },
+  "bin": {
+    "softr-sdk": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "!skills/_artifacts"
+  ],
+  "publishConfig": {
+    "access": "public"
   },
-  "files": ["dist", "skills", "!skills/_artifacts"],
-  "publishConfig": { "access": "public" },
   "scripts": {
     "build": "tsdown",
     "test": "node --import ./src/test-utils/setup.ts --test",
@@ -41,7 +62,9 @@
       "optional": true
     }
   },
-  "keywords": ["tanstack-intent"],
+  "keywords": [
+    "tanstack-intent"
+  ],
   "intent": {
     "version": 1,
     "repo": "@softr/sdk",

package/skills/softr-sdk/SKILL.md

@@ -5,9 +5,9 @@ description: >-
   four entrypoints (@softr/sdk, /server, /client, /vite) and the client-server
   boundary between them, softrAuthMiddleware, getSoftrContext,
   initialSoftrContext, SoftrContext, and which sub-skill to load for route
-  visibility, the current user, reading records, writing records, or auth. Load
-  this when unsure which sub-skill applies, or when touching the wiring; each
-  sub-skill stands alone for its own task.
+  visibility, the current user, reading records, charts and metrics, writing
+  records, or auth. Load this when unsure which sub-skill applies, or when
+  touching the wiring; each sub-skill stands alone for its own task.
 metadata:
   type: core
   library: softr-sdk
@@ -21,7 +21,7 @@ metadata:
 > **CRITICAL**: The SDK is split across four entrypoints and the split is enforced. `ds` and `auth` exist only on `@softr/sdk/server` and only run inside a `createServerFn` handler. Importing them anywhere else fails the build.
 > **CRITICAL**: Every route file must declare its audience with `defineVisibility`. There is no default and nothing is inherited from a sibling. A route file without a declaration is a lint error.
 > **CRITICAL**: The app is already wired. `src/start.ts`, `src/router.tsx` and `src/routes/__root.tsx` register the middleware and resolve the session. Do not add a second registration.
-> **CRITICAL**: `workflow.trigger` is exploratory. It exists on the entrypoints below and typechecks, but its endpoint is not final. Do not build a feature on it. Tell the user the capability is not ready and ask how they want to proceed.
+> **CRITICAL**: `workflow.trigger` and `integration.fetch` are exploratory. They exist on the entrypoints below and they typecheck, but their endpoints are not final. Do not build a feature on either of them. Tell the user the capability is not ready and ask how they want to proceed.
 
 Each sub-skill stands alone for its task and repeats the boundary above, so most work needs **one** sub-skill and not this file. Load this one when you are unsure which sub-skill applies, or when the wiring below is what you are touching. Add a second sub-skill only when the work genuinely crosses that boundary: a page that lists records behind a group restriction needs `reading-records` plus `routes-and-visibility`.
 
@@ -29,7 +29,7 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 
 | Import | Runs | Holds |
 | --- | --- | --- |
-| `@softr/sdk` | Both | `defineVisibility`, `q`, `useCurrentUser`, `usePermissions`, `getSoftrContext`, `initialSoftrContext`, `softrAuthMiddleware`, the error predicates, and every type |
+| `@softr/sdk` | Both | `defineAction`, `defineVisibility`, `useCurrentUser`, `usePermissions`, `useUserTimezone`, `getSoftrContext`, `initialSoftrContext`, `softrAuthMiddleware`, the error predicates, and every type |
 | `@softr/sdk/server` | Server only | `ds`, `auth`, `workflow`, `integration` |
 | `@softr/sdk/client` | Browser only | Nothing yet, reserved for browser-only utilities |
 | `@softr/sdk/vite` | Build | `softr()`, already in `vite.config.ts` |
@@ -41,6 +41,7 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 | Add a route, or change who can see one | [routes-and-visibility/SKILL.md](./routes-and-visibility/SKILL.md) |
 | Read the signed-in visitor or what they may do | [current-user/SKILL.md](./current-user/SKILL.md) |
 | Fetch records from a datasource | [reading-records/SKILL.md](./reading-records/SKILL.md) |
+| Chart, aggregate or count records | [charts-and-metrics/SKILL.md](./charts-and-metrics/SKILL.md) |
 | Create, update or delete a record | [data-mutations/SKILL.md](./data-mutations/SKILL.md) |
 | Sign a visitor in, out, or up | [auth/SKILL.md](./auth/SKILL.md) |
 
@@ -56,6 +57,9 @@ Showing the visitor's name, or hiding UI they cannot use?
 Putting records on a page, in a table, a list or a detail view?
   load softr-sdk/reading-records
 
+Drawing a chart, a stat tile, or any aggregated number?
+  load softr-sdk/charts-and-metrics
+
 Submitting a form, editing a record, or deleting one?
   load softr-sdk/data-mutations
 

package/skills/softr-sdk/charts-and-metrics/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: charts-and-metrics
+description: >-
+  Aggregate Softr datasource records inside a server function: ds.chart with
+  groupBy, metrics, where and orderBy for chart rows, ds.metric for a single
+  headline number, date bucket intervals, which aggregations each kind of field
+  offers, the two-group-column ceiling, and distinct values for filter
+  controls. Aggregation only. Listing and fetching records is reading-records.
+metadata:
+  type: sub-skill
+  library: softr-sdk
+  library_version: 0.0.22
+---
+
+This skill builds on softr-sdk, and on reading-records for declaring the action a chart aggregates over.
+
+# Charts and metrics
+
+`ds.chart` groups records and aggregates each group into one row: the data behind a bar chart, a line, a pie. `ds.metric` aggregates everything into one value: the number on a stat tile. Both live on `@softr/sdk/server` and run inside a `createServerFn` handler, and both take the same read action `ds.list` takes, with the same `where` filters.
+
+## Setup
+
+```ts
+import { createServerFn } from '@tanstack/react-start'
+import { defineAction } from '@softr/sdk'
+import { ds } from '@softr/sdk/server'
+
+const sales = defineAction({
+  id: 'sales',
+  datasource: '8f14e45f-ceea-467a-9d0b-2c1a0e3b5d77',
+  operation: 'read',
+  fields: {
+    amount: 'Vk9cXm2pSz6Ld4',   // CURRENCY
+    region: 'fZk3Qm9pLw2Xa1',   // SELECT
+    status: 'Ru7bVx2cNq0Ed9',   // SELECT, choice ids 'paid' | 'open' | 'void'
+    closedAt: 'Xp2dLh6vKz9Fa3', // DATETIME
+    rep: 'Gq5wNt8rJy3Hb1',      // LINKED_RECORD
+  },
+  permission: { userGroup: 'LOGGED_IN_USERS' },
+})
+```
+
+A chart only sees the action's declared fields, so a field to group, aggregate or filter by must be in `fields`.
+
+## Core Patterns
+
+### A bar chart
+
+```ts
+const ordersByRegion = createServerFn().handler(async () => {
+  const { data } = await ds
+    .chart(sales)
+    .groupBy((q) => ({ region: q.region }))
+    .metrics((q) => ({ orders: q.$count }))
+    .orderBy((q) => q.orders.desc)
+  return data
+})
+// data: Array<{ region: string | null; orders: number }>
+```
+
+One row per group, keyed by the names you chose in `groupBy` and `metrics`. `orders` is `number`, not `number | null`: a group that exists holds at least one record. The `null` region is the bucket of records with no value. The result also carries `executionTimestamp: Date`, when the numbers were computed.
+
+A SELECT or LINKED_RECORD group column comes back as the choice's display label, not its id. Labels are user-editable and a `where` on the same field compares ids, so a clicked bar's value cannot be fed straight back into a filter.
+
+### A time series
+
+```ts
+const { data } = await ds
+  .chart(sales)
+  .groupBy((q) => ({ month: q.closedAt.byMonth }))
+  .metrics((q) => ({ revenue: q.amount.sum }))
+  .where((q) => q.status.is('paid'))
+  .orderBy((q) => q.month.asc)
+// data: Array<{ month: string | null; revenue: number | null }>
+```
+
+`q.closedAt` bare groups by the field's value. The bucket leaves hanging off it group a date field by the bucket: `byDay`, `byWeek`, `byMonth`, `byQuarter`, `byYear`, and the cyclic `byHourOfDay`, `byDayOfWeek`, `byMonthOfYear`, `byQuarterOfYear`. What each one holds is in [references/aggregations.md](./references/aggregations.md); `byMonth` reads as `"2025-06"`.
+
+**Sort the time axis ascending yourself.** Left unsorted, rows come back by the first bucket ascending when there is one, else by the first metric descending. A time axis that misses the fallback arrives in value order, which draws a scrambled line rather than failing.
+
+### Spread, not just totals
+
+```ts
+const { data } = await ds
+  .chart(sales)
+  .groupBy((q) => ({ region: q.region }))
+  .metrics((q) => ({
+    smallest: q.amount.min,
+    typical: q.amount.avg,
+    biggest: q.amount.max,
+  }))
+  .orderBy((q) => q.typical.desc)
+```
+
+Any number of metrics in one request, several over the same field included. Each row carries all of them, so one request can feed two panels. A metric key may not reuse a group key, and two metrics may not ask for the same value. `avg` comes back rounded to two decimals.
+
+### Two group columns, which is the ceiling
+
+```ts
+const { data } = await ds
+  .chart(sales)
+  .groupBy((q) => ({ month: q.closedAt.byMonth, region: q.region }))
+  .metrics((q) => ({ revenue: q.amount.sum }))
+  .orderBy((q) => [q.month.asc, q.revenue.desc])
+// data: Array<{ month: string | null; region: string | null; revenue: number | null }>
+```
+
+The result is long format, one row per month and region pair, so the app pivots into one array per series before charting. **A chart groups by at most two columns**, each a different field, and a field cannot be grouped and aggregated in the same chart. A third group column is a compile error.
+
+### Distinct values, for a filter control
+
+```ts
+const { data } = await ds.chart(sales).groupBy((q) => ({ region: q.region }))
+// data: Array<{ region: string | null }>
+```
+
+Skip `metrics` entirely and the rows hold the distinct group values, one each. This is the cheapest way to fill a dropdown from a real column.
+
+### A headline number
+
+```ts
+const { value } = await ds
+  .metric(sales, (q) => q.amount.sum)
+  .where((q) => q.status.is('paid'))
+// value: number | null
+```
+
+One aggregation, no grouping, one value. Whenever the answer is a single number, a stat tile or a count, reach for `ds.metric` rather than a one-row chart: there is nothing to group by and nothing to unpack out of `data`. The same measure handles apply, `q.$count` included:
+
+```ts
+const { value: open } = await ds.metric(sales, (q) => q.$count).where((q) => q.status.is('open'))
+// open: number
+```
+
+### Top N
+
+```ts
+const { data } = await ds
+  .chart(sales)
+  .groupBy((q) => ({ rep: q.rep }))
+  .metrics((q) => ({ revenue: q.amount.sum }))
+  .orderBy((q) => q.revenue.desc)
+
+const top5 = data.slice(0, 5)
+```
+
+A chart has no row limit to set, so a top-N is a client-side slice of the fully sorted rows.
+
+### A dashboard load
+
+```ts
+const loadDashboard = createServerFn().handler(async () => {
+  const [mtd, series] = await Promise.all([
+    ds
+      .metric(sales, (q) => q.amount.sum)
+      .where((q) => q.$and(q.status.is('paid'), q.closedAt.gte('2026-09-01'))),
+    ds
+      .chart(sales)
+      .groupBy((q) => ({ month: q.closedAt.byMonth }))
+      .metrics((q) => ({ revenue: q.amount.sum }))
+      .where((q) => q.status.is('paid'))
+      .orderBy((q) => q.month.asc),
+  ])
+  return { mtd: mtd.value, series: series.data }
+})
+```
+
+Each tile and panel is its own request, fired in parallel from one handler.
+
+## Order of calls
+
+`groupBy` comes first and exactly once; a chart cannot be awaited before it. `metrics` follows, at most once, or not at all for distinct values. `where` can be chained anywhere, repeatedly, and calling it more than once ands the filters together. `orderBy` sorts by the chart's own keys, group and metric alike, and only sees the keys declared so far, so call it last.
+
+## References
+
+- [references/aggregations.md](./references/aggregations.md): every bucket interval and its value type, which aggregations each kind of field offers, and the chart rules
+- [reading-records/SKILL.md](../reading-records/SKILL.md): declaring the action, and the filter operators `where` accepts
+- [reading-records/references/query-builder.md](../reading-records/references/query-builder.md): the full filter matrix

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/data-mutations/SKILL.md

@@ -2,9 +2,10 @@
 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
@@ -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