softr-vibe-coding 2.11.1 → 2.13.0

package/CHANGELOG.md

@@ -4,6 +4,15 @@ 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.0] - 2026-10-05
+- Release 2.13.0
+- Record the USER::: user-field Source-condition token (verified 2026-10-05 on HubSpot)
+- Block Visibility is enforced server-side on the records endpoints (verified 2026-10-05)
+- Rewrite HubSpot guidance from the 2026-10-05 verification run
+
+## [2.12.0] - 2026-10-01
+- Add references/browser-checks.md: checking a pushed block in a browser with agent-browser (verified 2026-10-01)
+
 ## [2.11.1] - 2026-10-01
 - Correct four 2.11.0 statements after an independent fact-check of the transcripts
 

package/README.md

@@ -197,6 +197,12 @@ softr-vibe-coding/
 │   │                                 # (Sep 18 2026); Oct 1 2026: tool rename map,
 │   │                                 # push verification by sourceSha256, stub tools
 │   │                                 # after a resume, update_field/update_table fixes
+│   ├── 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
+│   │                                 # shell, eval measurements, the records-trigger
+│   │                                 # write guard proven before any click, what a
+│   │                                 # click sent, screenshots to disk (Oct 1 2026)
 │   ├── advanced-integrations.md      # Shadow DOM CSS isolation
 │   │                                 # Leaflet, Mapbox, TinyMCE, Quill, FullCalendar
 │   ├── native-chrome-styling.md      # Restyle Softr's native shell (header, footer,
@@ -257,7 +263,8 @@ softr-vibe-coding/
     │                                 #   the from: parameter, getting the datasource UUIDs,
     │                                 #   select: as a module-scope identifier, the union-of-
     │                                 #   selects read payload (a conditional select is not
-    │                                 #   privacy), Actions per table (Sep 18 2026)
+    │                                 #   privacy), Actions per table (Sep 18 2026);
+    │                                 #   block Visibility gates its endpoints (Oct 5 2026)
     ├── reading.md                    # useRecords, filtering, sorting, pagination,
     │                                 # metrics, charts, current user; no detail-page
     │                                 # auto-scoping, useRecords ignores enabled:false,
@@ -270,7 +277,8 @@ softr-vibe-coding/
     ├── softr-database.md             # Native DB — field IDs, no rate limits
     ├── airtable.md                   # Column names, PAT vs OAuth, rate limits
     ├── google-sheets.md              # Text formatting, 50-100 user cap
-    ├── hubspot.md                    # CRM objects, Sensitive Data Scopes
+    ├── hubspot.md                    # 15 objects (listed ≠ usable), field model,
+    │                                 # association writes (open), row scoping (Oct 5 2026)
     ├── notion.md                     # Database pages only, Relation workarounds
     ├── coda.md                       # API token auth, limitations
     ├── monday.md                     # API token, Connected Boards

package/SKILL.md

@@ -96,6 +96,7 @@ You generate complete, production-ready Softr Vibe Coding blocks as TypeScript R
    - Array-setting rows keyed by **index**, never by a builder-editable field value
    - Media settings that may start empty (`src: ""`) gated with a conditional render or placeholder — never an unconditional `<img src={setting.src}>`
    - **Deploying through the MCP:** `errors: null` on a push is not proof — compare the push result's `sourceSha256` with `shasum -a 256` of the file you sent, every byte counted, trailing newline included (Softr stores exactly what it receives; the one-byte drift we once blamed on it was a chunked read on our side). Prove deployed == disk *before* editing the same way, with `vibe_coding_block_get_code` and `includeCode: false`, so a Studio-side change is never overwritten. Fetch the full `sourceCode` only when a digest is missing or the hashes differ. Protocol in [references/softr-mcp.md → Verifying a push](references/softr-mcp.md#verifying-a-push--the-deployed-source-is-the-only-proof)
+   - **Then check it in a browser.** Once the push checks pass, check rendering and behaviour in a fresh preview with saves blocked, per [references/browser-checks.md](references/browser-checks.md)
 
 ## What to Clarify
 
@@ -180,6 +181,7 @@ For advanced patterns beyond data fetching, load the relevant reference when the
 | Small reusable patterns — `localStorage` cross-page state, clipboard copy button | [references/common-patterns.md](references/common-patterns.md) |
 | Writing Airtable Automation Scripts / Scripting Extension scripts / Airtable formulas — companion to Softr blocks for cross-table cascades and computed values | [references/airtable-automations.md](references/airtable-automations.md) |
 | The official **Softr MCP server** — Softr DB schema + full record/table/field/database CRUD (deletes included), field-level browsing of connected integrations (Airtable / Google Sheets / Notion / Supabase and more), **creating, editing, versioning, and deploying Vibe Coding blocks directly** (`vibe_coding_block_get_docs`, `vibe_coding_block_create`, ...), push verification by `sourceSha256`, app management/scaffolding, the **Softr Workflows** suite (28 tools, 418-node catalog), and **per-application MCP servers**. Tool names changed on 2026-10-01; the file carries the old → new map | [references/softr-mcp.md](references/softr-mcp.md) |
+| **Checking a pushed block in a browser** — rendering and behaviour in a Softr preview with the agent-browser CLI (ask before installing it): the preview cookie, reaching into the block's shadow DOM through accessibility refs, measuring with `eval`, blocking and proving the save endpoint before any click, reading what a click sent, screenshots to disk | [references/browser-checks.md](references/browser-checks.md) |
 | Restyling Softr's **native shell — header / footer / nav / dropdowns / page background** (not a block; it's Softr chrome, done with global Custom Code CSS): stable selectors vs. hashed classes, floating "island" header+footer, the dropdown blank-space grid fix, the multi-layer page-background stacking, restyle-vs-replace | [references/native-chrome-styling.md](references/native-chrome-styling.md) |
 | Adding a **dynamic date filter or custom filter control to a native List/Grid block** (via a Custom Code Static block, not a Vibe block): drive the block's conditional filter with `{URL_PARAM:…}`, the empty-param "match nothing" wide-range sentinel, inject the control into the filter row and keep it alive across Softr's re-renders | [references/native-block-filters.md](references/native-block-filters.md) |
 | **Editable settings deep-dive** — full hook catalog (incl. verified-undocumented `useLongTextSetting` and the `navigation` array-schema type), settings-first granularity doctrine, heading-line-split and `-text`/`-link` pairing patterns, naming conventions, rename-resets-value gotcha, empty-media gating, key-by-index rule | [references/editable-settings.md](references/editable-settings.md) |
@@ -423,7 +425,11 @@ var askAi = useNavigationSetting({
 - `OPEN_CHAT` — opens Softr's AI chat. **No `destination` or `openIn` needed** — it's the cheapest "Ask AI" button to wire up. **GOTCHA:** Softr's AI pulls context from the block that triggered the chat, NOT from the page. If the block has no data source connected, `chat/prepare` returns HTTP 500 ("Failed to prepare AI assistant") even though the chat panel opens. Fix: in Softr Studio, connect the block to whatever data source the AI should read from — even if the block doesn't read or write any records itself, the connection is what gives the AI context. Verified by direct experiment, May 2026: a button-only helper block with no data source caused this exact failure; connecting it to the same table as the main block fixed it without any code change.
 - `OPEN_URL` — opens an external URL. Needs `destination` (the URL) + `openIn` (`"SELF"` | `"TAB"`).
 - `OPEN_PAGE` — navigates to a Softr page in-app. Needs `destination` (page path) + `openIn` (`"SELF"` | `"TAB"` | `"MODAL"`).
-- `TRIGGER_CUSTOM_WORKFLOW` — runs a Softr workflow. The documented setting shape is `{ action: "TRIGGER_CUSTOM_WORKFLOW" }` with no `destination` (same shape as `OPEN_CHAT`); the builder picks the workflow in the block's settings panel. Not verified live whether a `destination` is also accepted — don't rely on one. The workflow-side receiving end is the Softr Apps trigger **"Run Custom Workflow action triggered"** in the workflow node catalog (name-based match, not wired live) — workflows themselves are buildable via MCP; see [references/softr-mcp.md](references/softr-mcp.md#workflows).
+- `TRIGGER_CUSTOM_WORKFLOW` — runs a Softr workflow.
+  - **Setting shape:** the documented shape is `{ action: "TRIGGER_CUSTOM_WORKFLOW" }` with no `destination`, the same shape as `OPEN_CHAT`. The type also carries an optional `actionId`. The builder picks which workflow it points at. Whether a `destination` is also accepted is not verified live, so don't rely on one.
+  - **Calling it from code:** besides `<NavigationAction>`, the live developer guide documents `navigate(setting, { recordId, datasourceId })` ("Runs the workflow with recordId and datasourceId"). It is callable from a mutation's `onSuccess`, e.g. to run a workflow on a record `useRecordCreate` just made (documented 2026-10-05; not yet run end to end by us).
+  - **The receiving end** is the Softr Apps trigger **"Run custom workflow"** (`SOFTR_APPS_TRIGGER_WORKFLOW`) in the workflow node catalog. The vibe path documents only `recordId` and `datasourceId` as payload, and the trigger is browser-callable, so have the workflow re-read the record rather than trust its input.
+  - Workflows themselves are buildable via MCP; see [references/softr-mcp.md](references/softr-mcp.md#workflows).
 
 When the action navigates to a record-specific page, pass the runtime record id via the `recordId` prop on `<NavigationAction>` (not on the setting) so Softr can resolve dynamic URLs:
 
@@ -595,10 +601,13 @@ Non-negotiable rules. Most are enforced by the Softr platform (compiler, validat
     endpoint is per block + connection and returns the UNION of every field named by any READ
     `q.select` on that connection, to every viewer. A second or ternary select "only for admins"
     hides nothing. Put a private field on a **second connection of the same table** (allowed) read
-    only by a hook non-privileged browsers never run, or in a group-gated block. Page VIEW permission
-    is enforced on these endpoints, but on a page any logged-in user may view, every connected
-    datasource is readable by any logged-in user who crafts the request -- Source conditions are the
-    only server-side ROW gate. Verified live 2026-09-18. See
+    only by a hook non-privileged browsers never run, or in a group-gated block. Two all-or-nothing
+    gates are enforced on these endpoints (list and by-id): page VIEW permission and the **block's own
+    Visibility** -- a viewer outside the block's user group gets 403 (verified 2026-10-05). So a block
+    gated to a staff group may read unfiltered connections for a staff view. The gate is per block:
+    the same table connected to an ungated block, on a page any logged-in user may view, is readable
+    by any logged-in user who crafts the request. Source conditions remain the only server-side ROW
+    gate. Verified live 2026-09-18 and 2026-10-05. See
     [datasources/multi-datasource.md](datasources/multi-datasource.md#one-connection--one-read-payload-the-union-of-its-selects).
 24. **Multi-datasource: `select:` is a plain module-scope identifier** -- a ternary
     (`select: a ? X : Y`) cannot be attributed to a connection and the query returns `fields: {}`, no

package/datasources/hubspot.md

@@ -1,51 +1,404 @@
 # HubSpot
 
+*Rewritten 2026-10-05 from a read-only verification run: five investigations and four adversarial
+fact-checks against a HubSpot-connected demo app on an EU portal, plus Softr's and HubSpot's live
+docs. Labels used below: **verified live** = observed that day through the Softr or HubSpot MCP;
+**documented** = Softr or HubSpot docs say so; **inferred** = reasoned, not observed;
+**unverified** = nobody has tested it. That run made no writes, so nothing on the write side of
+this page is "verified live". It is documented at best.*
+
 ## Overview
-CRM platform used as a data source for Softr. Requires a Business or Enterprise plan in Softr. Connects via OAuth.
+
+CRM used as a Softr data source, connected by OAuth.
+
+- **Softr plan:** Business or Enterprise (documented).
+- **Connecting needs a HubSpot Super Admin** (documented).
+- **HubSpot tier, for what the integration itself reads and writes:** contacts, companies, deals,
+  tasks and tickets work on HubSpot Free (documented, HubSpot's product catalog). Custom objects need
+  HubSpot Enterprise (documented). HubSpot's *own* workflows need Professional or higher, and
+  ticket-based workflows need Service Hub Professional or Enterprise (documented). A Softr workflow
+  does not need either ([Workflows](#workflows-softr-workflows-with-hubspot)).
 
 ## Connection Setup
-1. In Softr admin, go to Data Sources and select HubSpot.
-2. Authenticate via OAuth with your HubSpot account.
-3. Select the HubSpot object type to connect (Contacts, Companies, Deals, etc.).
-4. If accessing sensitive fields, ensure Sensitive Data Scopes are enabled in your HubSpot app settings.
-
-## Vibe Coding Field IDs
-Use the Field Inspector block to determine exact field IDs for HubSpot properties. Default HubSpot properties use their internal API names (e.g., `"firstname"`, `"dealstage"`, `"company"`). Custom properties use the internal name assigned by HubSpot when created.
-
-## Supported Fields
-
-**Supported HubSpot Objects:**
-- Contacts
-- Companies
-- Deals
-- Tickets
-- Notes
-- Tasks
-- Custom Objects
-
-| Field Type           | Writable  | Notes |
-|----------------------|-----------|-------|
-| Default Properties   | Yes       | All standard HubSpot properties for the connected object |
-| Custom Properties    | Yes       | Custom properties created in HubSpot |
-| Associations         | Read-only | Relational data between objects. Displayed via Linked List Blocks in Softr. |
-| Calculation          | Read-only | |
-| Rollup               | Read-only | |
-| Count                | Read-only | |
-| Formula              | Read-only | |
-
-## Rate Limits
-HubSpot enforces its own API rate limits based on your HubSpot plan tier. Softr requests count against your HubSpot API quota. Refer to HubSpot's documentation for current limits on your plan.
+
+1. In Softr Studio, go to Data Sources and select HubSpot.
+2. Authenticate via OAuth as a HubSpot Super Admin.
+3. Pick the HubSpot object to connect (see [Supported objects](#supported-objects)).
+4. Some HubSpot fields and objects need **Sensitive Data scopes** for API access (documented). If a
+   field you expect comes back empty or missing, check those scopes first.
+
+An object appears only if HubSpot grants Softr access to it. Reconnecting restores one that is
+missing (documented).
+
+**Through the MCP** (verified live 2026-10-05): `integration_list_databases` on a HubSpot integration
+returns the object ids. For HubSpot the `databaseId`, the `tableId` and the `tableName` are all that
+same object id (`tickets`, `line_items`, …), so pass the object id three times to
+`integration_list_table_fields` and `vibe_coding_block_connect_data_source`.
+
+## Supported objects
+
+Softr's docs list **15 objects** since softr-public-documentation PR #127 (merged 2026-09-24; the
+list had 7 before). The live integration returned **14 object ids**, i.e. all except Custom Objects,
+which that portal did not have (verified live 2026-10-05).
+
+**Listed does not mean usable, and usable does not mean writable.** Softr publishes no per-object
+write matrix, and no vibe-block write to any HubSpot object has been tested.
+
+| Object | Id | Primary field | What to know |
+|---|---|---|---|
+| Contacts | `contacts` | `hs_full_name_or_email` | HubSpot Free. The natural users table. Has no `associatedcompanyid` in Softr (see [Field model](#field-model)) |
+| Companies | `companies` | `name` | HubSpot Free |
+| Deals | `deals` | `dealname` | HubSpot Free. Stage ids are portal-specific |
+| Tickets | `tickets` | `subject` | HubSpot Free. A create needs `subject` and `hs_pipeline_stage` ([Writing](#writing)) |
+| Tasks | `tasks` | `hs_task_subject` | HubSpot Free |
+| Notes | `notes` | `hs_body_preview` | A create needs `hs_timestamp`. HubSpot says a note should be associated with at least one record, so notes depend on the [association-write question](#association-writes--an-open-question) |
+| Leads, Listings, Appointments | `leads`, `listings`, `appointments` | — | Listed live; not examined in the 2026-10-05 run |
+| Projects | `projects` | `hs_name` | **Must be activated in HubSpot by a Super Admin** (Data Management > Data Model; documented). On a portal where it apparently wasn't, Softr still listed the object, but its `hs_pipeline` / `hs_pipeline_stage` had **zero choices** (verified live). HubSpot requires both on create (documented), so no create can succeed there |
+| Products | `products` | `name` | Catalog entries. Links go only to deals and to other products, none to companies or contacts |
+| Line Items | `line_items` | `name` | **Need a parent object** (deal, quote, subscription, invoice or payment link; documented). No links to companies or contacts |
+| Invoices | `invoices` | `hs_number` | **Need Commerce Hub** (documented). A draft needs only `hs_currency`; moving one to Open needs an associated contact and at least one line item (HubSpot API docs) |
+| Subscriptions | `subscriptions` | `hs_name` | **Need Commerce Hub. Treat as read-only:** HubSpot's API needs HubSpot payments or Stripe for writes, and it cannot set associations at all (documented) |
+| Custom Objects | — | — | **Need HubSpot Enterprise** (documented). Appear only when they exist in the portal |
+
+Softr's Workflows HubSpot page says Add / Update / Delete work "across every HubSpot object". That is
+a marketing line. HubSpot's own API rules above contradict it for subscriptions, and for projects
+until activation. Don't quote it to a client as a write guarantee.
+
+**Native blocks vs vibe blocks.** Softr's HubSpot page says "You can connect only one object type to
+one block". That rule is for native blocks. A vibe block connects several objects with
+`datasource.define` plus `from:` on every hook (see
+[multi-datasource.md](multi-datasource.md)).
+
+## Field model
+
+*Verified live 2026-10-05 via `integration_list_table_fields` and `vibe_coding_block_get_settings`,
+unless marked otherwise.*
+
+- **`fieldReferenceKey` is `"id"`.** `q.select()` uses HubSpot internal property names (`firstname`,
+  `dealstage`, `hs_pipeline_stage`). Custom properties use the internal name HubSpot gave them.
+- **Associations are `LINKED_RECORD` fields named `associations.<x>`**, with
+  `options.linkedTableId` set to the target object. Examples:
+  - deals: `associations.company` ("Associated Company"), `associations.contact`,
+    `associations.deal_to_company` ("Associated Primary Company")
+  - tickets: `associations.company`, `associations.contact`, `associations.ticket_to_company`
+    ("Associated Primary Company"), `associations.deal`. Tickets have 13 in all.
+  - companies: `associations.company_to_deal`, `associations.company_to_ticket`,
+    `associations.company_to_contact` (the "with Primary Company" links), 20 in all.
+
+  Read them as you would any linked field: an association can arrive as a single `{ id, label }`
+  object as well as an array of them, so normalise before you `.map()` (see
+  [reading.md](reading.md#filtering-by-a-linked-record-server-side)). The single-object case was
+  seen in a Softr workflow's Find record output; the vibe-hook read shape for HubSpot is unverified.
+- **SELECT fields carry id→label choices** in `options.choices`, and HubSpot ids are not labels.
+  - **Deals:** stage ids are portal-specific. The live portal had `6183367908` = Initial Contact
+    … `closedwon` = Closed Won, in pipeline `default` ("Sales Pipeline").
+  - **Tickets:** they use `hs_pipeline_stage`, which held `1` New, `2` Waiting on contact,
+    `3` Waiting on us and `4` Closed, all in pipeline `0` ("Support Pipeline"). That is a fresh
+    portal's default, so read the choices from the schema rather than hardcoding them.
+  - **Owners:** `hubspot_owner_id` choices are numeric HubSpot owner ids, labelled
+    "Name (email)".
+- **`hubspot_owner_email` and `hubspot_owner_name` are fields Softr derives, not HubSpot
+  properties.** HubSpot returns them as `propertiesNotFound`, yet they appear as SELECT fields on
+  every object. Filtering on them is untested, because HubSpot's search has no such property to
+  filter on. Filter and write ownership through **`hubspot_owner_id`**, which is the real property.
+- **Softr exposes only a subset of HubSpot's properties.** Tickets showed 36 of about 122 HubSpot
+  properties, plus the 2 derived owner fields; invoices showed 26 of about 94. Missing on tickets
+  are `hs_all_associated_contact_emails`, `hs_v2_date_entered_*`, `hs_resolution`, `hs_ticket_id`,
+  `hs_tag_ids` and `hs_object_source_label`. Softr's docs say "All default HubSpot object
+  properties" are supported; the live schema contradicts that. **Custom properties are exposed:**
+  the portal's custom ticket properties (`issue_category`, `issue_severity`) were in the schema.
+  Before designing around a property, confirm it is in the field list.
+- **Field metadata has no read-only flag.** Each field carries only `id`, `name`, `type` and
+  `options`. HubSpot-computed properties (`hs_object_id`, `createdate`, `hs_lastmodifieddate`,
+  `num_associated_*`) look exactly like writable ones.
+- **Contacts have no `associatedcompanyid` in Softr**, and HubSpot also returned it as not found. A
+  contact reaches its company only through `associations.company` /
+  `associations.contact_to_company`, or through the free-text `company` property.
+- `hs_file_upload` on tickets is an ATTACHMENT in Softr but a plain string property in HubSpot.
+  Writing it is untested.
+
+## Writing
+
+| Field kind | Writable? | Evidence |
+|---|---|---|
+| Default properties | Yes | Documented (Softr's HubSpot page); untested from a vibe block |
+| Custom properties | Yes | Documented; untested from a vibe block |
+| Softr computed fields (Calculation, Rollup, Count, Formula) | Read-only | Documented. These are the **only** fields Softr's page lists as read-only |
+| HubSpot-computed properties (`hs_object_id`, `createdate`, `hs_lastmodifieddate`, `num_associated_*`) | Presumably not | Inferred from HubSpot; nothing in Softr's metadata says so |
+| Associations (`associations.*`) | **Unverified** | [Open question below](#association-writes--an-open-question) |
+| `hubspot_owner_email` / `hubspot_owner_name` | Don't | Softr-derived; write `hubspot_owner_id` instead (inferred) |
+
+- **Ticket create:** HubSpot requires `subject` and `hs_pipeline_stage`. `hs_pipeline` is optional
+  when the portal has one ticket pipeline, because the default is used (documented, HubSpot API).
+  **Note create:** `hs_timestamp` is required (documented).
+- **SELECT write format is unknown for HubSpot.** On Softr Database, vibe hooks write a SELECT by
+  its **label** (verified 2026-08-25; see [writing.md](writing.md#dropdown--single-select-softr-database)).
+  On HubSpot the id and the label differ (`'1'` vs `'New'`, `'6183367908'` vs `'Initial Contact'`),
+  and which one the connector accepts has not been tested. Test both on a throwaway record before
+  building a form on it.
+
+### Association writes — an open question
+
+**Unverified.** This page used to say "Associations are read-only in Vibe Coding blocks". That
+statement had no source and was removed on 2026-10-05. What is actually known:
+
+- Softr's HubSpot page lists only computed fields as read-only. It documents associations for
+  display only: the Linked List block, the Associated Object IDs property, and visibility
+  conditional filters. It never says they are read-only (documented; the January 2025 version reads
+  the same).
+- Softr's generic "Mapping Fields for Actions" page auto-maps "every writable column" into native
+  Add / Update record forms. Linked-record fields "are included", as dropdowns or multi-selects, and
+  computed fields are skipped (documented, not HubSpot-specific).
+- A Softr staff post in the community HubSpot beta thread (2024-03-26) announced "You can now
+  associate Tickets with other Tickets". That is a community announcement about native blocks, not
+  documentation.
+- HubSpot's ticket-create API accepts inline associations, so the connector *could* write them
+  (documented, HubSpot side).
+- No vibe-block test exists, and the field metadata cannot settle it.
+
+**If you are cleared to run a write test** (it creates real HubSpot records, so only on a disposable
+portal or with the owner's go-ahead):
+
+1. Create one **plain** ticket first (`subject`, `hs_pipeline_stage`). This settles the
+   SELECT id-vs-label question on its own.
+2. Then add `associations.company` / `associations.contact` as `["<id>"]` (the Softr Database
+   string-array shape), falling back to `[{ id }]` (the Airtable shape); see
+   [writing.md](writing.md#linked-record-format-for-mutations). Check with
+   `vibe_coding_block_get_settings` that the ADD_RECORD action still exists and lists the
+   association field. On Airtable, an unresolvable field in a create select silently disables the
+   whole action ([airtable.md](airtable.md#maintainability-gotcha)); whether a non-writable
+   association does the same is unknown.
+3. Check the result in HubSpot: was the link created, and is `associations.company` the unlabeled
+   link (type 339) or the primary one (26)? Repeat with `useRecordUpdate`, to learn whether it adds
+   links or replaces them.
+
+**Documented fallback: a Softr workflow calls HubSpot's associations API.**
+
+- **The step:** a **Run custom code** step (`CUSTOM_CODE` v1.2.0) with the HubSpot integration
+  attached. `fetch()` calls to `api.hubapi.com` then carry that integration's credentials, with no
+  token in the code.
+- **Plan and testing:** the step needs a paid Softr plan, and it is `REAL_ONLY`, so a test run
+  writes for real.
+- **Limits:** about 2 minutes per run, and up to 20 fetches per second.
+- **The HubSpot calls** (associations v4):
+  - Unlabeled: `PUT /crm/objects/2026-09/ticket/{ticketId}/associations/default/company/{companyId}`,
+    and the same pattern for `contact`.
+  - Labeled, e.g. primary company: `PUT /crm/objects/2026-09/ticket/{ticketId}/associations/company/{companyId}`
+    with body `[{ "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 26 }]`.
+  - Type ids: ticket→contact **16**, ticket→company **339**, ticket→primary company **26**.
+  - `DELETE` on the same path unlinks.
+  - HubSpot's ticket-create endpoint also accepts an `associations` array, so one step can create
+    the ticket already linked.
+- **Starting it from the block:** call `navigate(setting, { recordId, datasourceId })` on a
+  `TRIGGER_CUSTOM_WORKFLOW` setting inside `useRecordCreate`'s `onSuccess` (see SKILL.md's
+  NavigationAction section). The vibe path documents only `recordId` and `datasourceId` as payload.
+  The trigger is a browser-callable endpoint, so the workflow should re-read the ticket from HubSpot
+  rather than trust what it receives.
+- **No block wiring:** a `HUBSPOT_RECORD_CREATED` trigger on tickets plus the same custom-code step
+  can link each new ticket by a requester-email property. This also catches tickets created in
+  HubSpot itself. The cost is trigger latency (unknown, see below) and a run for every new ticket.
+- **Why the block can't do it itself:** `useProxyFetch` is documented for REST API sources only.
+  Call API authenticates only REST_API integrations and needs Professional or higher, so it would
+  need a HubSpot private-app token stored as a REST integration (inferred).
+- **HubSpot-side route:** a HubSpot workflow's "Create associations" action needs Pro or
+  Enterprise, and ticket-based workflows need Service Hub Pro or Enterprise (documented). It
+  matches records by exact, case-sensitive property value.
+
+## Row scoping — who sees which records
+
+A connection's **Source conditions are the only server-side row gate**. A `where` in block code is a
+request parameter the caller controls, not access control. See
+[../references/softr-mcp.md](../references/softr-mcp.md#what-the-server-enforces-on-a-blocks-data-endpoints)
+(verified 2026-09-18 on Softr Database; on HubSpot 2026-10-05, below).
+
+The **block's Visibility** is enforced on the same endpoints, all or nothing (verified 2026-10-05 on
+HubSpot). A block gated to an "Account managers" condition group returned every deal and ticket to
+members from connections with no Source condition, and 403 on list and by-id to clients, a
+Softr-only user and logged-out visitors. So a staff view can be a group-gated block with
+unfiltered connections. The same tables on an ungated block are open to anyone who may view the
+page ([details](multi-datasource.md#one-connection--one-read-payload-the-union-of-its-selects)).
+
+- **Scope clients by company with the user's own field** (verified 2026-10-05). A Source
+  condition `associations.company IS_ONE_OF ["USER:::associations.company"]`, logical operator
+  AND, on the deals and the tickets connections gave each client only their own companies'
+  records: Dana 1 deal and 1 ticket, Tom 1 deal. The users table is the contacts table, so
+  `USER:::associations.company` is the logged-in contact's own company association. The token is
+  `USER:::<user field id>`, **no braces**, as the entire value. It was set in Studio's Source tab
+  and over MCP alike ([details](../references/softr-mcp.md#logged-in-user-values-in-source-conditions)).
+  - **It fails closed.** A synced contact with no company, a Softr-only user and account managers
+    without a company all got 0 rows. By-id reads of other companies' records returned 404.
+  - **So staff need their own block**, gated to their group, with unfiltered connections (above).
+    Widening the client condition for them would widen it for everyone.
+  - **Use AND.** With one rule OR and AND behave the same, but a second rule added under OR widens
+    access.
+- **The email token is different: `{USER:::EMAIL}`, with braces**, as the entire value. It is
+  verified on Softr Database and untested on HubSpot. For any other user field, pick it once in the
+  block's Source tab and read `dataSources[].condition` back with `vibe_coding_block_get_settings`.
+- **Community evidence for association scoping in native blocks.** In
+  [community.softr.io/t/hubspot-conditional-filter/10572](https://community.softr.io/t/hubspot-conditional-filter/10572)
+  (September 2024), a native filter "ticket's Associated Company ID = logged-in user's Associated
+  Company ID" worked after a Softr fix. It used an older field model; `associatedcompanyid` is no
+  longer on Softr's contacts. Softr's HubSpot page also says "You can also use associated objects
+  in Visibility Conditional Filters". The vibe-block version above is the verified one.
+- **Fallback: put the user's email on the records**, for scoping that no user field can express. Add
+  a custom text property, e.g. "Portal requester email" on tickets or "Account manager email" on
+  companies and deals. Write it when the record is created, and compare it with `{USER:::EMAIL}`
+  using **IS**. If the property holds a list of emails and you use CONTAINS, mind the substring
+  trap: `bob@x.com` also matches `jbob@x.com` (verified 2026-09-18 on Softr Database). The value is
+  written by the browser, so a determined user could tamper with it on create. That is acceptable
+  for scoping a demo; production needs a server-side source of identity. The user's company
+  association above lives in HubSpot instead, out of reach of a block with no contact write action.
+- **Owner scoping.** `hubspot_owner_id` is the real property, but on a contact it names that
+  contact's owner, not the contact. Scoping "my deals" for an account manager would need a custom
+  contact property holding their own owner id, read through `USER:::<field id>` (untested). For a
+  team-wide staff view, a group-gated block with unfiltered connections needs no owner filter at
+  all. Owners are also HubSpot users, i.e. HubSpot seats.
+
+**Filter limits** ([docs.softr.io/troubleshooting/troubleshooting-hubspot-errors](https://docs.softr.io/troubleshooting/troubleshooting-hubspot-errors)):
+
+- **Softr's numbers:** 5 groups × 6 filters, 18 filters per block in total, and only **4 AND
+  filters on a block with an Edit button**.
+- **What counts:** conditional filters, inline search and filter, and action-visibility filters
+  (documented). A code `where` presumably lands in the same HubSpot search request (inferred).
+- **AND and OR are swapped on Softr's page.** It calls the groups "AND" and the filters inside them
+  "OR". HubSpot's search API is the other way round: filters inside a group are ANDed and groups are
+  ORed, with the same 5 / 6 / 18 caps (documented).
+- **HubSpot search also caps:** a query returns at most 10,000 results (documented). Associations
+  are filtered through the `associations.{objectType}` pseudo-property, which does not cover
+  custom-object associations (documented).
+- **The MCP's record-filter tool** takes one flat AND/OR list per connection, and each value is an
+  array of strings. ARRAY fields allow `IS`, `IS_ONE_OF`, `IS_NONE_OF`, `HAS_ALL_OF`, `IS_EMPTY` and
+  `IS_NOT_EMPTY`, with no `CONTAINS` (verified 2026-10-05 from the tool's description).
+
+## Rate limits
+
+- **110 requests per 10 seconds per HubSpot account** for apps distributed through the HubSpot
+  Marketplace. The search API is counted separately, and HubSpot's API-limit add-on does not raise
+  this (documented). That Softr's connection counts as such an app is **inferred**: Softr has a
+  Marketplace listing.
+- **The CRM search API allows 5 requests per second per account** (documented). How Softr turns
+  hook calls into HubSpot calls is not documented. If list reads go through search, several
+  HubSpot connections on one page, times concurrent users, can reach that limit (inferred).
+- **New and updated records take "a few moments" to appear in search results** (documented). A
+  `refetch()` right after a mutation may therefore still return the old value (inferred). Prefer
+  updating the UI optimistically from the mutation's own result.
+- Softr also caches data-source reads ("short-term" on one docs page, "24 hour" on another; scope
+  unspecified). See [overview.md](overview.md).
+
+## User sync
+
+- **HubSpot supports 2-way user sync** (documented). Email is required and is the unique
+  identifier. Name, Magic link, Avatar, Created date and Last seen date map too. All other contact
+  properties remain usable in user groups, conditional filters and `useCurrentUser({ properties })`.
+- **Filtered sync** ("Selected", with rules) is available (documented; listed under Business on
+  Softr's pricing page).
+- **Deleting a Softr user deletes the HubSpot contact.** Deleting in HubSpot does not delete the
+  Softr user (documented). The filtered-sync option "Delete their user account" also removes the
+  data-source record (documented).
+- **`createUserInDatasource` defaults to `true`** on `application_create_user_connection`, so users
+  added in Softr create HubSpot contacts. To keep people out of HubSpot (e.g. internal account
+  managers), use the "Let the user only exist in the Softr app" option (documented).
+- **Sync is continuous only on a published app.** In Studio, or on an unpublished app, it runs on
+  login, on publish and when the Users tab is opened (documented).
+- **Even on a published app the lag varies** (verified 2026-10-05). A new HubSpot contact appeared
+  as a Softr user after 33 s in the morning; two more, created later that day, took 24 min. Never
+  assume real time: confirm the user exists with `application_list_users` before testing as them.
+- **An app has one users table** (documented). Account managers are therefore either contacts in the
+  same table or Softr-only users.
+- **`useCurrentUser().id` exists only when user sync is on** (documented). Whether it equals the
+  HubSpot contact id is **unverified**.
+- **User Caching** (App Settings > Advanced) keeps the **logged-in user's own record** for 2 minutes.
+  Softr recommends leaving it on, and suggests turning it off when user-group membership updates
+  slowly (documented). It affects group membership and logged-in-user values, not how fresh other
+  records are. A ticket-status lag comes from elsewhere: the search delay above, data-source
+  caching, or workflow trigger latency.
+- **Condition-based user groups on a synced HubSpot property work** (verified 2026-10-05). For a
+  select contact property the rule is subject `USER:portal_role` (the property's internal name),
+  type `ARRAY`, operator `IS_ONE_OF`, value `[<choice id>]`: the choice id, not the label. That
+  syntax is for **user groups**. In a block's Source condition the subject form returned 400; there
+  the user field goes in the value, as `USER:::<field id>` (see above). Membership then lives in
+  HubSpot: anyone who can edit that property there can grant the group's access.
+- **`application_list_users` is not a membership check.** It showed `userGroups: []` for every
+  user, including members of condition groups that demonstrably applied (verified 2026-10-05).
+  Test membership by what the user can reach, e.g. preview as them against a group-gated block.
+
+## Audit trail
+
+- **HubSpot records a connected app's writes with change source "Integration"**, not the person who
+  made the edit. Only edits made in HubSpot's own UI show a user's name and email (documented). A
+  2022 HubSpot developer changelog adds that the app's ID is recorded.
+- **Integration writes cannot be restored with one click.** Property history offers Restore only for
+  CRM UI edits, imports and workflows (documented).
+- What HubSpot puts in "Updated by user ID" for a Softr write is **unknown**. Records written by a
+  different connector carried an ID that belonged to no user in the portal (verified live; not a
+  Softr write).
+- **Workaround:** write a "Last edited in Softr by" custom property from `useCurrentUser().email`
+  on every create and update. The value is self-reported, because the browser sends it. That is fine
+  for a trail, but it is not security.
+- Emails sent by a Softr workflow's Send email step don't appear on the HubSpot record's timeline.
+  Logging them as a note would need an association write (inferred).
+
+## Workflows (Softr Workflows with HubSpot)
+
+*Catalog and specs verified live 2026-10-05.*
+
+- **Triggers: `HUBSPOT_RECORD_CREATED` and `HUBSPOT_RECORD_UPDATED`** (v1.0.0, both `REAL_ONLY`).
+  - Their only inputs are `integrationId`, `type` (the object id, e.g. `"tickets"`) and an optional
+    `objectTypeId`.
+  - There is **no property filter**. Softr Tables and Airtable "record updated" triggers have an
+    `updateField` option; these don't.
+  - Whether a data-source integration connected before triggers existed can run them is untested.
+    Zoho's docs say to reconnect in that case.
+- **Latency is unknown.**
+  - Neither trigger appears on Softr's Trigger Types page, and the HubSpot Workflows page lists
+    actions only.
+  - The Trigger Types page says only Softr Tables, Calendly, Attio and Zoho CRM are instant and
+    "other services use background polling". That sentence is wrong for Stripe (Softr registers a
+    webhook) and for DocuSign (pushed by Docusign Connect), so it can't be relied on for HubSpot
+    either.
+  - Time a real run before promising anything.
+- **Record updated fires on any change to any record of that object.** Expect it to fire on
+  HubSpot's internal recalculations and on Softr's own writes too (inferred). Build two things in
+  from the start:
+  - **A stage filter.** Note that a filter on the *current* stage alone fires again on every later
+    edit to a ticket already in that stage.
+  - **A dedupe property**, e.g. `softr_last_notified_stage`: filter on `stage != it`, and set it
+    after acting. Softr exposes no `hs_v2_date_entered_*` property to tell a stage entry apart from
+    other edits.
+- **Actions:** Add record (`MOCK_AND_REAL`), Update record (`REAL_ONLY`), Update multiple records,
+  Delete record, Delete multiple records, Find record and Find multiple records.
+  - **There is no associate action.**
+  - Add and Update take a `fields` input of type `DATA_SOURCE_FIELDS`. Whether `associations.*`
+    is offered there, or actually written, is unknown.
+- **Find record output** is `{ id, fields }`. Associations arrive as lists of `{ id, label }`
+  (e.g. `fields["associations.contact"][*].id`), though some single-label associations come back
+  as one `{ id, label }` object. SELECT fields arrive as `{ id, label }`, so compare on `.id`. This
+  was seen on a companies sample from a mock test; the same shape on tickets is inferred.
+- Workflow nodes call the workspace's HubSpot integration directly, with `type` set to the object
+  id, so an object need not be connected to any block for a workflow to use it.
 
 ## Gotchas
-- **Business or Enterprise Softr plan required.** HubSpot is not available on Free or Basic plans.
-- **Sensitive Data Scopes** must be explicitly enabled in HubSpot for certain fields (e.g., email content, certain contact properties). Without this, those fields return empty.
-- **Associations are read-only** in Vibe Coding blocks. Use Linked List Blocks to display related records (e.g., Deals associated with a Contact).
-- **Custom Objects** require that the object is properly configured in HubSpot with the necessary scopes granted during OAuth.
-- **Deal stages and pipeline data** use internal IDs, not display labels. Map these in your block logic if you need human-readable values.
+
+- **Listed is not usable.** Projects needs activation, Subscriptions are read-only, Invoices and
+  Subscriptions need Commerce Hub, Line Items need a parent, Custom Objects need HubSpot Enterprise.
+- **Association writes are unverified**, not "read-only". Don't build a form that depends on them
+  until a write test has passed. The fallback is a workflow with Run custom code.
+- **SELECT ids ≠ labels**, and the write format is unknown. Take display labels from the schema's
+  choices (`useFieldOptions` should serve them, but that is untested on HubSpot); don't hardcode
+  stage ids across portals.
+- **The owner email and name fields are Softr's, not HubSpot's.** Filter and write
+  `hubspot_owner_id`.
+- **Only part of each object's properties is exposed.** Check a property is in the field list
+  before relying on it.
+- **Mind the filter budget on blocks with an Edit button:** 4 AND filters, counting Source
+  conditions, inline search and action-visibility filters together.
+- **Scope client rows with `USER:::associations.company`, no braces,** in a Source condition
+  joined by AND. It fails closed, so give staff their own group-gated block.
 
 ## Best For
+
+- Client and partner portals on top of HubSpot-managed contacts and companies
+- Support ticket portals
 - Sales portals and deal rooms
 - CRM dashboards for teams or clients
-- Support ticket portals
-- Partner portals with HubSpot-managed contacts
 - Any app where HubSpot is the system of record

package/datasources/multi-datasource.md

@@ -91,7 +91,7 @@ it behaves as a **union** of both branches, not a choice between them. Which is
 
 ## One connection = one read payload (the union of its selects)
 
-*Verified live 2026-09-18.*
+*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
@@ -131,11 +131,20 @@ function AdminNotes({ recordId }) {
 Or put the private field in a separate block whose visibility is group-gated.
 
 Know what this buys you. Not *rendering* the hook keeps the field out of ordinary browsers, but
-the endpoint still exists: page VIEW permission is enforced on it (a viewer who cannot view the
-page gets a 403), yet on a page any logged-in user may view, **every connected datasource is
-readable by any logged-in user who crafts the request**. A connection's **Source conditions are
-the only server-side ROW gate**; the only server-side gate on the *field* is a page or block the
-viewer cannot see. See [../references/softr-mcp.md](../references/softr-mcp.md#what-the-server-enforces-on-a-blocks-data-endpoints).
+the endpoint still exists. Two all-or-nothing gates are enforced on it, list and by-id: page VIEW
+permission, and the **block's own Visibility** (`predefinedUserGroup` + `customUserGroupIds`). A
+viewer outside either gets a 403 (block gate verified 2026-10-05, on HubSpot). Past those gates, on
+an ungated block on a page any logged-in user may view, **every connected datasource is readable by
+any logged-in user who crafts the request**. A connection's **Source conditions are the only
+server-side ROW gate**; the only server-side gate on the *field* is a page or block the viewer
+cannot see.
+
+**A block gated to a user group may therefore read unfiltered connections** (verified 2026-10-05).
+A staff dashboard gated to an "Account managers" group, with no Source condition on its deals and
+tickets connections, gave both members all 41 deals and 16 tickets, and gave clients, a Softr-only
+user and logged-out visitors 403 on list and by-id. The gate belongs to the block, not the table:
+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.

package/datasources/overview.md

@@ -32,7 +32,7 @@
 - Data is connected to **dynamic blocks** (List, Grid, Table, Kanban, Chart, Form, etc.) in the Softr Studio.
 - **Multiple data sources** can coexist in a single Softr app, even on the same page.
 - Softr IP addresses to whitelist for secured databases: `3.120.79.212`, `3.123.159.186`, `52.58.246.121`
-- **AI-assisted schema discovery via MCP:** the official Softr MCP server (`https://mcp.softr.io/mcp`) reads schema and field references directly from the workspace -- Softr Databases in full, plus browsable field-level access to connected **Airtable, Google Sheets, Notion, and Supabase** integrations. Other external sources still need the manual workflows in [fields.md](fields.md). See [../references/softr-mcp.md](../references/softr-mcp.md).
+- **AI-assisted schema discovery via MCP:** the official Softr MCP server (`https://mcp.softr.io/mcp`) reads schema and field references directly from the workspace -- Softr Databases in full, plus browsable field-level access to connected external integrations, among them **Airtable, Google Sheets, Notion, Supabase and HubSpot** (HubSpot browsed live 2026-10-05; the full type list is in softr-mcp.md). Sources the MCP cannot browse still need the manual workflows in [fields.md](fields.md). See [../references/softr-mcp.md](../references/softr-mcp.md).
 
 ## User Sync Availability
 

package/datasources/reading.md

@@ -308,6 +308,13 @@ var user = useCurrentUser();
 // Note: `id` is only present when user sync is enabled.
 ```
 
+**`where: q.text("ownerEmail").is(user.email)` is not access control.** It shapes the UI, but the
+caller controls that parameter. To restrict rows to the logged-in user on the server, put the
+condition in the connection's Source conditions, as the whole value: `{USER:::EMAIL}` (with
+braces) for the user's email, or `USER:::<user field id>` (no braces) for one of the user's own
+fields, e.g. their company (verified 2026-10-05 on HubSpot; fails closed when the field is empty).
+See [../references/softr-mcp.md](../references/softr-mcp.md#logged-in-user-values-in-source-conditions).
+
 **Custom user-record fields** are first-class: pass a `properties` map (aliased like a `select` query) and read them under `user.properties`:
 
 ```jsx

package/datasources/writing.md

@@ -16,6 +16,13 @@ Record mutations, sequential write queues, file uploads, linked record format, a
 
 Every Vibe Coding block in Softr Studio has an **Actions tab** alongside Chat / Source / Content / Visibility. The Actions tab is a **read-only inspector** of the Create / Update / Delete operations the platform inferred from your code.
 
+> **Docs discrepancy (noted 2026-10-05, unresolved).**
+> - **What the docs say:** the live Vibe Coding page tells builders to "Review each action and configure permissions, conditions, or connected workflows as needed".
+> - **Where we agree:** permissions are settable, on the Actions tab or with `vibe_coding_block_set_action_visibility`, so "read-only" is about the action *list*, which only the code changes.
+> - **What nobody has observed:** an Actions-tab control for conditions or connected workflows on a vibe block, or whether a vibe block's `ADD_RECORD` fires the Softr Apps "Add record" workflow trigger.
+>
+> Until someone sees those controls in Studio, start workflows from code with `navigate()` on a `TRIGGER_CUSTOM_WORKFLOW` setting (SKILL.md, NavigationAction).
+
 Each Action's "FIELDS USED" list mirrors the aliases in your `q.select()` mapping. Actions are not a separately-managed system:
 
 - The platform parses your block's source on every save

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "softr-vibe-coding",
-  "version": "2.11.1",
+  "version": "2.13.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/browser-checks.md

@@ -0,0 +1,199 @@
+# Checking a pushed block in a browser
+
+How to check a deployed block's rendering and behaviour in a Softr preview with the
+[agent-browser](https://github.com/vercel-labs/agent-browser) CLI. **Verified 2026-10-01** with
+agent-browser v0.38.1 on macOS (Node 22) against a real Softr preview; only the commands under
+[Untested but promising](#untested-but-promising) were not run.
+
+## When to use it
+
+After a push has passed the hash check in
+[softr-mcp.md → Verifying a push](softr-mcp.md#verifying-a-push--the-deployed-source-is-the-only-proof).
+The hash proves what Softr stored; a browser shows what it does: the layout at a given width, what
+a control does, what a Save would send. **Not for data checks** (read records through the MCP or the
+API), and **not for logged-in Studio or Airtable work**, which needs the user's own session and so
+belongs to the user's own Chrome tool.
+
+## Tool choice and why
+
+**agent-browser**, because a check costs fewer tokens and can be made safe:
+
+- One browser stays alive between shell commands (a daemon per `--session`), so a check is a few
+  short commands rather than one script.
+- `eval` prints only its result. The Playwright MCP's `browser_run_code_unsafe` repeats the whole
+  script back in every result, under "### Ran Playwright code".
+- Screenshots go to disk and cost nothing until someone opens one.
+- It aborts requests by URL pattern and lists what a click sent: the write guard below.
+
+An in-app or embedded browser pane stops rendering while it is hidden: IntersectionObserver and
+`requestAnimationFrame` never fire, and screenshots time out. It can check scroll- or
+visibility-driven behaviour only while it is visibly open.
+
+## Install
+
+Check with `agent-browser --version`. If it is missing, **ask the user before installing**: it is a
+global npm package plus a Chrome for Testing download (182 MB, about 360 MB on disk under
+`~/.agent-browser`). On a yes:
+
+```bash
+npm i -g agent-browser && agent-browser install
+agent-browser doctor     # passed every check; a headless launch took about 0.9 s
+```
+
+npm may warn `EBADENGINE`, asking for Node ≥ 24. It ran fine on Node 22: that requirement is for
+building from source, and the CLI is a native binary. If the user declines, drive a headless Chrome
+with Playwright, or use an in-app browser only while it is visibly open.
+
+## Why not the skills.sh `agent-browser` skill
+
+vercel-labs also publish an `agent-browser` skill on skills.sh. Do not install it. Its description
+tells the agent to prefer it over every built-in browser tool, and it triggers on generic requests,
+even Slack ones. Yet it is only a stub that loads `agent-browser skills get core` (about 38 KB, some
+10k tokens). The CLI serves that guide on demand, matched to the installed version: run
+`agent-browser skills get core` yourself, and only when this recipe is not enough.
+
+## The recipe
+
+### 1. Session, preview cookie, page
+
+Work from a scratch directory, not the project: nothing is written to the working folder, and
+screenshots go where you tell them.
+
+```bash
+ab() { agent-browser --session softr-check "$@"; }   # a function, not a variable: see Gotchas
+ab open '<previewUrl>' >/dev/null      # once per session: sets the preview cookie
+ab set viewport 1280 900
+ab open 'https://<subdomain>.preview.softr.app/<page>?recordId=<recordId>&autoUser=true'
+ab wait --load networkidle             # works on Softr previews
+ab wait 2500                           # 2000–3000 ms more, so the block's data hooks can load
+```
+
+`<previewUrl>` is what the MCP's `application_preview` returns. `open` prints the URL it opened, and
+this one carries a sign-in token, hence `/dev/null`. The direct URL then loads the app itself, not
+the toolbar shell that frames it, so `document` in `eval` is the app's.
+
+### 2. Reaching into the block
+
+A block renders inside a shadow root, which CSS selectors and `find` locators do not cross.
+**Refs from the accessibility readout do**: `ab snapshot -i` lists the block's textboxes, buttons
+and checkboxes as `[ref=eN]`, and `ab fill @eN '…'` and `ab click @eN` act inside the block. Grep
+the ref out in the same shell call, so the readout never enters your context:
+
+```bash
+REF=$(ab snapshot -i | grep -o 'textbox "Search by[^[]*\[ref=e[0-9]*' | head -1 | grep -o 'e[0-9]*$'); ab fill "@$REF" 'term'
+```
+
+### 3. Measuring with `eval`
+
+`ab eval "<expr>"`, or `ab eval --stdin < check.js` for anything longer. An async IIFE is awaited,
+and only the result is printed: return `JSON.stringify(...)` to get one JSON-encoded line. Find the
+block's shadow root by text only that block contains:
+
+```js
+(async () => {
+  const root = [...document.querySelectorAll('*')].map(e => e.shadowRoot).filter(Boolean)
+    .find(s => /<text unique to the block>/.test(s.textContent));
+  if (!root) return 'block not found';
+  const r = root.querySelector('<selector>').getBoundingClientRect();
+  return JSON.stringify({ left: r.left, right: innerWidth - r.right, top: r.top, width: r.width });
+})()
+```
+
+A date input has no ref (role `Date` in the full readout, absent from `-i`) and is React-controlled:
+set it through the native setter, then fire both events, inside the IIFE once `root` is found.
+
+```js
+const i = root.querySelector('input[type="date"]');
+const set = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value').set;
+set.call(i, '2026-10-15');
+i.dispatchEvent(new Event('input', { bubbles: true }));
+i.dispatchEvent(new Event('change', { bubbles: true }));
+```
+
+### 4. Block saves before any click, and prove it
+
+The preview writes to the live data
+([softr-mcp.md](softr-mcp.md#testing-as-any-app-user-without-logins--the-preview-as-switcher)), so
+before a check clicks anything that could save:
+
+```bash
+ab network route '*records-trigger*' --abort
+ab eval "fetch('/records-trigger-probe-' + Date.now()).then(r => 'NOT BLOCKED ' + r.status).catch(e => 'blocked: ' + e.message)"
+#   blocked: Failed to fetch
+ab eval "fetch('/plain-probe-' + Date.now()).then(r => 'reached ' + r.status).catch(e => 'blocked: ' + e.message)"
+#   reached 404 (the control: other requests still get through)
+```
+
+A `useRecordUpdate` save goes out as a PATCH, with the record ID in the path (see Gotchas):
+
+```
+PATCH https://<subdomain>.preview.softr.app/v1/datasource/applications/<app>/pages/<page>/blocks/<block>/datasources/<ds>/records-trigger/<recordId>
+```
+
+Only this update endpoint is verified. Before clicking a create or delete control, learn its URL
+with `ab network requests` where a write is harmless, never on client data, and block that pattern
+too. Do not assume `*records-trigger*` covers it.
+
+### 5. Click, then read what it sent
+
+Read the record through the database API, click Save by its ref (step 2), then read the record
+again: `updatedAt` and the field should be unchanged. The aborted request is still logged, so you
+see the payload without it reaching the server:
+
+```bash
+ab network requests --filter records-trigger   # lists the save, with its id
+ab network request <id> --json                 # method: PATCH, postData: {"context":{…},"fields":{"<fieldId>":"2026-10-15"}}
+```
+
+### 6. Screenshots and cleanup
+
+```bash
+ab screenshot ./empty-1280.png         # ✓ Screenshot saved to …   (--full for the whole page)
+ab network unroute
+ab close                               # ✓ Browser closed (no process left behind)
+```
+
+Give a path; without one, it writes to a temp directory. A saved screenshot costs no tokens until
+someone opens it; one shown inline costs about 1.5k. Left alone, the daemon exits after an hour idle.
+
+## Gotchas
+
+- **zsh does not word-split.** `AB="agent-browser --session x"; $AB open …` fails with "command not
+  found": use the function. Agent shells usually keep no functions or variables between calls, so
+  define `ab`, and grep any ref, in the call that uses them; the browser lives on in the daemon.
+- **Selectors stop at the shadow root.** `ab fill 'input[placeholder^="…"]' 'x'` gives
+  `✗ Element not found`, and `find` locators fail the same way (upstream issue
+  vercel-labs/agent-browser#1266, open since April 2026). Use refs, or `eval`.
+- **Refs change on every page load.** Grep again after each `open` or reload.
+- **Readouts are huge on data pages.** A table-heavy page measured 268 KB in full, 197 KB with `-c`
+  and 164 KB with `-i` (or `-i -c`), about 40k tokens: `-i` keeps table cells as context for the
+  buttons in them. A small page was 5.8 KB, 2.9 KB with `-i`. Never print one on a data page: grep
+  it, or write it to a file.
+- **Saves are PATCH, and the record ID is in the path.** A guard on POST misses them, and so does one
+  that looks for the record ID in the body; that one once let a write through. Match the URL, never
+  the method or the body.
+- **Plain `ab network request <id>` printed only the URL** of the blocked save. Add `--json`.
+- **A preview serves the version it was minted on.** After every push, mint a fresh one with
+  `application_preview` and open it again before checking anything.
+- **The preview URL is a sign-in token.** Never share it ([why](softr-mcp.md#application-management-tools)).
+- **Attachment URLs are re-signed on every read:** compare by id, filename and size, never by URL.
+
+## Measured
+
+The same check, an empty-state centring check at two widths plus a screenshot, cost about 650 tokens
+with agent-browser (2026-10-01) against about 1,540 with the Playwright MCP's run-code
+(2026-09-30): about 58% less, mostly because Playwright repeats the script back. Learning the tool
+in a fresh session cost about 1.6k tokens, once, without loading `skills get core`.
+
+## Untested but promising
+
+In agent-browser's docs, **not yet tried against a Softr preview**. Try one before relying on it:
+
+- `ab pdf <path>`: to check a print layout ([printing.md](printing.md#7-gotchas-and-testing) has
+  the verified Playwright route).
+- `--init-script <path>` (before the first navigation) or `ab addinitscript <js>` (at runtime): for
+  example, to stub `window.print` before load.
+- `ab screenshot --if-changed`: skips a screenshot that matches the last one.
+- `ab diff snapshot`: compares the current readout with the last one.
+- `ab a11y`: the built-in axe-core accessibility audit.
+- `--allowed-domains <list>`: restricts the session's network to the domains listed.

package/references/editable-settings.md

@@ -137,7 +137,7 @@ Value shapes per action type (full detail in SKILL.md's NavigationAction section
 - `OPEN_PAGE` — `destination` (page path) + `openIn` (`"SELF"` | `"TAB"` | `"MODAL"`)
 - `OPEN_URL` — `destination` (URL) + `openIn` (`"SELF"` | `"TAB"`)
 - `OPEN_CHAT` — no destination (mind the data-source-context gotcha in [anti-patterns.md](anti-patterns.md))
-- `TRIGGER_CUSTOM_WORKFLOW` — no destination; builder picks the workflow in Studio (workflow-side receiving end by name: the "Run Custom Workflow action triggered" trigger — name-based match, not wired live; see [softr-mcp.md](softr-mcp.md#workflows))
+- `TRIGGER_CUSTOM_WORKFLOW` — no destination; builder picks the workflow in Studio. Code can also run it with `navigate(setting, { recordId, datasourceId })` (documented 2026-10-05). The workflow-side receiving end is the "Run custom workflow" trigger (`SOFTR_APPS_TRIGGER_WORKFLOW`); see [softr-mcp.md](softr-mcp.md#workflows)
 
 **[verified-undocumented] `action` is accepted as optional.** Softr's setting validator accepts an initialValue with no `action` key — `{ destination: "/", openIn: "SELF" }` alone — and Studio's own AI emits exactly that shape (verified 2026-08-31: a Studio-generated block with three action-less `useNavigationSetting` initialValues, plus three more action-less link values inside an array setting, saved and rendered its Settings pane). Corroborating in-repo evidence that not every key is mandatory: the validator's own error message for `openIn` ends in *"if provided"* (see [anti-patterns.md](anti-patterns.md#editable-settings)). Two consequences:
 

package/references/softr-mcp.md

@@ -47,6 +47,13 @@ On 2026-10-01 Softr renamed the workspace-server tools outside Workflows to **ar
 (`application_update_pwa_settings`); the 28 Workflows tools and `get_workspace_integrations` kept their names. The
 map below was checked against the tool lists the server delivered on 2026-09-30 (old) and 2026-10-01 (new).
 
+**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`;
+`integration_list` covers it.
+
 Most new names are the old words reordered. These are the ones you would not guess:
 
 | Old | New |
@@ -293,6 +300,8 @@ definition says, check that `sourceCode` came back `null`.
    result to a file rather than returning it inline, so compare from that file with a script, never
    by eye.
 
+Matching hashes prove what Softr stored, not how the block behaves: for that, check it in a fresh preview with saves blocked, per [browser-checks.md](browser-checks.md).
+
 **Hash the exact bytes, trailing newline included.** Softr stores exactly what it receives: across
 112 push→fetch pairs between 2026-09-09 and 2026-09-30 the fetched
 `sourceCode` was byte- and MD5-identical to the text sent, including two pushes sent *without* a
@@ -451,31 +460,78 @@ Both edit paths recompile, so both reset Action permissions either way (Hard Con
 ### What the server enforces on a block's data endpoints
 
 *Verified live 2026-09-18 (Softr Database; draft preview, "Preview as" different users, requests
-captured from the app iframe).* A block's data lives behind per-connection endpoints —
+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:
 
 | 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** |
 | 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)) |
 
 The consequence to design around: **on a page any logged-in user may view, every datasource
-connected to its blocks is readable by any logged-in user who crafts the request** — all rows the
+connected to its ungated blocks is readable by any logged-in user who crafts the request** — all rows the
 Source conditions allow, all fields the block's read selects name. A per-record access check in
 React ("is this viewer a party to this record?") shapes the UI; it is not access control. When rows
-must be private per user, put it in the Source conditions (e.g. a logged-in-user condition) or on a
+must be private per user, put it in the Source conditions (e.g. a logged-in-user condition; see
+[below](#logged-in-user-values-in-source-conditions) for the two forms known to work) or on a
 page only the right group can view. When a field must be private, a second connection of the table
 keeps it out of every ordinary browser's payload — but not away from a crafted request by someone
 who may view the page; for that it has to live on a page (or in a group-gated block) the viewer
-cannot see. (The verified 403 case was page VIEW; the message's "block/action visibility rules"
-wording suggests block visibility is checked the same way, which is inference.)
+cannot see. Conversely, a block gated to a staff group may read unfiltered connections for a staff
+view: on 2026-10-05 group members got all 41 deals and 16 tickets, and everyone else got 403, with
+the page VIEW permission at `LOGGED_IN_USERS` throughout.
 
 This is also what makes the open-`ADD_RECORD` finding above severity-dependent on the page's VIEW
 permission rather than uniformly critical.
 
+#### Logged-in-user values in Source conditions
+
+*The email token was verified on Softr Database in a production project: set in Studio's Source
+tab and read back with `vibe_coding_block_get_settings` on 2026-09-01, then set over MCP and checked
+against the records endpoint's totals as different users on 2026-09-18. The user-field token was
+verified on HubSpot on 2026-10-05, the same way.* There are two forms, and **their braces differ**:
+
+- **The email: `{USER:::EMAIL}`, with braces, only as the ENTIRE value** of an expression, e.g.
+  `{ "subject": { "field": "<fieldId>", "type": "TEXT" }, "operator": "CONTAINS", "value": ["{USER:::EMAIL}"] }`.
+  Softr substitutes it as a whole-value token, not by string interpolation. The embedded form
+  `",{USER:::EMAIL},"` returned total 0 for every user, including users who should have matched.
+- **A users-table field: `USER:::<user field id>`, with NO braces, as the entire value** (verified
+  2026-10-05 on HubSpot). `associations.company IS_ONE_OF ["USER:::associations.company"]` on a
+  deals connection gave each user only their own companies' deals. Studio stores a picked user
+  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.
+- **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
+  tried, including `{USER:::<fieldId>}`, `{USER:<fieldId>}` and `{USER:::FIELD:<fieldId>}`. Each
+  silently matched nothing. All eleven had braces, so the braceless form is untested on Softr
+  Database, not disproved. A subject of `USER:<fieldId>`, the syntax user-group rules use, returned
+  HTTP 400 "Field not found": the user field goes in the value, never the subject. No token for a
+  user group has been found.
+- Studio's conditional-filter UI offers the logged-in user's Email and Email-Domain, plus every
+  users-table field once users sync from a data source (documented). For a value not listed here,
+  pick it in a block's Source tab, save, and read `dataSources[].condition` back with
+  `vibe_coding_block_get_settings`. That is how the user-field form was found.
+- **CONTAINS against a list of emails has a substring trap:** `bob@x.com` matches a field holding
+  `jbob@x.com`. Prefer IS against a single-email field. If a record must hold several emails, the
+  delimiter trick the embedded form was meant to provide does not work, so accept the trap or
+  split the data.
+- When a row gate must follow something other than the user's email (a company, a team), compare
+  the record's field with the user's own field through `USER:::<user field id>`. Where that form is
+  untested (Softr Database so far), store an email on the record and compare it with
+  `{USER:::EMAIL}`. Staff who need every row get a group-gated block with unfiltered connections
+  ([above](#what-the-server-enforces-on-a-blocks-data-endpoints)), not a wider condition.
+
+For HubSpot specifics (association-based scoping, owner fields), see
+[../datasources/hubspot.md](../datasources/hubspot.md#row-scoping--who-sees-which-records).
+
 ## Adopting Studio-AI-generated code
 
 When you pull a Studio-AI-generated block via `vibe_coding_block_get_code` to adopt into a project repo as source of truth: its output renders fine but ships with predictable defects. **Functional patterns in Studio output are platform-support evidence** (it surfaces undocumented capabilities before the docs do — see SKILL.md's "Platform truth sources"); **its code hygiene is not a pattern to imitate.** Cleanup pass before committing:
@@ -554,6 +610,13 @@ passwords, no test accounts to create:
   [../datasources/](../datasources/) were established — read the wire, not the rendered UI.
 - Blocks render in shadow roots inside that iframe: read the DOM through
   `iframe.contentDocument` and each block host's `shadowRoot`, not `document.querySelector`.
+- **Switch user without the switcher** (verified 2026-10-05): on the preview link's origin,
+  `fetch('/studio/impersonate/<softrUserId>')` makes the preview run as that user. The id is the
+  user's Softr id from `application_list_users`. It works from a fresh preview link, so it needs no
+  Studio session in the browser.
+- **Press the preview's own `#refresh-button` after a push.** An open preview kept serving the old
+  block version until it was pressed (verified 2026-10-05). Minting a fresh link does too (see the
+  version note above).
 
 > **The preview is wired to the LIVE datasource.** Anything clicked there — a Save, a status
 > change, a form submit — writes real records, as the previewed user. Keep preview sessions to
@@ -667,9 +730,19 @@ Softr Workflows are automations built from trigger + action nodes, and the MCP c
 | 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` |
 
+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).
+
 **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:
 
-- **Softr-native triggers:** one-time + recurring schedules, `WEBHOOK` (inbound webhook), `SOFTR_EMAIL_RECEIVED` (inbound email! — delivery mechanism not captured), Softr Databases record events (added / updated / deleted / meets-conditions / enters-view / "run custom workflow on selected records"), Softr Apps events (Add Record form submitted, Edit Record form submitted, form submitted, user added, comment added) — and **"Run Custom Workflow action triggered"**, which by its name is the receiving end of the vibe block's `TRIGGER_CUSTOM_WORKFLOW` NavigationAction (name-based inference; the pairing has not been wired live). See SKILL.md's NavigationAction action-types list.
+- **Softr-native triggers:** one-time + recurring schedules, `WEBHOOK` (inbound webhook), `SOFTR_EMAIL_RECEIVED` (inbound email! — delivery mechanism not captured), Softr Databases record events (added / updated / deleted / meets-conditions / enters-view / "run custom workflow on selected records"), Softr Apps events (Add Record form submitted, Edit Record form submitted, form submitted, user added, comment added) — and **"Run custom workflow"** (`SOFTR_APPS_TRIGGER_WORKFLOW`; this file called it "Run Custom Workflow action triggered" until 2026-10-05, and the live label is "Run custom workflow"). This is the receiving end of the vibe block's `TRIGGER_CUSTOM_WORKFLOW` action.
+  - **From the block:** the live developer guide documents `navigate(setting, { recordId, datasourceId })` on a `TRIGGER_CUSTOM_WORKFLOW` setting, callable for example from `useRecordCreate`'s `onSuccess`, and says "the builder picks which action it points at" (documented, checked 2026-10-05). We have not yet run it end to end ourselves.
+  - **The trigger and its payload:** its only input is `corsAllowedOrigins`. Saved payloads look like `{ body: { ... }, query: {} }`, with `body` holding whatever the triggering action mapped. Native buttons can map form or record fields; the vibe path documents only `recordId` and `datasourceId`.
+  - **Who can call it:** the endpoint is browser-callable (per its spec, an empty `corsAllowedOrigins` allows any origin), so re-read the record server-side rather than trusting the body.
+  - **Wait screen:** `workflow_create` scaffolds the Show Wait Screen and End User Interactions steps for this trigger. Whether a vibe `navigate()` call shows the wait screen is undocumented; the docs describe the toggle only on native app actions.
+
+  See SKILL.md's NavigationAction action-types list.
 - **Softr-native actions:** `BRANCH`, `FILTER`, `WAIT`, `LOOP_ACTION_GROUP` (run each list item through the same steps), `SOFTR_SEND_EMAIL`, `CALL_API` (REST), `WEBPAGE_SCRAPPER`, `PDF_TO_TEXT`, `COMPRESS_FILES` (zip + download link), `TRANSFORM_DATA`, `RESPONDED_TO_WEBHOOK` (custom HTTP response to the webhook caller); Softr DB record CRUD incl. bulk update/delete and find; Softr Apps user management (find / create / delete / deactivate / activate / invite user, send push notification).
 - **`CUSTOM_CODE`:** runs custom **JavaScript or Python** inside a workflow.
 - **AI actions:** Softr AI, OpenAI, Anthropic, Gemini, and Mistral each ship Write / Summarize / Categorize / Custom-prompt nodes; OpenAI adds gpt-image-2 image generation. Pinecone, Firecrawl, Replicate, and Linkup nodes exist too.
@@ -679,12 +752,15 @@ Softr Workflows are automations built from trigger + action nodes, and the MCP c
 
 - Node inputs can embed **references to another node's runtime output**, a loop's current item, or named date/time tokens.
 - **Test-first is mandated:** every testable node needs a test run before its outputs become referenceable by downstream nodes. Each node carries a `testRunMode` — `REAL_ONLY`, `MOCK_ONLY`, or `MOCK_AND_REAL` — so some nodes can only be tested against real side effects while others mock. See the test-safety rules under build-loop findings below before testing anything against a production workspace.
-- **Workflows are workspace-level, not part of an app**: `application_preview` / `application_publish` do not apply. Link a workflow as `https://studio.softr.io/workflow/{workflowId}`.
+- **Workflows are owned by a workspace, and can now be pinned to an app** (verified 2026-10-05 from the tool definitions). `workflow_create` still requires a `workspaceId`; its optional `applicationId` "pins the workflow to it, so it is listed on that app's Workflows tab", and `workflow_list({ applicationId })` lists the workflows pinned to an app. Leave `applicationId` out for a workflow that belongs to the workspace as a whole. Pinning or not, `application_preview` / `application_publish` do not apply to workflows. Link a workflow as `https://studio.softr.io/workflow/{workflowId}`.
 
 **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.
 - **`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.
 - **Test-safety rules** (which `testRunMode` means what in practice):