@agent-native/core 0.99.1 → 0.99.3

package/corpus/core/src/client/use-db-sync.ts

@@ -1,9 +1,6 @@
 import { useEffect, useRef, useState } from "react";
 
-import {
-  ensureDemoModeFetchInterceptor,
-  refreshDemoModeFetchInterceptor,
-} from "../demo/fetch-interceptor.js";
+import { ensureDemoModeFetchInterceptor } from "../demo/fetch-interceptor.js";
 import { agentNativePath } from "./api-path.js";
 import { getBrowserTabId } from "./browser-tab-id.js";
 import {
@@ -314,15 +311,6 @@ class SyncTransport {
   // -------------------------------------------------------------------------
 
   private fan(events: SyncEvent[], version: number | undefined): void {
-    if (
-      events.some(
-        (event) =>
-          event.source === "app-state" &&
-          (event.key === "demo-mode" || event.key === "*"),
-      )
-    ) {
-      void refreshDemoModeFetchInterceptor();
-    }
     for (const sub of this.subscribers.values()) {
       sub.onEvents(events, version);
     }
@@ -544,8 +532,8 @@ class SyncTransport {
   };
 
   private start(): void {
-    // Universal demo-mode redaction for the UI. Idempotent + browser-only +
-    // a no-op until demo mode is on. Lives here because every template root
+    // Universal browser-local demo-mode presentation redaction. Idempotent and
+    // a no-op until the local preference is on. Lives here because every root
     // already mounts useDbSync, so this needs zero per-template wiring.
     ensureEmbedAuthFetchInterceptor();
     ensureDemoModeFetchInterceptor();

package/corpus/core/src/client/use-demo-mode-status.ts

@@ -1,44 +1,30 @@
-import { useQuery } from "@tanstack/react-query";
+import { useSyncExternalStore } from "react";
 
-import { agentNativePath } from "./api-path.js";
-import { useChangeVersion } from "./use-change-version.js";
-
-interface DemoModeStatusResponse {
-  enabled?: boolean;
-  forced?: boolean;
-}
+import {
+  getBrowserDemoModeEnabled,
+  subscribeToBrowserDemoMode,
+} from "../demo/browser-state.js";
 
 export interface DemoModeStatus {
   enabled: boolean;
-  forced: boolean;
+  forced: false;
   isLoading: boolean;
 }
 
-const DEMO_STATUS_URL = agentNativePath("/_agent-native/demo/status");
-
 /**
- * Reads the effective Demo mode status for the current user. The shared
- * change-version stream advances after Demo mode application state changes,
- * so mounted consumers refresh without polling or duplicating the route call.
+ * Reads the browser-local Demo mode presentation preference. This deliberately
+ * has no backend request: the server and agent always operate on real data.
  */
 export function useDemoModeStatus(): DemoModeStatus {
-  const demoModeVersion = useChangeVersion("app-state:demo-mode");
-
-  const { data, isLoading } = useQuery({
-    queryKey: ["agent-native", "demo-mode", demoModeVersion],
-    queryFn: async () => {
-      const res = await fetch(DEMO_STATUS_URL, {
-        credentials: "same-origin",
-      });
-      if (!res.ok) return null;
-      return (await res.json()) as DemoModeStatusResponse | null;
-    },
-    staleTime: Infinity,
-  });
+  const enabled = useSyncExternalStore(
+    subscribeToBrowserDemoMode,
+    getBrowserDemoModeEnabled,
+    () => false,
+  );
 
   return {
-    enabled: data?.enabled === true,
-    forced: data?.forced === true,
-    isLoading,
+    enabled,
+    forced: false,
+    isLoading: false,
   };
 }

package/corpus/core/src/demo/browser-state.ts

@@ -0,0 +1,47 @@
+/** Browser-local Demo mode state.
+ *
+ * Demo mode is a presentation preference for this browser only. It must not
+ * be persisted in application state or consulted by backend actions.
+ */
+export const DEMO_MODE_STORAGE_KEY = "agent-native:demo-mode";
+
+const DEMO_MODE_CHANGE_EVENT = "agent-native:demo-mode-change";
+
+export function getBrowserDemoModeEnabled(): boolean {
+  if (typeof window === "undefined") return false;
+  try {
+    return window.localStorage.getItem(DEMO_MODE_STORAGE_KEY) === "true";
+  } catch {
+    return false;
+  }
+}
+
+export function setBrowserDemoModeEnabled(enabled: boolean): void {
+  if (typeof window === "undefined") return;
+  try {
+    if (enabled) {
+      window.localStorage.setItem(DEMO_MODE_STORAGE_KEY, "true");
+    } else {
+      window.localStorage.removeItem(DEMO_MODE_STORAGE_KEY);
+    }
+  } catch {
+    // A blocked or unavailable localStorage should not break the settings UI.
+  }
+  window.dispatchEvent(new Event(DEMO_MODE_CHANGE_EVENT));
+}
+
+export function subscribeToBrowserDemoMode(callback: () => void): () => void {
+  if (typeof window === "undefined") return () => undefined;
+
+  const onStorage = (event: StorageEvent) => {
+    if (event.key === DEMO_MODE_STORAGE_KEY || event.key === null) callback();
+  };
+  const onChange = () => callback();
+
+  window.addEventListener("storage", onStorage);
+  window.addEventListener(DEMO_MODE_CHANGE_EVENT, onChange);
+  return () => {
+    window.removeEventListener("storage", onStorage);
+    window.removeEventListener(DEMO_MODE_CHANGE_EVENT, onChange);
+  };
+}

package/corpus/core/src/demo/fetch-interceptor.ts

@@ -1,4 +1,3 @@
-import { agentNativePath } from "../client/api-path.js";
 /**
  * Client-side demo-mode redaction.
  *
@@ -14,8 +13,8 @@ import { agentNativePath } from "../client/api-path.js";
  * can only ever post-process JSON the app already parses for display, so it
  * physically cannot break auth, SSE streams, SSR HTML, or binary downloads.
  *
- * The agent is handled separately and in-process (its action tool results are
- * redacted in `production-agent.ts`), so it doesn't depend on this at all.
+ * The agent transport is intentionally skipped because it carries the real
+ * backend results; this interceptor is only a browser presentation transform.
  *
  * Scope intentionally narrow:
  *   - Only same-document `GET` requests are redacted. Mutation responses
@@ -23,20 +22,18 @@ import { agentNativePath } from "../client/api-path.js";
  *     typed isn't echoed back as fake data mid-demo.
  *   - Only `application/json` 2xx bodies. Streams (`text/event-stream`),
  *     HTML, and binary are skipped by content-type.
- *   - Framework infra endpoints (poll, events, the demo-status endpoint
- *     itself) are skipped — no PII and avoids self-recursion.
+ *   - Framework infra endpoints (poll and events) are skipped.
  *   - Any error during interception falls back to the original response.
  */
+import { getBrowserDemoModeEnabled } from "./browser-state.js";
 import { redactDemoData } from "./redact.js";
 
-const STATUS_PATH = agentNativePath("/_agent-native/demo/status");
 const SKIP_SUBSTRINGS = [
-  "/_agent-native/demo/status",
   "/_agent-native/poll",
   "/_agent-native/events",
-  // Never touch agent transport. The agent already gets in-process
-  // redaction of its tool results; faking its own transcript adds no demo
-  // value and must stay clear of the tool_use/tool_result protocol. Covers
+  // Never touch agent transport. The agent receives real tool results; faking
+  // its own transcript adds no demo value and must stay clear of the
+  // tool_use/tool_result protocol. Covers
   // "/_agent-native/agent" (stream) and "/_agent-native/agent-chat"
   // (thread history) and any sub-paths.
   "/_agent-native/agent",
@@ -73,16 +70,6 @@ export function shouldSkipDemoResponseRedaction(url: string): boolean {
 }
 
 let installed = false;
-let demoEnabled = false;
-let originalFetch: typeof fetch | null = null;
-let refreshPromise: Promise<void> | null = null;
-
-// Set once the first demo-status check completes. We DO NOT block requests on
-// it — if status isn't known yet a response is simply passed through
-// un-redacted (a brief first-paint window) rather than delaying transport.
-// Injecting latency into early GETs previously risked the agent's streaming
-// reconnect logic; transport safety wins over redacting the first paint.
-let firstStatusDone = false;
 
 /** Reject after `ms` so a misclassified streaming body can never hang. */
 function withTimeout<T>(p: Promise<T>, ms: number): Promise<T> {
@@ -114,49 +101,17 @@ function methodOf(input: RequestInfo | URL, init?: RequestInit): string {
   return m.toUpperCase();
 }
 
-async function refreshDemoFlag(): Promise<void> {
-  const f = originalFetch ?? fetch;
-  try {
-    const res = await f(STATUS_PATH, { credentials: "same-origin" });
-    if (!res.ok) return;
-    const json = (await res.json()) as {
-      enabled?: boolean;
-      forced?: boolean;
-    } | null;
-    demoEnabled = json?.enabled === true || json?.forced === true;
-  } catch {
-    // Status endpoint unreachable — leave the last known value.
-  } finally {
-    firstStatusDone = true;
-  }
-}
-
-/** Refresh demo mode after the shared DB-sync stream reports a real change. */
-export function refreshDemoModeFetchInterceptor(): Promise<void> {
-  if (!installed) return Promise.resolve();
-  if (!refreshPromise) {
-    refreshPromise = refreshDemoFlag().finally(() => {
-      refreshPromise = null;
-    });
-  }
-  return refreshPromise;
-}
-
 /**
- * Install the demo-mode fetch interceptor and read demo status once. Later
- * changes are driven by the shared DB-sync transport instead of a separate
- * fixed polling loop.
+ * Install the browser-local demo-mode fetch interceptor.
  * Idempotent and browser-only — safe to call from any hook that runs in
- * every template root (we call it from `useDbSync`). A no-op until demo
- * mode is actually on.
+ * every template root (we call it from `useDbSync`).
  */
 export function ensureDemoModeFetchInterceptor(): void {
   if (typeof window === "undefined") return;
   if (installed) return;
   installed = true;
 
-  originalFetch = window.fetch.bind(window);
-  const base = originalFetch;
+  const base = window.fetch.bind(window);
 
   window.fetch = async function patchedFetch(
     input: RequestInfo | URL,
@@ -164,11 +119,11 @@ export function ensureDemoModeFetchInterceptor(): void {
   ): Promise<Response> {
     const res = await base(input, init);
 
-    // Fast path: anything that isn't a demo-enabled, plain GET returns the
+    // Fast path: anything that isn't a browser-local-demo, plain GET returns the
     // ORIGINAL response with zero body work and zero extra awaits — when
     // demo mode is off this wrapper is byte-for-byte native fetch, so it
     // cannot influence agent/run/stream transport.
-    if (!demoEnabled || !firstStatusDone) return res;
+    if (!getBrowserDemoModeEnabled()) return res;
     if (methodOf(input, init) !== "GET") return res;
     if (!res.ok) return res;
 
@@ -217,6 +172,4 @@ export function ensureDemoModeFetchInterceptor(): void {
       return res;
     }
   };
-
-  void refreshDemoModeFetchInterceptor();
 }

package/corpus/core/src/deploy/workspace-deploy.ts

@@ -416,7 +416,7 @@ function writeCloudflareRoutingManifest(distDir: string, apps: string[]): void {
   const dispatch = apps
     .map(
       (a) =>
-        `  if (pathname === "/${a}" || pathname.startsWith("/${a}/")) return ${moduleIdent(a)}.fetch(requestForMountedApp(request, "/${a}"), env, ctx);`,
+        `  if (pathname === "/${a}" || pathname === "/${a}.data" || pathname.startsWith("/${a}/")) return ${moduleIdent(a)}.fetch(requestForMountedApp(request, "/${a}"), env, ctx);`,
     )
     .join("\n");
   const dispatchRootFrameworkRoutes = apps.includes("dispatch")
@@ -880,7 +880,7 @@ function patchNetlifyFunctionEntry(
   const pathConfig =
     app === "dispatch"
       ? ["/_agent-native/*", "/.well-known/*", `${basePath}/*`]
-      : [basePath, `${basePath}/*`];
+      : [basePath, `${basePath}.data`, `${basePath}/*`];
   const normalizeBasePathHelper =
     app === "dispatch"
       ? ""

package/corpus/core/src/server/action-discovery.ts

@@ -599,7 +599,6 @@ export async function mergeCoreSharingActions(
       "change-appearance",
       () => import("../appearance/actions/change-appearance.js"),
     ],
-    ["toggle-demo-mode", () => import("../demo/actions/toggle-demo-mode.js")],
     // Audit log — read surface (who changed what, when, agent vs human).
     [
       "list-audit-events",

package/corpus/core/src/server/core-routes-plugin.ts

@@ -1205,36 +1205,6 @@ export function createCoreRoutesPlugin(
         }),
       );
 
-      // Demo-mode status — read by the client fetch interceptor and the
-      // Demo mode settings toggle. `forced` reflects the DEMO_MODE env (a
-      // hosted demo deployment); `enabled` ORs that with the per-user
-      // application_state toggle. No request-context dependency: the env case
-      // needs nothing, and the per-user case resolves the session straight
-      // off the request cookie via getSession(event).
-      getH3App(nitroApp).use(
-        `${P}/demo/status`,
-        defineEventHandler(async (event) => {
-          const { isDemoModeForced } = await import("../demo/config.js");
-          const forced = isDemoModeForced();
-          if (forced) return { enabled: true, forced: true };
-          try {
-            const session = await getSession(event);
-            const email = session?.email;
-            if (!email) return { enabled: false, forced: false };
-            const { appStateGet } =
-              await import("../application-state/store.js");
-            const state = await appStateGet(email, "demo-mode");
-            return {
-              enabled:
-                (state as { enabled?: boolean } | null)?.enabled === true,
-              forced: false,
-            };
-          } catch {
-            return { enabled: false, forced: false };
-          }
-        }),
-      );
-
       // Polling
       getH3App(nitroApp).use(`${P}/poll`, createPollHandler());
 

package/corpus/core/src/templates/workspace-core/.agents/skills/native-navigation/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: native-navigation
+description: >-
+  Use when adding or reviewing UI navigation so internal routes preserve
+  normal SPA behavior plus Cmd/Ctrl-click and middle-click new-tab semantics.
+scope: dev
+---
+
+# Native Navigation
+
+## Rule
+
+Pure navigation must render a real React Router `<Link>` for same-SPA routes,
+a native `<a href>` for external/public or explicit new-tab destinations, or a
+shadcn `Button asChild` wrapper around one. Do not use a button whose only job
+is to call `navigate()`, `window.open()`, or `window.location`.
+
+## Why
+
+Browser modifier-click, middle-click, keyboard activation, accessibility, and
+normal client-side routing come from real links. Imperative JavaScript
+navigation hides the destination and blocks those browser semantics.
+
+## How
+
+```tsx
+import { Link } from "react-router";
+
+<Link to={`/items/${item.id}`}>...</Link>
+
+<Button asChild>
+  <Link to="/settings">Settings</Link>
+</Button>
+
+<a href={previewUrl} target="_blank" rel="noopener noreferrer">
+  Preview
+</a>
+```
+
+- Use `Link` for same-SPA internal routes.
+- Use `<a>` when the URL is external, crosses an app/public boundary, is an
+  auth or sign-in destination, or intentionally opens in a new tab.
+- Preserve query strings and hashes in `to` or `href`.
+- For cards with nested actions, link only the non-interactive card region or
+  use a transparent Link overlay; never nest links or buttons.
+- If selection mode changes click behavior, prevent default only for an
+  unmodified primary click and preserve modified clicks.
+
+Keep imperative navigation for post-mutation redirects, OAuth and popup flows,
+downloads, media/blob URLs, playback, keyboard shortcuts, and stateful tabs.
+
+## Review
+
+Search for `onClick={() => navigate`, `window.open`, `window.location`,
+`onAuxClick`, and buttons whose only purpose is routing. For each candidate,
+confirm whether it is pure navigation or a stateful workflow before changing
+it.
+
+Verify the rendered DOM exposes an `href`, then test normal click, Cmd/Ctrl-click,
+middle-click, keyboard Enter, and nested controls where applicable. Run oxfmt
+and focused app tests or typechecks for the touched package.
+
+## Related Skills
+
+- `client-side-routing`
+- `frontend-design`
+- `shadcn-ui`

package/corpus/templates/analytics/.agents/skills/dashboard-management/SKILL.md

@@ -58,6 +58,23 @@ once — do not switch to db-patch or raw SQL.
 
 Do not use `app-db` as a dashboard source. For first-party events collected through `/track`, use `source: "first-party"` or the `query-agent-native-analytics` action rather than raw internal `db-query`.
 
+AI-generated first-party panels are dashboard-time-bound by default. Set
+`config.timeScope` to `"dashboard"` and include the matching dashboard time
+filter in the SQL. The allowed values are:
+
+- `dashboard`: use the dashboard-selected time range; the default for ordinary metrics.
+- `fixed-window`: use an explicit bounded window independent of the dashboard filter.
+- `cohort-history`: use the bounded history of an explicitly defined cohort.
+- `all-time`: scan all available history; use only when the user requests it and
+  put `all-time`, `lifetime`, or `historical` in the title or description.
+
+`{{timeRange}}` requires an explicit matching `filters` entry with
+`id: "timeRange"` and `type: "select"`. `{{<id>Start}}` and `{{<id>End}}`
+require a matching `filters` entry with that id and `type: "date-range"`.
+Do not rely on undeclared time variables. Server validation rejects unbound
+first-party SQL, so declare the filter or choose an explicit non-dashboard
+scope before saving.
+
 ## Creating A Dashboard
 
 When the user asks for a dashboard:
@@ -154,7 +171,8 @@ Notes:
       "source": "first-party",
       "chartType": "metric",
       "width": 1,
-      "sql": "SELECT COUNT(*) AS value FROM analytics_events WHERE event_name = 'click'",
+      "config": { "timeScope": "dashboard" },
+      "sql": "SELECT COUNT(*) AS value FROM analytics_events WHERE event_name = 'click' AND event_date >= '{{dateStart}}' AND event_date < '{{dateEnd}}'",
     },
     {
       "id": "kpi-signups",
@@ -162,7 +180,8 @@ Notes:
       "source": "first-party",
       "chartType": "metric",
       "width": 1,
-      "sql": "SELECT COUNT(*) AS value FROM analytics_events WHERE event_name = 'signup'",
+      "config": { "timeScope": "dashboard" },
+      "sql": "SELECT COUNT(*) AS value FROM analytics_events WHERE event_name = 'signup' AND event_date >= '{{dateStart}}' AND event_date < '{{dateEnd}}'",
     },
     {
       "id": "kpi-active",
@@ -170,7 +189,8 @@ Notes:
       "source": "first-party",
       "chartType": "metric",
       "width": 1,
-      "sql": "SELECT COUNT(DISTINCT user_id) AS value FROM analytics_events",
+      "config": { "timeScope": "dashboard" },
+      "sql": "SELECT COUNT(DISTINCT user_id) AS value FROM analytics_events WHERE event_date >= '{{dateStart}}' AND event_date < '{{dateEnd}}'",
     },
     // Section header switches the grid to 2 columns for the panels below it.
     {
@@ -186,7 +206,8 @@ Notes:
       "source": "first-party",
       "chartType": "line",
       "width": 2,
-      "sql": "SELECT DATE(timestamp) AS date, COUNT(*) AS value FROM analytics_events WHERE timestamp >= '{{dateStart}}' AND timestamp < '{{dateEnd}}' GROUP BY 1 ORDER BY 1",
+      "config": { "timeScope": "dashboard" },
+      "sql": "SELECT event_date AS date, COUNT(*) AS value FROM analytics_events WHERE event_date >= '{{dateStart}}' AND event_date < '{{dateEnd}}' GROUP BY 1 ORDER BY 1",
     },
   ],
 }
@@ -196,6 +217,13 @@ Notes:
 
 `filters[]` defines dashboard-wide controls. Filter values are available in panel SQL through `{{var}}` interpolation. Date ranges emit `{{<id>Start}}` and `{{<id>End}}`.
 
+For dashboard-time-bound first-party SQL, use `config.timeScope: "dashboard"`
+and a predicate that consumes the declared filter, such as
+`event_date >= '{{dateStart}}' AND event_date < '{{dateEnd}}'`. A
+`{{timeRange}}` token must have a matching select filter and SQL branches for
+its options; date variables must have a matching date-range filter. The server
+rejects unbound first-party SQL during dashboard validation.
+
 **Filter ids must be unique.** Two filters with the same `id` collide on the same URL param, so changing one visibly updates the other in the UI. The dashboard save endpoint rejects duplicates with a 400.
 
 **Use `type: "date-range"` for paired start/end dates.** Don't add two `type: "date"` filters labeled "Start" and "End" — even with distinct ids, that ships the wrong UX. A single date-range filter renders as the "from … to …" pair and exposes both halves to SQL via `{{<id>Start}}` / `{{<id>End}}`.
@@ -244,6 +272,17 @@ type DashboardPatch = {
   variables?: Record<string, string>;
 };
 
+type PanelTimeScope =
+  | "dashboard"
+  | "fixed-window"
+  | "cohort-history"
+  | "all-time";
+
+type PanelConfig = Record<string, unknown> & {
+  // Use "dashboard" for AI-generated first-party panels by default.
+  timeScope?: PanelTimeScope;
+};
+
 type PanelPatch = {
   title?: string;
   sql?: string;
@@ -268,7 +307,7 @@ type PanelPatch = {
   width?: number;
   columns?: number;
   tab?: string;
-  config?: Record<string, unknown>;
+  config?: PanelConfig;
   description?: string;
 };
 
@@ -346,7 +385,9 @@ dashboard
     source: "first-party",
     chartType: "metric",
     width: 1,
-    sql: "SELECT COUNT(*) AS value FROM analytics_events",
+    config: { timeScope: "dashboard" },
+    // Assumes filters includes { id: "date", type: "date-range", default: "30d" }.
+    sql: "SELECT COUNT(*) AS value FROM analytics_events WHERE event_date >= '{{dateStart}}' AND event_date < '{{dateEnd}}'",
   })
   .atTop();
 ```
@@ -441,7 +482,7 @@ For a **first-party analytics** dashboard, prefer `compose-dashboard` over hand-
 - **Never hand-author large first-party configs panel-by-panel.** Call `compose-dashboard` with the metric keys instead.
 - Unknown metric keys are skipped and reported in `unknownMetrics` (not fatal). Each panel's SQL is validated independently — valid panels save, invalid ones are reported in `invalidMetrics`.
 - By default (no `overwrite`), composing into an existing dashboard APPENDS the new panels and skips ids already present. `overwrite: true` replaces the whole config.
-- Each metric accepts an optional per-metric `window` of `'30d' | '90d' | 'all'` (only affects windowed virality/time metrics) and `title` / `chartType` / `width` overrides.
+- Each metric accepts an optional per-metric `window` of `'30d' | '90d' | 'all'` (only affects windowed virality/time metrics) and `title` / `chartType` / `width` overrides. Request `'all'` only when the user asks for all-time coverage, and describe it as full available history.
 - Returns `{ dashboardId, panelCount, createdMetrics, unknownMetrics, invalidMetrics, skippedExistingIds }` — report `panelCount` as proof-of-done.
 
 Available metric keys: `total-signups`, `signups-over-time`, `signups-by-template`, `sessions-by-app`, `sessions-over-time`, `replay-sessions`, `replay-chunks-over-time`, `recent-replay-sessions`, `signed-in-vs-anon`, `total-template-clicks`, `total-demo-clicks`, `total-cli-copies`, `template-interest-over-time`, `clicks-by-template`, `demo-clicks-by-template`, `cli-copies-by-template`, `cli-copies-over-time`, `pageviews-over-time`, `top-referrer-domains`, `referred-signups-30d`, `viral-signup-share-30d`, `clip-share-signups-30d`, `signups-by-referral-source`, `referred-signups-over-time`, `top-referrers`, `share-funnel-30d`, `viral-participation-rate-90d`, `viral-coefficient-90d`, `activated-referrers-90d`.

package/corpus/templates/analytics/AGENTS.md

@@ -119,11 +119,11 @@ details live in `.agents/skills/`.
   without raw replay events or storage references. Do not add replay blob or
   dashboard mutation actions to this catalog without an explicit security
   review.
-- While Demo mode is enabled, session and error identities display anonymized
-  (`anonymous@builder.io`), so incident lookups must filter by the stable
+- Demo mode is a browser-local presentation preference. Analytics backend
+  actions, agent/MCP reads, session replays, and error issues always return real
+  authorized identities, so incident lookups should use the actual
   `userId`/email parameter (e.g. `userId: "user@example.com"`) or recording/
-  issue id — never by matching emails read back from previously displayed
-  output.
+  issue id.
 - Analytics keeps its direct MCP surface explicitly curated, so external
   agents should use `ask_app` for multi-step investigation and changes. The
   six incident reads above are bounded, user/org-scoped fallback tools for

package/corpus/templates/analytics/actions/compose-dashboard.ts

@@ -11,6 +11,7 @@ import {
 } from "@agent-native/core/server";
 import { z } from "zod";
 
+import { validateFirstPartyDashboardTimeScope } from "../server/lib/dashboard-time-scope";
 import {
   getDashboard,
   upsertDashboard,
@@ -138,7 +139,7 @@ export default defineAction({
     "If the dashboard already exists and `overwrite` is false (default), the new panels are APPENDED (panels whose id is already present are skipped); with `overwrite: true` the config is replaced. " +
     "Returns { dashboardId, panelCount, createdMetrics, unknownMetrics, invalidMetrics, urlPath, deepLink, message } — use panelCount as proof-of-done. " +
     `Available metric keys: ${METRIC_KEYS.join(", ")}. ` +
-    "Each metric accepts an optional per-metric `window` of '30d' | '90d' | 'all' (only affects windowed virality/time metrics).",
+    "Each metric accepts an optional per-metric `window` of '30d' | '90d' | 'all' (only affects windowed virality/time metrics). Catalog panels are time-scoped by construction; custom first-party SQL added later must use `{{timeRange}}` or declare `config.timeScope`.",
   schema: z.object({
     dashboardId: z
       .string()
@@ -200,6 +201,7 @@ export default defineAction({
     const unknownMetrics: string[] = [];
     const invalidMetrics: Array<{ metric: string; reason: string }> = [];
     const composedPanels: ComposedPanel[] = [];
+    const catalogDashboard = withFirstPartyDashboardFilters({ filters: [] });
 
     for (const req of requests) {
       const panel = buildPanel(req.metric, {
@@ -220,6 +222,15 @@ export default defineAction({
       // rest of the dashboard still builds. (Catalog SQL is known-good, so this
       // is a defensive net, e.g. if a future window/override produces bad SQL.)
       try {
+        const timeScopeError = validateFirstPartyDashboardTimeScope(
+          panel,
+          catalogDashboard,
+          0,
+        );
+        if (timeScopeError) {
+          invalidMetrics.push({ metric: req.metric, reason: timeScopeError });
+          continue;
+        }
         validateFirstPartyAnalyticsSql(panel.sql);
       } catch (e: any) {
         invalidMetrics.push({

package/corpus/templates/analytics/actions/dashboard-mutation-api.ts

@@ -32,6 +32,17 @@ type DashboardPatch = {
   parentId?: string;
 };
 
+type PanelTimeScope =
+  | "dashboard"
+  | "fixed-window"
+  | "cohort-history"
+  | "all-time";
+
+type PanelConfig = Record<string, unknown> & {
+  /** Use "dashboard" for AI-generated first-party panels by default. */
+  timeScope?: PanelTimeScope;
+};
+
 type PanelPatch = {
   title?: string;
   sql?: string;
@@ -40,7 +51,7 @@ type PanelPatch = {
   width?: number;
   columns?: number;
   tab?: string;
-  config?: Record<string, unknown>;
+  config?: PanelConfig;
   description?: string; // shorthand for config.description
 };
 
@@ -112,9 +123,9 @@ export const DASHBOARD_MUTATION_EXAMPLES = [
   'dashboard.panelsMatching({"source":"first-party"}).setWidth(2);',
   'dashboard.panel("retention").setConfigPath("yAxis.format","percent");',
   'dashboard.section("retention-activity-section").append(["repeat-users","retention-over-time"]);',
-  'dashboard.insertPanel({"id":"new-kpi","title":"New KPI","source":"first-party","chartType":"metric","width":1,"sql":"SELECT COUNT(*) AS value FROM analytics_events"}).atTop();',
-  'dashboard.insertPanel({"id":"new-chart","title":"New Chart","source":"first-party","chartType":"line","width":1,"sql":"SELECT date, COUNT(*) AS value FROM analytics_events GROUP BY date ORDER BY date"}).nextTo("retention-over-time");',
-  'dashboard.insertPanel({"id":"row-chart","title":"Row Chart","source":"first-party","chartType":"bar","width":1,"sql":"SELECT name, COUNT(*) AS value FROM analytics_events GROUP BY name"}).atRow(2);',
+  `dashboard.insertPanel({"id":"new-kpi","title":"New KPI","source":"first-party","chartType":"metric","width":1,"config":{"timeScope":"dashboard"},"sql":"SELECT COUNT(*) AS value FROM analytics_events WHERE event_date >= '{{dateStart}}' AND event_date < '{{dateEnd}}'"}).atTop();`,
+  `dashboard.insertPanel({"id":"new-chart","title":"New Chart","source":"first-party","chartType":"line","width":1,"config":{"timeScope":"dashboard"},"sql":"SELECT event_date AS date, COUNT(*) AS value FROM analytics_events WHERE event_date >= '{{dateStart}}' AND event_date < '{{dateEnd}}' GROUP BY event_date ORDER BY event_date"}).nextTo("retention-over-time");`,
+  `dashboard.insertPanel({"id":"row-chart","title":"Row Chart","source":"first-party","chartType":"bar","width":1,"config":{"timeScope":"dashboard"},"sql":"SELECT event_name AS name, COUNT(*) AS value FROM analytics_events WHERE event_date >= '{{dateStart}}' AND event_date < '{{dateEnd}}' GROUP BY event_name"}).atRow(2);`,
   'dashboard.insertPanel({"id":"pipeline-widget","title":"Pipeline Widget","chartType":"extension","width":3,"config":{"extensionId":"<existing-extension-id>"}}).atBottom();',
 ] as const;
 

package/corpus/templates/analytics/actions/mutate-dashboard.ts

@@ -122,6 +122,7 @@ const apiHelp =
   "Subjects: dashboard.set, dashboard.panel, dashboard.panels, dashboard.panelsMatching, dashboard.section, dashboard.insertPanel. " +
   "Selection methods: moveToTop, moveToBottom, moveBefore, moveAfter, moveToIndex, moveNextTo, moveToRow, remove, set, setTitle, setSql, setWidth, setConfig, setConfigPath, duplicate. " +
   "Inserted panels support atTop, atBottom, before, after, atIndex, nextTo, atRow, atRowStart, and atRowEnd. Use nextTo(panelId) or atRow(rowNumber) for visible row placement. " +
+  "AI-generated first-party panels are dashboard-time-bound by default: set config.timeScope to dashboard and include a matching dashboard time filter in SQL. Allowed values are dashboard, fixed-window, cohort-history, and all-time; use all-time only when the user requests full available history and put all-time, lifetime, or historical in the title or description. A {{timeRange}} token requires the timeRange select filter; {{<id>Start}}/{{<id>End}} require a matching date-range filter. Server validation rejects unbound first-party SQL. " +
   `Examples: ${DASHBOARD_MUTATION_EXAMPLES.slice(0, 5).join(" ")}`;
 
 function resolveScope() {
@@ -198,7 +199,7 @@ export default defineAction({
     "Apply general SQL dashboard edits through a small typed mutation API in ONE atomic save. " +
     "Prefer this for dashboard layout and panel edits: move panels by id, edit titles/SQL/width/config, remove panels, duplicate panels, insert panels, or patch dashboard fields. " +
     "For user placement requests like 'second row' or 'next to return rates', use row-aware placement such as `dashboard.insertPanel(...).nextTo(\"retention-over-time\")` or `.atRow(2)`, then verify rendered rows from `get-sql-dashboard.layout.groups`. " +
-    "This is code-shaped but not arbitrary code execution: the server parses the allowed dashboard methods, validates the resulting config with the same invariants as update-dashboard, saves once, syncs collab, and returns compact proof. " +
+    "This is code-shaped but not arbitrary code execution: the server parses the allowed dashboard methods, validates the resulting config with the same invariants as update-dashboard, saves once, syncs collab, and returns compact proof. First-party SQL must be explicitly time-bound as described in the API help; server validation rejects unbound first-party SQL. " +
     "The main code argument is a string, so it avoids brittle JSON-pointer indexes and native-array serialization issues. " +
     `Common example: ${DASHBOARD_MUTATION_EXAMPLES[0]}`,
   schema: z.object({