@netlify/agent-runner-cli 2.7.0 → 2.8.0

package/dist/skills/netlify-forms/SKILL.md

@@ -1,358 +1,214 @@
 ---
 name: netlify-forms
-description: Build and configure Netlify Forms for serverless form handling. Use when implementing contact forms, feedback forms, file uploads, or any form that collects user submissions without backend code. Make sure to always run `node scripts/enable.cjs` located in this skill's directory after implementing Netlify Forms.
+description: Serverless form handling on Netlify-hosted sites — detects HTML forms at deploy time, stores submissions, filters spam, and sends notifications. Use when adding a contact form, lead-capture form, file-upload form, or newsletter signup to a Netlify site; wiring AJAX form submission; setting up a custom thank-you page; adding a honeypot or reCAPTCHA to a form; getting forms working in Next.js, Nuxt, SvelteKit, Astro, or Gatsby; reading form submissions via the Netlify API; or debugging missing submissions and forms that silently fail to register.
 ---
 
 # Netlify Forms
 
-Netlify Forms is a serverless form-handling service. The build system parses HTML at deploy time to detect forms and
-automatically creates submission endpoints.
+Mark a form for detection with `data-netlify="true"` (or the bare `netlify` attribute — equivalent) on the `<form>` tag. Forms are detected by **parsing the final built HTML at deploy time** — there is no runtime API call or backend code. Client-side/JS-rendered/SSR forms are NOT in the built HTML and are never detected on their own; they require a static skeleton file (see below).
 
-## Enable Feature
+Prerequisite: form detection must be enabled once in the Netlify UI (Forms > **Enable form detection**). Takes effect on the next deploy.
 
-After implementing Netlify Forms, you **must** run the enable script to activate the feature on the deploy. The script
-is located in this skill's `scripts/` directory:
-
-```bash
-node scripts/enable.cjs
-```
-
-## Quick Start
-
-Add `data-netlify="true"` or `netlify` attribute to any `<form>` tag:
+## Static HTML form
 
 ```html
 <form name="contact" method="POST" data-netlify="true">
-  <input type="text" name="name" required />
-  <input type="email" name="email" required />
-  <textarea name="message"></textarea>
-  <button type="submit">Send</button>
+  <p><label>Your Name: <input type="text" name="name" /></label></p>
+  <p><label>Your Email: <input type="email" name="email" /></label></p>
+  <p><label>Message: <textarea name="message"></textarea></label></p>
+  <p><button type="submit">Send</button></p>
 </form>
 ```
 
-**Key requirements:**
-
-- The `name` attribute identifies the form in Netlify UI (must be unique per site)
-- Method must be `POST`
-- Netlify injects a hidden `form-name` field during build
-
-## AJAX / JavaScript Submission
-
-Submit forms without page reload:
-
-```javascript
-const form = document.getElementById('contact-form')
-
-form.addEventListener('submit', async (e) => {
-  e.preventDefault()
-
-  const response = await fetch('/', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-    body: new URLSearchParams(new FormData(form)).toString(),
-  })
-
-  if (response.ok) {
-    // Handle success
-  }
-})
-```
-
-> **SSR/SPA apps (React, Vue, TanStack Start, Next.js, SvelteKit, Remix, Nuxt):** You MUST create a static HTML skeleton
-> file for build-time form detection. Without it, Netlify cannot detect the form during build and submissions will
-> silently fail. Additionally, the `fetch` URL must target the skeleton file path (e.g. `/__forms.html`), **not** `/` —
-> in SSR apps, `fetch('/')` is intercepted by the SSR function and never reaches Netlify's form processing middleware.
-> See [JavaScript Frameworks](#javascript-frameworks-ssr--client-rendered-apps) below.
+- `name` sets the form name in the UI and **must be unique per site**.
+- At deploy, Netlify strips the `data-netlify`/`netlify` attribute and injects `<input type="hidden" name="form-name" value="contact" />`.
+- Add an `<input name="email">` so the notification email's `Reply-to` is set to the submitter.
 
-**Critical AJAX requirements:**
+## JS-rendered / SSR / framework forms (Next.js, Nuxt, SvelteKit, Astro, Gatsby)
 
-1. Content-Type MUST be `application/x-www-form-urlencoded`
-2. Include hidden `form-name` field in your HTML:
-   ```html
-   <input type="hidden" name="form-name" value="contact" />
-   ```
+Two required pieces:
 
-## JavaScript Frameworks (SSR & Client-Rendered Apps)
-
-Netlify's build bot cannot detect forms rendered client-side. For any SSR or SPA framework (React, Vue, TanStack Start,
-Next.js, SvelteKit, Remix, Nuxt), you MUST:
-
-1. **Create a static HTML skeleton** in `public/` for build-time form detection — this is the critical step. Without it,
-   Netlify never registers the form and submissions will silently fail or 404.
-2. Submit via AJAX with `e.preventDefault()` — full-page POST will not work in SPAs
-3. Include a hidden `form-name` field matching the form's `name` attribute
-
-### Static Form Skeleton
-
-Create a static HTML file (e.g. `public/__forms.html`) containing every form your app uses. The file name does not
-matter — Netlify scans all HTML files in the build output:
+**1. Static skeleton file `public/__forms.html`** — a hidden copy of each form with `data-netlify="true"`, a hidden `form-name` input, and every field the component submits, with names matching **exactly** (Netlify validates field names against the registered form). Without this file, submissions silently fail.
 
 ```html
-<!-- public/__forms.html — only for Netlify's build bot detection -->
-<html>
-  <body>
-    <form name="contact" data-netlify="true" netlify-honeypot="bot-field" hidden>
-      <input type="hidden" name="form-name" value="contact" />
-      <input name="name" />
-      <input name="email" />
-      <textarea name="message"></textarea>
-      <input name="bot-field" />
-    </form>
-  </body>
-</html>
+<!-- public/__forms.html -->
+<form name="pizzaOrder" data-netlify="true" hidden>
+  <input type="hidden" name="form-name" value="pizzaOrder" />
+  <input name="order" type="text" />
+</form>
 ```
 
-**Rules:**
-
-- The form `name` attribute must exactly match the `form-name` value in your React/Vue component
-- Include every field your component submits — Netlify validates field names against the registered form
-- Add `netlify-honeypot="bot-field"` and a `bot-field` input for spam protection
-
-### React Example
+**2. The rendered form** carries a matching hidden `form-name` input:
 
 ```jsx
-function ContactForm() {
-  const handleSubmit = async (e) => {
-    e.preventDefault()
-    const formData = new FormData(e.target)
-
-    // URL must point to the static skeleton file, not '/' — SSR catch-all intercepts '/'
-    await fetch('/__forms.html', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-      body: new URLSearchParams(formData).toString(),
-    })
-  }
-
-  return (
-    <form name="contact" method="POST" data-netlify="true" netlify-honeypot="bot-field" onSubmit={handleSubmit}>
-      {/* Hidden field required for AJAX */}
-      <input type="hidden" name="form-name" value="contact" />
-      <p style={{ display: 'none' }}>
-        <label>
-          Don't fill this out: <input name="bot-field" />
-        </label>
-      </p>
-      <input name="name" required />
-      <input name="email" type="email" required />
-      <textarea name="message" />
-      <button type="submit">Send</button>
-    </form>
-  )
-}
-```
-
-## File Uploads
-
-```html
-<form name="upload" method="POST" data-netlify="true" enctype="multipart/form-data">
-  <input type="file" name="attachment" />
-  <button type="submit">Upload</button>
+<form name="pizzaOrder" method="post" data-netlify="true" onSubmit={handleSubmit}>
+  <input type="hidden" name="form-name" value="pizzaOrder" />
+  <input name="order" type="text" onChange={handleChange} />
+  <input type="submit" />
 </form>
 ```
 
-**Limits:**
-
-- Maximum request size: **8 MB**
-- Timeout: **30 seconds**
-- One file per input field (use multiple inputs for multiple files)
-
-**Security:** For file uploads containing PII (personally identifiable information), use the
-[Very Good Security (VGS)](https://www.netlify.com/integrations/very-good-security/) integration for additional
-protection.
-
-**AJAX file uploads:** Do NOT set Content-Type header - let browser set `multipart/form-data` with boundary:
+**⚠️ SSR POST target:** In SSR apps, `fetch("/")` is intercepted by the SSR catch-all function and never reaches form processing. POST to the static skeleton file itself — `/__forms.html` — not `/` or an arbitrary path.
 
-```javascript
-// Correct - no Content-Type header
-fetch('/', {
-  method: 'POST',
-  body: new FormData(form), // Browser sets correct Content-Type
-})
-```
+**⚠️ Astro on-demand routes:** Routes with `export const prerender = false` or `output: "server"` are never scanned at build time, so their forms are never registered. Put the form on a prerendered page, or rely on the static skeleton file.
 
-## Spam Protection
+**Next.js Runtime v5 (Next.js 13.5+):** extract form definitions to the static skeleton file and submit via AJAX rather than full-page navigation. See https://docs.netlify.com/build/frameworks/framework-setup-guides/nextjs/overview#v5-breaking-changes
 
-### Honeypot Field (Recommended)
+## AJAX submission
 
-```html
-<form name="contact" method="POST" data-netlify="true" netlify-honeypot="bot-field">
-  <!-- Hidden from humans, filled by bots -->
-  <p style="display:none">
-    <label>Don't fill this: <input name="bot-field" /></label>
-  </p>
-
-  <!-- Visible fields -->
-  <input name="name" required />
-  <button type="submit">Send</button>
-</form>
+```js
+const handleSubmit = event => {
+  event.preventDefault();
+  const formData = new FormData(event.target);
+  fetch("/__forms.html", {   // static sites may POST to "/"; SSR must target the skeleton file
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams(formData).toString()
+  })
+    .then(() => alert("Thank you for your submission"))  // or navigate("/thank-you")
+    .catch(error => alert(error));
+};
+document.querySelector("form").addEventListener("submit", handleSubmit);
 ```
 
-### reCAPTCHA v2 (Netlify-provided)
+- **Body MUST be URL-encoded. JSON is NOT supported.**
+- If the rendered form has no hidden `form-name` input, you MUST include a `form-name` field in the POST body.
+- The honeypot field name and `g-recaptcha-response` (if used) must be in the body — automatic with `FormData()`.
 
-```html
-<form name="contact" method="POST" data-netlify="true" data-netlify-recaptcha="true">
-  <input name="name" required />
+## File uploads
 
-  <!-- Netlify injects reCAPTCHA here -->
-  <div data-netlify-recaptcha="true"></div>
+Add `type="file"`; optionally `enctype="multipart/form-data"` on the `<form>`. For AJAX file uploads, **do NOT set a `Content-Type` header** — let the browser set it (with the multipart boundary).
 
-  <button type="submit">Send</button>
-</form>
+```js
+document.forms.fileForm.addEventListener("submit", event => {
+  event.preventDefault();
+  fetch("/", { body: new FormData(event.target), method: "POST" })  // no headers
+    .then(() => { /* success */ });
+});
 ```
 
-Only one Netlify-provided reCAPTCHA per page. For multiple CAPTCHAs on one page, use custom reCAPTCHA.
-
-### Custom reCAPTCHA v2
-
-Use your own reCAPTCHA 2 code with Netlify validation:
+Limits: one file per field (use multiple fields for multiple files) · 8 MB max request size · 30 s upload timeout · after form deletion, uploaded files stay at their direct URL for 24 h. PII uploads need extra security (Very Good Security integration).
 
-1. Sign up for a [reCAPTCHA API key pair](http://www.google.com/recaptcha/admin) and add the reCAPTCHA script/widget to
-   your form.
-2. Set environment variables in Netlify (UI, CLI, or API):
-   - `SITE_RECAPTCHA_KEY` — your reCAPTCHA site key (scopes: Builds + Runtime)
-   - `SITE_RECAPTCHA_SECRET` — your reCAPTCHA secret key (scope: Runtime)
-3. Add `data-netlify-recaptcha="true"` to your `<form>` tag.
+## Custom success page
 
-Netlify validates the `g-recaptcha-response` server-side on each submission.
-
-**For AJAX with reCAPTCHA:** Include `g-recaptcha-response` in POST body (automatic if using `FormData()`).
-
-## Success Redirects
+Add an `action` path relative to site root, starting with `/`. **Use extensionless paths** — Netlify serves `thank-you.html` at `/thank-you`; the `.html` path returns 404.
 
 ```html
-<!-- Redirect to custom thank-you page -->
-<form name="contact" method="POST" data-netlify="true" action="/thank-you"></form>
+<form name="contact" action="/thank-you" method="POST" data-netlify="true"></form>
 ```
 
-The `action` path must:
-
-- Start with `/`
-- Be relative to site root
-- Point to an existing page
-
-> **Pretty URLs:** Netlify serves `thank-you.html` at `/thank-you` by default. Use `action="/thank-you"`, not
-> `action="/thank-you.html"` — the `.html` path returns 404.
-
-## Notifications
-
-### Email Notifications
-
-Configure in Netlify UI: **Project configuration > Notifications > Emails and webhooks > Form submission notifications**
+Custom success *alert* is only possible via AJAX (substitute the redirect with your own logic).
 
-- Include `<input name="email">` to set reply-to address automatically
-- Custom subject line:
-  ```html
-  <input type="hidden" name="subject" value="New inquiry from %{formName}" />
-  ```
-- Available variables: `%{formName}`, `%{siteName}`, `%{submissionId}`
-- For forms created before May 5, 2023: remove `[Netlify]` prefix from subject by adding `data-remove-prefix`:
-  ```html
-  <input type="hidden" name="subject" data-remove-prefix value="Sales inquiry" />
-  ```
+## Spam prevention
 
-### Webhooks
+All submissions are filtered by Akismet. Passed → **Verified submissions**; flagged → **Spam submissions**. Honeypot/reCAPTCHA failures are rejected and appear in neither list.
 
-Configure in Netlify UI: **Project configuration > Notifications > Emails and webhooks > Form submission notifications**
+**Honeypot:** add `netlify-honeypot="bot-field"` to the `<form>` and include a CSS-hidden field of that name. Any value entered → submission quietly rejected.
 
-Sends JSON payload on each verified submission.
-
-## Function Triggers
-
-Trigger serverless functions on submissions:
-
-```typescript
-// netlify/functions/submission-created.mts
-import type { Context } from '@netlify/functions'
-
-interface FormPayload {
-  form_name: string
-  data: Record<string, string>
-  created_at: string
-}
-
-export default async (req: Request, context: Context) => {
-  const { payload } = (await req.json()) as { payload: FormPayload }
-
-  console.log('Form:', payload.form_name)
-  console.log('Data:', payload.data)
-
-  // Process submission (send to CRM, Slack, etc.)
-
-  return new Response('OK')
-}
+```html
+<form name="contact" method="POST" netlify-honeypot="bot-field" data-netlify="true">
+  <p class="hidden"><label>Don’t fill this out: <input name="bot-field" /></label></p>
+  <!-- real fields -->
+</form>
 ```
 
-**Event name:** `submission-created` (filename must match)
-
-## Limits
+**Netlify reCAPTCHA 2:** add `data-netlify-recaptcha="true"` to the `<form>` AND an empty `<div data-netlify-recaptcha="true"></div>` where it renders. Only ONE Netlify-provided challenge per page — for multiple, use custom reCAPTCHA. For JS-rendered forms, also add the `div` to the static skeleton file.
 
-| Feature      | Free Tier   | Paid Tier  |
-| ------------ | ----------- | ---------- |
-| Submissions  | 100/month   | Metered    |
-| File Storage | 10 MB/month | Scalable   |
-| Request Size | 8 MB        | 8 MB       |
-| Timeout      | 30 seconds  | 30 seconds |
+**Custom reCAPTCHA 2:** your own reCAPTCHA snippet + `data-netlify-recaptcha="true"` on the `<form>`, plus env vars:
+- `SITE_RECAPTCHA_KEY` — site key (scopes: Builds + Runtime)
+- `SITE_RECAPTCHA_SECRET` — secret (scope: Runtime)
 
-## Common Errors & Solutions
+## Email notifications & subject line
 
-### "404 on submit"
+Default sender: `formresponses@netlify.com`. Set subject via a hidden `subject` input **or** the Netlify UI (Forms > Submission notifications) — **not both; the HTML value always overrides the UI.**
 
-**Cause:** Build bot didn't detect the form. **Fix:**
+```html
+<input type="hidden" name="subject" value="New lead from %{formName} (%{submissionId})" />
+```
 
-1. Ensure static HTML version exists for JS frameworks
-2. Verify `form-name` hidden input is present
-3. Check form has `name` attribute
+Variables: `%{formName}`, `%{siteName}`, `%{submissionId}`. Forms created before **May 5, 2023** carry a `[Netlify]` subject prefix — remove it by adding the `data-remove-prefix` attribute to the `subject` input.
 
-### Submissions not appearing
+Set up notifications (email/webhook/Slack) in the UI: Forms > Submission notifications > **Add notification**.
 
-**Check:**
+## Reading submissions via the API
 
-1. Look in **Spam** folder in Netlify UI (Akismet filtering)
-2. Avoid test values like "test@test.com" or "asdf" — use real email and full sentences
-3. Verify form was included in the latest deploy
+Use only documented surfaces. Do NOT invent `api.netlify.com` endpoints or read tokens from local CLI config files. Reference: https://open-api.netlify.com/#tag/submission/operation/listFormSubmissions
 
-### AJAX submission fails silently
+- **Page through results using the `Link` header** — code that reads only the first response silently drops the rest.
+- `listFormSubmissions` returns data from old/removed fields no longer shown in the UI.
+- Query spam with `?state=spam`.
 
-**Ensure:**
+## Submission summary (field order matters)
 
-1. Content-Type is `application/x-www-form-urlencoded` (not JSON)
-2. `form-name` field is included in body
-3. Check browser Network tab for actual response
+The UI summary is derived from field **type**, not name:
+- **Title**: first non-hidden text `<input>` that isn't email-like (`type="email"`, or name matching `email`/`mail`/`from`/`twitter`/`sender`); falls back to a field named `title` or `subject`.
+- **Body**: first `<textarea>`.
 
-### Form succeeds but no submissions appear (SSR apps)
+Field order in the HTML affects what appears in the summary.
 
-**Cause:** Two things must be true for SSR form submissions to work:
+## Debugging missing submissions
 
-1. A static HTML skeleton file must exist in `public/` so Netlify registers the form at build time.
-2. The `fetch` URL must target the skeleton file path (e.g. `/__forms.html`), **not** `/`.
+- **First suspect: Akismet false positive.** A missing legitimate submission is usually spam-flagged — check the **Spam** list (or API `?state=spam`) and mark it verified. Do NOT build a custom recovery function or disable spam filtering as a first resort.
+- Test submissions get flagged as spam: use a real email (not `test@test.com`), write full sentences, don't hammer from one IP.
+- No submissions at all: confirm form detection is enabled (Forms > Form detection) and redeploy.
+- SSR/JS forms silently failing: verify the static skeleton file exists with exactly-matching field names and that AJAX targets the skeleton file, not `/`.
+- Missing old-field data: the UI shows only fields from the last deployed form version. Mark old fields `hidden` instead of removing them to keep them visible; old data remains available via `listFormSubmissions`.
+- Still stuck: Netlify Support Guide on how to debug your form — https://answers.netlify.com/t/common-issue-how-to-debug-your-form/92
 
-Without (1), Netlify doesn't know the form exists. Without (2), the POST to `/` is intercepted by the SSR catch-all
-function (TanStack Start, Next.js, SvelteKit, Remix, Nuxt) — the SSR handler renders a 200 HTML page, so `fetch()`
-reports success, but the request never reaches Netlify's form processing middleware.
+## Constraints
 
-**Fix:**
+- Deleting a form is permanent: future submissions return `404`, past submissions become unavailable. Export CSV first.
+- Submitted code is sanitized (`<script>` → escaped entities).
+- For PII, export and delete data regularly.
+- Data is stored in Netlify's database, not accessible except via UI/API/CSV.
 
-1. Create a static HTML skeleton in `public/` (see
-   [JavaScript Frameworks](#javascript-frameworks-ssr--client-rendered-apps) section).
-2. Change `fetch('/')` to `fetch('/__forms.html')` (or whatever path your skeleton file is at) so the request routes
-   through the CDN origin where Netlify's `formsHandler` runs.
+<!-- system: agent-context/forms/system.md — human-owned, merged by ctx-gen; edit system.md, not this section -->
+# Netlify house rules (forms)
 
-### File upload fails
+These are org conventions and field-learned guardrails, not docs facts — they
+are merged into the rendered skill by ctx-gen and are never generated.
+Extracted from the previous hand-written netlify-forms skill; owned by the
+skills maintainer.
 
-**Check:**
+1. In SSR apps (Next.js, Nuxt, SvelteKit, etc.), `fetch("/")` is intercepted
+   by the SSR catch-all function and never reaches Netlify's form processing.
+   POST the AJAX submission to the static skeleton file itself (e.g.
+   `/__forms.html`), not to an arbitrary path.
+2. Use only documented surfaces: do not curl `https://api.netlify.com/...`
+   with an invented endpoint shape, and do not read tokens out of local CLI
+   config files (`~/Library/Preferences/netlify/config.json`).
+3. When reading submissions via the API, page through results (`Link`
+   header); code that reads only the first response silently drops the rest.
+4. For JS-rendered and SSR forms, always create the static skeleton file
+   `public/__forms.html`: a hidden copy of each form with
+   `data-netlify="true"`, a hidden `form-name` input, and every field the
+   component submits — names matching exactly (Netlify validates field names
+   against the registered form). Without this file, submissions silently fail.
+5. Astro routes rendered on demand (`export const prerender = false`, or
+   `output: "server"` routes) are never scanned at build time, so their forms
+   are never registered. Put the form on a prerendered page or rely on the
+   static skeleton file.
+6. A "missing" legitimate submission is usually an Akismet false positive:
+   check the Spam list (or the API with `?state=spam`) and mark it verified.
+   Do not build a custom recovery function or disable spam filtering as a
+   first resort.
+7. For custom success pages, use extensionless `action` paths (`/thank-you`,
+   not `/thank-you.html`) — Netlify serves `thank-you.html` at `/thank-you`
+   and the `.html` path returns 404.
 
-1. Total request size under 8 MB
-2. Not setting Content-Type header manually
-3. Using `enctype="multipart/form-data"` on form
 
-## API Access
+## Additional requirements
 
-List submissions programmatically:
+After implementing Netlify Forms, you MUST run `scripts/enable.cjs` from this skill using Node. Use the absolute path to
+the script and keep the project's directory as your working directory:
 
 ```bash
-curl -H "Authorization: Bearer $NETLIFY_AUTH_TOKEN" \
-  https://api.netlify.com/api/v1/forms/{form_id}/submissions
+node /absolute/path/to/netlify-forms/scripts/enable.cjs
 ```
 
-Export available as CSV from Netlify UI.
+Replace the example path with the installed location of this skill. The script creates `.netlify/features/netlify-forms`
+in the project's repository. The deployment workflow uses that marker to request form detection enablement before
+deploying.
+
+In this environment, this script replaces the manual UI enablement prerequisite above. Do not ask the user to enable
+form detection in the Netlify UI; run the script after implementing the form.