diff --git a/docs/security/embeds-and-csp.md b/docs/security/embeds-and-csp.md
new file mode 100644
index 00000000..12d309b0
--- /dev/null
+++ b/docs/security/embeds-and-csp.md
@@ -0,0 +1,135 @@
+# CMS embeds and browser content policies
+
+This document describes the trust boundary between CMS-authored content
+and the browser: which third-party embeds are allowed, how they are
+constrained, and which security headers every response carries.
+
+The single source of truth for the embed allowlist is
+[`src/lib/security/embedPolicy.mjs`](../../src/lib/security/embedPolicy.mjs).
+The Content-Security-Policy in
+[`src/lib/security/headers.mjs`](../../src/lib/security/headers.mjs) is
+built from the same allowlist, so approving a new provider in one place
+updates both the runtime validation and the CSP.
+
+## Structured embed configuration
+
+CMS editors configure embeds with structured fields, not raw HTML:
+
+- **Promise updates** (`promise-updates` global): the `formUrl` field
+ takes the https URL of the Airtable shared form (e.g.
+ `https://airtable.com/embed/app…/shr…`). The legacy `embedCode` field
+ still accepts a plain Airtable ``,
+ ),
+ ).toBe(AIRTABLE_URL);
+ });
+
+ it("returns null when there is no iframe src", () => {
+ expect(extractIframeSrc("
hello
")).toBeNull();
+ expect(extractIframeSrc(null)).toBeNull();
+ });
+});
+
+describe("resolveUpdateFormUrl", () => {
+ it("prefers the structured formUrl", () => {
+ expect(
+ resolveUpdateFormUrl({
+ formUrl: AIRTABLE_URL,
+ embedCode: ``,
+ }),
+ ).toBe(AIRTABLE_URL);
+ });
+
+ it("falls back to the legacy iframe snippet src", () => {
+ expect(
+ resolveUpdateFormUrl({
+ embedCode: ``,
+ }),
+ ).toBe(AIRTABLE_URL);
+ });
+
+ it("rejects URLs outside the allowlist", () => {
+ expect(
+ resolveUpdateFormUrl({ formUrl: "https://evil.example.com/embed" }),
+ ).toBeNull();
+ expect(
+ resolveUpdateFormUrl({
+ embedCode: ``,
+ }),
+ ).toBeNull();
+ expect(resolveUpdateFormUrl(null)).toBeNull();
+ });
+});
+
+describe("withUpdateFormPrefill", () => {
+ it("adds prefill query params to the form URL", () => {
+ const result = new URL(
+ withUpdateFormPrefill(AIRTABLE_URL, {
+ promiseTitle: "Build 500km of roads",
+ promiseUrl: "https://checkmedia.org/promise/1",
+ updateDate: "2026-07-16T10:00:00Z",
+ }),
+ );
+ expect(result.searchParams.get("prefill_Promise")).toBe(
+ "Build 500km of roads",
+ );
+ expect(result.searchParams.get("prefill_CheckMedia Link")).toBe(
+ "https://checkmedia.org/promise/1",
+ );
+ expect(result.searchParams.get("hide_CheckMedia Link")).toBe("true");
+ expect(result.searchParams.get("prefill_Date")).toBe("2026-07-16");
+ });
+
+ it("leaves the URL unchanged when no prefill values are provided", () => {
+ expect(withUpdateFormPrefill(AIRTABLE_URL, {})).toBe(AIRTABLE_URL);
+ });
+});
+
+describe("getMailchimpBotFieldName", () => {
+ it("derives the honeypot field name from u and id params", () => {
+ expect(getMailchimpBotFieldName(MAILCHIMP_URL)).toBe("b_abc123_def456");
+ });
+
+ it("returns null when params are missing", () => {
+ expect(
+ getMailchimpBotFieldName("https://example.us1.list-manage.com/post"),
+ ).toBeNull();
+ });
+});
+
+describe("promise-update field validators", () => {
+ it("accepts an approved form URL and empty optional value", () => {
+ expect(validateUpdateFormUrlField(AIRTABLE_URL)).toBe(true);
+ expect(validateUpdateFormUrlField("")).toBe(true);
+ });
+
+ it("rejects non-allowlisted form URLs", () => {
+ expect(
+ validateUpdateFormUrlField("https://evil.example.com/embed"),
+ ).toMatch(/approved embed provider/);
+ });
+
+ it("requires either formUrl or embedCode", () => {
+ expect(validateUpdateEmbedCodeField("", null)).toMatch(/Provide/);
+ expect(validateUpdateEmbedCodeField("", AIRTABLE_URL)).toBe(true);
+ });
+
+ it("accepts a plain allowlisted iframe snippet", () => {
+ expect(
+ validateUpdateEmbedCodeField(``),
+ ).toBe(true);
+ });
+
+ it.each([
+ [
+ "script tags",
+ ``,
+ /script/i,
+ ],
+ [
+ "inline event handlers",
+ ``,
+ /event handler/i,
+ ],
+ ["snippets without an iframe", `