@agent-native/core 0.115.4 → 0.116.0

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

@@ -124,7 +124,7 @@ const USER_KEY_SQL = "NULLIF(user_key, '')";
 const RETENTION_ROLLING_DAYS = 7;
 const RETENTION_MIN_COHORT_SIZE = 5;
 const PER_TEMPLATE_RETENTION_MIN_COHORT_SIZE = 20;
-const RECURRING_ACTIVITY_LOOKBACK_DAYS = 365;
+const OBSERVED_ACTIVITY_LOOKBACK_DAYS = 365;
 
 function daysAgoSql(days: number): string {
   const unit = days === 1 ? "day" : "days";
@@ -222,42 +222,160 @@ export function usesFirstPartyDashboardFilters(sql: string): boolean {
 
 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 ${EVENT_DATE_SQL}) - 1)::int AS n FROM analytics_events LIMIT 800), signup_events AS (SELECT ${EVENT_DATE_SQL} AS date, ${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 RETENTION_OVER_TIME_SQL = `WITH base AS (SELECT ${SIGNED_IN_ACTIVITY_KEY_SQL} AS user_key, ${EVENT_DATE_SQL} AS event_date, user_id FROM analytics_events WHERE ${SIGNED_IN_PRODUCT_ACTIVITY_FILTER} AND ${DASHBOARD_EMAIL_FILTER}), first_seen AS (SELECT user_key, MIN(event_date) AS cohort_date FROM base GROUP BY user_key), anchor_dates AS (SELECT DISTINCT cohort_date AS date FROM first_seen WHERE cohort_date <= ${daysAgoSql(14)} AND ${dashboardTimeRangeFilter("cohort_date")}), cohort_windows AS (SELECT a.date, f.user_key, f.cohort_date FROM anchor_dates a JOIN first_seen f ON f.cohort_date >= ${rollingWindowStartSql()} AND f.cohort_date <= a.date), cohort_sizes AS (SELECT date, COUNT(DISTINCT user_key) AS users FROM cohort_windows GROUP BY date), periods AS (SELECT '1-7d return' AS period UNION ALL SELECT '7-14d return' AS period), retained AS (SELECT cw.date, '1-7d return' AS period, COUNT(DISTINCT cw.user_key) AS retained FROM cohort_windows cw JOIN base b ON b.user_key = cw.user_key AND b.event_date > cw.cohort_date AND b.event_date <= to_char(cw.cohort_date::date + INTERVAL '7 days', 'YYYY-MM-DD') GROUP BY cw.date UNION ALL SELECT cw.date, '7-14d return' AS period, COUNT(DISTINCT cw.user_key) AS retained FROM cohort_windows cw JOIN base b ON b.user_key = cw.user_key AND b.event_date >= to_char(cw.cohort_date::date + INTERVAL '7 days', 'YYYY-MM-DD') AND b.event_date <= to_char(cw.cohort_date::date + INTERVAL '14 days', 'YYYY-MM-DD') GROUP BY cw.date) SELECT cs.date, p.period, COALESCE(r.retained, 0) AS retained_users, cs.users AS cohort_users, COALESCE(r.retained::float / NULLIF(cs.users, 0), 0) AS rate FROM cohort_sizes cs CROSS JOIN periods p LEFT JOIN retained r ON r.date = cs.date AND r.period = p.period WHERE cs.users >= ${RETENTION_MIN_COHORT_SIZE} ORDER BY cs.date, p.period`;
-const ONE_DAY_RETENTION_BY_TEMPLATE_SQL = `WITH base AS (SELECT ${SIGNED_IN_ACTIVITY_KEY_SQL} AS user_key, ${TEMPLATE_EXPR} AS template, ${EVENT_DATE_SQL} AS event_date, user_id FROM analytics_events WHERE ${SIGNED_IN_ACTIVITY_FILTER} AND ${DASHBOARD_EMAIL_FILTER} AND ${KNOWN_PRODUCT_ACTIVITY_TEMPLATE_FILTER}), ranked_first_seen AS (SELECT user_key, template, event_date AS cohort_date, ROW_NUMBER() OVER (PARTITION BY user_key ORDER BY event_date, template) AS rn FROM base), first_seen AS (SELECT user_key, template, cohort_date FROM ranked_first_seen WHERE rn = 1), cohorts AS (SELECT user_key, template, cohort_date FROM first_seen WHERE cohort_date <= ${daysAgoSql(7)} AND ${dashboardTimeRangeFilter("cohort_date")}), cohort_sizes AS (SELECT template, COUNT(DISTINCT user_key) AS users FROM cohorts GROUP BY template), retained AS (SELECT c.template, COUNT(DISTINCT c.user_key) AS retained FROM cohorts c JOIN base b ON b.user_key = c.user_key AND b.event_date > c.cohort_date AND b.event_date <= to_char(c.cohort_date::date + INTERVAL '7 days', 'YYYY-MM-DD') GROUP BY c.template) SELECT cs.template, COALESCE(r.retained, 0) AS retained_users, cs.users AS cohort_users, COALESCE(r.retained::float / NULLIF(cs.users, 0), 0) AS rate FROM cohort_sizes cs LEFT JOIN retained r ON r.template = cs.template WHERE cs.users >= ${PER_TEMPLATE_RETENTION_MIN_COHORT_SIZE} ORDER BY rate DESC, cs.users DESC, cs.template`;
-const SEVEN_DAY_RETENTION_BY_TEMPLATE_SQL = `WITH base AS (SELECT ${SIGNED_IN_ACTIVITY_KEY_SQL} AS user_key, ${TEMPLATE_EXPR} AS template, ${EVENT_DATE_SQL} AS event_date, user_id FROM analytics_events WHERE ${SIGNED_IN_ACTIVITY_FILTER} AND ${DASHBOARD_EMAIL_FILTER} AND ${KNOWN_PRODUCT_ACTIVITY_TEMPLATE_FILTER}), ranked_first_seen AS (SELECT user_key, template, event_date AS cohort_date, ROW_NUMBER() OVER (PARTITION BY user_key ORDER BY event_date, template) AS rn FROM base), first_seen AS (SELECT user_key, template, cohort_date FROM ranked_first_seen WHERE rn = 1), cohorts AS (SELECT user_key, template, cohort_date FROM first_seen WHERE cohort_date <= ${daysAgoSql(14)} AND ${dashboardTimeRangeFilter("cohort_date")}), cohort_sizes AS (SELECT template, COUNT(DISTINCT user_key) AS users FROM cohorts GROUP BY template), retained AS (SELECT c.template, COUNT(DISTINCT c.user_key) AS retained FROM cohorts c JOIN base b ON b.user_key = c.user_key AND b.event_date >= to_char(c.cohort_date::date + INTERVAL '7 days', 'YYYY-MM-DD') AND b.event_date <= to_char(c.cohort_date::date + INTERVAL '14 days', 'YYYY-MM-DD') GROUP BY c.template) SELECT cs.template, COALESCE(r.retained, 0) AS retained_users, cs.users AS cohort_users, COALESCE(r.retained::float / NULLIF(cs.users, 0), 0) AS rate FROM cohort_sizes cs LEFT JOIN retained r ON r.template = cs.template WHERE cs.users >= ${PER_TEMPLATE_RETENTION_MIN_COHORT_SIZE} ORDER BY rate DESC, cs.users DESC, cs.template`;
+export const LEGACY_RETENTION_OVER_TIME_SQL = `WITH base AS (SELECT ${SIGNED_IN_ACTIVITY_KEY_SQL} AS user_key, ${EVENT_DATE_SQL} AS event_date, user_id FROM analytics_events WHERE ${SIGNED_IN_PRODUCT_ACTIVITY_FILTER} AND ${DASHBOARD_EMAIL_FILTER}), first_seen AS (SELECT user_key, MIN(event_date) AS cohort_date FROM base GROUP BY user_key), anchor_dates AS (SELECT DISTINCT cohort_date AS date FROM first_seen WHERE cohort_date <= ${daysAgoSql(14)} AND ${dashboardTimeRangeFilter("cohort_date")}), cohort_windows AS (SELECT a.date, f.user_key, f.cohort_date FROM anchor_dates a JOIN first_seen f ON f.cohort_date >= ${rollingWindowStartSql()} AND f.cohort_date <= a.date), cohort_sizes AS (SELECT date, COUNT(DISTINCT user_key) AS users FROM cohort_windows GROUP BY date), periods AS (SELECT '1-7d return' AS period UNION ALL SELECT '7-14d return' AS period), retained AS (SELECT cw.date, '1-7d return' AS period, COUNT(DISTINCT cw.user_key) AS retained FROM cohort_windows cw JOIN base b ON b.user_key = cw.user_key AND b.event_date > cw.cohort_date AND b.event_date <= to_char(cw.cohort_date::date + INTERVAL '7 days', 'YYYY-MM-DD') GROUP BY cw.date UNION ALL SELECT cw.date, '7-14d return' AS period, COUNT(DISTINCT cw.user_key) AS retained FROM cohort_windows cw JOIN base b ON b.user_key = cw.user_key AND b.event_date >= to_char(cw.cohort_date::date + INTERVAL '7 days', 'YYYY-MM-DD') AND b.event_date <= to_char(cw.cohort_date::date + INTERVAL '14 days', 'YYYY-MM-DD') GROUP BY cw.date) SELECT cs.date, p.period, COALESCE(r.retained, 0) AS retained_users, cs.users AS cohort_users, COALESCE(r.retained::float / NULLIF(cs.users, 0), 0) AS rate FROM cohort_sizes cs CROSS JOIN periods p LEFT JOIN retained r ON r.date = cs.date AND r.period = p.period WHERE cs.users >= ${RETENTION_MIN_COHORT_SIZE} ORDER BY cs.date, p.period`;
+export const LEGACY_ONE_DAY_RETENTION_BY_TEMPLATE_SQL = `WITH base AS (SELECT ${SIGNED_IN_ACTIVITY_KEY_SQL} AS user_key, ${TEMPLATE_EXPR} AS template, ${EVENT_DATE_SQL} AS event_date, user_id FROM analytics_events WHERE ${SIGNED_IN_ACTIVITY_FILTER} AND ${DASHBOARD_EMAIL_FILTER} AND ${KNOWN_PRODUCT_ACTIVITY_TEMPLATE_FILTER}), ranked_first_seen AS (SELECT user_key, template, event_date AS cohort_date, ROW_NUMBER() OVER (PARTITION BY user_key ORDER BY event_date, template) AS rn FROM base), first_seen AS (SELECT user_key, template, cohort_date FROM ranked_first_seen WHERE rn = 1), cohorts AS (SELECT user_key, template, cohort_date FROM first_seen WHERE cohort_date <= ${daysAgoSql(7)} AND ${dashboardTimeRangeFilter("cohort_date")}), cohort_sizes AS (SELECT template, COUNT(DISTINCT user_key) AS users FROM cohorts GROUP BY template), retained AS (SELECT c.template, COUNT(DISTINCT c.user_key) AS retained FROM cohorts c JOIN base b ON b.user_key = c.user_key AND b.event_date > c.cohort_date AND b.event_date <= to_char(c.cohort_date::date + INTERVAL '7 days', 'YYYY-MM-DD') GROUP BY c.template) SELECT cs.template, COALESCE(r.retained, 0) AS retained_users, cs.users AS cohort_users, COALESCE(r.retained::float / NULLIF(cs.users, 0), 0) AS rate FROM cohort_sizes cs LEFT JOIN retained r ON r.template = cs.template WHERE cs.users >= ${PER_TEMPLATE_RETENTION_MIN_COHORT_SIZE} ORDER BY rate DESC, cs.users DESC, cs.template`;
+export const LEGACY_SEVEN_DAY_RETENTION_BY_TEMPLATE_SQL = `WITH base AS (SELECT ${SIGNED_IN_ACTIVITY_KEY_SQL} AS user_key, ${TEMPLATE_EXPR} AS template, ${EVENT_DATE_SQL} AS event_date, user_id FROM analytics_events WHERE ${SIGNED_IN_ACTIVITY_FILTER} AND ${DASHBOARD_EMAIL_FILTER} AND ${KNOWN_PRODUCT_ACTIVITY_TEMPLATE_FILTER}), ranked_first_seen AS (SELECT user_key, template, event_date AS cohort_date, ROW_NUMBER() OVER (PARTITION BY user_key ORDER BY event_date, template) AS rn FROM base), first_seen AS (SELECT user_key, template, cohort_date FROM ranked_first_seen WHERE rn = 1), cohorts AS (SELECT user_key, template, cohort_date FROM first_seen WHERE cohort_date <= ${daysAgoSql(14)} AND ${dashboardTimeRangeFilter("cohort_date")}), cohort_sizes AS (SELECT template, COUNT(DISTINCT user_key) AS users FROM cohorts GROUP BY template), retained AS (SELECT c.template, COUNT(DISTINCT c.user_key) AS retained FROM cohorts c JOIN base b ON b.user_key = c.user_key AND b.event_date >= to_char(c.cohort_date::date + INTERVAL '7 days', 'YYYY-MM-DD') AND b.event_date <= to_char(c.cohort_date::date + INTERVAL '14 days', 'YYYY-MM-DD') GROUP BY c.template) SELECT cs.template, COALESCE(r.retained, 0) AS retained_users, cs.users AS cohort_users, COALESCE(r.retained::float / NULLIF(cs.users, 0), 0) AS rate FROM cohort_sizes cs LEFT JOIN retained r ON r.template = cs.template WHERE cs.users >= ${PER_TEMPLATE_RETENTION_MIN_COHORT_SIZE} ORDER BY rate DESC, cs.users DESC, cs.template`;
+export const LEGACY_V0_RETENTION_OVER_TIME_SQL =
+  LEGACY_RETENTION_OVER_TIME_SQL.replace(
+    "cohort_date <= to_char(CURRENT_DATE, 'YYYY-MM-DD') AND ",
+    "",
+  )
+    .replace("AND (('{{timeRange}}", "AND ('{{timeRange}}")
+    .replace(
+      "CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD'))))",
+      "CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD')))",
+    );
+export const LEGACY_V0_SEVEN_DAY_RETENTION_BY_TEMPLATE_SQL =
+  LEGACY_SEVEN_DAY_RETENTION_BY_TEMPLATE_SQL.replace(
+    "cohort_date <= to_char(CURRENT_DATE, 'YYYY-MM-DD') AND ",
+    "",
+  )
+    .replace("AND (('{{timeRange}}", "AND ('{{timeRange}}")
+    .replace(
+      "CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD'))))",
+      "CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD')))",
+    );
+export const LEGACY_V0_ONE_DAY_RETENTION_BY_TEMPLATE_SQL =
+  LEGACY_ONE_DAY_RETENTION_BY_TEMPLATE_SQL.replace(
+    "cohort_date <= to_char(CURRENT_DATE, 'YYYY-MM-DD') AND ",
+    "",
+  )
+    .replace("AND (('{{timeRange}}", "AND ('{{timeRange}}")
+    .replace(
+      "CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD'))))",
+      "CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD')))",
+    );
 const SIGNUPS_BY_TEMPLATE_SQL = `SELECT ${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 ${TEMPLATE_EXPR} ORDER BY count DESC`;
 export const LEGACY_RECURRING_USERS_BY_TEMPLATE_SQL = `WITH all_users AS (SELECT ${SIGNED_IN_ACTIVITY_KEY_SQL} AS user_key, ${EVENT_DATE_SQL}, user_id, ${TEMPLATE_EXPR} AS template FROM analytics_events WHERE ${SIGNED_IN_PRODUCT_ACTIVITY_FILTER} AND ${DASHBOARD_EMAIL_FILTER}), first_seen AS (SELECT user_key, MIN(event_date) AS first_date FROM all_users GROUP BY user_key) SELECT a.event_date AS date, a.template AS template, COUNT(DISTINCT a.user_key) AS users FROM all_users a JOIN first_seen f ON f.user_key = a.user_key WHERE a.event_date <> f.first_date AND a.template <> 'unknown' AND ${dashboardTimeRangeFilter("a.event_date")} GROUP BY 1, 2 ORDER BY date, template`;
 export const LEGACY_RECURRING_USERS_BY_TEMPLATE_WEEKLY_SQL = `WITH all_users AS (SELECT ${SIGNED_IN_ACTIVITY_KEY_SQL} AS user_key, ${EVENT_DATE_SQL}, user_id, ${TEMPLATE_EXPR} AS template FROM analytics_events WHERE ${SIGNED_IN_PRODUCT_ACTIVITY_FILTER} AND ${DASHBOARD_EMAIL_FILTER}), first_seen AS (SELECT user_key, MIN(event_date) AS first_date FROM all_users GROUP BY user_key) SELECT to_char(date_trunc('week', a.event_date::date), 'YYYY-MM-DD') AS date, a.template AS template, COUNT(DISTINCT a.user_key) AS users FROM all_users a JOIN first_seen f ON f.user_key = a.user_key WHERE a.event_date <> f.first_date AND a.template <> 'unknown' AND ${dashboardTimeRangeFilter("a.event_date")} GROUP BY 1, 2 ORDER BY date, template`;
-const RECURRING_ACTIVITY_LOOKBACK_FILTER = `${EVENT_DATE_SQL} >= ${daysAgoSql(RECURRING_ACTIVITY_LOOKBACK_DAYS)}`;
-const RECURRING_USERS_BY_TEMPLATE_SQL =
+const OBSERVED_ACTIVITY_LOOKBACK_FILTER = `${EVENT_DATE_SQL} >= ${daysAgoSql(OBSERVED_ACTIVITY_LOOKBACK_DAYS)}`;
+export const INTERMEDIATE_RECURRING_USERS_BY_TEMPLATE_SQL =
   LEGACY_RECURRING_USERS_BY_TEMPLATE_SQL.replace(
     `${DASHBOARD_EMAIL_FILTER}), first_seen`,
-    `${DASHBOARD_EMAIL_FILTER} AND ${RECURRING_ACTIVITY_LOOKBACK_FILTER}), first_seen`,
+    `${DASHBOARD_EMAIL_FILTER} AND ${OBSERVED_ACTIVITY_LOOKBACK_FILTER}), first_seen`,
   );
-const RECURRING_USERS_BY_TEMPLATE_WEEKLY_SQL =
+export const INTERMEDIATE_RECURRING_USERS_BY_TEMPLATE_WEEKLY_SQL =
   LEGACY_RECURRING_USERS_BY_TEMPLATE_WEEKLY_SQL.replace(
     `${DASHBOARD_EMAIL_FILTER}), first_seen`,
-    `${DASHBOARD_EMAIL_FILTER} AND ${RECURRING_ACTIVITY_LOOKBACK_FILTER}), first_seen`,
+    `${DASHBOARD_EMAIL_FILTER} AND ${OBSERVED_ACTIVITY_LOOKBACK_FILTER}), first_seen`,
   );
+export const DEPLOYED_RECURRING_USERS_BY_TEMPLATE_SQL =
+  LEGACY_RECURRING_USERS_BY_TEMPLATE_SQL.replace(
+    "a.event_date <= to_char(CURRENT_DATE, 'YYYY-MM-DD') AND ",
+    "",
+  )
+    .replace("AND (('{{timeRange}}", "AND ('{{timeRange}}")
+    .replace(
+      "CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD'))))",
+      "CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD')))",
+    );
+const RETENTION_OVER_TIME_SQL = LEGACY_RETENTION_OVER_TIME_SQL.replace(
+  `${DASHBOARD_EMAIL_FILTER}), first_seen`,
+  `${DASHBOARD_EMAIL_FILTER} AND ${OBSERVED_ACTIVITY_LOOKBACK_FILTER}), first_seen`,
+);
+const ONE_DAY_RETENTION_BY_TEMPLATE_SQL =
+  LEGACY_ONE_DAY_RETENTION_BY_TEMPLATE_SQL.replace(
+    `${KNOWN_PRODUCT_ACTIVITY_TEMPLATE_FILTER}), ranked_first_seen`,
+    `${KNOWN_PRODUCT_ACTIVITY_TEMPLATE_FILTER} AND ${OBSERVED_ACTIVITY_LOOKBACK_FILTER}), ranked_first_seen`,
+  );
+const SEVEN_DAY_RETENTION_BY_TEMPLATE_SQL =
+  LEGACY_SEVEN_DAY_RETENTION_BY_TEMPLATE_SQL.replace(
+    `${KNOWN_PRODUCT_ACTIVITY_TEMPLATE_FILTER}), ranked_first_seen`,
+    `${KNOWN_PRODUCT_ACTIVITY_TEMPLATE_FILTER} AND ${OBSERVED_ACTIVITY_LOOKBACK_FILTER}), ranked_first_seen`,
+  );
+const RECURRING_USERS_BY_TEMPLATE_SQL = `WITH first_seen AS (SELECT ${SIGNED_IN_ACTIVITY_KEY_SQL} AS user_key, MIN(${EVENT_DATE_SQL}) AS first_date FROM analytics_events WHERE ${SIGNED_IN_PRODUCT_ACTIVITY_FILTER} AND ${DASHBOARD_EMAIL_FILTER} AND ${OBSERVED_ACTIVITY_LOOKBACK_FILTER} GROUP BY 1), activity AS (SELECT ${SIGNED_IN_ACTIVITY_KEY_SQL} AS user_key, ${EVENT_DATE_SQL} AS event_date, ${TEMPLATE_EXPR} AS template FROM analytics_events WHERE ${SIGNED_IN_PRODUCT_ACTIVITY_FILTER} AND ${DASHBOARD_EMAIL_FILTER} AND ${OBSERVED_ACTIVITY_LOOKBACK_FILTER} AND ${DASHBOARD_TIME_RANGE_FILTER}) SELECT a.event_date AS date, a.template AS template, COUNT(DISTINCT a.user_key) AS users FROM activity a JOIN first_seen f ON f.user_key = a.user_key WHERE a.event_date <> f.first_date AND a.template <> 'unknown' GROUP BY 1, 2 ORDER BY date, template`;
+const RECURRING_USERS_BY_TEMPLATE_WEEKLY_SQL = `WITH first_seen AS (SELECT ${SIGNED_IN_ACTIVITY_KEY_SQL} AS user_key, MIN(${EVENT_DATE_SQL}) AS first_date FROM analytics_events WHERE ${SIGNED_IN_PRODUCT_ACTIVITY_FILTER} AND ${DASHBOARD_EMAIL_FILTER} AND ${OBSERVED_ACTIVITY_LOOKBACK_FILTER} GROUP BY 1), activity AS (SELECT ${SIGNED_IN_ACTIVITY_KEY_SQL} AS user_key, ${EVENT_DATE_SQL} AS event_date, ${TEMPLATE_EXPR} AS template FROM analytics_events WHERE ${SIGNED_IN_PRODUCT_ACTIVITY_FILTER} AND ${DASHBOARD_EMAIL_FILTER} AND ${OBSERVED_ACTIVITY_LOOKBACK_FILTER} AND ${DASHBOARD_TIME_RANGE_FILTER}) SELECT to_char(date_trunc('week', a.event_date::date), 'YYYY-MM-DD') AS date, a.template AS template, COUNT(DISTINCT a.user_key) AS users FROM activity a JOIN first_seen f ON f.user_key = a.user_key WHERE a.event_date <> f.first_date AND a.template <> 'unknown' GROUP BY 1, 2 ORDER BY date, template`;
 const LEGACY_RECURRING_USERS_DESCRIPTION =
   "Daily signed-in visitors who are NOT on their all-time first active day (Recurring only), stacked by inferred template/app used that day. Docs traffic and unknown template are excluded.";
 const LEGACY_RECURRING_USERS_WEEKLY_DESCRIPTION =
   "Weekly distinct signed-in visitors who are NOT on their all-time first active day (Recurring only), stacked by inferred template/app used that week. Weeks start Monday; docs traffic and unknown template are excluded.";
+const LEGACY_RETENTION_OVER_TIME_DESCRIPTION =
+  "Trailing 7-day first-seen signed-in app session cohorts, keyed by browser identity. Counts returns within 1-7d and 7-14d windows. Docs traffic is excluded; windows under 5 identities are hidden.";
+const LEGACY_ONE_DAY_RETENTION_BY_TEMPLATE_DESCRIPTION =
+  "Selected-range signed-in cohorts by the browser identity's first non-docs app/template. Counts returns to any non-docs app within 1-7 days. Templates with fewer than 20 mature cohort identities are hidden.";
+const LEGACY_SEVEN_DAY_RETENTION_BY_TEMPLATE_DESCRIPTION =
+  "Selected-range signed-in cohorts by the browser identity's first non-docs app/template. Counts returns to any non-docs app within 7-14 days. Templates with fewer than 20 mature cohort identities are hidden.";
 const RECURRING_USERS_DESCRIPTION =
   "Daily signed-in visitors who are not on their first active day observed in the previous 365 days, stacked by inferred template/app used that day. Docs traffic and unknown template are excluded.";
 const RECURRING_USERS_WEEKLY_DESCRIPTION =
   "Weekly distinct signed-in visitors who are not on their first active day observed in the previous 365 days, stacked by inferred template/app used that week. Weeks start Monday; docs traffic and unknown template are excluded.";
+const RETENTION_OVER_TIME_DESCRIPTION =
+  "Trailing 7-day cohorts whose first signed-in app session was observed in the previous 365 days, keyed by browser identity. Counts returns within 1-7d and 7-14d windows. Docs traffic is excluded; windows under 5 identities are hidden.";
+const ONE_DAY_RETENTION_BY_TEMPLATE_DESCRIPTION =
+  "Selected-range signed-in cohorts by the browser identity's first non-docs app/template observed in the previous 365 days. Counts returns to any non-docs app within 1-7 days. Templates with fewer than 20 mature cohort identities are hidden.";
+const SEVEN_DAY_RETENTION_BY_TEMPLATE_DESCRIPTION =
+  "Selected-range signed-in cohorts by the browser identity's first non-docs app/template observed in the previous 365 days. Counts returns to any non-docs app within 7-14 days. Templates with fewer than 20 mature cohort identities are hidden.";
 
-export function repairFirstPartyRecurringUserPanels(
+export type ExactFirstPartyPanelReplacement = {
+  id: string;
+  legacySql: readonly string[];
+  sql: string;
+  legacyDescription?: string;
+  description?: string;
+};
+type FirstPartyPanelReplacement = Omit<ExactFirstPartyPanelReplacement, "id">;
+
+export function repairFirstPartyObservedRetentionPanels(
   config: Record<string, unknown>,
+  additionalReplacements: readonly ExactFirstPartyPanelReplacement[] = [],
 ): { config: Record<string, unknown>; changed: boolean } {
   if (!Array.isArray(config.panels)) return { config, changed: false };
 
-  const replacements = new Map([
+  const replacements = new Map<string, FirstPartyPanelReplacement>([
+    [
+      "retention-over-time",
+      {
+        legacySql: [
+          LEGACY_RETENTION_OVER_TIME_SQL,
+          LEGACY_V0_RETENTION_OVER_TIME_SQL,
+        ],
+        sql: RETENTION_OVER_TIME_SQL,
+        legacyDescription: LEGACY_RETENTION_OVER_TIME_DESCRIPTION,
+        description: RETENTION_OVER_TIME_DESCRIPTION,
+      },
+    ],
+    [
+      "one-day-retention-by-template",
+      {
+        legacySql: [
+          LEGACY_ONE_DAY_RETENTION_BY_TEMPLATE_SQL,
+          LEGACY_V0_ONE_DAY_RETENTION_BY_TEMPLATE_SQL,
+        ],
+        sql: ONE_DAY_RETENTION_BY_TEMPLATE_SQL,
+        legacyDescription: LEGACY_ONE_DAY_RETENTION_BY_TEMPLATE_DESCRIPTION,
+        description: ONE_DAY_RETENTION_BY_TEMPLATE_DESCRIPTION,
+      },
+    ],
+    [
+      "seven-day-retention-by-template",
+      {
+        legacySql: [
+          LEGACY_SEVEN_DAY_RETENTION_BY_TEMPLATE_SQL,
+          LEGACY_V0_SEVEN_DAY_RETENTION_BY_TEMPLATE_SQL,
+        ],
+        sql: SEVEN_DAY_RETENTION_BY_TEMPLATE_SQL,
+        legacyDescription: LEGACY_SEVEN_DAY_RETENTION_BY_TEMPLATE_DESCRIPTION,
+        description: SEVEN_DAY_RETENTION_BY_TEMPLATE_DESCRIPTION,
+      },
+    ],
     [
       "recurring-users-by-template",
       {
-        legacySql: LEGACY_RECURRING_USERS_BY_TEMPLATE_SQL,
+        legacySql: [
+          LEGACY_RECURRING_USERS_BY_TEMPLATE_SQL,
+          INTERMEDIATE_RECURRING_USERS_BY_TEMPLATE_SQL,
+          DEPLOYED_RECURRING_USERS_BY_TEMPLATE_SQL,
+        ],
         sql: RECURRING_USERS_BY_TEMPLATE_SQL,
         legacyDescription: LEGACY_RECURRING_USERS_DESCRIPTION,
         description: RECURRING_USERS_DESCRIPTION,
@@ -266,12 +384,18 @@ export function repairFirstPartyRecurringUserPanels(
     [
       "recurring-users-by-template-bar",
       {
-        legacySql: LEGACY_RECURRING_USERS_BY_TEMPLATE_WEEKLY_SQL,
+        legacySql: [
+          LEGACY_RECURRING_USERS_BY_TEMPLATE_WEEKLY_SQL,
+          INTERMEDIATE_RECURRING_USERS_BY_TEMPLATE_WEEKLY_SQL,
+        ],
         sql: RECURRING_USERS_BY_TEMPLATE_WEEKLY_SQL,
         legacyDescription: LEGACY_RECURRING_USERS_WEEKLY_DESCRIPTION,
         description: RECURRING_USERS_WEEKLY_DESCRIPTION,
       },
     ],
+    ...additionalReplacements.map(
+      (replacement) => [replacement.id, replacement] as const,
+    ),
   ]);
   let changed = false;
   const panels = config.panels.map((rawPanel) => {
@@ -279,7 +403,13 @@ export function repairFirstPartyRecurringUserPanels(
     const panel = rawPanel as Record<string, unknown>;
     const replacement =
       typeof panel.id === "string" ? replacements.get(panel.id) : undefined;
-    if (!replacement || panel.sql !== replacement.legacySql) return rawPanel;
+    if (
+      !replacement ||
+      typeof panel.sql !== "string" ||
+      !replacement.legacySql.includes(panel.sql)
+    ) {
+      return rawPanel;
+    }
 
     changed = true;
     const panelConfig =
@@ -293,7 +423,9 @@ export function repairFirstPartyRecurringUserPanels(
         ? {
             config: {
               ...panelConfig,
-              ...(panelConfig.description === replacement.legacyDescription
+              ...(replacement.legacyDescription !== undefined &&
+              replacement.description !== undefined &&
+              panelConfig.description === replacement.legacyDescription
                 ? { description: replacement.description }
                 : {}),
             },
@@ -806,8 +938,7 @@ const ENTRIES: FirstPartyMetric[] = [
         valueKey: "rate",
       },
       colors: ["#10b981", "#8b5cf6"],
-      description:
-        "Trailing 7-day first-seen signed-in app session cohorts, keyed by browser identity. Counts returns within 1-7d and 7-14d windows. Docs traffic is excluded; windows under 5 identities are hidden.",
+      description: RETENTION_OVER_TIME_DESCRIPTION,
     },
   },
   {
@@ -828,8 +959,7 @@ const ENTRIES: FirstPartyMetric[] = [
         { key: "retained_users", label: "Returned", format: "number" },
         { key: "cohort_users", label: "Cohort", format: "number" },
       ],
-      description:
-        "Selected-range signed-in cohorts by the browser identity's first non-docs app/template. Counts returns to any non-docs app within 1-7 days. Templates with fewer than 20 mature cohort identities are hidden.",
+      description: ONE_DAY_RETENTION_BY_TEMPLATE_DESCRIPTION,
     },
   },
   {
@@ -850,8 +980,7 @@ const ENTRIES: FirstPartyMetric[] = [
         { key: "retained_users", label: "Returned", format: "number" },
         { key: "cohort_users", label: "Cohort", format: "number" },
       ],
-      description:
-        "Selected-range signed-in cohorts by the browser identity's first non-docs app/template. Counts returns to any non-docs app within 7-14 days. Templates with fewer than 20 mature cohort identities are hidden.",
+      description: SEVEN_DAY_RETENTION_BY_TEMPLATE_DESCRIPTION,
     },
   },
   {

package/corpus/templates/analytics/server/lib/google-sheets-export.ts

@@ -0,0 +1,188 @@
+import { executeProviderApiRequest } from "./provider-api";
+
+export interface GoogleSheetExportInput {
+  dashboardId: string;
+  dashboardTitle: string;
+  panelId: string;
+  panelTitle: string;
+  source: string;
+  rows: Record<string, unknown>[];
+  schema: { name: string; type: string }[];
+  truncated?: boolean;
+  bytesProcessed?: number;
+}
+
+export interface GoogleSheetExportResult {
+  spreadsheetUrl: string;
+  spreadsheetId: string;
+  rowCount: number;
+  metadata: {
+    dashboardId: string;
+    dashboardTitle: string;
+    panelId: string;
+    panelTitle: string;
+    source: string;
+    chartType: "table";
+    sheetTitle: string;
+    columns: string[];
+    columnCount: number;
+    truncated: boolean;
+    bytesProcessed: number | null;
+    provider: "google_drive";
+    updatedCells: number | null;
+  };
+}
+
+type ProviderResponse = {
+  ok?: boolean;
+  status?: number;
+  statusText?: string;
+  json?: unknown;
+};
+
+function providerResponse(result: unknown, label: string): ProviderResponse {
+  const response = (result as { response?: unknown } | null)?.response;
+  if (!response || typeof response !== "object") {
+    throw new Error(`${label} returned an unexpected response.`);
+  }
+  const typed = response as ProviderResponse;
+  if (!typed.ok) {
+    const status = typed.status ? ` HTTP ${typed.status}` : "";
+    const statusText = typed.statusText ? ` ${typed.statusText}` : "";
+    throw new Error(`${label} failed${status}${statusText}.`);
+  }
+  return typed;
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function sheetCell(value: unknown): string | number | boolean {
+  if (value === null || value === undefined) return "";
+  if (typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number") return Number.isFinite(value) ? value : "";
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+function quoteSheetTitle(title: string): string {
+  return `'${title.replace(/'/g, "''")}'`;
+}
+
+function normalizeSheetTitle(
+  dashboardTitle: string,
+  panelTitle: string,
+): string {
+  const title = `${dashboardTitle} - ${panelTitle}`
+    .replace(/[\u0000-\u001f\u007f]/g, " ")
+    .trim();
+  return (title || "Analytics export").slice(0, 100);
+}
+
+function sheetColumnCount(
+  schema: GoogleSheetExportInput["schema"],
+  rows: GoogleSheetExportInput["rows"],
+): string[] {
+  const names = schema
+    .map((column) => column.name.trim())
+    .filter((name, index, columns) => name && columns.indexOf(name) === index);
+  if (names.length > 0) return names;
+  return Object.keys(rows[0] ?? {});
+}
+
+export async function exportDashboardPanelToGoogleSheet(
+  input: GoogleSheetExportInput,
+): Promise<GoogleSheetExportResult> {
+  const columns = sheetColumnCount(input.schema, input.rows);
+  const sheetTitle = normalizeSheetTitle(
+    input.dashboardTitle,
+    input.panelTitle,
+  );
+  const createResult = await executeProviderApiRequest({
+    provider: "google_drive",
+    method: "POST",
+    path: "https://sheets.googleapis.com/v4/spreadsheets",
+    query: {
+      fields: "spreadsheetId,spreadsheetUrl,properties.title,sheets.properties",
+    },
+    body: { properties: { title: sheetTitle } },
+  });
+  const createResponse = providerResponse(
+    createResult,
+    "Google Sheet creation",
+  );
+  const created = asRecord(createResponse.json);
+  const spreadsheetId =
+    typeof created.spreadsheetId === "string" ? created.spreadsheetId : "";
+  if (!spreadsheetId) {
+    throw new Error("Google Sheet creation did not return a spreadsheet id.");
+  }
+
+  const sheets = Array.isArray(created.sheets) ? created.sheets : [];
+  const firstSheet = asRecord(sheets[0]);
+  const firstProperties = asRecord(firstSheet.properties);
+  const actualSheetTitle =
+    typeof firstProperties.title === "string" && firstProperties.title
+      ? firstProperties.title
+      : "Sheet1";
+  let updatedCells: number | null = null;
+
+  if (columns.length > 0) {
+    const values = [
+      columns,
+      ...input.rows.map((row) =>
+        columns.map((column) => sheetCell(row[column])),
+      ),
+    ];
+    const updateResult = await executeProviderApiRequest({
+      provider: "google_drive",
+      method: "PUT",
+      path: `https://sheets.googleapis.com/v4/spreadsheets/${encodeURIComponent(spreadsheetId)}/values/${encodeURIComponent(`${quoteSheetTitle(actualSheetTitle)}!A1`)}`,
+      query: { valueInputOption: "RAW" },
+      body: {
+        range: `${quoteSheetTitle(actualSheetTitle)}!A1`,
+        majorDimension: "ROWS",
+        values,
+      },
+    });
+    const updateResponse = providerResponse(
+      updateResult,
+      "Google Sheet values update",
+    );
+    const updated = asRecord(updateResponse.json);
+    updatedCells =
+      typeof updated.updatedCells === "number" ? updated.updatedCells : null;
+  }
+
+  const spreadsheetUrl =
+    typeof created.spreadsheetUrl === "string" && created.spreadsheetUrl
+      ? created.spreadsheetUrl
+      : `https://docs.google.com/spreadsheets/d/${encodeURIComponent(spreadsheetId)}/edit`;
+
+  return {
+    spreadsheetUrl,
+    spreadsheetId,
+    rowCount: input.rows.length,
+    metadata: {
+      dashboardId: input.dashboardId,
+      dashboardTitle: input.dashboardTitle,
+      panelId: input.panelId,
+      panelTitle: input.panelTitle,
+      source: input.source,
+      chartType: "table",
+      sheetTitle: actualSheetTitle,
+      columns,
+      columnCount: columns.length,
+      truncated: input.truncated === true,
+      bytesProcessed: input.bytesProcessed ?? null,
+      provider: "google_drive",
+      updatedCells,
+    },
+  };
+}

package/corpus/templates/analytics/server/lib/provider-api.ts

@@ -11,8 +11,13 @@ import {
 import { requireRequestCredentialContext } from "./credentials-context";
 import { resolveAnalyticsProviderCredential } from "./provider-credentials";
 
-export const ANALYTICS_PROVIDER_API_IDS = listProviderApiIdsForTemplateUse(
-  "analytics",
+export const ANALYTICS_PROVIDER_API_IDS = Array.from(
+  new Set([
+    ...listProviderApiIdsForTemplateUse("analytics"),
+    // Google Sheets creation and writes use the existing Google Drive OAuth
+    // connection, whose consent is limited to drive.file.
+    "google_drive" as ProviderApiId,
+  ]),
 ) as [ProviderApiId, ...ProviderApiId[]];
 export type AnalyticsProviderApiId = ProviderApiId;
 export type { ProviderApiMethod, ProviderApiRequestArgs };

package/corpus/templates/analytics/server/plugins/collab.ts

@@ -10,7 +10,10 @@ export default createCollabPlugin({
   contentColumn: "config",
   idColumn: "id",
   autoSeed: true,
-  resourceType: "dashboard",
-  resolveResourceId: (docId) =>
-    docId.startsWith("dash-") ? docId.slice("dash-".length) : docId,
+  access: {
+    mode: "resource",
+    resourceType: "dashboard",
+    resolveResourceId: (docId) =>
+      docId.startsWith("dash-") ? docId.slice("dash-".length) : docId,
+  },
 });

package/corpus/templates/analytics/shared/sql-query-limits.ts

@@ -0,0 +1 @@
+export const MAX_CONCURRENT_SQL_QUERIES = 4;

package/corpus/templates/assets/.agents/skills/agent-native-toolkit/SKILL.md

@@ -85,7 +85,10 @@ in the moment of agent use.
   approval, generative UI, progress, and screen-state exposure.
 - **Chat history kit**: presentational chat lists and recent-chat rails belong
   in Toolkit; Core keeps thread persistence, agent execution, transport, and
-  page-to-sidebar handoff. Apps inject routing, labels, and domain actions.
+  page-to-sidebar handoff. Use Toolkit's `ChatHistoryRail` for the standard
+  five-item sidebar preview and a footer row with New chat followed by an
+  ellipsis disclosure up to fifteen. Apps inject routing, labels, and domain
+  actions.
 - **Agent page kit**: the full-page `/agent` surface (`AgentTabsPage` from
   `@agent-native/core/client`) with Context, Files, Connections, Jobs, and
   Access tabs plus a Personal/Organization scope toggle. The canonical home

package/corpus/templates/assets/.agents/skills/real-time-collab/SKILL.md

@@ -16,7 +16,7 @@ metadata:
 
 Collaborative editing uses Yjs CRDT via TipTap. The agent and human users are
 equal participants — both edit the same Y.Doc and changes merge cleanly without
-conflicts. Always set `resourceType` on `createCollabPlugin`.
+conflicts. Always choose an explicit `access` mode on `createCollabPlugin`.
 
 ## How It Works
 
@@ -104,7 +104,16 @@ in **different** regions merge fine through the CRDT.
 
 ## Security
 
-### Always set `resourceType`
+### Always choose an explicit access mode
+
+Inspect the schema and sharing registration before configuring collaboration:
+
+- For owned or shareable records, use `mode: "resource"` and the resource type
+  registered through `registerShareableResource`.
+- For records deliberately visible to every authenticated user on the
+  deployment, use `mode: "all-authenticated"`.
+- Never invent a `resourceType` merely to silence a warning. Resource mode is
+  correct only when the matching ownership and sharing model exists.
 
 ```ts
 // server/plugins/collab.ts
@@ -114,14 +123,23 @@ export default createCollabPlugin({
   table: "documents",
   contentColumn: "content",
   idColumn: "id",
-  resourceType: "document", // required
+  access: { mode: "resource", resourceType: "document" },
 });
 ```
 
-Without `resourceType`, the server logs a one-time warning and collab push
-events are delivered to **all authenticated users** without document-level
-scoping. Set it to the resource type name registered via
-`registerShareableResource`.
+For intentionally deployment-wide authenticated collaboration:
+
+```ts
+createCollabPlugin({
+  table: "todos",
+  contentColumn: "content",
+  access: { mode: "all-authenticated" },
+});
+```
+
+Omitting `access` is supported only for legacy compatibility and is deprecated.
+It behaves like `all-authenticated`, logs a warning, and is flagged by Doctor.
+Choose the mode explicitly so access intent is reviewable.
 
 Non-owner sharees who have explicit access fall back to state-vector catch-up
 (safe, slightly higher latency). Awareness routes require the same viewer
@@ -133,7 +151,10 @@ Write routes reject payloads exceeding `maxPayloadBytes` (default 2 MB) with
 HTTP 413. Override:
 
 ```ts
-createCollabPlugin({ resourceType: "document", maxPayloadBytes: 512 * 1024 });
+createCollabPlugin({
+  access: { mode: "resource", resourceType: "document" },
+  maxPayloadBytes: 512 * 1024,
+});
 ```
 
 ## Enabling Collaboration
@@ -144,7 +165,7 @@ createCollabPlugin({ resourceType: "document", maxPayloadBytes: 512 * 1024 });
 pnpm add @tiptap/extension-collaboration @tiptap/extension-collaboration-caret @tiptap/y-tiptap @tiptap/core
 ```
 
-### 2. Add collab server plugin (with `resourceType`)
+### 2. Add collab server plugin (with explicit access)
 
 ```ts
 // server/plugins/collab.ts
@@ -154,7 +175,7 @@ export default createCollabPlugin({
   table: "documents",
   contentColumn: "content",
   idColumn: "id",
-  resourceType: "document",
+  access: { mode: "resource", resourceType: "document" },
 });
 ```
 
@@ -343,9 +364,10 @@ the whole history — external/agent edits must not wipe the user's undo stack.
 
 ## Common Pitfalls
 
-- **Missing `resourceType`** — The server logs a warning on startup and
-  delivers collab events to all authenticated users without access scoping.
-  Always set `resourceType`.
+- **Missing `access`** — Legacy omission behaves like `all-authenticated`, logs
+  a startup warning, and is flagged by Doctor. Choose `resource` for records
+  backed by ownership/sharing, or explicit `all-authenticated` for intentionally
+  deployment-wide records. Never invent a resource type to silence the warning.
 - **Don't pass `content` as a TipTap prop** when Collaboration is enabled —
   Yjs owns the content. Seed via `editor.commands.setContent()` only when the
   Y.XmlFragment is empty.

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

@@ -72,7 +72,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
   });
   ```
 
-  `useDbSync` and every `subscribeSyncEvents` subscriber share one `EventSource` and one fallback poll loop per tab — this is how collaborative documents receive doc updates and cursor/awareness events.
+  `useDbSync` and every `subscribeSyncEvents` subscriber share one `EventSource` and one fallback poll loop per tab — this is how collaborative documents receive doc updates and cursor/awareness events. Hidden tabs keep that shared transport alive by default: SSE stays connected and active fallback polling relaxes to a 10-second floor (idle polling remains once per minute). Pass `pauseWhenHidden: true` only for a consumer that explicitly must stop all hidden-tab sync.
 
 ## Which sources to depend on
 

package/corpus/templates/assets/app/components/layout/Layout.tsx

@@ -71,7 +71,7 @@ export function Layout({ children }: LayoutProps) {
     // A direct /chat/:id link already names the thread and must preserve the
     // normal chat-to-sidebar transition. Only the empty home chat needs the
     // recent marker that proves an agent handoff is in flight.
-    requireActiveHandoff: location.pathname === "/",
+    requireActiveHandoff: false,
   });
 
   useEffect(() => {