primitive-admin 1.1.0-alpha.8 → 1.1.0-alpha.80

package/dist/src/commands/analytics.js

@@ -1,57 +1,221 @@
 import { ApiClient } from "../lib/api-client.js";
 import { resolveAppId } from "../lib/config.js";
-import { error, info, keyValue, formatTable, formatId, formatDate, formatNumber, formatPercent, formatDuration, json, divider, heading, } from "../lib/output.js";
+import { error, info, formatTable, formatId, formatDate, formatNumber, formatPercent, formatDuration, json, heading, result as printResult, dim, } from "../lib/output.js";
+import { buildActivityEnvelope } from "../lib/log-inspection.js";
+import { ALL_APPS_CONFLICT_ERROR, ALL_APPS_SUPER_ADMIN_ERROR, isAbortStatus, isSuperAdminRole, mergeUsageReports, parseWindowDaysFlag, renderMergedUsageReport, renderUsageReport, usageExitCode, USAGE_CLI_DEFAULT_WINDOW_DAYS, USAGE_CLI_MAX_WINDOW_DAYS, USAGE_CLI_MIN_WINDOW_DAYS, } from "../lib/workflow-usage.js";
+/** Format a value that is already a percentage (e.g. 33.3 → "33.3%") */
+function formatPctRaw(value) {
+    if (value === undefined || value === null)
+        return "-";
+    return `${value.toFixed(1)}%`;
+}
 export function registerAnalyticsCommands(program) {
     const analytics = program
         .command("analytics")
         .description("View usage analytics, user activity, and integration metrics")
+        // Subcommands are listed once, by commander, from what is registered
+        // below — a second hand-written list drifts (#2860: `errors-groups`
+        // shipped and never reached the copy). Examples illustrate; they do not
+        // re-list the group.
         .addHelpText("after", `
 Examples:
   $ primitive analytics overview
-  $ primitive analytics top-users --window-days 7 --limit 20
-  $ primitive analytics integrations
+  $ primitive analytics daily-active --window-days 14
+  $ primitive analytics top-users --limit 20
+  $ primitive analytics user-search --query user@example.com
+  $ primitive analytics user-detail <user-ulid>
+  $ primitive analytics events --window-days 7 --page 0
+  $ primitive analytics events-grouped --group-by feature
+  $ primitive analytics errors-groups --window-days 14 --limit 100
+  $ primitive analytics cohort-retention
+  $ primitive analytics workflows --limit 5
+  $ primitive analytics prompts --window-days 14
+  $ primitive analytics workflow-usage --window-days 30 --all-apps --json
 `);
-    // Overview
+    // ── Overview (DAU / WAU / MAU / Growth) ──────────────────────────
     analytics
         .command("overview")
-        .description("Get analytics overview for an app")
+        .description("Show DAU, WAU, MAU, and growth accounting")
         .argument("[app-id]", "App ID (uses current app if not specified)")
         .option("--app <app-id>", "App ID")
-        .option("--window-days <n>", "Time window in days", "30")
+        .option("--window-days <n>", "Growth window in days", "28")
+        .option("--json", "Output as JSON")
+        .action(async (appId, options) => {
+        const resolvedAppId = resolveAppId(appId, options);
+        const client = new ApiClient();
+        try {
+            const [dau, wau, mau, growth] = await Promise.all([
+                client.getAnalyticsOverviewDau(resolvedAppId),
+                client.getAnalyticsOverviewWau(resolvedAppId),
+                client.getAnalyticsOverviewMau(resolvedAppId),
+                client.getAnalyticsOverviewGrowth(resolvedAppId, {
+                    windowDays: parseInt(options.windowDays),
+                }),
+            ]);
+            if (options.json) {
+                json({ dau, wau, mau, growth });
+                return;
+            }
+            heading("Active Users");
+            console.log();
+            const formatDelta = (d) => d > 0 ? `+${(d * 100).toFixed(1)}%` : d === 0 ? "0%" : `${(d * 100).toFixed(1)}%`;
+            console.log(formatTable([
+                { metric: "DAU", value: dau.value, previous: dau.previous, delta: formatDelta(dau.deltaPct) },
+                { metric: "WAU", value: wau.value, previous: wau.previous, delta: formatDelta(wau.deltaPct) },
+                { metric: "MAU", value: mau.value, previous: mau.previous, delta: formatDelta(mau.deltaPct) },
+            ], [
+                { header: "METRIC", key: "metric" },
+                { header: "CURRENT", key: "value", align: "right", format: formatNumber },
+                { header: "PREVIOUS", key: "previous", align: "right", format: formatNumber },
+                { header: "CHANGE", key: "delta", align: "right" },
+            ]));
+            console.log();
+            heading(`Growth Accounting (${growth.window_days} days)`);
+            console.log();
+            printResult("Current active", String(growth.current_active));
+            printResult("Previous active", String(growth.previous_active));
+            printResult("New users", String(growth.new_users));
+            printResult("Retained", String(growth.retained_users));
+            printResult("Reactivated", String(growth.reactivated_users));
+            printResult("Churned", String(growth.churned_users));
+            printResult("Delta", formatDelta(growth.deltaPct));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ── Daily Active ─────────────────────────────────────────────────
+    analytics
+        .command("daily-active")
+        .description("Daily active users time series")
+        .argument("[app-id]", "App ID (uses current app if not specified)")
+        .option("--app <app-id>", "App ID")
+        .option("--window-days <n>", "Time window in days (7-90)", "28")
         .option("--json", "Output as JSON")
         .action(async (appId, options) => {
         const resolvedAppId = resolveAppId(appId, options);
         const client = new ApiClient();
         try {
-            const result = await client.getAnalyticsOverview(resolvedAppId, {
+            const result = await client.getAnalyticsDailyActive(resolvedAppId, {
                 windowDays: parseInt(options.windowDays),
             });
             if (options.json) {
                 json(result);
                 return;
             }
-            heading(`Analytics Overview (${result.windowDays} days)`);
+            heading(`Daily Active Users (${result.window_days} days)`);
             console.log();
-            keyValue("Daily Active Users (DAU)", formatNumber(result.totals.dau));
-            keyValue("Weekly Active Users (WAU)", formatNumber(result.totals.wau));
-            keyValue("Monthly Active Users (MAU)", formatNumber(result.totals.mau));
-            keyValue("Total Events", formatNumber(result.totals.totalEvents));
-            if (result.series && result.series.length > 0) {
-                divider();
-                info("Activity Series:");
-                console.log(formatTable(result.series.slice(-10), [
-                    { header: "DATE", key: "bucketStart", format: (v) => v.slice(0, 10) },
-                    { header: "USERS", key: "activeUsers", align: "right" },
-                    { header: "EVENTS", key: "totalEvents", align: "right" },
-                ]));
+            if (!result.rows || result.rows.length === 0) {
+                info("No data found.");
+                return;
+            }
+            console.log(formatTable(result.rows, [
+                { header: "DATE", key: "day_label" },
+                { header: "ACTIVE USERS", key: "active_users", align: "right", format: formatNumber },
+            ]));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ── Rolling Active ───────────────────────────────────────────────
+    analytics
+        .command("rolling-active")
+        .description("Rolling active users (28 data points)")
+        .argument("[app-id]", "App ID (uses current app if not specified)")
+        .option("--app <app-id>", "App ID")
+        .option("--window-days <n>", "Rolling window size in days (1-28)", "7")
+        .option("--json", "Output as JSON")
+        .action(async (appId, options) => {
+        const resolvedAppId = resolveAppId(appId, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.getAnalyticsRollingActive(resolvedAppId, {
+                windowDays: parseInt(options.windowDays),
+            });
+            if (options.json) {
+                json(result);
+                return;
             }
+            heading(`Rolling Active Users (${result.window_days}-day window)`);
+            console.log();
+            if (!result.rows || result.rows.length === 0) {
+                info("No data found.");
+                return;
+            }
+            console.log(formatTable(result.rows, [
+                { header: "DATE", key: "day_label" },
+                { header: "ACTIVE USERS", key: "active_users", align: "right", format: formatNumber },
+            ]));
         }
         catch (err) {
             error(err.message);
             process.exit(1);
         }
     });
-    // Top users
+    // ── Cohort Retention ─────────────────────────────────────────────
+    analytics
+        .command("cohort-retention")
+        .description("Weekly cohort retention matrix")
+        .argument("[app-id]", "App ID (uses current app if not specified)")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (appId, options) => {
+        const resolvedAppId = resolveAppId(appId, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.getAnalyticsCohortRetention(resolvedAppId);
+            if (options.json) {
+                json(result);
+                return;
+            }
+            heading("Cohort Retention");
+            console.log();
+            if (!result.rows || result.rows.length === 0) {
+                info("No cohort data found.");
+                return;
+            }
+            // Build week headers
+            const weekHeaders = result.weeks.map((w) => `W${w}`);
+            // Build table rows with retention percentages
+            const tableRows = result.rows.map((row) => {
+                const entry = {
+                    cohort: row.signup_week_label,
+                    size: row.cohort_size,
+                };
+                row.retention.forEach((r, i) => {
+                    entry[`w${result.weeks[i]}`] =
+                        r !== null ? `${r.toFixed(0)}%` : "-";
+                });
+                return entry;
+            });
+            const columns = [
+                { header: "COHORT", key: "cohort" },
+                { header: "SIZE", key: "size", align: "right", format: formatNumber },
+                ...weekHeaders.map((h, i) => ({
+                    header: h,
+                    key: `w${result.weeks[i]}`,
+                    align: "right",
+                })),
+            ];
+            console.log(formatTable(tableRows, columns));
+            // Print averages row
+            if (result.averages) {
+                const avgStr = result.averages
+                    .map((a) => a !== null ? `${a.toFixed(0)}%` : "-")
+                    .join("  ");
+                console.log();
+                dim(`Averages: ${avgStr}`);
+            }
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ── Top Users ────────────────────────────────────────────────────
     analytics
         .command("top-users")
         .description("Get top users by activity")
@@ -80,6 +244,7 @@ Examples:
             }
             console.log(formatTable(result.results, [
                 { header: "USER", key: "userUlid", format: formatId },
+                { header: "EMAIL", key: "email" },
                 { header: "EVENTS", key: "eventCount", align: "right" },
                 { header: "FIRST SEEN", key: "firstSeen", format: formatDate },
                 { header: "LAST SEEN", key: "lastSeen", format: formatDate },
@@ -90,53 +255,134 @@ Examples:
             process.exit(1);
         }
     });
-    // User details
+    // ── User Search ──────────────────────────────────────────────────
     analytics
-        .command("user")
-        .description("Get analytics for a specific user")
+        .command("user-search")
+        .description("Search users by email or ULID, or list who signed up on a given day")
         .argument("[app-id]", "App ID (uses current app if not specified)")
-        .argument("<user-ulid>", "User ULID")
         .option("--app <app-id>", "App ID")
-        .option("--window-days <n>", "Time window in days", "30")
+        // #3127 — no longer required: "who signed up on day D" names no user, so a
+        // signup filter is the second way to say what is being asked for.
+        .option("--query <q>", "Email or ULID to search for")
+        .option("--signup-day <day>", "Users who joined on this UTC day (YYYY-MM-DD)")
+        .option("--signup-start-day <day>", "Start of an inclusive signup range (YYYY-MM-DD, at most 90 days)")
+        .option("--signup-end-day <day>", "End of an inclusive signup range (YYYY-MM-DD)")
+        .option("--offset <n>", "Row offset; page a busy day until the result is not truncated")
+        .option("--limit <n>", "Max results", "25")
         .option("--json", "Output as JSON")
-        .action(async (appIdOrUserUlid, userUlidOrUndefined, options) => {
-        let resolvedAppId;
-        let userUlid;
-        if (userUlidOrUndefined) {
-            resolvedAppId = resolveAppId(appIdOrUserUlid, options);
-            userUlid = userUlidOrUndefined;
+        .action(async (appId, options) => {
+        const resolvedAppId = resolveAppId(appId, options);
+        const client = new ApiClient();
+        const hasSignupFilter = Boolean(options.signupDay || options.signupStartDay || options.signupEndDay);
+        if (!options.query && !hasSignupFilter) {
+            error("Give --query, or a signup filter (--signup-day, or " +
+                "--signup-start-day with --signup-end-day).");
+            process.exit(1);
+            return;
+        }
+        try {
+            const limit = parseInt(options.limit);
+            const result = await client.getAnalyticsUserSearch(resolvedAppId, {
+                ...(options.query ? { q: options.query } : {}),
+                limit,
+                ...(options.signupDay ? { signupDay: options.signupDay } : {}),
+                ...(options.signupStartDay
+                    ? { signupStartDay: options.signupStartDay }
+                    : {}),
+                ...(options.signupEndDay ? { signupEndDay: options.signupEndDay } : {}),
+                ...(options.offset !== undefined
+                    ? { offset: parseInt(options.offset) }
+                    : {}),
+            });
+            if (options.json) {
+                json(result);
+                return;
+            }
+            heading(hasSignupFilter
+                ? `Signups: ${result.signupStartDay ?? ""} to ${result.signupEndDay ?? ""}`
+                : `User Search: "${result.query}"`);
+            console.log();
+            if (!result.results || result.results.length === 0) {
+                info("No users found.");
+                return;
+            }
+            console.log(formatTable(result.results, [
+                { header: "USER", key: "userUlid", format: formatId },
+                { header: "EMAIL", key: "email" },
+                { header: "NAME", key: "name" },
+                { header: "SIGNED UP", key: "signedUpAt", format: formatDate },
+                { header: "EVENTS", key: "eventCount", align: "right" },
+                { header: "LAST SEEN", key: "lastSeen", format: formatDate },
+            ]));
+            // #3127 — a busy day has more matches than one page. Say so, and say
+            // exactly what to run next: silence here is how a digest undercounts.
+            //
+            // The step is the limit the SERVER used, not the one asked for: it
+            // clamps to 100, so advancing by a larger `--limit` would step straight
+            // over the users this page could not hold (CR3127-002).
+            if (result.truncated) {
+                const pageSize = typeof result.limit === "number" && result.limit > 0
+                    ? result.limit
+                    : limit;
+                const nextOffset = (result.offset ?? 0) + pageSize;
+                console.log();
+                // stdout, with the table it continues — a hint printed to stderr is
+                // the one a piped digest never sees.
+                console.log(`more results: rerun with --offset ${nextOffset}`);
+            }
         }
-        else {
-            resolvedAppId = resolveAppId(undefined, options);
-            userUlid = appIdOrUserUlid;
+        catch (err) {
+            error(err.message);
+            process.exit(1);
         }
+    });
+    // ── User Detail ──────────────────────────────────────────────────
+    analytics
+        .command("user-detail")
+        .description("Detailed activity for a single user")
+        .argument("<user-ulid>", "User ULID")
+        .argument("[app-id]", "App ID (uses current app if not specified)")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (userUlid, appId, options) => {
+        const resolvedAppId = resolveAppId(appId, options);
         const client = new ApiClient();
         try {
-            const result = await client.getAnalyticsUserTimeline(resolvedAppId, userUlid, {
-                windowDays: parseInt(options.windowDays),
-            });
+            const result = await client.getAnalyticsUserDetail(resolvedAppId, userUlid);
             if (options.json) {
                 json(result);
                 return;
             }
-            heading(`User Activity (${result.windowDays} days)`);
-            keyValue("User", userUlid);
+            heading("User Detail");
             console.log();
-            if (result.breakdown && result.breakdown.length > 0) {
-                info("Activity Breakdown:");
-                console.log(formatTable(result.breakdown.slice(0, 15), [
+            printResult("ULID", result.user.user_ulid);
+            if (result.user.email)
+                printResult("Email", result.user.email);
+            if (result.user.name)
+                printResult("Name", result.user.name);
+            console.log();
+            printResult("First seen", result.stats.first_seen ? formatDate(result.stats.first_seen) : "-");
+            printResult("Last active", result.stats.last_active ? formatDate(result.stats.last_active) : "-");
+            printResult("Total events", String(result.stats.total_events));
+            printResult("Days active", String(result.stats.days_active));
+            if (result.events_by_action?.length > 0) {
+                console.log();
+                heading("Events by Action");
+                console.log();
+                console.log(formatTable(result.events_by_action, [
                     { header: "ACTION", key: "action" },
-                    { header: "FEATURE", key: "feature" },
-                    { header: "ROUTE", key: "route" },
-                    { header: "EVENTS", key: "events", align: "right" },
+                    { header: "COUNT", key: "event_count", align: "right", format: formatNumber },
+                    { header: "LAST OCCURRED", key: "last_occurred", format: formatDate },
                 ]));
             }
-            if (result.timeline && result.timeline.length > 0) {
-                divider();
-                info("Recent Timeline:");
-                console.log(formatTable(result.timeline.slice(-10), [
-                    { header: "TIME", key: "bucketStart", format: formatDate },
-                    { header: "EVENTS", key: "events", align: "right" },
+            if (result.events_by_feature?.length > 0) {
+                console.log();
+                heading("Events by Feature");
+                console.log();
+                console.log(formatTable(result.events_by_feature, [
+                    { header: "FEATURE", key: "feature" },
+                    { header: "COUNT", key: "event_count", align: "right", format: formatNumber },
+                    { header: "PCT", key: "pct", align: "right", format: formatPctRaw },
                 ]));
             }
         }
@@ -145,7 +391,220 @@ Examples:
             process.exit(1);
         }
     });
-    // Integration metrics
+    // ── User Snapshot ────────────────────────────────────────────────
+    analytics
+        .command("user-snapshot")
+        .description("Latest context snapshot for a user")
+        .argument("<user-ulid>", "User ULID")
+        .argument("[app-id]", "App ID (uses current app if not specified)")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (userUlid, appId, options) => {
+        const resolvedAppId = resolveAppId(appId, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.getAnalyticsUserSnapshot(resolvedAppId, userUlid);
+            if (options.json) {
+                json(result);
+                return;
+            }
+            heading("User Snapshot");
+            console.log();
+            if (!result.snapshot) {
+                info("No snapshot found for this user.");
+                return;
+            }
+            printResult("Timestamp", formatDate(result.snapshot.timestamp));
+            console.log();
+            console.log(JSON.stringify(result.snapshot.values, null, 2));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ── Events Feed ──────────────────────────────────────────────────
+    analytics
+        .command("events")
+        .description("Paginated event feed")
+        .argument("[app-id]", "App ID (uses current app if not specified)")
+        .option("--app <app-id>", "App ID")
+        .option("--window-days <n>", "Time window in days", "7")
+        .option("--page <n>", "Page number (0-based)", "0")
+        .option("--user-id <id>", "Filter to a single user's events")
+        .option("--json", "Output as JSON")
+        .action(async (appId, options) => {
+        const resolvedAppId = resolveAppId(appId, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.getAnalyticsEvents(resolvedAppId, {
+                windowDays: parseInt(options.windowDays),
+                page: parseInt(options.page),
+                // The events feed filters by user via the bracketed
+                // `filter[user][is]` syntax the analytics route already parses — not
+                // a raw query param (behavior 11).
+                ...(options.userId ? { "filter[user][is]": options.userId } : {}),
+            });
+            if (options.json) {
+                // Normalize the offset-paged response to the shared activity
+                // envelope: `{page_size, rows}` → `{pageSize, items}` with the
+                // activity allowlist dropping infra fields such as `colo`
+                // (behaviors 7, 9).
+                json(buildActivityEnvelope(result));
+                return;
+            }
+            heading(`Events (page ${result.page}, ${result.total_rows} total)`);
+            console.log();
+            if (!result.rows || result.rows.length === 0) {
+                info("No events found.");
+                return;
+            }
+            // The USER cell prefers the feed's display name (#3168): only the
+            // system principal `sys:<appId>` has one, and its id is 30 characters
+            // — `formatId` truncated it at 26, mid-ULID. A column `format` sees
+            // only its own cell, so the fallback is folded in here.
+            const eventRows = result.rows.map((row) => ({
+                ...row,
+                user_display: row.user_name ?? formatId(row.user_ulid ?? ""),
+            }));
+            console.log(formatTable(eventRows, [
+                { header: "TIME", key: "timestamp", format: formatDate },
+                { header: "USER", key: "user_display" },
+                { header: "ACTION", key: "action" },
+                { header: "FEATURE", key: "feature" },
+                { header: "ROUTE", key: "route" },
+                { header: "COUNTRY", key: "country" },
+            ]));
+            const totalPages = Math.ceil(result.total_rows / result.page_size);
+            if (result.page + 1 < totalPages) {
+                console.log();
+                dim(`Page ${result.page + 1} of ${totalPages}. Use --page ${result.page + 1} for the next page.`);
+            }
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ── Events Grouped ───────────────────────────────────────────────
+    analytics
+        .command("events-grouped")
+        .description("Events grouped by a dimension")
+        .argument("[app-id]", "App ID (uses current app if not specified)")
+        .option("--app <app-id>", "App ID")
+        .option("--group-by <dim>", "Dimension: action, feature, route, country, deviceType, plan, day", "action")
+        .option("--window-days <n>", "Time window in days", "7")
+        .option("--json", "Output as JSON")
+        .action(async (appId, options) => {
+        const resolvedAppId = resolveAppId(appId, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.getAnalyticsEventsGrouped(resolvedAppId, {
+                groupBy: options.groupBy,
+                windowDays: parseInt(options.windowDays),
+            });
+            if (options.json) {
+                json(result);
+                return;
+            }
+            heading(`Events by ${result.group_by}`);
+            console.log();
+            if (!result.rows || result.rows.length === 0) {
+                info("No events found.");
+                return;
+            }
+            console.log(formatTable(result.rows, [
+                { header: result.group_by.toUpperCase(), key: "group_value" },
+                { header: "EVENTS", key: "events", align: "right", format: formatNumber },
+                { header: "UNIQUE USERS", key: "unique_users", align: "right", format: formatNumber },
+            ]));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ── Errors Grouped ───────────────────────────────────────────────
+    analytics
+        .command("errors-groups")
+        .description("Group failure events by fingerprint with per-day count buckets")
+        .argument("[app-id]", "App ID (uses current app if not specified)")
+        .option("--app <app-id>", "App ID")
+        .option("--window-days <n>", "Time window in days", "7")
+        .option("--limit <n>", "Max error groups to return", "50")
+        .option("--status-class <class>", "Filter by status class: 4xx, 5xx, transport")
+        .option("--source <source>", "Filter by source: workflow_run, workflow_step, integration")
+        .option("--verbose", "Also print each group's exemplar (a raw sample of the failure) and where it came from")
+        .option("--json", "Output as JSON")
+        .action(async (appId, options) => {
+        const resolvedAppId = resolveAppId(appId, options);
+        const client = new ApiClient();
+        try {
+            const params = {
+                windowDays: parseInt(options.windowDays),
+                limit: parseInt(options.limit),
+            };
+            if (options.statusClass) {
+                params["filter[statusClass][is]"] = options.statusClass;
+            }
+            if (options.source) {
+                params["filter[source][is]"] = options.source;
+            }
+            const result = await client.getAnalyticsErrorsGroups(resolvedAppId, params);
+            if (options.json) {
+                json(result);
+                return;
+            }
+            heading(`Error groups (last ${result.window_days} days)`);
+            console.log();
+            if (!result.rows || result.rows.length === 0) {
+                info("No error groups found.");
+                return;
+            }
+            console.log(formatTable(result.rows, [
+                { header: "TITLE", key: "normalized_title" },
+                { header: "SOURCE", key: "source" },
+                { header: "STATUS", key: "status_class" },
+                {
+                    header: "TOTAL",
+                    key: "total",
+                    align: "right",
+                    format: formatNumber,
+                },
+                {
+                    header: "DAYS",
+                    key: "daily",
+                    align: "right",
+                    format: (d) => formatNumber(Array.isArray(d) ? d.length : 0),
+                },
+                { header: "LAST SEEN", key: "last_seen", format: formatDate },
+                { header: "FINGERPRINT", key: "fingerprint", format: formatId },
+            ]));
+            // The normalized title is a grouping key, not an explanation — the
+            // exemplar is the raw sample plus the run/step it came from, which is
+            // what makes a group actionable without paging `analytics events`.
+            if (options.verbose) {
+                for (const row of result.rows) {
+                    console.log();
+                    heading(row.normalized_title || row.fingerprint);
+                    printResult("Seen", `${row.first_seen ? formatDate(row.first_seen) : "-"} → ${row.last_seen ? formatDate(row.last_seen) : "-"}`);
+                    if (!row.exemplar) {
+                        info("No exemplar available for this group.");
+                        continue;
+                    }
+                    printResult("Example", row.exemplar.message);
+                    printResult("Scope", row.exemplar.scope_key || "-");
+                    printResult("Step", row.exemplar.step_id || "-");
+                    printResult("Run", row.exemplar.run_id || "-");
+                }
+            }
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ── Integration Metrics ──────────────────────────────────────────
     analytics
         .command("integrations")
         .description("Get integration usage metrics")
@@ -174,8 +633,8 @@ Examples:
                 { header: "INTEGRATION", key: "integrationKey" },
                 { header: "CALLS", key: "invocations", align: "right", format: formatNumber },
                 { header: "ERROR RATE", key: "errorRate", align: "right", format: formatPercent },
-                { header: "AVG LATENCY", key: "avgDurationMs", align: "right", format: formatDuration },
-                { header: "P95 LATENCY", key: "p95DurationMs", align: "right", format: formatDuration },
+                { header: "MEDIAN", key: "medianDurationMs", align: "right", format: formatDuration },
+                { header: "P95", key: "p95DurationMs", align: "right", format: formatDuration },
             ]));
         }
         catch (err) {
@@ -183,5 +642,191 @@ Examples:
             process.exit(1);
         }
     });
+    // ── Top Workflows ────────────────────────────────────────────────
+    analytics
+        .command("workflows")
+        .description("Top workflows by runs")
+        .argument("[app-id]", "App ID (uses current app if not specified)")
+        .option("--app <app-id>", "App ID")
+        .option("--window-days <n>", "Time window in days", "30")
+        .option("--limit <n>", "Number of workflows to show", "10")
+        .option("--json", "Output as JSON")
+        .action(async (appId, options) => {
+        const resolvedAppId = resolveAppId(appId, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.getAnalyticsTopWorkflows(resolvedAppId, {
+                windowDays: parseInt(options.windowDays),
+                limit: parseInt(options.limit),
+            });
+            if (options.json) {
+                json(result);
+                return;
+            }
+            heading(`Top Workflows (${result.windowDays} days)`);
+            console.log();
+            if (!result.workflows || result.workflows.length === 0) {
+                info("No workflow data found.");
+                return;
+            }
+            console.log(formatTable(result.workflows, [
+                { header: "WORKFLOW", key: "workflowKey" },
+                { header: "RUNS", key: "runs", align: "right", format: formatNumber },
+                { header: "SUCCESS", key: "successRate", align: "right", format: formatPercent },
+                { header: "MEDIAN", key: "medianDurationMs", align: "right", format: formatDuration },
+                { header: "P95", key: "p95", align: "right", format: formatDuration },
+                { header: "TOKENS", key: "totalTokens", align: "right", format: formatNumber },
+            ]));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ── Top Prompts ──────────────────────────────────────────────────
+    analytics
+        .command("prompts")
+        .description("Top prompts by executions")
+        .argument("[app-id]", "App ID (uses current app if not specified)")
+        .option("--app <app-id>", "App ID")
+        .option("--window-days <n>", "Time window in days", "30")
+        .option("--limit <n>", "Number of prompts to show", "10")
+        .option("--json", "Output as JSON")
+        .action(async (appId, options) => {
+        const resolvedAppId = resolveAppId(appId, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.getAnalyticsTopPrompts(resolvedAppId, {
+                windowDays: parseInt(options.windowDays),
+                limit: parseInt(options.limit),
+            });
+            if (options.json) {
+                json(result);
+                return;
+            }
+            heading(`Top Prompts (${result.windowDays} days)`);
+            console.log();
+            if (!result.prompts || result.prompts.length === 0) {
+                info("No prompt data found.");
+                return;
+            }
+            console.log(formatTable(result.prompts, [
+                { header: "PROMPT", key: "promptKey" },
+                { header: "RUNS", key: "executions", align: "right", format: formatNumber },
+                { header: "MEDIAN", key: "medianDurationMs", align: "right", format: formatDuration },
+                { header: "P95", key: "p95DurationMs", align: "right", format: formatDuration },
+                { header: "TOKENS", key: "totalTokens", align: "right", format: formatNumber },
+            ]));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ── Workflow step usage ──────────────────────────────────────────
+    /** Print one report's blocks: headings to stderr, bodies to stdout. */
+    function printUsageBlocks(blocks) {
+        for (const block of blocks) {
+            if (block.heading) {
+                console.log();
+                heading(block.heading);
+            }
+            console.log(block.body);
+        }
+    }
+    analytics
+        .command("workflow-usage")
+        .description("Step kinds this app's workflows configure, their runs in the window, and the sync-callable and idle workflows")
+        .argument("[app-id]", "App ID (uses current app if not specified)")
+        .option("--app <app-id>", "App ID")
+        .option("--window-days <n>", `Run window in days (${USAGE_CLI_MIN_WINDOW_DAYS}-${USAGE_CLI_MAX_WINDOW_DAYS}, default ${USAGE_CLI_DEFAULT_WINDOW_DAYS})`)
+        .option("--all-apps", "Merge the report across every app (super-admin only)")
+        .option("--json", "Output as JSON")
+        .action(async (appId, options) => {
+        // Both boundary checks run before the client is constructed, so an
+        // invalid invocation never reaches the network (principle 6).
+        if (options.allApps && (appId || options.app)) {
+            error(ALL_APPS_CONFLICT_ERROR);
+            process.exit(1);
+        }
+        const window = parseWindowDaysFlag(options.windowDays);
+        if ("error" in window) {
+            error(window.error);
+            process.exit(1);
+            return;
+        }
+        // Omitted means omitted on the wire: the server applies its own default
+        // and the CLI reports the same number for a merge that has no request.
+        const params = window.omitted
+            ? undefined
+            : { windowDays: window.effective };
+        const client = new ApiClient();
+        if (options.allApps) {
+            try {
+                // The role gate comes first and is server-side: GET /admin/api/apps
+                // has no role filter, and the per-app endpoint admits any admin
+                // assigned to the app, so an app admin assigned to every app would
+                // otherwise receive the aggregate (D3130-002).
+                const me = await client.getMe();
+                if (!isSuperAdminRole(me.role)) {
+                    error(ALL_APPS_SUPER_ADMIN_ERROR);
+                    process.exit(1);
+                }
+                // There is no cross-app endpoint by design (intent): the CLI calls
+                // the per-app one once per app, over the GLOBAL apps list.
+                const apps = await client.listAllAppsGlobal();
+                const results = [];
+                for (const app of apps) {
+                    try {
+                        results.push({
+                            appId: app.appId,
+                            report: await client.getWorkflowUsage(app.appId, params),
+                        });
+                    }
+                    catch (err) {
+                        // A merged report over a silently chosen subset would answer a
+                        // different question, so a refusal ends the walk.
+                        if (isAbortStatus(err?.statusCode))
+                            throw err;
+                        results.push({
+                            appId: app.appId,
+                            error: err?.message ?? String(err),
+                        });
+                    }
+                }
+                const merged = mergeUsageReports(window.effective, results);
+                if (options.json) {
+                    json(merged);
+                }
+                else {
+                    printUsageBlocks(renderMergedUsageReport(merged));
+                }
+                // An incomplete report still prints, and still fails (intent).
+                // `exitCode` rather than `exit()`: the report is already on stdout
+                // and `process.exit` truncates a pipe's pending writes (#1004).
+                process.exitCode = usageExitCode(merged);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
+            return;
+        }
+        const resolvedAppId = resolveAppId(appId, options);
+        try {
+            const report = await client.getWorkflowUsage(resolvedAppId, params);
+            if (options.json) {
+                json(report);
+            }
+            else {
+                printUsageBlocks(renderUsageReport(report));
+            }
+            process.exitCode = usageExitCode(report);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
 }
 //# sourceMappingURL=analytics.js.map