softr-vibe-coding 2.13.4 → 2.13.5

package/CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to this skill are documented here. Versions follow [Semantic
 
 Entries from 1.3.1 onward are generated automatically from git commit subjects between version bumps (see `.github/workflows/publish.yml`). Entries before 1.3.1 were backfilled by hand from the existing commit history.
 
+## [2.13.5] - 2026-10-06
+- Release 2.13.5
+- Correct the MCP FILTER-condition claim and eight other conflicts found in the 2026-10-06 audit
+
 ## [2.13.4] - 2026-10-06
 - Release 2.13.4
 - Add in-block modal above Softr's bars (shadcn Dialog sits under the top bar)

package/README.md

@@ -169,7 +169,7 @@ Create a contact form that creates records in our Airtable Contacts table
 softr-vibe-coding/
 ├── SKILL.md                          # Main skill
 │                                     # Workflow, code structure, visual baseline,
-│                                     # components, settings, 28 hard constraints
+│                                     # components, settings, 29 hard constraints
 │
 ├── ui-ux-guidelines.md               # Design reference
 │                                     # 26 sections: hierarchy, color, typography,
@@ -190,13 +190,16 @@ softr-vibe-coding/
 │   │                                 # browsing (Airtable/Sheets/Notion/Supabase),
 │   │                                 # Softr DB schema + record tools incl. deletes,
 │   │                                 # app management/scaffolding, Workflows suite
-│   │                                 # (26 tools, 418-node catalog), per-application
+│   │                                 # (28 tools, 418-node catalog), per-application
 │   │                                 # MCP servers, auth, permissions; what the server
 │   │                                 # enforces on block data endpoints, "Preview as"
 │   │                                 # role testing, search-replace on 100KB+ blocks
 │   │                                 # (Sep 18 2026); Oct 1 2026: tool rename map,
 │   │                                 # push verification by sourceSha256, stub tools
-│   │                                 # after a resume, update_field/update_table fixes
+│   │                                 # after a resume, update_field/update_table fixes;
+│   │                                 # Oct 6 2026: MCP-written FILTER conditions are
+│   │                                 # inert (set them in Studio), Workflows tools as
+│   │                                 # workflow_*, denied by-id fetch per backend
 │   ├── browser-checks.md             # Checking a pushed block in a browser with
 │   │                                 # the agent-browser CLI (ask before installing):
 │   │                                 # preview cookie, shadow-DOM refs grepped in the
@@ -271,11 +274,14 @@ softr-vibe-coding/
     ├── reading.md                    # useRecords, filtering, sorting, pagination,
     │                                 # metrics, charts, current user; no detail-page
     │                                 # auto-scoping, useRecords ignores enabled:false,
-    │                                 # server-side linked-record filters (Sep 18 2026)
+    │                                 # server-side linked-record filters (Sep 18 2026);
+    │                                 # where/orderBy aliases resolve per hook (Oct 6 2026)
     ├── writing.md                    # Mutations, sequential write queues, uploads,
-    │                                 # linked record format, cross-table writes
+    │                                 # linked record format, cross-table writes;
+    │                                 # Actions register per table (Sep 18 2026)
     ├── fields.md                     # getFieldValue(), field type shapes, record
-    │                                 # structure, debug utilities
+    │                                 # structure, debug utilities; date-only fields
+    │                                 # parsed as local dates (Oct 6 2026)
     ├── rest-api.md                   # useProxyFetch + useQuery (full docs)
     ├── softr-database.md             # Native DB — field IDs, no rate limits
     ├── airtable.md                   # Column names, PAT vs OAuth, rate limits
@@ -334,7 +340,7 @@ The skill enforces these automatically, but good to know (verified live against
 - No `import React from 'react'` — use named imports (`import { useState } from "react"`)
 - Must use `export default function Block()`
 - Wrap layout in `<div className="container py-0"><div className="content">` for app/content blocks (house convention for width alignment with native blocks) — the platform default is actually full width, so full-bleed marketing blocks (heroes, banners, footers) legitimately omit the wrappers and own their gutters
-- Only ONE `useRecords` call per **datasource** — but a block can connect to several sources; declare them with `datasource.define()` and pass `from:` on every hook
+- One `useRecords` per **connection** (house rule) — a block can connect to several sources, including the same table twice; declare them with `datasource.define()` and pass `from:` on every hook
 - `fetchNextPage` never in the render body (infinite loop) — call it from an event handler (Load More `onClick`) or a guarded `useEffect`
 - All hooks declared before any conditional `return` — React error #310
 - Every field value rendered in JSX must pass through `getFieldValue()`

package/SKILL.md

@@ -72,6 +72,8 @@ You generate complete, production-ready Softr Vibe Coding blocks as TypeScript R
    - Multi-datasource block: every `select:` / `fields:` value is a **plain module-scope identifier** — no ternary, no inline `q.select({...})` inside the hook options (the query returns `fields: {}`; Hard Constraint 24)
    - Detail page: the record is fetched with `useRecord({ select, recordId, enabled: !!recordId })` using `useCurrentRecordId()`, and the code checks `data.id === recordId` before rendering — never `useRecords({ count: 1 })`, which returns the table's FIRST row (Hard Constraint 25)
    - No list query relies on `enabled: false` — `useRecords` fetches anyway; conditional list queries live in a child component mounted only when needed, or carry a match-nothing `where` (Hard Constraint 26)
+   - Every alias a hook's `where` / `orderBy` names is in **that hook's own** `select` — anything else crashes the block at runtime (Hard Constraint 29)
+   - Date-only values are parsed with `toLocalDate()`, never `new Date()` — midnight UTC renders a day early west of Greenwich ([datasources/fields.md](datasources/fields.md#date-only-fields-arrive-as-midnight-utc))
    - No field is "hidden" from some viewers by a conditional / second `select` on the same connection — the browser receives the union of every read select on that connection (Hard Constraint 23)
    - All imports use named imports (no `import React from 'react'`)
    - `export default function Block()` is present
@@ -614,9 +616,15 @@ Non-negotiable rules. Most are enforced by the Softr platform (compiler, validat
     changing the wrapper to take the hook's *result* instead.)
 11. **Airtable, Notion, Google Sheets: use field NAMES, not IDs** — `q.select()` values are field names for these three sources; Softr Database and Supabase use field IDs (Supabase = SQL column name). Getting this wrong fails silently: the block compiles and saves, then renders empty. See [datasources/airtable.md](datasources/airtable.md).
 12. **Record fields nested under `fields`** — Access via `record.fields.alias`, not `record.alias`.
-13. **ONE `useRecords` per datasource** — filter client-side rather than issuing several queries against
-    the same table. A block CAN connect to multiple data sources and call `useRecords` once per source;
-    declare them with `datasource.define()` and pass `from:` on every hook. See
+13. **One `useRecords` per connection [house]** — not a documented platform limit (Softr's developer
+    guide shows one `useRecords` per datasource but states no rule; checked 2026-10-06). Read each
+    connection once and filter client-side when the table is small and every viewer may see all of
+    it anyway. When the data must differ, add connections rather than queries: a second table gets
+    its own connection, and so does a private read of the same table (Hard Constraint 23). A
+    server-side `where` is better for large tables and linked children, but it is a request
+    parameter, never access control. A query mounted in a child component (Hard Constraint 26) is
+    that connection's one read; don't also read the connection in the parent. Declare connections
+    with `datasource.define()` and pass `from:` on every hook. See
     [datasources/multi-datasource.md](datasources/multi-datasource.md). Multiple `useMetric` calls OK.
 14. **React functional components only** — No class components.
 15. **Do NOT `import React from 'react'`** — Use named imports for hooks.
@@ -650,7 +658,9 @@ Non-negotiable rules. Most are enforced by the Softr platform (compiler, validat
     A push that returns `errors: null` can still have left public write access on the block.
     **If any action is still broader than intended, report it WITH its severity and let the builder decide.**
     Check the page's own VIEW permission first (`application_page_get_permissions`): a page gated to logged-in
-    users makes an open action housekeeping, a public page makes it a real hole. Surface the list
+    users makes an open action housekeeping, a public page makes it a real hole. Report the block's own
+    Visibility with it -- it gates the block's reads and sets ADD_RECORD's default, but whether it
+    refuses writes on its own is untested. Surface the list
     either way -- page, block, action type, data source -- and note that a human sets them on the
     block's Actions tab. Do not unilaterally block a publish; it is not your app.
 22. **Blocks cannot import each other -- cross-block consistency is discipline, not architecture [house]**
@@ -700,6 +710,11 @@ Non-negotiable rules. Most are enforced by the Softr platform (compiler, validat
     them takes global CSS across Softr's page structure as well as print CSS in the block. Never
     an in-page "print view" either (Leo rejected it by name). Verified live 2026-09-30. See
     [references/printing.md](references/printing.md).
+29. **`where` / `orderBy` may only name aliases from the same hook's `select`** -- aliases resolve per
+    hook, not per connection. Naming any other alias crashes the whole block at runtime ("Could not
+    find an alias for subject \"undefined\"") although the push compiles clean. Seen live
+    2026-09-18 on a `useMetric`. See
+    [datasources/reading.md](datasources/reading.md#filter-and-sort-aliases-must-be-in-the-same-hooks-select).
 
 ## Style Conventions
 

package/datasources/fields.md

@@ -32,13 +32,35 @@ Property priority: `label` first (most common in Softr formatted fields), then `
 
 Apply `getFieldValue()` everywhere you read fields:
 - Table cells, badges, tooltips: `<td>{getFieldValue(f.subject)}</td>`
-- Date parsing: `new Date(getFieldValue(f.dueDate))` -- raw value might be `{label: "2025-12-01"}`
+- Date parsing: `toLocalDate(getFieldValue(f.dueDate))` for date-only fields ([below](#date-only-fields-arrive-as-midnight-utc)), `new Date(...)` for real timestamps -- raw value might be `{label: "2025-12-01"}`
 - Number parsing: `parseInt(getFieldValue(f.count), 10)` -- formula numbers come back as objects
 - String methods: `getFieldValue(f.status).toLowerCase()`
 - Inside `useMemo` normalizers, BEFORE storing into state -- prevents the object from propagating
 
 For companion helpers (`getLinkedNames`, `getLinkedItems`) used in helper block consumers, see [../references/helper-blocks.md](../references/helper-blocks.md).
 
+### Date-only fields arrive as midnight UTC
+
+*Verified live 2026-09-18 (Softr Database).* A date field without a time arrives as midnight UTC.
+`new Date()` parses it as UTC, so anywhere west of Greenwich (New York, for one) date-fns renders
+the **previous day**. Parse date-only values as local dates, and keep the default parse for real
+timestamps:
+
+```jsx
+var DATE_ONLY_RE = /^(\d{4})-(\d{2})-(\d{2})(?:[T ]00:00(?::00(?:\.0+)?)?(?:Z|\+00:00)?)?$/;
+
+function toLocalDate(raw) {
+  if (typeof raw === "string") {
+    var m = raw.match(DATE_ONLY_RE);
+    if (m) return new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3]));
+  }
+  return new Date(raw);
+}
+```
+
+A real timestamp at exactly midnight UTC matches the pattern too, so call `toLocalDate` only on
+fields you know are date-only.
+
 ## Debugging Error #31
 
 If React crashes with error #31 ("Objects are not valid as a React child"), open console on the first record that crashes and run:
@@ -78,7 +100,7 @@ var name = f.firstName || "";
 
 ## Debug Utilities
 
-Two throwaway diagnostic blocks you can drop into a page to diagnose data problems. Neither is meant for production -- delete or hide them once the issue is resolved. During development, drop them on a `/debug` page that's only visible to admins, or on a hidden page you navigate to manually.
+Two throwaway diagnostic blocks you can drop into a page to diagnose data problems. Neither is meant for production -- delete or hide them once the issue is resolved. During development, drop them on a `/debug` page whose VIEW permission is limited to admins. A page that is merely left out of the navigation is still reachable by URL, and its blocks' endpoints answer anyone the page lets in (see [softr-mcp.md](../references/softr-mcp.md#what-the-server-enforces-on-a-blocks-data-endpoints)).
 
 ### Field Inspector Block
 
@@ -123,7 +145,7 @@ export default function Block() {
 
 4. **Inline in Studio (one field at a time)** -- in the Data tab, click a field's name to open its edit drawer. The field ID appears next to the "Field name" label (e.g. `ID: 37fts`). Fastest for spot-checking a single field.
 
-5. **Softr Database REST API with `fieldNames=true`** -- runtime inspection from inside a Vibe Coding block (internal-portal blocks only, since this exposes a PAT in client code):
+5. **Softr Database REST API with `fieldNames=true`** -- runtime inspection from inside a Vibe Coding block (only on a page limited to admins, and removed afterwards: the PAT sits in the block's source, and anyone who can load the page can read it and use it against the whole database, past every page, block and Source-condition gate):
 
 ```jsx
 import { useEffect, useState } from "react";

package/datasources/multi-datasource.md

@@ -94,7 +94,7 @@ it behaves as a **union** of both branches, not a choice between them. Which is
 *Verified live 2026-09-18; the block-visibility gate 2026-10-05.*
 
 The records endpoint is per block + connection —
-`/blocks/<blockId>/datasources/<dataSourceId>/records` — and it returns the **UNION of every field
+`/blocks/<blockId>/datasources/<connection>/records` (`<connection>` was recorded as the connection's id in the 2026-09-18 Softr Database capture and seen as its alias in a 2026-10-05 HubSpot capture; unresolved, and it only matters when reading a network log) — and it returns the **UNION of every field
 named by any READ `q.select` attributed to that connection**. Two selects on one connection do
 NOT produce two payloads: every read hook on that connection gets all the fields, for every
 viewer.
@@ -146,8 +146,10 @@ user and logged-out visitors 403 on list and by-id. The gate belongs to the bloc
 connect the same table to an ungated block and it is open again. See
 [../references/softr-mcp.md](../references/softr-mcp.md#what-the-server-enforces-on-a-blocks-data-endpoints).
 
-Alias → field attribution is per connection, so two selects on different connections may reuse
-an alias name (`customer` on both) without colliding — including in `where` filters.
+Two selects on different connections may reuse an alias name (`customer` on both) without
+colliding. Aliases resolve **per hook**, though: a hook's `where` / `orderBy` may name only aliases
+from that hook's own `select`, or the block crashes at runtime — see
+[reading.md](reading.md#filter-and-sort-aliases-must-be-in-the-same-hooks-select).
 
 ## Mutation Actions register per TABLE, not per connection
 
@@ -206,3 +208,11 @@ right tool for:
 `crew-feedback-form.jsx` — a public feedback form that reads a person from **People** by an
 `email` URL param, resolves a **Shifts** record from a job-code param, and writes a row to
 **Feedback** linking both. One block, three sources, no helpers, no `window` globals.
+
+**Read it against the rules above before copying it.** On a public page every logged-out visitor
+may call the People connection, and the endpoint returns every row the Source conditions allow,
+with every field the block's read selects name. The `email` URL param narrows nothing on the
+server: it ends up in a `where`, which is a request parameter the caller controls, and there is no
+logged-in user for a Source condition to match. Select only what the form must show, assume every
+row of it is public, and if that is not acceptable resolve the person server-side (a Softr
+Workflow) instead of reading People from the block.

package/datasources/reading.md

@@ -65,7 +65,7 @@ var isRefetching = result.isRefetching;
 var items = (data && data.pages) ? data.pages.flatMap(function(p) { return p.items; }) : [];
 ```
 
-**CRITICAL:** Only ONE `useRecords` call **per datasource**. Fetch that table's data in one call and filter client-side. Multiple `useMetric` calls ARE allowed.
+**House rule: one `useRecords` per connection.** It is not a documented platform limit — Hard Constraint 13 in SKILL.md says when to filter client-side, when to add a connection, and when a server-side `where` is the better choice. 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** —
@@ -80,7 +80,9 @@ A block can connect to **several data sources** and call `useRecords` once per s
 *Verified live 2026-09-18 (network capture).* `useRecords({ ..., enabled: false })` **fetches
 anyway** — with a literal `false` and with a variable alike. `useRecord` is different: it honours
 `enabled: false` and issues no request. (`useLinkedRecords`, `useMetric` and `useChartData` were
-not probed — don't assume either behaviour for them.)
+not probed — don't assume either behaviour for them.) The official developer guide still
+describes `enabled` on `useRecords` as an "optional boolean to defer loading" (checked
+2026-10-06); the capture says otherwise, so trust it until a newer one does not.
 
 So `enabled` cannot make a list query conditional, and it cannot keep a query away from viewers
 who should not run it. Two things that do work:
@@ -171,7 +173,7 @@ var result = useLinkedRecords({
   field: "category",    // the ALIAS from q.select(), NOT the raw field ID
   sortOrder: "ASC",     // "ASC" | "DESC"
   search: "",           // optional search string
-  enabled: true,        // defer loading until needed
+  enabled: true,        // documented as deferral; not verified live (see the useRecords note)
   count: 50,            // optional page size — default 100, max 1000
 });
 
@@ -257,6 +259,26 @@ where: q.and(
 )
 ```
 
+### Filter and sort aliases must be in the same hook's select
+
+*Seen live 2026-09-18 (Softr Database, on a `useMetric`).* Aliases are resolved **per hook**, not
+per connection. A `where` or `orderBy` that names an alias missing from that hook's own `select`
+crashes the whole block at runtime ("Could not find an alias for subject \"undefined\"" and
+Softr's "Oh snap" panel), although the push compiled clean:
+
+```jsx
+// WRONG — "status" is not in this hook's select: compiles, then crashes the block
+var countSelect = q.select({ orderNo: "FIELD_ID1" });
+var open = useMetric({ select: countSelect, metric: metric.count(), where: q.text("status").is("Open") });
+
+// CORRECT — every alias the where / orderBy names is in the hook's own select
+var countSelect = q.select({ orderNo: "FIELD_ID1", status: "FIELD_ID2" });
+```
+
+Adding the field to the select also adds it to the connection's read payload
+([multi-datasource.md](multi-datasource.md#one-connection--one-read-payload-the-union-of-its-selects)),
+so put a filter on a private field on the connection that is allowed to carry it.
+
 ### Filtering by a linked record (server-side)
 
 *Verified live 2026-09-18 (Softr Database, network capture).* A linked-record field filters on
@@ -275,9 +297,10 @@ var comments = useRecords({
 ```
 
 On the wire the alias is resolved to the field id:
-`{ subject: <fieldId>, type: "ARRAY", operator: "HAS_ALL_OF", value: [orderId] }`. Alias → field
-attribution is **per datasource**, so two selects on different connections may use the same alias
-name for different fields and each filter still resolves against its own connection.
+`{ subject: <fieldId>, type: "ARRAY", operator: "HAS_ALL_OF", value: [orderId] }`. Aliases resolve
+**per hook** ([above](#filter-and-sort-aliases-must-be-in-the-same-hooks-select)), so two selects on
+different connections may use the same alias name for different fields, and each filter resolves
+against its own hook's `select`.
 
 `orderId` must be a real id when the hook runs — `useRecords` cannot be switched off with
 `enabled: false` ([above](#userecords-ignores-enabled-false)), so mount this query in a child

package/datasources/writing.md

@@ -85,6 +85,10 @@ Because the parser only inspects your hooks and `q.select` mappings (not the JSX
 
 All mutation hooks expose an `enabled` boolean. You must check it before rendering any mutation UI or calling the mutate function.
 
+The snippets below write `fields: q.select({...})` inline for brevity, as single-datasource
+shorthand. In a block with more than one connection, hoist every `fields:` select to module scope
+and pass the identifier ([multi-datasource.md](multi-datasource.md#select-must-be-a-plain-module-scope-identifier)).
+
 ### useRecordCreate
 
 ```jsx
@@ -677,7 +681,7 @@ Three remaining alternatives, for the cases multi-datasource doesn't cover:
 **Update:** PATCH `/{recordId}` with `{ fields: { fieldId1: "newValue" } }`
 
 Notes:
-- API key is exposed in client-side code -- acceptable for internal portals only
+- The API key ships in the block's source. Anyone who can load the page can read it and use it against the whole database, past page VIEW, block Visibility and Source conditions alike. Use this only on a page limited to a trusted group, and only for what the hooks or a Softr Workflow cannot do
 - When updating linked records or multi-selects, read existing values first, merge, then write
 - Use `fieldNames=true` on GET for human-readable field names
 - Rate limits: Reads 40 req/s, Writes 30 req/s

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "softr-vibe-coding",
-  "version": "2.13.4",
+  "version": "2.13.5",
   "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/anti-patterns.md

@@ -19,9 +19,10 @@ Run through this catalog before delivering any block. Every row is a violation o
 | 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 |
-| "Hiding" a private field from non-admins with a second `q.select`, or a ternary between a public and an admin select, on the SAME connection | **Not privacy.** The records endpoint is per block + connection (`/blocks/<id>/datasources/<dsId>/records`) and returns the UNION of every field named by any READ `q.select` on that connection — every viewer's browser receives the private field; it is merely not rendered (verified live 2026-09-18, network capture). A mutation hook's `fields:` select does not join the union. Fix: connect the **same table a second time** (allowed — it gets its own dataSourceId), read the private field only from that connection in a hook that non-privileged browsers never run (a child component mounted only for admins), or move it to a group-gated block. Server-side, page VIEW permission gates the endpoint and Source conditions gate ROWS; nothing else does. See [datasources/multi-datasource.md](../datasources/multi-datasource.md#one-connection--one-read-payload-the-union-of-its-selects) |
+| "Hiding" a private field from non-admins with a second `q.select`, or a ternary between a public and an admin select, on the SAME connection | **Not privacy.** The records endpoint is per block + connection (`/blocks/<id>/datasources/<connection>/records`) and returns the UNION of every field named by any READ `q.select` on that connection — every viewer's browser receives the private field; it is merely not rendered (verified live 2026-09-18, network capture). A mutation hook's `fields:` select does not join the union. Fix: connect the **same table a second time** (allowed — it gets its own dataSourceId), read the private field only from that connection in a hook that non-privileged browsers never run (a child component mounted only for admins), or move it to a group-gated block. Server-side, page VIEW permission and the block's own Visibility gate the endpoint (403 on list and by-id; block gate verified 2026-10-05), and Source conditions gate ROWS; nothing else does. See [datasources/multi-datasource.md](../datasources/multi-datasource.md#one-connection--one-read-payload-the-union-of-its-selects) |
 | `select: isAdmin ? adminSelect : publicSelect` (or an inline `q.select({...})` in the hook options) in a **multi-datasource** block | The select cannot be attributed to a connection and the query returns records with `fields: {}` — no compile error, no runtime error, just empty fields (verified live 2026-09-18). `select:` / `fields:` must be a **plain module-scope identifier**. In a single-datasource block the ternary "works", but as a union of both branches (row above) — so it is never the tool it looks like. See [datasources/multi-datasource.md](../datasources/multi-datasource.md#select-must-be-a-plain-module-scope-identifier) |
 | `useRecords({ select, count: 1 })` on a detail page, expecting the page's record — or a `useRecord` with no / null `recordId` | There is **no detail-page auto-scoping**: the runtime sends `pageContext: null`, so `count: 1` returns the table's FIRST row, and a null-id `useRecord` falls back to a list call (verified live 2026-09-18). It passes a test on the first record and fails on every other. Use `useRecord({ from, select, recordId, enabled: !!recordId })` with `recordId = useCurrentRecordId()` (which does return the URL's `recordId`; the call hits `/records/<id>`), and verify `data.id === recordId` before rendering or writing. See [datasources/reading.md](../datasources/reading.md#userecord----fetch-a-single-record) |
+| `where: q.text("status")…` or `orderBy` naming an alias that is not in **that hook's own** `select` | Crashes the whole block at runtime — "Could not find an alias for subject \"undefined\"", Softr's "Oh snap" panel — though the push compiled clean (seen live 2026-09-18 on a `useMetric`). Aliases resolve per hook, not per connection: add the field to the hook's select (it then joins the connection's read payload). Hard Constraint 29; see [datasources/reading.md](../datasources/reading.md#filter-and-sort-aliases-must-be-in-the-same-hooks-select) |
 | `useRecords({ ..., enabled: false })` / `enabled: someFlag` to defer or withhold a list query | **`useRecords` ignores `enabled: false`** — literal or variable, it fetches anyway (verified live 2026-09-18). `useRecord` honours it. To make a list query conditional, mount the hook in a **child component rendered only when needed** (the only option that sends no request), or give it a match-nothing `where`. Never rely on `enabled` to keep a table away from viewers who should not load it. See [datasources/reading.md](../datasources/reading.md#userecords-ignores-enabled-false) |
 
 ## Mutations
@@ -57,6 +58,7 @@ Run through this catalog before delivering any block. Every row is a violation o
 |---|---|
 | `field.toLowerCase()` on selects | `getFieldValue(field).toLowerCase()` |
 | `item.fields.formula === true` | Formula booleans: `=== "1"` |
+| `new Date(value)` / date-fns `format(new Date(value))` on a **date-only** field | Date-only values arrive as midnight UTC, so west of Greenwich they render one day early (verified 2026-09-18). Parse them with `toLocalDate()` — see [datasources/fields.md](../datasources/fields.md#date-only-fields-arrive-as-midnight-utc). Keep `new Date()` for real timestamps |
 
 ## Hooks & React
 

package/references/helper-blocks.md

@@ -83,7 +83,11 @@ function getLinkedItems(f) {
     if (x && typeof x === "object") return { id: x.id || "", title: x.label || x.name || x.title || "" };
     return { id: "", title: String(x) };
   }).filter(function(o) { return o.id || o.title; });
-  return [];
+  if (typeof f === "object") {            /* a single link arrives as one { id, label } object */
+    var t = f.label || f.name || f.title || "";
+    return (f.id || t) ? [{ id: f.id || "", title: t }] : [];
+  }
+  return [{ id: "", title: String(f) }];
 }
 ```
 
@@ -362,7 +366,7 @@ When you change a helper's output shape (e.g., `advisorOffice` from array to str
 1. Document the published shape as a comment at the top of the helper file and update all consumers in the same commit.
 2. Version the namespace (`__myapp_projects_v2`) -- old consumers keep reading v1 until migrated.
 
-Defensive consumers can use `Array.isArray(x) ? x.map(...) : x` when shape might vary, but don't lean on this -- it hides bugs.
+Defensive consumers can use `Array.isArray(x) ? x.map(...) : x` when shape might vary, but don't lean on this -- it hides bugs. (That is about the shape of a global *you* publish. Linked-record values read from Softr are different: they arrive as a single `{ id, label }` object or as an array, and must always be normalised -- see [fields.md](../datasources/fields.md).)
 
 ### useState, Not useRef, for IDs Consumed by useMemo
 

package/references/softr-mcp.md

@@ -50,8 +50,8 @@ map below was checked against the tool lists the server delivered on 2026-09-30
 **The Workflows tools have since followed** (when exactly is not known; first seen 2026-10-05). The 2026-10-05 roster delivered all 28 as `workflow_*`:
 `workflow_create`, `workflow_get`, `workflow_list`, `workflow_publish`, `workflow_update_node_inputs`,
 `workflow_get_node_specifications`, `workflow_list_node_types`, `workflow_test_node` and the rest,
-i.e. area first, then the old verb and object. [Workflows](#workflows) below still lists the
-pre-rename names. Translate them that way. That roster had no `get_workspace_integrations`;
+i.e. area first, then the old verb and object. [Workflows](#workflows) below uses the new names
+(re-checked against the live roster 2026-10-06: all 28 present). That roster had no `get_workspace_integrations`;
 `integration_list` covers it.
 
 Most new names are the old words reordered. These are the ones you would not guess:
@@ -195,7 +195,7 @@ For block-building work you need **Applications & Forms: Full access** (to creat
 
 ## Vibe coding block tools
 
-Before writing any block code through the MCP, call `vibe_coding_block_get_docs` — it returns the current version of the [Vibe Coding Developer Guide](https://docs.softr.io/vibe-coding-developer-guide), which is the authority on hook signatures if it and this skill ever disagree.
+Before writing any block code through the MCP, call `vibe_coding_block_get_docs` — it returns the current version of the [Vibe Coding Developer Guide](https://docs.softr.io/vibe-coding-developer-guide), which is the authority on hook signatures if it and this skill ever disagree. On runtime *behaviour* the guide's prose can lag a live capture, and where it does this skill says so: the guide still describes `useRecords({ enabled })` as a way to defer loading (checked 2026-10-06), while a 2026-09-18 network capture showed `useRecords` fetching anyway ([reading.md](../datasources/reading.md#userecords-ignores-enabled-false)). Trust the capture until a newer one says otherwise.
 
 | Group | Tools |
 |---|---|
@@ -250,9 +250,13 @@ context. Keep the local mirror in step mechanically rather than by hand:
    sent, which is what makes it usable here: on this path you never see the merged file yourself.
 
 One encoding trap: JSON `\uXXXX` escapes inside the ops are **decoded to the real characters** on
-Softr's side (`"—"` is stored as `—`). The mirror must therefore hold raw UTF-8 — apply the
+Softr's side (`"\u2014"` is stored as `—`). The mirror must therefore hold raw UTF-8 — apply the
 ops to it *after* JSON-decoding them, never as the escaped text, or the final comparison
 fails on every non-ASCII character.
+The same decoding happens to an agent's own tool-call arguments: a `\u2014` typed into a
+file-writing tool lands on disk as `—` (it put a wrong example into this very paragraph
+twice, 2026-09-18 and 2026-10-06). When a file must hold a literal backslash-u sequence, build the
+backslash at runtime (`chr(92)` in Python) and check the bytes afterwards.
 
 **Reach for the full replace when the change is structural** — reordering JSX, moving logic between
 components, adding a hook — where being sure of "the exact current text" of a dozen scattered fragments
@@ -421,13 +425,17 @@ preserves explicitly set permissions across a recompile, so every recompile need
    the call errors rather than lying, but an agent that batches calls can easily miss which one failed.
 5. If any action is still broader than intended (typically ADD_RECORD at `ALL_USERS`), **report it
    and let the builder decide.** Check the page's own VIEW permission first with
-   `application_page_get_permissions`, because that is what sets the severity:
+   `application_page_get_permissions`, because that is what sets the severity, and report the
+   block's own Visibility with it (`vibe_coding_block_get_settings`): it gates the block's reads
+   and sets ADD_RECORD's default (2026-10-05), but whether it refuses writes on its own is untested
+   ([below](#what-the-server-enforces-on-a-blocks-data-endpoints)):
    - **Page VIEW is gated** (e.g. `LOGGED_IN_USERS`) — an anonymous visitor cannot load the page at
      all, so exploiting the open action means calling its endpoint directly, and the realistic worst
      case is junk records rather than data exposure or deletion. Housekeeping: worth fixing on the
      next Studio pass, not worth holding a release for.
-   - **Page VIEW is `ALL_USERS`** — the action permission is the only gate left. That is a genuine
-     hole and deserves to be called one.
+   - **Page VIEW is `ALL_USERS`** — the action permission is the only gate known to hold on writes
+     (the block's Visibility may also refuse them; untested). That is a genuine hole and deserves
+     to be called one.
 
    Report page, block, action type, data source and current group; say which of the two cases applies;
    note that a human sets them on the block's Actions tab in Studio. Then stop — **do not unilaterally
@@ -438,8 +446,10 @@ preserves explicitly set permissions across a recompile, so every recompile need
    **is** enforced on the block's datasource **records** endpoint (verified live 2026-09-18 — a
    viewer who cannot view the page gets a 403 whose message names "block/action visibility rules";
    see [below](#what-the-server-enforces-on-a-blocks-data-endpoints)). The *action* (write) endpoint
-   was not exercised separately; the message wording suggests the same gate covers it, but that part
-   is inference. So the reason to treat a gated page as low-severity is still the practical
+   refuses outsiders too: on 2026-10-05 a replayed PATCH from outside the block's group got 403
+   ([hubspot.md](../datasources/hubspot.md#writing)). The block and its actions were both limited to
+   that group, so which rule refused it is not known, and whether page VIEW alone gates writes is
+   untested. So the reason to treat a gated page as low-severity is still the practical
    difficulty and low blast radius — and note that "gated to logged-in users" keeps out anonymous
    visitors only: any logged-in user can view that page, and therefore reach its endpoints. Say that
    plainly rather than implying the action is safe.
@@ -462,14 +472,14 @@ Both edit paths recompile, so both reset Action permissions either way (Hard Con
 *Verified live 2026-09-18 (Softr Database; draft preview, "Preview as" different users, requests
 captured from the app iframe); the block-visibility row verified 2026-10-05 (HubSpot; preview link,
 impersonated users, direct POSTs).* A block's data lives behind per-connection endpoints —
-`/blocks/<blockId>/datasources/<dataSourceId>/records` for lists, `/records/<id>` for one record —
-and these are the gates that actually exist on them:
+`/blocks/<blockId>/datasources/<connection>/records` for lists, `/records/<id>` for one record —
+and these are the gates that actually exist on them (`<connection>` was recorded as the connection's id in the 2026-09-18 Softr Database capture and seen as its alias in a 2026-10-05 HubSpot capture; unresolved, and it only matters when reading a network log):
 
 | Gate | Enforced server-side? |
 |---|---|
 | **Page VIEW permission** | **Yes.** A viewer who cannot view the page gets **403** ("block/action visibility rules…") from the block's datasource endpoint — crafting the request by hand does not get around it |
 | **The block's Visibility** (`predefinedUserGroup` + `customUserGroupIds`; `vibe_coding_block_set_visibility`) | **Yes.** A viewer outside the block's group gets the same **403**, on list and by-id, even where the page lets them in. The body reads like a write error on a read: "You cannot add or edit a record because either the block/action visibility rules, user group conditions, or the user/record data in the datasource has changed." Per block: the same table on an ungated block stays open. Five code pushes left the setting intact |
-| **The connection's Source conditions** (Source tab / `vibe_coding_block_set_data_source_record_filters`) | **Yes — and they are the only server-side ROW gate** |
+| **The connection's Source conditions** (Source tab / `vibe_coding_block_set_data_source_record_filters`) | **Yes — and they are the only server-side ROW gate.** A by-id request for a record the condition excludes answers differently per backend: **HTTP 200 with an empty body** on Softr Database (2026-09-18), **404** on HubSpot (2026-10-05). Treat both as "not found" |
 | A `where` filter in the block's code | No — it is a request parameter the caller controls |
 | Which fields the block *renders*, a second / conditional `q.select`, `enabled: false` on `useRecords` | No — the endpoint returns the union of the connection's read selects to anyone allowed to call it (see [multi-datasource.md](../datasources/multi-datasource.md#one-connection--one-read-payload-the-union-of-its-selects)) |
 
@@ -506,7 +516,8 @@ verified on HubSpot on 2026-10-05, the same way.* There are two forms, and **the
   field in this form (Leo set it in the Source tab, and it read back that way), and the same form
   works when written with `vibe_coding_block_set_data_source_record_filters`.
   **It fails closed:** a user whose field is empty, or who has no record in the users' data source,
-  gets 0 rows, and a by-id request for a record outside the condition returns 404.
+  gets 0 rows, and a by-id request for a record outside the condition returns 404 (on HubSpot;
+  Softr Database answers HTTP 200 with an empty body).
 - **Use AND between rules.** With one rule OR and AND behave the same, but a second rule added
   under OR widens access (2026-10-05).
 - **The braced user-field spellings fail.** On 2026-09-18, on Softr Database, eleven spellings were
@@ -726,13 +737,13 @@ Softr Workflows are automations built from trigger + action nodes, and the MCP c
 
 | Group | Tools |
 |---|---|
-| Workflow lifecycle | `create_workflow`, `get_workflow`, `get_workflow_url`, `list_workflows`, `rename_workflow`, `update_workflow_configuration`, `publish_workflow`, `unpublish_workflow`, `test_workflow` |
-| Node management | `add_node`, `add_branch_node`, `create_branch`, `delete_node`, `duplicate_node`, `rename_node`, `reorder_node`, `reorder_multiple_nodes`, `replace_node`, `replace_trigger_node`, `update_node_inputs`, `update_node_note`, `update_node_continue_on_error`, `update_node_retry` |
-| Discovery / testing | `list_node_types`, `get_node_specifications`, `get_dynamic_input_options`, `test_node`, `get_node_output` |
+| Workflow lifecycle | `workflow_create`, `workflow_get`, `workflow_get_url`, `workflow_list`, `workflow_rename`, `workflow_update_configuration`, `workflow_publish`, `workflow_unpublish`, `workflow_test` |
+| Node management | `workflow_add_node`, `workflow_add_branch_node`, `workflow_create_branch`, `workflow_delete_node`, `workflow_duplicate_node`, `workflow_rename_node`, `workflow_reorder_node`, `workflow_reorder_multiple_nodes`, `workflow_replace_node`, `workflow_replace_trigger_node`, `workflow_update_node_inputs`, `workflow_update_node_note`, `workflow_update_node_continue_on_error`, `workflow_update_node_retry` |
+| Discovery / testing | `workflow_list_node_types`, `workflow_get_node_specifications`, `workflow_get_dynamic_input_options`, `workflow_test_node`, `workflow_get_node_output` |
 
-These are the names as of 2026-10-01. By 2026-10-05 the server delivered them as `workflow_*`
-(`create_workflow` → `workflow_create`, `update_node_inputs` → `workflow_update_node_inputs`); see
-[the rename note](#tool-names--the-2026-10-01-rename).
+These are the current names (live roster, 2026-10-06). Until 2026-10-01 they had no `workflow_`
+prefix (`create_workflow` → `workflow_create`), and older notes, including project docs, still use
+those; see [the rename note](#tool-names--the-2026-10-01-rename).
 
 **The node catalog is huge** — live-enumerated 2026-08-31: **418 node types (58 triggers + 360 actions) across 56 applications.** The parts that matter most for this skill:
 
@@ -756,13 +767,13 @@ These are the names as of 2026-10-01. By 2026-10-05 the server delivered them as
 
 **Build-loop findings (verified live 2026-09-01, first end-to-end production build — 10 workflows):**
 
-- **`create_workflow` instantiates an OLD version of the trigger node.** Immediately call `replace_trigger_node` with the **same trigger type** — the replacement lands at the current version with the current inputs. Example: `updateField` on `SOFTR_TABLES_RECORD_UPDATED` (fire only when a specific field changed) only exists at v1.2.0; the version `create_workflow` instantiates doesn't have it.
-- **FILTER node conditions are set via `update_node_inputs` with inputName `"condition"`** — the value is an `{operator, conditions: [...]}` object. The condition is stored on the FILTER node's **outgoing path**, the same way the Studio builder wires it.
-  - **The official MCP docs disagree:** "Branch and filter conditions can't be set through MCP yet ... deciding what sends a run down each path is something you finish in the builder" (docs.softr.io/mcp/workflows, checked 2026-10-05).
-  - **What stands on each side:** our 2026-09-01 build did set them this way. The FILTER spec today declares `inputs: {}`, but live FILTER nodes still keep their condition on the outgoing path, so the empty spec does not refute the mechanism.
-  - **Until it's re-checked:** after setting a condition over MCP, read the workflow back (`workflow_get`) and confirm the path condition is there. If it isn't, finish the condition in the builder.
+- **`workflow_create` instantiates an OLD version of the trigger node.** Immediately call `workflow_replace_trigger_node` with the **same trigger type** — the replacement lands at the current version with the current inputs. Example: `updateField` on `SOFTR_TABLES_RECORD_UPDATED` (fire only when a specific field changed) only exists at v1.2.0; the version `workflow_create` instantiates doesn't have it.
+- **A FILTER condition written over MCP is inert — set it in Studio** (corrected 2026-10-06; this bullet used to say the MCP writes it). `workflow_update_node_inputs` with inputName `"condition"` accepts an `{operator, conditions: [...]}` object and stores it in the node's `inputs.condition`, a field the engine does not read. The engine evaluates the condition on the FILTER node's **outgoing path** (the `paths` entry whose `fromActionId` is the filter), and only the Studio builder writes that. **A filter built over MCP passes every run.** A 2026-09-19 audit of this very build showed it three ways: the one workflow actually running had empty `inputs` and its whole condition on the path; two others, edited in Studio afterwards, held one condition in `inputs.condition` and a different one on the path, so Studio reads and writes only the path.
+  - **The official MCP docs agree:** "Branch and filter conditions can't be set through MCP yet ... deciding what sends a run down each path is something you finish in the builder" (docs.softr.io/mcp/workflows, checked 2026-10-05), and the FILTER spec declares `inputs: {}`. BRANCH conditions were not tested separately here; treat them the same way.
+  - **How to build one:** add the FILTER over MCP if that is convenient, then open it in Studio, set its clauses and save. Never trust `inputs.condition` as a record of what the filter does; it can disagree with the path.
+  - **How to check one:** read the workflow back with `workflow_get` and find the `paths` entry whose `fromActionId` is the filter; the condition must be there. FILTER nodes cannot be run with `workflow_test_node`, so this read-back is the only check before a real run.
 - **`LOOP_ACTION_GROUP`'s `loopVariables.items` must reference a plain array**, e.g. `$.records` — a `[*]` projection (e.g. `$.records[*].fields.X`) is rejected by the validator. Per-item references **inside** the loop use `{loopActionGroup.<id>:::loopVariables.items.fields.<fieldId>}` (use the bracket form for ids that start with a digit).
-- **`update_node_inputs` batches validate against the STORED node state**, not the batch-in-progress — an update that depends on another update in the same batch fails validation. Split dependent updates into sequential calls.
+- **`workflow_update_node_inputs` batches validate against the STORED node state**, not the batch-in-progress — an update that depends on another update in the same batch fails validation. Split dependent updates into sequential calls.
 - **Test-safety rules** (which `testRunMode` means what in practice):
   - Record-**write** nodes (`SOFTR_TABLES_UPDATE_RECORD` etc.) are `REAL_ONLY` — **never test them against a production workspace**; the test performs the real write.
   - `SOFTR_SEND_EMAIL` is `MOCK_AND_REAL` — **always pass `mode: "mock"`**.