@agent-native/core 0.99.1 → 0.99.2

package/corpus/core/src/client/settings/DemoModeSection.tsx

@@ -1,61 +1,12 @@
-/**
- * <DemoModeSection /> — toggle that replaces emails and numbers with realistic
- * fake data everywhere (UI + what the agent sees) while preserving names,
- * free text, labels, IDs, and structure so the app keeps working.
- *
- * The toggle is stored in application_state under `demo-mode`
- * (`{ enabled: boolean }`) and written via `PUT
- * /_agent-native/application-state/demo-mode` (optimistic — flip first,
- * write in the background). It READS from `/_agent-native/demo/status`
- * instead, which ORs the per-user toggle with the `DEMO_MODE` env: a hosted
- * demo deployment is forced on and the switch is locked so it can't be
- * accidentally turned off on stage.
- */
+/** Browser-local presentation toggle. Backend and agent results stay real. */
 
 import { IconEyeOff } from "@tabler/icons-react";
-import { useEffect, useState } from "react";
 
-import { agentNativePath } from "../api-path.js";
+import { setBrowserDemoModeEnabled } from "../../demo/browser-state.js";
 import { useDemoModeStatus } from "../use-demo-mode-status.js";
 
-const DEMO_MODE_WRITE_URL = agentNativePath(
-  "/_agent-native/application-state/demo-mode",
-);
-
 export function DemoModeSection() {
-  const [enabled, setEnabled] = useState<boolean | null>(null);
-  const { enabled: serverEnabled, forced, isLoading } = useDemoModeStatus();
-
-  // Surface the server value once it arrives (and on subsequent polls), but
-  // never clobber an in-flight optimistic toggle with a stale read. When
-  // forced by env, always reflect the locked-on state.
-  useEffect(() => {
-    if (forced) {
-      setEnabled(true);
-    } else if (!isLoading) {
-      setEnabled((prev) => (prev === null ? serverEnabled : prev));
-    }
-  }, [serverEnabled, forced, isLoading]);
-
-  const toggle = async (next: boolean) => {
-    if (forced) return;
-    const previous = enabled;
-    // Optimistic: flip immediately, write in the background.
-    setEnabled(next);
-    try {
-      const res = await fetch(DEMO_MODE_WRITE_URL, {
-        method: "PUT",
-        headers: { "Content-Type": "application/json" },
-        credentials: "include",
-        body: JSON.stringify({ enabled: next }),
-      });
-      if (!res.ok) {
-        throw new Error(`HTTP ${res.status}`);
-      }
-    } catch {
-      setEnabled(previous);
-    }
-  };
+  const { enabled } = useDemoModeStatus();
 
   return (
     <div className="flex items-start justify-between gap-3 rounded-md border border-border bg-accent/30 px-2.5 py-2">
@@ -64,30 +15,23 @@ export function DemoModeSection() {
           Enable demo mode
         </div>
         <p className="text-[10px] text-muted-foreground mt-0.5">
-          Anonymize emails in the UI and reshape supported dashboard charts for
-          presentations. Agent-visible emails and numbers are also anonymized.
-          Names, labels, IDs, and structure stay intact.
+          Anonymize displayed emails in this browser and reshape supported
+          dashboard charts for presentations. Backend, MCP, and agent results
+          stay real and access-scoped.
         </p>
-        {forced && (
-          <p className="text-[10px] text-muted-foreground mt-0.5">
-            Enforced by the <code>DEMO_MODE</code> environment variable — can't
-            be turned off here.
-          </p>
-        )}
       </div>
       <button
         type="button"
         role="switch"
-        aria-checked={!!enabled}
+        aria-checked={enabled}
         aria-label="Enable demo mode"
-        disabled={enabled === null || forced}
-        onClick={() => toggle(!enabled)}
+        onClick={() => setBrowserDemoModeEnabled(!enabled)}
         // Theme tokens; streaming agent owns layout.
         className={`relative inline-flex h-4 w-7 shrink-0 cursor-pointer items-center rounded-full transition-colors ${
           enabled
             ? "bg-primary"
             : "bg-muted-foreground/30 hover:bg-muted-foreground/50"
-        } ${enabled === null || forced ? "opacity-60" : ""}`}
+        }`}
       >
         <span
           className={`inline-block h-3 w-3 transform rounded-full bg-background transition-transform ${

package/corpus/core/src/client/settings/SettingsPanel.tsx

@@ -2790,7 +2790,7 @@ function SettingsPanelContent({
             id={settingsSectionDomId("demo-mode")}
             icon={<IconEyeOff size={14} />}
             title="Demo mode"
-            subtitle="Replace emails and numbers with realistic fake data everywhere — in the UI and what the agent sees. Names, free text, labels, IDs, and structure are preserved so the app keeps working."
+            subtitle="Replace displayed emails with realistic fake data in this browser and reshape supported charts for presentations. Backend, MCP, and agent results stay real and access-scoped."
             open={openSection === "demo-mode"}
             onToggle={() => toggle("demo-mode")}
           >

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`.