softr-vibe-coding 2.1.2 → 2.3.0

package/references/softr-mcp.md

@@ -1,6 +1,8 @@
 # Softr MCP Server
 
-The official Softr MCP server (`https://mcp.softr.io/mcp`) gives an AI assistant (Claude Code, Claude Desktop, claude.ai, Cursor, ChatGPT, Mistral) direct access to a Softr **workspace**: databases, applications, vibe coding blocks, integrations (external data sources), and workflows. Everything the assistant does happens as the connected user, with their permissions, and shows up in Studio like any other change.
+The official Softr MCP server (`https://mcp.softr.io/mcp`) gives an AI assistant (Claude Code, Claude Desktop, claude.ai, Cursor, ChatGPT, Mistral) direct access to a Softr **workspace**: databases, applications, vibe coding blocks, integrations (external data sources), and workflows. On this workspace server, everything the assistant does happens as the connected user, with their permissions, and shows up in Studio like any other change.
+
+**There are now TWO server classes.** Besides the workspace server above, Softr ships **per-application MCP servers** — one server per published app, exposing that app's data (and only what the app's pages actually use) through the app's own permission model. Different tools, different schema doc, and (apparently) a different identity model. See [Per-application MCP servers](#per-application-mcp-servers). (Live-enumerated 2026-08-31; roster facts below marked "roster-verified" mean the tool exists — its behavior was not necessarily exercised.)
 
 **This file is a sibling concern to the [../datasources/](../datasources/) guides, which cover in-block data fetching (`useRecords` + `q.select()`).** The MCP runs at chat-build time, not inside the block. For Vibe Coding work it matters twice: it answers "what fields does this table have?" without any paste-ins, and it can create and deploy the block itself — no copy-paste into Studio.
 
@@ -12,9 +14,13 @@ The official Softr MCP server (`https://mcp.softr.io/mcp`) gives an AI assistant
 - [Connection and auth](#connection-and-auth)
 - [Permissions model](#permissions-model)
 - [Vibe coding block tools](#vibe-coding-block-tools)
+- [Adopting Studio-AI-generated code](#adopting-studio-ai-generated-code)
 - [Vibe coding gotchas (official)](#vibe-coding-gotchas-official)
+- [Application management tools](#application-management-tools)
 - [Browsing integrations (external data sources)](#browsing-integrations-external-data-sources)
 - [Softr Database tools](#softr-database-tools)
+- [Workflows](#workflows)
+- [Per-application MCP servers](#per-application-mcp-servers)
 - [Two delivery paths for this skill](#two-delivery-paths-for-this-skill)
 - [When the MCP is not installed](#when-the-mcp-is-not-installed)
 
@@ -22,11 +28,11 @@ The official Softr MCP server (`https://mcp.softr.io/mcp`) gives an AI assistant
 
 | Area | What the assistant can do | Official docs |
 |---|---|---|
-| Databases | Query, filter, aggregate; create/update records; build tables and fields | https://docs.softr.io/mcp/databases |
-| Applications | Read apps, pages, blocks, permissions; preview; publish | https://docs.softr.io/mcp/apps |
+| Databases | Query, filter, aggregate; create/update **and delete** records; build **and delete** tables, fields, databases | https://docs.softr.io/mcp/databases |
+| 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, test, and publish workflows | https://docs.softr.io/mcp/workflows |
+| 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 |
 
 `list_workspaces` is often the first call — it turns "my Sales workspace" into the workspace ID every other tool needs.
 
@@ -73,9 +79,22 @@ Before writing any block code through the MCP, call `get_vibe_coding_docs` — i
 | Settings / visibility | `update_vibe_coding_block_settings`, `set_vibe_coding_block_visibility`, `set_vibe_coding_block_action_visibility` |
 | Versions | `list_vibe_coding_block_versions`, `restore_vibe_coding_block_version`, `duplicate_vibe_coding_block_from_version` |
 | Data sources | `connect_vibe_coding_block_data_source`, `disconnect_vibe_coding_block_data_source`, `set_vibe_coding_block_data_source_sort`, `set_vibe_coding_block_data_source_record_filters` |
+| Any block | `get_block` (roster-verified 2026-08-31; presumed to read any block type, not just vibe blocks — unconfirmed by a live call on a native block) |
 
 Editable settings via MCP are the same fields as the block's **Content → Settings** panel; sort and record filters are the same as the **Source** tab. Duplicating from a version is the safe way to try an alternative — the original keeps working while you experiment on the copy.
 
+## Adopting Studio-AI-generated code
+
+When you pull a Studio-AI-generated block via `get_vibe_coding_block_code` to adopt into a project repo as source of truth: its output renders fine but ships with predictable defects. **Functional patterns in Studio output are platform-support evidence** (it surfaces undocumented capabilities before the docs do — see SKILL.md's "Platform truth sources"); **its code hygiene is not a pattern to imitate.** Cleanup pass before committing:
+
+- **Run a formatter** — Studio output ships inconsistent indentation (observed: statements at column 0 inside a 4-space-indented component).
+- **Hoist and consolidate brand hexes** into module-scope constants; flag near-duplicate hexes as probable unintended drift (observed: `#AE5E3D` vs `#B4603D` for one terracotta in a single block).
+- **Fix React keys on settings-array loops** — Studio emits `key={item.label}`; use `key={index}` (see [anti-patterns.md](anti-patterns.md#editable-settings)).
+- **Add the guards Studio omits** — conditional render for empty media settings, `whitespace-pre-line` on long-text settings, mobile nav for block-owned headers, `aria-hidden` on decorative glyphs.
+- **Rewrite absolute self-domain URLs relative** (`https://<app>.softr.app/#x` → `/#x`) — observed as a configured setting value on a Studio-generated hero, 2026-08-31.
+
+This is distinct from SKILL.md's no-churn rule: cleaning up a block you're ADOPTING into the repo is required; modernizing a deployed working block's syntax is still churn — don't do that.
+
 ## Vibe coding gotchas (official)
 
 From the official MCP docs — these hold for MCP-driven and Studio-driven edits alike:
@@ -86,6 +105,24 @@ From the official MCP docs — these hold for MCP-driven and Studio-driven edits
 - **Changing the code resets action permissions.** Any code change rebuilds the block's record actions at default visibility — restrictions to user groups must be re-applied. (This is Hard Constraint 21 in SKILL.md, now officially documented: tighten Action permissions only after the LAST redeploy.)
 - **A block with an unconnected data source saves without complaint**, then errors when the page loads. If a freshly created block looks broken but the code seems right, check its data source connection first.
 
+## Application management tools
+
+The Applications area goes well beyond reads (all roster-verified 2026-08-31; behavior not individually exercised):
+
+| Group | Tools |
+|---|---|
+| Apps | `list_applications`, `get_application`, `create_application` (create a whole app via MCP), `update_application_data_source` (point/swap the app's data source), `set_application_login` |
+| App users | `add_application_user`, `remove_application_user`, `list_user_groups` |
+| Pages / blocks / permissions | `list_pages`, `get_page`, `get_page_permissions`, `get_access_control`, `get_block` |
+| Publish / preview | `preview_app`, `publish_app` |
+| Workspace | `list_workspaces`, `get_workspace_integrations` (distinct from the [integrations drill-down](#browsing-integrations-external-data-sources) below) |
+
+Combined with the database tools (`create_database` / `create_table` / `create_field`) and `create_vibe_coding_block` + `publish_app`, the tool set for scaffolding a full app end to end now exists. (Existence-verified only — that pipeline hasn't been run live; treat the first full scaffold as an experiment, not a routine.)
+
+**Etiquette from the server's own instructions:** after changing a block, link the page as `https://studio.softr.io/applications/{applicationId}/pages/{pageId}`; offer `preview_app` or `publish_app`, but **only publish when the user asks**.
+
+> **preview_app links are auth tokens.** Per the server's own instructions, a preview link **signs its opener in as the user who requested it** and lasts about a day. Give it only to that user, and mint a fresh one with another `preview_app` call rather than re-sending an old link. Never paste a preview link into a shared channel.
+
 ## Browsing integrations (external data sources)
 
 An integration is an external data source connected once per workspace (the builder says "integrations", the tools say "data sources" — same thing). Five read-only tools drill down from workspace to fields; each level needs an ID from the level above:
@@ -111,19 +148,25 @@ Getting this wrong **fails silently** — the code compiles, saves, and looks ri
 
 ## Softr Database tools
 
-For Softr's native databases the MCP goes far beyond browsing: `get_schema` (authoritative field-type + filter-operator reference — call it before building tables or filters), database/table/field CRUD, `list_views`, record reads (`list_records`, `search_records`, `get_record`), record writes (`create_record`, `create_records` batch, `update_record`), and `aggregate_data` for grouped summaries.
+For Softr's native databases the MCP goes far beyond browsing: `get_schema` (authoritative field-type + filter-operator reference — call it before creating/updating tables, fields, or filters; the server's own instructions say "do not guess field types, options, or operators"), database/table/field CRUD **including deletes** (`delete_database`, `delete_table`, `delete_field`), `list_views`, record reads (`list_records`, `search_records`, `get_record`), record writes (`create_record`, `create_records` batch, `update_record`, `delete_record`, `delete_records` batch), and `aggregate_data` for grouped summaries.
+
+**Call economy (from the server's own instructions):** `get_table` returns a table's metadata AND all its field definitions in one call; `list_fields` returns the fields alone. Call ONE of them once per table and reuse the result — never both. (Sensible extension: re-fetch only after you changed the table's fields yourself.)
+
+**get_schema, live-confirmed 2026-08-31:** `readOnlyFieldTypes` = AUTONUMBER, COUNT, CREATED_AT, CREATED_BY, FORMULA, LOOKUP, RECORD_ID, ROLLUP, UPDATED_AT, UPDATED_BY (matches this file's long-standing claim verbatim). 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). 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:** the workspace server's `get_schema` 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, BUTTON), and even the operator NAMES differ between server kinds (workspace `GREATER_THAN` / `DOES_NOT_CONTAIN` vs per-app `GT` / `DOES_NOT_CONTAINS`) — so filter payloads are not portable between them. Always call `get_schema` on the server you are actually using.
 
 Known limits and behaviors (per official docs):
 
 - Record field keys are **field IDs**, not labels — `list_fields` maps between them.
 - Computed fields (formula, lookup, rollup, count) and system fields (created/updated time and by, autonumber, record ID) are read-only; a field's type cannot be changed after creation.
-- **Nothing can be deleted through the MCP yet** — no record/table/field/database delete tools (docs say deletion is coming). Deletions happen in the builder.
+- **Deletion now exists** (supersedes the earlier "nothing can be deleted through the MCP yet" finding): `delete_record`, `delete_records` (batch), `delete_field`, `delete_table`, and `delete_database` are all in the roster (verified 2026-08-31), and per-app servers add `delete_record` + `batch_delete_records`. Roster-verified only — no destructive call was made, so which Databases permission level gates them and how cascades behave (e.g. deleting a table with linked records) are untested. Treat every delete as irreversible; no soft-delete is documented.
 - **Attachment writes take a URL and copy the file.** `create_record` / `update_record` accept
   `{ 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 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 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
@@ -133,12 +176,56 @@ Known limits and behaviors (per official docs):
 
 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):
+
+| Group | Tools |
+|---|---|
+| Workflow lifecycle | `create_workflow`, `get_workflow`, `get_workflow_url`, `list_workflows`, `rename_workflow`, `update_workflow_configuration`, `publish_workflow`, `unpublish_workflow` |
+| Node management | `add_node`, `add_branch_node`, `create_branch`, `delete_node`, `duplicate_node`, `rename_node`, `reorder_node`, `reorder_multiple_nodes`, `replace_node`, `replace_trigger_node`, `update_node_inputs`, `update_node_note`, `update_node_continue_on_error` |
+| Discovery / testing | `list_node_types`, `get_node_specifications`, `get_dynamic_input_options`, `test_node`, `get_node_output` |
+
+**The node catalog is huge** — live-enumerated 2026-08-31: **418 node types (58 triggers + 360 actions) across 56 applications.** The parts that matter most for this skill:
+
+- **Softr-native triggers:** one-time + recurring schedules, `WEBHOOK` (inbound webhook), `SOFTR_EMAIL_RECEIVED` (inbound email! — delivery mechanism not captured), Softr Databases record events (added / updated / deleted / meets-conditions / enters-view / "run custom workflow on selected records"), Softr Apps events (Add Record form submitted, Edit Record form submitted, form submitted, user added, comment added) — and **"Run Custom Workflow action triggered"**, which by its name is the receiving end of the vibe block's `TRIGGER_CUSTOM_WORKFLOW` NavigationAction (name-based inference; the pairing has not been wired live). See SKILL.md's NavigationAction action-types list.
+- **Softr-native actions:** `BRANCH`, `FILTER`, `WAIT`, `LOOP_ACTION_GROUP` (run each list item through the same steps), `SOFTR_SEND_EMAIL`, `CALL_API` (REST), `WEBPAGE_SCRAPPER`, `PDF_TO_TEXT`, `COMPRESS_FILES` (zip + download link), `TRANSFORM_DATA`, `RESPONDED_TO_WEBHOOK` (custom HTTP response to the webhook caller); Softr DB record CRUD incl. bulk update/delete and find; Softr Apps user management (find / create / delete / deactivate / activate / invite user, send push notification).
+- **`CUSTOM_CODE`:** runs custom **JavaScript or Python** inside a workflow.
+- **AI actions:** Softr AI, OpenAI, Anthropic, Gemini, and Mistral each ship Write / Summarize / Categorize / Custom-prompt nodes; OpenAI adds gpt-image-2 image generation. Pinecone, Firecrawl, Replicate, and Linkup nodes exist too.
+- **Integration apps (top of 56):** Stripe (36 nodes), QuickBooks (24), ActiveCampaign (23), SharePoint (22), Asana (18), Gmail/Attio/Brevo/Resend (12 each), ClickUp/Zendesk (10), Airtable/Notion/Cal.com/HubSpot/Xero/DocuSign/Apollo (9 each), Sheets/Excel (8), monday/SQL/Jira (7), Slack/Telegram (6), plus Salesforce, Coda, Calendly, Twilio, Zoom, Linear, Trello, form tools (Typeform/Tally/Jotform/Fillout), and more.
+
+**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.
+- **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}`.
+
+**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
+
+A separate product class from the workspace server (live-observed 2026-08-31 on two connected app servers): **one MCP server per published Softr app**, exposing that app's data to MCP clients. How these servers are provisioned/connected was not captured — check the app's settings in Studio or the official docs when setting one up.
+
+**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`.
+
+**Live-observed semantics:**
+
+- **The table catalog is derived from the app itself.** `list_tables` returns only tables the app's pages actually use, each with an `operations` array (`read` / `create` / `update` / `delete`) mirroring the app's configured actions — read-only tables genuinely appear read-only. Each table also carries `context.pages` (which app pages use it) and `operationLabels` (the app's actual button labels: "Add record", "Edit", "Delete").
+- An app may connect **multiple distinct data sources**; always call `list_tables` first for the full catalog before concluding data doesn't exist.
+- `get_current_user` exists, and combined with the action-scoped catalog this implies the server operates in an **app-user context** rather than the builder identity the workspace server uses (inferred — not confirmed by a live `get_current_user` call).
+- **Field keys in records are field IDs, not labels** — same rule as everywhere in Softr DB land; on these servers the mapping tool is `describe_table` (not `list_fields`).
+- Its `get_schema` returns a **richer field-type catalog than the workspace server's**: creatable types add ADDRESS, PROGRESS, TIME, DATE_RANGE, BUTTON; SELECT documents `choices: array<{id, label, color}>` + `allowToAddNewChoice`; LONG_TEXT documents TEXT|HTML|MARKDOWN formats; ATTACHMENT documents `fileType` + `showAs PREVIEW|BADGE`; PERCENT documents `showAs NUMBER|PROGRESS_BAR|PROGRESS_RING`. Read-only list matches the workspace server.
+- **Documented conventions** (unlike the workspace server's silent caps): pagination is `page` (1-based) + `pageSize` (max 100) with `total` and `hasMore` in the response; timestamps are UTC `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'` for reads AND writes; errors return `{code, error, suggestion}` with machine-readable codes (NOT_FOUND, VALIDATION_ERROR, PERMISSION_DENIED, INVALID_REQUEST, INTERNAL_ERROR). Do not assume the workspace server's limits (200-record silent read cap, etc.) transfer here, or vice versa.
+- Filter operators use the per-app naming (`GT`/`LT`/`GTE`/`LTE`, `DOES_NOT_CONTAINS`, `IS_WITHIN` relative dates, `IS_ONE_OF`/`IS_NONE_OF`, `HAS_ALL_OF`/`HAS_NONE_OF` (the latter flagged legacy in the schema), `INLINE_CONTAINS`) with per-operator supported-type lists — see the schema-drift caution in [Softr Database tools](#softr-database-tools).
+
+**What they are NOT:** a delivery path for blocks. Per-app servers serve a published app's **data** at runtime; they cannot create, edit, or deploy vibe coding blocks — that stays on the workspace server.
+
 ## Two delivery paths for this skill
 
 When generating a block, pick the delivery path by what's connected:
 
-1. **MCP connected with Applications & Forms full access** — write the `.tsx` file locally first (it remains the source of truth and the reviewable artifact), then offer to deploy it directly: `create_vibe_coding_block` (or `update_vibe_coding_block_code` for edits), then `connect_vibe_coding_block_data_source` to wire up the data. Remember the action-permissions reset gotcha after every code push.
-2. **No MCP (or read-only access)** — classic path: write the `.tsx` file and have the user paste it into Studio's Vibe Coding editor, then connect the data source in the **Source** tab themselves.
+1. **WORKSPACE MCP server connected with Applications & Forms full access** (a per-application server does not count — it cannot create or deploy blocks; see the section above) — write the `.tsx` file locally first (it remains the source of truth and the reviewable artifact), then offer to deploy it directly: `create_vibe_coding_block` (or `update_vibe_coding_block_code` for edits), then `connect_vibe_coding_block_data_source` to wire up the data. Remember the action-permissions reset gotcha after every code push. After deploying, link the Studio page (`https://studio.softr.io/applications/{applicationId}/pages/{pageId}`) and offer `preview_app` / `publish_app` — publish only when asked, and mind the [preview-link auth warning](#application-management-tools).
+2. **No workspace MCP (or read-only access)** — classic path: write the `.tsx` file and have the user paste it into Studio's Vibe Coding editor, then connect the data source in the **Source** tab themselves.
 
 Either way, never deliver code inline in chat (JSX character corruption — see SKILL.md workflow step 5).
 

package/references/static-blocks.md

@@ -0,0 +1,97 @@
+# Static Marketing Blocks — Heroes, Landing Sections, and the Editorial Lane
+
+A **static block** is a Vibe Coding block with **zero datasources**: all content comes from editable settings, nothing loads, nothing mutates. Officially blessed — Softr's user guide lists "a static layout like a page header, pricing table, or content section" as a first-class use of the Vibe Coding block. Typical members: hero sections, landing-page headers, pricing tables, testimonial bands, logo walls, FAQ sections, footers, content/feature sections.
+
+This archetype inverts most of the skill's data-block defaults, so read this file INSTEAD of the datasource guides when the requested block is static marketing content. (Verified against a Studio-AI-generated hero rendering live in Studio, 2026-08-31.)
+
+## Contents
+
+- [Workflow deltas](#workflow-deltas)
+- [Editorial baseline (replaces the Premium Visual Baseline)](#editorial-baseline-replaces-the-premium-visual-baseline)
+- [Full-bleed layout license](#full-bleed-layout-license)
+- [Full-viewport hero sizing](#full-viewport-hero-sizing)
+- [Block-owned landing-page header](#block-owned-landing-page-header)
+- [Section anchors on landing pages](#section-anchors-on-landing-pages)
+- [Harvesting Studio-AI marketing blocks](#harvesting-studio-ai-marketing-blocks)
+
+## Workflow deltas
+
+When the block is static marketing content:
+
+- **SKIP data-source interrogation entirely** — no data source type question, no field IDs, no datasource guide loading. Step 1 (DESIGN.md brand detection) still runs unchanged.
+- **Settings-first design is the default** — every user-visible string, image, and link becomes an editable setting; see the granularity doctrine in [editable-settings.md](editable-settings.md#granularity-doctrine-settings-first-static-blocks). This is what makes the block a reusable, client-editable template instead of frozen copy.
+- **Self-validation deltas** — these Step 6 checklist items DON'T apply: loading/error/empty states (nothing loads), `getFieldValue()` wrapping (no records), mutation `enabled` gating, `fetchNextPage` rules, container/content wrappers (see full-bleed below). These DO apply, plus extras: hooks before conditional returns, module-scope sub-components, no hardcoded user-visible copy, media settings gated for the empty-src state, array rows keyed by index, `// BLOCK PLACEMENT:` comment present.
+- **Ask-AI buttons still need a data source.** The one place a "static" block touches data: an `OPEN_CHAT` NavigationAction pulls AI context from the block that triggered it — with no data source connected, `chat/prepare` returns HTTP 500. Connect the block to whatever table the AI should read, even though the block renders none of it. See [anti-patterns.md](anti-patterns.md#layout--styling).
+
+## Editorial baseline (replaces the Premium Visual Baseline)
+
+SKILL.md's Premium Visual Baseline (gradient wrapper, icon-in-rounded-square header, card grids, skeletons, empty states) is an **app-UI** baseline — applying it to a hero produces a dashboard cosplaying as a landing page. For static marketing blocks, the baseline is editorial instead:
+
+1. **Typographic hierarchy carries the design** — display-size headings, an eyebrow/tagline, generous line-height on body copy. Use the marketing display-type lane in ui-ux-guidelines.md §6.
+2. **Brand-exact values over theme tokens** — arbitrary Tailwind values (`bg-[#FAF5EC]`, `text-[17px]`, `rounded-[6px]`) and inline-style brand hexes are the correct tool here (see §7's editorial lane in ui-ux-guidelines.md). Hoist repeated hexes to module-scope constants — see [anti-patterns.md](anti-patterns.md#layout--styling).
+3. **Decorative layers, used deliberately** — background blobs/shapes, edge-fade image masks, art-directed responsive images. Recipes in [common-patterns.md](common-patterns.md).
+4. **No loading/empty/error scaffolding** — there is nothing to load. The only "empty" state to handle is an un-uploaded media setting ([editable-settings.md](editable-settings.md#media-hooks-useimagesetting-and-usevideosetting)).
+5. **Restraint still applies** — ui-ux-guidelines.md's AI-slop bans (purple-to-blue gradients, glassmorphism everywhere, gradient text) bind in this lane too. Editorial ≠ decorated.
+
+## Full-bleed layout license
+
+**`container`/`content` wrappers are optional platform behavior, not platform-enforced.** Per the official developer guide: "By default, block occupies full width of the page but special classes - `container` and `content` are **available** to constrain the width [of content to match app's max width settings]" (emphasis added). The wrappers remain the strong default for app/content blocks that sit next to native blocks (width consistency — that's their whole purpose). Static marketing blocks legitimately skip them so backgrounds, images, and decorative shapes run edge-to-edge.
+
+When you go full-bleed:
+
+- **Own your horizontal gutters** — the responsive padding ramp `px-6 md:px-12 lg:px-16` on the content container is the Studio-verified shape.
+- **Own your inner max-widths** — constrain the copy column yourself (`lg:max-w-[46%]`, `max-w-[430px]` on body text).
+- **`overflow-hidden` on the block root** if decorative shapes offset off-canvas (prevents horizontal scroll).
+- **Record the choice** in the placement comment so future edits and reviews know it's deliberate:
+
+  ```tsx
+  // BLOCK PLACEMENT: full-bleed hero, native header hidden, owns all spacing
+  // Spacing: no container/content; gutters px-6 md:px-12 lg:px-16
+  ```
+
+The standard spacing table (`py-3 px-8` wrappers) does not apply — a full-bleed block owns all of its spacing.
+
+## Full-viewport hero sizing
+
+The Studio-verified responsive shape:
+
+```tsx
+<div className="relative min-h-screen lg:min-h-0 lg:h-screen lg:flex lg:flex-col ...">
+  <main className="lg:flex-1 lg:flex lg:items-center ...">
+```
+
+Natural height on mobile, locked viewport height on desktop, content vertically centered in the remaining space. Rules and gotchas:
+
+- **vh/`h-screen` resolve against the real viewport** (blocks are shadow DOM in the main document — see [Block-owned landing-page header](#block-owned-landing-page-header)). So `h-screen` fills the window only when the native header is hidden on that page; with a native header above, a 100vh block overflows by the header height. Use `min-h-[calc(100vh-<headerHeight>px)]` when native chrome stays.
+- **Hard `h-screen` + `overflow-hidden` + centered flex CLIPS settings-grown content — unrecoverably.** Every string in a settings-first hero is builder-lengthenable; on a short laptop viewport, two extra sentences in the description push the CTA row past the clip, and centered-flex overflow clips top AND bottom, so no scrolling reaches it. Prefer `lg:min-h-screen` (grow-with-content) unless the locked-viewport look is explicitly wanted; if locking, flag the tradeoff to the user and keep the copy settings short.
+- **Mobile URL-bar resize**: consider `min-h-[100svh]`/`dvh` variants if the mobile jump matters; the `min-h-screen` mobile default is the safe baseline.
+
+## Block-owned landing-page header
+
+The scope rule stays true: Softr's **native** chrome (top bar, auth-aware account menu, user-group-gated nav) cannot be built or replaced as a block — restyling it is global Custom Code territory ([native-chrome-styling.md](native-chrome-styling.md)). But on a landing page where the native header is **hidden in Studio**, a hero block CAN render its own `<header>` — Softr's own Studio AI emits exactly this, and the official user guide lists "a page header" as a supported static layout. Mechanics (rendered live in Studio 2026-08-31; the positioning behavior is standard shadow-DOM/CSS — confirm in the published app):
+
+- **`position: fixed` works from inside the block** and anchors to the viewport — blocks render in a shadow root in the MAIN document (not an iframe), and shadow roots don't create a containing block. The header escapes the block's visual bounds and overlays every other block on the page.
+- **Window scroll listeners work normally** — `window.scrollY` reflects the real page. The scroll-condensing treatment (translucent bg + backdrop-blur + border after ~24px) is in [common-patterns.md](common-patterns.md#scroll-condensing-fixed-header-landing-page-hero).
+
+The caveat set — state these in any block that ships its own header:
+
+1. **Per-page only.** The header exists solely on pages containing this block. Every page of a multi-page site needs either this block or the native header, or navigation disappears.
+2. **No auth-aware nav logic.** You forfeit Softr's account menu and user-group-gated items — nav items are plain `<NavigationAction>`s. Fine for public landing pages; wrong for logged-in app pages. For the login CTA, use the auth-aware swap (`useCurrentUser()` → "Sign in" vs "Dashboard") from [common-patterns.md](common-patterns.md#auth-aware-header-cta).
+3. **Don't ship both headers on one page.** The z-index outcome against a visible native `#topbar-root` (sticky, main document) is untested — hide the native header on this page, or don't use the pattern.
+4. **Keep transforms/filters off the header's ancestors.** `position: fixed` anchors to the viewport ONLY while no ancestor establishes a containing block — a `transform`, `filter`, `perspective`, or `will-change` on the block root (e.g. an entrance animation) silently converts the "fixed" header to absolute and lets `overflow-hidden` clip it. Leaf-element transforms (`hover:-translate-y-[1px]` on buttons) are fine. Verify in the **published app**, not just the Studio canvas.
+5. **Mobile nav is mandatory.** `hidden md:flex` on the nav with no fallback means nav items simply don't exist on phones (Studio AI ships exactly this bug). Pair the pattern with a shadcn `Sheet`-based mobile menu (hamburger → drawer listing the same `navItems` array) — the component is on the platform roster.
+6. **Landmark hygiene.** Shadow DOM does NOT hide landmarks from assistive tech, and Softr's native chrome uses semantic elements. On a page with native chrome visible, a block's own `<header>`/`<main>` creates duplicate banner/main landmarks — use plain `<div>`s there. Reserve `<header>`/`<main>` for pages where the native chrome is hidden and the block genuinely IS the page chrome.
+
+The wider decision (restyle native vs replace globally vs block-owned) is laid out in [native-chrome-styling.md](native-chrome-styling.md#restyle-vs-replace-vs-block-owned-header).
+
+## Section anchors on landing pages
+
+Heroes pair with same-page sections via hash links (nav "Capabilities" → `#capabilities` further down).
+
+- **Write anchor destinations RELATIVE**, per Hard Constraint 20: `/#capabilities` or `/page#section`. A Studio-generated hero shipped its CTA configured as the absolute self-domain form (`https://<app>.softr.app/#capabilities`, observed in the Settings pane 2026-08-31) — rewrite that form; hardcoded domains break on custom-domain publish and between staging/production.
+- **A URL fragment cannot target an element inside a Vibe block's shadow root** — fragment lookup stops at the shadow boundary (same family as the documented `getElementById` anti-pattern). Anchors must target something in the main document: the block/section host. Softr has a native anchor-link mechanism targeting blocks — **verify live which fragment a Vibe Coding block answers to** before promising exact syntax to a user.
+- **In-block scrolling** (scroll to a section inside the same block) uses refs + `scrollIntoView` with the `setTimeout(fn, 0)` rule (Hard Constraint 17), not fragments.
+
+## Harvesting Studio-AI marketing blocks
+
+Marketing blocks are where you'll most often mine Studio-AI output for platform truth (it surfaced `useLongTextSetting` and the `navigation` array-schema type before the official docs did). Mine capabilities, never copy verbatim — the standard defects to fix on adoption are listed in SKILL.md's "Platform truth sources" note and [softr-mcp.md](softr-mcp.md#adopting-studio-ai-generated-code) (React keys, hex drift, formatting, missing mobile nav, unconditional media renders).

package/ui-ux-guidelines.md

@@ -192,6 +192,17 @@ Aim for at least **1.25x ratio** between adjacent scale steps. Sizes only 1-2px
 - Use `text-foreground`, not pure black. The theme token is calibrated for comfortable contrast.
 - **Use tabular numbers** in data tables for column alignment: add `style={{ fontVariantNumeric: "tabular-nums" }}` to numeric cells.
 
+### Marketing / editorial display type (heroes, landing blocks)
+
+The scale above is for **app UI** (dashboards, forms, lists). Static marketing blocks get a sanctioned exception lane (patterns verified from rendering Studio-AI hero output, 2026-08-31 — see [references/static-blocks.md](references/static-blocks.md)):
+
+- **Display headings 40–60px**, stepped per breakpoint with arbitrary px classes — `text-[40px] md:text-[56px] lg:text-[54px] xl:text-[60px]` — px precision because the Tailwind scale jumps too coarsely up there.
+- **Display line-height 1.05–1.1** for multi-line display headings (`leading-[1.08]`); the leading-snug rule above is for app-scale headings.
+- **Slight negative tracking on large display type**: `tracking-[-0.015em]`.
+- **Eyebrow/tagline pattern**: 13–14px, uppercase, `tracking-[0.15em]`–`tracking-[0.2em]`, `font-medium`, in an accent color, above the heading. (An eyebrow IS a "short label" — the all-caps rule below permits it.)
+- **Wordmark/logotype text**: `font-light`/`font-normal` + wide tracking (`tracking-[0.16em]`) for luxury brands.
+- Body copy in this lane still follows the body rules (16–19px, `leading-[1.6]`-ish, max-width constrained).
+
 ### Typography Anti-Patterns:
 - **DO NOT** use monospace typography as lazy shorthand for "technical/developer" vibes.
 - **DO NOT** place large rounded icons above every heading — they rarely add value and look templated.
@@ -220,7 +231,7 @@ All spacing uses **multiples of 4px**. The critical step that pure 8pt systems m
 - **Vary spacing for hierarchy.** A heading with extra space above reads as more important. Uniform padding everywhere feels monotonous.
 - **Internal spacing <= external spacing:** Padding *inside* a component must be smaller than the margin *between* components.
 - **Button height:** 40px (`h-10`) or 48px (`h-12`) — touch-friendly.
-- **Never use arbitrary values** like `p-[13px]`. Always use the Tailwind scale.
+- **Stick to the Tailwind scale for spacing in app-UI blocks** — avoid arbitrary spacing values like `p-[13px]` there; scale steps keep rhythm consistent. This is a design-consistency preference, NOT a platform limit: the platform's Tailwind build is JIT and the full arbitrary-value syntax compiles, including opacity-modified arbitrary hex (`bg-[#FAF5EC]/85`), negatives (`-top-[22%]`), arbitrary object-position/z/vw (verified from rendering Studio-AI output, 2026-08-31). In the **editorial/brand-faithful lane** (marketing heroes, luxury type, brand-exact radii — see [references/static-blocks.md](references/static-blocks.md)), px-precise arbitrary values are the correct tool. Elsewhere in this file, `min-h-[44px]` touch targets already use them.
 - **Generous whitespace** reduces cognitive load — it is not wasted space.
 
 ### Depth and Elevation:
@@ -306,7 +317,7 @@ Vestibular disorders affect ~35% of adults over 40. Always respect `prefers-redu
 | State | Purpose | Implementation |
 |---|---|---|
 | **Default** | Ready to use | Standard `Button` component |
-| **Hover** | Cursor over it | Handled by shadcn `Button` |
+| **Hover** | Cursor over it | Handled by shadcn `Button` — EXCEPT when an inline `style={{ backgroundColor }}` overrides the variant: inline style beats every `hover:bg-*` class, so use `hover:opacity-90` / transform instead (see SKILL.md's brand-hex Button recipe) |
 | **Focus** | Keyboard-selected | `focus-visible:ring-2` — never remove |
 | **Active** | Being pressed | Pressed in, darker |
 | **Loading** | Action in progress | Replace label with `<Spinner />` + disable |
@@ -535,6 +546,8 @@ Avoid the "hero metric layout template" — big number, small label, supporting
 ### Keyboard and screen reader:
 - All interactive elements reachable by keyboard (Tab, Enter, Space, Escape).
 - `aria-label` on all icon-only buttons.
+- **`aria-hidden="true"` on decorative glyph characters** used as separators or ornaments (●, •, |, →, ✦) — screen readers otherwise announce them literally ("black circle"). Purely decorative empty divs need nothing; decorative `<img>` elements need `alt=""`.
+- **Landmark hygiene when a block ships page chrome**: shadow DOM does NOT hide landmarks from assistive tech, and Softr's native chrome uses semantic elements — so a block's own `<header>`/`<main>` on a page with native chrome creates duplicate banner/main landmarks. Use plain `<div>`s there; reserve `<header>`/`<main>` for pages where the native chrome is hidden.
 - Semantic HTML: `<button>` for actions, `<a>` for navigation, `<input>` for data.
 - **Focus rings:** Never `outline: none` without replacement. Always keep `focus-visible:ring-2`. Focus ring must be 2-3px thick, high contrast, offset from the element.
 - Tables: proper `<thead>`, `<tbody>`, `<th scope="col">`.
@@ -551,6 +564,9 @@ Avoid the "hero metric layout template" — big number, small label, supporting
 - Form fields: `w-full` on mobile.
 - Navigation: collapse to hamburger or bottom nav on small screens.
 
+### Art-directed responsive images:
+A settings hook returns a plain value, so one `useImageSetting` may safely feed **two sibling `<img>` renders** with opposite visibility classes — desktop: absolute-positioned, masked, cropped via arbitrary `object-[x%_y%]`; mobile: in-flow full-bleed (`hidden lg:block` / `lg:hidden`, same mechanism as the table→cards swap in §18). The builder still edits ONE image in the Settings pane. To bleed the mobile render edge-to-edge against the wrapper's own horizontal padding, use matching negative margins (`-mx-6` against `px-6`, `md:-mx-12` against `md:px-12`).
+
 ### Breakpoint strategy:
 ```
 Mobile first: default -> sm (640px) -> md (768px) -> lg (1024px) -> xl (1280px)