softr-vibe-coding 2.4.0 → 2.4.2

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.4.2] - 2026-09-01
+- softr-mcp.md: Workflows build/publish loop verified end to end 2026-09-01 (10 production workflows built live via MCP), replacing the not-yet-exercised hedge with build-loop findings: create_workflow instantiates an OLD trigger node version — immediately replace_trigger_node with the same type for current inputs (updateField on SOFTR_TABLES_RECORD_UPDATED only exists at v1.2.0); FILTER conditions set via update_node_inputs inputName "condition" ({operator, conditions} object stored on the outgoing path like the builder); LOOP_ACTION_GROUP loopVariables.items must be a plain array like $.records — [*] projections rejected by the validator, per-item refs inside the loop via {loopActionGroup.<id>:::loopVariables.items.fields.<fieldId>} (bracket form for digit-leading ids); update_node_inputs batches validate against STORED node state so dependent updates split into sequential calls; test-safety doctrine — record-write nodes REAL_ONLY (never test against production), SOFTR_SEND_EMAIL always mode:"mock", triggers/GET_RECORDS REAL_ONLY but read-only-safe. Plus: workspace update_field on SELECT silently drops added choices (echoes old set, no error) — add choices in Studio or let allowToAddNewChoice auto-create on first unknown-label write; joins the allowMultipleEntries silent-ignore
+
+## [2.4.1] - 2026-09-01
+- Reconcile the brand pipeline with building-design-md v2.0.0, which now drives dembrandt too. README migration note un-retires the companion: it runs the same dembrandt engine and layers voice & copy register, a resolved fonts block, logo assets, app-pattern scaffolds, and custom-code-header.html on an untouched dembrandt base. references/dembrandt.md legacy note becomes a companion-skill note (v2+ files read natively here; v1.x brand:/source:/extracted: files remain valid). SKILL.md Step 1 offers the fuller foundation alongside its quick raw generation and honours companion-v2 extra sections, preferring a fonts block over computed fontFamily values
+
 ## [2.4.0] - 2026-09-01
 - Replace building-design-md with dembrandt as the Step 1 DESIGN.md generator. New references/dembrandt.md operating guide: MCP install via npx pinned @latest (deliberate deviation from upstream README — bare npx reuses its cache and never re-checks the registry) + one-time install-browser step (CLI self-heals a missing browser since 0.30.0, the MCP server does not — exact error string and remediation documented), the get_design_tokens → get_job_status → get_findings → generate_design_md flow behavior-tested live 2026-09-01 (async job_id default; completion returns the FULL extraction — 65KB for one page — so pass job_id downstream, never the payload; completed jobs kept 1 hour; generate_design_md returns markdown text and writes no file — the agent writes ./DESIGN.md in the project root), multi-page crawl doctrine (pages 3–5 / --crawl 5; live 1-page noise: 46 near-duplicate text tokens, 2.72px spacing steps, white-on-white button sample), DESIGN.md anatomy per Google draft spec 0.4 (name/description/colors/typography/spacing/rounded/components frontmatter — context-named typography tokens with text-N fallback, source URL inside description, no date field; Font URLs vs computed ui-sans-serif cross-check), failed-job remediation (slow retry / CLI firefox for Cloudflare / install-browser), authoring custom-code-header.html from DESIGN.md tokens (provenance claim fixed in native-chrome-styling.md — dembrandt generates no Softr-ready CSS), compute_drift brand QA (drift = did it change, findings = is it good). SKILL.md Step 1 rewritten: found-branch reads dembrandt frontmatter with legacy brand:/source:/extracted: files (incl. Application Patterns/tech_stack) still honoured + regenerate-overwrites note; not-found option A now generates in-session via MCP or CLI instead of ending the skill, with next-session MCP caveat, no-website hand-author path, and permission gate. README: brand pipeline section swapped to dembrandt with migration note for building-design-md users, TL;DR bullet, References entry, tree + file-count refresh
 - airtable-automations.md: Meta API now creates formula/rollup/lookup fields + tables (verified live 2026-08-31); still no automations/views/deletes/option-renames

package/README.md

@@ -109,7 +109,7 @@ npx -y dembrandt@latest install-browser   # one-time: fetches the Chromium dembr
 
 The skill auto-updates on every Claude Code session (SessionStart hook), and the dembrandt server checks the registry for the newest release on every launch (`@latest`), so both stay current. Skip the two dembrandt lines if you only want default Softr styling. Full operating guide (MCP flow, multi-page crawls, DESIGN.md anatomy, drift QA): `references/dembrandt.md`.
 
-Previously used the `building-design-md` companion skill? It's retired as of v2.4.0 and can be uninstalled — DESIGN.md files it produced remain fully supported (Step 1 reads their `brand:`/`source:` frontmatter and `Application Patterns`/`tech_stack` sections as before).
+The [`building-design-md`](https://github.com/leo-softr/design-md-extractor-skill) companion skill moved to the same engine: since its v2.0.0 it drives dembrandt too, and layers on what raw extraction can't provide — voice & copy register, resolved font names, logo assets, Softr app-pattern scaffolds, and the `custom-code-header.html` snippet. Run it when a project deserves the full brand foundation; this skill's Step 1 covers the quick raw DESIGN.md. Files from its v1.x (pre-dembrandt) remain fully supported.
 
 ---
 

package/SKILL.md

@@ -37,7 +37,7 @@ You generate complete, production-ready Softr Vibe Coding blocks as TypeScript R
 
      (Filling the placeholders: in a dembrandt-generated file, `<name>` is the frontmatter `name:` and the source URL sits inside `description:`; legacy files carry `brand:`/`source:`/`extracted:` instead. On request, a stale DESIGN.md can also be regenerated with dembrandt — that overwrites `./DESIGN.md`, and legacy scaffolding sections like `Application Patterns`/`tech_stack` are not reproduced.)
 
-     If (1), load every token section present: `colors`, `typography`, `spacing`, `rounded`, `components` from the YAML frontmatter, plus the body's Layout / Elevation & Depth / Shapes evidence and the Typography section's **Font URLs** (the frontmatter `fontFamily` can name a generic fallback like `ui-sans-serif` while the Font URLs reveal the real brand font — cross-check before picking the font). Sections without extracted evidence are simply absent — don't invent defaults for them. Legacy pre-dembrandt files may instead carry `elevation`, an `Application Patterns` scaffold, or a `tech_stack` block — honour those when present (the `tech_stack` block may pin specific shadcn variants or note bundler quirks). Full format anatomy: [references/dembrandt.md](references/dembrandt.md#designmd-anatomy-what-step-1-reads).
+     If (1), load every token section present: `colors`, `typography`, `spacing`, `rounded`, `components` from the YAML frontmatter, plus the body's Layout / Elevation & Depth / Shapes evidence and the Typography section's **Font URLs** (the frontmatter `fontFamily` can name a generic fallback like `ui-sans-serif` while the Font URLs reveal the real brand font — cross-check before picking the font). Sections without extracted evidence are simply absent — don't invent defaults for them. Files from the `building-design-md` companion (v2+) and legacy pre-dembrandt files may carry extra sections — a `fonts` block (the resolved brand fonts — prefer it over computed `fontFamily` values), an `Application Patterns` scaffold, a `tech_stack` block, or legacy `elevation` — honour those when present (the `tech_stack` block may pin specific shadcn variants or note bundler quirks). Full format anatomy: [references/dembrandt.md](references/dembrandt.md#designmd-anatomy-what-step-1-reads).
 
      If (2), proceed with the default Softr style (see Step 3).
 
@@ -50,7 +50,7 @@ You generate complete, production-ready Softr Vibe Coding blocks as TypeScript R
      > B. **Quick brand override** — paste the brand's primary color, accent color, and font name now. I'll apply just those.
      > C. **Use the default Softr style** — primary `#386AF5`, accent `#FCB500`, Inter font."
 
-     Wait for their pick. If (A) — extracting only a site the user owns or has permission to analyze (a contracted client's own site qualifies) — run the dembrandt pipeline from [references/dembrandt.md](references/dembrandt.md) in this same session — via the dembrandt MCP server when connected (`get_design_tokens` with `pages: 3`–`5` → poll `get_job_status` → `get_findings` sanity check → `generate_design_md`, then **write the returned markdown to `./DESIGN.md` in the project root**), or the CLI fallback when not (`npx -y dembrandt@latest <url> --design-md --crawl 5`, then copy `output/<domain>/DESIGN.md` to `./DESIGN.md`). If neither is available, give the user the install commands from that reference and pause until dembrandt is set up (an MCP server added now connects next session — the CLI is the same-session path). Show the user the extracted brand summary, then continue to Step 2 with those tokens. No public website to extract? Use (B), or offer to hand-author `./DESIGN.md` from whatever brand material the user has (a brand guide PDF, a style sheet) — Step 1 honours any DESIGN.md with token sections, not only dembrandt-generated ones. If (B) or (C), record their choice for Step 3 and continue.
+     Wait for their pick. If (A) — extracting only a site the user owns or has permission to analyze (a contracted client's own site qualifies) — run the dembrandt pipeline from [references/dembrandt.md](references/dembrandt.md) in this same session — via the dembrandt MCP server when connected (`get_design_tokens` with `pages: 3`–`5` → poll `get_job_status` → `get_findings` sanity check → `generate_design_md`, then **write the returned markdown to `./DESIGN.md` in the project root**), or the CLI fallback when not (`npx -y dembrandt@latest <url> --design-md --crawl 5`, then copy `output/<domain>/DESIGN.md` to `./DESIGN.md`). If neither is available, give the user the install commands from that reference and pause until dembrandt is set up (an MCP server added now connects next session — the CLI is the same-session path). Show the user the extracted brand summary, then continue to Step 2 with those tokens. (When the project deserves a fuller foundation — voice & copy register, logo assets, app-pattern scaffolds, the `custom-code-header.html` snippet — offer the `building-design-md` skill (v2+, same dembrandt engine plus those layers) instead of this quick raw generation.) No public website to extract? Use (B), or offer to hand-author `./DESIGN.md` from whatever brand material the user has (a brand guide PDF, a style sheet) — Step 1 honours any DESIGN.md with token sections, not only dembrandt-generated ones. If (B) or (C), record their choice for Step 3 and continue.
 
    Do not silently default to Softr's brand. The user must opt in to defaults explicitly.
 

package/package.json

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

@@ -78,7 +78,7 @@ Body sections in order: `# Design System` → Overview → Colors → Typography
 - **Font URLs** (in the Typography section): direct `.woff2` links to the site's real webfonts. The frontmatter `fontFamily` reports the *computed* value, which can be a generic fallback (`ui-sans-serif`) while the Font URLs reveal the actual brand font — cross-check before declaring the brand font, and use these URLs when authoring page-level `@font-face` CSS.
 - Motion tokens exist in dembrandt's JSON extraction but are **not** part of DESIGN.md `[official]` — don't expect an animation section.
 
-Legacy note: DESIGN.md files generated before this pipeline (the retired `building-design-md` skill) carry different frontmatter (`brand:`/`source:`/`extracted:`) and extra sections (`Application Patterns`, `tech_stack`). They remain valid brand sources — Step 1 honours whatever token sections are present rather than demanding the dembrandt shape.
+Companion-skill note: the `building-design-md` skill (v2+) drives this same dembrandt pipeline and layers more on top — voice & copy register, a resolved `fonts` block, logo `assets`, Softr `tech_stack`, and an Application Patterns scaffold — appended around an untouched dembrandt base, so its files read here natively. Files from its v1.x (pre-dembrandt) carry different frontmatter (`brand:`/`source:`/`extracted:`) and old-format sections; they remain valid brand sources — Step 1 honours whatever token sections are present rather than demanding the dembrandt shape.
 
 ## Authoring `custom-code-header.html` from DESIGN.md
 

package/references/softr-mcp.md

@@ -164,21 +164,26 @@ Known limits and behaviors (per official docs):
   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; the server has grown
-  substantially since — deletes added by 2026-08-31 — so this write surface is worth a re-test when
-  next touched live). To flip a LINKED_RECORD
+  field property; the call succeeds and changes nothing (verified 2026-08-26; the write surface was
+  re-touched live 2026-09-01 and the silent-no-op failure class held — see the SELECT-choices bullet
+  below). 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).
+- **`update_field` on a SELECT field silently drops added choices** — the call succeeds and echoes the
+  OLD choice set back, no error (verified live 2026-09-01; the second known silent no-op on this write
+  surface, joining the `allowMultipleEntries` finding above). New choices must be added in Studio —
+  or, when the field has `allowToAddNewChoice` enabled, the first record write with an unknown label
+  auto-creates the choice.
 - 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.
 
 ## Workflows
 
-Softr Workflows are automations built from trigger + action nodes, and the MCP can build, wire, test, and publish them — a **26-tool suite** (roster-verified 2026-08-31; `list_node_types` called live, the build/publish loop itself not yet exercised end to end):
+Softr Workflows are automations built from trigger + action nodes, and the MCP can build, wire, test, and publish them — a **26-tool suite** (roster-verified 2026-08-31; the full build → wire → test → publish loop **exercised end to end 2026-09-01** — 10 production workflows built live through MCP; see the build-loop findings below):
 
 | Group | Tools |
 |---|---|
@@ -197,9 +202,20 @@ Softr Workflows are automations built from trigger + action nodes, and the MCP c
 **Mechanics from the server's own instructions:**
 
 - Node inputs can embed **references to another node's runtime output**, a loop's current item, or named date/time tokens.
-- **Test-first is mandated:** every testable node needs a test run before its outputs become referenceable by downstream nodes. Each node carries a `testRunMode` — `REAL_ONLY`, `MOCK_ONLY`, or `MOCK_AND_REAL` — so some nodes can only be tested against real side effects while others mock.
+- **Test-first is mandated:** every testable node needs a test run before its outputs become referenceable by downstream nodes. Each node carries a `testRunMode` — `REAL_ONLY`, `MOCK_ONLY`, or `MOCK_AND_REAL` — so some nodes can only be tested against real side effects while others mock. See the test-safety rules under build-loop findings below before testing anything against a production workspace.
 - **Workflows are workspace-level, not part of an app**: `preview_app` / `publish_app` do not apply. Link a workflow as `https://studio.softr.io/workflow/{workflowId}`.
 
+**Build-loop findings (verified live 2026-09-01, first end-to-end production build — 10 workflows):**
+
+- **`create_workflow` instantiates an OLD version of the trigger node.** Immediately call `replace_trigger_node` with the **same trigger type** — the replacement lands at the current version with the current inputs. Example: `updateField` on `SOFTR_TABLES_RECORD_UPDATED` (fire only when a specific field changed) only exists at v1.2.0; the version `create_workflow` instantiates doesn't have it.
+- **FILTER node conditions are set via `update_node_inputs` with inputName `"condition"`** — the value is an `{operator, conditions: [...]}` object. The condition is stored on the FILTER node's **outgoing path**, the same way the Studio builder wires it.
+- **`LOOP_ACTION_GROUP`'s `loopVariables.items` must reference a plain array**, e.g. `$.records` — a `[*]` projection (e.g. `$.records[*].fields.X`) is rejected by the validator. Per-item references **inside** the loop use `{loopActionGroup.<id>:::loopVariables.items.fields.<fieldId>}` (use the bracket form for ids that start with a digit).
+- **`update_node_inputs` batches validate against the STORED node state**, not the batch-in-progress — an update that depends on another update in the same batch fails validation. Split dependent updates into sequential calls.
+- **Test-safety rules** (which `testRunMode` means what in practice):
+  - Record-**write** nodes (`SOFTR_TABLES_UPDATE_RECORD` etc.) are `REAL_ONLY` — **never test them against a production workspace**; the test performs the real write.
+  - `SOFTR_SEND_EMAIL` is `MOCK_AND_REAL` — **always pass `mode: "mock"`**.
+  - Triggers and `GET_RECORDS` are `REAL_ONLY` but read-only-safe; a record-updated / enters-view trigger test just samples an existing record.
+
 **Why this matters to block work:** Softr Workflows are now the Softr-native answer to the "block writes to its own table, backend cascades the rest" pattern — for **Softr Database backends** what [airtable-automations.md](airtable-automations.md) is for Airtable backends. See the cross-table alternatives in [../datasources/writing.md](../datasources/writing.md#cross-table-operations).
 
 ## Per-application MCP servers