@agent-native/core 0.176.1 → 0.176.2-nightly-20260831184159

package/docs/content/template-forms-agent.mdx

@@ -0,0 +1,65 @@
+---
+title: "Forms: Talk to the Agent"
+description: "What the agent sees when you're in Forms, and prompts organized by task."
+---
+
+# Talk to the Agent
+
+Everything in Forms is available to the agent through the same actions the UI uses, so anything you can click, you can also ask for in plain English. This page covers how the agent sees your screen and useful prompts by task. See [Forms](/docs/template-forms) for the overview.
+
+## How the agent sees your screen
+
+The agent always knows which form or view you have open, down to the browser tab. If you have one form open in one tab and the responses list open in another, the agent keeps them separate. That's why you can ask "add a required NPS question to this form" or "how many responses does this have" without naming the form. The agent already knows which one you mean. When you're looking at a form's responses, the agent can also see a preview of those responses, based on what you're allowed to see.
+
+## Useful prompts by task
+
+Every prompt below becomes a real action against your actual form, the same one the UI reads and writes. Here's one worked example.
+
+<Comparison>
+
+### :blue: You ask
+
+"Create a beta signup form with role, team size, and priority use case."
+
+### :green: What happens
+
+This creates something new. The agent builds the form with those fields already in place, and it shows up in your Forms list right away, ready to fine-tune or publish. Nothing needs a page refresh. The new form is just there.
+
+</Comparison>
+
+<Cards columns={2}>
+
+### Build
+
+- **"Create a beta signup form with role, team size, and priority use case."** The new form appears in your Forms list right away, ready to fine-tune.
+- **"Add a required NPS question and a free-text follow-up."** The fields show up on the form immediately.
+- **"Make this form shorter without losing the fields we need for routing."** The agent trims the form while keeping the fields your destinations depend on.
+
+### Publish and protect
+
+- **"Publish this and give me the link."** The form goes live and you get its public URL right away.
+- **"Create an anonymous customer feedback form and give me the public link."** The form is published anonymous from the start, so no submitter information is ever captured.
+- **"Only allow this form to be submitted from https://example.com."** The form starts rejecting submissions from anywhere else. This is only available by asking the agent today. There's no toggle for it in the builder.
+
+### Responses and insights
+
+- "How many responses does the beta signup form have?"
+- "Who submitted today?"
+- "Summarize this week's submissions and group them by customer segment."
+- "Chart submissions by day."
+- "How are submissions trending across all my forms this month?"
+- "Export this to CSV."
+
+### Routing
+
+- **"Post every new response to the product Slack channel."** New responses start showing up in Slack the moment they arrive, once a destination is connected.
+- "What's the setup for my beta signup form?"
+
+</Cards>
+
+## What's next
+
+- [**Forms**](/docs/template-forms) — the overview and what it replaces
+- [**Features**](/docs/template-forms-features) — every feature area, with setup steps for each
+- [**Forms in a Multi-App Workspace**](/docs/template-forms-integrations) — delegation and the public submit endpoint other apps use
+- [**Developer Guide**](/docs/template-forms-developers) — every action and the data model behind these features

package/docs/content/template-forms-developers.mdx

@@ -1,35 +1,148 @@
 ---
-title: "Forms — data model and actions"
-description: "The Forms template's SQL schema, its full action reference, and how to extend it with new field types or capabilities."
+title: "Forms: Developer Guide"
+description: "Quick start, the full action reference, data model, routes, and how to extend the Forms template."
 ---
 
-# Forms — data model and actions
+# Developer Guide
 
-This page is for developers customizing or extending the Forms template. It covers the SQL schema, every action the agent and UI call, and how to add new capabilities. For what the app does day to day, see [Forms](/docs/template-forms); for field types, publishing, and public-form protections, see [Building and publishing a form](/docs/template-forms-building-publishing); for response handling, see [Responses, insights, and destinations](/docs/template-forms-responses).
+This page is for developers customizing or extending the Forms template. It covers the quick start, every action, the data model, the route surface, and how to add to it. See [Forms](/docs/template-forms) for what the app does.
 
-### Quick start
+## Quick start
+
+<Steps>
+
+### Create the app
 
 ```bash
 npx @agent-native/core@latest create my-forms --standalone --template forms
+cd my-forms
+pnpm install
+```
+
+This needs [Node.js](https://nodejs.org) 22 or later and [pnpm](https://pnpm.io) installed first. See [Getting started](/docs/getting-started) if you haven't installed either yet, or don't have an LLM connection (Builder.io, an Anthropic/OpenAI key, or local Ollama) set up.
+
+### Start the dev server
+
+```bash
+pnpm dev
 ```
 
-See [Getting started](/docs/getting-started) for install, dev server, and deployment steps. For a workspace with Forms alongside other apps, run `npx @agent-native/core@latest create my-platform` and pick Forms in the template list.
+The app opens at `http://localhost:8084`. If it doesn't open automatically, visit that URL in your browser.
+
+</Steps>
+
+For a workspace with Forms alongside other apps, run `npx @agent-native/core@latest create my-platform` and pick Forms in the template list.
+
+<Callout tone="info">
+
+**Exports need file storage configured.** `export-responses` calls `uploadFile()`. Without a file storage provider connected (Settings → File uploads, or a custom provider registered), the action throws instead of silently failing. Connect one before testing exports locally.
+
+</Callout>
+
+## Action reference
+
+Every operation is a TypeScript file in `templates/forms/actions/`, auto-mounted at `POST /_agent-native/actions/:name`.
+
+### Form lifecycle
+
+| Action         | What it does                                                                                                                                                          |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `create-form`  | Create a draft or published form (title, description, fields, settings, slug, status). Returns an editor URL, plus a public response URL when created as `published`. |
+| `get-form`     | Get a single form by id with all fields and settings. Private settings (`integrations`, `allowedOrigins`) are only included for owner, editor, or admin roles.        |
+| `list-forms`   | List accessible forms with response counts. Pass `archived: true` to list soft-deleted forms (the Archive) instead of the main list.                                  |
+| `delete-form`  | Soft-delete (sets `deleted_at`). Responses are preserved and stay visible in the Archive. Pass `purge: true` to permanently delete the form and all its responses.    |
+| `restore-form` | Restore a soft-deleted form. Responses stay intact.                                                                                                                   |
+
+### Editing fields
+
+| Action              | What it does                                                                                                                                                                                                                                                                 |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `patch-form-fields` | The visual builder's real edit path. Applies granular `upsert` / `remove` / `reorder` operations via a server-side, per-form-locked read-modify-write, so two concurrent editors patching different fields both survive instead of one clobbering the other.                 |
+| `update-form`       | Whole-array replace of `fields`, plus `title` / `description` / `slug` / `settings` / `status`. Marked legacy in its own source docblock, kept for agents and bulk imports that want to replace the entire form in one call. The UI builder does not use it for field edits. |
+
+The result is validated before it's persisted. `assertValidFields` rejects invalid or duplicate field ids and conditional rules that reference a later or missing field. If the form is already `published`, `assertPublishableForm` also re-checks that every field still has a label and that `select` / `multiselect` / `radio` fields still have options.
+
+### Previewing and analyzing
+
+| Action              | What it does                                                                                                                                                                                                                                       |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `preview-form`      | Inline chat summary of a form's setup: fields, status, visibility, response count, and an "Open editor" action. The first-party answer to "what's the setup for this form?"                                                                        |
+| `response-insights` | Chart, table, or insights analytics widget over response data. `displayMode` (`chart` / `table` / `insights`, default `insights`) controls what's returned. See [Features](/docs/template-forms-features#response-insights) for the full contract. |
+| `list-responses`    | List raw response rows for a form, for reasoning or export. If the user just wants to see responses in the UI, use `navigate` with `view=responses` instead of rendering rows in chat.                                                             |
+| `export-responses`  | Export responses to CSV or JSON, uploaded to configured file storage (never written to local disk), returning the file URL. Throws with a clear message if no file storage provider is configured.                                                 |
+
+### Database
+
+| Action       | What it does                                                                                                                                                                                                |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `db-status`  | Check the current database connection (local SQLite file vs. a configured remote `DATABASE_URL`).                                                                                                           |
+| `db-connect` | Explain how to configure `DATABASE_URL` / `DATABASE_AUTH_TOKEN` for a deployment. It does not write the connection itself, since those are deployment-level settings applied through your hosting provider. |
+
+### Navigation and UI state
+
+| Action        | What it does                                                                                                                                                                                    |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `navigate`    | Move the UI to a view, form, or tab.                                                                                                                                                            |
+| `view-screen` | Read the current view back for the agent, including the current form, builder tab, and a preview of visible responses, scoped per browser tab. Not meant to be called directly by integrations. |
 
 ## Data model
 
-All data lives in SQL via Drizzle ORM. Schema: `templates/forms/server/db/schema.ts`. Forms carry the standard `ownableColumns()` and a matching framework shares table, so they slot into the per-user / per-org sharing model.
+All data lives in SQL via Drizzle ORM. Schema: `templates/forms/server/db/schema.ts`. Forms carry the standard `ownableColumns()` and a matching framework shares table, so they slot into the per-user and per-org sharing model.
+
+| Table         | What it holds                                                                                                                                                                                                 |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `forms`       | A form definition: `title`, `description`, unique `slug`, `fields` (JSON array of `FormField`), `settings` (JSON `FormSettings`), `status` (`draft` / `published` / `closed`), and a soft-delete `deleted_at` |
+| `responses`   | One submission per row: `form_id`, `data` (JSON `{ fieldId: value }`), `submitted_at`, optional `ip`, `submitter_email`, `page_url`, and `client_surface`                                                     |
+| `form_shares` | Framework shares table mapping principals (users or orgs) to roles (viewer, editor, admin) per form                                                                                                           |
+
+`page_url` and `client_surface` are hidden pass-through columns. Trusted embeds (like the framework's FeedbackButton) forward the URL of the page a respondent was on and the runtime shell they were in (`web`, `electron`, or `tauri`), so form owners can see which screen and which app feedback came from. Both are `NULL` for direct fills that send no context, and `client_surface` is allowlisted server-side. Anything else is dropped.
+
+Every persisted field `id` (and `conditional.fieldId`) is restricted to `/^[A-Za-z0-9_-]+$/`. Both are interpolated into HTML attributes and inline-script selectors by the public-form renderer, so an unrestricted id would be a stored-XSS vector.
+
+The `fields` and `settings` JSON shapes are defined in `templates/forms/shared/types.ts` (`FormField`, `FormSettings`). A field object looks like this:
+
+```json
+{
+  "id": "team_size",
+  "type": "select",
+  "label": "Team size",
+  "placeholder": "Select...",
+  "description": "Roughly how many people are on your team?",
+  "required": true,
+  "options": ["1-5", "6-20", "21-100", "100+"],
+  "validation": {
+    "min": 1,
+    "max": 100,
+    "pattern": "^[0-9]+$",
+    "message": "Enter a number"
+  },
+  "width": "half"
+}
+```
 
-| Table         | What it holds                                                                                                                                                                                                  |
-| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `forms`       | A form definition — `title`, `description`, unique `slug`, `fields` (JSON array of `FormField`), `settings` (JSON `FormSettings`), `status` (`draft` / `published` / `closed`), and a soft-delete `deleted_at` |
-| `responses`   | One submission per row — `form_id`, `data` (JSON `{ fieldId: value }`), `submitted_at`, optional `ip`, `submitter_email`, `page_url`, and `client_surface`                                                     |
-| `form_shares` | Framework shares table mapping principals (users or orgs) to roles (viewer, editor, admin) per form                                                                                                            |
+`id`, `type`, `label`, and `required` are the only required properties. `options` is required for `select`, `multiselect`, and `radio`. `validation` (`min` / `max` / `pattern` / `message`) is optional and type-appropriate. `width` is `"full"` (default) or `"half"` for a side-by-side layout.
 
-`page_url` and `client_surface` are hidden pass-through columns: trusted embeds (like the framework's FeedbackButton) forward the URL of the page a respondent was on and the runtime shell they were in (`web`, `electron`, or `tauri`), so form owners can see which screen and which app feedback came from. Both are `NULL` for direct fills that send no context, and `client_surface` is allowlisted server-side — anything else is dropped.
+A conditional field adds a `conditional` object referencing an earlier field:
 
-The `fields` and `settings` JSON shapes are defined in `templates/forms/shared/types.ts` (`FormField`, `FormSettings`). `FormSettings` includes `integrations` (webhook URLs) and `allowedOrigins`, both owner-private. `toPublicFormSettings()` projects settings down to an explicit allowlist (`submitText`, `successMessage`, `redirectUrl`, `showProgressBar`) before any data reaches the public fill page, so integration URLs never leak to anonymous respondents.
+```json
+{
+  "id": "other_use_case",
+  "type": "text",
+  "label": "Tell us more",
+  "required": false,
+  "conditional": {
+    "fieldId": "use_case",
+    "operator": "equals",
+    "value": "Other"
+  }
+}
+```
+
+`fieldId` must reference a field that appears earlier in the form. A forward or missing reference is rejected before it can be saved. The supported operators are `equals`, `not_equals`, and `contains` (the last one also matches against multi-select arrays).
+
+`FormSettings` includes `integrations` (webhook URLs) and `allowedOrigins`, both owner-private. `toPublicFormSettings()` projects settings down to an explicit allowlist (`submitText`, `successMessage`, `redirectUrl`, `showProgressBar`) before any data reaches the public fill page, so integration URLs never leak to anonymous respondents.
 
-Every persisted field `id` (and `conditional.fieldId`) is restricted to `/^[A-Za-z0-9_-]+$/` — both are interpolated into HTML attributes and inline-script selectors by the public-form renderer, so an unrestricted id would be a stored-XSS vector.
+A Google Sheets destination has to be a deployed Apps Script `/exec` URL that calls `JSON.parse(e.postData.contents)` and appends the values. A plain spreadsheet URL, or the script's `/dev` URL, will not receive submissions, since neither one runs the deployed script against POSTed data. Every integration and `allowedOrigins` URL is validated in `server/lib/integrations.ts` against private IP ranges, cloud-metadata addresses, and non-`http(s)` schemes, both when it's saved and again each time a response fires, so a form can't be turned into a way to probe your internal network.
 
 <DataModel
   id="doc-block-forms8"
@@ -112,67 +225,108 @@ Every persisted field `id` (and `conditional.fieldId`) is restricted to `/^[A-Za
   ]}
 />
 
-## Action reference
-
-Every operation is a TypeScript file in `templates/forms/actions/`, auto-mounted at `POST /_agent-native/actions/:name`.
-
-**Form lifecycle**
-
-- `create-form` — create a draft or published form (title, description, fields, settings, slug, status). Set `settings.anonymous: true` to suppress submitter IP/identity/source metadata, or `settings.emailOnNewResponses: true` to email the owner on new responses. Returns an editor URL, plus a public response URL when created as `published`.
-- `get-form` — get a single form by id with all fields and settings. Private settings (`integrations`, `allowedOrigins`) are only included for owner/editor/admin roles.
-- `list-forms` — list accessible forms with response counts. Pass `archived: true` to list soft-deleted forms (the Archive) instead of the main list.
-- `delete-form` — soft-delete (sets `deleted_at`); responses are preserved and stay visible in the Archive. Pass `purge: true` to permanently delete the form and all its responses.
-- `restore-form` — restore a soft-deleted form; responses stay intact.
-
-**Editing fields**
+## An action walked through
 
-- `patch-form-fields` — the visual builder's real edit path. Applies granular `upsert` / `remove` / `reorder` operations against the current row via a server-side, per-form-locked read-modify-write, so two concurrent editors patching different fields both survive instead of one clobbering the other with a stale full-array snapshot.
-- `update-form` — whole-array replace of `fields`, plus `title`/`description`/`slug`/`settings`/`status`. Its own source docblock marks this the _legacy_ path, kept for agents and bulk imports that want to replace the entire form in one call. The UI builder does not use it for field edits.
+`patch-form-fields` shows patterns worth reusing in any action: serializing concurrent writers to the same row, reading fresh state inside that lock instead of before it, and validating the result before it's persisted.
 
 <AnnotatedCode
   id="doc-block-forms9"
-  title="patch-form-fields: upsert, remove, reorder in one call"
-  filename="patch-form-fields ops"
-  language="bash"
+  title="Patching a form's fields safely"
+  filename="templates/forms/actions/patch-form-fields.ts"
+  language="ts"
   code={
-    'pnpm action patch-form-fields --id frm_8x2 --ops \'[\n  {"op":"upsert","field":{"id":"nps_score","type":"scale","label":"How likely are you to recommend us?","required":true,"validation":{"min":0,"max":10}}},\n  {"op":"remove","id":"legacy_notes"},\n  {"op":"reorder","ids":["name","email","nps_score"]}\n]\''
+    '/**\n * Granular field-level update for a form.\n *\n * Accepts a list of per-field operations (upsert / remove / reorder) and\n * applies them server-side via read-modify-write against the CURRENT row, so\n * concurrent edits to DIFFERENT fields both survive instead of the later\n * client overwriting the earlier one with its stale full-array snapshot.\n *\n * The read-modify-write runs under a per-form in-process lock (same pattern\n * as `patch-deck` in the slides template) so two concurrent callers (e.g. the\n * form-builder autosave and an agent edit) are serialized instead of racing\n * on the same row — without the lock, the second writer\'s read would miss\n * the first writer\'s not-yet-committed update and silently clobber it.\n *\n * The UI form builder uses this action for all incremental edits.\n * The legacy `update-form --fields <json>` path remains available for agents\n * and bulk imports that want to replace the whole fields array at once.\n */\nimport { defineAction } from "@agent-native/core/action";\nimport { assertAccess } from "@agent-native/core/sharing";\nimport { eq } from "drizzle-orm";\nimport { z } from "zod";\n\nimport { getDb, schema } from "../server/db/index.js";\nimport { applyFieldOps } from "../server/lib/merge-fields.js";\nimport { invalidatePublicFormCache } from "../server/lib/public-form-ssr.js";\nimport {\n  assertValidFields,\n  normalizePersistedFields,\n} from "../server/lib/validate-fields.js";\nimport type { FormField } from "../shared/types.js";\nimport { assertPublishableForm } from "./lib/assert-publishable-form.js";\n\n// ---------------------------------------------------------------------------\n// Per-form write lock — mirrors `withDeckLock` in\n// templates/slides/actions/patch-deck.ts so concurrent client and agent\n// writes to the same form\'s fields are serialised in-process.\n// ---------------------------------------------------------------------------\nconst LOCK_KEY = "__formsFieldPatchLocks" as const;\ntype GlobalWithLocks = typeof globalThis & {\n  [LOCK_KEY]?: Map<string, Promise<unknown>>;\n};\nconst globalRef = globalThis as GlobalWithLocks;\nif (!globalRef[LOCK_KEY]) {\n  globalRef[LOCK_KEY] = new Map<string, Promise<unknown>>();\n}\nconst formLocks: Map<string, Promise<unknown>> = globalRef[LOCK_KEY]!;\n\nexport function withFormLock<T>(\n  formId: string,\n  fn: () => Promise<T>,\n): Promise<T> {\n  const prev = formLocks.get(formId) ?? Promise.resolve();\n  const next = prev.then(fn, fn);\n  formLocks.set(formId, next);\n  next\n    .finally(() => {\n      if (formLocks.get(formId) === next) formLocks.delete(formId);\n    })\n    .catch(() => {});\n  return next;\n}\n\nconst fieldOpSchema = z.union([\n  z.object({\n    op: z.literal("upsert"),\n    field: z\n      .record(z.string(), z.any())\n      .describe(\n        "Complete field object with id, type, label, and required; never use shorthand strings.",\n      ),\n  }),\n  z.object({\n    op: z.literal("remove"),\n    id: z.string(),\n  }),\n  z.object({\n    op: z.literal("reorder"),\n    ids: z.array(z.string()),\n  }),\n]);\n\nexport default defineAction({\n  description:\n    "Apply granular field operations (upsert/remove/reorder) to a form using a server-side read-modify-write merge. Concurrent edits to different fields both survive.",\n  schema: z.object({\n    id: z.string().describe("Form ID"),\n    ops: z\n      .union([z.string(), z.array(fieldOpSchema)])\n      .describe(\n        "Array of field ops, or JSON string of the same. Each op is {op:\'upsert\',field:{...}} | {op:\'remove\',id:string} | {op:\'reorder\',ids:string[]}",\n      ),\n  }),\n  run: async (args) => {\n    await assertAccess("form", args.id, "editor");\n\n    return withFormLock(args.id, async () => {\n      const db = getDb();\n      const [existing] = await db\n        .select()\n        .from(schema.forms)\n        .where(eq(schema.forms.id, args.id))\n        .limit(1);\n\n      if (!existing) {\n        throw new Error(`Form ${args.id} not found`);\n      }\n\n      let ops: Array<{ op: string; [k: string]: unknown }>;\n      if (typeof args.ops === "string") {\n        try {\n          ops = JSON.parse(args.ops);\n        } catch {\n          throw new Error("--ops must be valid JSON");\n        }\n      } else {\n        ops = args.ops as Array<{ op: string; [k: string]: unknown }>;\n      }\n\n      if (!Array.isArray(ops)) {\n        throw new Error("ops must be an array");\n      }\n\n      // Parse current fields from the DB row.\n      let currentFields: FormField[] = [];\n      try {\n        currentFields = normalizePersistedFields(\n          JSON.parse(existing.fields),\n        ) as FormField[];\n      } catch {\n        currentFields = [];\n      }\n\n      // Apply ops server-side so concurrent edits on different fields both land.\n      const nextFields = applyFieldOps(\n        currentFields,\n        ops as Parameters<typeof applyFieldOps>[1],\n      );\n\n      // Validate the result before persisting.\n      assertValidFields(nextFields);\n      if (existing.status === "published") {\n        assertPublishableForm(nextFields);\n      }\n\n      const now = new Date().toISOString();\n      await db\n        .update(schema.forms)\n        .set({ fields: JSON.stringify(nextFields), updatedAt: now })\n        .where(eq(schema.forms.id, args.id));\n\n      invalidatePublicFormCache(existing);\n\n      return { id: args.id, fields: nextFields, updatedAt: now };\n    });\n  },\n});'
   }
   annotations={[
     {
-      lines: "2",
-      label: "upsert",
-      note: "Inserts if `id` is new, or replaces in place at the same position if it already exists — safe under the per-form lock even if another editor is patching a different field at the same time.",
+      lines: "49-62",
+      label: "A per-form lock, not a database lock",
+      note: "Keeps a `Map` of in-flight promises keyed by form id, and chains each new call after whatever is already running for that form. Edits to different forms run fully in parallel. Two edits to the same form run one after another, so the second one always sees the first one's result instead of racing it.",
     },
     {
-      lines: "3",
-      label: "remove",
-      note: "Deletes the field by id. A no-op if the id is already gone.",
+      lines: "97-104",
+      label: "The row is read inside the lock, not before it",
+      note: "Reading happens after the lock is acquired, so it always reads the latest committed state. If the read happened first and the lock second, two overlapping calls could both start from the same stale row and the second write would silently erase the first.",
     },
     {
-      lines: "4",
-      label: "reorder",
-      note: "Fields listed in `ids` move to that order; any field not mentioned keeps its place, appended after the listed ones.",
+      lines: "109-118",
+      label: "Ops can arrive as a JSON string or a real array",
+      note: "A CLI call passes `--ops` as a string, so it's parsed here if needed. A programmatic caller can pass the array directly. Either way, the rest of the function only ever deals with a real array.",
+    },
+    {
+      lines: "140-144",
+      label: "Validated before it's saved, twice if the form is live",
+      note: "`assertValidFields` always runs and rejects duplicate or malformed field ids. `assertPublishableForm` only runs if the form is already `published`, so a live form can't be patched into a broken state, like removing the last option from a select field.",
+    },
+    {
+      lines: "152",
+      label: "The public cache is invalidated on every write",
+      note: "The public fill page caches a form for up to 60 seconds. Without this call, a field edit could take up to a minute to show up for anyone filling out the live form.",
     },
   ]}
 />
 
-The result is validated before it's persisted: `assertValidFields` rejects invalid or duplicate field ids and conditional rules that reference a later or missing field, and — if the form is already `published` — `assertPublishableForm` re-checks that every field still has a label and that `select`/`multiselect`/`radio` fields still have options.
-
-**Previewing and analyzing**
+## Routes reference
 
-- `preview-form` — inline chat summary/table of a form's setup: fields, status, visibility, response count, and an "Open editor" action. The first-party answer to "@form setup?"
-- `response-insights` — chart/table/insights analytics widget over response data. `displayMode` (`chart` / `table` / `insights`, default `insights`) controls what's returned. See [Responses, insights, and destinations](/docs/template-forms-responses#response-insights) for the full contract.
-- `list-responses` — list raw response rows for a form, for reasoning or export. If the user just wants to see responses in the UI, use `navigate` with `view=responses` instead of rendering rows in chat.
-- `export-responses` — export responses to CSV or JSON, uploaded to configured file storage (never written to local disk), returning the file URL.
-
-**Database**
-
-- `db-status` — check the current database connection (local SQLite file vs. a configured remote `DATABASE_URL`).
-- `db-connect` — explain how to configure `DATABASE_URL` / `DATABASE_AUTH_TOKEN` for a deployment; it does not write the connection itself, since those are deployment-level settings applied through your hosting provider.
-
-**UI awareness**
-
-`navigate` and `view-screen` give the agent awareness of the current form, builder tab, and response view — they back the "what am I looking at" and "open this view" behavior described in [Forms](/docs/template-forms) and aren't meant to be called directly by integrations.
+<FileTree
+  id="doc-block-forms10"
+  title="Forms template layout"
+  entries={[
+    {
+      path: "actions/",
+      note: "every agent-callable action — form lifecycle, fields, previewing, database",
+    },
+    {
+      path: "app/routes/_app.forms._index.tsx",
+      note: "the forms list",
+    },
+    {
+      path: "app/routes/_app.forms.$id.tsx",
+      note: "the form builder (Edit, Responses, Settings, Integrations tabs)",
+    },
+    {
+      path: "app/routes/_app.forms.$id_.responses.tsx",
+      note: "the responses view for one form",
+    },
+    {
+      path: "app/routes/_app.response-insights.tsx",
+      note: "the response insights page",
+    },
+    { path: "app/routes/_app.ask.tsx", note: "the Ask Forms landing chat" },
+    {
+      path: "app/routes/f.$.tsx",
+      note: "the public fill page (canonical: /f/{slug})",
+    },
+    {
+      path: "app/routes/form-preview.tsx",
+      note: "internal form preview, used by the builder",
+    },
+    {
+      path: "server/db/schema.ts",
+      note: "Drizzle tables — forms, responses, form_shares",
+    },
+    {
+      path: "server/handlers/forms.ts",
+      note: "the public, unauthenticated form-fetch handler",
+    },
+    {
+      path: "server/handlers/submissions.ts",
+      note: "the public submission handler — captcha, SSRF checks, routing",
+    },
+    {
+      path: "server/lib/integrations.ts",
+      note: "Slack, Discord, Google Sheets, and webhook delivery",
+    },
+    {
+      path: "server/lib/validate-fields.ts",
+      note: "field and conditional-rule validation",
+    },
+    {
+      path: "shared/types.ts",
+      note: "FormField, FormSettings, and PublicFormSettings shapes",
+    },
+  ]}
+/>
 
 ## Customizing it
 
@@ -184,12 +338,13 @@ Ask the agent for shipped behavior first:
 - "Create a customer feedback form with a 1-10 scale and a long-text follow-up."
 - "Make some forms public and others login-only."
 
-If you need new capabilities such as file uploads, signatures, or custom field widgets, treat them as template extensions: add the SQL shape, actions, UI editor controls, public renderer support, and agent instructions together. See [Creating Templates](/docs/creating-templates) for the current build pattern.
+If you need new capabilities such as file uploads, signatures, or custom field widgets, treat them as template extensions. Add the SQL shape, actions, UI editor controls, public renderer support, and agent instructions together. See [Creating Templates](/docs/creating-templates) for the current build pattern.
 
 ## What's next
 
-- [**Forms**](/docs/template-forms) — the product overview and non-developer tour
-- [**Building and publishing a form**](/docs/template-forms-building-publishing) — field types, conditional logic, and public-form protections
-- [**Responses, insights, and destinations**](/docs/template-forms-responses) — analyzing, exporting, and routing submissions
-- [**Actions**](/docs/actions-overview) — the action system powering the builder
-- [**Sharing**](/docs/sharing) — the `form_shares` role model
+- [**Forms**](/docs/template-forms) — the overview and what it replaces
+- [**Features**](/docs/template-forms-features) — the user-facing behavior these actions and this data model power
+- [**Talk to the Agent**](/docs/template-forms-agent) — every prompt by task and how the agent sees your screen
+- [**Forms in a Multi-App Workspace**](/docs/template-forms-integrations) — how these actions get exposed to other apps and Dispatch
+- [**Actions**](/docs/actions-overview) — the action system this template is built on
+- [**Sharing**](/docs/sharing) — the share-grant model `form_shares` uses

package/docs/content/template-forms-features.mdx

@@ -0,0 +1,154 @@
+---
+title: "Forms: Features"
+description: "Every core Forms feature, including field types, publishing, protections, responses, insights, and routing, with setup steps for each."
+---
+
+# Features
+
+Every core Forms feature: how it works, and how to set it up. See [Forms](/docs/template-forms) for the overview and [Talk to the Agent](/docs/template-forms-agent) for the full list of prompts.
+
+## Create a form
+
+Every form starts with a set of fields. Describe what you want to the agent and it builds the form for you, or start from scratch and add fields yourself in the visual builder. Both paths edit the same form, so switching between them never causes anything to fall out of sync. Once a form exists, its builder has four tabs, Edit, Responses, Settings, and Integrations, for adjusting labels, placeholders, required fields, options, and field order by hand whenever you want more direct control than describing a change in chat.
+
+<Video
+  src="https://cdn.builder.io/o/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fd1d93690182e42089cdd41c9b1eb9806?alt=media&token=da8d18fd-b0d7-4720-aabd-9e6f6edcc93a&apiKey=YJIGb4i01jvw0SRdL5Bt"
+  alt="A brief video showing an existing form, including adding 'required' to a field."
+  caption="A brief video showing an existing form, including adding 'required' to a field."
+  autoplay={true}
+  loop={true}
+/>
+
+### Field types {#field-types}
+
+Forms ships with 11 field types out of the box. Ask the agent for any of them by name, or just describe the question you want to ask and let it pick the right type.
+
+<Table
+  id="doc-block-forms3"
+  title="Shipped field types"
+  columns={["Type", "Needs options", "Example use"]}
+  rows={[
+    ["text", "No", "Name, company"],
+    ["email", "No", "Contact email"],
+    ["number", "No", "Age, quantity"],
+    ["textarea", "No", "Message, comments"],
+    ["select", "Yes", "Country, department"],
+    ["multiselect", "Yes", "Skills, interests"],
+    ["checkbox", "No", "Consent, opt-in"],
+    ["radio", "Yes", "Gender, preference"],
+    ["date", "No", "Birthday, deadline"],
+    ["rating", "No", "Satisfaction, quality (1-5 stars)"],
+    ["scale", "No", "NPS, likelihood (numeric range)"],
+  ]}
+/>
+
+Every field needs a label and a type. Fields like `select`, `multiselect`, and `radio` also need a list of options for people to choose from. You can mark any field as required, add validation like a minimum or maximum value, and choose whether it takes up the full width of the form or sits side by side with another field.
+
+### Conditional fields
+
+A field can stay hidden until an earlier answer matches a rule you set. For example, you could hide a "Tell us more" text field unless someone picks "Other" on an earlier question.
+
+The field you're checking against has to come earlier in the form. A rule that points at a later field, or one that doesn't exist, is rejected before it can be saved. You can check whether an earlier answer equals a value, does not equal a value, or contains a value, which also works for questions where someone can pick more than one option. If a field ends up hidden by its condition, its answer is never stored or sent anywhere, so a hidden field can't leave an old or default value in your data.
+
+Scripting form creation directly instead of describing it in chat? See the field and settings JSON reference in the [Developer Guide](/docs/template-forms-developers#data-model).
+
+## Publish your form
+
+A form moves through three statuses:
+
+| Status      | Meaning                                  | Public access          |
+| ----------- | ---------------------------------------- | ---------------------- |
+| `draft`     | Work in progress, not publicly available | No                     |
+| `published` | Live and accepting responses             | Yes                    |
+| `closed`    | No longer accepting responses            | Shows a closed message |
+
+A form can't be published if it has no fields, any field is missing a label, or a `select`, `multiselect`, or `radio` field has no options. If rejected when publishing, you'll be given a specific reason.
+
+The public URL looks like `/f/<slug>`, where the slug is generated from the title plus a short unique suffix, like `beta-signup-a1b2c3`. It regenerates automatically whenever the title changes, unless you set a custom slug.
+
+### Collect responses
+
+Every submission to a published form becomes one response: the answers, when it arrived, and, unless the form is anonymous, who sent it and where from. Open any form's Responses tab to see each one in detail, or just ask the agent:
+
+- "How many responses does the beta signup form have?"
+- "Who submitted today?"
+- "Show me the responses for the customer feedback form."
+
+If a response came in through a feedback button embedded in another app, rather than the public form page itself, the responses table also shows which page and which app it came from. These columns only show up once at least one response actually carries that information.
+
+## Settings
+
+Each form has its own settings, in the builder's Settings tab, for how it behaves and what respondents see.
+
+- **Submit button text.** Change the label on the submit button from the default "Submit" to something more specific, like "Send feedback" or "Reserve my spot."
+- **Success message.** Choose what respondents see right after they submit, instead of the default confirmation.
+- **Redirect URL.** Send respondents to another page after they submit, instead of showing a success message on the form itself.
+- **Progress bar.** Show a progress bar across the top of a longer form so respondents can see how much is left.
+- **Anonymous mode.** Turn off all tracking of who responded, so submissions never capture an IP address, email, or location.
+- **Email me for new responses.** Get an email every time someone submits, sent through your configured email provider.
+
+## Protect and brand a public form
+
+### Spam protection
+
+Public submissions can require verification through [Cloudflare Turnstile](https://www.cloudflare.com/products/turnstile/) before they go through. Turn this on by setting a site key and a secret key in Settings. Two protections stay on even without Turnstile: a hidden field that quietly discards bot submissions, and a check that rejects anything submitted faster than a person could reasonably fill out the form.
+
+<Callout tone="warning">
+
+Set both Turnstile keys together. The public form page only shows the verification widget when the site key is set, and the server only checks it when both keys are set. Setting just the secret key verifies nothing, and setting just the site key shows a widget the server never actually checks.
+
+</Callout>
+
+### Branding
+
+Every standalone public form shows a small "Built with Agent-Native" badge in the corner. This isn't something you turn on or off per form. It's hidden automatically only when the form is embedded inside another page, like a feedback popover, since that page already carries its own branding.
+
+### Restrict submitting origins
+
+By default, a form's submit link accepts submissions from anywhere, which is how a plain public form link is meant to behave. If you're embedding a form's submit link inside a widget on another site and want to make sure only that site can use it, you can restrict submissions to a specific list of website origins.
+
+There's no toggle for this in the builder today. Ask the agent to set it up, for example "only allow this form to be submitted from https://example.com." Give the agent the exact origin (the scheme and domain, like `https://example.com`, without a trailing path) for each site that should be allowed.
+
+## Response insights {#response-insights}
+
+Ask for trends or summaries instead of scrolling through rows. Try "submissions by day," "how many responses this week," or "summarize this week's feedback," and the agent gives you back a chart, a table, or both, instead of a wall of raw data.
+
+<Video
+  src="https://cdn.builder.io/o/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fc594fa6d6bfe4479a36114306401bb60?alt=media&token=fa7e9243-7a96-4418-9aeb-9eb3fa441e76&apiKey=YJIGb4i01jvw0SRdL5Bt"
+  alt="An example of requesting tabular data from a form, based on response themes."
+  caption="An example of requesting tabular data from a form, based on response themes."
+  autoplay={true}
+  loop={true}
+/>
+
+When you don't name a specific form, the agent looks across your most recently updated forms instead, up to 50 by default and 100 at most. This is useful for a question like "how are submissions trending across all my forms this month?" Every answer tells you whether it's showing everything or just a sample, along with how many rows that covers, so you always know what you're looking at.
+
+## Export
+
+From a form's Responses tab, click **Export CSV** to download a CSV of what's currently on screen right away, including any search or sort you've applied. This works immediately, with no setup needed.
+
+You can also ask the agent for "a CSV of this form" or "a JSON export of all responses." This always exports every response, not just what's currently filtered, and needs a file storage provider connected first. If none is connected yet, the agent will tell you and point you to Settings → File uploads, where a free Builder.io account works as a quick option. Once storage is connected, the agent hands you back a link to the file instead of downloading it directly. Each export uses your field labels as column headers (for CSV), and if someone selected more than one option in a field, those choices are joined together in one cell. Any answer that looks like it could be a spreadsheet formula is neutralized first, which protects you from a submission that tries to run code when you open the file.
+
+## Route submissions
+
+Turn on automatic delivery so new responses show up where your team already works, instead of someone checking the Responses tab. This is a per-form setting, configured in the builder's Integrations tab.
+
+| Destination   | What it needs                                                                                   |
+| ------------- | ----------------------------------------------------------------------------------------------- |
+| Slack         | An Incoming Webhook URL for the channel you want                                                |
+| Discord       | A webhook URL for the channel you want                                                          |
+| Google Sheets | A Google Apps Script URL set up to receive submissions. A plain spreadsheet link will not work. |
+| Webhook       | Any web address that can receive the submission as data                                         |
+
+This is separate from connecting Slack for the agent to post there directly, which is covered in [Messaging](/docs/messaging). Connect that first if you want the agent itself to post updates to Slack. Every destination address is checked to make sure it isn't pointing at a private network or an internal address, both when you save it and every time a response comes in, so a form can't be turned into a way to probe your own network.
+
+You can also turn on an email notification so the form owner gets an email every time there's a new response, sent through whichever email service is already configured. Sending that email is best effort. A submission still goes through even if the notification email fails to send.
+
+## What's next
+
+- [**Forms**](/docs/template-forms) — the overview and what it replaces
+- [**Talk to the Agent**](/docs/template-forms-agent) — every prompt by task and how the agent sees your screen
+- [**Forms in a Multi-App Workspace**](/docs/template-forms-integrations) — delegation and the public submit endpoint other apps use
+- [**Developer Guide**](/docs/template-forms-developers) — the field, settings, and action reference behind these features
+- [**Sharing**](/docs/sharing) — the share-grant model form shares build on
+- [**Messaging**](/docs/messaging) — connecting Slack for the agent to post directly