@agent-native/core 0.72.3 → 0.73.0

package/corpus/templates/analytics/server/lib/first-party-metric-catalog.ts

@@ -88,6 +88,18 @@ function fixed(sql: string): (window?: MetricWindow) => string {
   return () => sql;
 }
 
+const SIGNUP_TEMPLATE_EXPR =
+  "COALESCE(NULLIF(template, ''), NULLIF(properties::jsonb ->> 'templateId', ''), NULLIF(properties::jsonb ->> 'agent_native_template', ''), NULLIF(properties::jsonb ->> 'agentNativeTemplate', ''), NULLIF(app, ''), NULLIF(properties::jsonb ->> 'agent_native_app', ''), NULLIF(properties::jsonb ->> 'agentNativeApp', ''), 'unknown')";
+const DASHBOARD_TIME_RANGE_FILTER =
+  "('{{timeRange}}' IN ('', 'all') OR ('{{timeRange}}' = '7d' AND substr(timestamp, 1, 10) >= to_char(CURRENT_DATE - INTERVAL '7 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '30d' AND substr(timestamp, 1, 10) >= to_char(CURRENT_DATE - INTERVAL '30 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '90d' AND substr(timestamp, 1, 10) >= to_char(CURRENT_DATE - INTERVAL '90 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '180d' AND substr(timestamp, 1, 10) >= to_char(CURRENT_DATE - INTERVAL '180 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '365d' AND substr(timestamp, 1, 10) >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD')))";
+const DASHBOARD_EMAIL_FILTER =
+  "('{{emailFilter}}' IN ('', 'all') OR ('{{emailFilter}}' = 'exclude_builder' AND lower(coalesce(user_id, '')) NOT LIKE '%@builder.io') OR ('{{emailFilter}}' = 'only_builder' AND lower(coalesce(user_id, '')) LIKE '%@builder.io'))";
+const TOTAL_SIGNUPS_SQL = `SELECT COUNT(*) AS signups FROM analytics_events WHERE event_name = 'signup' AND ${DASHBOARD_TIME_RANGE_FILTER} AND ${DASHBOARD_EMAIL_FILTER}`;
+const SIGNUPS_OVER_TIME_SQL = `WITH offsets AS (SELECT (ROW_NUMBER() OVER (ORDER BY timestamp) - 1)::int AS n FROM analytics_events LIMIT 800), signup_events AS (SELECT substr(timestamp, 1, 10) AS date, ${SIGNUP_TEMPLATE_EXPR} AS template FROM analytics_events WHERE event_name = 'signup' AND ${DASHBOARD_TIME_RANGE_FILTER} AND ${DASHBOARD_EMAIL_FILTER}), bounds AS (SELECT MIN(date::date) AS start_date, MAX(date::date) AS end_date FROM signup_events), dates AS (SELECT to_char(bounds.start_date + offsets.n, 'YYYY-MM-DD') AS date FROM bounds CROSS JOIN offsets WHERE bounds.start_date IS NOT NULL AND bounds.start_date + offsets.n <= bounds.end_date), templates AS (SELECT DISTINCT template FROM signup_events), daily AS (SELECT date, template, COUNT(*) AS count FROM signup_events GROUP BY date, template) SELECT dates.date, templates.template, COALESCE(daily.count, 0) AS count FROM dates CROSS JOIN templates LEFT JOIN daily ON daily.date = dates.date AND daily.template = templates.template ORDER BY dates.date, templates.template`;
+const ONE_DAY_RETENTION_BY_TEMPLATE_SQL = `WITH base AS (SELECT COALESCE(NULLIF(user_id, ''), NULLIF(anonymous_id, '')) AS user_key, ${SIGNUP_TEMPLATE_EXPR} AS template, substr(timestamp, 1, 10) AS event_date, user_id FROM analytics_events WHERE COALESCE(NULLIF(user_id, ''), NULLIF(anonymous_id, '')) IS NOT NULL AND ${DASHBOARD_EMAIL_FILTER}), first_seen AS (SELECT user_key, template, MIN(event_date) AS cohort_date FROM base GROUP BY user_key, template), cohorts AS (SELECT user_key, template, cohort_date FROM first_seen WHERE cohort_date <= to_char(CURRENT_DATE - INTERVAL '1 day', 'YYYY-MM-DD') AND ('{{timeRange}}' IN ('', 'all') OR ('{{timeRange}}' = '7d' AND cohort_date >= to_char(CURRENT_DATE - INTERVAL '7 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '30d' AND cohort_date >= to_char(CURRENT_DATE - INTERVAL '30 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '90d' AND cohort_date >= to_char(CURRENT_DATE - INTERVAL '90 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '180d' AND cohort_date >= to_char(CURRENT_DATE - INTERVAL '180 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '365d' AND cohort_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD')))) SELECT c.cohort_date AS date, c.template, COALESCE(COUNT(DISTINCT c.user_key) FILTER (WHERE b.event_date = to_char(c.cohort_date::date + INTERVAL '1 day', 'YYYY-MM-DD'))::float / NULLIF(COUNT(DISTINCT c.user_key), 0), 0) AS rate FROM cohorts c LEFT JOIN base b ON b.user_key = c.user_key AND b.template = c.template GROUP BY c.cohort_date, c.template ORDER BY c.cohort_date, c.template`;
+const SEVEN_DAY_RETENTION_BY_TEMPLATE_SQL = `WITH base AS (SELECT COALESCE(NULLIF(user_id, ''), NULLIF(anonymous_id, '')) AS user_key, ${SIGNUP_TEMPLATE_EXPR} AS template, substr(timestamp, 1, 10) AS event_date, user_id FROM analytics_events WHERE COALESCE(NULLIF(user_id, ''), NULLIF(anonymous_id, '')) IS NOT NULL AND ${DASHBOARD_EMAIL_FILTER}), first_seen AS (SELECT user_key, template, MIN(event_date) AS cohort_date FROM base GROUP BY user_key, template), cohorts AS (SELECT user_key, template, cohort_date FROM first_seen WHERE cohort_date <= to_char(CURRENT_DATE - INTERVAL '7 days', 'YYYY-MM-DD') AND ('{{timeRange}}' IN ('', 'all') OR ('{{timeRange}}' = '7d' AND cohort_date >= to_char(CURRENT_DATE - INTERVAL '7 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '30d' AND cohort_date >= to_char(CURRENT_DATE - INTERVAL '30 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '90d' AND cohort_date >= to_char(CURRENT_DATE - INTERVAL '90 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '180d' AND cohort_date >= to_char(CURRENT_DATE - INTERVAL '180 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '365d' AND cohort_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD')))) SELECT c.cohort_date AS date, c.template, COALESCE(COUNT(DISTINCT c.user_key) FILTER (WHERE b.event_date = to_char(c.cohort_date::date + INTERVAL '7 days', 'YYYY-MM-DD'))::float / NULLIF(COUNT(DISTINCT c.user_key), 0), 0) AS rate FROM cohorts c LEFT JOIN base b ON b.user_key = c.user_key AND b.template = c.template GROUP BY c.cohort_date, c.template ORDER BY c.cohort_date, c.template`;
+const SIGNUPS_BY_TEMPLATE_SQL = `SELECT ${SIGNUP_TEMPLATE_EXPR} AS template, COUNT(*) AS count FROM analytics_events WHERE event_name = 'signup' AND ${DASHBOARD_TIME_RANGE_FILTER} AND ${DASHBOARD_EMAIL_FILTER} GROUP BY ${SIGNUP_TEMPLATE_EXPR} ORDER BY count DESC`;
+
 /**
  * Catalog entries. Order here is the default panel order when a caller passes
  * metrics; callers can reorder by listing keys in the order they want.
@@ -96,19 +108,16 @@ const ENTRIES: FirstPartyMetric[] = [
   // --- Signups -------------------------------------------------------------
   {
     key: "total-signups",
-    title: "Signups",
+    title: "Total Signups",
     chartType: "metric",
     source: "first-party",
     width: 1,
     windowed: false,
-    buildSql: fixed(
-      "SELECT COUNT(*) AS count FROM analytics_events WHERE event_name = 'signup'",
-    ),
+    buildSql: fixed(TOTAL_SIGNUPS_SQL),
     config: {
-      yKey: "count",
+      yKey: "signups",
       yFormatter: "number",
-      description:
-        "Better Auth user creation events from all Agent Native templates",
+      description: "Total signup events in the selected time range.",
     },
   },
   {
@@ -118,14 +127,18 @@ const ENTRIES: FirstPartyMetric[] = [
     source: "first-party",
     width: 2,
     windowed: false,
-    buildSql: fixed(
-      "SELECT substr(timestamp, 1, 10) AS date, COUNT(*) AS count FROM analytics_events WHERE event_name = 'signup' GROUP BY substr(timestamp, 1, 10) ORDER BY date",
-    ),
+    buildSql: fixed(SIGNUPS_OVER_TIME_SQL),
     config: {
       xKey: "date",
       yKey: "count",
-      color: "#8b5cf6",
-      description: "Daily signup events across all Agent Native templates",
+      yFormatter: "number",
+      pivot: {
+        xKey: "date",
+        seriesKey: "template",
+        valueKey: "count",
+      },
+      stacked: true,
+      description: "Daily signup events stacked by inferred template/app.",
     },
   },
   {
@@ -133,16 +146,15 @@ const ENTRIES: FirstPartyMetric[] = [
     title: "Signups by Template",
     chartType: "bar",
     source: "first-party",
-    width: 1,
+    width: 2,
     windowed: false,
-    buildSql: fixed(
-      "SELECT COALESCE(NULLIF(template, ''), NULLIF(app, ''), 'unknown') AS template, COUNT(*) AS count FROM analytics_events WHERE event_name = 'signup' GROUP BY COALESCE(NULLIF(template, ''), NULLIF(app, ''), 'unknown') ORDER BY count DESC LIMIT 20",
-    ),
+    buildSql: fixed(SIGNUPS_BY_TEMPLATE_SQL),
     config: {
       xKey: "template",
       yKey: "count",
-      color: "#8b5cf6",
-      description: "Signup events grouped by inferred template/app",
+      yFormatter: "number",
+      color: "var(--brand-purple)",
+      description: "Signup events grouped by inferred template/app.",
     },
   },
 
@@ -253,45 +265,85 @@ const ENTRIES: FirstPartyMetric[] = [
     width: 2,
     windowed: false,
     buildSql: fixed(
-      "SELECT substr(timestamp, 1, 10) AS date, COUNT(*) AS count FROM analytics_events WHERE event_name = 'click template' GROUP BY substr(timestamp, 1, 10) ORDER BY date",
+      "SELECT substr(timestamp, 1, 10) AS date, COALESCE(NULLIF(template, ''), 'unknown') AS template, COUNT(*) AS count FROM analytics_events WHERE event_name = 'click template' GROUP BY substr(timestamp, 1, 10), COALESCE(NULLIF(template, ''), 'unknown') ORDER BY date, template",
     ),
-    config: { xKey: "date", yKey: "count", color: "var(--brand-blue)" },
+    config: {
+      xKey: "date",
+      yKey: "count",
+      yFormatter: "number",
+      pivot: {
+        xKey: "date",
+        seriesKey: "template",
+        valueKey: "count",
+      },
+      stacked: true,
+    },
   },
   {
     key: "clicks-by-template",
-    title: "Clicks by Template",
-    chartType: "bar",
+    title: "Clicks by Template Over Time",
+    chartType: "area",
     source: "first-party",
-    width: 1,
+    width: 2,
     windowed: false,
     buildSql: fixed(
-      "SELECT COALESCE(NULLIF(template, ''), 'unknown') AS template, COUNT(*) AS count FROM analytics_events WHERE event_name = 'click template' GROUP BY COALESCE(NULLIF(template, ''), 'unknown') ORDER BY count DESC LIMIT 20",
+      "SELECT substr(timestamp, 1, 10) AS date, COALESCE(NULLIF(template, ''), 'unknown') AS template, COUNT(*) AS count FROM analytics_events WHERE event_name = 'click template' GROUP BY substr(timestamp, 1, 10), COALESCE(NULLIF(template, ''), 'unknown') ORDER BY date, template",
     ),
-    config: { xKey: "template", yKey: "count", color: "var(--brand-blue)" },
+    config: {
+      xKey: "date",
+      yKey: "count",
+      yFormatter: "number",
+      pivot: {
+        xKey: "date",
+        seriesKey: "template",
+        valueKey: "count",
+      },
+      stacked: true,
+    },
   },
   {
     key: "demo-clicks-by-template",
-    title: "Try-Demo Clicks by Template",
-    chartType: "bar",
+    title: "Try-Demo Clicks Over Time",
+    chartType: "area",
     source: "first-party",
-    width: 1,
+    width: 2,
     windowed: false,
     buildSql: fixed(
-      "SELECT COALESCE(NULLIF(template, ''), 'unknown') AS template, COUNT(*) AS count FROM analytics_events WHERE event_name = 'click try demo' GROUP BY COALESCE(NULLIF(template, ''), 'unknown') ORDER BY count DESC LIMIT 20",
+      "SELECT substr(timestamp, 1, 10) AS date, COALESCE(NULLIF(template, ''), 'unknown') AS template, COUNT(*) AS count FROM analytics_events WHERE event_name = 'click try demo' GROUP BY substr(timestamp, 1, 10), COALESCE(NULLIF(template, ''), 'unknown') ORDER BY date, template",
     ),
-    config: { xKey: "template", yKey: "count", color: "var(--brand-teal)" },
+    config: {
+      xKey: "date",
+      yKey: "count",
+      yFormatter: "number",
+      pivot: {
+        xKey: "date",
+        seriesKey: "template",
+        valueKey: "count",
+      },
+      stacked: true,
+    },
   },
   {
     key: "cli-copies-by-template",
-    title: "CLI Copies by Template",
-    chartType: "bar",
+    title: "CLI Copies by Template Over Time",
+    chartType: "area",
     source: "first-party",
-    width: 1,
+    width: 2,
     windowed: false,
     buildSql: fixed(
-      "SELECT COALESCE(NULLIF(template, ''), 'unknown') AS template, COUNT(*) AS count FROM analytics_events WHERE event_name = 'copy cli command' GROUP BY COALESCE(NULLIF(template, ''), 'unknown') ORDER BY count DESC LIMIT 20",
+      "SELECT substr(timestamp, 1, 10) AS date, COALESCE(NULLIF(template, ''), 'unknown') AS template, COUNT(*) AS count FROM analytics_events WHERE event_name = 'copy cli command' GROUP BY substr(timestamp, 1, 10), COALESCE(NULLIF(template, ''), 'unknown') ORDER BY date, template",
     ),
-    config: { xKey: "template", yKey: "count", color: "#06b6d4" },
+    config: {
+      xKey: "date",
+      yKey: "count",
+      yFormatter: "number",
+      pivot: {
+        xKey: "date",
+        seriesKey: "template",
+        valueKey: "count",
+      },
+      stacked: true,
+    },
   },
   {
     key: "cli-copies-over-time",
@@ -301,9 +353,19 @@ const ENTRIES: FirstPartyMetric[] = [
     width: 2,
     windowed: false,
     buildSql: fixed(
-      "SELECT substr(timestamp, 1, 10) AS date, COUNT(*) AS count FROM analytics_events WHERE event_name = 'copy cli command' GROUP BY substr(timestamp, 1, 10) ORDER BY date",
+      "SELECT substr(timestamp, 1, 10) AS date, COALESCE(NULLIF(template, ''), 'unknown') AS template, COUNT(*) AS count FROM analytics_events WHERE event_name = 'copy cli command' GROUP BY substr(timestamp, 1, 10), COALESCE(NULLIF(template, ''), 'unknown') ORDER BY date, template",
     ),
-    config: { xKey: "date", yKey: "count", color: "#06b6d4" },
+    config: {
+      xKey: "date",
+      yKey: "count",
+      yFormatter: "number",
+      pivot: {
+        xKey: "date",
+        seriesKey: "template",
+        valueKey: "count",
+      },
+      stacked: true,
+    },
   },
 
   // --- Activity / pageviews ------------------------------------------------
@@ -314,17 +376,200 @@ const ENTRIES: FirstPartyMetric[] = [
     source: "first-party",
     width: 2,
     windowed: false,
-    // First-party tracking has no distinct `pageview` event; total tracked
-    // events per day is the honest activity/pageviews proxy over analytics_events.
+    // Browser telemetry emits explicit `pageview` events with URL context, so
+    // keep pageview panels scoped to that event instead of all tracked events.
     buildSql: fixed(
-      "SELECT substr(timestamp, 1, 10) AS date, COUNT(*) AS count FROM analytics_events GROUP BY substr(timestamp, 1, 10) ORDER BY date",
+      `SELECT substr(timestamp, 1, 10) AS date, COALESCE(NULLIF(template, ''), NULLIF(app, ''), 'unknown') AS template, COUNT(*) AS count FROM analytics_events WHERE event_name = 'pageview' AND ${DASHBOARD_TIME_RANGE_FILTER} AND ${DASHBOARD_EMAIL_FILTER} GROUP BY substr(timestamp, 1, 10), COALESCE(NULLIF(template, ''), NULLIF(app, ''), 'unknown') ORDER BY date, template`,
     ),
     config: {
       xKey: "date",
       yKey: "count",
-      color: "var(--brand-blue)",
+      yFormatter: "number",
+      pivot: {
+        xKey: "date",
+        seriesKey: "template",
+        valueKey: "count",
+      },
+      stacked: true,
+      description: "Pageview events per day stacked by inferred template/app.",
+    },
+  },
+  {
+    key: "top-visited-urls",
+    title: "Top Visited URLs",
+    chartType: "table",
+    source: "first-party",
+    width: 2,
+    windowed: false,
+    buildSql: fixed(
+      `WITH pageviews AS (SELECT COALESCE(CASE WHEN NULLIF(hostname, '') IS NOT NULL THEN 'https://' || hostname || COALESCE(NULLIF(path, ''), '/') END, NULLIF(url, ''), NULLIF(path, ''), 'unknown') AS url, CASE WHEN NULLIF(hostname, '') IS NOT NULL THEN 'https://' || hostname || COALESCE(NULLIF(path, ''), '/') WHEN NULLIF(url, '') LIKE 'http%' THEN url ELSE COALESCE(NULLIF(url, ''), NULLIF(path, ''), '') END AS href, COUNT(*) AS views, COUNT(DISTINCT COALESCE(NULLIF(user_id, ''), NULLIF(anonymous_id, ''))) AS users, MAX(substr(timestamp, 1, 10)) AS last_seen FROM analytics_events WHERE event_name = 'pageview' AND ${DASHBOARD_TIME_RANGE_FILTER} AND ${DASHBOARD_EMAIL_FILTER} GROUP BY 1, 2) SELECT url, views, users, last_seen, href FROM pageviews ORDER BY views DESC LIMIT 25`,
+    ),
+    config: {
+      description:
+        "Most-viewed URLs in the selected time range. Links open in a new tab.",
+      sortable: true,
+      limit: 25,
+      columns: [
+        { key: "url", label: "URL", format: "link", linkKey: "href" },
+        { key: "views", label: "Views", format: "number" },
+        { key: "users", label: "Users", format: "number" },
+        { key: "last_seen", label: "Last seen", format: "date" },
+        { key: "href", hidden: true },
+      ],
+    },
+  },
+  {
+    key: "top-visited-clips",
+    title: "Top Visited Clips",
+    chartType: "table",
+    source: "first-party",
+    width: 2,
+    windowed: false,
+    buildSql: fixed(
+      `WITH clip_events AS (SELECT COALESCE(NULLIF(properties::jsonb ->> 'recording_id', ''), NULLIF(path, ''), NULLIF(url, ''), 'unknown') AS clip_key, CASE WHEN NULLIF(url, '') LIKE 'http%' THEN url WHEN NULLIF(hostname, '') IS NOT NULL THEN 'https://' || hostname || COALESCE(NULLIF(path, ''), '/') WHEN NULLIF(path, '') LIKE '/%' THEN 'https://clips.agent-native.com' || path ELSE COALESCE(NULLIF(url, ''), '') END AS href, user_id, anonymous_id, timestamp FROM analytics_events WHERE event_name = 'share_view' AND ${DASHBOARD_TIME_RANGE_FILTER} AND ${DASHBOARD_EMAIL_FILTER} AND COALESCE(NULLIF(properties::jsonb ->> 'surface', ''), 'clip') = 'clip'), clip_views AS (SELECT clip_key, COALESCE(MAX(NULLIF(href, '')), clip_key) AS href, COUNT(*) AS views, COUNT(DISTINCT COALESCE(NULLIF(user_id, ''), NULLIF(anonymous_id, ''))) AS users, MAX(substr(timestamp, 1, 10)) AS last_seen FROM clip_events GROUP BY clip_key) SELECT CASE WHEN href LIKE 'http%' THEN href ELSE clip_key END AS clip, views, users, last_seen, href FROM clip_views ORDER BY views DESC LIMIT 25`,
+    ),
+    config: {
+      description: "Most-viewed shared Clips pages in the selected time range.",
+      sortable: true,
+      limit: 25,
+      columns: [
+        { key: "clip", label: "Clip URL", format: "link", linkKey: "href" },
+        { key: "views", label: "Views", format: "number" },
+        { key: "users", label: "Users", format: "number" },
+        { key: "last_seen", label: "Last seen", format: "date" },
+        { key: "href", hidden: true },
+      ],
+    },
+  },
+  {
+    key: "repeat-users",
+    title: "Repeat Users",
+    chartType: "metric",
+    source: "first-party",
+    width: 1,
+    windowed: false,
+    buildSql: fixed(
+      "WITH user_days AS (SELECT COALESCE(NULLIF(user_id, ''), NULLIF(anonymous_id, '')) AS user_key, COUNT(DISTINCT substr(timestamp, 1, 10)) AS active_days FROM analytics_events WHERE COALESCE(NULLIF(user_id, ''), NULLIF(anonymous_id, '')) IS NOT NULL AND ('{{timeRange}}' IN ('', 'all') OR ('{{timeRange}}' = '7d' AND substr(timestamp, 1, 10) >= to_char(CURRENT_DATE - INTERVAL '7 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '30d' AND substr(timestamp, 1, 10) >= to_char(CURRENT_DATE - INTERVAL '30 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '90d' AND substr(timestamp, 1, 10) >= to_char(CURRENT_DATE - INTERVAL '90 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '180d' AND substr(timestamp, 1, 10) >= to_char(CURRENT_DATE - INTERVAL '180 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '365d' AND substr(timestamp, 1, 10) >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD'))) AND ('{{emailFilter}}' IN ('', 'all') OR ('{{emailFilter}}' = 'exclude_builder' AND lower(coalesce(user_id, '')) NOT LIKE '%@builder.io') OR ('{{emailFilter}}' = 'only_builder' AND lower(coalesce(user_id, '')) LIKE '%@builder.io')) GROUP BY COALESCE(NULLIF(user_id, ''), NULLIF(anonymous_id, ''))) SELECT COUNT(*) AS count FROM user_days WHERE active_days >= 2",
+    ),
+    config: {
+      yKey: "count",
+      yFormatter: "number",
+      description:
+        "Distinct users with activity on at least two days in the selected time range. Uses user_id first, then anonymous_id.",
+    },
+  },
+  {
+    key: "retention-over-time",
+    title: "1d / 7d Retention Over Time",
+    chartType: "line",
+    source: "first-party",
+    width: 3,
+    windowed: false,
+    buildSql: fixed(
+      "WITH base AS (SELECT COALESCE(NULLIF(user_id, ''), NULLIF(anonymous_id, '')) AS user_key, substr(timestamp, 1, 10) AS event_date, user_id FROM analytics_events WHERE COALESCE(NULLIF(user_id, ''), NULLIF(anonymous_id, '')) IS NOT NULL AND ('{{emailFilter}}' IN ('', 'all') OR ('{{emailFilter}}' = 'exclude_builder' AND lower(coalesce(user_id, '')) NOT LIKE '%@builder.io') OR ('{{emailFilter}}' = 'only_builder' AND lower(coalesce(user_id, '')) LIKE '%@builder.io'))), first_seen AS (SELECT user_key, MIN(event_date) AS cohort_date FROM base GROUP BY user_key), cohorts AS (SELECT user_key, cohort_date FROM first_seen WHERE cohort_date <= to_char(CURRENT_DATE - INTERVAL '7 days', 'YYYY-MM-DD') AND ('{{timeRange}}' IN ('', 'all') OR ('{{timeRange}}' = '7d' AND cohort_date >= to_char(CURRENT_DATE - INTERVAL '7 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '30d' AND cohort_date >= to_char(CURRENT_DATE - INTERVAL '30 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '90d' AND cohort_date >= to_char(CURRENT_DATE - INTERVAL '90 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '180d' AND cohort_date >= to_char(CURRENT_DATE - INTERVAL '180 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '365d' AND cohort_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD')))), retention AS (SELECT c.cohort_date AS date, '1d retention' AS period, COALESCE(COUNT(DISTINCT c.user_key) FILTER (WHERE b.event_date = to_char(c.cohort_date::date + INTERVAL '1 day', 'YYYY-MM-DD'))::float / NULLIF(COUNT(DISTINCT c.user_key), 0), 0) AS rate FROM cohorts c LEFT JOIN base b ON b.user_key = c.user_key GROUP BY c.cohort_date UNION ALL SELECT c.cohort_date AS date, '7d retention' AS period, COALESCE(COUNT(DISTINCT c.user_key) FILTER (WHERE b.event_date = to_char(c.cohort_date::date + INTERVAL '7 days', 'YYYY-MM-DD'))::float / NULLIF(COUNT(DISTINCT c.user_key), 0), 0) AS rate FROM cohorts c LEFT JOIN base b ON b.user_key = c.user_key GROUP BY c.cohort_date) SELECT date, period, rate FROM retention ORDER BY date, period",
+    ),
+    config: {
+      xKey: "date",
+      yKey: "rate",
+      yFormatter: "percent",
+      pivot: {
+        xKey: "date",
+        seriesKey: "period",
+        valueKey: "rate",
+      },
+      colors: ["#10b981", "#8b5cf6"],
+      description:
+        "First-seen daily cohorts in the selected range. Cohorts must be at least seven days old so both lines are mature.",
+    },
+  },
+  {
+    key: "one-day-retention-by-template",
+    title: "1d Retention by Template",
+    chartType: "line",
+    source: "first-party",
+    width: 2,
+    windowed: false,
+    buildSql: fixed(ONE_DAY_RETENTION_BY_TEMPLATE_SQL),
+    config: {
+      xKey: "date",
+      yKey: "rate",
+      yFormatter: "percent",
+      pivot: {
+        xKey: "date",
+        seriesKey: "template",
+        valueKey: "rate",
+      },
+      description:
+        "Per-template first-seen cohorts in the selected range. A user is retained when they return to the same template the next day.",
+    },
+  },
+  {
+    key: "seven-day-retention-by-template",
+    title: "7d Retention by Template",
+    chartType: "line",
+    source: "first-party",
+    width: 2,
+    windowed: false,
+    buildSql: fixed(SEVEN_DAY_RETENTION_BY_TEMPLATE_SQL),
+    config: {
+      xKey: "date",
+      yKey: "rate",
+      yFormatter: "percent",
+      pivot: {
+        xKey: "date",
+        seriesKey: "template",
+        valueKey: "rate",
+      },
+      description:
+        "Per-template first-seen cohorts in the selected range. A user is retained when they return to the same template seven days later.",
+    },
+  },
+  {
+    key: "dau-over-time",
+    title: "DAU by Template",
+    chartType: "area",
+    source: "first-party",
+    width: 2,
+    windowed: false,
+    buildSql: fixed(
+      "SELECT substr(timestamp, 1, 10) AS date, COALESCE(NULLIF(template, ''), NULLIF(app, ''), 'unknown') AS template, COUNT(DISTINCT COALESCE(NULLIF(user_id, ''), NULLIF(anonymous_id, ''))) AS users FROM analytics_events WHERE COALESCE(NULLIF(user_id, ''), NULLIF(anonymous_id, '')) IS NOT NULL AND ('{{timeRange}}' IN ('', 'all') OR ('{{timeRange}}' = '7d' AND substr(timestamp, 1, 10) >= to_char(CURRENT_DATE - INTERVAL '7 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '30d' AND substr(timestamp, 1, 10) >= to_char(CURRENT_DATE - INTERVAL '30 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '90d' AND substr(timestamp, 1, 10) >= to_char(CURRENT_DATE - INTERVAL '90 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '180d' AND substr(timestamp, 1, 10) >= to_char(CURRENT_DATE - INTERVAL '180 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '365d' AND substr(timestamp, 1, 10) >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD'))) AND ('{{emailFilter}}' IN ('', 'all') OR ('{{emailFilter}}' = 'exclude_builder' AND lower(coalesce(user_id, '')) NOT LIKE '%@builder.io') OR ('{{emailFilter}}' = 'only_builder' AND lower(coalesce(user_id, '')) LIKE '%@builder.io')) GROUP BY substr(timestamp, 1, 10), COALESCE(NULLIF(template, ''), NULLIF(app, ''), 'unknown') ORDER BY date, template",
+    ),
+    config: {
+      xKey: "date",
+      yKey: "users",
+      yFormatter: "number",
+      pivot: {
+        xKey: "date",
+        seriesKey: "template",
+        valueKey: "users",
+      },
+      stacked: true,
+      description:
+        "Distinct active users per day in the selected time range, stacked by template. Uses user_id first, then anonymous_id.",
+    },
+  },
+  {
+    key: "wau-over-time",
+    title: "WAU by Template",
+    chartType: "area",
+    source: "first-party",
+    width: 2,
+    windowed: false,
+    buildSql: fixed(
+      "WITH base AS (SELECT COALESCE(NULLIF(user_id, ''), NULLIF(anonymous_id, '')) AS user_key, COALESCE(NULLIF(template, ''), NULLIF(app, ''), 'unknown') AS template, substr(timestamp, 1, 10) AS event_date, user_id FROM analytics_events WHERE COALESCE(NULLIF(user_id, ''), NULLIF(anonymous_id, '')) IS NOT NULL AND ('{{emailFilter}}' IN ('', 'all') OR ('{{emailFilter}}' = 'exclude_builder' AND lower(coalesce(user_id, '')) NOT LIKE '%@builder.io') OR ('{{emailFilter}}' = 'only_builder' AND lower(coalesce(user_id, '')) LIKE '%@builder.io'))), days AS (SELECT DISTINCT event_date AS date FROM base WHERE ('{{timeRange}}' IN ('', 'all') OR ('{{timeRange}}' = '7d' AND event_date >= to_char(CURRENT_DATE - INTERVAL '7 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '30d' AND event_date >= to_char(CURRENT_DATE - INTERVAL '30 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '90d' AND event_date >= to_char(CURRENT_DATE - INTERVAL '90 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '180d' AND event_date >= to_char(CURRENT_DATE - INTERVAL '180 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '365d' AND event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD')))) SELECT d.date, b.template, COUNT(DISTINCT b.user_key) AS users FROM days d JOIN base b ON b.event_date >= to_char(d.date::date - INTERVAL '6 days', 'YYYY-MM-DD') AND b.event_date <= d.date GROUP BY d.date, b.template ORDER BY d.date, b.template",
+    ),
+    config: {
+      xKey: "date",
+      yKey: "users",
+      yFormatter: "number",
+      pivot: {
+        xKey: "date",
+        seriesKey: "template",
+        valueKey: "users",
+      },
+      stacked: true,
       description:
-        "Total first-party tracked events per day (activity proxy — there is no distinct pageview event in /track data).",
+        "Trailing 7-day distinct active users for each active date in the selected time range, stacked by template.",
     },
   },
 

package/corpus/templates/assets/.agents/skills/a2a-assets/SKILL.md

@@ -1,20 +1,26 @@
 ---
 name: a2a-assets
-description: Call the Assets agent from other agent-native apps to generate, refine, export, and insert brand images or videos.
+description: Use Assets from other apps or MCP hosts to generate, refine, export, and insert brand images or videos.
 ---
 
-# A2A Assets
+# Assets MCP Tool
 
-Use A2A when another app needs brand imagery, video, or reusable source media and Assets owns the library.
+Use the Assets MCP tool surface when another app or external host needs brand
+imagery, video, or reusable source media and Assets owns the library. Prefer the
+pure MCP `generate-asset` flow for human-in-the-loop generation because it can
+return the inline picker. A2A remains useful for unattended cross-app
+delegation, but A2A replies cannot render MCP App pickers.
 
 ## Caller Flow
 
-1. Call `match-library` or `list-libraries` on the Assets agent when the library
-   is ambiguous.
-2. Call `generate-image-batch` with one slot per destination, such as one hero
-   per slide. Always pass `source: "a2a"` and `callerAppId` with the calling
-   app id (`slides`, `design`, `content`, `mail`) so the Assets audit log can
-   group cross-agent generations.
+1. For human selection, call `generate-asset` with the brief, `callerAppId`, and
+   `libraryId` when known. It will match the library, generate candidates, and
+   return the Assets picker filtered to the new run IDs.
+2. For unattended A2A-style work, call `match-library` or `list-libraries` when
+   the library is ambiguous, then call `generate-image-batch` with one slot per
+   destination, such as one hero per slide. Pass `source: "a2a"` and
+   `callerAppId` with the calling app id (`slides`, `design`, `content`,
+   `mail`) so the Assets audit log can group cross-agent generations.
 3. Treat image batches as complete when the action returns. Use returned
    successful `images` entries directly; only regenerate slots that returned
    `ok: false`.
@@ -25,7 +31,8 @@ Use A2A when another app needs brand imagery, video, or reusable source media an
 6. For video, call `generate-video` and then `refresh-generation-run` until the run completes.
 7. Preserve returned `assetId`, `runId`, `previewUrl`, `downloadUrl`, and
    `embedPath` exactly.
-8. Insert exported URLs into the caller's artifact.
+8. Insert chosen/exported URLs into the caller's artifact. Design callers should
+   call `insert-asset` after the picker returns a selected asset.
 9. On feedback, call `refine-image` with the prior `assetId`, `source: "a2a"`,
    and the same `callerAppId`, then replace only the affected destination.
 

package/corpus/templates/assets/.agents/skills/asset-generation/SKILL.md

@@ -16,9 +16,14 @@ or generated image/video assets that another app can reference by ID and URL.
 
 ## Choose The Path
 
-- Use `open-asset-picker` when a person should browse, search, generate, and
-  select an asset in UI. Pass `mediaType: "image"` by default, or
-  `mediaType: "video"` for video libraries.
+- Use `generate-asset` when a person should get newly generated, on-brand image
+  candidates and choose the winner in the inline picker. It matches a library
+  when `libraryId` is omitted, generates candidates, returns the picker filtered
+  to those run IDs, and works in in-app chat plus external MCP hosts.
+- Use `open-asset-picker` when a person should browse, search, or select an
+  existing asset in UI, or when you want the picker to handle generation itself.
+  Pass `mediaType: "image"` by default, or `mediaType: "video"` for video
+  libraries.
 - Use unattended actions when the agent already knows what to do:
   `search-assets`, `list-assets`, `generate-image`, `generate-image-batch`,
   `generate-video`, `refresh-generation-run`, and `export-asset`.
@@ -41,7 +46,9 @@ or generated image/video assets that another app can reference by ID and URL.
 
 ## Image Workflows
 
-1. Pick or match the library with `list-libraries` or `match-library`.
+1. For human-in-the-loop generation, call `generate-asset` first and preserve
+   the returned picker/candidate metadata. For unattended generation, pick or
+   match the library with `list-libraries` or `match-library`.
    If the user wants a default look rather than a brand library, call
    `list-library-presets` and then `create-library-from-preset`; the resulting
    library is editable and reusable like any other library.
@@ -85,8 +92,10 @@ deferred.
   Do not put shared secrets in skill files.
 - Local customization: run `npx @agent-native/core@latest app-skill launch --local` from the
   Assets app-skill manifest, or pass `--into <path>` for editable source.
-- For A2A or MCP callers, include exact `assetId`, `runId`, media type, and
-  URLs in the final response so the caller can attach or embed the media.
+- For MCP callers, `generate-asset` is the portable first choice because the
+  same MCP App picker renders inline in Agent-Native chat, ChatGPT, and Claude
+  when the host supports MCP Apps. Include exact `assetId`, `runId`, media type,
+  and URLs in the final response so the caller can attach or embed the media.
   Include `presetId` and `sessionId` when present.
 
 ## Don't

package/corpus/templates/assets/AGENTS.md

@@ -1,8 +1,9 @@
 # Assets — Agent Guide
 
 Assets is an agent-native asset library and generation workspace. The agent
-manages libraries, images, generated assets, inline embeds, notifications,
-collaboration, and A2A asset requests through actions and SQL state.
+manages libraries, images, generated assets, inline MCP App pickers,
+notifications, collaboration, and portable asset requests through actions and
+SQL state.
 
 Detailed library, generation, image, embed, and engine rules live in
 `.agents/skills/`.
@@ -61,9 +62,10 @@ Read the relevant skill before deeper work:
   plain image-generation requests. Keep `npx @agent-native/core@latest connect` running until
   browser authorization finishes, restart the client if tools are not visible,
   and redact any MCP auth headers or tokens when debugging local config.
-- For human-in-the-loop image creation, call `open-asset-picker` with `prompt`,
-  `autoGenerate: true`, and `count: 3` so the picker opens with candidates to
-  preview, tweak by preset/aspect/count, and choose.
+- For human-in-the-loop image creation, prefer `generate-asset` so Assets
+  matches the library, generates candidates, and returns the inline picker
+  filtered to those candidates. Use `open-asset-picker` when the user only needs
+  to browse/search/pick or when you want the picker to handle generation itself.
 - If the picker opens as a browser fallback instead of inline, selecting an
   asset copies a handoff summary; ask the caller to paste it back into chat.
 - Treat Codex, Claude Code, and Claude Desktop Code as link-out hosts for MCP