@agent-native/core 0.91.2 → 0.92.1

package/corpus/templates/analytics/.agents/skills/session-replay/SKILL.md

@@ -98,12 +98,11 @@ agent answers about browser recordings in the Analytics template.
 - Wait for all replay chunks (`isComplete`) before constructing the rrweb
   `Replayer`. Progressive chunk publishes should only update the loading bar;
   rebuilding the player mid-load desyncs the scrubber and playhead.
-- Prefer the latest sane Meta / ViewportResize frame for stage dimensions.
-  Out-of-range aspect ratios are clamped (preserve height, shrink width) before
-  handing events to rrweb so the stage does not collapse into an ultra-wide
-  ribbon and the recorded DOM stays roughly aligned. Capture also clamps the
-  same frames in `@agent-native/core` so new recordings never store absurd
-  Meta widths.
+- Pass events to `Replayer` untouched (aside from stylesheet/script sanitization
+  that prevents blank frames from live CSS loads). Let rrweb own iframe sizing
+  via Meta / ViewportResize; use those dimensions only for CSS fit-to-stage of
+  the outer wrapper. Never rewrite Meta widths or force iframe dimensions —
+  that desyncs the FullSnapshot DOM and blanks the stage.
 - The event timeline soft-highlights the active marker, auto-scrolls it into
   view (pausing briefly after manual scroll), and supports search. It appears
   beside the player from ~880px content width upward.

package/corpus/templates/analytics/.agents/skills/storing-data/SKILL.md

@@ -13,7 +13,9 @@ metadata:
 
 ## Rule
 
-All application data lives in **SQL** (SQLite locally, persistent database in production). The agent and UI share the same database. Do not store durable app data in the filesystem unless the app is explicitly running a Local File Mode artifact flow described below.
+All application data lives in **SQL** (SQLite locally, persistent database in production). The agent and UI share the same database. SQL stores structured records, metadata, references, and searchable text — not large raw file payloads. Do not store durable app data in the filesystem unless the app is explicitly running a Local File Mode artifact flow described below.
+
+Large binary or file-like payloads (images, video/audio, PDFs, ZIPs, screenshots, session replay chunks, thumbnails, generated assets, `data:` URLs, and base64 file bodies) must go through configured file/blob storage such as `uploadFile()` or `putPrivateBlob()`. Persist only the returned URL, asset id, or opaque blob handle in SQL. If storage is unavailable in hosted or persistent-database mode, fail closed with setup guidance instead of falling back to base64 in `application_state`, `settings`, `resources`, or app tables. Local SQLite-only dev fallbacks may exist for tiny assets, but they must be capped, documented as dev-only, and kept off hot list/read paths.
 
 **Local File Mode exception:** some artifact apps (Content, Plans, Slides, Dashboards, Designs, etc.) can intentionally use repo files as the source of truth for the artifact itself. This must be explicit via `agent-native.json`, `AGENT_NATIVE_MODE=local-files`, or an app-owned local-file action helper. In that mode, the UI and agent still go through app actions, but those actions read/write scoped files through `@agent-native/core/local-artifacts` instead of SQL rows. App state, auth, settings, credentials, collaboration metadata, and hosted database mode remain SQL. File-to-database or file-to-provider synchronization is an explicit sync step, not an implicit side effect of editing.
 
@@ -136,6 +138,7 @@ Polling streams database changes to the UI. When the agent writes to the databas
 - Use the `settings` store for app configuration and user preferences
 - Use `application-state` for ephemeral UI state that the agent and UI share
 - Use `oauth-tokens` for OAuth credentials
+- Use `uploadFile()` or `putPrivateBlob()` for large files/blob data and store only URLs, ids, or handles in SQL
 - Use core DB scripts (`db-schema`, `db-query`, `db-exec`, `db-patch`) for ad-hoc database operations
 - Use `db-exec --statements` instead of several separate `db-exec` calls for related writes; it is faster and rolls back the whole batch if one statement fails
 - Reach for `db-patch` instead of `db-exec UPDATE` whenever you're making a small change to a large text/JSON column — it's much cheaper on tokens
@@ -146,6 +149,7 @@ Polling streams database changes to the UI. When the agent writes to the databas
 - Don't store app state in localStorage, sessionStorage, or cookies (except for UI-only preferences like sidebar width)
 - Don't keep state only in memory (server variables, global stores)
 - Don't use Redis or any external state store for app data
+- Don't store large files, base64 blobs, `data:` URLs, screenshots, videos, audio, PDFs, ZIPs, or session replay chunks directly in SQL rows, `application_state`, `settings`, or `resources`
 - Don't implement product features with raw SQL or `getDbExec()` when Drizzle can express the query
 - Don't write SQLite-only or Postgres-only SQL in app code
 - Don't interpolate user input directly into SQL queries — use Drizzle ORM's query builder

package/corpus/templates/analytics/.agents/skills/upgrade-agent-native/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: upgrade-agent-native
+description: >-
+  Bring an older Agent Native app or workspace current. Use when updating
+  @agent-native/core, fixing a broken upgrade, or when tempted to patch or
+  override core/dispatch packages to make an old branch run.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Upgrade Agent Native
+
+## Rule
+
+When an older Agent Native app/branch needs to run on current packages, use
+`agent-native upgrade`. Never "fix" upgrade breakage with
+`pnpm.overrides`, `patchedDependencies`, `resolutions`, local patches, or
+edits under `node_modules/@agent-native/*` — especially not against
+`@agent-native/core` or `@agent-native/dispatch`.
+
+## Why
+
+Agents often respond to a failed core bump by inventing framework patches and
+dispatch behavior overrides. That hides the real app-level break, drifts from
+upstream, and makes the next upgrade worse. The supported path is bump →
+install → refresh scaffold skills → verify, then fix **app** code only.
+
+## How
+
+1. **Doctor first (optional but recommended)**
+
+   ```bash
+   npx @agent-native/core@latest upgrade check
+   ```
+
+   This reports framework overrides/patches and pending `@agent-native/*`
+   bumps. If overrides/patches are present, remove them before continuing.
+
+2. **Run the upgrade**
+
+   ```bash
+   npx @agent-native/core@latest upgrade
+   ```
+
+   Or from an already-installed CLI: `pnpm exec agent-native upgrade` /
+   `agent-native upgrade`.
+
+   What it does:
+
+   - Blocks (unless `--force`) when `@agent-native/*` overrides/patches exist
+   - Rewrites non-local `@agent-native/*` dependency pins to `latest`
+   - Runs the package manager install
+   - Runs `skills update scaffold --project`
+   - Runs `typecheck` when the project has that script
+
+3. **If upgrade or typecheck fails**
+
+   - Read the concrete error
+   - Fix **app** source, actions, config, or env — not framework packages
+   - Re-run `agent-native upgrade` or `pnpm typecheck`
+   - Stop and ask the user if you cannot fix the app-level error
+
+4. **Dry-run / partial runs**
+
+   ```bash
+   agent-native upgrade --dry-run
+   agent-native upgrade --skip-verify
+   agent-native upgrade --skip-install   # package.json bumps only
+   ```
+
+## Don't
+
+- Don't add `pnpm.overrides`, `overrides`, `resolutions`, or
+  `patchedDependencies` for any `@agent-native/*` package
+- Don't edit `node_modules/@agent-native/core` or
+  `node_modules/@agent-native/dispatch`
+- Don't invent local "dispatch behavior" shims to paper over version skew
+- Don't keep iterating with more framework patches after a failed install
+- Don't skip `skills update scaffold --project` after a core bump (the
+  upgrade command does this for you)
+
+## Related Skills
+
+- **self-modifying-code** — Tier 4: framework packages are off limits
+- **agent-native-docs** — version-matched docs after the bump
+- **portability** — keep app code provider-agnostic across upgrades

package/corpus/templates/analytics/AGENTS.md

@@ -9,6 +9,10 @@ details live in `.agents/skills/`.
 
 ## Core Rules
 
+- Store large file/blob payloads in configured file/blob storage, not SQL: no
+  base64, `data:` URLs, images, video/audio, PDFs, ZIPs, screenshots,
+  thumbnails, or replay chunks in app tables, `application_state`, `settings`,
+  or `resources`; persist URLs, ids, or handles instead.
 - Never hardcode API keys, tokens, webhook URLs, signing secrets, private Builder/internal data, customer data, or credential-looking literals. Use secrets/OAuth/runtime configuration and obvious placeholders in examples.
 - Data integrity comes first. Do not invent numbers, dimensions, filters, or
   source semantics. State uncertainty and inspect the source when needed.
@@ -84,15 +88,18 @@ details live in `.agents/skills/`.
   / `$ai_latency`, `status`, `tool_calls`, `successful_tools`, `failed_tools`,
   and `$ai_error` / `error_message`. Do not expect prompts, tool args, or model
   responses in these tracked events by default.
-- `/agents` is the Analytics home for core agent-admin surfaces. The default
-  Monitoring view embeds the shared observability dashboard for traces,
-  conversations, evals, experiments, and feedback. The Advanced menu opens
-  `/agents?view=database`, where organization owners/admins can connect other
-  agent-native app databases and use the shared database admin tool for table
-  browsing, row editing, and SQL inspection. This surface is for connected
-  target app databases, not broad access to all Analytics data. Keep future
-  agent-admin additions inside this route instead of adding many top-level
-  sidebar tabs.
+- `/agents` is the Analytics home for admin surfaces. The default Monitoring
+  view embeds the shared observability dashboard for traces, conversations,
+  evals, experiments, and feedback. `/agents?view=dashboards` shows the
+  admin-only dashboard usage audit; call `list-dashboard-usage-stats` when
+  admins ask about dashboard created/modified dates, owners, last tracked
+  modifier, views, engagements, saved views, or cleanup candidates. The
+  Advanced menu opens `/agents?view=database`, where organization owners/admins
+  can connect other agent-native app databases and use the shared database admin
+  tool for table browsing, row editing, and SQL inspection. This database
+  surface is for connected target app databases, not broad access to all
+  Analytics data. Keep future admin additions inside this route instead of
+  adding many top-level sidebar tabs.
 - For dashboard edits, default to `mutate-dashboard` with its typed
   `dashboard.*` script API. It supports id-based panel moves, title/SQL/config
   edits, inserts, duplication, removal, and dashboard field patches in one
@@ -100,6 +107,13 @@ details live in `.agents/skills/`.
   serialization traps. The script is constrained: only documented dashboard
   method calls with JSON-compatible arguments are parsed; variables, imports,
   loops, functions, network, filesystem, and DB access are not available.
+- Dashboard saves keep bounded history in SQL. Use
+  `list-dashboard-revisions` to inspect undo points and
+  `restore-dashboard-revision` to restore one instead of hand-editing history
+  rows.
+- Saved analyses also keep bounded history. Use `list-analysis-revisions` and
+  `restore-analysis-revision` for rollback after a re-run updates the saved
+  findings.
 - Do not count shifting `/panels/<index>` values for ordinary dashboard edit
   requests. Use low-level JSON-pointer edits only when explicitly requested.
 - `get-sql-dashboard` is compact by default for agents. Use its `panels`
@@ -140,11 +154,15 @@ details live in `.agents/skills/`.
   `thresholdMode: "distinct_count"` counts unique values from `distinctBy`.
   Alert notifications use the shared notification channel registry, so
   `channels` can include `inbox`, `email`, `slack`, `webhook`, or any custom
-  registered channel. Configure Slack with `NOTIFICATIONS_SLACK_WEBHOOK_URL`
-  and optional `NOTIFICATIONS_SLACK_WEBHOOK_AUTH`; configure email with
-  `NOTIFICATIONS_EMAIL_CHANNEL=1`, existing `RESEND_API_KEY` or
-  `SENDGRID_API_KEY` plus `EMAIL_FROM`, and pass per-rule `emailRecipients` or
-  the fallback `NOTIFICATIONS_EMAIL_RECIPIENTS`.
+  registered channel. Slack/webhook prefer delivery-only
+  `metadata.delivery.slackWebhookUrl` / `metadata.delivery.webhookUrl` (uptime
+  monitors store these on the monitor row), then fall back to
+  `NOTIFICATIONS_SLACK_WEBHOOK_URL` / `NOTIFICATIONS_WEBHOOK_URL`. Configure
+  optional `NOTIFICATIONS_SLACK_WEBHOOK_AUTH`; configure email with existing
+  `RESEND_API_KEY` or `SENDGRID_API_KEY` plus `EMAIL_FROM`, and pass per-rule
+  `emailRecipients` or the fallback `NOTIFICATIONS_EMAIL_RECIPIENTS`. Saving
+  explicit `emailRecipients` also remembers them as the current user's defaults
+  for the next alert rule created in Settings.
   Netlify builds emit an alert cron trigger plus background worker from
   `scripts/emit-netlify-dashboard-report-cron.ts` every five minutes; long-lived
   runtimes use the in-process scheduler unless `ANALYTICS_ALERT_JOBS=0` is set.
@@ -161,9 +179,9 @@ details live in `.agents/skills/`.
   `view="catalog"` for the template catalog, `view="sessions"` for session
   replay, `view="monitoring"` with `monitoringView="uptime|errors"` (plus the
   `monitorId`, `statusPageId`, or `errorIssueId` deep links) for uptime checks,
-  public status pages, or error triage, and `view="agents"` /
-  `agentsView="database"` with optional `dbAdminConnectionId` for agent
-  monitoring or connected app database admin.
+  public status pages, or error triage, and `view="agents"` with
+  `agentsView="dashboards|database"` plus optional `dbAdminConnectionId` for
+  dashboard usage or connected app database admin.
 - Use `view-screen` when the active dashboard/chart context is unclear.
 
 ## Session Replay
@@ -240,7 +258,10 @@ details live in `.agents/skills/`.
   `@agent-native/core/client` (`captureException` / `captureMessage` /
   `addErrorBreadcrumb`), auto-enabled by `configureTracking` and transported
   through the first-party analytics ingest as a `$exception` event. Deep link:
-  `?view=errors&issue=<id>`. See `docs/error-capture.md`.
+  `?view=errors&issue=<id>`. Issue detail includes recent frequency,
+  parsed/raw stack traces, source code snippets when available, breadcrumbs,
+  tags, occurrence history, and session replay links. See
+  `docs/error-capture.md`.
 - Session replay ↔ Errors: a recording's devtools Console error lines link to
   the grouped issue at `/monitoring?view=errors&issue=<id>`, resolved by
   `match-error-issues` (exact fingerprint match, no heuristics); issues link

package/corpus/templates/analytics/actions/capture-test-error.ts

@@ -19,10 +19,14 @@ export default defineAction({
   schema: z.object({
     message: z
       .string()
+      .trim()
+      .max(500)
       .optional()
       .describe("Optional custom error message for the sample error."),
     type: z
       .string()
+      .trim()
+      .regex(/^[A-Za-z_$][\w$.]{0,79}$/)
       .optional()
       .describe("Optional error type/name, e.g. TypeError. Defaults to Error."),
   }),

package/corpus/templates/analytics/actions/get-analytics-alert-rule-defaults.ts

@@ -0,0 +1,23 @@
+import { defineAction } from "@agent-native/core";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server";
+import { z } from "zod";
+
+import { getAnalyticsAlertRuleDefaults } from "../server/lib/analytics-alerts";
+
+export default defineAction({
+  description:
+    "Read the current user's remembered defaults for creating analytics alert rules.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  readOnly: true,
+  agentTool: false,
+  run: async () => {
+    const email = getRequestUserEmail();
+    if (!email) throw new Error("no authenticated user");
+    const orgId = getRequestOrgId() || null;
+    return getAnalyticsAlertRuleDefaults({ email, orgId });
+  },
+});

package/corpus/templates/analytics/actions/get-error-issue.ts

@@ -15,7 +15,7 @@ function resolveScope() {
 
 export default defineAction({
   description:
-    "Get one captured error issue with its recent occurrences (parsed stack frames, breadcrumbs, tags/extra) and links to the session replays where the error happened. Use this to triage a specific issue and jump to the replay.",
+    "Get one captured error issue with its recent occurrence frequency, parsed/raw stack traces, source code snippets when available, breadcrumbs, tags/extra, and links to the session replays where the error happened. Use this to triage a specific issue and jump to the replay.",
   schema: z.object({
     id: z.string().describe("Error issue id (erriss_...)."),
     eventsLimit: z.coerce

package/corpus/templates/analytics/actions/list-analysis-revisions.ts

@@ -0,0 +1,40 @@
+import { defineAction } from "@agent-native/core";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server";
+import { z } from "zod";
+
+import { listAnalysisRevisions } from "../server/lib/dashboards-store";
+
+function resolveScope() {
+  const orgId = getRequestOrgId() || null;
+  const email = getRequestUserEmail();
+  if (!email) throw new Error("no authenticated user");
+  return { orgId, email };
+}
+
+export default defineAction({
+  description: "List saved history revisions for an ad-hoc analysis.",
+  schema: z.object({
+    analysisId: z.string().describe("Analysis id to inspect"),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async (args) => {
+    const revisions = await listAnalysisRevisions(
+      args.analysisId,
+      resolveScope(),
+    );
+    return {
+      revisions: revisions.map((revision) => ({
+        id: revision.id,
+        analysisId: revision.analysisId,
+        name: revision.name,
+        description: revision.description,
+        createdAt: revision.createdAt,
+        createdBy: revision.createdBy,
+      })),
+    };
+  },
+});

package/corpus/templates/analytics/actions/list-dashboard-revisions.ts

@@ -0,0 +1,40 @@
+import { defineAction } from "@agent-native/core";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server";
+import { z } from "zod";
+
+import { listDashboardRevisions } from "../server/lib/dashboards-store";
+
+function resolveScope() {
+  const orgId = getRequestOrgId() || null;
+  const email = getRequestUserEmail();
+  if (!email) throw new Error("no authenticated user");
+  return { orgId, email };
+}
+
+export default defineAction({
+  description: "List saved dashboard history revisions for undo/restore.",
+  schema: z.object({
+    dashboardId: z.string().describe("Dashboard id to inspect"),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async (args) => {
+    const revisions = await listDashboardRevisions(
+      args.dashboardId,
+      resolveScope(),
+    );
+    return {
+      revisions: revisions.map((revision) => ({
+        id: revision.id,
+        dashboardId: revision.dashboardId,
+        kind: revision.kind,
+        title: revision.title,
+        createdAt: revision.createdAt,
+        createdBy: revision.createdBy,
+      })),
+    };
+  },
+});

package/corpus/templates/analytics/actions/list-dashboard-usage-stats.ts

@@ -0,0 +1,299 @@
+import { defineAction } from "@agent-native/core/action";
+import { buildDeepLink } from "@agent-native/core/server";
+import { and, eq, like, or, sql } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import { requireDbAdminContextFromRequest } from "../server/lib/db-admin-connections";
+
+type DashboardUsageStats = {
+  id: string;
+  name: string;
+  kind: "explorer" | "sql";
+  ownerEmail: string | null;
+  visibility: "private" | "org" | "public";
+  createdAt: string;
+  updatedAt: string;
+  updatedBy: string | null;
+  archivedAt: string | null;
+  hiddenAt: string | null;
+  hiddenBy: string | null;
+  viewCount: number;
+  engagementCount: number;
+  eventEngagementCount: number;
+  savedViewCount: number;
+  uniqueUserCount: number;
+  lastViewedAt: string | null;
+  lastSavedViewAt: string | null;
+  panelCount: number | null;
+  url: string;
+};
+
+function toNumber(value: unknown): number {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "bigint") return Number(value);
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : 0;
+  }
+  return 0;
+}
+
+function parseConfig(value: unknown): Record<string, unknown> {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return value as Record<string, unknown>;
+  }
+  if (typeof value !== "string") return {};
+  try {
+    const parsed = JSON.parse(value);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? parsed
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+function dashboardName(row: { title: string; config: unknown }): string {
+  const config = parseConfig(row.config);
+  const configName = config.name;
+  if (typeof configName === "string" && configName.trim()) {
+    return configName.trim();
+  }
+  return row.title || "Untitled";
+}
+
+function dashboardPanelCount(row: {
+  kind: string;
+  config: unknown;
+}): number | null {
+  if (row.kind !== "sql") return null;
+  const panels = parseConfig(row.config).panels;
+  return Array.isArray(panels) ? panels.length : 0;
+}
+
+export function dashboardIdFromPath(path: string | null): string | null {
+  const pathname = path ?? "";
+  const match = pathname.match(/(?:^|\/)(?:dashboards|adhoc)\/([^/?#]+)/);
+  if (!match) return null;
+  if (match[1] === "explorer-dashboard") {
+    return null;
+  }
+  try {
+    return decodeURIComponent(match[1]);
+  } catch {
+    return match[1];
+  }
+}
+
+export function dashboardIdFromEventLocation(
+  path: string | null,
+  url: string | null,
+): string | null {
+  const direct = dashboardIdFromPath(path);
+  if (direct) return direct;
+  const raw = url || path;
+  if (!raw) return null;
+  try {
+    const parsed = new URL(raw, "https://analytics.local");
+    if (
+      /(?:^|\/)(?:dashboards|adhoc)\/explorer-dashboard$/.test(parsed.pathname)
+    ) {
+      const id = parsed.searchParams.get("id");
+      return id && id.trim() ? id : null;
+    }
+  } catch {
+    // Fall through to regex below for malformed relative strings.
+  }
+  const match = raw.match(
+    /(?:^|\/)(?:dashboards|adhoc)\/explorer-dashboard(?:\?[^#]*)?[?&]id=([^&#]+)/,
+  );
+  if (!match) return null;
+  try {
+    return decodeURIComponent(match[1].replace(/\+/g, " "));
+  } catch {
+    return match[1];
+  }
+}
+
+function dashboardUrl(row: { id: string; kind: string }): string {
+  return row.kind === "explorer"
+    ? `/dashboards/explorer-dashboard?id=${encodeURIComponent(row.id)}`
+    : `/dashboards/${encodeURIComponent(row.id)}`;
+}
+
+export default defineAction({
+  description:
+    "List admin-only dashboard usage and cleanup stats for every dashboard in the active organization. Includes lifecycle metadata, owner, last tracked modifier, pageviews, engagement events, unique viewers, saved view counts, archive/hidden state, and dashboard links. Requires active organization owner/admin role.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  readOnly: true,
+  link: () => ({
+    url: buildDeepLink({
+      app: "analytics",
+      view: "agents",
+      params: { agentsView: "dashboards" },
+    }),
+    label: "Open dashboard usage admin",
+    view: "agents",
+  }),
+  run: async (_args, ctx) => {
+    const admin = await requireDbAdminContextFromRequest(ctx);
+    const db = getDb() as any;
+
+    // guard:allow-unscoped — org owner/admin audit intentionally spans all
+    // dashboard rows in the active org after requireDbAdminContextFromRequest.
+    const dashboardRows = await db
+      .select()
+      .from(schema.dashboards)
+      .where(eq(schema.dashboards.orgId, admin.orgId));
+
+    const dashboardIds = new Set<string>(
+      dashboardRows.map((row: { id: string }) => row.id),
+    );
+
+    const savedViewRows = await db
+      .select({
+        dashboardId: schema.dashboardViews.dashboardId,
+        count: sql<number>`count(*)`,
+        lastSavedViewAt: sql<
+          string | null
+        >`max(${schema.dashboardViews.createdAt})`,
+      })
+      .from(schema.dashboardViews)
+      .groupBy(schema.dashboardViews.dashboardId);
+
+    const savedViewsByDashboard = new Map<
+      string,
+      { count: number; lastSavedViewAt: string | null }
+    >();
+    for (const row of savedViewRows as Array<{
+      dashboardId: string;
+      count: unknown;
+      lastSavedViewAt: string | null;
+    }>) {
+      if (!dashboardIds.has(row.dashboardId)) continue;
+      savedViewsByDashboard.set(row.dashboardId, {
+        count: toNumber(row.count),
+        lastSavedViewAt: row.lastSavedViewAt ?? null,
+      });
+    }
+
+    const analyticsUserIdentity = sql<
+      string | null
+    >`coalesce(nullif(${schema.analyticsEvents.userKey}, ''), nullif(${schema.analyticsEvents.userId}, ''), nullif(${schema.analyticsEvents.anonymousId}, ''), nullif(${schema.analyticsEvents.sessionId}, ''))`;
+    const eventRows = await db
+      .select({
+        path: schema.analyticsEvents.path,
+        url: schema.analyticsEvents.url,
+        eventName: schema.analyticsEvents.eventName,
+        count: sql<number>`count(*)`,
+        userIdentity: analyticsUserIdentity,
+        lastSeenAt: sql<
+          string | null
+        >`max(${schema.analyticsEvents.receivedAt})`,
+      })
+      .from(schema.analyticsEvents)
+      .where(
+        and(
+          eq(schema.analyticsEvents.orgId, admin.orgId),
+          or(
+            like(schema.analyticsEvents.path, "%/dashboards/%"),
+            like(schema.analyticsEvents.path, "%/adhoc/%"),
+            like(schema.analyticsEvents.url, "%/dashboards/%"),
+            like(schema.analyticsEvents.url, "%/adhoc/%"),
+          ),
+        ),
+      )
+      .groupBy(
+        schema.analyticsEvents.path,
+        schema.analyticsEvents.url,
+        schema.analyticsEvents.eventName,
+        analyticsUserIdentity,
+      );
+
+    const eventsByDashboard = new Map<
+      string,
+      {
+        viewCount: number;
+        eventEngagementCount: number;
+        uniqueUsers: Set<string>;
+        lastViewedAt: string | null;
+      }
+    >();
+    for (const row of eventRows as Array<{
+      path: string | null;
+      url: string | null;
+      eventName: string;
+      count: unknown;
+      userIdentity: string | null;
+      lastSeenAt: string | null;
+    }>) {
+      const dashboardId = dashboardIdFromEventLocation(row.path, row.url);
+      if (!dashboardId || !dashboardIds.has(dashboardId)) continue;
+      const current = eventsByDashboard.get(dashboardId) ?? {
+        viewCount: 0,
+        eventEngagementCount: 0,
+        uniqueUsers: new Set<string>(),
+        lastViewedAt: null,
+      };
+      const count = toNumber(row.count);
+      if (row.eventName === "pageview") {
+        current.viewCount += count;
+        current.lastViewedAt =
+          !current.lastViewedAt ||
+          (row.lastSeenAt && row.lastSeenAt > current.lastViewedAt)
+            ? (row.lastSeenAt ?? current.lastViewedAt)
+            : current.lastViewedAt;
+      } else {
+        current.eventEngagementCount += count;
+      }
+      if (row.userIdentity) current.uniqueUsers.add(row.userIdentity);
+      eventsByDashboard.set(dashboardId, current);
+    }
+
+    return (dashboardRows as Array<any>)
+      .map((row): DashboardUsageStats => {
+        const savedViews = savedViewsByDashboard.get(row.id) ?? {
+          count: 0,
+          lastSavedViewAt: null,
+        };
+        const events = eventsByDashboard.get(row.id) ?? {
+          viewCount: 0,
+          eventEngagementCount: 0,
+          uniqueUsers: new Set<string>(),
+          lastViewedAt: null,
+        };
+        return {
+          id: row.id,
+          name: dashboardName(row),
+          kind: row.kind === "explorer" ? "explorer" : "sql",
+          ownerEmail: row.ownerEmail ?? null,
+          visibility:
+            row.visibility === "org" || row.visibility === "public"
+              ? row.visibility
+              : "private",
+          createdAt: row.createdAt,
+          updatedAt: row.updatedAt,
+          updatedBy: row.updatedBy ?? null,
+          archivedAt: row.archivedAt ?? null,
+          hiddenAt: row.hiddenAt ?? null,
+          hiddenBy: row.hiddenBy ?? null,
+          viewCount: events.viewCount,
+          eventEngagementCount: events.eventEngagementCount,
+          savedViewCount: savedViews.count,
+          engagementCount: events.eventEngagementCount + savedViews.count,
+          uniqueUserCount: events.uniqueUsers.size,
+          lastViewedAt: events.lastViewedAt,
+          lastSavedViewAt: savedViews.lastSavedViewAt,
+          panelCount: dashboardPanelCount(row),
+          url: dashboardUrl(row),
+        };
+      })
+      .sort((a, b) => {
+        const views = b.viewCount - a.viewCount;
+        if (views !== 0) return views;
+        return b.updatedAt.localeCompare(a.updatedAt);
+      });
+  },
+});