docs: document the surface-isolation security model and CSP usage

The Architecture invariants in AGENTS.md (the agent dev guide) had the core
"agent content only renders in a sandboxed iframe" rule but predated this
security pass. Expand it to capture what we now rely on:

- the /s/:id `Content-Security-Policy: sandbox allow-scripts` response header,
  which keeps a top-level load opaque-origin (the iframe attribute only covers
  the embedded case);
- how we use CSP — buildCsp (html parts: CDN allowlist, connect-src is CDNs
  only) vs buildRichCsp (rich parts: no connect-src at all), and that the
  resource policy is independent of the sandbox that makes the origin opaque;
- the bridge trust model — author:"user" is reserved for the composer
  (sendPrompt posts "surface"; MCP reply_to_user coerces "user"→"agent"),
  openLink is re-validated host-side, and every request body is capped.

No runtime change.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: benvinegar

.changeset/document-security-model.md

@@ -0,0 +1,5 @@
+---
+---
+
+Docs only: document the surface-isolation security model and CSP usage in the
+agent dev guide (AGENTS.md). No runtime change.

AGENTS.md

@@ -99,7 +99,23 @@ consciously, not as a side effect):
   happen at an opaque origin. When you add a part kind, pick (a) or (b); never a
   third way. The iframes are sandboxed without `allow-same-origin` (opaque
   origin) and `connect-src`-free for rich parts (no exfil even if contained
-  script runs); never weaken this.
+  script runs); never weaken this. `/s/:id` is same-origin, so the iframe
+  `sandbox` attribute only covers embedding — the route also sends a
+  `Content-Security-Policy: sandbox allow-scripts` **header** (a meta tag can't
+  carry `sandbox`) so a top-level load stays opaque too; never add
+  `allow-same-origin`.
+- **CSP layers.** `buildCsp` (html parts): `default-src 'none'`, CDN allowlist,
+  `connect-src` = those CDNs only (no board API); origin named in
+  `img-src`/`media-src` since `'self'` is nothing at an opaque origin.
+  `buildRichCsp` (rich parts, `renderSandboxedPart`): bridge-only inline script,
+  no `connect-src`. CSP limits _resources_; the sandbox makes the _origin_
+  opaque — keep both.
+- **Surface→host bridge — gate every crossing.** `author:"user"` is reserved
+  for the composer: `sendPrompt` posts `author:"surface"` (never reaches the
+  agent), MCP `reply_to_user` coerces `"user"`→`"agent"`. `openLink` is
+  re-validated host-side (`http(s)` only). Request bodies are capped
+  (`bodyLimit`). A new host-affecting message or write endpoint gets gated
+  likewise.
 - WebKit quirk in sandboxed iframes: ResizeObserver's initial callback may not
   fire and `documentElement.scrollHeight` ratchets to viewport height — the
   bridge reports `body.scrollHeight` on `load` plus staggered timers. Don't