softr-vibe-coding 2.1.1 → 2.1.2

package/CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to this skill are documented here. Versions follow [Semantic
 
 Entries from 1.3.1 onward are generated automatically from git commit subjects between version bumps (see `.github/workflows/publish.yml`). Entries before 1.3.1 were backfilled by hand from the existing commit history.
 
+## [2.1.2] - 2026-08-26
+- Document four linked-record write traps verified live 2026-08-26
+- Fail the build when main moves ahead of npm
+
 ## [2.1.1] - 2026-08-26
 - Release 2.1.1
 - Document external-URL attachment ingestion (copy, not link)

package/datasources/writing.md

@@ -291,6 +291,43 @@ 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.
 
+### Linked-record write traps (verified live 2026-08-26)
+
+Four Softr Database behaviors proven by direct experiment on a live production build — a
+49-link backfill across a self-referencing parent/child pair. They bite hardest in backfills
+and schema work, and **none of them raises an error**.
+
+1. **A single-valued link pair is enforced ON WRITE — and it clobbers silently.** With
+   `allowMultipleEntries: false` on the inverse side, writing child N's link to a parent
+   silently unlinks child N−1: no error, the earlier link just vanishes (16 of 49 backfill
+   links disappeared this way before it was caught). Pre-existing multi links DO survive a
+   flip from multi to single, which is why a scratch-table spike that flips an
+   already-linked pair reports the setting as "cosmetic only" and misleads — the
+   enforcement only fires on the next write. If one side must hold many links, both sides
+   must allow multiple entries; enforce any one-parent rule in the UI, not the schema.
+
+2. **`allowMultipleEntries` is a TOP-LEVEL field property, not part of `options`.** The
+   workspace MCP's `update_field` silently ignores it when nested inside `options` — the
+   call succeeds and changes nothing. A Tables API `PUT /fields/{id}` with the property at
+   top level works.
+
+3. **A Tables API field PUT that omits `options.inverseLinkFieldId` SEVERS the inverse
+   pairing** — it comes back `null` and the two sides stop mirroring each other. Always
+   echo `inverseLinkFieldId` inside the `options` you send, and re-read BOTH sides after
+   any linked-record field PUT to confirm the pairing survived.
+
+4. **An empty multi-entry link reads back as `[]`, which is truthy in JS.** Any
+   "already linked — skip" guard written as `if (value)` matches every record after a
+   single→multi flip, so a resumable backfill re-processes nothing or skips everything.
+   Test presence explicitly:
+
+   ```jsx
+   const hasLink = Array.isArray(v) ? v.length > 0 : !!v;
+   ```
+
+   (The populated read shapes are in [fields.md](fields.md); this is the empty case, and
+   it becomes a write trap the moment a backfill uses it as a skip condition.)
+
 ## Writing to Field Types
 
 Different Softr field types accept different value shapes in mutation payloads. The shape returned when you READ a field is often different from the shape you must SEND when you WRITE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "softr-vibe-coding",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "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/softr-mcp.md

@@ -122,6 +122,13 @@ Known limits and behaviors (per official docs):
   `{ filename, url }` on an ATTACHMENT field with any publicly reachable URL; Softr fetches it, stores its
   own copy and generates thumbnails, so backfilling images from another system is one write per record
   with no upload step. Verified 2026-08-26 — see [../datasources/writing.md](../datasources/writing.md#attachment).
+- **`update_field` silently ignores `allowMultipleEntries` nested inside `options`** — it is a TOP-LEVEL
+  field property; the call succeeds and changes nothing (verified 2026-08-26). To flip a LINKED_RECORD
+  field between single and multi, `PUT` it via the Tables API with `allowMultipleEntries` at top level —
+  and always echo `options.inverseLinkFieldId` in that PUT, because omitting it severs the inverse
+  pairing. Full write-up, including the silent on-write clobbering of single-valued link pairs and the
+  truthy-`[]` empty-link read shape:
+  [../datasources/writing.md](../datasources/writing.md#linked-record-write-traps-verified-live-2026-08-26).
 - Limits: 100 records per `create_records` call, 200 records per read (silently capped, not an error), 2 group-by fields in `aggregate_data`. For big tables prefer a filter or aggregate over paging.
 
 Typical Vibe Coding uses: "list every field on `Wigs` with id, name, type, and dropdown options", "what's the option id for `Payment status` = 'Partially paid'?", "show 3 sample records so we know value shapes", "verify the field id in my `q.select()` exists". This eliminates the field-id-typo / wrong-option-uuid class of bugs entirely.