softr-vibe-coding 2.13.0 → 2.13.1

package/CHANGELOG.md

@@ -4,6 +4,13 @@ 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.1] - 2026-10-05
+- Release 2.13.1
+- Keep HubSpot association claims at their tested scope (second review round)
+- Record HubSpot association writes: create with id strings, update with [{ id }] replaces the list (verified 2026-10-05)
+- Fix three stale TOC anchors in helper-blocks.md
+- Record that no read follows a write, and HubSpot's after-write changes (verified 2026-10-05)
+
 ## [2.13.0] - 2026-10-05
 - Release 2.13.0
 - Record the USER::: user-field Source-condition token (verified 2026-10-05 on HubSpot)

package/README.md

@@ -278,7 +278,7 @@ softr-vibe-coding/
     ├── airtable.md                   # Column names, PAT vs OAuth, rate limits
     ├── google-sheets.md              # Text formatting, 50-100 user cap
     ├── hubspot.md                    # 15 objects (listed ≠ usable), field model,
-    │                                 # association writes (open), row scoping (Oct 5 2026)
+    │                                 # association writes, write behaviour, row scoping (Oct 5 2026)
     ├── notion.md                     # Database pages only, Relation workarounds
     ├── coda.md                       # API token auth, limitations
     ├── monday.md                     # API token, Connected Boards
@@ -325,7 +325,7 @@ The skill enforces these automatically, but good to know (verified live against
 - Data hook options must be **inline object literals** — `useRecords(opts)` with a variable or wrapper fails to compile
 - Create payloads are **flat**; update payloads are `{ recordId, fields: {...} }` — asymmetric by design
 - `mutateAsync` is fully supported — it's the tool for sequential multi-row saves
-- SELECT fields write by option **label string**; linked records write as arrays of record-id strings
+- SELECT fields write by option **label string**; linked records write as arrays of record-id strings. HubSpot differs (verified Oct 2026): SELECTs take the choice id, and an association update needs `[{ id }]` objects; in the one test it replaced the ticket's whole company list (see `datasources/hubspot.md`)
 - Every code recompile resets the block's auto-registered Actions to default permissions — tighten permissions after the last redeploy, and note there is **no cosmetic-edit exemption**: an edit that changes only a comment resets them too. **Always read the permissions back to confirm** — a create action defaults to the block's own visibility, so on a block everyone can see it comes back publicly writable, and the MCP call that re-tightens it can fail with no fallback
 - **Blocks cannot import each other**, so two blocks that must look alike will drift — each one looks correct in isolation while the set does not. Repeated page chrome (back button, title, primary action) must sit at the same offset on every page, and a loading skeleton must track the REST state of whatever it stands in for
 - No `import React from 'react'` — use named imports (`import { useState } from "react"`)

package/SKILL.md

@@ -85,7 +85,7 @@ You generate complete, production-ready Softr Vibe Coding blocks as TypeScript R
    - Sub-components (FieldLabel, TextInput, ChipButton, SectionCard, etc.) defined at **module scope**, NOT inside `Block()` -- prevents inputs losing focus after one keystroke (each render creates a new component identity, React unmounts/remounts the `<input>`)
    - When a custom DESIGN.md is in use, brand `fontFamily` (and any non-inherited brand defaults) set as an **inline style on the block's outermost wrapper** `<div>`, not relied on from `custom-code-header.html` -- Vibe Coding blocks render inside a shadow DOM and `html, body` rules don't cross that boundary. Per-element overrides (e.g. Fraunces serif on h1) still set inline at the element.
    - `fetchNextPage` never called in the render body — only from an event handler (Load More `onClick` with `disabled={isFetching}`, the official pattern) or a guarded `useEffect` (auto-load-all)
-   - Mutations use `recordId` (not `id`) and call `refetch()` in `onSuccess`
+   - Mutations use `recordId` (not `id`) and call `refetch()` in `onSuccess` — no read follows a write otherwise (measured 2026-10-05 on a HubSpot-backed block). When the source changes other fields itself (HubSpot stamps a closing deal's close date and recalculates its probability a few seconds later), also read again a few seconds later — see [writing.md → Fields the source changes after the write](datasources/writing.md#fields-the-source-changes-after-the-write)
    - `useRecordUpdate` payload is `{ recordId, fields: { ... } }` — nested. `useRecordCreate` payload is **flat** (no `fields` wrapper). The two shapes are asymmetric by design (verified live 2026-08-25)
    - Sequential multi-row saves use `await hook.mutateAsync(...)` per row, in order, with stop-on-failure + retry state — `mutateAsync` is fully supported on the current platform (verified 2026-08-25; the old ".mutate() only" Action-parser rule is gone — see [datasources/writing.md](datasources/writing.md)). Independent writes to **different tables** may run in parallel via `Promise.all`; drag/reassign UIs should be optimistic with an Undo toast — see [writing.md → Parallel writes across tables](datasources/writing.md#parallel-writes-across-tables-the-one-sanctioned-parallelism)
    - No hardcoded domains in links -- use relative paths (`/page?recordId=...`); same-page anchors written relative too (`/#section`)

package/datasources/hubspot.md

@@ -2,10 +2,15 @@
 
 *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.*
+docs. Labels used below: **verified live** = observed that day through the Softr or HubSpot MCP,
+in the browser's network log, or in a test block's own output in the preview; **documented** =
+Softr or HubSpot docs say so; **inferred** = reasoned, not observed; **unverified** = nobody has
+tested it. That run made no writes. Write tests followed that day, all in Studio preview
+("Preview as": the builder's session acting as the chosen user, not a real login). In the
+morning a test block created a ticket with company and contact links and then re-linked it. In
+the afternoon the Accounts block changed the stage of that ticket and of one test deal, and a
+client's replay of one of those requests was refused. On the write side, only what those tests
+covered is verified live.*
 
 ## Overview
 
@@ -42,7 +47,7 @@ list had 7 before). The live integration returned **14 object ids**, i.e. all ex
 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.
+write matrix, and vibe-block writes have been tested on tickets and deals only (2026-10-05).
 
 | Object | Id | Primary field | What to know |
 |---|---|---|---|
@@ -51,7 +56,7 @@ write matrix, and no vibe-block write to any HubSpot object has been tested.
 | 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) |
+| Notes | `notes` | `hs_body_preview` | A create needs `hs_timestamp`. HubSpot says a note should be associated with at least one record. Links can be written on a ticket create ([Association writes](#association-writes)); a note create with links is untested |
 | 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 |
@@ -87,8 +92,14 @@ unless marked otherwise.*
 
   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.
+  [reading.md](reading.md#filtering-by-a-linked-record-server-side)). In a vibe hook (verified
+  live 2026-10-05 on tickets), `associations.company` and `associations.contact` read as arrays
+  of `{ id, label }`, usually with the record's name as the label (one re-read shortly after a
+  link update showed the company's id instead; see [Association writes](#association-writes)).
+  The primary-company link `associations.ticket_to_company` read as one `{ id, label }` object,
+  or `null` (seen once, in a re-read shortly after a link update, while a company was still
+  linked; HubSpot's primary label was not checked). A Softr workflow's Find record output showed
+  the single-object case too.
 - **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").
@@ -121,58 +132,158 @@ unless marked otherwise.*
 
 | Field kind | Writable? | Evidence |
 |---|---|---|
-| Default properties | Yes | Documented (Softr's HubSpot page); untested from a vibe block |
+| Default properties | Yes | **Verified live** 2026-10-05: `dealstage` and `hs_pipeline_stage` with `useRecordUpdate`, and `subject`, `content`, `hs_pipeline` and `hs_pipeline_stage` on a ticket create with `useRecordCreate`; the rest documented (Softr's HubSpot page) |
 | 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) |
+| Associations (`associations.*`) | Yes for a ticket's company and contact links; an update replaced the company list | **Verified live** 2026-10-05 on one ticket's `associations.company` and `associations.contact` ([below](#association-writes)); other links, including the primary company, untested |
 | `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.**
+- **Write a SELECT by its choice id** (verified live 2026-10-05). `fields: { stage: "closedwon" }`
+  on `dealstage` and `fields: { status: "1" }` on `hs_pipeline_stage` both saved, and so did a
+  ticket create with `hs_pipeline: "0"` and `hs_pipeline_stage: "1"`. The id and the
+  label differ (`'1'` vs `'New'`, `'6183367908'` vs `'Initial Contact'`). Softr Database is the
+  other way round: there the **label** is written
+  ([writing.md](writing.md#dropdown--single-select-softr-database)). Whether HubSpot also accepts
+  a label is untested.
+- **What goes over the wire** (verified live 2026-10-05, ticket stage write):
+  - The write is `PATCH …/blocks/<block>/datasources/<connection id>/records-trigger/<recordId>`
+    with the body `{"context":{…},"fields":{"hs_pipeline_stage":"1"}}`. Fields are keyed by
+    HubSpot property id, and the value is a plain string.
+  - The response holds only the written field, in its read shape:
+    `{"record":{"id":"…","fields":{"hs_pipeline_stage":{"id":"1","label":"New"}}},"triggerResponse":null}`.
+  - The connection id in the write URL is internal: the deals connection's id changed when the
+    block was recompiled. Reads use the alias (`…/datasources/tickets/records`). This only
+    matters when reading a network log.
+- **The write endpoint enforces visibility** (verified live 2026-10-05). A client who replayed an
+  account manager's PATCH got 403. The block and its actions were both limited to account
+  managers, so the test did not show which of the two rules refused it. Every code push resets
+  action visibility (Hard Constraint 21 in SKILL.md), so re-lock it and read it back after each push.
+
+### What HubSpot changes after a write
+
+*Verified live 2026-10-05 on one test ticket and one test deal. The writes came from a vibe
+block in preview; the results were read back through the HubSpot MCP and the block's own list
+reads.*
+
+- **A deal's close date is overwritten when it closes, won or lost.** Entering `closedwon` or
+  `closedlost` sets `closedate` to the moment of the write: `closedwon` replaced a planned date
+  four months away, and `closedlost` later did the same. Reopening the deal, or undoing the
+  change, kept the new date; the old one had to be restored by hand. Say so in the confirm step
+  before a block closes a deal.
+- **A ticket's close date is cleared when it reopens.** Entering the closed status set
+  `closed_date` and `time_to_close`. Moving the ticket back to an open status cleared both.
+- **Probability and weighted amount lag behind the stage.** HubSpot recalculates
+  `hs_deal_stage_probability` and `hs_projected_amount` after the write (table below).
+- **HubSpot modifies a ticket again about 10 s after a stage write.** `hs_lastmodifieddate`
+  moved again 9 to 11 s after each of the three stage writes where it was checked.
+- **Stage writes leave associations alone.** They do leave a permanent stage history
+  (`hs_v2_date_entered_*` / `hs_v2_date_exited_*`), even when the value is put back.
+
+What the block's own list reads returned for the deal (Closed Lost, then Undo 5 s later):
+
+| Read of `deals` | `dealstage`, `closedate` | `hs_deal_stage_probability`, `hs_projected_amount` |
+|---|---|---|
+| +4 s after Closed Lost | `closedlost`, the new date | 0.1 and 1,980: the values from before the write |
+| +4 s after the Undo | Initial Contact, the new date kept | 0 and 0: Closed Lost's values |
+| +12 s after the Undo | Initial Contact, the new date kept | 0.1 and 1,980: correct |
+
+So the stage and the close date were readable within 4 s, while the computed fields were still
+one write behind at that point. No read follows a write unless the block asks. A block that
+shows any of these fields should, on top of the `refetch()` in `onSuccess`, read the table again
+about 4 s and 12 s after each successful save
+([pattern](writing.md#fields-the-source-changes-after-the-write)). A read right after the write
+was not measured.
+
+### Association writes
+
+*Verified live 2026-10-05 from a test block in Studio preview, "Preview as" Softr's built-in Test
+User (the builder's session acting as that user, who had no HubSpot record): one ticket, one
+company and one contact. HubSpot's MCP confirmed the links, the company count and the source;
+the primary-company link and the link labels were seen only in the block's own reads. Not
+tested: a create with `[{ id }]` objects, objects other than tickets, writing the primary-company
+link directly, and a real client login on the published app.*
+
+To Softr's action parser the association fields are ordinary fields. With `associations.company`
+and `associations.contact` in the hooks' `fields:` selects, the derived ADD_RECORD and
+UPDATE_RECORD actions listed both ("Associated Company", "Associated Contact"), and both hooks
+were enabled.
+
+**Create: link with an array of id strings.** This worked:
+
+```tsx
+const ticketCreateFields = q.select({
+  subject: "subject",
+  pipeline: "hs_pipeline",
+  stage: "hs_pipeline_stage",
+  company: "associations.company",
+  contact: "associations.contact",
+});
+
+// Inside the block: const createTicket = useRecordCreate({ from: ds.tickets, fields: ticketCreateFields });
+await createTicket.mutateAsync({
+  subject,
+  pipeline: "0",          // choice ids, not labels
+  stage: "1",
+  company: [companyId],   // an array of id strings, as on Softr Database
+  contact: [contactId],
+});
+```
+
+- **The ticket was linked to the written company and contact** (confirmed in HubSpot). In Softr's
+  read, the written company was also the primary company (`associations.ticket_to_company`);
+  whether Softr's write set that or HubSpot did is not known.
+- **An extra company link appeared.** The ticket was also linked to the contact's other company,
+  which was also that contact's primary company. The block wrote only the one company, so HubSpot
+  most likely added it (inferred), perhaps through a portal setting (unchecked). Whether it adds
+  every company of the contact or only the primary one is open. Expect extra company links on a
+  ticket created with a contact (seen once).
+- **Link labels are not always names.** The create's result labelled both links with their ids
+  (`{ "id": "450812074179", "label": "450812074179" }`), and the update's result did the same for
+  the company. A re-read after the create had the names. A re-read about 15 s after the update
+  still labelled the company with its id while the contact had its name; a later read had the
+  name. When a label equals its id, take the name from the companies or contacts the block
+  already reads, or show the id.
+- **HubSpot records the source** as `INTEGRATION`, detail "Softr".
+
+**Update: `[{ id }]` objects, and the update replaced the company list.**
+
+- `useRecordUpdate` with `company` and `contact` both as `["<id>"]` failed with **500**
+  (`Failed to update record: 500`) and, in the block's re-read, changed nothing, although the
+  create had accepted that shape.
+- `company: [{ id }]` and `contact: [{ id }]` worked, and the company list was **replaced**: the
+  extra company was removed (HubSpot's company count went from 2 to 1). In the block's re-read
+  about 15 s later, `associations.ticket_to_company` was `null` although the written company stayed
+  linked, so expect the primary-company link to be lost (not checked in HubSpot). The contact list
+  held only the written contact before and after, so whether contact links are replaced too could
+  not be seen (likely; inferred).
+- So, with the two shapes tried, an update could not add one link on its own: `["<id>"]` failed
+  and `[{ id }]` replaced the list. A block can write the whole list back with the new id added
+  (untested; it may lose the primary label, as the test's update did), or leave it to the
+  workflow route below.
+- An update whose `fields:` select held no association fields left the links alone: later stage
+  writes on this ticket came from another block whose update select held only the stage, and the
+  ticket kept its company. Whether leaving them out of the payload is enough when they are in the
+  select is untested, so keep association fields out of any update select that is not meant to
+  write them.
+
+**Nothing checked the link ids.** The create linked the ticket to a company and a contact that had
+nothing to do with the Test User who sent it. In this test the tickets connection had no Source
+condition and the create action had no record condition. Whether a Source condition, an action's
+record condition or a real client session checks the links on a create or an update is untested.
+The request comes from the browser, so treat link ids as client input: a client could probably
+link a new ticket to another company, and that company's portal would then show it (inferred).
+For client-facing creates, set or check the links server-side with the workflow route below.
+
+*History: this page called association writes "read-only" until 2026-10-05 (no source), then
+"unverified" until the test above.*
+
+**Workflow route (documented; not run in these tests): a Softr workflow calls HubSpot's
+associations API.** Use it to add a link without replacing the list, to set the primary label, or
+to set a client's links server-side.
 
 - **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
@@ -248,6 +359,14 @@ page ([details](multi-datasource.md#one-connection--one-read-payload-the-union-o
   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.
+  Association fields can be written like other fields ([Association writes](#association-writes),
+  verified on tickets), so a contacts write action a client can reach could let them rewrite their
+  own company links and widen their own scope (inferred; contact association writes untested).
+  Keep `associations.company` out of any such action.
+- **Writes are a separate question.** Whether a Source condition limits what a create or an
+  update may write, such as the link ids on a new ticket, is untested. A create on a connection
+  without one, run in preview, accepted links to a company and a contact unrelated to the user
+  ([Association writes](#association-writes)).
 - **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
@@ -280,8 +399,11 @@ page ([details](multi-datasource.md#one-connection--one-read-payload-the-union-o
   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.
+  `refetch()` right after a mutation may therefore still return the old value (inferred, not
+  measured). A list read at +4 s had the written stage, while HubSpot's computed fields were
+  still stale at +4 s and correct by +12 s (verified live 2026-10-05,
+  [details](#what-hubspot-changes-after-a-write)). Show the written value optimistically and
+  read again later.
 - Softr also caches data-source reads ("short-term" on one docs page, "24 hour" on another; scope
   unspecified). See [overview.md](overview.md).
 
@@ -358,7 +480,9 @@ page ([details](multi-datasource.md#one-connection--one-read-payload-the-union-o
     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
+  HubSpot's internal recalculations and on Softr's own writes too (inferred). HubSpot does modify
+  a record again about 10 s after a stage write (measured on a ticket, 2026-10-05), so one stage
+  change from a block may fire it twice (inferred; the trigger was not run). 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.
@@ -381,11 +505,17 @@ page ([details](multi-datasource.md#one-connection--one-read-payload-the-union-o
 
 - **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.
+- **Association links: create with `["<id>"]`, update with `[{ id }]`, and an update replaced the
+  ticket's whole company list** (verified live 2026-10-05, one ticket); Softr then read no primary
+  company (not checked in HubSpot). A ticket created with a contact may also get another of that
+  contact's companies. Treat link ids as client input.
+- **SELECT ids ≠ labels, and writes take the id** (verified live 2026-10-05; label untested).
+  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.
+- **Closing a deal overwrites its close date, and reopening keeps the new one.** Reopening a
+  ticket clears its close date. See [What HubSpot changes after a write](#what-hubspot-changes-after-a-write).
+- **After a save, read again at about 4 s and 12 s** on top of the usual `refetch()`. No read
+  follows a write on its own, and HubSpot's computed fields arrive late.
 - **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

package/datasources/reading.md

@@ -201,9 +201,10 @@ var statusOptions = useFieldOptions({
 
 // statusOptions → { options: [...], isLoading: bool }
 // statusOptions.options → [{ id: "sel...", label: "Active", color: "greenLight1" }, ...]
-//   id    — stable option id (use as a React key; NOT needed in mutate payloads — SELECT
-//           fields write by LABEL string on the current platform, verified 2026-08-25)
-//   label — display string AND the value to write in mutate payloads
+//   id    — stable option id (use as a React key; NOT needed in mutate payloads on Softr
+//           Database — SELECT fields write by LABEL string there, verified 2026-08-25.
+//           HubSpot is the exception: write the id, verified 2026-10-05)
+//   label — display string AND the value to write in mutate payloads (not on HubSpot)
 //   color — Airtable swatch color name (optional; handy for tinting chips)
 ```
 
@@ -219,7 +220,7 @@ same `select` object can be shared by both. Reuse one `select` for many fields a
 
 **When to use this vs. hardcoding:**
 
-- **Use `useFieldOptions`** when option labels could change post-deploy — selects with rapidly-evolving lists, user-editable choices, or any case where re-pasting blocks for an option rename is annoying. Since SELECT fields write by label (verified 2026-08-25), live options also keep write payloads rename-proof: render and write `option.label`. Hardcoded labels remain fine as a display-only loading fallback while the live options fetch. Cross-table case: to render a select field from table B inside a block bound to table A (e.g. an intake form bound to Jobs that needs the Wigs `Color` options), put the `useRecords` + `useFieldOptions` in a hidden helper block bound to table B and publish the options to a `window` global (see [helper-blocks.md](../references/helper-blocks.md)).
+- **Use `useFieldOptions`** when option labels could change post-deploy — selects with rapidly-evolving lists, user-editable choices, or any case where re-pasting blocks for an option rename is annoying. Since SELECT fields write by label on Softr Database (verified 2026-08-25), live options also keep write payloads rename-proof: render and write `option.label`. HubSpot writes the choice id instead (verified 2026-10-05; see [hubspot.md](hubspot.md#writing)). Hardcoded labels remain fine as a display-only loading fallback while the live options fetch. Cross-table case: to render a select field from table B inside a block bound to table A (e.g. an intake form bound to Jobs that needs the Wigs `Color` options), put the `useRecords` + `useFieldOptions` in a hidden helper block bound to table B and publish the options to a `window` global (see [helper-blocks.md](../references/helper-blocks.md)).
 - **Hardcode** when the option set is stable and frequently referenced (e.g. a status enum that drives a state machine), so the label vocabulary lives in source and rename-safety is enforced by greppable constants. A robust middle ground: prefer the live options, fall back to a hardcoded list per field so the UI still renders if the helper hasn't published yet.
 
 `useFieldOptions` is the read-side equivalent of using `useLinkedRecords` for foreign records — it abstracts away the field's option store. Items are shaped `{ id, label, color }` (note: `label`, not `title` like `useLinkedRecords`).

package/datasources/writing.md

@@ -128,6 +128,20 @@ updateRecord.mutate({
 });
 ```
 
+**No read follows a write** (measured live 2026-10-05 on a HubSpot-backed block). The network
+log showed the PATCH and then no read of the table until the block's own `refetch()`. The hook
+resolves to `{ id, fields }`: the PATCH response's record mapped through the hook's `fields:`
+select (seen in the compiled block bundle), and that response held only the written field.
+Nothing HubSpot-specific was seen in the hook's client code, so expect the same on other
+sources (inferred, untested elsewhere). So:
+
+- Call `refetch()` on every query that shows the written table.
+- If the source changes other fields itself with a delay (a HubSpot deal's probability, for
+  example), a `refetch()` in `onSuccess` can still return them old (inferred from a read at
+  +4 s; a read right after the write was not measured). Read the table again a few seconds
+  later as well; see
+  [Fields the source changes after the write](#fields-the-source-changes-after-the-write).
+
 #### CRITICAL: The `useRecordUpdate` payload shape (and the retired `.mutate()`-only rule)
 
 **Payload must be `{ recordId, fields: {...} }` — not flat.** Field values must be nested inside a `fields: {...}` object. The flat form (`mutate({ recordId, status: "active" })`) can succeed at runtime, but Softr's Action parser doesn't see field references inside it, so no Update Action is derived — `enabled` stays `false`, the UI gated on it silently does nothing, and Studio's Actions tab shows "No actions used in this block yet":
@@ -284,13 +298,62 @@ completes reads as broken. The pattern (verified live 2026-08-31 on a custom Kan
 3. **Revert on failure**: delete the override + `refetch()` → the card snaps back, with an
    error toast.
 4. **Clear on convergence**: an effect compares each override against fresh server data and
-   deletes it once they match — never clear on a timer.
+   deletes it once they match — never clear on a timer. Don't wait for fresh data to arrive
+   on its own: no read followed a write in the network log ([useRecordUpdate](#userecordupdate)),
+   so without a `refetch()` the override may never converge.
 5. **Undo**: snapshot the *server* state before mutating (previous lead, each row's previous
    value — per-row, since a batch may have had mixed values), and offer
    `toast.success(msg, { duration: 8000, action: { label: "Undo", onClick: restore } })`.
    The restore is just another optimistic move driven by the snapshot. Snapshot before the
    write, not from the UI — the UI may already be showing an optimistic override.
 
+### Fields the source changes after the write
+
+Some sources change other fields of a record when one is written. HubSpot stamps a deal's close
+date when it closes and recalculates its probability and weighted amount a few seconds later. A
+formula or rollup that depends on the written field recalculates on any source (inferred). No
+read follows a write, and a source that applies its own changes with a delay can still serve the
+old values to a `refetch()` in `onSuccess` (inferred). So read the written table again once the
+source has settled (verified live 2026-10-05 on HubSpot deals):
+
+```tsx
+// After a save the source changes some fields itself, a few seconds later, so the written
+// table is read again twice. The timers are cleared if the block unmounts first.
+const followUps = useRef<number[]>([]);
+useEffect(() => () => followUps.current.forEach((t) => window.clearTimeout(t)), []);
+
+async function saveStage(id: string, stage: string) {
+  if (!updateDeal.enabled) return;
+  try {
+    await updateDeal.mutateAsync({ recordId: id, fields: { stage } });
+  } catch {
+    toast.error("We couldn't save the change. Try again.");
+    return;
+  }
+  void dealsQ.refetch();
+  followUps.current = followUps.current.concat(
+    [4000, 12000].map((ms) => window.setTimeout(() => void dealsQ.refetch(), ms)),
+  );
+}
+```
+
+- **The delays depend on the source.** On HubSpot the read at +4 s already had the new stage
+  and close date, but the probability and weighted amount still held the previous write's
+  values. The read at +12 s had everything. HubSpot's own follow-up change landed 9 to 11 s
+  after a ticket write, so +12 s leaves about a second of margin: go later rather than earlier.
+  Measurements and the list of what HubSpot changes:
+  [hubspot.md](hubspot.md#what-hubspot-changes-after-a-write).
+- **Keep the immediate `refetch()` too.** A read right after the write was not measured.
+  HubSpot documents that changes take "a few moments" to reach its search, but whether Softr's
+  list reads use that search is not documented. With an optimistic override the immediate read
+  may add little; it is cheap and keeps the `refetch()`-in-`onSuccess` rule whole.
+- **Show the known outcome at once.** When you know what the source will set (today's date as
+  a closing deal's close date), show it in the override and let the re-read replace it.
+- **Only where it's needed.** Add the delayed reads when the block shows a field the source
+  sets or computes. A plain field the user wrote needs nothing more than the usual `refetch()`.
+
+## File Uploads
+
 ```jsx
 import { useUpload } from "@/lib/datasource";
 
@@ -369,6 +432,12 @@ parentAccount: "RECORD_ID_1"
 string-array shape is the verified current form on Softr Database; if a linked-record write
 fails on an Airtable-backed block, try the `[{ id }]` object shape before deeper debugging.
 
+**HubSpot associations: the string array worked on a create, but an update needs `[{ id }]`
+objects** (verified live 2026-10-05, one ticket). A create with `company: ["<id>"]` linked the
+ticket; a create with `[{ id }]` is untested. An update with string arrays failed with 500; with
+`[{ id }]` it worked and **replaced** the ticket's company list. See
+[hubspot.md](hubspot.md#association-writes).
+
 ### Linked-record write traps (verified live 2026-08-26)
 
 Four Softr Database behaviors proven by direct experiment on a live production build — a
@@ -438,6 +507,10 @@ keep vocabularies as greppable constants, or fetch them live with `useFieldOptio
 [reading.md](reading.md#usefieldoptions----fetch-singlemulti-select-choices)) and write
 `option.label`.
 
+**On HubSpot, write the choice id** (`"closedwon"`, `"1"`; verified live 2026-10-05 on
+`dealstage` and `hs_pipeline_stage`). Whether HubSpot also accepts the label is untested, so
+don't rely on it; see [hubspot.md](hubspot.md#writing).
+
 **Legacy note.** Until mid-2026 this skill documented the opposite — write the option UUID,
 labels rejected (verified April 2026 on the then-current platform). If a label write is
 rejected on an old app, the UUID form is the thing to try; on the current platform it is not
@@ -445,7 +518,7 @@ needed.
 
 ### Linked Record
 
-Array of record-id **strings** (`["RECORD_ID"]`) on Softr Database (verified 2026-08-25); the legacy / Airtable fallback shape is `[{ id }]` objects. See "Linked Record Format for Mutations" above.
+Array of record-id **strings** (`["RECORD_ID"]`) on Softr Database (verified 2026-08-25); the legacy / Airtable fallback shape is `[{ id }]` objects. HubSpot associations: the string array worked on create; an update needs `[{ id }]` and replaced the company list (verified 2026-10-05, one ticket; [hubspot.md](hubspot.md#association-writes)). See "Linked Record Format for Mutations" above.
 
 ### Multi-Select
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "softr-vibe-coding",
-  "version": "2.13.0",
+  "version": "2.13.1",
   "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

@@ -34,10 +34,11 @@ Run through this catalog before delivering any block. Every row is a violation o
 | Assuming `mutation.enabled === false` always means a code bug | `enabled` is BOTH a parser signal AND a permissions signal. Per the official Softr docs, "`enabled` reflects user permissions." When code looks correct and the Actions tab shows the action listed, the cause is almost always permissions. Test by switching "Preview as" in Studio to an Owner / admin; if it then works, the issue is permissions. Three places to check, in priority order: (1) the block's **Visibility** tab (right panel), (2) **Studio → Users → Data Restrictions → Global data restrictions** — an app-wide layer that easily gets overlooked because it's hidden under Users (not on the block); it overlays every block in the app, and a single restriction on the target table will silently disable every mutation against that table for the affected user group, (3) the data-source PAT scope — if granted read-only, every write fails regardless of UI permissions. See [datasources/writing.md](../datasources/writing.md#how-actions-work-studios-actions-tab) |
 | `deleteRecord.mutate({ id: r.id })` | `deleteRecord.mutate(r.id)` -- just the string |
 | `var { mutateAsync } = useRecordUpdate({...})` -- destructuring the mutate function off the hook | `var updateRecord = useRecordUpdate({...})` -- keep the full object so `.enabled`, `.status`, `.reset()` stay reachable (using `.mutateAsync` itself is fine) |
-| Not calling `refetch()` after mutations | Always `refetch()` in `onSuccess` |
+| Not calling `refetch()` after mutations | Always `refetch()` in `onSuccess`. The runtime issued no read after a write (measured live 2026-10-05 on a HubSpot-backed block), so without it the list is never re-read. If the source changes other fields itself (HubSpot stamps a closing deal's close date and recalculates its probability a few seconds later), read again a few seconds later too — see [writing.md](../datasources/writing.md#fields-the-source-changes-after-the-write) |
 | Including read-only fields (formula / rollup / aiText / lookup / createdTime / lastModifiedTime / autoNumber) in the `fields` q.select passed to `useRecordCreate` or `useRecordUpdate` | Softr's Action parser silently rejects the **entire** create/update Action — not just the bad alias. Same all-or-nothing failure mode as a renamed/missing column: Studio's Actions tab shows "No actions used in this block yet", `createRecord.enabled` / `updateRecord.enabled` stays `false`, `.mutate()` calls dispatch but resolve to "not yet ready", every OTHER writable field in the same q.select is also lost. Reads handle these field types fine — only the write q.select chokes. Fix: split into separate q.selects per the Three Mappings Pattern (`useRecord` / `useRecords` gets the full select with read-only fields; `useRecordCreate` / `useRecordUpdate` gets a writable-only subset). Diagnostic when the symptom shows up: same bisection procedure as the renamed-column case — strip the write q.select to a known-writable minimum, then add fields back in halves until the Action drops out. Verified 2026-05-22: `blocks/wig-details/wig-details-page.jsx` shared one `wigSelect` between `useRecord` and `useRecordUpdate`; the select included `Wig Tag ID` (formula), `Total client price` (rollup), `Total worker pay` (rollup), `Instrucciones` (aiText) — Update Action stayed disabled until those four read-only fields were lifted out into a separate write-only select. See [datasources/airtable.md](../datasources/airtable.md#maintainability-gotcha) and [datasources/writing.md](../datasources/writing.md). |
-| Linked record as bare string, or `[{ id }]` objects on Softr Database | Array of record-id **strings**: `familyLink: [familyId]` — verified live 2026-08-25 on Softr DB. (The `[{ id }]` object shape was the May 2026 verified form on Airtable-backed blocks; try it if a string-array write fails there.) See [datasources/writing.md](../datasources/writing.md#linked-record-format-for-mutations) |
-| Writing dropdown values as `{ id, label }` objects (the read shape) or hunting for option UUIDs | Write the option **LABEL string**, exactly matching a defined choice — e.g. `status: "Active"` (verified live 2026-08-25; supersedes the April 2026 UUID rule). Keep vocabularies as greppable constants or fetch live via `useFieldOptions` and write `option.label` |
+| Linked record as bare string, or `[{ id }]` objects on Softr Database | Array of record-id **strings**: `familyLink: [familyId]` — verified live 2026-08-25 on Softr DB. (The `[{ id }]` object shape was the May 2026 verified form on Airtable-backed blocks; try it if a string-array write fails there.) HubSpot associations: the string array worked on create, but an update needs `[{ id }]` (the string array returned 500; verified live 2026-10-05). See [datasources/writing.md](../datasources/writing.md#linked-record-format-for-mutations) |
+| Adding one HubSpot association with `useRecordUpdate`, e.g. `fields: { company: [{ id: newId }] }` | The update **replaced** the whole company list (verified live 2026-10-05, one ticket), and Softr's read afterwards showed no primary company (not checked in HubSpot). Writing the full list back with the new id is untested and would likely drop the primary label too (inferred); or add the link from a workflow that calls HubSpot's associations API — see [hubspot.md](../datasources/hubspot.md#association-writes) |
+| Writing dropdown values as `{ id, label }` objects (the read shape) or hunting for option UUIDs | Write the option **LABEL string**, exactly matching a defined choice — e.g. `status: "Active"` (verified live 2026-08-25; supersedes the April 2026 UUID rule). Keep vocabularies as greppable constants or fetch live via `useFieldOptions` and write `option.label`. **Except on HubSpot**, which takes the choice **id** as a plain string (`"closedwon"`; verified live 2026-10-05, label untested; see [hubspot.md](../datasources/hubspot.md#writing)) |
 | Writing a formatted phone value (`(212) 555-0100`, `212-555-0100`) to a PHONE field | Sanitize to unformatted international format — `+` followed by digits only (`+12125550100`) — before `mutate()`; some datasources (Monday.com, per the official guide) reject formatted values outright. Official sanitizer: `const sanitizePhone = (raw) => raw.replace(/[^\d+]/g, "").replace(/(?!^)\+/g, "");` See [datasources/writing.md](../datasources/writing.md#phone) |
 | Wrapping a `useRecordCreate` payload in `{ fields: {...} }` (copied from an update call) | Create payloads are **FLAT** — `createRecord.mutate({ name: "Jane" })`. Only update payloads nest: `{ recordId, fields: {...} }`. The asymmetry is by design (verified 2026-08-25) |
 | Passing a data hook's options through a variable or wrapper function: `useRecords(buildOpts())` | **Fails to compile** — the options object must be an inline literal at the call site (verified live 2026-08-25; hit in production, fixed by making the wrapper take the hook's *result* instead). Share `q.select` mappings between hooks, never whole options objects |

package/references/helper-blocks.md

@@ -10,9 +10,9 @@ Cross-block communication via `window` globals, the invisible helper block patte
 - [Companion Field Helpers](#companion-field-helpers)
 - [Breadcrumb / Back Navigation](#breadcrumb--back-navigation)
 - [Multi-Table Access via Invisible Helper Blocks](#multi-table-access-via-invisible-helper-blocks)
-- [Publisher Template](#publisher-template)
-- [Consumer Pattern](#consumer-pattern)
-- [useWindowData Custom Hook](#usewindowdata-custom-hook)
+- [Publisher Template](#publisher-template-the-invisible-helper-block)
+- [Consumer Pattern](#consumer-pattern-inside-the-main-block)
+- [useWindowData Custom Hook](#usewindowdata-custom-hook-cleaner-consumer)
 - [Triggering Actions in Other Blocks (Bi-Directional Events)](#triggering-actions-in-other-blocks-bi-directional-events)
 - [Advanced Patterns](#advanced-patterns)
 - [Anti-Patterns](#anti-patterns)