@agent-native/core-corpus 0.203.2-nightly-20261007213109 → 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: 11353
+- 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,7 +15,9 @@ 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";
 
 type ReplayImageResource = { document: Document; url: string };
@@ -567,8 +569,12 @@ function imageResourcesInDocuments(
       (element): element is HTMLVideoElement => element.tagName === "VIDEO",
     )) {
       if (!isElementRendered(video, current)) continue;
-      if (
-        video.poster ||
+      if (video.controls) throw new ReplayScreenshotAssetError();
+      if (hasCurrentVideoFrame(video)) {
+        assertVideoFrameReadable(video);
+      } else if (video.poster) {
+        addUrl(video.poster, current.baseURI, current);
+      } else if (
         video.currentSrc ||
         video.hasAttribute("src") ||
         video.srcObject ||
@@ -631,6 +637,68 @@ function imageResourcesInDocuments(
   );
 }
 
+function hasCurrentVideoFrame(video: HTMLVideoElement): boolean {
+  return (
+    video.readyState >= VIDEO_READY_STATE_HAVE_CURRENT_DATA &&
+    video.videoWidth > 0 &&
+    video.videoHeight > 0
+  );
+}
+
+function assertVideoFrameReadable(video: HTMLVideoElement): void {
+  const probe = video.ownerDocument.createElement("canvas");
+  probe.width = 1;
+  probe.height = 1;
+  const context = probe.getContext("2d");
+  if (!context) throw new ReplayScreenshotAssetError();
+  try {
+    context.drawImage(video, 0, 0, 1, 1);
+    context.getImageData(0, 0, 1, 1);
+  } catch {
+    throw new ReplayScreenshotAssetError();
+  }
+}
+
+function copyComputedStyles(
+  source: Element,
+  target: HTMLElement,
+  view: Window,
+): void {
+  const styles = view.getComputedStyle(source);
+  for (let index = 0; index < styles.length; index += 1) {
+    const property = styles.item(index);
+    target.style.setProperty(
+      property,
+      styles.getPropertyValue(property),
+      styles.getPropertyPriority(property),
+    );
+  }
+}
+
+function html2CanvasVideoClone(
+  video: HTMLVideoElement,
+  clonesByMarker: Map<string, Element>,
+): Element | undefined {
+  const parent = video.parentElement;
+  const parentMarker = parent?.getAttribute(REPLAY_SCREENSHOT_MARKER);
+  const clonedParent = parentMarker ? clonesByMarker.get(parentMarker) : null;
+  if (!parent || !clonedParent) return undefined;
+
+  const originalChildren = Array.from(parent.children).filter(
+    (element) => element.tagName !== "SCRIPT",
+  );
+  const videoIndex = originalChildren.indexOf(video);
+  if (videoIndex === -1) return undefined;
+
+  const clonedChildren = Array.from(clonedParent.children).filter(
+    (element) =>
+      element.tagName !== "SCRIPT" &&
+      element.localName !== "html2canvaspseudoelement",
+  );
+  const clone = clonedChildren[videoIndex];
+  return clone?.tagName === "CANVAS" ? clone : undefined;
+}
+
 function imageUrlsInDocuments(documents: Document[]): string[] {
   return [
     ...new Set(imageResourcesInDocuments(documents).map(({ url }) => url)),
@@ -859,6 +927,17 @@ export function inlineReplayAssets(
     }
   }
 
+  for (const originalElement of originalElements) {
+    if (originalElement.tagName !== "VIDEO") continue;
+    const marker = originalElement.getAttribute(REPLAY_SCREENSHOT_MARKER);
+    if (!marker || clonesByMarker.has(marker)) continue;
+    const clone = html2CanvasVideoClone(
+      originalElement as HTMLVideoElement,
+      clonesByMarker,
+    );
+    if (clone) clonesByMarker.set(marker, clone);
+  }
+
   for (const [documentIndex, original] of originalDocuments.entries()) {
     const rootMarker = original.documentElement.getAttribute(
       REPLAY_SCREENSHOT_MARKER,
@@ -878,9 +957,13 @@ export function inlineReplayAssets(
       if (originalElement.tagName === "SCRIPT") continue;
       const marker = originalElement.getAttribute(REPLAY_SCREENSHOT_MARKER);
       let clonedElement = marker ? clonesByMarker.get(marker) : undefined;
+      const isHtml2CanvasVideoClone =
+        originalElement.tagName === "VIDEO" &&
+        clonedElement?.tagName === "CANVAS";
       if (
         !clonedElement ||
-        (originalElement.tagName !== clonedElement.tagName &&
+        (!isHtml2CanvasVideoClone &&
+          originalElement.tagName !== clonedElement.tagName &&
           !originalElement.localName.includes("-"))
       ) {
         throw new ReplayScreenshotAssetError();
@@ -894,21 +977,34 @@ export function inlineReplayAssets(
           const image = cloned.createElement("img");
           image.alt = "";
           image.src = screenshot;
-          const frameStyles = view.getComputedStyle(originalElement);
-          for (let index = 0; index < frameStyles.length; index += 1) {
-            const property = frameStyles.item(index);
-            image.style.setProperty(
-              property,
-              frameStyles.getPropertyValue(property),
-              frameStyles.getPropertyPriority(property),
-            );
-          }
+          copyComputedStyles(originalElement, image, view);
           image.style.setProperty("object-fit", "fill", "important");
           clonedElement.replaceWith(image);
           clonedElement = image;
           if (marker) clonesByMarker.set(marker, image);
         }
       }
+      if (originalElement.tagName === "VIDEO") {
+        const video = originalElement as HTMLVideoElement;
+        if (!hasCurrentVideoFrame(video) && video.poster) {
+          const posterUrl = new URL(video.poster, original.baseURI).href;
+          const poster = documentAssets.get(posterUrl);
+          if (!poster) throw new ReplayScreenshotAssetError();
+          const image = cloned.createElement("img");
+          image.alt = "";
+          image.src = poster;
+          const videoStyles = view.getComputedStyle(video);
+          copyComputedStyles(video, image, view);
+          image.style.setProperty(
+            "object-fit",
+            videoStyles.objectFit || "contain",
+            "important",
+          );
+          clonedElement.replaceWith(image);
+          clonedElement = image;
+          if (marker) clonesByMarker.set(marker, image);
+        }
+      }
       if (originalElement instanceof view.HTMLImageElement) {
         const source = originalElement.currentSrc || originalElement.src;
         const dataUrl = documentAssets.get(source);
@@ -1084,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 (
@@ -1198,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);
@@ -1214,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-screenshot-export-captures-readable-video-fra.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-10-07
+---
+
+Session replay screenshot export captures readable video frames and safe poster images.

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