softr-vibe-coding 1.11.2 → 2.1.0

package/datasources/reading.md

@@ -56,7 +56,15 @@ var isRefetching = result.isRefetching;
 var items = (data && data.pages) ? data.pages.flatMap(function(p) { return p.items; }) : [];
 ```
 
-**CRITICAL:** Only ONE `useRecords` call per block. Fetch all data in one call and filter client-side. Multiple `useMetric` calls ARE allowed.
+**CRITICAL:** Only ONE `useRecords` call **per datasource**. Fetch that table's data in one call and filter client-side. Multiple `useMetric` calls ARE allowed.
+
+**CRITICAL:** The options object must be an **inline literal** at the call site. Passing it
+through a variable or a wrapper function (`useRecords(buildOpts())`) **fails to compile** —
+verified live 2026-08-25, hit in a production block; the fix was changing the wrapper to take
+the hook's *result* instead. Share `q.select` mappings between hooks, never whole options
+objects.
+
+A block can connect to **several data sources** and call `useRecords` once per source — declare them with `datasource.define()` and pass `from:` on every hook. See [multi-datasource.md](multi-datasource.md). (This replaces the old one-table-per-block limit; blocks no longer need an invisible helper block just to read a second table.)
 
 ### Loading All Records (Auto-Pagination)
 
@@ -97,7 +105,7 @@ var result = useLinkedRecords({
   sortOrder: "ASC",     // "ASC" | "DESC"
   search: "",           // optional search string
   enabled: true,        // defer loading until needed
-  count: 50,
+  count: 50,            // optional page size — default 100, max 1000
 });
 
 var options = (result.data && result.data.pages) ? result.data.pages.flatMap(function(p) { return p.items; }) : [];
@@ -126,8 +134,9 @@ var statusOptions = useFieldOptions({
 
 // statusOptions → { options: [...], isLoading: bool }
 // statusOptions.options → [{ id: "sel...", label: "Active", color: "greenLight1" }, ...]
-//   id    — the option's UUID, used in mutate payloads
-//   label — display string
+//   id    — stable option id (use as a React key; NOT needed in mutate payloads — SELECT
+//           fields write by LABEL string on the current platform, verified 2026-08-25)
+//   label — display string AND the value to write in mutate payloads
 //   color — Airtable swatch color name (optional; handy for tinting chips)
 ```
 
@@ -143,8 +152,8 @@ same `select` object can be shared by both. Reuse one `select` for many fields a
 
 **When to use this vs. hardcoding:**
 
-- **Use `useFieldOptions`** when option IDs / labels could change post-deploy — selects with rapidly-evolving lists, user-editable choices, or any case where re-pasting blocks for an option rename is annoying. Cross-table case: to render a select field from table B inside a block bound to table A (e.g. an intake form bound to Jobs that needs the Wigs `Color` options), put the `useRecords` + `useFieldOptions` in a hidden helper block bound to table B and publish the options to a `window` global (see [helper-blocks.md](../references/helper-blocks.md)).
-- **Hardcode** when the option set is stable and frequently referenced (e.g. a status enum that drives a state machine), so the IDs live in source and rename-safety is enforced by greppable constants. A robust middle ground: prefer the live options, fall back to a hardcoded list per field so the UI still renders if the helper hasn't published yet.
+- **Use `useFieldOptions`** when option labels could change post-deploy — selects with rapidly-evolving lists, user-editable choices, or any case where re-pasting blocks for an option rename is annoying. Since SELECT fields write by label (verified 2026-08-25), live options also keep write payloads rename-proof: render and write `option.label`. Hardcoded labels remain fine as a display-only loading fallback while the live options fetch. Cross-table case: to render a select field from table B inside a block bound to table A (e.g. an intake form bound to Jobs that needs the Wigs `Color` options), put the `useRecords` + `useFieldOptions` in a hidden helper block bound to table B and publish the options to a `window` global (see [helper-blocks.md](../references/helper-blocks.md)).
+- **Hardcode** when the option set is stable and frequently referenced (e.g. a status enum that drives a state machine), so the label vocabulary lives in source and rename-safety is enforced by greppable constants. A robust middle ground: prefer the live options, fall back to a hardcoded list per field so the UI still renders if the helper hasn't published yet.
 
 `useFieldOptions` is the read-side equivalent of using `useLinkedRecords` for foreign records — it abstracts away the field's option store. Items are shaped `{ id, label, color }` (note: `label`, not `title` like `useLinkedRecords`).
 
@@ -196,9 +205,22 @@ import { useCurrentUser } from "@/lib/user";
 var user = useCurrentUser();
 // Returns null if not logged in
 // Fields: { id, fullName, firstName, lastName, email, avatar } (all string or null)
+// Note: `id` is only present when user sync is enabled.
+```
+
+**Custom user-record fields** are first-class: pass a `properties` map (aliased like a `select` query) and read them under `user.properties`:
+
+```jsx
+var user = useCurrentUser({
+  properties: {
+    stripeId: "FIELD_ID1",
+    plan: "FIELD_ID2",
+  },
+});
+// user.properties.stripeId, user.properties.plan
 ```
 
-**For user groups, role, or custom fields** -- use `window.__softr_current_user` (NOT `useCurrentUser()`):
+**For user groups / role ONLY** -- these are not exposed by `useCurrentUser()` (not even via `properties`); use `window.__softr_current_user`:
 
 ```jsx
 var softrUser = window.__softr_current_user || {};

package/datasources/rest-api.md

@@ -100,6 +100,24 @@ export default function Block() {
 - Softr injects the authentication headers configured in the data source automatically
 - API keys are **never exposed** in client-side code
 - The response is the raw API JSON -- access fields directly (e.g., `item.name`, not `record.fields.name`)
+- **The proxy only supports text payloads** -- streams, `FormData`, and file uploads won't work. Serialize request bodies as JSON/text.
+
+### Multiple datasources
+
+When the block has more than one datasource, `useProxyFetch` needs to know which source to route through. Unlike the record hooks (which take a `from:` option), it takes the alias as its **function argument**:
+
+```jsx
+import { datasource, useProxyFetch } from "@/lib/datasource";
+
+var ds = datasource.define({
+  store: "ds_id_1",     // the REST API datasource
+  orders: "ds_id_2",    // e.g. a Softr DB table alongside it
+});
+
+var proxyFetch = useProxyFetch(ds.store);   // alias as ARGUMENT, not from:
+```
+
+With a single datasource `useProxyFetch()` works with no argument; once there's more than one, omitting the alias **throws**. Define the aliases with `datasource.define`, the same pattern the record hooks use — see [multi-datasource.md](multi-datasource.md).
 
 ### Dynamic Query Parameters
 
@@ -124,7 +142,7 @@ var result = useQuery({
 
 ### POST Requests
 
-`proxyFetch` accepts the same options as standard `fetch`:
+`proxyFetch` accepts the same options as standard `fetch`, but bodies must be text (JSON strings etc.) — `FormData`, streams, and file uploads are not supported by the proxy:
 
 ```jsx
 var result = useQuery({
@@ -172,6 +190,7 @@ fetch("https://workflows-api.softr.io/v1/workflows/WORKFLOW_ID/executions/EXECUT
 
 - Supports GET and POST methods only in the data source connector (no PUT, PATCH, DELETE -- use Softr Action buttons with custom API call actions for those)
 - Response data must be parseable JSON
+- **Proxy payloads are text-only** -- streams, `FormData`, and file uploads through `proxyFetch` fail. For file-to-record uploads use `useUpload` (see [writing.md](writing.md#file-uploads)), which targets the connected record datasource; uploading files to an arbitrary external API needs a different mechanism (e.g. a Softr workflow / webhook receiver)
 - No 2-way user sync
 - Requires Business or Enterprise plan
 

package/datasources/shared-patterns.md

@@ -4,6 +4,7 @@ These patterns apply to all data sources that use `useRecords` + `q.select()` (e
 
 | Topic | Guide |
 |---|---|
+| **Multiple data sources in one block** — `datasource.define()`, the `from:` parameter, getting the datasource UUIDs | [multi-datasource.md](multi-datasource.md) |
 | Query builder, useRecords, useRecord, useLinkedRecords, filtering, sorting, pagination, current user, metrics, chart data | [reading.md](reading.md) |
-| Record mutations (create/update/delete), file uploads, linked record format, cross-table REST API writes | [writing.md](writing.md) |
+| Record mutations (create/update/delete), sequential multi-row write queues, file uploads, linked record format, cross-table writes | [writing.md](writing.md) |
 | `getFieldValue()` helper, field type shapes, record structure, debug utilities (Field Inspector, User Inspector) | [fields.md](fields.md) |

package/datasources/softr-database.md

@@ -8,7 +8,7 @@ No setup needed. Softr Database is available by default in every Softr app. Crea
 
 ## AI-Assisted Workflows
 
-Softr publishes an official MCP server (`https://mcp.softr.io/mcp`) that lets the AI read Softr DB schema and field IDs directly — eliminating the manual "paste `tablespace-with-tables` JSON" step. For setup, scopes, the 20 tools, and the limitation that this only covers Softr DB (not external sources), see [../references/softr-database-mcp.md](../references/softr-database-mcp.md).
+Softr publishes an official MCP server (`https://mcp.softr.io/mcp`) that lets the AI read Softr DB schema and field IDs directly — eliminating the manual "paste `tablespace-with-tables` JSON" step. The same server can also browse connected Airtable / Google Sheets / Notion / Supabase integrations, and can create and deploy Vibe Coding blocks. For setup, permissions, and the full tool catalog, see [../references/softr-mcp.md](../references/softr-mcp.md).
 
 ## Vibe Coding Field IDs
 Field IDs are short alphanumeric codes (e.g., `"xgETy"`, `"TLhWF"`). These codes are NOT human-readable names.
@@ -23,7 +23,7 @@ q.select({ name: "First Name" })
 
 Find field IDs in this order of preference:
 
-1. **Softr Database MCP** (recommended when working with an AI assistant) — the AI calls schema/list-fields tools directly. See [../references/softr-database-mcp.md](../references/softr-database-mcp.md).
+1. **Softr MCP server** (recommended when working with an AI assistant) — the AI calls schema/list-fields tools directly. See [../references/softr-mcp.md](../references/softr-mcp.md).
 2. **`get-softr-database` CLI script (bundled)** — a Python CLI bundled with this skill at `~/.claude/skills/softr-vibe-coding/tools/get-softr-database.py`. Exports the full schema (every table, field, dropdown option UUID) to `~/Desktop/softr-database-<id>-<timestamp>.json`. Stdlib only, no `pip install`. See [Bundled CLI script](#bundled-cli-script-get-softr-database) below.
 3. **Network inspector** — DevTools -> Network -> filter `tablespace-with-tables` for the full schema including dropdown option UUIDs. Paste the JSON into chat to share with an AI when the MCP isn't installed.
 4. **Inline in Studio** — click a field's name in the Data tab; the ID appears in the field-edit drawer.
@@ -86,11 +86,11 @@ After `source ~/.zshrc`, just run `get-softr-database <database_id>` from anywhe
 |----------------|----------|-------|
 | Text           | Yes      | |
 | Number         | Yes      | |
-| Date           | Yes      | |
+| Date           | Yes      | Date-semantics fields take `"yyyy-MM-dd"`; timestamp fields take `new Date().toISOString()` (verified 2026-08-25) |
 | File / Image   | Yes      | |
 | Checkbox       | Yes      | |
-| Dropdown       | Yes      | |
-| Relationship   | Yes      | Linked records to other Softr Database tables |
+| Dropdown       | Yes      | Write the option **LABEL string**, exactly matching a defined choice (verified 2026-08-25; supersedes the old option-UUID rule). See [writing.md](writing.md#dropdown--single-select-softr-database) |
+| Relationship   | Yes      | Linked records to other Softr Database tables. Write as an **array of record-id strings**, e.g. `[recordId]` (verified 2026-08-25) |
 | Formula        | Read-only | Booleans return as strings: use `=== "1"` for true, `=== "0"` for false |
 
 ## Rate Limits
@@ -98,7 +98,7 @@ No API rate limits. Softr Database queries run internally without external API c
 
 ## Gotchas
 - **Formula boolean values are strings.** A formula that evaluates to true returns `"1"`, not `true`. Always compare with `=== "1"` or `=== "0"`.
-- **Field IDs are opaque codes.** You cannot guess them from column names. Use the Field Inspector block to find them.
+- **Field IDs are opaque codes.** You cannot guess them from column names. Look them up via the ranked list above (MCP `list_fields` / bundled CLI / network inspector / Studio field drawer) — the generic Field Inspector block does NOT work for Softr Database.
 - **Relationships** work similarly to linked records in Airtable but use Softr's internal record IDs.
 
 ## Best For

package/datasources/writing.md

@@ -1,11 +1,12 @@
 # Writing Data
 
-Record mutations, file uploads, linked record format, and cross-table operations.
+Record mutations, sequential write queues, file uploads, linked record format, and cross-table operations.
 
 ## Table of Contents
 
 - [How Actions Work (Studio's Actions Tab)](#how-actions-work-studios-actions-tab)
 - [Record Mutations](#record-mutations)
+- [Sequential Multi-Row Writes (mutateAsync)](#sequential-multi-row-writes-mutateasync)
 - [File Uploads](#file-uploads)
 - [Linked Record Format for Mutations](#linked-record-format-for-mutations)
 - [Writing to Field Types](#writing-to-field-types)
@@ -23,6 +24,13 @@ Each Action's "FIELDS USED" list mirrors the aliases in your `q.select()` mappin
 - Cosmetic AND structural code edits both update the Action automatically -- you do NOT need to re-prompt the AI assistant after editing code
 - There is no manual delete control; to remove an Action, remove the mutation hook from the code
 
+**⚠️ Every recompile resets Action permissions (verified live 2026-08-25).** Each code
+recompile/redeploy re-registers the block's auto-derived Actions with **default permissions** —
+any per-Action permission tightening done in the Actions tab is wiped. Deployment-order
+implication: do the Actions-tab tightening pass only AFTER the last redeploy of a block, and
+re-check every tightened block after any future redeploy. Hit across a 15-block production
+deployment; treat it as standing platform behavior, not a one-off.
+
 The `enabled` boolean on a mutation hook is a combined signal — it's `true` only when BOTH conditions are met:
 
 1. **The Action was successfully derived from the code** (parser side). Causes of failure here:
@@ -65,6 +73,11 @@ if (createRecord.enabled) {
 }
 ```
 
+**Create payloads are FLAT — no `{ fields }` wrapper** (verified live 2026-08-25). The payload's
+keys are the aliases from the hook's `fields:` q.select, at the top level. This is deliberately
+asymmetric with `useRecordUpdate`, whose payload nests them: `{ recordId, fields: { ... } }`.
+Wrapping a create payload in `fields:` is a wrong shape — don't copy it from an update call.
+
 ### useRecordUpdate
 
 ```jsx
@@ -85,38 +98,31 @@ updateRecord.mutate({
 });
 ```
 
-#### CRITICAL: Two parser requirements for `useRecordUpdate`
-
-Softr's Action parser is strict about both the **method name** and the **payload shape**. Get either wrong and the Action is never derived, `enabled` stays `false`, and any UI gated on it silently does nothing — no error, no warning, console just shows `enabled: false, error: null, status: "idle"`.
+#### CRITICAL: The `useRecordUpdate` payload shape (and the retired `.mutate()`-only rule)
 
-**Requirement 1 — Call `.mutate()`, NOT `.mutateAsync()`.** The parser scans for the literal `.mutate(` token to detect mutation call sites. `.mutateAsync()` runs fine at runtime (it's just a Promise wrapper), but the parser ignores it and no Update Action gets created. Pass per-call success/error handlers as the second argument (react-query convention):
-
-```jsx
-// CORRECT — parser sees `.mutate(`, derives the Action
-updateRecord.mutate(
-  { recordId: id, fields: { status: optionId } },
-  {
-    onSuccess: function() { toast.success("Saved"); },
-    onError: function(err) { toast.error(err.message); },
-  }
-);
-
-// WRONG — parser ignores `.mutateAsync(`, Action never created
-updateRecord.mutateAsync({ recordId: id, fields: { status: optionId } })
-  .then(function() { toast.success("Saved"); });
-```
-
-**Requirement 2 — Payload must be `{ recordId, fields: {...} }` — not flat.** Field values must be nested inside a `fields: {...}` object. The flat form (`mutate({ recordId, status: "active" })`) can succeed at runtime, but the parser doesn't see field references inside it, so no Action is derived:
+**Payload must be `{ recordId, fields: {...} }` — not flat.** Field values must be nested inside a `fields: {...}` object. The flat form (`mutate({ recordId, status: "active" })`) can succeed at runtime, but Softr's Action parser doesn't see field references inside it, so no Update Action is derived — `enabled` stays `false`, the UI gated on it silently does nothing, and Studio's Actions tab shows "No actions used in this block yet":
 
 ```jsx
 // CORRECT
-updateRecord.mutate({ recordId: id, fields: { status: optionId } }, { onSuccess, onError });
+updateRecord.mutate({ recordId: id, fields: { status: "Active" } }, { onSuccess, onError });
 
 // WRONG — Action parser ignores this, hook stays disabled
-updateRecord.mutate({ recordId: id, status: optionId }, { onSuccess, onError });
+updateRecord.mutate({ recordId: id, status: "Active" }, { onSuccess, onError });
 ```
 
-Verified by direct experiment (May 2026): Softr's Studio AI assistant emits both `.mutate()` AND the nested payload shape — and that combination is what produces a derived Update Action. Switching either back to its alternative form (`.mutateAsync()` or flat payload) disables the hook.
+Note the asymmetry: **update payloads nest under `fields:`, create payloads are flat** (no wrapper). Verified live 2026-08-25.
+
+**`.mutateAsync()` is fully supported (verified live 2026-08-25 — supersedes the old rule).**
+Until mid-2026 this skill documented that the Action parser only recognized the literal
+`.mutate(` token, and that any mutation written as `.mutateAsync(...)` produced no derived
+Action (verified by direct experiment, May 2026, on the then-current platform). The current
+platform derives Actions for `mutateAsync` call sites too — a 15-block production deployment
+built its entire multi-row write layer on `await hook.mutateAsync(...)` with Actions deriving
+correctly on every block. Use `.mutate(payload, { onSuccess, onError })` for fire-and-forget
+single writes; use `await .mutateAsync(payload)` when the code must sequence writes or branch
+on the result (see [Sequential Multi-Row Writes](#sequential-multi-row-writes-mutateasync)).
+If you're maintaining an old app where an Action refuses to derive, the legacy `.mutate(`-only
+parser is worth checking before deeper debugging.
 
 ### useRecordDelete
 
@@ -153,18 +159,75 @@ var createFields = q.select({ name: "FIELD_1", email: "FIELD_2" });
 var updateFields = q.select({ name: "FIELD_1", email: "FIELD_2" });
 ```
 
+## Sequential Multi-Row Writes (mutateAsync)
+
+`await hook.mutateAsync(...)` is the tool for any save that writes several rows in a required
+order — a header record followed by its line items, a source record followed by ledger rows, a
+batch of rows that must stop cleanly on the first failure. Verified live 2026-08-25: this
+pattern carried every multi-row save in a 15-block production deployment.
+
+The battle-tested queue shape:
+
+```tsx
+// Track queue state in component state so a failure is renderable and resumable.
+// { phase: "idle" | "saving" | "failed" | "done", failedIndex: number | null }
+
+async function saveAll() {
+  setQueue({ phase: "saving", failedIndex: null });
+
+  // 1. Header first — its id links every line.
+  const header = await createHeader.mutateAsync({ name, date });   // create payloads are FLAT
+  if (!header?.id) throw new Error("Header created without an id");
+
+  // 2. Lines in order. STOP on the first failure; never re-issue completed writes.
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].saved) continue;                 // resume support: skip completed rows
+    try {
+      await createLine.mutateAsync({ header: [header.id], product: lines[i].product, qty: lines[i].qty });
+      markSaved(i);
+    } catch (err) {
+      setQueue({ phase: "failed", failedIndex: i });   // render the failed line + a Retry button
+      return;
+    }
+  }
+  await refetch();                                // refresh affected queries BEFORE toasting
+  setQueue({ phase: "done", failedIndex: null });
+  toast.success("Saved");
+}
+```
+
+Rules that make this safe:
+
+- **Header first, then lines in order.** Await each write; never fire the loop in parallel and
+  never chain with nested `.then()` callbacks.
+- **Stop on failure, keep the queue.** Render the failed row with its error and a Retry button;
+  Retry re-runs only the failed write and resumes the remainder. Completed writes are never
+  re-issued.
+- **Guard against ambiguous failures.** A failed *response* doesn't prove a failed *write* (the
+  server may have committed and the response been lost). Before a Retry re-writes, re-fetch the
+  already-written child rows for that header and skip any the server already has — this is what
+  makes the queue double-write-proof.
+- **Guard the created id.** If a create resolves without an id, throw — don't write lines linked
+  to `undefined`.
+- **Gate the whole flow on the hooks' `enabled` booleans**, same as any mutation UI.
+
 ## File Uploads
 
 ```jsx
 import { useUpload } from "@/lib/datasource";
 
 var upload = useUpload();
+// Returns { uploadAsync, isUploading } — use isUploading to disable the submit
+// button / show a spinner while the upload is in flight:
+//   <Button disabled={upload.isUploading || !file}>...
 
 // Single file:
 upload.uploadAsync(file).then(function(results) {
   var result = results[0];
   if (result.status === "completed") {
     // result.url = uploaded file URL, result.file.name = original filename
+  } else {
+    toast.error((result.error && result.error.message) || "Upload failed");
   }
 });
 
@@ -176,10 +239,19 @@ upload.uploadAsync(file).then(function(results) {
       name: "Document",
       attachment: { filename: result.file.name, url: result.url },
     });
+  } else {
+    toast.error((result.error && result.error.message) || "Upload failed");
   }
 });
+
+// Multiple files: uploadAsync accepts an array; filter the completed results.
+upload.uploadAsync(Array.from(e.target.files)).then(function(results) {
+  var completed = results.filter(function(r) { return r.status === "completed"; });
+});
 ```
 
+Always handle the non-`"completed"` branch — a failed result carries `result.error?.message` for the toast.
+
 ### Async/await style
 
 The official Softr Vibe Coding docs use this form; it's more ergonomic when uploading inside a larger async flow:
@@ -188,81 +260,91 @@ The official Softr Vibe Coding docs use this form; it's more ergonomic when uplo
 var [result] = await upload.uploadAsync(file);
 if (result.status === "completed") {
   createRecord.mutate(
-    { fields: { attachment: { filename: result.file.name, url: result.url } } },
+    { attachment: { filename: result.file.name, url: result.url } },   // create payload is FLAT
     { onSuccess: function() { toast.success("Saved"); } }
   );
 }
 ```
 
-**Stick with `.mutate(...)` even inside async functions** — don't switch to `.mutateAsync(...)` just for the await ergonomics. Softr's Action parser only recognizes the `.mutate(` token, so any mutation written as `.mutateAsync(` produces no derived Action and `enabled` stays `false` (see "Two parser requirements for `useRecordUpdate`" below).
+Inside a larger async flow, `await createRecord.mutateAsync({ attachment: ... })` works just as
+well — `mutateAsync` is fully supported on the current platform (verified 2026-08-25; see the
+supersession note under `useRecordUpdate` above).
 
 ## Linked Record Format for Mutations
 
+Write linked-record fields as an **array of record-id strings** (verified live 2026-08-25 on
+Softr Database — every cross-table link in a 15-block production deployment used this shape):
+
 ```jsx
-// CORRECT -- Array of { id } objects
+// CORRECT -- array of record-id strings, even for a single link
 createRecord.mutate({
-  parentAccount: [{ id: "RECORD_ID_1" }],
-  teamMembers: [{ id: "MEMBER_1" }, { id: "MEMBER_2" }],
+  parentAccount: ["RECORD_ID_1"],
+  teamMembers: ["MEMBER_1", "MEMBER_2"],
 });
 
-// WRONG -- Plain string or array of strings
-parentAccount: "RECORD_ID_1"           // Won't work
-teamMembers: ["MEMBER_1"]              // Won't work
+// WRONG -- bare string, not wrapped in an array
+parentAccount: "RECORD_ID_1"
 ```
 
+**Legacy / Airtable note.** This skill previously documented arrays of `{ id }` objects
+(`teamMembers: [{ id: "MEMBER_1" }]`), verified May 2026 on Airtable-backed blocks. The
+string-array shape is the verified current form on Softr Database; if a linked-record write
+fails on an Airtable-backed block, try the `[{ id }]` object shape before deeper debugging.
+
 ## Writing to Field Types
 
 Different Softr field types accept different value shapes in mutation payloads. The shape returned when you READ a field is often different from the shape you must SEND when you WRITE.
 
 ### Dropdown / Single Select (Softr Database)
 
-Write the option's UUID as a **plain string**, not an object:
+Write the option's **LABEL string** — it must exactly match a defined choice on the field. No
+option-UUID discovery step is needed:
 
 ```jsx
-// CORRECT -- plain string UUID
+// CORRECT -- the option's display label, exactly as defined
 createRecord.mutate({
-  status: "822b8d69-3af4-47b4-90eb-3a80c5d1b85c",
+  status: "Active",
 });
 
 // WRONG -- object form (returned on read, but rejected on write)
 createRecord.mutate({
   status: { id: "822b8d69-3af4-47b4-90eb-3a80c5d1b85c", label: "Active" },
 });
-
-// WRONG -- display label
-createRecord.mutate({
-  status: "Active",
-});
 ```
 
-Option UUIDs are stable. Three ways to retrieve them:
+Verified live 2026-08-25 (Softr Database, `useRecordCreate` AND `useRecordUpdate`): every
+controlled-vocabulary SELECT write in a 15-block production deployment wrote label strings
+(`"Tier 1"`, `"Prospect"`, `"Physical count correction"`, ...) with no UUID discovery step.
 
-- **AI scaffolding** -- Softr's AI assistant in Studio inlines them automatically into `<SelectItem value="...">` when generating a form
-- **Network inspector** -- DevTools -> Network -> filter `tablespace-with-tables` returns the full `choices` array for any SELECT field (see [fields.md](fields.md#field-inspector-block) for the full technique). Pasting this JSON into an AI assistant chat is the most reliable way to share UUIDs without transcription errors.
-- **Runtime scan** -- learn them at runtime from already-loaded records (useful when the block must work in environments where UUIDs are not known at code time)
+The label must match a defined choice character-for-character — a typo fails the write, so
+keep vocabularies as greppable constants, or fetch them live with `useFieldOptions` (see
+[reading.md](reading.md#usefieldoptions----fetch-singlemulti-select-choices)) and write
+`option.label`.
 
-Verified by direct experiment (April 2026) for `useRecordCreate`. The same pattern is expected to apply to `useRecordUpdate` but has not been independently verified.
+**Legacy note.** Until mid-2026 this skill documented the opposite — write the option UUID,
+labels rejected (verified April 2026 on the then-current platform). If a label write is
+rejected on an old app, the UUID form is the thing to try; on the current platform it is not
+needed.
 
 ### Linked Record
 
-Array of `{ id }` objects. See "Linked Record Format for Mutations" above.
+Array of record-id **strings** (`["RECORD_ID"]`) on Softr Database (verified 2026-08-25); the legacy / Airtable fallback shape is `[{ id }]` objects. See "Linked Record Format for Mutations" above.
 
 ### Multi-Select
 
-Array of option UUIDs as plain strings — mirrors Single Select but wrapped in an array:
+Expected: array of option **label strings** — mirrors Single Select (which writes by label,
+verified 2026-08-25) but wrapped in an array:
 
 ```jsx
-// CORRECT
-createRecord.mutate({ tags: ["uuid-1", "uuid-2"] });
+// EXPECTED
+createRecord.mutate({ tags: ["Urgent", "Internal"] });
 
 // WRONG -- {id, label} objects (returned on read, rejected on write)
 tags: [{ id: "uuid-1", label: "Urgent" }]
-
-// WRONG -- display labels
-tags: ["Urgent", "Internal"]
 ```
 
-_Inferred from the read shape (see [fields.md](fields.md)); verify by experiment before production use._
+_Not independently verified — inferred from the verified single-select label behavior; verify by
+experiment before production use. (The pre-2026-08 platform took option-UUID arrays instead.)_
 
 ### Number
 
@@ -296,7 +378,10 @@ createRecord.mutate({ dueDate: "2025-03-15" });
 createRecord.mutate({ lastSeenAt: "2025-03-15T14:00:00Z" });
 ```
 
-_Inferred from the read shape (see [fields.md](fields.md)); verify by experiment before production use._
+Verified live 2026-08-25 (Softr Database): DATETIME fields with **date semantics** (a due date,
+a distribution date) take the `"yyyy-MM-dd"` form; **timestamp** fields (`*_at` audit fields)
+take `new Date().toISOString()`. Writing a full timestamp into a date-semantics field invites
+timezone-shift bugs — compare and display such fields on the `yyyy-MM-dd` slice.
 
 ### Date Range
 
@@ -333,16 +418,37 @@ To upload a file before writing it to a record, see [File Uploads](#file-uploads
 
 _Shape matches the example shown in [File Uploads](#file-uploads). Not yet independently verified across all data sources._
 
-### Text / Email / URL / Phone
+### Text / Email / URL
 
 Plain string. To clear a value, both `null` and `""` work for Softr Database text fields (verified by direct experiment, May 2026, for `useRecordUpdate`). Behavior on other data sources has not been independently verified.
 
+### Phone
+
+**Unformatted international format only**: `+` followed by digits — nothing else (e.g. `+12125550100`). Some datasources (Monday.com is the one the official guide names) reject values containing spaces, dashes, or parentheses. Strip all non-digit characters except the leading `+` before submitting (official sanitizer from the developer guide):
+
+```tsx
+const sanitizePhone = (raw: string) => raw.replace(/[^\d+]/g, "").replace(/(?!^)\+/g, "");
+
+mutate({ phone: sanitizePhone(inputValue) });
+```
+
+Any form block with a phone input should sanitize before `mutate()` — never send the user's typed formatting through.
+
 ## Cross-Table Operations
 
-`useRecordCreate`, `useRecordUpdate`, and `useRecordDelete` only work with the block's configured datasource. Two paths to write across tables:
+**The default path is multi-datasource (supersedes the REST-API-first guidance that used to live
+here).** A block can connect to several data sources at once — declare them with
+`datasource.define({ alias: "uuid", ... })` and pass `from: ds.alias` on every hook, including
+the mutation hooks. Reading two tables and writing a third from one block needs no helper
+block, no REST API, and no exposed key. Required reading:
+[multi-datasource.md](multi-datasource.md). Verified at scale 2026-08-25: a 15-block production
+deployment routed all of its cross-table writes (header + ledger + audit-log rows) through
+`from:`-scoped mutation hooks.
+
+Two remaining alternatives, for the cases multi-datasource doesn't cover:
 
-- **For Airtable backends** — usually cleanest to write to the block's own table and let an Airtable automation script handle the cascade. See [../references/airtable-automations.md](../references/airtable-automations.md). Keeps the block simple, avoids exposing an API key in the browser, and lets cross-table logic live next to the data.
-- **Softr Database REST API via `fetch()`** — the only option for non-Airtable sources, and the right choice when an automation cycle would be too slow. Details below.
+- **For Airtable backends** — when the cascade logic is heavy, write to the block's own table and let an Airtable automation script handle the cascade. See [../references/airtable-automations.md](../references/airtable-automations.md). Keeps the block simple and lets cross-table logic live next to the data.
+- **Softr Database REST API via `fetch()`** — a fallback for what the hooks can't express (e.g. writes from outside a Vibe block, or admin tooling that must bypass block bindings). Details below.
 
 **Base URL:** `https://tables-api.softr.io/api/v1/databases/{databaseId}/tables/{tableId}/records`
 
@@ -358,4 +464,4 @@ Notes:
 - Use `fieldNames=true` on GET for human-readable field names
 - Rate limits: Reads 40 req/s, Writes 30 req/s
 
-Verified by direct experiment (May 2026): POST to this endpoint with field IDs as keys writes successfully, returning HTTP 200 and the full record JSON. The endpoint uses the same field-ID format and the same value shapes as `useRecordCreate` -- plain string UUID for dropdown writes; the response returns the dropdown value as a `{id, label}` object (matching the read shape).
+Verified by direct experiment (May 2026): POST to this endpoint with field IDs as keys writes successfully, returning HTTP 200 and the full record JSON. At that time the endpoint took plain string UUIDs for dropdown writes, and the response returned the dropdown value as a `{id, label}` object (matching the read shape). Note: that observation predates the 2026-08-25 finding that the **in-block hooks** write SELECTs by label — the REST endpoint is a separate surface and may still expect UUIDs; re-verify whichever shape you use here.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "softr-vibe-coding",
-  "version": "1.11.2",
+  "version": "2.1.0",
   "description": "Claude Code skill for generating production-ready Softr Vibe Coding blocks (JSX). Installs into ~/.claude/skills/ and auto-updates on each Claude Code session.",
   "bin": {
     "softr-vibe-coding": "./bin/cli.js"

package/references/airtable-automations.md

@@ -2,7 +2,7 @@
 
 Companion reference for Softr Vibe Coding blocks. Many Softr blocks talk to an Airtable backend, and some flows can't be done from the block side — most commonly **cross-table writes triggered by a record change** (the block can only write to its own configured data source). For those, the right tool is an Airtable Automation Script, written in JavaScript and triggered by Airtable's automation runner.
 
-This guide covers Airtable's two scripting environments + Airtable formulas. **It is NOT about Softr Vibe Coding** — runtime, API surface, and gotchas are entirely different. Don't apply Softr block rules (no `?.`, shadow DOM, etc.) here.
+This guide covers Airtable's two scripting environments + Airtable formulas. **It is NOT about Softr Vibe Coding** — runtime, API surface, and gotchas are entirely different. Don't apply Softr block rules (shadow DOM isolation, data-hook constraints, etc.) here.
 
 ## When to reach for an Airtable script vs. a Softr block