softr-vibe-coding 2.11.0 → 2.12.0

package/CHANGELOG.md

@@ -4,6 +4,12 @@ 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.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
+
 ## [2.11.0] - 2026-10-01
 - Track Softr's 2026-10-01 MCP release: renamed tools, sourceSha256 push checks, stub-tool root cause
 

package/README.md

@@ -195,8 +195,14 @@ softr-vibe-coding/
 │   │                                 # enforces on block data endpoints, "Preview as"
 │   │                                 # role testing, search-replace on 100KB+ blocks
 │   │                                 # (Sep 18 2026); Oct 1 2026: tool rename map,
-│   │                                 # push verification by sourceSha256, stub-tool
-│   │                                 # root cause, update_field/update_table fixes
+│   │                                 # 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,

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) |
@@ -570,8 +572,9 @@ Non-negotiable rules. Most are enforced by the Softr platform (compiler, validat
     everyone can see it comes back `ALL_USERS`, i.e. writable by logged-OUT visitors (UPDATE/DELETE
     reset to logged-in users). The MCP call that re-tightens it (`vibe_coding_block_set_action_visibility`)
     can itself fail with no fallback. It fails when the client holds only a stub of the tool
-    (name-only description, no properties), which happens after a session resume, so check the
-    loaded definition and start a fresh session if it is a stub (see
+    (name-only description, no properties), which has happened after a session was resumed. Check
+    the loaded definition; if it is a stub, start a fresh top-level session (a subagent inherits the
+    stubs) (see
     [references/softr-mcp.md](references/softr-mcp.md#the-array-argument-rejection-and-why-it-is-a-security-issue)).
     A push that returns `errors: null` can still have left public write access on the block.
     **If any action is still broader than intended, report it WITH its severity and let the builder decide.**

package/package.json

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

@@ -44,7 +44,7 @@ Run through this catalog before delivering any block. Every row is a violation o
 | Tightening Actions-tab permissions before the block's final redeploy | Every code recompile **resets the auto-registered Actions to default permissions** (verified live 2026-08-25). Tighten permissions after the LAST redeploy, and re-check after any future one |
 | Assuming a comment-only edit is "safe" and leaves Action permissions alone | There is no cosmetic-edit exemption. Any save recompiles, and every recompile rebuilds the Actions at default visibility — a `search_replace` changing nothing but a code comment resets them exactly like a rewrite (verified live 2026-09-09, on two blocks at once). Re-check after EVERY push, including cosmetic ones |
 | Treating the permission-restore call as done because you issued it | Read the permissions back with `vibe_coding_block_get_settings` and confirm each one changed. `vibe_coding_block_set_action_visibility` can fail outright on the array-argument rejection (the client holding only a stub of the tool, typically after a session resume), and it has **no fallback** — the default for ADD_RECORD follows the block's own visibility, so on a block everyone can see, a routine push silently leaves it publicly writable while returning `errors: null`. Verified live 2026-09-09: four ADD_RECORD actions left open across two blocks. Report the list with its severity — check the page's VIEW permission with `application_page_get_permissions`, since a logged-in-gated page makes this housekeeping while a public page makes it a real hole — and let the builder decide whether it holds their release. A human sets them on the block's Actions tab |
-| Calling an array-argument MCP tool (`vibe_coding_block_set_action_visibility`, `vibe_coding_block_update_code_search_replace`) when its loaded definition is a stub — description identical to the tool name, schema `{"type":"object"}` with no properties | A stub declares no types, so the array is sent as a JSON string and rejected (since 2026-10-01 the error reads "Parameter '…' must be an array of objects, but a string was sent"). Stubs appear after a session resume. Start a fresh session, which reloads the real definitions, then call. Root cause established 2026-10-01 — see [softr-mcp.md](softr-mcp.md#the-array-argument-rejection-and-why-it-is-a-security-issue) |
+| Calling an array-argument MCP tool (`vibe_coding_block_set_action_visibility`, `vibe_coding_block_update_code_search_replace`) when its loaded definition is a stub — description identical to the tool name, schema `{"type":"object"}` with no properties | A stub declares no types, so the array is sent as a JSON string and rejected (since 2026-10-01 the error reads "Parameter '…' must be an array of objects, but a string was sent"). Stubs have appeared after a session was resumed, and subagents spawned from that session inherit them. Start a fresh top-level session, which reloaded the real definitions when we tried it, then call. Found 2026-10-01 — see [softr-mcp.md](softr-mcp.md#the-array-argument-rejection-and-why-it-is-a-security-issue) |
 | Verifying a push by pulling the whole block source back into the model's context | Compare `sourceSha256` from the push result (or from `vibe_coding_block_get_code` with `includeCode: false`) with `shasum -a 256` of the file you sent; fetch the full source only when the digest is missing or differs. Available since 2026-10-01 — see [softr-mcp.md](softr-mcp.md#verifying-a-push--the-deployed-source-is-the-only-proof) |
 | Splitting one table's writes across several `useRecordUpdate` hooks (or across two connections of the same table) to get separately-permissioned Actions | Actions register per **TABLE**: the hooks merge into ONE UPDATE_RECORD action whose field list is the union, and a hook pointed at a second connection of the table is still filed under the FIRST connection's dataSourceId (verified live 2026-09-18). Point writes at the table's first connection; expect one action per table + operation when re-tightening permissions. See [datasources/writing.md](../datasources/writing.md#actions-register-per-table-not-per-hook-or-connection) |
 | Treating Studio's Actions tab as a separately-managed configuration to keep in sync with code | Actions auto-derive from your `useRecordCreate`/`useRecordUpdate`/`useRecordDelete` + `q.select` on every save. The Actions tab is a read-only inspector; there is no manual delete control. To change an Action, change the code |

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/softr-mcp.md

@@ -35,13 +35,13 @@ The official Softr MCP server (`https://mcp.softr.io/mcp`) gives an AI assistant
 | Applications | **Create whole apps**; manage app users and login settings; swap an app's data source; read apps, pages, blocks, permissions, user groups; preview; publish — see [Application management tools](#application-management-tools) | https://docs.softr.io/mcp/apps |
 | Vibe coding blocks | Create and edit blocks, manage settings, visibility, versions, data source connections | https://docs.softr.io/mcp/vibe-coding |
 | Integrations | Browse external data sources connected to the workspace, down to field level | https://docs.softr.io/mcp/integrations |
-| Workflows | Build, wire, test, and publish workflows — 26 tools and a 418-node trigger/action catalog; see [Workflows](#workflows) | https://docs.softr.io/mcp/workflows |
+| Workflows | Build, wire, test, and publish workflows — 28 tools and a 418-node trigger/action catalog; see [Workflows](#workflows) | https://docs.softr.io/mcp/workflows |
 
 `workspace_list` is often the first call — it turns "my Sales workspace" into the workspace ID every other tool needs. The server's own instructions now start from `application_list` (applications and their workspace IDs) and `database_list` (databases), and keep `workspace_list` for turning a workspace name into an ID.
 
 ## Tool names — the 2026-10-01 rename
 
-On 2026-10-01 Softr renamed every workspace-server tool outside Workflows to **area first, then verb**:
+On 2026-10-01 Softr renamed the workspace-server tools outside Workflows to **area first, then verb**:
 `vibe_coding_block_*`, `application_*` (pages are `application_page_*`), `database_*`,
 `integration_*` and `workspace_*`. 79 tools were renamed and one was added
 (`application_update_pwa_settings`); the 28 Workflows tools and `get_workspace_integrations` kept their names. The
@@ -264,9 +264,10 @@ unverified until the deployed source is proven identical to your file.
 search-replace) and `vibe_coding_block_get_code` carry `sourceSha256` and `sourceBytes`: the SHA-256
 of the UTF-8 source Softr persisted, and its length in bytes. A failed compile stores nothing and
 reports neither field. With `includeCode: false`, `vibe_coding_block_get_code` returns the digest and
-`sourceCode: null`. Verified live 2026-10-01: a deployed block's `sourceSha256` equalled
-`shasum -a 256` of the file last pushed to it, and the read came back at about 1 KB for a 15 KB
-block. (The digest on push results is per Softr's release notes; no push of ours has shown it yet.)
+`sourceCode: null`. Verified live 2026-10-01: a deployed block's `sourceSha256` equalled the SHA-256
+of the exact source last pushed to it (taken from the push call), and the read came back at about
+1 KB for a 15 KB block. The same check showed that block's local mirror had picked up three comment
+edits since that push, which is exactly what step 1 below exists to catch. (The digest on push results is per Softr's release notes; no push of ours has shown it yet.)
 Right after that release our client's copy of the tool definition did not declare `includeCode`, so
 the argument went out as the string `"false"` and the server still honoured it. Whatever the loaded
 definition says, check that `sourceCode` came back `null`.
@@ -292,8 +293,10 @@ 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
-58 push→fetch pairs between 2026-08-26 and 2026-09-10 (14 blocks, 16–161 KB each) the fetched
+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
 final newline and stored without one. The "deployed block is one byte shorter" we chased on
 2026-09-09 was our own read: an agent that reads a large file in chunks can drop the final
@@ -347,19 +350,23 @@ from String value (token `JsonToken.VALUE_STRING`)
 | `vibe_coding_block_update_code_search_replace` | `operations` | Start a fresh session (below) | Use `vibe_coding_block_update_code` (full replace) |
 | `vibe_coding_block_set_action_visibility` | `updates` | Start a fresh session (below) | **NONE — a human must fix it in Studio** |
 
-**Where the string comes from — root cause found 2026-10-01: tool stubs in a resumed session.**
-When Claude Code resumes a session, MCP connector tools it already knew can come back as **stubs**:
-the description is just the tool name and the input schema is `{"type":"object"}`, with no
-properties. They stay stubs until the connector delivers its definitions again, which a fresh session
-does (so did reconnecting the connector, once). A stub declares no types, so an array argument
-goes out as a JSON string and Softr rejects it. Nothing is written, so the failure is safe, but no
-amount of care on the caller's side gets an array through a stub. The evidence, from the complete
-transcripts of one build:
+**Where the string comes from: tool stubs on the client side (found 2026-10-01).** In the sessions
+we examined, our client (Claude Code) at times held the Softr tools as **stubs**: the description is
+just the tool name and the input schema is `{"type":"object"}`, with no properties. A stub declares
+no types, so an array argument goes out as a JSON string and Softr rejects it. Nothing is written,
+so the failure is safe, but no amount of care on the caller's side gets an array through a stub.
+The evidence, from the complete transcripts of one build:
 
 - On 2026-09-09 every successful array call came before that session was resumed, and every
   rejected one came after.
-- On 2026-09-30, in a resumed session, every Softr tool definition the client recorded was a stub.
-- A fresh session on 2026-10-01 loaded the full definitions.
+- On 2026-09-30, after the session was picked up again, every Softr tool definition the client
+  recorded was a stub: in the session itself and in all 47 subagents it spawned. A live tool-list
+  update from the server that day did not change that.
+- Only two things ever replaced the stubs with real definitions: re-adding the connector (once) and
+  a fresh session (2026-10-01).
+- Not every pick-up produced stubs: a session picked up on the morning of 2026-09-09 held real
+  definitions. So the trigger is not fully understood. The stubs most likely come from our side
+  rather than Softr's server, since a fresh session got full definitions from the same server.
 
 This replaces two earlier explanations in this file: that the model "had not loaded the tool
 definitions" (2026-09-10), and that the workspace server's tools "can arrive schema-less"
@@ -370,7 +377,8 @@ publish full schemas.
 
 **The rule:** before any array-argument call, look at the tool's loaded definition (ToolSearch shows
 it). If the description is just the tool name and there are no `properties`, do not make the call:
-start a fresh session first. That matters most for `vibe_coding_block_set_action_visibility`, which
+start a fresh top-level session first. A subagent is not a fresh session; it inherits the stubs.
+That matters most for `vibe_coding_block_set_action_visibility`, which
 has no fallback. For a code edit, a full replace is an acceptable stopgap: one file per subagent for
 a large block, hash-verified.
 
@@ -378,8 +386,8 @@ a large block, hash-verified.
 block's auto-registered Actions at Softr's default permissions. Per Softr (2026-10-01), the default
 for **ADD_RECORD follows the block's own visibility**. On a block everyone can see, it comes back
 `ALL_USERS`, writable by logged-OUT visitors. UPDATE_RECORD and DELETE_RECORD are always reset to
-`LOGGED_IN_USERS`. That is what we saw on 2026-09-09, when one push left four ADD_RECORD actions
-open across two blocks. The remedy is to re-apply the permissions with
+`LOGGED_IN_USERS`. That is what we saw on 2026-09-09, when one round of pushes (two saves, one per
+block) left four ADD_RECORD actions open across two blocks and every restore call was rejected. The remedy is to re-apply the permissions with
 `vibe_coding_block_set_action_visibility`. When that call is the one that fails, a routine cosmetic
 push silently leaves public write access on the block. Nothing in the push result says so: the push
 itself returns `errors: null, warnings: null`.
@@ -522,8 +530,8 @@ Combined with the database tools (`database_create` / `database_create_table` /
   blocks yet. Softr has said placement will come later. Until then, a human drags it into place in
   Studio. Say so when you hand the block over.
 - **Timestamps are UTC with a `Z`.** Since 2026-10-01, timestamps such as `publishedAt` or a
-  version's `createdAt` are ISO-8601 UTC with millisecond precision on both server kinds (verified
-  on `vibe_coding_block_list_versions` that day). Before then, studio-side timestamps came back with
+  version's `createdAt` are ISO-8601 UTC with millisecond precision, studio-side and tables-side
+  alike (per Softr; verified on `vibe_coding_block_list_versions` that day). Before then, studio-side timestamps came back with
   no zone designator and nine fractional digits (`2026-09-09T22:34:11.157881061`). They were UTC, so
   read any older logged value as UTC, never as local time.
 
@@ -602,7 +610,7 @@ For Softr's native databases the MCP goes far beyond browsing: `database_get_fie
 
 **Call economy (from the server's own instructions):** `database_get_table` returns a table's metadata AND all its field definitions in one call; `database_list_fields` returns the fields alone. Call ONE of them once per table and reuse the result — never both — and re-fetch only after you changed the table's fields yourself.
 
-**`database_get_field_reference` (was `get_schema`).** It describes the whole product, not one table: it takes no table ID and returns the same content every time. Live-confirmed 2026-08-31: `readOnlyFieldTypes` = AUTONUMBER, COUNT, CREATED_AT, CREATED_BY, FORMULA, LOOKUP, RECORD_ID, ROLLUP, UPDATED_AT, UPDATED_BY. On 2026-10-01 the list was the same without COUNT, which no longer appears in either the read-only list or the field types. The `LINKED_RECORD` value example is `["record-id-1", "record-id-2"]` — independently corroborating the verified string-array write shape in [../datasources/softr-database.md](../datasources/softr-database.md). On 2026-10-01 it listed `allowMultipleEntries` among the available options of SELECT and LINKED_RECORD. Operator families include relative-date `IS_WITHIN` / `IS_NOT_WITHIN` ("last 7 days"), ternary `IS_BETWEEN` / `IS_NOT_BETWEEN`, and `AND`/`OR` composites. **Schema-drift caution:** this reference and the [per-application servers'](#per-application-mcp-servers) `get_schema` have drifted. The per-app catalog lists creatable types the workspace one omits: ADDRESS, PROGRESS, TIME, DATE_RANGE and BUTTON were still absent from the workspace reference on 2026-10-01, although, per Softr, the workspace server returns fields of those types. The operator NAMES differed too (workspace `GREATER_THAN` / `DOES_NOT_CONTAIN` vs per-app `GT` / `DOES_NOT_CONTAINS`, observed 2026-08-31); per Softr the per-app names were realigned on 2026-09-09, which we have not re-checked. Do not assume a filter payload is portable between the two kinds: call the reference of the server you are actually using.
+**`database_get_field_reference` (was `get_schema`).** It describes the whole product, not one table: it takes no table ID and returns the same content every time. Live-confirmed 2026-08-31 (and in reads of 2026-08-26 and 2026-09-09): `readOnlyFieldTypes` = AUTONUMBER, COUNT, CREATED_AT, CREATED_BY, FORMULA, LOOKUP, RECORD_ID, ROLLUP, UPDATED_AT, UPDATED_BY. On 2026-10-01 the list was the same without COUNT, which no longer appears in either the read-only list or the field types. The `LINKED_RECORD` value example is `["record-id-1", "record-id-2"]` — independently corroborating the verified string-array write shape in [../datasources/softr-database.md](../datasources/softr-database.md). On 2026-10-01 it listed `allowMultipleEntries` among the available options of SELECT and LINKED_RECORD. Operator families include relative-date `IS_WITHIN` / `IS_NOT_WITHIN` ("last 7 days"), ternary `IS_BETWEEN` / `IS_NOT_BETWEEN`, and `AND`/`OR` composites. **Schema-drift caution:** this reference and the [per-application servers'](#per-application-mcp-servers) `get_schema` have drifted. The per-app catalog lists creatable types the workspace one omits: ADDRESS, PROGRESS, TIME, DATE_RANGE and BUTTON were still absent from the workspace reference on 2026-10-01, although, per Softr, the workspace server returns fields of those types. The operator NAMES differed too (workspace `GREATER_THAN` / `DOES_NOT_CONTAIN` vs per-app `GT` / `DOES_NOT_CONTAINS`, observed 2026-08-31); per Softr the per-app names were realigned on 2026-09-09, which we have not re-checked. Do not assume a filter payload is portable between the two kinds: call the reference of the server you are actually using.
 
 Known limits and behaviors (per official docs):
 
@@ -694,7 +702,7 @@ A separate product class from the workspace server (live-observed 2026-08-31 on
 
 **Tools (12):** `list_tables`, `describe_table`, `get_schema`, `get_records`, `get_record`, `get_linked_records`, `get_current_user`, `create_record`, `update_record`, `delete_record`, `batch_update_records`, `batch_delete_records`. These are this server's own names, last enumerated by us in late August 2026; the 2026-10-01 rename of the workspace server did not touch them.
 
-**If the tool definitions arrive empty, do not conclude the server sent them that way.** Every definition of these tools our client ever recorded had a name-only description and an `{"type":"object"}` schema, the same signature as the stubs described [above](#the-array-argument-rejection-and-why-it-is-a-security-issue). Unlike the workspace stubs, these were stubs even at times when the same client held real workspace definitions, so their cause is not settled. Per Softr, these servers publish full schemas and descriptions. A tool with no arguments (`list_tables`, `get_schema`, `get_current_user`) works either way; before relying on one that takes arguments, start a fresh session and check the loaded definition again.
+**If the tool definitions arrive empty, do not conclude the server sent them that way.** Every definition of these tools our client ever recorded had a name-only description and an `{"type":"object"}` schema, the same signature as the stubs described [above](#the-array-argument-rejection-and-why-it-is-a-security-issue). Unlike the workspace stubs, these were stubs even at times when the same client held real workspace definitions, so their cause is not settled. Per Softr, these servers publish full schemas and descriptions. A tool with no arguments (`list_tables`, `get_schema`, `get_current_user`) works either way; before relying on one that takes arguments, start a fresh top-level session and check the loaded definition again.
 
 **Live-observed semantics:**