softr-vibe-coding 1.12.0 → 2.1.0

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.12.0",
+  "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
 

package/references/anti-patterns.md

@@ -16,7 +16,7 @@ Run through this catalog before delivering any block. Every row is a violation o
 | Hardcoding API keys for connected API | Use `useProxyFetch` -- key stays server-side |
 | Using `q.select({})` to dump all fields on Softr Database | Returns record IDs with empty `fields: {}`. Look up field IDs in Studio's Data tab, or use the Softr DB REST API with `fieldNames=true` |
 | Building an invisible helper block + `window` globals just to read a second table | A block can connect to **multiple data sources**. Declare them with `datasource.define({ alias: "uuid" })` and pass `from: ds.alias` on every hook. One block instead of two, no page-order dependency, no mount-timing race. See [datasources/multi-datasource.md](../datasources/multi-datasource.md). Helper blocks remain correct for genuinely cross-*block* jobs (triggering another block, sharing computed state) — just not for plain multi-table reads |
-| Omitting `from:` on a hook when the block has more than one datasource | Throws at runtime. `from:` is optional ONLY when exactly one source is connected — then hooks default to it. Applies to `useRecords`, `useRecord`, `useLinkedRecords`, `useFieldOptions`, `useMetric`, `useChartData`, `useRecordCreate`, `useRecordUpdate`, `useRecordDelete`. NOT to `useUpload` / `useCurrentRecordId`, which are app-level |
+| Omitting `from:` on a hook when the block has more than one datasource | Throws at runtime. `from:` is optional ONLY when exactly one source is connected — then hooks default to it. Applies to `useRecords`, `useRecord`, `useLinkedRecords`, `useFieldOptions`, `useMetric`, `useChartData`, `useRecordCreate`, `useRecordUpdate`, `useRecordDelete`. NOT to `useUpload` / `useCurrentRecordId`, which are app-level. `useProxyFetch` has the same multi-datasource requirement but takes the alias as its **argument** — `useProxyFetch(ds.store)` — not as `from:` |
 | Hoisting datasource ids into constants: `datasource.define({ people: PEOPLE_DS_ID })` | Fails to compile — *"datasource.define() object values must be string literals."* Softr statically analyses the call, same as `q.select()`. Keep the UUIDs **inline**: `datasource.define({ people: "74d2cbfd-…" })`. Fails fast with an explicit message, but hoisting magic strings is a strong reflex — resist it here |
 | Asking Studio's AI chat "what are the datasource IDs?" and pasting the answer | **It fabricates them.** Verified July 2026: asked three times for the same three connected tables, it gave three different UUID sets, once reusing a previously-mentioned table's uuid for a different table — all confidently worded, none hedged. Ask it to **write code** instead (*"write a datasource.define call covering every connected source, plus one useRecords per source, code only"*) — scaffolding is bound to the real connections. Then RUN it: real rows under each heading proves each alias maps where you think. A wrong uuid fails safe (matches nothing → error); a *swapped pair* of valid uuids does not |
 
@@ -25,15 +25,19 @@ Run through this catalog before delivering any block. Every row is a violation o
 | Anti-Pattern | Correct Approach |
 |---|---|
 | `.mutate({ id: ... })` | `.mutate({ recordId: ... })` -- `id` causes 404 |
-| `updateRecord.mutate({ recordId, status: "..." })` — flat payload | `updateRecord.mutate({ recordId, fields: { status: "..." } })` — fields **must** be nested. The flat form can run at runtime but Softr's Action parser doesn't see field references inside it, so the derived Update Action never gets created. The hook's `enabled` stays `false`, the Save button never lights up, the Actions tab in Studio shows "No actions used in this block yet" — all with no error, no warning. The symptom is a button that does nothing and a console log showing `enabled: false, error: null, status: "idle"`. Use the nested form for EVERY mutate call, even single-field updates. See [datasources/writing.md](../datasources/writing.md#critical-two-parser-requirements-for-userecordupdate) |
-| `updateRecord.mutateAsync(payload).then(...).catch(...)` | `updateRecord.mutate(payload, { onSuccess, onError })` — Softr's Action 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 — no Action gets derived, `enabled` stays `false`, the Actions tab shows "No actions used in this block yet". This is the same silent-failure mode as the flat-payload anti-pattern, and the two often appear together because devs reach for `mutateAsync` to chain `.then()/.catch()`. The fix is to use `.mutate(payload, { onSuccess, onError })` — per-call handlers go in the second argument (react-query convention). Verified by direct experiment, May 2026. See [datasources/writing.md](../datasources/writing.md#critical-two-parser-requirements-for-userecordupdate) |
+| `updateRecord.mutate({ recordId, status: "..." })` — flat payload | `updateRecord.mutate({ recordId, fields: { status: "..." } })` — fields **must** be nested. The flat form can run at runtime but Softr's Action parser doesn't see field references inside it, so the derived Update Action never gets created. The hook's `enabled` stays `false`, the Save button never lights up, the Actions tab in Studio shows "No actions used in this block yet" — all with no error, no warning. The symptom is a button that does nothing and a console log showing `enabled: false, error: null, status: "idle"`. Use the nested form for EVERY update call, even single-field updates (create payloads are flat — see the dedicated row below). See [datasources/writing.md](../datasources/writing.md#critical-the-userecordupdate-payload-shape-and-the-retired-mutate-only-rule) |
+| Sequencing multi-row saves with nested `.then()/.catch()` chains, or firing the rows in parallel | `await hook.mutateAsync(row)` per row, in order — header first, then lines; stop on the first failure with renderable retry state; never re-issue completed writes. `mutateAsync` is **fully supported** on the current platform (verified live 2026-08-25 — this supersedes the May 2026 finding that the Action parser only recognized the literal `.mutate(` token; that limitation is gone, and is worth checking only when maintaining an old app whose Action refuses to derive). Full queue pattern: [datasources/writing.md](../datasources/writing.md#sequential-multi-row-writes-mutateasync) |
 | Assuming `mutation.enabled === false` always means a code bug | `enabled` is BOTH a parser signal AND a permissions signal. Per the official Softr docs, "`enabled` reflects user permissions." When code looks correct and the Actions tab shows the action listed, the cause is almost always permissions. Test by switching "Preview as" in Studio to an Owner / admin; if it then works, the issue is permissions. Three places to check, in priority order: (1) the block's **Visibility** tab (right panel), (2) **Studio → Users → Data Restrictions → Global data restrictions** — an app-wide layer that easily gets overlooked because it's hidden under Users (not on the block); it overlays every block in the app, and a single restriction on the target table will silently disable every mutation against that table for the affected user group, (3) the data-source PAT scope — if granted read-only, every write fails regardless of UI permissions. See [datasources/writing.md](../datasources/writing.md#how-actions-work-studios-actions-tab) |
 | `deleteRecord.mutate({ id: r.id })` | `deleteRecord.mutate(r.id)` -- just the string |
-| `var { mutateAsync } = useRecordUpdate({...})` | `var updateRecord = useRecordUpdate({...})` -- keep full object for `.enabled`, `.status`, `.reset()` |
+| `var { mutateAsync } = useRecordUpdate({...})` -- destructuring the mutate function off the hook | `var updateRecord = useRecordUpdate({...})` -- keep the full object so `.enabled`, `.status`, `.reset()` stay reachable (using `.mutateAsync` itself is fine) |
 | Not calling `refetch()` after mutations | Always `refetch()` in `onSuccess` |
 | Including read-only fields (formula / rollup / aiText / lookup / createdTime / lastModifiedTime / autoNumber) in the `fields` q.select passed to `useRecordCreate` or `useRecordUpdate` | Softr's Action parser silently rejects the **entire** create/update Action — not just the bad alias. Same all-or-nothing failure mode as a renamed/missing column: Studio's Actions tab shows "No actions used in this block yet", `createRecord.enabled` / `updateRecord.enabled` stays `false`, `.mutate()` calls dispatch but resolve to "not yet ready", every OTHER writable field in the same q.select is also lost. Reads handle these field types fine — only the write q.select chokes. Fix: split into separate q.selects per the Three Mappings Pattern (`useRecord` / `useRecords` gets the full select with read-only fields; `useRecordCreate` / `useRecordUpdate` gets a writable-only subset). Diagnostic when the symptom shows up: same bisection procedure as the renamed-column case — strip the write q.select to a known-writable minimum, then add fields back in halves until the Action drops out. Verified 2026-05-22: `blocks/wig-details/wig-details-page.jsx` shared one `wigSelect` between `useRecord` and `useRecordUpdate`; the select included `Wig Tag ID` (formula), `Total client price` (rollup), `Total worker pay` (rollup), `Instrucciones` (aiText) — Update Action stayed disabled until those four read-only fields were lifted out into a separate write-only select. See [datasources/airtable.md](../datasources/airtable.md#maintainability-gotcha) and [datasources/writing.md](../datasources/writing.md). |
-| Linked record as plain string | Must be `[{ id: "..." }]` array |
-| Writing dropdown values as `{ id, label }` objects (the read shape) | Write the option UUID as a plain string -- e.g. `status: "822b8d69-..."`, not `status: { id: "...", label: "..." }` |
+| Linked record as bare string, or `[{ id }]` objects on Softr Database | Array of record-id **strings**: `familyLink: [familyId]` — verified live 2026-08-25 on Softr DB. (The `[{ id }]` object shape was the May 2026 verified form on Airtable-backed blocks; try it if a string-array write fails there.) See [datasources/writing.md](../datasources/writing.md#linked-record-format-for-mutations) |
+| Writing dropdown values as `{ id, label }` objects (the read shape) or hunting for option UUIDs | Write the option **LABEL string**, exactly matching a defined choice — e.g. `status: "Active"` (verified live 2026-08-25; supersedes the April 2026 UUID rule). Keep vocabularies as greppable constants or fetch live via `useFieldOptions` and write `option.label` |
+| Writing a formatted phone value (`(212) 555-0100`, `212-555-0100`) to a PHONE field | Sanitize to unformatted international format — `+` followed by digits only (`+12125550100`) — before `mutate()`; some datasources (Monday.com, per the official guide) reject formatted values outright. Official sanitizer: `const sanitizePhone = (raw) => raw.replace(/[^\d+]/g, "").replace(/(?!^)\+/g, "");` See [datasources/writing.md](../datasources/writing.md#phone) |
+| Wrapping a `useRecordCreate` payload in `{ fields: {...} }` (copied from an update call) | Create payloads are **FLAT** — `createRecord.mutate({ name: "Jane" })`. Only update payloads nest: `{ recordId, fields: {...} }`. The asymmetry is by design (verified 2026-08-25) |
+| Passing a data hook's options through a variable or wrapper function: `useRecords(buildOpts())` | **Fails to compile** — the options object must be an inline literal at the call site (verified live 2026-08-25; hit in production, fixed by making the wrapper take the hook's *result* instead). Share `q.select` mappings between hooks, never whole options objects |
+| Tightening Actions-tab permissions before the block's final redeploy | Every code recompile **resets the auto-registered Actions to default permissions** (verified live 2026-08-25). Tighten permissions after the LAST redeploy, and re-check after any future one |
 | Treating Studio's Actions tab as a separately-managed configuration to keep in sync with code | Actions auto-derive from your `useRecordCreate`/`useRecordUpdate`/`useRecordDelete` + `q.select` on every save. The Actions tab is a read-only inspector; there is no manual delete control. To change an Action, change the code |
 | One alias in a write-side `q.select` referencing a renamed / non-existent Airtable column | Softr's Action parser silently rejects the **entire** create/update Action — not just the bad alias. Symptoms: Studio's Actions tab shows "No actions used in this block yet", `createRecord.enabled` / `updateRecord.enabled` stays `false`, `.mutate()` calls dispatch but resolve immediately to "not yet ready". Every OTHER field in the same `q.select()` is also lost, even the ones that map cleanly. Diagnostic: bisect the `q.select` — strip down to a known-good minimal set, confirm the Action appears in Studio, then add fields back in halves until it drops out. The culprit is in the last half added. Once narrowed to a single field, grep its name against the freshest Airtable schema export to catch the rename / trailing-space / case-mismatch. Verified 2026-05-21: a `"Photos"` column on Wigs was renamed to `"Before Photos"`, the helper that wrote `photos: "Photos"` had its entire Action disabled even though 11 other fields in the same `q.select` were fine. See [datasources/airtable.md](../datasources/airtable.md#maintainability-gotcha) |
 
@@ -51,7 +55,7 @@ Run through this catalog before delivering any block. Every row is a violation o
 | `import React from 'react'` | Named imports only |
 | Named export | `export default function Block()` |
 | Hook declared after conditional `return` | All hooks at top before any conditional `return` -- React error #310 |
-| `fetchNextPage()` in render body | Inside `useEffect` only -- in render = infinite loop |
+| `fetchNextPage()` in render body | Never in the render body (render → data update → re-render → infinite loop). Call from an event handler — the official Load More pattern: `<button onClick={() => fetchNextPage()} disabled={isFetching}>` — or a guarded `useEffect` for auto-load-all |
 | `useRef` for IDs used in `useMemo` | `useState` -- ref mutations don't trigger recomputation |
 | Defining a sub-component INSIDE the `Block()` function body | Define ALL sub-components at MODULE scope (above `export default function Block()`). Sub-components defined inside `Block()` get a brand-new function reference on every render, which makes React unmount/remount their entire DOM subtree every time `Block` re-renders. The user-visible symptom: **inputs lose focus after typing one character** (because each keystroke triggers a `setState` -> re-render -> the `<input>` is destroyed and recreated). Move `function FieldLabel`, `function TextInput`, `function ChipButton`, `function SectionCard`, etc. above `export default function Block()` so React sees stable component identity across renders. Closure-captured `Block`-internal state must be passed as props, not closed over. |
 

package/references/common-patterns.md

@@ -1,6 +1,6 @@
 # Common Patterns
 
-Small reusable patterns that come up across Vibe Coding blocks but don't warrant their own reference file. Each is a copy-pasteable snippet using the skill's preferred style (`var`, `function() {}`).
+Small reusable patterns that come up across Vibe Coding blocks but don't warrant their own reference file. Each is a copy-pasteable snippet. The snippets below use legacy var-style (`var`, `function() {}`), which remains valid — write new blocks in modern TS (see SKILL.md Style Conventions).
 
 ## Table of Contents
 

package/references/helper-blocks.md

@@ -56,7 +56,7 @@ in the published app.
 Key rules:
 - The helper block must be on the **same Softr page** as the consumer -- `window` is page-scoped, globals don't cross pages.
 - **One helper block per foreign table.** Multiple helpers with distinct namespaces coexist fine on the same page.
-- **Read-only pattern.** Helpers expose foreign table data for lookups, pickers, and display only. Writes still happen from the main block via its own `useRecordUpdate` / `useRecordCreate`. If the main block needs to write to the helper's table, use a webhook or the Softr Database REST API (see [writing.md Cross-Table Operations](../datasources/writing.md#cross-table-operations)), not the helper.
+- **Read-only pattern.** Helpers expose foreign table data for lookups, pickers, and display only. Writes still happen from the main block via its own `useRecordUpdate` / `useRecordCreate`. **Modern path for writing to another table:** connect it as a second datasource and write with `useRecordCreate({ from: ds.x })` — see [writing.md Cross-Table Operations](../datasources/writing.md#cross-table-operations); a webhook or the Softr Database REST API remain fallbacks for writes the hooks can't express. Never write through the helper.
 
 ## Companion Field Helpers
 
@@ -144,7 +144,9 @@ Key points:
 import { useRecords, q } from "@/lib/datasource";
 import { useEffect, useMemo, useRef } from "react";
 
-var select = q.select({ fullName: "fldXXX", isActive: "fldYYY" });
+// q.select values: field NAMES for Airtable/Notion/Google Sheets, field IDs for Softr DB/Supabase.
+// (An Airtable "fldXXX" ID here compiles and saves, then silently returns empty data.)
+var select = q.select({ fullName: "Full Name", isActive: "Active" });
 
 function toOption(record) {
   return { id: record.id, title: record.fields.fullName || "" };

package/references/native-block-filters.md

@@ -8,7 +8,7 @@ Softr's native **List / Grid** blocks support category chips and *static* filter
 
 > **Sibling to [native-chrome-styling.md](native-chrome-styling.md).** That doc restyles Softr's *shell* (header/footer/nav) with global CSS. This one *drives and augments native blocks* with custom-code JS. Both reach the **main document**, never a block's shadow DOM — so this is a **Custom Code Static block**, not a Vibe Coding (JSX) block.
 
-House code style still applies in the `<script>`: `var`, `function(){}`, **no** optional chaining (`?.`) or nullish coalescing (`??`).
+Modern JS is fine in the `<script>` — Custom Code blocks run unbundled in the browser, and the old `var`/`function(){}`/no-`?.` house style is retired everywhere (the Vibe Coding compiler accepts modern syntax too, verified 2026-08-25).
 
 ---