@agent-native/core-corpus 0.219.0 → 0.220.0-nightly-20261023212848

package/corpus/README.md

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

package/corpus/templates/analytics/.agents/skills/actions/SKILL.md

@@ -172,6 +172,7 @@ Everything else — CRUD, settings, search, list/detail reads, auth state, anyth
 - **Do** signal failure by throwing, using `fail()` for expected caller-readable failures. Never return `{ error: ... }` as a failure result: a normal return is treated as a successful action. Reserve bare errors for unexpected internal faults.
 - **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser and to agents; unexpected errors become a generic 500. Reserve bare throws for internal faults.
 - **Do** give `fail()` the status that matches the cause: it defaults to `400`, and `useActionQuery` retries only `429`, `502`, `503`, and `504`. Mutations do not retry; use transient statuses only for retryable failures.
+- **Do** throw `NoWriteError(message, { errorCode, statusCode })` instead of `fail()` for a rejection raised before the action's first write, such as an edit that matches nothing or a missing target. The agent then retries with corrected arguments instead of stopping on a write whose outcome is unknown. Throw it only before the first write: the framework rejects the claim when a nested write action ran, but it cannot see the handler's own writes.
 - **Do** render `actionErrorMessage(error) ?? yourCopy` in UI, never bare `error.message`. The message keeps an `Action <name> failed:` prefix that belongs in a console, so a toast built from it reads "Action update-brand-kit failed: That name is taken." The helper returns only what the action wrote, and `undefined` when nothing did (network drop, proxy HTML page), which is why the fallback is not optional.
 - **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP. `details` follow as an `Error details: {...}` JSON line, and as `structuredContent.error` over MCP, capped at 2,000 characters, so keep them to what the agent acts on next: ids, limits, field names. The status never reaches either.
 - **Don't** re-export actions as REST — `/_agent-native/actions/:name` is already the REST surface; duplicating it under `/api/*` hides the operation from agents.

package/corpus/templates/analytics/.agents/skills/external-agents/references/mcp-apps-embedding.md

@@ -162,8 +162,15 @@ actions for Forms, Content, Clips, Slides, and Design. The action should return
 concise structured content plus the link; it should not dump large catalogs or
 HTML.
 
-Compatibility target: build to the standard once, not per-client shims. MCP
-Apps-capable hosts should include Claude/Claude Desktop/Claude Code, ChatGPT
-custom MCP apps, VS Code GitHub Copilot, Goose, Postman, MCPJam, Cursor, and
-any future host that follows the extension negotiation. Host support varies by
-plan, release channel, and client version, so keep the deep link fallback.
+Compatibility target: build to the standard once, not per-client shims.
+Hosts that render MCP Apps inline today include Claude chat on web, desktop, and
+mobile, plus the Claude Desktop Code tab; ChatGPT; VS Code GitHub Copilot (1.109+);
+Microsoft 365 Copilot; Cursor (2.6+); Goose; Postman; MCPJam; Codex Desktop (26.616+);
+and T3 Code (in Codex threads). Desktop Code rendering is observed in
+[widget bug reports](https://github.com/anthropics/claude-code/issues/103809).
+Treat the Claude Code terminal, Cowork, and Code on claude.ai web as link-out hosts.
+[Cowork doesn't declare MCP Apps yet](https://github.com/anthropics/claude-code/issues/103924),
+and using it on the same connector can make inline apps disappear in Chat until
+you reconnect the connector. Host support varies by plan, release channel, and client version,
+so keep the deep link fallback. See the community-maintained
+[MCP client matrix](https://modelcontextprotocol.io/extensions/client-matrix).

package/corpus/templates/analytics/.deploy-tmp/agent-native-provided-plugins.mjs

@@ -0,0 +1,10 @@
+// AUTO-GENERATED by @agent-native/core deploy build
+import { markDefaultPluginProvided } from "@agent-native/core/server/edge";
+
+const pluginStems = ["agent-chat","analytics-alert-jobs","analytics-rollup-backfill-jobs","auth","collab","config","content-metrics-collection-jobs","core-routes","creative-context","dashboard-report-jobs","db","feature-flags","labs","onboarding","otel","session-replay-retention-jobs","transactional-emails","uptime-monitor-jobs"];
+
+export default function markBuildDiscoveredPlugins(nitroApp) {
+  for (const stem of pluginStems) {
+    markDefaultPluginProvided(nitroApp, stem);
+  }
+}

package/corpus/templates/assets/.agents/skills/actions/SKILL.md

@@ -172,6 +172,7 @@ Everything else — CRUD, settings, search, list/detail reads, auth state, anyth
 - **Do** signal failure by throwing, using `fail()` for expected caller-readable failures. Never return `{ error: ... }` as a failure result: a normal return is treated as a successful action. Reserve bare errors for unexpected internal faults.
 - **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser and to agents; unexpected errors become a generic 500. Reserve bare throws for internal faults.
 - **Do** give `fail()` the status that matches the cause: it defaults to `400`, and `useActionQuery` retries only `429`, `502`, `503`, and `504`. Mutations do not retry; use transient statuses only for retryable failures.
+- **Do** throw `NoWriteError(message, { errorCode, statusCode })` instead of `fail()` for a rejection raised before the action's first write, such as an edit that matches nothing or a missing target. The agent then retries with corrected arguments instead of stopping on a write whose outcome is unknown. Throw it only before the first write: the framework rejects the claim when a nested write action ran, but it cannot see the handler's own writes.
 - **Do** render `actionErrorMessage(error) ?? yourCopy` in UI, never bare `error.message`. The message keeps an `Action <name> failed:` prefix that belongs in a console, so a toast built from it reads "Action update-brand-kit failed: That name is taken." The helper returns only what the action wrote, and `undefined` when nothing did (network drop, proxy HTML page), which is why the fallback is not optional.
 - **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP. `details` follow as an `Error details: {...}` JSON line, and as `structuredContent.error` over MCP, capped at 2,000 characters, so keep them to what the agent acts on next: ids, limits, field names. The status never reaches either.
 - **Don't** re-export actions as REST — `/_agent-native/actions/:name` is already the REST surface; duplicating it under `/api/*` hides the operation from agents.

package/corpus/templates/assets/.agents/skills/external-agents/references/mcp-apps-embedding.md

@@ -162,8 +162,15 @@ actions for Forms, Content, Clips, Slides, and Design. The action should return
 concise structured content plus the link; it should not dump large catalogs or
 HTML.
 
-Compatibility target: build to the standard once, not per-client shims. MCP
-Apps-capable hosts should include Claude/Claude Desktop/Claude Code, ChatGPT
-custom MCP apps, VS Code GitHub Copilot, Goose, Postman, MCPJam, Cursor, and
-any future host that follows the extension negotiation. Host support varies by
-plan, release channel, and client version, so keep the deep link fallback.
+Compatibility target: build to the standard once, not per-client shims.
+Hosts that render MCP Apps inline today include Claude chat on web, desktop, and
+mobile, plus the Claude Desktop Code tab; ChatGPT; VS Code GitHub Copilot (1.109+);
+Microsoft 365 Copilot; Cursor (2.6+); Goose; Postman; MCPJam; Codex Desktop (26.616+);
+and T3 Code (in Codex threads). Desktop Code rendering is observed in
+[widget bug reports](https://github.com/anthropics/claude-code/issues/103809).
+Treat the Claude Code terminal, Cowork, and Code on claude.ai web as link-out hosts.
+[Cowork doesn't declare MCP Apps yet](https://github.com/anthropics/claude-code/issues/103924),
+and using it on the same connector can make inline apps disappear in Chat until
+you reconnect the connector. Host support varies by plan, release channel, and client version,
+so keep the deep link fallback. See the community-maintained
+[MCP client matrix](https://modelcontextprotocol.io/extensions/client-matrix).

package/corpus/templates/assets/.deploy-tmp/agent-native-provided-plugins.mjs

@@ -0,0 +1,10 @@
+// AUTO-GENERATED by @agent-native/core deploy build
+import { markDefaultPluginProvided } from "@agent-native/core/server/edge";
+
+const pluginStems = ["agent-chat","auth","creative-context","db","labs","onboarding","otel"];
+
+export default function markBuildDiscoveredPlugins(nitroApp) {
+  for (const stem of pluginStems) {
+    markDefaultPluginProvided(nitroApp, stem);
+  }
+}

package/corpus/templates/brain/.agents/skills/actions/SKILL.md

@@ -172,6 +172,7 @@ Everything else — CRUD, settings, search, list/detail reads, auth state, anyth
 - **Do** signal failure by throwing, using `fail()` for expected caller-readable failures. Never return `{ error: ... }` as a failure result: a normal return is treated as a successful action. Reserve bare errors for unexpected internal faults.
 - **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser and to agents; unexpected errors become a generic 500. Reserve bare throws for internal faults.
 - **Do** give `fail()` the status that matches the cause: it defaults to `400`, and `useActionQuery` retries only `429`, `502`, `503`, and `504`. Mutations do not retry; use transient statuses only for retryable failures.
+- **Do** throw `NoWriteError(message, { errorCode, statusCode })` instead of `fail()` for a rejection raised before the action's first write, such as an edit that matches nothing or a missing target. The agent then retries with corrected arguments instead of stopping on a write whose outcome is unknown. Throw it only before the first write: the framework rejects the claim when a nested write action ran, but it cannot see the handler's own writes.
 - **Do** render `actionErrorMessage(error) ?? yourCopy` in UI, never bare `error.message`. The message keeps an `Action <name> failed:` prefix that belongs in a console, so a toast built from it reads "Action update-brand-kit failed: That name is taken." The helper returns only what the action wrote, and `undefined` when nothing did (network drop, proxy HTML page), which is why the fallback is not optional.
 - **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP. `details` follow as an `Error details: {...}` JSON line, and as `structuredContent.error` over MCP, capped at 2,000 characters, so keep them to what the agent acts on next: ids, limits, field names. The status never reaches either.
 - **Don't** re-export actions as REST — `/_agent-native/actions/:name` is already the REST surface; duplicating it under `/api/*` hides the operation from agents.

package/corpus/templates/brain/.agents/skills/external-agents/references/mcp-apps-embedding.md

@@ -162,8 +162,15 @@ actions for Forms, Content, Clips, Slides, and Design. The action should return
 concise structured content plus the link; it should not dump large catalogs or
 HTML.
 
-Compatibility target: build to the standard once, not per-client shims. MCP
-Apps-capable hosts should include Claude/Claude Desktop/Claude Code, ChatGPT
-custom MCP apps, VS Code GitHub Copilot, Goose, Postman, MCPJam, Cursor, and
-any future host that follows the extension negotiation. Host support varies by
-plan, release channel, and client version, so keep the deep link fallback.
+Compatibility target: build to the standard once, not per-client shims.
+Hosts that render MCP Apps inline today include Claude chat on web, desktop, and
+mobile, plus the Claude Desktop Code tab; ChatGPT; VS Code GitHub Copilot (1.109+);
+Microsoft 365 Copilot; Cursor (2.6+); Goose; Postman; MCPJam; Codex Desktop (26.616+);
+and T3 Code (in Codex threads). Desktop Code rendering is observed in
+[widget bug reports](https://github.com/anthropics/claude-code/issues/103809).
+Treat the Claude Code terminal, Cowork, and Code on claude.ai web as link-out hosts.
+[Cowork doesn't declare MCP Apps yet](https://github.com/anthropics/claude-code/issues/103924),
+and using it on the same connector can make inline apps disappear in Chat until
+you reconnect the connector. Host support varies by plan, release channel, and client version,
+so keep the deep link fallback. See the community-maintained
+[MCP client matrix](https://modelcontextprotocol.io/extensions/client-matrix).

package/corpus/templates/brain/.deploy-tmp/agent-native-provided-plugins.mjs

@@ -0,0 +1,10 @@
+// AUTO-GENERATED by @agent-native/core deploy build
+import { markDefaultPluginProvided } from "@agent-native/core/server/edge";
+
+const pluginStems = ["agent-chat","auth","brain-jobs","core-routes","db","otel"];
+
+export default function markBuildDiscoveredPlugins(nitroApp) {
+  for (const stem of pluginStems) {
+    markDefaultPluginProvided(nitroApp, stem);
+  }
+}

package/corpus/templates/calendar/.agents/skills/actions/SKILL.md

@@ -172,6 +172,7 @@ Everything else — CRUD, settings, search, list/detail reads, auth state, anyth
 - **Do** signal failure by throwing, using `fail()` for expected caller-readable failures. Never return `{ error: ... }` as a failure result: a normal return is treated as a successful action. Reserve bare errors for unexpected internal faults.
 - **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser and to agents; unexpected errors become a generic 500. Reserve bare throws for internal faults.
 - **Do** give `fail()` the status that matches the cause: it defaults to `400`, and `useActionQuery` retries only `429`, `502`, `503`, and `504`. Mutations do not retry; use transient statuses only for retryable failures.
+- **Do** throw `NoWriteError(message, { errorCode, statusCode })` instead of `fail()` for a rejection raised before the action's first write, such as an edit that matches nothing or a missing target. The agent then retries with corrected arguments instead of stopping on a write whose outcome is unknown. Throw it only before the first write: the framework rejects the claim when a nested write action ran, but it cannot see the handler's own writes.
 - **Do** render `actionErrorMessage(error) ?? yourCopy` in UI, never bare `error.message`. The message keeps an `Action <name> failed:` prefix that belongs in a console, so a toast built from it reads "Action update-brand-kit failed: That name is taken." The helper returns only what the action wrote, and `undefined` when nothing did (network drop, proxy HTML page), which is why the fallback is not optional.
 - **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP. `details` follow as an `Error details: {...}` JSON line, and as `structuredContent.error` over MCP, capped at 2,000 characters, so keep them to what the agent acts on next: ids, limits, field names. The status never reaches either.
 - **Don't** re-export actions as REST — `/_agent-native/actions/:name` is already the REST surface; duplicating it under `/api/*` hides the operation from agents.

package/corpus/templates/calendar/.agents/skills/external-agents/references/mcp-apps-embedding.md

@@ -162,8 +162,15 @@ actions for Forms, Content, Clips, Slides, and Design. The action should return
 concise structured content plus the link; it should not dump large catalogs or
 HTML.
 
-Compatibility target: build to the standard once, not per-client shims. MCP
-Apps-capable hosts should include Claude/Claude Desktop/Claude Code, ChatGPT
-custom MCP apps, VS Code GitHub Copilot, Goose, Postman, MCPJam, Cursor, and
-any future host that follows the extension negotiation. Host support varies by
-plan, release channel, and client version, so keep the deep link fallback.
+Compatibility target: build to the standard once, not per-client shims.
+Hosts that render MCP Apps inline today include Claude chat on web, desktop, and
+mobile, plus the Claude Desktop Code tab; ChatGPT; VS Code GitHub Copilot (1.109+);
+Microsoft 365 Copilot; Cursor (2.6+); Goose; Postman; MCPJam; Codex Desktop (26.616+);
+and T3 Code (in Codex threads). Desktop Code rendering is observed in
+[widget bug reports](https://github.com/anthropics/claude-code/issues/103809).
+Treat the Claude Code terminal, Cowork, and Code on claude.ai web as link-out hosts.
+[Cowork doesn't declare MCP Apps yet](https://github.com/anthropics/claude-code/issues/103924),
+and using it on the same connector can make inline apps disappear in Chat until
+you reconnect the connector. Host support varies by plan, release channel, and client version,
+so keep the deep link fallback. See the community-maintained
+[MCP client matrix](https://modelcontextprotocol.io/extensions/client-matrix).

package/corpus/templates/calendar/.deploy-tmp/agent-native-provided-plugins.mjs

@@ -0,0 +1,10 @@
+// AUTO-GENERATED by @agent-native/core deploy build
+import { markDefaultPluginProvided } from "@agent-native/core/server/edge";
+
+const pluginStems = ["agent-chat","auth","core-routes","db","event-rules","oauth-refresh","otel","transactional-emails"];
+
+export default function markBuildDiscoveredPlugins(nitroApp) {
+  for (const stem of pluginStems) {
+    markDefaultPluginProvided(nitroApp, stem);
+  }
+}

package/corpus/templates/chat/.agents/skills/actions/SKILL.md

@@ -172,6 +172,7 @@ Everything else — CRUD, settings, search, list/detail reads, auth state, anyth
 - **Do** signal failure by throwing, using `fail()` for expected caller-readable failures. Never return `{ error: ... }` as a failure result: a normal return is treated as a successful action. Reserve bare errors for unexpected internal faults.
 - **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser and to agents; unexpected errors become a generic 500. Reserve bare throws for internal faults.
 - **Do** give `fail()` the status that matches the cause: it defaults to `400`, and `useActionQuery` retries only `429`, `502`, `503`, and `504`. Mutations do not retry; use transient statuses only for retryable failures.
+- **Do** throw `NoWriteError(message, { errorCode, statusCode })` instead of `fail()` for a rejection raised before the action's first write, such as an edit that matches nothing or a missing target. The agent then retries with corrected arguments instead of stopping on a write whose outcome is unknown. Throw it only before the first write: the framework rejects the claim when a nested write action ran, but it cannot see the handler's own writes.
 - **Do** render `actionErrorMessage(error) ?? yourCopy` in UI, never bare `error.message`. The message keeps an `Action <name> failed:` prefix that belongs in a console, so a toast built from it reads "Action update-brand-kit failed: That name is taken." The helper returns only what the action wrote, and `undefined` when nothing did (network drop, proxy HTML page), which is why the fallback is not optional.
 - **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP. `details` follow as an `Error details: {...}` JSON line, and as `structuredContent.error` over MCP, capped at 2,000 characters, so keep them to what the agent acts on next: ids, limits, field names. The status never reaches either.
 - **Don't** re-export actions as REST — `/_agent-native/actions/:name` is already the REST surface; duplicating it under `/api/*` hides the operation from agents.

package/corpus/templates/chat/.deploy-tmp/agent-native-provided-plugins.mjs

@@ -0,0 +1,10 @@
+// AUTO-GENERATED by @agent-native/core deploy build
+import { markDefaultPluginProvided } from "@agent-native/core/server/edge";
+
+const pluginStems = ["agent-chat","auth","otel"];
+
+export default function markBuildDiscoveredPlugins(nitroApp) {
+  for (const stem of pluginStems) {
+    markDefaultPluginProvided(nitroApp, stem);
+  }
+}

package/corpus/templates/clips/.agents/skills/actions/SKILL.md

@@ -172,6 +172,7 @@ Everything else — CRUD, settings, search, list/detail reads, auth state, anyth
 - **Do** signal failure by throwing, using `fail()` for expected caller-readable failures. Never return `{ error: ... }` as a failure result: a normal return is treated as a successful action. Reserve bare errors for unexpected internal faults.
 - **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser and to agents; unexpected errors become a generic 500. Reserve bare throws for internal faults.
 - **Do** give `fail()` the status that matches the cause: it defaults to `400`, and `useActionQuery` retries only `429`, `502`, `503`, and `504`. Mutations do not retry; use transient statuses only for retryable failures.
+- **Do** throw `NoWriteError(message, { errorCode, statusCode })` instead of `fail()` for a rejection raised before the action's first write, such as an edit that matches nothing or a missing target. The agent then retries with corrected arguments instead of stopping on a write whose outcome is unknown. Throw it only before the first write: the framework rejects the claim when a nested write action ran, but it cannot see the handler's own writes.
 - **Do** render `actionErrorMessage(error) ?? yourCopy` in UI, never bare `error.message`. The message keeps an `Action <name> failed:` prefix that belongs in a console, so a toast built from it reads "Action update-brand-kit failed: That name is taken." The helper returns only what the action wrote, and `undefined` when nothing did (network drop, proxy HTML page), which is why the fallback is not optional.
 - **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP. `details` follow as an `Error details: {...}` JSON line, and as `structuredContent.error` over MCP, capped at 2,000 characters, so keep them to what the agent acts on next: ids, limits, field names. The status never reaches either.
 - **Don't** re-export actions as REST — `/_agent-native/actions/:name` is already the REST surface; duplicating it under `/api/*` hides the operation from agents.

package/corpus/templates/clips/.agents/skills/external-agents/references/mcp-apps-embedding.md

@@ -162,8 +162,15 @@ actions for Forms, Content, Clips, Slides, and Design. The action should return
 concise structured content plus the link; it should not dump large catalogs or
 HTML.
 
-Compatibility target: build to the standard once, not per-client shims. MCP
-Apps-capable hosts should include Claude/Claude Desktop/Claude Code, ChatGPT
-custom MCP apps, VS Code GitHub Copilot, Goose, Postman, MCPJam, Cursor, and
-any future host that follows the extension negotiation. Host support varies by
-plan, release channel, and client version, so keep the deep link fallback.
+Compatibility target: build to the standard once, not per-client shims.
+Hosts that render MCP Apps inline today include Claude chat on web, desktop, and
+mobile, plus the Claude Desktop Code tab; ChatGPT; VS Code GitHub Copilot (1.109+);
+Microsoft 365 Copilot; Cursor (2.6+); Goose; Postman; MCPJam; Codex Desktop (26.616+);
+and T3 Code (in Codex threads). Desktop Code rendering is observed in
+[widget bug reports](https://github.com/anthropics/claude-code/issues/103809).
+Treat the Claude Code terminal, Cowork, and Code on claude.ai web as link-out hosts.
+[Cowork doesn't declare MCP Apps yet](https://github.com/anthropics/claude-code/issues/103924),
+and using it on the same connector can make inline apps disappear in Chat until
+you reconnect the connector. Host support varies by plan, release channel, and client version,
+so keep the deep link fallback. See the community-maintained
+[MCP client matrix](https://modelcontextprotocol.io/extensions/client-matrix).

package/corpus/templates/clips/.deploy-tmp/agent-native-provided-plugins.mjs

@@ -0,0 +1,10 @@
+// AUTO-GENERATED by @agent-native/core deploy build
+import { markDefaultPluginProvided } from "@agent-native/core/server/edge";
+
+const pluginStems = ["agent-chat","auth","calendar-jobs","config","core-routes","db","feature-flags","labs","onboarding","onboarding-calendar","otel","transactional-email-catalog"];
+
+export default function markBuildDiscoveredPlugins(nitroApp) {
+  for (const stem of pluginStems) {
+    markDefaultPluginProvided(nitroApp, stem);
+  }
+}

package/corpus/templates/clips/app/components/recorder/storage-setup-card.tsx

@@ -31,10 +31,11 @@ import {
 // success should finish this card's setup; a connection made long after the
 // cancel belongs to something else.
 const CANCELLED_SETUP_RECOVERY_MS = 60_000;
+// The custom-keys form finishes in another tab with no signal back, so a
+// status read on leaving or returning credits it only this long after it was
+// opened; storage set up later belongs to something else.
+const CUSTOM_KEYS_CREDIT_WINDOW_MS = 15 * 60_000;
 
-// The S3 path finishes in settings, outside this card, so only the choice is
-// recorded here; a later `recording_started.storage_connected` shows whether
-// it landed.
 function trackStorageStep(
   name:
     | "onboarding_step_viewed"
@@ -66,6 +67,8 @@ export interface StorageSetupCardProps {
    */
   recordingAttemptId?: string;
   outputId?: string;
+  /** Why the host is showing the card, recorded on every step event. */
+  setupReason?: string;
 }
 
 export function StorageSetupCard({
@@ -79,6 +82,7 @@ export function StorageSetupCard({
   connectFlow = "file_upload",
   recordingAttemptId,
   outputId,
+  setupReason,
 }: StorageSetupCardProps) {
   const t = useT();
   const storageSetupHref = useStorageSetupHref();
@@ -100,6 +104,9 @@ export function StorageSetupCard({
   const connectRequestedRef = useRef(false);
   const connectIntentExpiresAtRef = useRef<number | null>(null);
   const [stepViewId] = useState(createOnboardingCorrelationId);
+  // Fixed for the showing: the host's status can change while the card is up,
+  // and every event under one step_view_id must agree on why it showed.
+  const [viewSetupReason] = useState(setupReason);
   const stepProperties = useMemo(
     () => ({
       flow: connectSource,
@@ -108,8 +115,69 @@ export function StorageSetupCard({
         ? { recording_attempt_id: recordingAttemptId }
         : {}),
       ...(outputId ? { output_id: outputId } : {}),
+      ...(viewSetupReason ? { setup_reason: viewSetupReason } : {}),
     }),
-    [connectSource, stepViewId, recordingAttemptId, outputId],
+    [connectSource, stepViewId, recordingAttemptId, outputId, viewSetupReason],
+  );
+  const stepPropertiesRef = useRef(stepProperties);
+  stepPropertiesRef.current = stepProperties;
+  const builderHandedOffRef = useRef(false);
+  const skippedRef = useRef(false);
+  const customKeysOpenedAtRef = useRef<number | null>(null);
+  const customKeysOpenedRecently = useCallback(() => {
+    const openedAt = customKeysOpenedAtRef.current;
+    return (
+      openedAt !== null && Date.now() - openedAt <= CUSTOM_KEYS_CREDIT_WINDOW_MS
+    );
+  }, []);
+  const completionTrackedRef = useRef(false);
+  const returnReadInFlightRef = useRef(false);
+  const storageBeforeSetupRef = useRef<Promise<
+    { status: VideoStorageStatus } | { error: unknown }
+  > | null>(null);
+  const readStorageBeforeSetup = useCallback(() => {
+    storageBeforeSetupRef.current ??= fetchVideoStorageStatus({
+      timeoutMs: 10_000,
+    }).then(
+      (status) => ({ status }),
+      (error: unknown) => ({ error }),
+    );
+  }, []);
+
+  // The route hosting this card can unmount it the moment the shared storage
+  // status reads configured, before this card's poll sees it, so the unmount
+  // path below reads the status once more and records through this too.
+  // Only a change to the workspace's own storage completes this step: free
+  // hosted clips also read as configured, and own storage that was already
+  // there at the showing's first setup click was not set up by this card.
+  // The read of storage before setup must start before any setup request
+  // can, since one-request account activation can finish before a read sent
+  // with it.
+  const trackCompletedIfConfigured = useCallback(
+    (status: VideoStorageStatus) => {
+      const before = storageBeforeSetupRef.current;
+      if (status.mode !== "own" || !before || completionTrackedRef.current) {
+        return;
+      }
+      // Claimed before the wait, so reads landing together record once.
+      completionTrackedRef.current = true;
+      void before.then((read) => {
+        if ("error" in read) {
+          console.warn(
+            "[storage-setup] storage before setup could not be read:",
+            read.error,
+          );
+          return;
+        }
+        if (read.status.mode === "own" || skippedRef.current) return;
+        const methodId = status.activeProvider?.id;
+        trackStorageStep("onboarding_step_completed", {
+          ...stepPropertiesRef.current,
+          ...(methodId ? { method_id: methodId } : {}),
+        });
+      });
+    },
+    [],
   );
 
   const clearConfiguredTimeout = useCallback(() => {
@@ -177,10 +245,7 @@ export function StorageSetupCard({
           stop();
           setConnecting(false);
           setConnected(true);
-          trackStorageStep("onboarding_step_completed", {
-            ...stepProperties,
-            method_id: "builder",
-          });
+          trackCompletedIfConfigured(status);
           clearConfiguredTimeout();
           configuredTimeoutRef.current = setTimeout(() => {
             configuredTimeoutRef.current = null;
@@ -211,9 +276,9 @@ export function StorageSetupCard({
   }, [
     clearConfiguredTimeout,
     onConfigured,
-    stepProperties,
     stopVisibilityHandler,
     t,
+    trackCompletedIfConfigured,
   ]);
 
   const handleBuilderConnected = useCallback(() => {
@@ -222,6 +287,7 @@ export function StorageSetupCard({
     connectRequestedRef.current = false;
     connectIntentExpiresAtRef.current = null;
     if (expiresAt !== null && Date.now() > expiresAt) return;
+    builderHandedOffRef.current = true;
     startFileUploadPoll();
   }, [startFileUploadPoll]);
 
@@ -269,6 +335,7 @@ export function StorageSetupCard({
         setStatusIssue("connect-not-allowed");
         return;
       }
+      readStorageBeforeSetup();
       connectRequestedRef.current = true;
       connectIntentExpiresAtRef.current = null;
       setStatusIssue(null);
@@ -281,7 +348,12 @@ export function StorageSetupCard({
         scope: builderConnectionScope,
       });
     },
-    [builderConnectionScope, builderConnect.start, stepProperties],
+    [
+      builderConnectionScope,
+      builderConnect.start,
+      readStorageBeforeSetup,
+      stepProperties,
+    ],
   );
   const handleBuilderCancel = useCallback(() => {
     connectIntentExpiresAtRef.current =
@@ -290,6 +362,7 @@ export function StorageSetupCard({
   }, [builderConnect.cancel]);
   const handleSkip = useCallback(() => {
     clearConfiguredTimeout();
+    skippedRef.current = true;
     trackStorageStep("onboarding_step_skipped", {
       ...stepProperties,
     });
@@ -307,8 +380,41 @@ export function StorageSetupCard({
           )
     : null;
   const builderConnecting = builderConnect.connecting;
+  const builderConnectingRef = useRef(builderConnecting);
+  builderConnectingRef.current = builderConnecting;
   const actionConnecting = connecting || builderConnecting;
 
+  // The custom-keys form opens in another tab, and some routes keep this card
+  // mounted after it saves, so a return to this tab reads the status too.
+  useEffect(() => {
+    const readOnReturn = () => {
+      if (
+        document.hidden ||
+        !customKeysOpenedRecently() ||
+        completionTrackedRef.current ||
+        skippedRef.current ||
+        returnReadInFlightRef.current
+      ) {
+        return;
+      }
+      returnReadInFlightRef.current = true;
+      void fetchVideoStorageStatus({ timeoutMs: 10_000 })
+        .then(trackCompletedIfConfigured)
+        .catch((err) => {
+          console.warn("[storage-setup] completion check failed:", err);
+        })
+        .finally(() => {
+          returnReadInFlightRef.current = false;
+        });
+    };
+    window.addEventListener("focus", readOnReturn);
+    document.addEventListener("visibilitychange", readOnReturn);
+    return () => {
+      window.removeEventListener("focus", readOnReturn);
+      document.removeEventListener("visibilitychange", readOnReturn);
+    };
+  }, [customKeysOpenedRecently, trackCompletedIfConfigured]);
+
   useEffect(() => {
     trackStorageStep("onboarding_step_viewed", {
       ...stepProperties,
@@ -319,6 +425,24 @@ export function StorageSetupCard({
     mountedRef.current = true;
     return () => {
       mountedRef.current = false;
+      // The route can unmount this card mid-setup: while the connect flow is
+      // still connecting, or after this card accepted the connect but before
+      // its storage poll saw it. After a cancel the flow keeps connecting
+      // through its popup-closed grace, so crediting then relies on that grace
+      // staying shorter than CANCELLED_SETUP_RECOVERY_MS.
+      const setupPending =
+        !completionTrackedRef.current &&
+        !skippedRef.current &&
+        (builderHandedOffRef.current ||
+          builderConnectingRef.current ||
+          customKeysOpenedRecently());
+      if (setupPending) {
+        void fetchVideoStorageStatus({ timeoutMs: 10_000 })
+          .then(trackCompletedIfConfigured)
+          .catch((err) => {
+            console.warn("[storage-setup] completion check failed:", err);
+          });
+      }
       clearConfiguredTimeout();
       if (pollRef.current) {
         clearInterval(pollRef.current);
@@ -326,7 +450,12 @@ export function StorageSetupCard({
       }
       stopVisibilityHandler();
     };
-  }, [clearConfiguredTimeout, stopVisibilityHandler]);
+  }, [
+    clearConfiguredTimeout,
+    customKeysOpenedRecently,
+    stopVisibilityHandler,
+    trackCompletedIfConfigured,
+  ]);
 
   return (
     <div className="mx-auto flex w-full max-w-md flex-col gap-5 rounded-2xl border border-border bg-card p-6 shadow-lg">
@@ -357,6 +486,7 @@ export function StorageSetupCard({
             cancel: undefined,
           }}
           onConnect={handleBuilderConnect}
+          onTriggerClick={readStorageBeforeSetup}
         >
           <Button
             type="button"
@@ -379,12 +509,14 @@ export function StorageSetupCard({
                 href={storageSetupHref}
                 target="_blank"
                 rel="noopener noreferrer"
-                onClick={() =>
+                onClick={() => {
+                  readStorageBeforeSetup();
+                  customKeysOpenedAtRef.current = Date.now();
                   trackStorageStep("onboarding_method_clicked", {
                     ...stepProperties,
                     method_id: "s3",
-                  })
-                }
+                  });
+                }}
               >
                 {t("storageSetup.customKeys")}
               </a>

package/corpus/templates/clips/app/routes/record.tsx

@@ -1279,6 +1279,16 @@ export function shouldRedirectToStorageSetupHome({
   );
 }
 
+export function storageSetupReason(
+  status: Pick<VideoStorageStatus, "denyReason"> | undefined,
+): string {
+  if (!status) return "status_unavailable";
+  // "disabled" means free hosted clips are off, not that a hosted clip was denied.
+  return status.denyReason && status.denyReason !== "disabled"
+    ? `hosted_${status.denyReason}`
+    : "storage_required";
+}
+
 export function shouldShowFirstRunStorageSetup({
   storageConfigured,
   storageStatusUnavailable,
@@ -4187,6 +4197,7 @@ export default function RecordRoute() {
                     showBuilderStorageOffer={!hostedAllowanceExhausted}
                     connectSource="clips_record_storage_setup_card"
                     connectFlow="record"
+                    setupReason={storageSetupReason(storageQuery.data)}
                   />
                 </div>
               ) : showStorageStatusUnavailable ? (