@agent-native/core 0.98.0 → 0.98.2

package/corpus/templates/calendar/.agents/skills/real-time-sync/SKILL.md

@@ -30,7 +30,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
    useDbSync({ queryClient });
    ```
 
-   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries for ordinary domain events — that caused a request storm in production. The exception is `source: "action"`: a successful mutating action is the framework-wide "agent changed app data" signal, so `useDbSync` also refreshes active React Query observers as a compatibility safety net for custom apps that have not yet moved every read to `useActionQuery` or source-versioned query keys.
+   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries — that caused request storms in production. A successful mutating action refreshes active `useActionQuery` observers under the `["action"]` prefix. Browser actions carry a tab id so their originating tab ignores the sync echo while other tabs refresh. Legacy apps can opt into broader compatibility with `actionInvalidatePredicate`, but first-party apps should use action-backed or source-versioned query keys. Idle fallback polling runs once per minute; active agent work temporarily uses the faster cadence.
 
 3. **Templates fold per-source counters into their query keys.** This is the pattern that makes "agent writes show up without a manual refresh" reliable:
 
@@ -117,7 +117,7 @@ useQuery({
 | UI not updating after agent writes | Is `useDbSync` called with the correct `queryClient`? Does the affected query have an active observer?         |
 | Poll endpoint not responding       | Is `/_agent-native/poll` accessible? Is the server running?                                                    |
 | SSE not connecting                 | Is `/_agent-native/events` accessible and authenticated? Polling should still keep the UI fresh as fallback.   |
-| High CPU / event storms            | The agent is writing rapidly. Add `staleTime` to queries to debounce refetches.                                |
+| High CPU / event storms            | Use targeted source keys, settle bursty list counters, and avoid broad action invalidation.                   |
 
 ## Jitter Prevention
 

package/corpus/templates/calendar/app/root.tsx

@@ -230,6 +230,7 @@ export default function Root() {
           // Calendar aggressively refetches on focus because external
           // calendar events can change without a DB sync event (e.g. Google
           // Calendar webhooks with a processing delay).
+          // request-storm-allow: one user-driven focus refresh for provider data.
           refetchOnWindowFocus: true,
           // Flat retry: calendar data fetches don't need the auth-aware
           // retry function — auth errors surface through the booking flow.

package/corpus/templates/chat/.agents/skills/real-time-sync/SKILL.md

@@ -30,7 +30,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
    useDbSync({ queryClient });
    ```
 
-   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries for ordinary domain events — that caused a request storm in production. The exception is `source: "action"`: a successful mutating action is the framework-wide "agent changed app data" signal, so `useDbSync` also refreshes active React Query observers as a compatibility safety net for custom apps that have not yet moved every read to `useActionQuery` or source-versioned query keys.
+   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries — that caused request storms in production. A successful mutating action refreshes active `useActionQuery` observers under the `["action"]` prefix. Browser actions carry a tab id so their originating tab ignores the sync echo while other tabs refresh. Legacy apps can opt into broader compatibility with `actionInvalidatePredicate`, but first-party apps should use action-backed or source-versioned query keys. Idle fallback polling runs once per minute; active agent work temporarily uses the faster cadence.
 
 3. **Templates fold per-source counters into their query keys.** This is the pattern that makes "agent writes show up without a manual refresh" reliable:
 
@@ -117,7 +117,7 @@ useQuery({
 | UI not updating after agent writes | Is `useDbSync` called with the correct `queryClient`? Does the affected query have an active observer?         |
 | Poll endpoint not responding       | Is `/_agent-native/poll` accessible? Is the server running?                                                    |
 | SSE not connecting                 | Is `/_agent-native/events` accessible and authenticated? Polling should still keep the UI fresh as fallback.   |
-| High CPU / event storms            | The agent is writing rapidly. Add `staleTime` to queries to debounce refetches.                                |
+| High CPU / event storms            | Use targeted source keys, settle bursty list counters, and avoid broad action invalidation.                   |
 
 ## Jitter Prevention
 

package/corpus/templates/clips/app/components/player/video-player.tsx

@@ -1083,13 +1083,17 @@ export const VideoPlayer = forwardRef<VideoPlayerHandle, VideoPlayerProps>(
     const fullscreenMenuContainer = isFullscreen ? containerRef.current : null;
 
     const showThroughoutCta = cta && cta.placement === "throughout";
+    // Mobile Safari may defer loadeddata/canplay until playback starts. Keep
+    // the paused state actionable even when those readiness events have not
+    // fired yet; once the user asks to play, the pending/buffering states give
+    // them accurate loading feedback.
     const centerOverlayMode =
       activeVideoSrc &&
       !isLoomEmbed &&
       !unsupportedFormat &&
       !showEndCta &&
       (!isPlaying || isPlayPending || isBuffering)
-        ? isPreparing || isPlayPending || isBuffering || !canPlay
+        ? isPlayPending || isBuffering
           ? "loading"
           : "ready"
         : null;

package/corpus/templates/clips/app/hooks/use-auto-title.ts

@@ -16,6 +16,7 @@ import {
   callAction,
   sendToAgentChat,
   type AgentChatMessage,
+  useChangeVersions,
 } from "@agent-native/core/client";
 import { fullVideoAiModelSelection } from "@shared/clips-ai-prefs";
 import { useEffect, useRef } from "react";
@@ -23,7 +24,6 @@ import { useEffect, useRef } from "react";
 import { useRecordings, type RecordingSummary } from "./use-library";
 
 const DEFAULT_TITLE = "Untitled recording";
-const POLL_INTERVAL_MS = 3000;
 const TWO_MINUTES_MS = 2 * 60 * 1000;
 
 /** True when `title` is blank or equal to the server-seeded default. */
@@ -99,8 +99,9 @@ async function clearRequest(recordingId: string): Promise<void> {
 }
 
 /**
- * Mount this once in the app shell. It polls the recording list and fires
- * `sendToAgentChat` for every pending request queued by a clips action.
+ * Mount this once in the app shell. It watches the exact application-state
+ * keys used for queued Clips AI work and fires `sendToAgentChat` for every
+ * pending request queued by a clips action.
  * Idempotent — a given (recordingId, kind, requestedAt) is only dispatched
  * once per tab session.
  */
@@ -119,13 +120,26 @@ export function useAutoTitleBridge(): void {
         `${r.id}:${r.titleSource ?? ""}:${r.title}:${r.updatedAt}:${r.transcriptStatus ?? ""}:${r.transcriptHasText ? "1" : "0"}`,
     )
     .join("|");
+  const aiRequestVersion = useChangeVersions(
+    readyRecordings.map(
+      (recording) => `app-state:clips-ai-request-${recording.id}`,
+    ),
+  );
 
   useEffect(() => {
     if (readyRecordings.length === 0) return;
     let cancelled = false;
+    let fallbackTimer: ReturnType<typeof setTimeout> | null = null;
 
     async function tick() {
-      if (cancelled || inflight.current) return;
+      if (cancelled) return;
+      if (inflight.current) {
+        // A new request-state version can arrive while the previous list read
+        // is in flight. Recheck after it settles so that event is not the last
+        // chance to dispatch the queued work.
+        fallbackTimer = setTimeout(() => void tick(), 50);
+        return;
+      }
       inflight.current = true;
       try {
         const requestsById = await listRequests();
@@ -192,14 +206,66 @@ export function useAutoTitleBridge(): void {
       }
     }
 
-    tick();
-    const handle = setInterval(tick, POLL_INTERVAL_MS);
+    function scheduleNextFallback() {
+      if (cancelled) return;
+      const delay = nextAutoTitleFallbackDelay(
+        readyRecordings,
+        dispatched.current,
+      );
+      if (delay === null) return;
+      // Keep the timeout non-zero so a failed request cannot spin a tight loop.
+      fallbackTimer = setTimeout(
+        () => {
+          fallbackTimer = null;
+          void tick().finally(scheduleNextFallback);
+        },
+        Math.max(delay, 50),
+      );
+    }
+
+    // One initial read catches requests queued before this component mounted.
+    // Later reads are driven by the exact clips-ai-request application-state
+    // counters above. The only timer left is a one-shot wake-up when an old
+    // transcript-backed recording becomes eligible for the legacy fallback.
+    void tick().finally(scheduleNextFallback);
     return () => {
       cancelled = true;
-      clearInterval(handle);
+      if (fallbackTimer) clearTimeout(fallbackTimer);
     };
+    // readyRecordingsKey is the stable snapshot consumed by tick; depending on
+    // the array itself would restart the effect on every query result object.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [readyRecordingsKey]);
+  }, [aiRequestVersion, readyRecordingsKey]);
+}
+
+export function nextAutoTitleFallbackDelay(
+  recordings: readonly RecordingSummary[],
+  dispatched: ReadonlySet<string>,
+  now = Date.now(),
+): number | null {
+  let nextDelay: number | null = null;
+
+  for (const recording of recordings) {
+    if (recording.status !== "ready") continue;
+    if (!isAutoTitleReplaceable(recording.title, recording.titleSource)) {
+      continue;
+    }
+    if (
+      recording.transcriptStatus !== "ready" ||
+      recording.transcriptHasText !== true ||
+      dispatched.has(`${recording.id}:fallback`)
+    ) {
+      continue;
+    }
+
+    const createdAt = new Date(recording.createdAt).getTime();
+    const delay = Number.isFinite(createdAt)
+      ? Math.max(0, TWO_MINUTES_MS - (now - createdAt))
+      : 0;
+    nextDelay = nextDelay === null ? delay : Math.min(nextDelay, delay);
+  }
+
+  return nextDelay;
 }
 
 function buildRequestContext(rec: RecordingSummary, request: AiRequest) {

package/corpus/templates/clips/app/hooks/use-library.ts

@@ -44,24 +44,13 @@ export interface ListRecordingsArgs {
   offset?: number;
 }
 
-function isAwaitingAutoTitle(recording: RecordingSummary): boolean {
-  const title = (recording.title ?? "").trim();
-  const titleIsReplaceable =
-    title === "" ||
-    title === "Untitled recording" ||
-    recording.titleSource === "default" ||
-    recording.titleSource === "context";
-  if (!titleIsReplaceable) return false;
-
-  if (recording.transcriptStatus === "failed") return false;
-  if (recording.transcriptStatus === "ready") {
-    return recording.transcriptHasText === true;
-  }
-
-  return (
-    recording.transcriptStatus === "pending" ||
-    recording.transcriptStatus === "streaming"
-  );
+export function recordingsRefetchInterval(
+  recordings: readonly RecordingSummary[] | undefined,
+): number | false {
+  if (!recordings || recordings.length === 0) return false;
+  return recordings.some((recording) => isLiveRecordingUpload(recording))
+    ? 3000
+    : false;
 }
 
 export function useRecordings(args: ListRecordingsArgs = {}) {
@@ -74,17 +63,15 @@ export function useRecordings(args: ListRecordingsArgs = {}) {
           recordings: Array.isArray(data?.recordings) ? data.recordings : [],
         };
       },
-      // Keep a short poll while uploads/processors are active so the library
-      // card does not get stuck if the global refresh signal is missed.
-      // Also poll for replaceable seed titles so the card upgrades promptly.
+      // Keep a short poll only while uploads/processors are active so the
+      // library card does not get stuck if the global refresh signal is
+      // missed. Generated titles arrive through the shared DB sync transport;
+      // polling completed recordings forever is both redundant and expensive.
       refetchInterval: (q) => {
         const recs = (q.state.data as any)?.recordings as
           | RecordingSummary[]
           | undefined;
-        if (!recs || recs.length === 0) return false;
-        const pendingUpload = recs.some((rec) => isLiveRecordingUpload(rec));
-        const pendingTitle = recs.some(isAwaitingAutoTitle);
-        return pendingUpload || pendingTitle ? 3000 : false;
+        return recordingsRefetchInterval(recs);
       },
     },
   );

package/corpus/templates/clips/app/routes/_app.settings._index.tsx

@@ -734,7 +734,7 @@ export default function SettingsIndexRoute() {
     builderStatus.loading ||
     !builderConnect.hasFetchedStatus;
   const s3Configured = activeProviderId === "s3";
-  const s3Collapsed = builderConnected && !s3Expanded;
+  const s3Collapsed = !s3Expanded;
   const configuredApiKeyCount = AI_PROVIDER_FIELDS.filter(
     (field) => apiKeyStatus[field.key],
   ).length;
@@ -908,7 +908,7 @@ export default function SettingsIndexRoute() {
                   </div>
 
                   <Collapsible
-                    open={builderConnected ? !s3Collapsed : true}
+                    open={!s3Collapsed}
                     onOpenChange={(open) => setS3Expanded(open)}
                   >
                     <div className="rounded-md border border-border">
@@ -939,26 +939,24 @@ export default function SettingsIndexRoute() {
                                 : t("settings.s3OwnBucketDescription")}
                           </p>
                         </div>
-                        {builderConnected ? (
-                          <CollapsibleTrigger asChild>
-                            <Button
-                              type="button"
-                              variant="ghost"
-                              size="sm"
-                              className="shrink-0"
-                            >
-                              {s3Collapsed
-                                ? t("settings.configureS3")
-                                : t("settings.hideS3")}
-                              <IconChevronDown
-                                className={cn(
-                                  "h-4 w-4 transition-transform",
-                                  !s3Collapsed && "rotate-180",
-                                )}
-                              />
-                            </Button>
-                          </CollapsibleTrigger>
-                        ) : null}
+                        <CollapsibleTrigger asChild>
+                          <Button
+                            type="button"
+                            variant="ghost"
+                            size="sm"
+                            className="shrink-0"
+                          >
+                            {s3Collapsed
+                              ? t("settings.configureS3")
+                              : t("settings.hideS3")}
+                            <IconChevronDown
+                              className={cn(
+                                "h-4 w-4 transition-transform",
+                                !s3Collapsed && "rotate-180",
+                              )}
+                            />
+                          </Button>
+                        </CollapsibleTrigger>
                       </div>
 
                       <CollapsibleContent>

package/corpus/templates/clips/changelog/2026-07-11-clips-no-longer-stay-stuck-on-preparing-clip-when-they-are-r.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-11
+---
+
+Clips no longer stay stuck on Preparing clip when they are ready to play on mobile.

package/corpus/templates/clips/changelog/2026-07-11-generated-titles-no-longer-cause-continuous-background-refreshes.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-11
+---
+
+Generated titles no longer cause continuous background refreshes after a recording is ready.

package/corpus/templates/clips/changelog/2026-07-11-s3-storage-setup-stays-collapsed-until-you-choose-it-as-the-.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-11
+---
+
+S3 storage setup stays collapsed until you choose it as the secondary storage option.

package/corpus/templates/content/.agents/skills/real-time-sync/SKILL.md

@@ -30,7 +30,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
    useDbSync({ queryClient });
    ```
 
-   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries for ordinary domain events — that caused a request storm in production. The exception is `source: "action"`: a successful mutating action is the framework-wide "agent changed app data" signal, so `useDbSync` also refreshes active React Query observers as a compatibility safety net for custom apps that have not yet moved every read to `useActionQuery` or source-versioned query keys.
+   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries — that caused request storms in production. A successful mutating action refreshes active `useActionQuery` observers under the `["action"]` prefix. Browser actions carry a tab id so their originating tab ignores the sync echo while other tabs refresh. Legacy apps can opt into broader compatibility with `actionInvalidatePredicate`, but first-party apps should use action-backed or source-versioned query keys. Idle fallback polling runs once per minute; active agent work temporarily uses the faster cadence.
 
 3. **Templates fold per-source counters into their query keys.** This is the pattern that makes "agent writes show up without a manual refresh" reliable:
 
@@ -117,7 +117,7 @@ useQuery({
 | UI not updating after agent writes | Is `useDbSync` called with the correct `queryClient`? Does the affected query have an active observer?         |
 | Poll endpoint not responding       | Is `/_agent-native/poll` accessible? Is the server running?                                                    |
 | SSE not connecting                 | Is `/_agent-native/events` accessible and authenticated? Polling should still keep the UI fresh as fallback.   |
-| High CPU / event storms            | The agent is writing rapidly. Add `staleTime` to queries to debounce refetches.                                |
+| High CPU / event storms            | Use targeted source keys, settle bursty list counters, and avoid broad action invalidation.                   |
 
 ## Jitter Prevention
 

package/corpus/templates/content/app/components/sidebar/DocumentSidebar.tsx

@@ -1188,8 +1188,8 @@ export function DocumentSidebar({
         </div>
       )}
 
-      <ScrollArea className="min-h-0 flex-1">
-        <div className="min-w-full w-max py-2 pe-2">
+      <ScrollArea className="min-h-0 flex-1 [&_[data-radix-scroll-area-viewport]]:!overflow-x-hidden">
+        <div className="w-full min-w-0 py-2 pe-2">
           {/* Search results */}
           {filteredDocuments ? (
             <>

package/corpus/templates/content/app/hooks/use-comments.ts

@@ -65,7 +65,6 @@ export function useComments(documentId: string | null) {
         }
         return Array.from(threadMap.values());
       },
-      refetchInterval: 5000,
     },
   );
 }

package/corpus/templates/content/changelog/2026-07-11-comments-now-update-from-live-collaboration-events-without-c.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-11
+---
+
+Comments now update from live collaboration events without continuous background requests

package/corpus/templates/content/changelog/2026-07-12-the-left-sidebar-stays-fixed-horizontally-while-scrolling-on.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-12
+---
+
+The left sidebar stays fixed horizontally while scrolling on desktop and mobile.

package/corpus/templates/design/app/components/layout/Header.tsx

@@ -88,7 +88,7 @@ export function Header() {
       </div>
       <div className="flex items-center gap-2 shrink-0">
         {actions}
-        <RunsTray onOpenThread={openRunThread} />
+        <RunsTray pollMs={0} onOpenThread={openRunThread} />
         <AgentToggleButton />
       </div>
     </header>

package/corpus/templates/forms/.agents/skills/real-time-sync/SKILL.md

@@ -30,7 +30,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
    useDbSync({ queryClient });
    ```
 
-   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries for ordinary domain events — that caused a request storm in production. The exception is `source: "action"`: a successful mutating action is the framework-wide "agent changed app data" signal, so `useDbSync` also refreshes active React Query observers as a compatibility safety net for custom apps that have not yet moved every read to `useActionQuery` or source-versioned query keys.
+   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries — that caused request storms in production. A successful mutating action refreshes active `useActionQuery` observers under the `["action"]` prefix. Browser actions carry a tab id so their originating tab ignores the sync echo while other tabs refresh. Legacy apps can opt into broader compatibility with `actionInvalidatePredicate`, but first-party apps should use action-backed or source-versioned query keys. Idle fallback polling runs once per minute; active agent work temporarily uses the faster cadence.
 
 3. **Templates fold per-source counters into their query keys.** This is the pattern that makes "agent writes show up without a manual refresh" reliable:
 
@@ -117,7 +117,7 @@ useQuery({
 | UI not updating after agent writes | Is `useDbSync` called with the correct `queryClient`? Does the affected query have an active observer?         |
 | Poll endpoint not responding       | Is `/_agent-native/poll` accessible? Is the server running?                                                    |
 | SSE not connecting                 | Is `/_agent-native/events` accessible and authenticated? Polling should still keep the UI fresh as fallback.   |
-| High CPU / event storms            | The agent is writing rapidly. Add `staleTime` to queries to debounce refetches.                                |
+| High CPU / event storms            | Use targeted source keys, settle bursty list counters, and avoid broad action invalidation.                   |
 
 ## Jitter Prevention
 

package/corpus/templates/macros/app/components/layout/AppLayout.tsx

@@ -80,7 +80,7 @@ export function AppLayout({ children }: { children: React.ReactNode }) {
     }).catch(() => {});
   }, [location.pathname, isAnalytics, isSettings]);
 
-  // Poll for navigate commands from the agent
+  // useDbSync invalidates this key when the agent writes a navigate command.
   const { data: navCommand } = useQuery({
     queryKey: ["navigate-command"],
     queryFn: async () => {
@@ -94,7 +94,6 @@ export function AppLayout({ children }: { children: React.ReactNode }) {
         return null;
       }
     },
-    refetchInterval: 2000,
   });
 
   useEffect(() => {

package/corpus/templates/macros/app/root.tsx

@@ -169,9 +169,6 @@ export default function Root() {
     createAgentNativeQueryClient({
       defaultOptions: {
         queries: {
-          // Macros UI refetches on focus to pick up meals logged in other
-          // browser tabs or mobile, which don't always arrive via DB sync.
-          refetchOnWindowFocus: true,
           // Flat retry: macros data errors are usually transient network
           // issues, not auth failures, so a flat count is sufficient.
           retry: 1,

package/corpus/templates/mail/.agents/skills/real-time-sync/SKILL.md

@@ -30,7 +30,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
    useDbSync({ queryClient });
    ```
 
-   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries for ordinary domain events — that caused a request storm in production. The exception is `source: "action"`: a successful mutating action is the framework-wide "agent changed app data" signal, so `useDbSync` also refreshes active React Query observers as a compatibility safety net for custom apps that have not yet moved every read to `useActionQuery` or source-versioned query keys.
+   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries — that caused request storms in production. A successful mutating action refreshes active `useActionQuery` observers under the `["action"]` prefix. Browser actions carry a tab id so their originating tab ignores the sync echo while other tabs refresh. Legacy apps can opt into broader compatibility with `actionInvalidatePredicate`, but first-party apps should use action-backed or source-versioned query keys. Idle fallback polling runs once per minute; active agent work temporarily uses the faster cadence.
 
 3. **Templates fold per-source counters into their query keys.** This is the pattern that makes "agent writes show up without a manual refresh" reliable:
 
@@ -117,7 +117,7 @@ useQuery({
 | UI not updating after agent writes | Is `useDbSync` called with the correct `queryClient`? Does the affected query have an active observer?         |
 | Poll endpoint not responding       | Is `/_agent-native/poll` accessible? Is the server running?                                                    |
 | SSE not connecting                 | Is `/_agent-native/events` accessible and authenticated? Polling should still keep the UI fresh as fallback.   |
-| High CPU / event storms            | The agent is writing rapidly. Add `staleTime` to queries to debounce refetches.                                |
+| High CPU / event storms            | Use targeted source keys, settle bursty list counters, and avoid broad action invalidation.                   |
 
 ## Jitter Prevention
 

package/corpus/templates/mail/app/hooks/use-compose-state.ts

@@ -139,6 +139,7 @@ export function useComposeState() {
       return merged;
     },
     staleTime: 1_000,
+    // request-storm-allow: one focus refresh reconciles bounded compose drafts across tabs.
     refetchOnWindowFocus: true,
   });
 

package/corpus/templates/mail/app/root.tsx

@@ -419,18 +419,7 @@ function DbSyncSetup() {
 const MAIL_TOASTER = <Toaster richColors position="bottom-left" />;
 
 export default function Root() {
-  const [queryClient] = useState(() =>
-    createAgentNativeQueryClient({
-      defaultOptions: {
-        queries: {
-          // Mail's VisibilityRefresh handles the focus-based refresh with a
-          // 60 s throttle, so we also want React Query's focus refetch to
-          // fire for other query keys (labels, settings, etc.).
-          refetchOnWindowFocus: true,
-        },
-      },
-    }),
-  );
+  const [queryClient] = useState(() => createAgentNativeQueryClient());
   return (
     <AppToolkitProvider>
       <AppProviders

package/corpus/templates/plan/.agents/skills/real-time-sync/SKILL.md

@@ -30,7 +30,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
    useDbSync({ queryClient });
    ```
 
-   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries for ordinary domain events — that caused a request storm in production. The exception is `source: "action"`: a successful mutating action is the framework-wide "agent changed app data" signal, so `useDbSync` also refreshes active React Query observers as a compatibility safety net for custom apps that have not yet moved every read to `useActionQuery` or source-versioned query keys.
+   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries — that caused request storms in production. A successful mutating action refreshes active `useActionQuery` observers under the `["action"]` prefix. Browser actions carry a tab id so their originating tab ignores the sync echo while other tabs refresh. Legacy apps can opt into broader compatibility with `actionInvalidatePredicate`, but first-party apps should use action-backed or source-versioned query keys. Idle fallback polling runs once per minute; active agent work temporarily uses the faster cadence.
 
 3. **Templates fold per-source counters into their query keys.** This is the pattern that makes "agent writes show up without a manual refresh" reliable:
 
@@ -117,7 +117,7 @@ useQuery({
 | UI not updating after agent writes | Is `useDbSync` called with the correct `queryClient`? Does the affected query have an active observer?         |
 | Poll endpoint not responding       | Is `/_agent-native/poll` accessible? Is the server running?                                                    |
 | SSE not connecting                 | Is `/_agent-native/events` accessible and authenticated? Polling should still keep the UI fresh as fallback.   |
-| High CPU / event storms            | The agent is writing rapidly. Add `staleTime` to queries to debounce refetches.                                |
+| High CPU / event storms            | Use targeted source keys, settle bursty list counters, and avoid broad action invalidation.                   |
 
 ## Jitter Prevention
 

package/corpus/templates/plan/.agents/skills/visual-plan/references/local-files.md

@@ -36,9 +36,9 @@ The local-files contract:
   — encode multiline code as JSON string attributes such as `code={"const x =\n  y"}`
   (a static template literal is accepted only when it has no `${...}`
   interpolation). `plan local check` is a quick OFFLINE lint (a subset of the
-  renderer schema), so a green `check` does not guarantee the plan renders;
-  `plan local verify` is the authoritative validation against the real renderer
-  schema.
+  renderer schema), so a green `check` does not guarantee the plan renders.
+  `plan local verify` also stays on-device: it uses the offline lint unless it
+  can reach a Plan renderer on an explicit loopback `--app-url`.
 - **Write a local MDX folder.** Use `plans/<slug>/` to check the artifact into the
   repo, or a repo-ignored/temporary folder such as `.agent-native/plans/<slug>/`
   or `/tmp/agent-native-plans/<slug>/` when it should not be checked in. The
@@ -53,7 +53,10 @@ The local-files contract:
   (use `--kind plan` for plans, `--kind recap` for recaps). Report the local
   bridge URL from stdout or `<plan-dir>/.plan-url`; treat `.plan-url` as a local
   token file and do not commit it. The URL opens the hosted Plan UI but reads from
-  the localhost bridge on this machine, so it is not shareable across machines. On
+  the localhost bridge on this machine, so it is not shareable across machines.
+  The token is carried in the URL fragment (which is not sent to the hosted
+  origin), and the local-plan route disables DOM autocapture and session replay
+  while retaining sanitized pageviews and error monitoring. On
   macOS `--open` prefers Chromium browsers; if Safari opens, switch to
   Chrome/Chromium because Safari can block the hosted HTTPS page from fetching the
   HTTP localhost bridge. If the Plan app itself is running locally with the same
@@ -63,14 +66,16 @@ The local-files contract:
   running local Plan app.
 - **Headless verify.** Run
   `npx @agent-native/core@latest plan local verify --dir <plan-dir> --kind <plan|recap>`.
-  It starts the bridge, checks the private-network preflight and JSON payload, AND
-  validates the content against the real renderer schema via the Plan app's
-  `validate-local-plan-source` action. A non-`ok` result with
+  It starts the bridge and checks the private-network preflight and JSON payload
+  entirely on loopback. It never sends MDX or assets to a remote validation
+  action. When `--app-url` points to a loopback Plan app, verify also validates
+  against that local app's real renderer schema via `validate-local-plan-source`.
+  A non-`ok` result with
   `validation.valid: false` lists the renderer's exact schema-path issues (e.g.
   `blocks[1].data.tabs[0]...`); fix those before handing off. If `validation.ran`
-  is `false`, the Plan app did not expose the validate endpoint (older/unreachable
-  deploy) — point `--app-url` at a current Plan app (e.g. a local
-  `http://localhost:8096`) for the authoritative check. If the browser hangs on
+  is `false`, verify used the offline lint because the app URL was remote or the
+  local Plan app was unavailable. Run a local Plan app and pass
+  `--app-url http://localhost:8096` for the authoritative check. If the browser hangs on
   "Loading plan", fetch the `bridgeUrl` from the verify/serve JSON to read the
   concrete validation error.
 - **Never call hosted tools for that plan/recap.** Do not call
@@ -86,8 +91,8 @@ The local-files contract:
   attachment, and publish/export receipts are unavailable until the user
   explicitly opts into publishing.
 
-Local-files mode only prevents plan/recap content from reaching the Agent-Native
-Plan database. It does not by itself make the coding agent's language model local;
+Local-files mode prevents plan/recap content from being uploaded to the
+Agent-Native Plan server or database. It does not by itself make the coding agent's language model local;
 for that stronger boundary the host agent/model must also be local or otherwise
 approved by the user.