@agent-native/core-corpus 0.204.0-nightly-20261008011018 → 0.204.0

package/corpus/README.md

@@ -32,4 +32,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core-corpus/corpu
 
 ## Generated Counts
 
-- template files: 11374
+- template files: 11386

package/corpus/templates/analytics/.agents/skills/actions/references/action-fields.md

@@ -16,6 +16,7 @@ Rules:
 - To override the inference on an unusual action (e.g. a `POST` that only reads), pass `readOnly: true` on the action definition.
 - To let a mutating action run concurrently with other same-turn tool calls, pass `parallelSafe: true`. Only do this when the action is internally concurrency-safe and order-independent (for example, it uses an app-level lock or idempotent upsert semantics). Mutating actions remain serialized by default.
 - If a successful call hands control to the user — it renders a question, an intake form, or anything else the turn must wait on — pass `endsTurn: true` and make it the first or only call in the turn. It stops subsequent model steps and later calls, but cannot undo calls emitted before it. Without it a completion guard sees a turn that legitimately paused as one that failed to finish. `endsTurn: true` also hides the action from MCP, WebMCP, and A2A callers by default (`isActionExposedToExternalAgents` in core `action.ts`) — an external host has no in-app chat to receive the answer on. Pass `mcpTool: true` alongside it only when an external caller can complete the same operation without that answer.
+- MCP hosts read tool annotations to decide how carefully to treat a call. Every MCP catalog advertises declared `mcpAnnotations` (`readOnlyHint`, `destructiveHint`, `openWorldHint`, optional `idempotentHint`); otherwise `/mcp` derives only `readOnlyHint` and an approval-based `destructiveHint`. Declare them on any external write that removes, overwrites, or replaces user content — recoverable Trash included — and mark idempotency-key-guarded writes `idempotentHint: true`.
 
 Agents do NOT need to call `refresh-screen` after a normal action — it's already handled. `refresh-screen` is only needed when the agent mutates data via a path the framework can't see (e.g. writing to an external system the app mirrors) or when the agent wants to pass a `scope` hint for narrower invalidation.
 

package/corpus/templates/analytics/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable user-facing changes to Agent-Native Analytics are documented here. Open it any
 time from the command menu (Cmd+K → "What's new") or from Settings.
 
+## 2026-10-07
+
+### Added
+
+- Session replay screenshots can be copied directly into Design.
+
+### Fixed
+
+- Session replay screenshot export captures readable video frames and safe poster images.
+
 ## 2026-10-06
 
 ### Added

package/corpus/templates/analytics/app/i18n/en-US.ts

@@ -1581,6 +1581,13 @@ export default {
     savingScreenshot: "Saving screenshot…",
     screenshotDownloaded: "Screenshot downloaded",
     screenshotSaveFailed: "Couldn't save screenshot",
+    copyScreenshot: "Copy to Design",
+    copyingScreenshot: "Copying screenshot…",
+    screenshotCopiedForDesign: "Screenshot copied. Paste it into Design.",
+    screenshotCopyFailed:
+      "Couldn't copy the screenshot to the clipboard. Try Save screenshot, then upload the PNG in Design.",
+    screenshotCopyUnsupportedAssets:
+      "Screenshot not copied: this moment contains media or images that can't be captured securely. Try another moment in the replay.",
     screenshotUnsupportedAssets:
       "Screenshot not saved: some embedded media or images can't be captured securely.",
     timeline: "Event timeline",

package/corpus/templates/analytics/app/pages/sessions/SessionDetailPage.tsx

@@ -96,9 +96,11 @@ import {
 import { extractReplayDiagnostics } from "./session-replay-devtools";
 import type { ReplayDevToolsDiagnostics } from "./session-replay-devtools";
 import {
+  captureReplayScreenshot,
   completeReplayScreenshotCapture,
-  downloadReplayScreenshot,
+  downloadReplayScreenshotBlob,
   ReplayScreenshotAssetError,
+  writeReplayScreenshotToClipboard,
 } from "./session-replay-screenshot";
 import {
   type SessionIssueMatch,
@@ -582,6 +584,9 @@ function ReplayPlayer({
   const [currentTime, setCurrentTime] = useState(0);
   const [totalTime, setTotalTime] = useState(0);
   const [speed, setSpeed] = useState(DEFAULT_SPEED);
+  const [screenshotAction, setScreenshotAction] = useState<
+    "copy" | "save" | null
+  >(null);
   const [skipInactive, setSkipInactive] = useState(true);
   const [devToolsOpen, setDevToolsOpen] = useState(false);
   const [devToolsHeight, setDevToolsHeight] = useState(DEFAULT_DEVTOOLS_HEIGHT);
@@ -1032,18 +1037,23 @@ function ReplayPlayer({
     }
   }
 
-  async function saveScreenshot() {
+  function runScreenshotAction(
+    action: "copy" | "save",
+    operation: (
+      screenshot: Promise<Blob>,
+      filename: string,
+      onClipboardWriteFailure: () => void,
+    ) => Promise<void>,
+    onSuccess: () => void,
+    onFailure: (error: unknown) => void,
+  ) {
     const replayer = replayerRef.current;
     const iframe = replayer?.iframe as HTMLIFrameElement | undefined;
     const stage = stageAreaRef.current;
     const stageRoot = stageRootRef.current;
-    if (
-      !replayer ||
-      !iframe ||
-      !stage ||
-      !stageRoot ||
-      savingScreenshotRef.current
-    ) {
+    if (savingScreenshotRef.current) return;
+    if (!replayer || !iframe || !stage || !stageRoot) {
+      onFailure(new Error("Replay screenshot is unavailable"));
       return;
     }
 
@@ -1052,56 +1062,108 @@ function ReplayPlayer({
       replayer.getCurrentTime?.() ?? currentTimeRef.current,
     );
     const capture = new AbortController();
+    let clipboardWriteFailed = false;
+    const onClipboardWriteFailure = () => {
+      if (screenshotCaptureRef.current !== capture) return;
+      clipboardWriteFailed = true;
+      capture.abort();
+    };
     screenshotCaptureRef.current = capture;
     savingScreenshotRef.current = true;
     setSavingScreenshot(true);
+    setScreenshotAction(action);
 
+    const filename = `session-replay-${Math.floor(captureAt / 1000)
+      .toString()
+      .padStart(4, "0")}.png`;
+    let actionPromise: Promise<void>;
     try {
       replayer.pause(captureAt);
       setPlaying(false);
       updateTime(captureAt);
-      await downloadReplayScreenshot(
+      const screenshot = captureReplayScreenshot(
         stage,
         stageRoot,
         iframe,
-        `session-replay-${Math.floor(captureAt / 1000)
-          .toString()
-          .padStart(4, "0")}.png`,
         capture.signal,
       );
-      toast.success(t("sessions.screenshotDownloaded"));
+      // Clipboard writes need this click's activation, so start the operation before awaiting capture.
+      actionPromise = operation(screenshot, filename, onClipboardWriteFailure);
     } catch (error) {
-      if (!capture.signal.aborted) {
+      actionPromise = Promise.reject(error);
+    }
+
+    void actionPromise
+      .then(onSuccess, (error: unknown) => {
+        if (
+          !capture.signal.aborted ||
+          (clipboardWriteFailed && screenshotCaptureRef.current === capture)
+        ) {
+          capture.abort();
+          onFailure(error);
+        }
+      })
+      .finally(() => {
+        const captureStillCurrent = completeReplayScreenshotCapture(
+          screenshotCaptureRef,
+          capture,
+          () => {
+            savingScreenshotRef.current = false;
+            setSavingScreenshot(false);
+          },
+        );
+        if (captureStillCurrent) setScreenshotAction(null);
+        if (
+          captureStillCurrent &&
+          wasPlaying &&
+          replayerRef.current === replayer
+        ) {
+          try {
+            replayer.play(captureAt);
+            setPlaying(true);
+          } catch {
+            setPlaying(false);
+          }
+        }
+      });
+  }
+
+  function saveScreenshot() {
+    runScreenshotAction(
+      "save",
+      (screenshot, filename) =>
+        screenshot.then((blob) => downloadReplayScreenshotBlob(blob, filename)),
+      () => toast.success(t("sessions.screenshotDownloaded")),
+      (error) =>
         toast.error(
           t(
             error instanceof ReplayScreenshotAssetError
               ? "sessions.screenshotUnsupportedAssets"
               : "sessions.screenshotSaveFailed",
           ),
-        );
-      }
-    } finally {
-      const captureStillCurrent = completeReplayScreenshotCapture(
-        screenshotCaptureRef,
-        capture,
-        () => {
-          savingScreenshotRef.current = false;
-          setSavingScreenshot(false);
-        },
-      );
-      if (
-        captureStillCurrent &&
-        wasPlaying &&
-        replayerRef.current === replayer
-      ) {
-        try {
-          replayer.play(captureAt);
-          setPlaying(true);
-        } catch {
-          setPlaying(false);
-        }
-      }
-    }
+        ),
+    );
+  }
+
+  function copyScreenshotToDesign() {
+    runScreenshotAction(
+      "copy",
+      (screenshot, _filename, onClipboardWriteFailure) =>
+        writeReplayScreenshotToClipboard(
+          screenshot,
+          undefined,
+          onClipboardWriteFailure,
+        ),
+      () => toast.success(t("sessions.screenshotCopiedForDesign")),
+      (error) =>
+        toast.error(
+          t(
+            error instanceof ReplayScreenshotAssetError
+              ? "sessions.screenshotCopyUnsupportedAssets"
+              : "sessions.screenshotCopyFailed",
+          ),
+        ),
+    );
   }
 
   const disabled = status !== "ready" || savingScreenshot;
@@ -1224,11 +1286,25 @@ function ReplayPlayer({
               >
                 <IconDownload className="me-1.5 h-4 w-4" />
                 {t(
-                  savingScreenshot
+                  savingScreenshot && screenshotAction === "save"
                     ? "sessions.savingScreenshot"
                     : "sessions.saveScreenshot",
                 )}
               </Button>
+              <Button
+                type="button"
+                variant="outline"
+                size="sm"
+                disabled={disabled}
+                onClick={copyScreenshotToDesign}
+              >
+                <IconCopy className="me-1.5 h-4 w-4" />
+                {t(
+                  savingScreenshot && screenshotAction === "copy"
+                    ? "sessions.copyingScreenshot"
+                    : "sessions.copyScreenshot",
+                )}
+              </Button>
 
               <span className="w-12 text-center font-mono text-xs text-muted-foreground">
                 {formatClock(currentTime)}

package/corpus/templates/analytics/app/pages/sessions/session-replay-screenshot.ts

@@ -15,6 +15,7 @@ const MAX_INLINE_ASSET_BYTES = 32_000_000;
 const MAX_IMAGE_RESPONSE_BYTES = 12_000_000;
 const MAX_SCREENSHOT_DIMENSION = 8_192;
 const MAX_SCREENSHOT_PIXELS = 16_000_000;
+const MAX_CLIPBOARD_PNG_BYTES = 32_000_000;
 const MAX_REPLAY_IFRAME_DEPTH = 8;
 const VIDEO_READY_STATE_HAVE_CURRENT_DATA = 2;
 const REPLAY_SCREENSHOT_MARKER = "data-replay-screenshot-map";
@@ -1179,13 +1180,87 @@ function waitForReplayPaint(signal?: AbortSignal): Promise<void> {
   });
 }
 
-export async function downloadReplayScreenshot(
+export class ReplayScreenshotClipboardError extends Error {
+  constructor() {
+    super("Replay screenshot could not be copied to the clipboard");
+    this.name = "ReplayScreenshotClipboardError";
+  }
+}
+
+export function writeReplayScreenshotToClipboard(
+  screenshot: Blob | Promise<Blob>,
+  clipboard: Pick<Clipboard, "write"> | undefined = globalThis.navigator
+    ?.clipboard,
+  onClipboardWriteFailure?: () => void,
+): Promise<void> {
+  const ClipboardItemConstructor = globalThis.ClipboardItem;
+  const boundedPng = Promise.resolve(screenshot).then((blob) => {
+    if (
+      blob.type !== "image/png" ||
+      blob.size === 0 ||
+      blob.size > MAX_CLIPBOARD_PNG_BYTES
+    ) {
+      throw new ReplayScreenshotClipboardError();
+    }
+    return blob;
+  });
+  const pngResult = boundedPng.then(
+    () => ({ kind: "png-ready" as const }),
+    (error: unknown) => ({ error, kind: "png-failed" as const }),
+  );
+
+  let clipboardWrite: Promise<void>;
+  try {
+    if (!clipboard?.write || !ClipboardItemConstructor) {
+      throw new ReplayScreenshotClipboardError();
+    }
+
+    // Start the clipboard write with the click; the promised PNG can render afterward.
+    const item = new ClipboardItemConstructor({ "image/png": boundedPng });
+    clipboardWrite = Promise.resolve(clipboard.write([item]));
+  } catch (error) {
+    clipboardWrite = Promise.reject(error);
+  }
+
+  const writeResult = clipboardWrite.then(
+    () => ({ kind: "write-succeeded" as const }),
+    () => ({ kind: "write-failed" as const }),
+  );
+
+  return Promise.race([pngResult, writeResult]).then(async (firstResult) => {
+    if (firstResult.kind === "write-failed") {
+      const error = new ReplayScreenshotClipboardError();
+      onClipboardWriteFailure?.();
+      throw error;
+    }
+
+    const finalPngResult =
+      firstResult.kind === "png-ready" || firstResult.kind === "png-failed"
+        ? firstResult
+        : await pngResult;
+    if (finalPngResult.kind === "png-failed") {
+      if (finalPngResult.error instanceof ReplayScreenshotAssetError) {
+        throw finalPngResult.error;
+      }
+      throw new ReplayScreenshotClipboardError();
+    }
+
+    const finalWriteResult =
+      firstResult.kind === "write-succeeded" ? firstResult : await writeResult;
+    if (finalWriteResult.kind === "write-failed") {
+      const error = new ReplayScreenshotClipboardError();
+      onClipboardWriteFailure?.();
+      throw error;
+    }
+  });
+}
+
+export async function captureReplayScreenshot(
   stage: HTMLElement,
   stageRoot: HTMLElement,
   iframe: HTMLIFrameElement,
-  filename: string,
   signal?: AbortSignal,
-): Promise<void> {
+): Promise<Blob> {
   const replayWindow = iframe.contentWindow;
   const replayDocument = iframe.contentDocument;
   if (
@@ -1293,13 +1368,7 @@ export async function downloadReplayScreenshot(
     assertScreenshotDimensions(canvas.width, canvas.height);
     const blob = await canvasToBlob(canvas);
     assertCaptureAvailable();
-
-    const downloadUrl = URL.createObjectURL(blob);
-    const link = document.createElement("a");
-    link.download = filename;
-    link.href = downloadUrl;
-    link.click();
-    window.setTimeout(() => URL.revokeObjectURL(downloadUrl), 1000);
+    return blob;
   } finally {
     if (previousStageFrameMarker === null) {
       iframe.removeAttribute(REPLAY_SCREENSHOT_MARKER);
@@ -1309,6 +1378,34 @@ export async function downloadReplayScreenshot(
   }
 }
 
+export function downloadReplayScreenshotBlob(
+  blob: Blob,
+  filename: string,
+): void {
+  const downloadUrl = URL.createObjectURL(blob);
+  const link = document.createElement("a");
+  link.download = filename;
+  link.href = downloadUrl;
+  link.click();
+  window.setTimeout(() => URL.revokeObjectURL(downloadUrl), 1000);
+}
+
+export async function downloadReplayScreenshot(
+  stage: HTMLElement,
+  stageRoot: HTMLElement,
+  iframe: HTMLIFrameElement,
+  filename: string,
+  signal?: AbortSignal,
+): Promise<void> {
+  const screenshot = await captureReplayScreenshot(
+    stage,
+    stageRoot,
+    iframe,
+    signal,
+  );
+  downloadReplayScreenshotBlob(screenshot, filename);
+}
+
 function assertScreenshotDimensions(width: number, height: number): void {
   if (
     !Number.isSafeInteger(width) ||

package/corpus/templates/analytics/changelog/2026-10-07-session-replay-screenshots-can-be-copied-directly-into-desig.md

@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-10-07
+---
+
+Session replay screenshots can be copied directly into Design.

package/corpus/templates/assets/.agents/skills/actions/references/action-fields.md

@@ -16,6 +16,7 @@ Rules:
 - To override the inference on an unusual action (e.g. a `POST` that only reads), pass `readOnly: true` on the action definition.
 - To let a mutating action run concurrently with other same-turn tool calls, pass `parallelSafe: true`. Only do this when the action is internally concurrency-safe and order-independent (for example, it uses an app-level lock or idempotent upsert semantics). Mutating actions remain serialized by default.
 - If a successful call hands control to the user — it renders a question, an intake form, or anything else the turn must wait on — pass `endsTurn: true` and make it the first or only call in the turn. It stops subsequent model steps and later calls, but cannot undo calls emitted before it. Without it a completion guard sees a turn that legitimately paused as one that failed to finish. `endsTurn: true` also hides the action from MCP, WebMCP, and A2A callers by default (`isActionExposedToExternalAgents` in core `action.ts`) — an external host has no in-app chat to receive the answer on. Pass `mcpTool: true` alongside it only when an external caller can complete the same operation without that answer.
+- MCP hosts read tool annotations to decide how carefully to treat a call. Every MCP catalog advertises declared `mcpAnnotations` (`readOnlyHint`, `destructiveHint`, `openWorldHint`, optional `idempotentHint`); otherwise `/mcp` derives only `readOnlyHint` and an approval-based `destructiveHint`. Declare them on any external write that removes, overwrites, or replaces user content — recoverable Trash included — and mark idempotency-key-guarded writes `idempotentHint: true`.
 
 Agents do NOT need to call `refresh-screen` after a normal action — it's already handled. `refresh-screen` is only needed when the agent mutates data via a path the framework can't see (e.g. writing to an external system the app mirrors) or when the agent wants to pass a `scope` hint for narrower invalidation.
 

package/corpus/templates/brain/.agents/skills/actions/references/action-fields.md

@@ -16,6 +16,7 @@ Rules:
 - To override the inference on an unusual action (e.g. a `POST` that only reads), pass `readOnly: true` on the action definition.
 - To let a mutating action run concurrently with other same-turn tool calls, pass `parallelSafe: true`. Only do this when the action is internally concurrency-safe and order-independent (for example, it uses an app-level lock or idempotent upsert semantics). Mutating actions remain serialized by default.
 - If a successful call hands control to the user — it renders a question, an intake form, or anything else the turn must wait on — pass `endsTurn: true` and make it the first or only call in the turn. It stops subsequent model steps and later calls, but cannot undo calls emitted before it. Without it a completion guard sees a turn that legitimately paused as one that failed to finish. `endsTurn: true` also hides the action from MCP, WebMCP, and A2A callers by default (`isActionExposedToExternalAgents` in core `action.ts`) — an external host has no in-app chat to receive the answer on. Pass `mcpTool: true` alongside it only when an external caller can complete the same operation without that answer.
+- MCP hosts read tool annotations to decide how carefully to treat a call. Every MCP catalog advertises declared `mcpAnnotations` (`readOnlyHint`, `destructiveHint`, `openWorldHint`, optional `idempotentHint`); otherwise `/mcp` derives only `readOnlyHint` and an approval-based `destructiveHint`. Declare them on any external write that removes, overwrites, or replaces user content — recoverable Trash included — and mark idempotency-key-guarded writes `idempotentHint: true`.
 
 Agents do NOT need to call `refresh-screen` after a normal action — it's already handled. `refresh-screen` is only needed when the agent mutates data via a path the framework can't see (e.g. writing to an external system the app mirrors) or when the agent wants to pass a `scope` hint for narrower invalidation.
 

package/corpus/templates/calendar/.agents/skills/actions/references/action-fields.md

@@ -16,6 +16,7 @@ Rules:
 - To override the inference on an unusual action (e.g. a `POST` that only reads), pass `readOnly: true` on the action definition.
 - To let a mutating action run concurrently with other same-turn tool calls, pass `parallelSafe: true`. Only do this when the action is internally concurrency-safe and order-independent (for example, it uses an app-level lock or idempotent upsert semantics). Mutating actions remain serialized by default.
 - If a successful call hands control to the user — it renders a question, an intake form, or anything else the turn must wait on — pass `endsTurn: true` and make it the first or only call in the turn. It stops subsequent model steps and later calls, but cannot undo calls emitted before it. Without it a completion guard sees a turn that legitimately paused as one that failed to finish. `endsTurn: true` also hides the action from MCP, WebMCP, and A2A callers by default (`isActionExposedToExternalAgents` in core `action.ts`) — an external host has no in-app chat to receive the answer on. Pass `mcpTool: true` alongside it only when an external caller can complete the same operation without that answer.
+- MCP hosts read tool annotations to decide how carefully to treat a call. Every MCP catalog advertises declared `mcpAnnotations` (`readOnlyHint`, `destructiveHint`, `openWorldHint`, optional `idempotentHint`); otherwise `/mcp` derives only `readOnlyHint` and an approval-based `destructiveHint`. Declare them on any external write that removes, overwrites, or replaces user content — recoverable Trash included — and mark idempotency-key-guarded writes `idempotentHint: true`.
 
 Agents do NOT need to call `refresh-screen` after a normal action — it's already handled. `refresh-screen` is only needed when the agent mutates data via a path the framework can't see (e.g. writing to an external system the app mirrors) or when the agent wants to pass a `scope` hint for narrower invalidation.
 

package/corpus/templates/chat/.agents/skills/actions/references/action-fields.md

@@ -16,6 +16,7 @@ Rules:
 - To override the inference on an unusual action (e.g. a `POST` that only reads), pass `readOnly: true` on the action definition.
 - To let a mutating action run concurrently with other same-turn tool calls, pass `parallelSafe: true`. Only do this when the action is internally concurrency-safe and order-independent (for example, it uses an app-level lock or idempotent upsert semantics). Mutating actions remain serialized by default.
 - If a successful call hands control to the user — it renders a question, an intake form, or anything else the turn must wait on — pass `endsTurn: true` and make it the first or only call in the turn. It stops subsequent model steps and later calls, but cannot undo calls emitted before it. Without it a completion guard sees a turn that legitimately paused as one that failed to finish. `endsTurn: true` also hides the action from MCP, WebMCP, and A2A callers by default (`isActionExposedToExternalAgents` in core `action.ts`) — an external host has no in-app chat to receive the answer on. Pass `mcpTool: true` alongside it only when an external caller can complete the same operation without that answer.
+- MCP hosts read tool annotations to decide how carefully to treat a call. Every MCP catalog advertises declared `mcpAnnotations` (`readOnlyHint`, `destructiveHint`, `openWorldHint`, optional `idempotentHint`); otherwise `/mcp` derives only `readOnlyHint` and an approval-based `destructiveHint`. Declare them on any external write that removes, overwrites, or replaces user content — recoverable Trash included — and mark idempotency-key-guarded writes `idempotentHint: true`.
 
 Agents do NOT need to call `refresh-screen` after a normal action — it's already handled. `refresh-screen` is only needed when the agent mutates data via a path the framework can't see (e.g. writing to an external system the app mirrors) or when the agent wants to pass a `scope` hint for narrower invalidation.
 

package/corpus/templates/clips/.agents/skills/actions/references/action-fields.md

@@ -16,6 +16,7 @@ Rules:
 - To override the inference on an unusual action (e.g. a `POST` that only reads), pass `readOnly: true` on the action definition.
 - To let a mutating action run concurrently with other same-turn tool calls, pass `parallelSafe: true`. Only do this when the action is internally concurrency-safe and order-independent (for example, it uses an app-level lock or idempotent upsert semantics). Mutating actions remain serialized by default.
 - If a successful call hands control to the user — it renders a question, an intake form, or anything else the turn must wait on — pass `endsTurn: true` and make it the first or only call in the turn. It stops subsequent model steps and later calls, but cannot undo calls emitted before it. Without it a completion guard sees a turn that legitimately paused as one that failed to finish. `endsTurn: true` also hides the action from MCP, WebMCP, and A2A callers by default (`isActionExposedToExternalAgents` in core `action.ts`) — an external host has no in-app chat to receive the answer on. Pass `mcpTool: true` alongside it only when an external caller can complete the same operation without that answer.
+- MCP hosts read tool annotations to decide how carefully to treat a call. Every MCP catalog advertises declared `mcpAnnotations` (`readOnlyHint`, `destructiveHint`, `openWorldHint`, optional `idempotentHint`); otherwise `/mcp` derives only `readOnlyHint` and an approval-based `destructiveHint`. Declare them on any external write that removes, overwrites, or replaces user content — recoverable Trash included — and mark idempotency-key-guarded writes `idempotentHint: true`.
 
 Agents do NOT need to call `refresh-screen` after a normal action — it's already handled. `refresh-screen` is only needed when the agent mutates data via a path the framework can't see (e.g. writing to an external system the app mirrors) or when the agent wants to pass a `scope` hint for narrower invalidation.
 

package/corpus/templates/clips/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable user-facing changes to Clips are documented here. Open it any time
 from the command menu (Cmd+K → "What's new") or from Settings.
 
+## 2026-10-07
+
+### Improved
+
+- Builder.io setup choices now say “Use Builder.io”.
+
+### Fixed
+
+- Clips sizes Settings and recording views correctly while a recording is active.
+
 ## 2026-10-06
 
 ### Fixed

package/corpus/templates/content/.agents/skills/actions/references/action-fields.md

@@ -16,6 +16,7 @@ Rules:
 - To override the inference on an unusual action (e.g. a `POST` that only reads), pass `readOnly: true` on the action definition.
 - To let a mutating action run concurrently with other same-turn tool calls, pass `parallelSafe: true`. Only do this when the action is internally concurrency-safe and order-independent (for example, it uses an app-level lock or idempotent upsert semantics). Mutating actions remain serialized by default.
 - If a successful call hands control to the user — it renders a question, an intake form, or anything else the turn must wait on — pass `endsTurn: true` and make it the first or only call in the turn. It stops subsequent model steps and later calls, but cannot undo calls emitted before it. Without it a completion guard sees a turn that legitimately paused as one that failed to finish. `endsTurn: true` also hides the action from MCP, WebMCP, and A2A callers by default (`isActionExposedToExternalAgents` in core `action.ts`) — an external host has no in-app chat to receive the answer on. Pass `mcpTool: true` alongside it only when an external caller can complete the same operation without that answer.
+- MCP hosts read tool annotations to decide how carefully to treat a call. Every MCP catalog advertises declared `mcpAnnotations` (`readOnlyHint`, `destructiveHint`, `openWorldHint`, optional `idempotentHint`); otherwise `/mcp` derives only `readOnlyHint` and an approval-based `destructiveHint`. Declare them on any external write that removes, overwrites, or replaces user content — recoverable Trash included — and mark idempotency-key-guarded writes `idempotentHint: true`.
 
 Agents do NOT need to call `refresh-screen` after a normal action — it's already handled. `refresh-screen` is only needed when the agent mutates data via a path the framework can't see (e.g. writing to an external system the app mirrors) or when the agent wants to pass a `scope` hint for narrower invalidation.
 

package/corpus/templates/content/.agents/skills/document-editing/SKILL.md

@@ -169,17 +169,23 @@ pnpm action suggest-document-edit --id abc123 \
 
 ### delete-document
 
-Move a document and all its children to Trash. IDs, bodies, hierarchy, and
-collection membership remain intact so the subtree can be restored.
+Move a page and all its sub-pages to Trash. IDs, bodies, hierarchy, and
+collection membership remain intact so the subtree can be restored. Agents pass
+the page's exact `updatedAt` from `<current-screen>` or a fresh read, plus an
+idempotency key. A conflict means the page changed: read it again before
+deciding to trash it. Collection pages use `delete-content-database` instead.
 
 ```bash
-pnpm action delete-document --id abc123
+pnpm action delete-document --id abc123 \
+  --expectedUpdatedAt '<updatedAt>' --idempotencyKey '<uuid>'
 ```
 
-Restore the root subtree, or permanently delete it only after it is in Trash:
+Restore the receipt's `trashRootId` with its `trashedAt` (also listed by
+`list-content-trash`), or permanently delete it only after it is in Trash:
 
 ```bash
-pnpm action restore-document --id abc123
+pnpm action restore-document --id abc123 \
+  --expectedTrashedAt '<trashedAt>' --idempotencyKey '<uuid>'
 pnpm action plan-content-trash-purge --mode selection --documentIds '["abc123"]'
 pnpm action permanently-delete-document --id abc123 --planId '<reviewed plan ID>' --scopeToken '<opaque plan token>'
 ```
@@ -335,7 +341,7 @@ failures stop the run.
 | "What am I looking at?"   | Answer from `<current-screen>` (call `view-screen` only if truncated)             |
 | "Create a page about X"   | `create-document`, then `navigate --documentId <returned id>` and verify with `view-screen` |
 | "Fix a typo / small edit" | ID from `<current-screen>`, `edit-document --id ... --find "old" --replace "new"` |
-| "Delete this page"        | ID from `<current-screen>`, `delete-document --id ...`                            |
+| "Delete this page"        | ID and `updatedAt` from `<current-screen>`, `delete-document --id ... --expectedUpdatedAt ... --idempotencyKey ...` |
 
 ## Common Tasks
 
@@ -346,7 +352,7 @@ failures stop the run.
 | "Find my meeting notes"      | `search-documents --query "meeting notes"`                                          |
 | "Fix a typo / edit a line"   | `view-screen` to get ID, then `edit-document --id ... --find "old" --replace "new"` |
 | "Rewrite this document"      | `view-screen` to get ID, then `update-document --id ... --content ...`              |
-| "Delete this page"           | `view-screen` to get ID, then `delete-document --id ...`                            |
+| "Delete this page"           | `view-screen` for ID and `updatedAt`, then `delete-document` with both and an idempotency key |
 | "Add a sub-page"             | `create-document --title "Sub" --parentId <parentId>`                               |
 | "Show me the document tree"  | `list-documents`                                                                    |
 

package/corpus/templates/content/CHANGELOG.md

@@ -7,6 +7,10 @@ time from the command menu (Cmd+K → "What's new").
 
 ### Fixed
 
+- ChatGPT widgets identify a stalled Content editor instead of keeping its body skeleton onscreen.
+- ChatGPT widgets open document content without a cookie session
+- Content documents now open in ChatGPT widgets with their full body
+- Text two people type at the same spot now reaches the saved page for both of them, so readers and agents see it
 - ChatGPT widget previews show saved document bodies without a Content session.
 - Documents opened in ChatGPT show their saved content right away.
 - ChatGPT widgets show saved document bodies in read-only mode without a Content session.
@@ -14,12 +18,17 @@ time from the command menu (Cmd+K → "What's new").
 
 ## 2026-10-06
 
+### Added
+
+- External agents can now move a page and its sub-pages to recoverable Trash, list Trash, and restore it through Content's MCP tools.
+
 ### Improved
 
 - ChatGPT can open Content document and database editors in the existing workspace, and document links use the right label.
 
 ### Fixed
 
+- Connecting Notion no longer leaves its used authorization code in the address bar.
 - Documents and databases opened from ChatGPT load in the Content editor without a separate sign-in.
 - ChatGPT Content widgets load database views correctly.
 - Reopening a ChatGPT Content widget restores the editor for its saved document or collection.

package/corpus/templates/content/actions/_database-setup-mutation.ts

@@ -148,8 +148,7 @@ export async function claimSetupIntent(
   payload: unknown,
 ): Promise<Claim> {
   const email = getRequestUserEmail()?.trim().toLowerCase();
-  if (!email)
-    setupError("UNAUTHORIZED", "Sign in to change a Content database.", 401);
+  if (!email) setupError("UNAUTHORIZED", "Sign in to change Content.", 401);
   const payloadDigest = digest(payload);
   const table = schema.contentDatabaseSetupReceipts;
   const inserted = await tx
@@ -177,14 +176,11 @@ export async function claimSetupIntent(
     )
     .returning();
   if (!claim)
-    setupError(
-      "RECEIPT_MISMATCH",
-      "The database operation claim could not be read.",
-    );
+    setupError("RECEIPT_MISMATCH", "The operation claim could not be read.");
   if (claim.payloadDigest !== payloadDigest)
     setupError(
       "IDEMPOTENCY_KEY_REUSED",
-      "This key was already used for a different database operation. Use the original payload to retry it.",
+      "This key was already used for a different Content operation. Use the original payload to retry it.",
     );
   if (inserted.length === 0 && claim.resultJson === null)
     setupError(