@agent-native/core 0.122.3 → 0.123.0

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

@@ -0,0 +1,195 @@
+---
+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."
+---
+
+# Forms — data model and actions
+
+This page is for developers forking 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).
+
+### Quick start
+
+```bash
+npx @agent-native/core@latest create my-forms --standalone --template forms
+```
+
+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.
+
+## 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.
+
+| 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.
+
+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.
+
+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.
+
+<DataModel
+  id="doc-block-forms8"
+  title="Forms data model"
+  summary={
+    "Three tables. Fields and integrations are JSON columns on forms, so the agent's edits are surgical patches rather than cross-table row changes."
+  }
+  entities={[
+    {
+      id: "forms",
+      name: "forms",
+      note: "A form definition (ownable)",
+      fields: [
+        { name: "id", type: "id", pk: true },
+        { name: "title", type: "string" },
+        { name: "description", type: "string", nullable: true },
+        { name: "slug", type: "string", note: "unique; public URL" },
+        { name: "fields", type: "json", note: "FormField[] — all field types" },
+        {
+          name: "settings",
+          type: "json",
+          note: "FormSettings — integrations, etc.",
+        },
+        { name: "status", type: "enum", note: "draft | published | closed" },
+        {
+          name: "deleted_at",
+          type: "datetime",
+          nullable: true,
+          note: "soft delete",
+        },
+        { name: "owner_email", type: "string" },
+        { name: "org_id", type: "id", nullable: true },
+      ],
+    },
+    {
+      id: "responses",
+      name: "responses",
+      note: "One submission per row",
+      fields: [
+        { name: "id", type: "id", pk: true },
+        { name: "form_id", type: "id", fk: "forms.id" },
+        { name: "data", type: "json", note: "{ fieldId: value }" },
+        { name: "submitted_at", type: "datetime" },
+        { name: "ip", type: "string", nullable: true },
+        { name: "submitter_email", type: "string", nullable: true },
+        {
+          name: "page_url",
+          type: "string",
+          nullable: true,
+          note: "hidden pass-through — page respondent was on",
+        },
+        {
+          name: "client_surface",
+          type: "string",
+          nullable: true,
+          note: "hidden pass-through — web | electron | tauri",
+        },
+      ],
+    },
+    {
+      id: "form_shares",
+      name: "form_shares",
+      note: "Framework shares table — principals to roles per form",
+      fields: [
+        { name: "id", type: "id", pk: true },
+        { name: "form_id", type: "id", fk: "forms.id" },
+        { name: "principal", type: "string", note: "user or org" },
+        { name: "role", type: "enum", note: "viewer | editor | admin" },
+      ],
+    },
+  ]}
+  relations={[
+    { from: "forms", to: "responses", kind: "1-n", label: "has responses" },
+    {
+      from: "forms",
+      to: "form_shares",
+      kind: "1-n",
+      label: "has share grants",
+    },
+  ]}
+/>
+
+## 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**
+
+- `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.
+
+<AnnotatedCode
+  id="doc-block-forms9"
+  title="patch-form-fields: upsert, remove, reorder in one call"
+  filename="patch-form-fields ops"
+  language="bash"
+  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]\''
+  }
+  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: "3",
+      label: "remove",
+      note: "Deletes the field by id. A no-op if the id is already gone.",
+    },
+    {
+      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.",
+    },
+  ]}
+/>
+
+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**
+
+- `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.
+
+## Customizing it
+
+Ask the agent for shipped behavior first:
+
+- "Add a required radio field for preferred contact method."
+- "Post every new submission to Slack." Connect Slack first via [Messaging](/docs/messaging).
+- "Add a webhook destination for our CRM."
+- "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.
+
+## 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) — the action system powering the builder
+- [**Sharing**](/docs/sharing) — the `form_shares` role model

package/corpus/core/docs/content/template-forms-responses.mdx

@@ -0,0 +1,120 @@
+---
+title: "Forms — responses, insights, and destinations"
+description: "Where form submissions live, how to ask the agent for charts and summaries, exporting to CSV or JSON, and routing new responses to Slack, Discord, Sheets, or a webhook."
+---
+
+# Responses, insights, and destinations
+
+This page covers what happens after someone submits a form: where the response is stored, how to ask the agent to analyze it, how to export it, and how to route it to other tools automatically. It's for anyone reviewing form results, whether or not they touch code.
+
+## Collecting responses
+
+Every submission to a published form becomes one row: the answers (keyed by field id), when it arrived, and — unless the form is anonymous — who sent it and where from. You can open any form's Responses tab for a per-response detail view, or just ask:
+
+- "How many responses does the beta signup form have?"
+- "Who submitted today?"
+- "Show me the responses for the customer feedback form."
+
+When a response was submitted through an embedded feedback widget elsewhere (rather than filled out directly on the public form page), the responses table also shows a **Page** and **Source** column — the page the respondent was on and whether they were on web, desktop (Electron), or desktop (Tauri). These only appear when at least one response actually carries that context.
+
+## Response insights {#response-insights}
+
+Ask for trends or summaries instead of scrolling rows — "submissions by day," "how many responses this week," "summarize this week's feedback" — and the agent returns a native chart, table, or combined dashboard rather than a wall of raw data. Which one comes back depends on what you asked for:
+
+<Diagram
+  id="doc-block-forms6"
+  title="Response insights: one action, three shapes"
+  summary={
+    "The same analysis runs every time; only what gets returned changes with what you asked for."
+  }
+>
+
+```html
+<div class="diagram-branch">
+  <div class="diagram-panel center">
+    <span class="diagram-pill accent">response-insights</span
+    ><small class="diagram-muted">displayMode</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-col">
+    <div class="diagram-node">
+      chart<br /><small class="diagram-muted"
+        >"submissions by day" — bar chart only</small
+      >
+    </div>
+    <div class="diagram-node">
+      table<br /><small class="diagram-muted"
+        >"show me the rows" — response table only</small
+      >
+    </div>
+    <div class="diagram-node">
+      insights (default)<br /><small class="diagram-muted"
+        >"summarize this" — chart + table + summary</small
+      >
+    </div>
+  </div>
+</div>
+```
+
+```css
+.diagram-branch {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.diagram-branch .diagram-col {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+.diagram-branch .diagram-arrow {
+  font-size: 22px;
+  line-height: 1;
+}
+.diagram-branch .center {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+}
+```
+
+</Diagram>
+
+<WireframeBlock id="doc-block-forms7">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='display:flex;flex-direction:column;min-height:420px;box-sizing:border-box;padding:32px 48px;justify-content:center'><div class='wf-card' style='max-width:520px;gap:14px'><strong>Beta signup — response insights</strong><div style='display:flex;align-items:flex-end;gap:6px;height:64px'><div style='width:18px;height:20%;background:var(--wf-line)'></div><div style='width:18px;height:45%;background:var(--wf-line)'></div><div style='width:18px;height:30%;background:var(--wf-line)'></div><div style='width:18px;height:70%;background:var(--wf-line)'></div><div style='width:18px;height:55%;background:var(--wf-line)'></div><div style='width:18px;height:90%;background:var(--wf-line)'></div><div style='width:18px;height:60%;background:var(--wf-line)'></div></div><span class='wf-muted' style='font-size:12px'>Submissions by day · last 30 days · 187 responses</span><span class='wf-pill accent'>Open response insights</span></div></div>"
+    }
+  />
+</WireframeBlock>
+
+When you don't name a form, the agent scopes the analysis to your most recently updated accessible forms (up to 50 by default, 100 max) instead of just one — useful for "how are submissions trending across all my forms this month?" Every result reports whether it's exact or sampled, along with the row counts, so you always know if you're looking at everything or a preview.
+
+## Exporting
+
+"Export this to CSV" or "give me a JSON export of all responses" uploads a file to your configured file storage and returns the link — exports are never written to local disk, since serverless hosts have a read-only filesystem. CSV rows use field labels as headers, join multi-select answers with semicolons, and neutralize any cell that looks like a spreadsheet formula (a defense against CSV injection from anonymous submitters).
+
+## Routing submissions
+
+Turn on automatic delivery so new responses show up where your team already works, instead of someone having to check the Responses tab:
+
+| Destination   | What it needs                                                                                                                                                     |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Slack         | An Incoming Webhook URL for the target channel                                                                                                                    |
+| Discord       | A Discord channel webhook URL                                                                                                                                     |
+| Google Sheets | A deployed Apps Script `/exec` URL that calls `JSON.parse(e.postData.contents)` and appends the values — a spreadsheet or `/dev` URL will not receive submissions |
+| Webhook       | Any HTTPS endpoint; receives the full structured submission payload as JSON                                                                                       |
+
+These are configured per form in the builder's Integrations tab and are separate from the app-wide Slack connection under [Messaging](/docs/messaging) — connect that first if you want the agent to post there directly instead. Every destination URL is checked against private IPs, cloud-metadata addresses, and non-`http(s)` schemes both when you save it and again each time a response fires, so a form can't be turned into an internal-network probe.
+
+Turn on `settings.emailOnNewResponses` to also email the form owner's account on every new response, using whichever email provider is configured (Resend or SendGrid). Email delivery is best-effort: a public submission still succeeds even if the email fails to send, so check server logs and provider configuration if an expected email never arrives.
+
+## What's next
+
+- [**Forms**](/docs/template-forms) — the product overview
+- [**Building and publishing a form**](/docs/template-forms-building-publishing) — fields, conditional logic, and public-form protections
+- [**Forms — data model and actions**](/docs/template-forms-developers) — the `response-insights`, `export-responses`, and `list-responses` action contracts
+- [**Messaging**](/docs/messaging) — connecting Slack for direct agent posting

package/corpus/core/docs/content/template-forms.mdx

@@ -1,30 +1,30 @@
 ---
 title: "Forms"
-description: "Agent-native form builder — create, edit, publish, and route form submissions through natural language plus a visual editor."
+description: "Agent-native form builder — describe the form you want in chat, fine-tune it visually, publish a public link, and watch responses roll in."
 ---
 
 # Forms
 
-Forms is an agent-native form builder. Describe the form you want, refine it in the editor, and publish a public form that stores submissions in your own SQL database.
+Forms is a form builder for anyone who needs to collect information — signups, feedback, registrations, surveys — without writing code. Describe the form you want to the agent, fine-tune it visually when you want direct control, and publish a link anyone can fill out.
 
-<WireframeBlock id="doc-block-1x3o6t4">
+<WireframeBlock id="doc-block-forms1">
   <Screen
     surface="desktop"
     html={
-      "<div style='display:flex;flex-direction:column;min-height:520px;box-sizing:border-box'><div style='display:flex;align-items:center;gap:10px;padding:14px 16px;border-bottom:1.4px solid var(--wf-line)'><strong>Beta signup</strong><span class='wf-pill accent'>published</span><div style='flex:1'></div><button>Share</button><button class='primary'>Unpublish</button></div><div style='display:flex;gap:8px;padding:12px 16px;border-bottom:1.4px solid var(--wf-line)'><span class='wf-pill accent'>Edit</span><span class='wf-pill'>Results 187</span><span class='wf-pill'>Settings</span><span class='wf-pill'>Integrations</span></div><div style='display:flex;flex-direction:column;gap:12px;padding:30px 78px;overflow:hidden'><h2 style='margin:0'>Beta signup</h2><p class='wf-muted' style='margin:0'>Reserve a spot in the upcoming private beta cohort.</p><div class='wf-card'><strong>Full name</strong><input value='Ada Lovelace'/></div><div class='wf-card'><strong>Work email</strong><input value='you@company.com'/></div><div class='wf-card'><strong>Your role</strong><input value='Select...'/></div><div class='wf-card'><strong>Team size</strong><input value='Select...'/></div></div></div>"
+      "<div style='min-height:560px;box-sizing:border-box;display:flex;align-items:center;justify-content:center;padding:56px 40px'><div style='display:flex;flex-direction:column;align-items:center;justify-content:center;gap:24px;width:min(700px,92%);min-height:420px'><div style='text-align:center'><h1 style='margin:0'>Ask Forms</h1><p class='wf-muted' style='margin:10px 0 0'>Describe the form you want. Fine-tune it visually once it exists.</p></div><div class='wf-card' style='width:100%;min-height:140px;display:flex;flex-direction:column;gap:18px'><span class='wf-muted'>Create a beta signup form with role, team size, and priority use case</span><div style='flex:1'></div><div style='display:flex;align-items:center;gap:10px'><div style='flex:1'></div><button class='primary'>↑</button></div></div><div style='display:flex;gap:8px;flex-wrap:wrap;justify-content:center'><span class='wf-pill'>Post responses to Slack</span><span class='wf-pill'>Summarize this week's submissions</span><span class='wf-pill'>Make this form shorter</span></div></div></div>"
     }
   />
 </WireframeBlock>
 
-When you open the app, you see your forms, the current editor, and a live preview. The agent can create a form from a prompt, update field labels and options, change validation, and connect submission destinations using the same actions the UI uses.
+Every new session opens on **Ask Forms**, a chat where you describe what you want. The agent creates the form, and you move into the visual editor whenever you want to adjust fields, validation, or publishing settings by hand — both paths edit the same SQL-backed form definition, so nothing gets out of sync.
 
-<Diagram id="doc-block-1g89hqk" title="Build, publish, collect" summary={"The agent and the visual editor edit one SQL-backed form definition. The public fill page is unauthenticated, and submissions route server-side to your destinations."}>
+<Diagram id="doc-block-forms2" title="Build, publish, collect" summary={"The agent and the visual editor edit one SQL-backed form definition. The public fill page is unauthenticated, and submissions route server-side to your destinations."}>
 
 ```html
 <div class="diagram-flow">
   <div class="diagram-col">
     <div class="diagram-node">
-      Agent prompt<br /><small class="diagram-muted"
+      Ask Forms chat<br /><small class="diagram-muted"
         >"add an NPS question"</small
       >
     </div>
@@ -36,7 +36,7 @@ When you open the app, you see your forms, the current editor, and a live previe
   </div>
   <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
   <div class="diagram-panel center">
-    <span class="diagram-pill accent">create-form · update-form</span
+    <span class="diagram-pill accent">create-form · patch-form-fields</span
     ><small class="diagram-muted">fields JSON, settings JSON</small>
   </div>
   <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
@@ -85,245 +85,36 @@ When you open the app, you see your forms, the current editor, and a live previe
 
 ## What you can do with it
 
-- **Build forms conversationally.** "Create a contact form," "add an NPS score question," "make the email field required." The agent updates the form schema and the preview updates from SQL-backed state.
+- **Build forms conversationally.** "Create a contact form," "add an NPS score question," "make the email field required." See [field types and JSON schema](/docs/template-forms-building-publishing#field-types).
 - **Fine-tune visually.** Edit labels, placeholders, required state, options, and field order from the builder UI when you want direct control.
-- **Use the shipped field types.** Text, email, number, long text, select, multi-select, checkbox, radio, date, rating, and scale fields are supported out of the box.
-- **Collect responses.** Each submission is stored in SQL with a per-response detail view and a dashboard for reviewing entries.
-- **Route submissions.** Send submission payloads to webhooks, Slack, Discord, or Google Sheets using the built-in integrations.
-- **Publish public forms.** Share a public form URL and show a thank-you message after submission.
+- **Publish and protect a public form.** Share a public link, and turn on captcha protection or fully anonymous responses when you need them — see [Building and publishing a form](/docs/template-forms-building-publishing).
+- **Review responses and ask for insights.** "Summarize this week's submissions," "chart submissions by day" — see [Responses, insights, and destinations](/docs/template-forms-responses).
+- **Route submissions automatically.** Send new responses to Slack, Discord, Google Sheets, or a webhook the moment they arrive.
 
 ## Getting started
 
 Live demo: [forms.agent-native.com](https://forms.agent-native.com).
 
-1. **Create a form from a prompt.** Ask for the form you want, including the
-   audience and what should happen after submission.
-2. **Refine in the editor.** Adjust labels, validation, choices, and order in
-   the visual builder when direct editing is faster.
-3. **Publish and share.** Use the public form URL for respondents, then watch
-   results arrive in the Responses view.
-4. **Connect destinations.** Route new submissions to Slack, Discord, Google
-   Sheets, webhooks, or your own extension point.
+1. **Ask for the form you want.** Ask Forms is the landing chat — describe the audience and what should happen after submission.
+2. **Refine in the editor.** Adjust labels, validation, choices, and order in the visual builder when direct editing is faster.
+3. **Publish and share.** Use the public form URL for respondents, then watch results arrive in the Responses view.
+4. **Connect destinations.** Route new submissions to Slack, Discord, Google Sheets, webhooks, or your own extension point.
 
 ### Useful prompts
 
 - "Create a beta signup form with role, team size, and priority use case."
 - "Add a required NPS question and a free-text follow-up."
+- "Create an anonymous customer feedback form and give me the public link."
 - "Post every new response to the product Slack channel."
+- "What's the setup for my beta signup form?"
 - "Summarize this week's submissions and group them by customer segment."
 - "Make this form shorter without losing the fields we need for routing."
 
-## For developers
-
-The rest of this doc is for anyone forking the Forms template or extending it.
-
-### Quick start
-
-```bash
-npx @agent-native/core@latest create my-forms --standalone --template forms
-cd my-forms
-pnpm install
-pnpm dev
-```
-
-For a workspace with Forms alongside other apps:
-
-```bash
-npx @agent-native/core@latest create my-platform
-```
-
-Pick Forms and any other templates you want during the workspace setup.
-
-### Key features {#key-features}
-
-**JSON form definitions.** Fields live in one `fields` JSON column, so the agent can make surgical edits without schema changes for every field type.
-
-**Public fill pages.** Respondents can submit unauthenticated forms, while private settings are stripped before data reaches the browser.
-
-**Server-side destinations.** Slack, Discord, Google Sheets, and webhook integrations live in form settings and run after submission.
-
-### 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.
-
-| 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` and `submitter_email`                                                                                    |
-| `form_shares` | Framework shares table mapping principals (users or orgs) to roles (viewer, editor, admin) per form                                                                                                            |
-
-The `fields` and `settings` JSON shapes are defined in `templates/forms/shared/types.ts` (`FormField`, `FormSettings`). Owner-private settings such as integration webhook URLs and allowed origins are stripped before any data reaches the public fill page via `toPublicFormSettings`.
-
-<DataModel
-  id="doc-block-nhh66t"
-  title="Forms data model"
-  summary={
-    "Three tables. Fields and integrations are JSON columns on forms, so the agent's edits are surgical patches rather than cross-table row changes."
-  }
-  entities={[
-    {
-      id: "forms",
-      name: "forms",
-      note: "A form definition (ownable)",
-      fields: [
-        {
-          name: "id",
-          type: "id",
-          pk: true,
-        },
-        {
-          name: "title",
-          type: "string",
-        },
-        {
-          name: "description",
-          type: "string",
-          nullable: true,
-        },
-        {
-          name: "slug",
-          type: "string",
-          note: "unique; public URL",
-        },
-        {
-          name: "fields",
-          type: "json",
-          note: "FormField[] — all field types",
-        },
-        {
-          name: "settings",
-          type: "json",
-          note: "FormSettings — integrations, etc.",
-        },
-        {
-          name: "status",
-          type: "enum",
-          note: "draft | published | closed",
-        },
-        {
-          name: "deleted_at",
-          type: "datetime",
-          nullable: true,
-          note: "soft delete",
-        },
-        {
-          name: "owner_email",
-          type: "string",
-        },
-        {
-          name: "org_id",
-          type: "id",
-          nullable: true,
-        },
-      ],
-    },
-    {
-      id: "responses",
-      name: "responses",
-      note: "One submission per row",
-      fields: [
-        {
-          name: "id",
-          type: "id",
-          pk: true,
-        },
-        {
-          name: "form_id",
-          type: "id",
-          fk: "forms.id",
-        },
-        {
-          name: "data",
-          type: "json",
-          note: "{ fieldId: value }",
-        },
-        {
-          name: "submitted_at",
-          type: "datetime",
-        },
-        {
-          name: "ip",
-          type: "string",
-          nullable: true,
-        },
-        {
-          name: "submitter_email",
-          type: "string",
-          nullable: true,
-        },
-      ],
-    },
-    {
-      id: "form_shares",
-      name: "form_shares",
-      note: "Framework shares table — principals to roles per form",
-      fields: [
-        {
-          name: "id",
-          type: "id",
-          pk: true,
-        },
-        {
-          name: "form_id",
-          type: "id",
-          fk: "forms.id",
-        },
-        {
-          name: "principal",
-          type: "string",
-          note: "user or org",
-        },
-        {
-          name: "role",
-          type: "enum",
-          note: "viewer | editor | admin",
-        },
-      ],
-    },
-  ]}
-  relations={[
-    {
-      from: "forms",
-      to: "responses",
-      kind: "1-n",
-      label: "has responses",
-    },
-    {
-      from: "forms",
-      to: "form_shares",
-      kind: "1-n",
-      label: "has share grants",
-    },
-  ]}
-/>
-
-### Key actions
-
-Every operation is a TypeScript file in `templates/forms/actions/`, auto-mounted at `POST /_agent-native/actions/:name`:
-
-- `create-form` — create a new form (title, description, fields, settings)
-- `update-form` — update fields, settings, or status
-- `get-form` — retrieve a form by id or slug
-- `list-forms` — list accessible forms
-- `delete-form` — soft-delete (sets `deleted_at`)
-- `restore-form` — restore a soft-deleted form
-- `list-responses` — list submissions for a form with optional filters
-- `export-responses` — export responses as CSV or JSON
-
-### Customizing it
-
-Ask the agent for shipped behavior first:
-
-- "Add a required radio field for preferred contact method."
-- "Post every new submission to Slack." Connect Slack first via [Messaging](/docs/messaging).
-- "Add a webhook destination for our CRM."
-- "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.
-
 ## What's next
 
+- [**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
+- [**Forms — data model and actions**](/docs/template-forms-developers) — the SQL schema and action reference, for developers
 - [**Templates**](/docs/cloneable-saas) — the clone-and-own model
 - [**Actions**](/docs/actions) — the action system powering the builder
 - [**Messaging**](/docs/messaging) — Slack and other submission destinations