fraim-framework 2.0.179 → 2.0.180

package/dist/src/routes/analytics.js

@@ -0,0 +1,1447 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const express_1 = __importDefault(require("express"));
+const path_1 = __importDefault(require("path"));
+const usage_analytics_service_js_1 = require("../services/usage-analytics-service.js");
+const db_service_js_1 = require("../fraim/db-service.js");
+const mcp_service_js_1 = require("../services/mcp-service.js");
+const git_utils_js_1 = require("../core/utils/git-utils.js");
+const catalog_1 = require("../ai-hub/catalog");
+const router = express_1.default.Router();
+/**
+ * GET /api/analytics/stats
+ * Get usage statistics for a time period
+ */
+router.get('/stats', async (req, res) => {
+    let dbService;
+    let analyticsService;
+    try {
+        // Get API key data from middleware
+        const apiKeyData = req.apiKeyData;
+        if (!apiKeyData) {
+            return res.status(401).json({ error: 'Authentication required' });
+        }
+        // Create database connection
+        dbService = new db_service_js_1.FraimDbService();
+        await dbService.connect();
+        // Create analytics service
+        analyticsService = new usage_analytics_service_js_1.UsageAnalyticsService(dbService);
+        const { type, apiKey, repoIdentifier } = req.query;
+        const timeframe = resolveAnalyticsTimeframe(req.query);
+        const types = type ? (Array.isArray(type) ? type : [type]) : undefined;
+        let targetUserId;
+        if (apiKey && typeof apiKey === 'string') {
+            const isAdmin = apiKeyData.userId === 'sid.mathur@gmail.com';
+            if (!isAdmin) {
+                return res.status(403).json({ error: 'Admin access required to view other users data' });
+            }
+            const targetApiKeyData = await dbService.getApiKeyByKey(apiKey);
+            if (!targetApiKeyData) {
+                return res.status(404).json({ error: 'API key not found' });
+            }
+            targetUserId = targetApiKeyData.userId;
+        }
+        else {
+            targetUserId = apiKeyData.userId;
+        }
+        const stats = await analyticsService.getUsageStats({
+            period: timeframe.period,
+            startDate: timeframe.startDate,
+            endDate: timeframe.endDate,
+            types,
+            userId: targetUserId,
+            repoIdentifier: repoIdentifier
+        });
+        res.json(stats);
+    }
+    catch (error) {
+        console.error('Error fetching usage stats:', error);
+        res.status(500).json({ error: 'Internal server error' });
+    }
+    finally {
+        if (dbService) {
+            await dbService.close();
+        }
+    }
+});
+/**
+ * GET /api/analytics/components/top
+ * Get top components by usage count
+ */
+router.get('/components/top', async (req, res) => {
+    let dbService;
+    let analyticsService;
+    try {
+        // Get API key data from middleware
+        const apiKeyData = req.apiKeyData;
+        if (!apiKeyData) {
+            return res.status(401).json({ error: 'Authentication required' });
+        }
+        // Create database connection
+        dbService = new db_service_js_1.FraimDbService();
+        await dbService.connect();
+        // Create analytics service
+        analyticsService = new usage_analytics_service_js_1.UsageAnalyticsService(dbService);
+        const { limit = '10', apiKey, type, repoIdentifier } = req.query;
+        const timeframe = resolveAnalyticsTimeframe(req.query);
+        const types = type ? (Array.isArray(type) ? type : [type]) : undefined;
+        let targetUserId;
+        if (apiKey && typeof apiKey === 'string') {
+            const isAdmin = apiKeyData.userId === 'sid.mathur@gmail.com';
+            if (!isAdmin) {
+                return res.status(403).json({ error: 'Admin access required to view other users data' });
+            }
+            const targetApiKeyData = await dbService.getApiKeyByKey(apiKey);
+            if (!targetApiKeyData) {
+                return res.status(404).json({ error: 'API key not found' });
+            }
+            targetUserId = targetApiKeyData.userId;
+        }
+        else {
+            targetUserId = apiKeyData.userId;
+        }
+        const components = await analyticsService.getTopComponents(parseInt(limit, 10), timeframe.period, types, targetUserId, repoIdentifier, timeframe.startDate, timeframe.endDate);
+        res.json(components);
+    }
+    catch (error) {
+        console.error('Error fetching top components:', error);
+        res.status(500).json({ error: 'Internal server error' });
+    }
+    finally {
+        if (dbService) {
+            await dbService.close();
+        }
+    }
+});
+/**
+ * GET /api/analytics/trends
+ * Get trend data for a specific component
+ */
+router.get('/trends', async (req, res) => {
+    let dbService;
+    let analyticsService;
+    try {
+        // Get API key data from middleware
+        const apiKeyData = req.apiKeyData;
+        if (!apiKeyData) {
+            return res.status(401).json({ error: 'Authentication required' });
+        }
+        const { component, type, apiKey, dateUnit, repoIdentifier } = req.query;
+        const timeframe = resolveAnalyticsTimeframe(req.query);
+        if (!component || !type) {
+            return res.status(400).json({ error: 'Component name and type are required' });
+        }
+        // Create database connection
+        dbService = new db_service_js_1.FraimDbService();
+        await dbService.connect();
+        // Create analytics service
+        analyticsService = new usage_analytics_service_js_1.UsageAnalyticsService(dbService);
+        let targetUserId;
+        if (apiKey && typeof apiKey === 'string') {
+            const isAdmin = apiKeyData.userId === 'sid.mathur@gmail.com';
+            if (!isAdmin) {
+                return res.status(403).json({ error: 'Admin access required to view other users data' });
+            }
+            const targetApiKeyData = await dbService.getApiKeyByKey(apiKey);
+            if (!targetApiKeyData) {
+                return res.status(404).json({ error: 'API key not found' });
+            }
+            targetUserId = targetApiKeyData.userId;
+        }
+        else {
+            targetUserId = apiKeyData.userId;
+        }
+        const trend = await analyticsService.getComponentTrend(component, type, timeframe.period, targetUserId, dateUnit, repoIdentifier, timeframe.startDate, timeframe.endDate);
+        res.json(trend);
+    }
+    catch (error) {
+        console.error('Error fetching component trends:', error);
+        res.status(500).json({ error: 'Internal server error' });
+    }
+    finally {
+        if (dbService) {
+            await dbService.close();
+        }
+    }
+});
+/**
+ * GET /api/analytics/jobs/timeline
+ * Get job execution timeline for the bubble chart
+ */
+router.get('/jobs/timeline', async (req, res) => {
+    let dbService;
+    let analyticsService;
+    try {
+        const apiKeyData = req.apiKeyData;
+        if (!apiKeyData) {
+            return res.status(401).json({ error: 'Authentication required' });
+        }
+        const { apiKey, dateUnit, repoIdentifier } = req.query;
+        const timeframe = resolveAnalyticsTimeframe(req.query);
+        dbService = new db_service_js_1.FraimDbService();
+        await dbService.connect();
+        analyticsService = new usage_analytics_service_js_1.UsageAnalyticsService(dbService);
+        let targetUserId;
+        if (apiKey && typeof apiKey === 'string') {
+            const isAdmin = apiKeyData.userId === 'sid.mathur@gmail.com';
+            if (!isAdmin) {
+                return res.status(403).json({ error: 'Admin access required to view other users data' });
+            }
+            const targetApiKeyData = await dbService.getApiKeyByKey(apiKey);
+            if (!targetApiKeyData) {
+                return res.status(404).json({ error: 'API key not found' });
+            }
+            targetUserId = targetApiKeyData.userId;
+        }
+        else {
+            targetUserId = apiKeyData.userId;
+        }
+        const timeline = await analyticsService.getJobRunsOverTime(timeframe.period, targetUserId, dateUnit, repoIdentifier, timeframe.startDate, timeframe.endDate);
+        res.json(timeline);
+    }
+    catch (error) {
+        console.error('Error fetching job timeline:', error);
+        res.status(500).json({ error: 'Internal server error' });
+    }
+    finally {
+        if (dbService) {
+            await dbService.close();
+        }
+    }
+});
+/**
+ * GET /api/analytics/jobs/completion
+ * Get job completion metrics for analytics dashboard
+ */
+router.get('/jobs/completion', async (req, res) => {
+    let dbService;
+    let analyticsService;
+    try {
+        const apiKeyData = req.apiKeyData;
+        if (!apiKeyData) {
+            return res.status(401).json({ error: 'Authentication required' });
+        }
+        const { jobName, apiKey, repoIdentifier } = req.query;
+        const timeframe = resolveAnalyticsTimeframe(req.query);
+        dbService = new db_service_js_1.FraimDbService();
+        await dbService.connect();
+        analyticsService = new usage_analytics_service_js_1.UsageAnalyticsService(dbService);
+        let targetUserId;
+        if (apiKey && typeof apiKey === 'string') {
+            const isAdmin = apiKeyData.userId === 'sid.mathur@gmail.com';
+            if (!isAdmin) {
+                return res.status(403).json({ error: 'Admin access required to view other users data' });
+            }
+            const targetApiKeyData = await dbService.getApiKeyByKey(apiKey);
+            if (!targetApiKeyData) {
+                return res.status(404).json({ error: 'API key not found' });
+            }
+            targetUserId = targetApiKeyData.userId;
+        }
+        else {
+            targetUserId = apiKeyData.userId;
+        }
+        // Get completion metrics for all jobs or specific job
+        const metrics = await analyticsService.getJobCompletionMetrics(timeframe.period, jobName, targetUserId, repoIdentifier, timeframe.startDate, timeframe.endDate);
+        res.json(metrics);
+    }
+    catch (error) {
+        console.error('Error fetching job completion metrics:', error);
+        res.status(500).json({ error: 'Internal server error' });
+    }
+    finally {
+        if (dbService) {
+            await dbService.close();
+        }
+    }
+});
+/**
+ * GET /api/analytics/jobs/runs
+ * Get recent job runs for a specific job name (for clickable table rows)
+ */
+router.get('/jobs/runs', async (req, res) => {
+    let dbService;
+    try {
+        const apiKeyData = req.apiKeyData;
+        if (!apiKeyData) {
+            return res.status(401).json({ error: 'Authentication required' });
+        }
+        const { period = '30d', jobName, limit = '50', repoIdentifier } = req.query;
+        const timeframe = resolveAnalyticsTimeframe(req.query);
+        if (!jobName || typeof jobName !== 'string') {
+            return res.status(400).json({ error: 'jobName query parameter is required' });
+        }
+        dbService = new db_service_js_1.FraimDbService();
+        await dbService.connect();
+        const targetUserId = await resolveTargetUserIdFromQuery(dbService, apiKeyData, req.query);
+        const timeRangeDays = parsePeriodDays(timeframe.period);
+        const startDate = timeframe.startDate ?? new Date(Date.now() - timeRangeDays * 24 * 60 * 60 * 1000);
+        const runs = await dbService.getJobRuns(jobName, startDate, targetUserId, parseInt(limit, 10) || 50, repoIdentifier);
+        res.json(runs);
+    }
+    catch (error) {
+        if (error.status === 403)
+            return res.status(403).json({ error: error.message });
+        if (error.status === 404)
+            return res.status(404).json({ error: error.message });
+        console.error('Error fetching job runs:', error);
+        res.status(500).json({ error: 'Internal server error' });
+    }
+    finally {
+        if (dbService) {
+            await dbService.close();
+        }
+    }
+});
+/**
+ * GET /api/analytics/jobs/run/:jobId/timeline
+ * Get phase-by-phase timeline for a specific job run
+ */
+router.get('/jobs/run/:jobId/timeline', async (req, res) => {
+    let dbService;
+    try {
+        const apiKeyData = req.apiKeyData;
+        if (!apiKeyData) {
+            return res.status(401).json({ error: 'Authentication required' });
+        }
+        const jobId = req.params.jobId;
+        if (!jobId) {
+            return res.status(400).json({ error: 'jobId parameter is required' });
+        }
+        dbService = new db_service_js_1.FraimDbService();
+        await dbService.connect();
+        const targetUserId = await resolveTargetUserIdFromQuery(dbService, apiKeyData, req.query);
+        const jobName = req.query.jobName;
+        const events = await dbService.getJobRunTimeline(jobId, targetUserId, jobName);
+        // Calculate phase durations from consecutive events
+        const timeline = events.map((event, i) => {
+            const next = events[i + 1];
+            const durationMs = next ? new Date(next.createdAt).getTime() - new Date(event.createdAt).getTime() : null;
+            return {
+                ...event,
+                durationMs,
+                durationFormatted: durationMs !== null ? formatDuration(durationMs) : null
+            };
+        });
+        res.json(timeline);
+    }
+    catch (error) {
+        if (error.status === 403)
+            return res.status(403).json({ error: error.message });
+        if (error.status === 404)
+            return res.status(404).json({ error: error.message });
+        console.error('Error fetching job run timeline:', error);
+        res.status(500).json({ error: 'Internal server error' });
+    }
+    finally {
+        if (dbService) {
+            await dbService.close();
+        }
+    }
+});
+/**
+ * GET /api/analytics/jobs/:jobName/phases
+ * Get the declared FRAIM phase sequence for a job in registry order.
+ */
+router.get('/jobs/:jobName/phases', async (req, res) => {
+    try {
+        const apiKeyData = req.apiKeyData;
+        if (!apiKeyData) {
+            return res.status(401).json({ error: 'Authentication required' });
+        }
+        const jobName = req.params.jobName;
+        if (!jobName) {
+            return res.status(400).json({ error: 'jobName parameter is required' });
+        }
+        const discriminant = typeof req.query.discriminant === 'string' ? req.query.discriminant : 'feature';
+        const phases = (0, catalog_1.loadJobPhases)(jobName, process.cwd(), discriminant).map(phase => ({
+            key: phase.id,
+            label: phase.label
+        }));
+        res.json({ jobName, phases });
+    }
+    catch (error) {
+        console.error('Error fetching job phases:', error);
+        res.status(500).json({ error: 'Internal server error' });
+    }
+});
+function formatDuration(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    if (ms < 60000)
+        return `${(ms / 1000).toFixed(1)}s`;
+    if (ms < 3600000)
+        return `${Math.floor(ms / 60000)}m ${Math.floor((ms % 60000) / 1000)}s`;
+    return `${Math.floor(ms / 3600000)}h ${Math.floor((ms % 3600000) / 60000)}m`;
+}
+/**
+ * GET /api/analytics/jobs/:jobId/tokens
+ * Get per-job token usage (delta computed from cumulative snapshots)
+ */
+router.get('/jobs/:jobId/tokens', async (req, res) => {
+    let dbService;
+    try {
+        const apiKeyData = req.apiKeyData;
+        if (!apiKeyData) {
+            return res.status(401).json({ error: 'Authentication required' });
+        }
+        const jobId = req.params.jobId;
+        if (!jobId) {
+            return res.status(400).json({ error: 'jobId parameter is required' });
+        }
+        dbService = new db_service_js_1.FraimDbService();
+        await dbService.connect();
+        const targetUserId = await resolveTargetUserIdFromQuery(dbService, apiKeyData, req.query);
+        const result = await dbService.getTokenUsageByJob(jobId, targetUserId);
+        if (!result) {
+            return res.json({
+                jobId,
+                inputTokens: null,
+                outputTokens: null,
+                cacheReadTokens: null,
+                cacheCreationTokens: null,
+                costUsd: null,
+                model: null,
+                isPartial: false,
+                snapshotCount: 0,
+            });
+        }
+        res.json(result);
+    }
+    catch (error) {
+        if (error.status === 403)
+            return res.status(403).json({ error: error.message });
+        if (error.status === 404)
+            return res.status(404).json({ error: error.message });
+        console.error('Error fetching job token usage:', error);
+        res.status(500).json({ error: 'Internal server error' });
+    }
+    finally {
+        if (dbService) {
+            await dbService.close();
+        }
+    }
+});
+/**
+ * GET /api/analytics/usage/aggregate
+ * Issue #330 / R2.1 — token + cost aggregate for the You / Team accordion.
+ * Honors apiKey admin-gate (C2) and rejects local-path repoIdentifier (C3).
+ */
+router.get('/usage/aggregate', async (req, res) => {
+    let dbService;
+    try {
+        const apiKeyData = req.apiKeyData;
+        if (!apiKeyData) {
+            return res.status(401).json({ error: 'Authentication required' });
+        }
+        const { apiKey, repoIdentifier } = req.query;
+        const timeframe = resolveAnalyticsTimeframe(req.query);
+        // C3 — reject explicit local-path repoIdentifier inputs early.
+        if (repoIdentifier && typeof repoIdentifier === 'string' && repoIdentifier.length > 0 && (0, git_utils_js_1.isExplicitLocalRepoPath)(repoIdentifier)) {
+            return res.status(400).json({ error: 'Invalid repoIdentifier — local paths are not permitted' });
+        }
+        dbService = new db_service_js_1.FraimDbService();
+        await dbService.connect();
+        // C2 — admin-only when querying another user's data.
+        let targetUserId;
+        if (apiKey && typeof apiKey === 'string') {
+            const isAdmin = apiKeyData.userId === 'sid.mathur@gmail.com';
+            if (!isAdmin) {
+                return res.status(403).json({ error: 'Admin access required to view other users data' });
+            }
+            const targetApiKeyData = await dbService.getApiKeyByKey(apiKey);
+            if (!targetApiKeyData) {
+                return res.status(404).json({ error: 'API key not found' });
+            }
+            targetUserId = targetApiKeyData.userId;
+        }
+        else {
+            targetUserId = apiKeyData.userId;
+        }
+        const aggregate = await dbService.getUsageAggregate({
+            userId: targetUserId,
+            startDate: timeframe.startDate ?? new Date(Date.now() - 30 * 24 * 60 * 60 * 1000),
+            endDate: timeframe.endDate,
+            repoIdentifier: typeof repoIdentifier === 'string' ? repoIdentifier : undefined,
+        });
+        res.json(aggregate);
+    }
+    catch (error) {
+        console.error('Error fetching usage aggregate:', error);
+        res.status(500).json({ error: 'Internal server error' });
+    }
+    finally {
+        if (dbService) {
+            await dbService.close();
+        }
+    }
+});
+/**
+ * GET /api/analytics/jobs/:jobName/agent-summary
+ * Issue #330 / R2.8 — per-job-name agent split for the per-job page.
+ */
+router.get('/jobs/:jobName/agent-summary', async (req, res) => {
+    let dbService;
+    try {
+        const apiKeyData = req.apiKeyData;
+        if (!apiKeyData) {
+            return res.status(401).json({ error: 'Authentication required' });
+        }
+        const jobName = String(req.params.jobName || '');
+        if (!jobName) {
+            return res.status(400).json({ error: 'jobName parameter is required' });
+        }
+        const { repoIdentifier } = req.query;
+        const timeframe = resolveAnalyticsTimeframe(req.query);
+        if (repoIdentifier && typeof repoIdentifier === 'string' && repoIdentifier.length > 0 && (0, git_utils_js_1.isExplicitLocalRepoPath)(repoIdentifier)) {
+            return res.status(400).json({ error: 'Invalid repoIdentifier — local paths are not permitted' });
+        }
+        dbService = new db_service_js_1.FraimDbService();
+        await dbService.connect();
+        const targetUserId = await resolveTargetUserIdFromQuery(dbService, apiKeyData, req.query);
+        const summary = await dbService.getJobAgentSummary({
+            jobName,
+            userId: targetUserId,
+            startDate: timeframe.startDate ?? new Date(Date.now() - 30 * 24 * 60 * 60 * 1000),
+            endDate: timeframe.endDate,
+            repoIdentifier: typeof repoIdentifier === 'string' ? repoIdentifier : undefined,
+        });
+        res.json(summary);
+    }
+    catch (error) {
+        if (error.status === 403)
+            return res.status(403).json({ error: error.message });
+        if (error.status === 404)
+            return res.status(404).json({ error: error.message });
+        console.error('Error fetching job agent summary:', error);
+        res.status(500).json({ error: 'Internal server error' });
+    }
+    finally {
+        if (dbService) {
+            await dbService.close();
+        }
+    }
+});
+/**
+ * GET /api/analytics/jobs/token-summary
+ * Aggregated token usage across all jobs for a user
+ */
+router.get('/jobs/token-summary', async (req, res) => {
+    let dbService;
+    try {
+        const apiKeyData = req.apiKeyData;
+        if (!apiKeyData) {
+            return res.status(401).json({ error: 'Authentication required' });
+        }
+        const period = req.query.period || '30d';
+        const daysMatch = period.match(/^(\d+)d$/);
+        const days = daysMatch ? parseInt(daysMatch[1], 10) : 30;
+        const startDate = new Date();
+        startDate.setDate(startDate.getDate() - days);
+        dbService = new db_service_js_1.FraimDbService();
+        await dbService.connect();
+        const result = await dbService.getTokenUsageSummary(apiKeyData.userId, startDate);
+        res.json(result);
+    }
+    catch (error) {
+        console.error('Error fetching token usage summary:', error);
+        res.status(500).json({ error: 'Internal server error' });
+    }
+    finally {
+        if (dbService) {
+            await dbService.close();
+        }
+    }
+});
+/**
+ * GET /api/analytics/export
+ * Export usage data as CSV
+ */
+router.get('/export', async (req, res) => {
+    let dbService;
+    let analyticsService;
+    try {
+        // Get API key data from middleware
+        const apiKeyData = req.apiKeyData;
+        if (!apiKeyData) {
+            return res.status(401).json({ error: 'Authentication required' });
+        }
+        const { format = 'csv', limit = '100', apiKey, repoIdentifier } = req.query;
+        const timeframe = resolveAnalyticsTimeframe(req.query);
+        if (format !== 'csv') {
+            return res.status(400).json({ error: 'Only CSV format is currently supported' });
+        }
+        // Create database connection
+        dbService = new db_service_js_1.FraimDbService();
+        await dbService.connect();
+        // Create analytics service
+        analyticsService = new usage_analytics_service_js_1.UsageAnalyticsService(dbService);
+        let targetUserId;
+        if (apiKey && typeof apiKey === 'string') {
+            const isAdmin = apiKeyData.userId === 'sid.mathur@gmail.com';
+            if (!isAdmin) {
+                return res.status(403).json({ error: 'Admin access required to view other users data' });
+            }
+            const targetApiKeyData = await dbService.getApiKeyByKey(apiKey);
+            if (!targetApiKeyData) {
+                return res.status(404).json({ error: 'API key not found' });
+            }
+            targetUserId = targetApiKeyData.userId;
+        }
+        else {
+            targetUserId = apiKeyData.userId;
+        }
+        const csvData = await analyticsService.exportUsageData({
+            period: timeframe.period,
+            startDate: timeframe.startDate,
+            endDate: timeframe.endDate,
+            limit: parseInt(limit, 10),
+            userId: targetUserId,
+            repoIdentifier: repoIdentifier
+        });
+        res.setHeader('Content-Type', 'text/csv');
+        res.setHeader('Content-Disposition', `attachment; filename="usage-analytics-${timeframe.period}.csv"`);
+        res.send(csvData);
+    }
+    catch (error) {
+        console.error('Error exporting usage data:', error);
+        res.status(500).json({ error: 'Internal server error' });
+    }
+    finally {
+        if (dbService) {
+            await dbService.close();
+        }
+    }
+});
+/**
+ * GET /api/analytics/users
+ * Get list of users with their API keys and event counts (admin only)
+ */
+router.get('/users', async (req, res) => {
+    let dbService;
+    try {
+        // Get API key data from middleware
+        const apiKeyData = req.apiKeyData;
+        if (!apiKeyData) {
+            return res.status(401).json({ error: 'Authentication required' });
+        }
+        // Check if user is admin (FRAIM builder)
+        const isAdmin = apiKeyData.userId === 'sid.mathur@gmail.com';
+        if (!isAdmin) {
+            return res.status(403).json({ error: 'Admin access required' });
+        }
+        // Create database connection
+        dbService = new db_service_js_1.FraimDbService();
+        await dbService.connect();
+        // Get all API keys
+        const apiKeys = await dbService.listApiKeys();
+        // Get event counts for each API key
+        const db = await dbService.getDb();
+        const usageCollection = db.collection('fraim_usage_events');
+        const usersWithCounts = await Promise.all(apiKeys.map(async (apiKey) => {
+            const eventCount = await usageCollection.countDocuments({
+                userId: apiKey.userId
+            });
+            return {
+                key: apiKey.key,
+                userId: apiKey.userId,
+                eventCount,
+                status: apiKey.status || 'active'
+            };
+        }));
+        // Sort by event count (descending) then by userId
+        usersWithCounts.sort((a, b) => {
+            if (b.eventCount !== a.eventCount) {
+                return b.eventCount - a.eventCount;
+            }
+            return a.userId.localeCompare(b.userId);
+        });
+        res.json(usersWithCounts);
+    }
+    catch (error) {
+        console.error('Error fetching users:', error);
+        res.status(500).json({ error: 'Internal server error' });
+    }
+    finally {
+        if (dbService) {
+            await dbService.close();
+        }
+    }
+});
+/**
+ * GET /api/analytics/repos
+ * Get unique repositories that have generated telemetry for a user
+ */
+router.get('/repos', async (req, res) => {
+    let dbService;
+    let analyticsService;
+    try {
+        const apiKeyData = req.apiKeyData;
+        if (!apiKeyData) {
+            return res.status(401).json({ error: 'Authentication required' });
+        }
+        dbService = new db_service_js_1.FraimDbService();
+        await dbService.connect();
+        analyticsService = new usage_analytics_service_js_1.UsageAnalyticsService(dbService);
+        const repos = await analyticsService.getUniqueRepos(apiKeyData.userId);
+        res.json(repos);
+    }
+    catch (error) {
+        console.error('Error fetching repositories:', error);
+        res.status(500).json({ error: 'Internal server error' });
+    }
+    finally {
+        if (dbService) {
+            await dbService.close();
+        }
+    }
+});
+/**
+ * POST /api/analytics/events
+ * Batch upload usage events (for telemetry integration)
+ */
+router.post('/events', async (req, res) => {
+    let dbService;
+    let analyticsService;
+    try {
+        const apiKeyData = req.apiKeyData;
+        const { events } = req.body;
+        if (!Array.isArray(events)) {
+            return res.status(400).json({ error: 'Events must be an array' });
+        }
+        // Create database connection
+        dbService = new db_service_js_1.FraimDbService();
+        await dbService.connect();
+        // Create analytics service
+        analyticsService = new usage_analytics_service_js_1.UsageAnalyticsService(dbService);
+        // Process events in batch
+        const processedEvents = events.map(event => ({
+            type: event.type,
+            name: event.name,
+            userId: apiKeyData.userId,
+            sessionId: event.sessionId,
+            success: event.success !== false, // default to true
+            category: event.category || 'uncategorized',
+            args: event.args && typeof event.args === 'object' ? event.args : undefined,
+            jobId: event.jobId,
+            jobPhase: event.jobPhase,
+            tokenSnapshot: event.tokenSnapshot && typeof event.tokenSnapshot === 'object'
+                ? event.tokenSnapshot
+                : undefined,
+            repoIdentifier: event.repoIdentifier,
+            // Issue #330: pass through agent attribution + capture-coverage signaling
+            agentName: typeof event.agentName === 'string' ? event.agentName.toLowerCase() : undefined,
+            agentModel: typeof event.agentModel === 'string' ? event.agentModel : undefined,
+            tokenCaptureUnavailableReason: typeof event.tokenCaptureUnavailableReason === 'string'
+                ? event.tokenCaptureUnavailableReason
+                : undefined,
+        }));
+        // Persist uploaded telemetry immediately. This endpoint already receives
+        // batches from the local proxy, so re-queueing inside a per-request
+        // service instance only adds nondeterministic timing.
+        if (!analyticsService) {
+            throw new Error('Analytics service not initialized');
+        }
+        await Promise.all(processedEvents.map(event => analyticsService.logUsageImmediate(event)));
+        res.json({
+            message: 'Events processed',
+            count: processedEvents.length
+        });
+    }
+    catch (error) {
+        console.error('Error processing events:', error);
+        res.status(500).json({ error: 'Internal server error' });
+    }
+    finally {
+        if (dbService) {
+            await dbService.close();
+        }
+    }
+});
+/**
+ * POST /api/analytics/quality-score
+ *
+ * Emit a quality score for a completed quality-producing job (Issue #251).
+ *
+ * Called by the local MCP proxy on the final seekMentoring completion of a
+ * quality-producing job. The local proxy short-circuits seekMentoring for
+ * performance and personalized-job support, so the server-side mcp-service
+ * enforcement in handleSeekMentoring is rarely reached in practice. This
+ * dedicated endpoint is the primary write path for `fraim_quality_scores`.
+ *
+ * Request body:
+ * {
+ *   jobName:     string  // must be in QUALITY_PRODUCING_JOBS
+ *   jobId:       string
+ *   sessionId:   string
+ *   quality:     object  // must validate per REQUIRED_QUALITY_FIELDS
+ *   artifactPath:  string
+ *   repoIdentifier?: string
+ *   reviewContext?: {
+ *     subjectType?: string
+ *     subjectLabel?: string
+ *     reviewRef?: string
+ *     scopeSummary?: string
+ *     repoIdentifier?: string
+ *     branchRef?: string
+ *   }
+ * }
+ *
+ * Responses:
+ *   200 { message: "Quality score recorded" }
+ *   400 { error, details? }  — validation failed
+ *   401 { error }            — missing api key
+ */
+router.post('/quality-score', async (req, res) => {
+    let dbService;
+    try {
+        const apiKeyData = req.apiKeyData;
+        if (!apiKeyData) {
+            return res.status(401).json({ error: 'Authentication required' });
+        }
+        const { jobName, jobId, sessionId, quality, artifactPath, repoIdentifier, reviewContext } = req.body || {};
+        if (typeof jobName !== 'string' || !jobName) {
+            return res.status(400).json({ error: 'jobName is required' });
+        }
+        if (!mcp_service_js_1.QUALITY_PRODUCING_JOBS.includes(jobName)) {
+            return res.status(400).json({
+                error: `jobName "${jobName}" is not a quality-producing job`,
+                allowed: mcp_service_js_1.QUALITY_PRODUCING_JOBS
+            });
+        }
+        if (typeof jobId !== 'string' || !jobId) {
+            return res.status(400).json({ error: 'jobId is required' });
+        }
+        if (typeof sessionId !== 'string' || !sessionId) {
+            return res.status(400).json({ error: 'sessionId is required' });
+        }
+        const qualityErrors = mcp_service_js_1.McpService.validateQualityEvidence(quality, jobName);
+        if (qualityErrors) {
+            return res.status(400).json({
+                error: 'evidence.quality failed validation',
+                details: qualityErrors
+            });
+        }
+        if (typeof artifactPath !== 'string' || !artifactPath.trim()) {
+            return res.status(400).json({ error: 'artifactPath is required' });
+        }
+        dbService = new db_service_js_1.FraimDbService();
+        await dbService.connect();
+        const analyticsService = new usage_analytics_service_js_1.UsageAnalyticsService(dbService);
+        const normalizedReviewContext = reviewContext && typeof reviewContext === 'object' && !Array.isArray(reviewContext)
+            ? {
+                subjectType: typeof reviewContext.subjectType === 'string' ? reviewContext.subjectType : undefined,
+                subjectLabel: typeof reviewContext.subjectLabel === 'string' ? reviewContext.subjectLabel : undefined,
+                reviewRef: typeof reviewContext.reviewRef === 'string' ? reviewContext.reviewRef : undefined,
+                scopeSummary: typeof reviewContext.scopeSummary === 'string' ? reviewContext.scopeSummary : undefined,
+                repoIdentifier: typeof reviewContext.repoIdentifier === 'string' ? reviewContext.repoIdentifier : undefined,
+                branchRef: typeof reviewContext.branchRef === 'string' ? reviewContext.branchRef : undefined
+            }
+            : undefined;
+        let effectiveRepoIdentifier = typeof repoIdentifier === 'string' ? repoIdentifier : normalizedReviewContext?.repoIdentifier;
+        if (!effectiveRepoIdentifier && typeof apiKeyData.key === 'string') {
+            const session = await dbService.getSessionByApiKeyAndSessionId(apiKeyData.key, sessionId);
+            const sessionRepoUrl = typeof session?.repo?.url === 'string' ? session.repo.url : undefined;
+            effectiveRepoIdentifier = sessionRepoUrl;
+        }
+        await analyticsService.logQualityScore(apiKeyData.userId, jobName, jobId, sessionId, quality, typeof artifactPath === 'string' ? artifactPath : undefined, effectiveRepoIdentifier, normalizedReviewContext);
+        res.json({ message: 'Quality score recorded' });
+    }
+    catch (error) {
+        console.error('[quality-score] Error:', error);
+        res.status(500).json({ error: 'Failed to record quality score' });
+    }
+    finally {
+        if (dbService) {
+            try {
+                await dbService.close();
+            }
+            catch { /* ignore */ }
+        }
+    }
+});
+/**
+ * GET /api/analytics/me
+ * Get current user information
+ */
+router.get('/me', async (req, res) => {
+    try {
+        // Get API key data from middleware
+        const apiKeyData = req.apiKeyData;
+        if (!apiKeyData) {
+            return res.status(401).json({ error: 'Authentication required' });
+        }
+        res.json({
+            userId: apiKeyData.userId,
+            isAdmin: apiKeyData.userId === 'sid.mathur@gmail.com',
+            ...serializeKeyLifecycle(apiKeyData),
+        });
+    }
+    catch (error) {
+        console.error('Error getting user info:', error);
+        res.status(500).json({ error: 'Failed to get user information' });
+    }
+});
+// ===== TEAM ROUTES =====
+function parsePeriodDays(period) {
+    const n = parseInt(period);
+    return isNaN(n) ? 30 : n;
+}
+function parseDateParam(value, endOfDay = false) {
+    if (typeof value !== 'string' || !value.trim())
+        return undefined;
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime()))
+        return undefined;
+    if (endOfDay) {
+        date.setHours(23, 59, 59, 999);
+    }
+    else {
+        date.setHours(0, 0, 0, 0);
+    }
+    return date;
+}
+function resolveAnalyticsTimeframe(query) {
+    const period = typeof query.period === 'string' && query.period ? query.period : '30d';
+    const startDate = parseDateParam(query.startDate);
+    const endDate = parseDateParam(query.endDate, true);
+    if ((query.startDate || query.endDate) && (!startDate || !endDate)) {
+        const err = new Error('Both startDate and endDate must be valid ISO date strings');
+        err.status = 400;
+        throw err;
+    }
+    if (startDate && endDate && startDate > endDate) {
+        const err = new Error('startDate must be on or before endDate');
+        err.status = 400;
+        throw err;
+    }
+    return startDate && endDate ? { period: 'custom', startDate, endDate } : { period };
+}
+function serializeKeyLifecycle(keyData) {
+    if (!keyData) {
+        return { status: null, expiresAt: null };
+    }
+    return {
+        status: keyData.status ?? 'active',
+        expiresAt: keyData.expiresAt instanceof Date ? keyData.expiresAt.toISOString() : null,
+    };
+}
+async function resolveManagerMember(dbService, managerId, memberId) {
+    const members = await dbService.getTeamMembers(managerId);
+    if (!members.find(m => m.memberId === memberId)) {
+        const err = new Error('Not authorized to view this member');
+        err.status = 403;
+        throw err;
+    }
+    return memberId;
+}
+/**
+ * Resolve the userId to query based on optional delegation params.
+ *
+ * Accepts ?userId=<email> (manager → team member, checked via resolveManagerMember)
+ * or the legacy ?apiKey=<key> (admin-only backward compat).
+ * Falls back to the authenticated caller's own userId.
+ */
+async function resolveTargetUserIdFromQuery(dbService, apiKeyData, query) {
+    const targetUserIdParam = typeof query.userId === 'string' ? query.userId : undefined;
+    const targetApiKeyParam = typeof query.apiKey === 'string' ? query.apiKey : undefined;
+    if (targetUserIdParam && targetUserIdParam !== apiKeyData.userId) {
+        const isAdmin = apiKeyData.userId === 'sid.mathur@gmail.com';
+        if (!isAdmin) {
+            await resolveManagerMember(dbService, apiKeyData.userId, targetUserIdParam);
+        }
+        return targetUserIdParam;
+    }
+    if (targetApiKeyParam) {
+        const isAdmin = apiKeyData.userId === 'sid.mathur@gmail.com';
+        if (!isAdmin) {
+            const err = new Error('Admin access required to view other users data');
+            err.status = 403;
+            throw err;
+        }
+        const targetApiKeyData = await dbService.getApiKeyByKey(targetApiKeyParam);
+        if (!targetApiKeyData) {
+            const err = new Error('API key not found');
+            err.status = 404;
+            throw err;
+        }
+        return targetApiKeyData.userId;
+    }
+    return apiKeyData.userId;
+}
+/**
+ * GET /api/analytics/team/members/list
+ * Returns team member IDs only — fast, no stats queries.
+ * Used by the dashboard to render the member list immediately before lazy-loading stats.
+ */
+router.get('/team/members/list', async (req, res) => {
+    let dbService;
+    try {
+        const apiKeyData = req.apiKeyData;
+        if (!apiKeyData)
+            return res.status(401).json({ error: 'Authentication required' });
+        dbService = new db_service_js_1.FraimDbService();
+        await dbService.connect();
+        const members = await dbService.getTeamMembers(apiKeyData.userId);
+        res.json(members.map(m => ({ memberId: m.memberId, labels: m.labels || [] })));
+    }
+    catch (error) {
+        res.status(error.status || 500).json({ error: error.message || 'Failed to load team' });
+    }
+    finally {
+        if (dbService)
+            await dbService.close();
+    }
+});
+/**
+ * GET /api/analytics/team/members/:memberId/summary?period=30d
+ * Returns stats for a single member. Called lazily per-member after the list renders.
+ */
+router.get('/team/members/:memberId/summary', async (req, res) => {
+    let dbService;
+    try {
+        const apiKeyData = req.apiKeyData;
+        if (!apiKeyData)
+            return res.status(401).json({ error: 'Authentication required' });
+        const timeframe = resolveAnalyticsTimeframe(req.query);
+        const memberId = req.params.memberId;
+        dbService = new db_service_js_1.FraimDbService();
+        await dbService.connect();
+        await resolveManagerMember(dbService, apiKeyData.userId, memberId); // auth check
+        const analyticsService = new usage_analytics_service_js_1.UsageAnalyticsService(dbService);
+        const [dominant, stats, allTimeLastEventAt, hasFraimSetup, keyLifecycle] = await Promise.allSettled([
+            analyticsService.getDominantJobCategory(timeframe.period, memberId, undefined, timeframe.startDate, timeframe.endDate),
+            analyticsService.getUsageStats({ period: timeframe.period, startDate: timeframe.startDate, endDate: timeframe.endDate, types: ['job'], userId: memberId }),
+            dbService.getLatestUsageEventAt(memberId, ['job']),
+            dbService.hasFraimSetup(memberId),
+            dbService.getApiKeyByUserId(memberId, false),
+        ]);
+        const lastEventAt = stats.status === 'fulfilled' ? stats.value.lastEventAt ?? null : null;
+        const historicalLastEventAt = allTimeLastEventAt.status === 'fulfilled' ? allTimeLastEventAt.value ?? null : null;
+        const lifecycle = keyLifecycle.status === 'fulfilled'
+            ? serializeKeyLifecycle(keyLifecycle.value)
+            : { status: null, expiresAt: null };
+        res.json({
+            memberId,
+            dominantCategory: dominant.status === 'fulfilled' ? dominant.value?.category ?? null : null,
+            dominantCategoryCount: dominant.status === 'fulfilled' ? dominant.value?.count ?? 0 : 0,
+            totalEvents: stats.status === 'fulfilled' ? stats.value.totalEvents : 0,
+            hasFraimSetup: hasFraimSetup.status === 'fulfilled' ? hasFraimSetup.value : false,
+            lastEventAt,
+            allTimeLastEventAt: historicalLastEventAt,
+            lastActiveAt: lastEventAt,
+            ...lifecycle,
+        });
+    }
+    catch (error) {
+        res.status(error.status || 500).json({ error: error.message || 'Failed to load member summary' });
+    }
+    finally {
+        if (dbService)
+            await dbService.close();
+    }
+});
+/**
+ * GET /api/analytics/team/members?period=30d
+ * Returns team members with dominant category (manager view).
+ * Kept for backwards compatibility — prefer /list + /summary for non-blocking UI.
+ */
+router.get('/team/members', async (req, res) => {
+    let dbService;
+    try {
+        const apiKeyData = req.apiKeyData;
+        if (!apiKeyData)
+            return res.status(401).json({ error: 'Authentication required' });
+        const timeframe = resolveAnalyticsTimeframe(req.query);
+        dbService = new db_service_js_1.FraimDbService();
+        await dbService.connect();
+        const analyticsService = new usage_analytics_service_js_1.UsageAnalyticsService(dbService);
+        const members = await dbService.getTeamMembers(apiKeyData.userId);
+        if (members.length === 0)
+            return res.json([]);
+        const results = await Promise.allSettled(members.map(async (m) => {
+            const [dominant, stats, allTimeLastEventAt, hasFraimSetup] = await Promise.allSettled([
+                analyticsService.getDominantJobCategory(timeframe.period, m.memberId, undefined, timeframe.startDate, timeframe.endDate),
+                analyticsService.getUsageStats({ period: timeframe.period, startDate: timeframe.startDate, endDate: timeframe.endDate, types: ['job'], userId: m.memberId }),
+                dbService.getLatestUsageEventAt(m.memberId, ['job']),
+                dbService.hasFraimSetup(m.memberId)
+            ]);
+            const lastEventAt = stats.status === 'fulfilled' ? stats.value.lastEventAt ?? null : null;
+            const historicalLastEventAt = allTimeLastEventAt.status === 'fulfilled' ? allTimeLastEventAt.value ?? null : null;
+            return {
+                memberId: m.memberId,
+                labels: m.labels || [],
+                dominantCategory: dominant.status === 'fulfilled' ? dominant.value?.category ?? null : null,
+                dominantCategoryCount: dominant.status === 'fulfilled' ? dominant.value?.count ?? 0 : 0,
+                totalEvents: stats.status === 'fulfilled' ? stats.value.totalEvents : 0,
+                hasFraimSetup: hasFraimSetup.status === 'fulfilled' ? hasFraimSetup.value : false,
+                lastEventAt,
+                allTimeLastEventAt: historicalLastEventAt,
+                lastActiveAt: lastEventAt
+            };
+        }));
+        res.json(results
+            .filter(r => r.status === 'fulfilled')
+            .map(r => r.value));
+    }
+    catch (error) {
+        res.status(error.status || 500).json({ error: error.message || 'Failed to load team' });
+    }
+    finally {
+        if (dbService)
+            await dbService.close();
+    }
+});
+/**
+ * GET /api/analytics/team/member/:memberId/stats
+ */
+router.get('/team/member/:memberId/stats', async (req, res) => {
+    let dbService;
+    try {
+        const apiKeyData = req.apiKeyData;
+        if (!apiKeyData)
+            return res.status(401).json({ error: 'Authentication required' });
+        const { memberId } = req.params;
+        const { repoIdentifier } = req.query;
+        const timeframe = resolveAnalyticsTimeframe(req.query);
+        dbService = new db_service_js_1.FraimDbService();
+        await dbService.connect();
+        const memberUserId = await resolveManagerMember(dbService, apiKeyData.userId, memberId);
+        const analyticsService = new usage_analytics_service_js_1.UsageAnalyticsService(dbService);
+        const stats = await analyticsService.getUsageStats({
+            period: timeframe.period,
+            startDate: timeframe.startDate,
+            endDate: timeframe.endDate,
+            types: ['job'],
+            userId: memberUserId,
+            repoIdentifier: repoIdentifier
+        });
+        res.json(stats);
+    }
+    catch (error) {
+        res.status(error.status || 500).json({ error: error.message || 'Failed to load member stats' });
+    }
+    finally {
+        if (dbService)
+            await dbService.close();
+    }
+});
+/**
+ * GET /api/analytics/team/member/:memberId/usage/aggregate
+ * Issue #330 / R2.5 — token + cost aggregate for a team member, scoped
+ * to the calling manager's permission set via resolveManagerMember.
+ */
+router.get('/team/member/:memberId/usage/aggregate', async (req, res) => {
+    let dbService;
+    try {
+        const apiKeyData = req.apiKeyData;
+        if (!apiKeyData)
+            return res.status(401).json({ error: 'Authentication required' });
+        const { memberId } = req.params;
+        const { repoIdentifier } = req.query;
+        const timeframe = resolveAnalyticsTimeframe(req.query);
+        if (repoIdentifier && typeof repoIdentifier === 'string' && repoIdentifier.length > 0 && (0, git_utils_js_1.isExplicitLocalRepoPath)(repoIdentifier)) {
+            return res.status(400).json({ error: 'Invalid repoIdentifier — local paths are not permitted' });
+        }
+        dbService = new db_service_js_1.FraimDbService();
+        await dbService.connect();
+        const memberUserId = await resolveManagerMember(dbService, apiKeyData.userId, memberId);
+        const aggregate = await dbService.getUsageAggregate({
+            userId: memberUserId,
+            startDate: timeframe.startDate ?? new Date(Date.now() - 30 * 24 * 60 * 60 * 1000),
+            endDate: timeframe.endDate,
+            repoIdentifier: typeof repoIdentifier === 'string' ? repoIdentifier : undefined,
+        });
+        res.json(aggregate);
+    }
+    catch (error) {
+        res.status(error.status || 500).json({ error: error.message || 'Failed to load member usage aggregate' });
+    }
+    finally {
+        if (dbService)
+            await dbService.close();
+    }
+});
+/**
+ * GET /api/analytics/team/member/:memberId/components/top
+ */
+router.get('/team/member/:memberId/components/top', async (req, res) => {
+    let dbService;
+    try {
+        const apiKeyData = req.apiKeyData;
+        if (!apiKeyData)
+            return res.status(401).json({ error: 'Authentication required' });
+        const { memberId } = req.params;
+        const { limit = '10', repoIdentifier } = req.query;
+        const timeframe = resolveAnalyticsTimeframe(req.query);
+        dbService = new db_service_js_1.FraimDbService();
+        await dbService.connect();
+        const memberUserId = await resolveManagerMember(dbService, apiKeyData.userId, memberId);
+        const analyticsService = new usage_analytics_service_js_1.UsageAnalyticsService(dbService);
+        const components = await analyticsService.getTopComponents(parseInt(limit, 10), timeframe.period, ['job'], memberUserId, repoIdentifier, timeframe.startDate, timeframe.endDate);
+        res.json(components);
+    }
+    catch (error) {
+        res.status(error.status || 500).json({ error: error.message || 'Failed to load member components' });
+    }
+    finally {
+        if (dbService)
+            await dbService.close();
+    }
+});
+/**
+ * GET /api/analytics/team/member/:memberId/jobs/timeline
+ */
+router.get('/team/member/:memberId/jobs/timeline', async (req, res) => {
+    let dbService;
+    try {
+        const apiKeyData = req.apiKeyData;
+        if (!apiKeyData)
+            return res.status(401).json({ error: 'Authentication required' });
+        const { memberId } = req.params;
+        const { dateUnit, repoIdentifier } = req.query;
+        const timeframe = resolveAnalyticsTimeframe(req.query);
+        dbService = new db_service_js_1.FraimDbService();
+        await dbService.connect();
+        const memberUserId = await resolveManagerMember(dbService, apiKeyData.userId, memberId);
+        const analyticsService = new usage_analytics_service_js_1.UsageAnalyticsService(dbService);
+        const timeline = await analyticsService.getJobRunsOverTime(timeframe.period, memberUserId, dateUnit, repoIdentifier, timeframe.startDate, timeframe.endDate);
+        res.json(timeline);
+    }
+    catch (error) {
+        res.status(error.status || 500).json({ error: error.message || 'Failed to load member timeline' });
+    }
+    finally {
+        if (dbService)
+            await dbService.close();
+    }
+});
+router.get('/team/member/:memberId/repos', async (req, res) => {
+    let dbService;
+    try {
+        const apiKeyData = req.apiKeyData;
+        if (!apiKeyData)
+            return res.status(401).json({ error: 'Authentication required' });
+        const { memberId } = req.params;
+        dbService = new db_service_js_1.FraimDbService();
+        await dbService.connect();
+        const memberUserId = await resolveManagerMember(dbService, apiKeyData.userId, memberId);
+        const analyticsService = new usage_analytics_service_js_1.UsageAnalyticsService(dbService);
+        const repos = await analyticsService.getUniqueRepos(memberUserId);
+        res.json(repos);
+    }
+    catch (error) {
+        res.status(error.status || 500).json({ error: error.message || 'Failed to load member repositories' });
+    }
+    finally {
+        if (dbService)
+            await dbService.close();
+    }
+});
+/**
+ * GET /api/analytics/team/my-managers
+ * Returns list of manager emails for the current user (for transparency notice)
+ */
+router.get('/team/my-managers', async (req, res) => {
+    let dbService;
+    try {
+        const apiKeyData = req.apiKeyData;
+        if (!apiKeyData)
+            return res.status(401).json({ error: 'Authentication required' });
+        dbService = new db_service_js_1.FraimDbService();
+        await dbService.connect();
+        const managers = await dbService.getManagersForMember(apiKeyData.userId);
+        res.json(managers);
+    }
+    catch (error) {
+        res.status(500).json({ error: 'Failed to load managers' });
+    }
+    finally {
+        if (dbService)
+            await dbService.close();
+    }
+});
+/**
+ * GET /api/analytics/team/member/:memberId/quality/interviews
+ * Returns per-interview quality scores and latest gate decision for a team member.
+ * Used by the manager dashboard Quality tab (Issue #251).
+ */
+router.get('/team/member/:memberId/quality/interviews', async (req, res) => {
+    let dbService;
+    try {
+        const apiKeyData = req.apiKeyData;
+        if (!apiKeyData)
+            return res.status(401).json({ error: 'Authentication required' });
+        const { memberId } = req.params;
+        const { repoIdentifier } = req.query;
+        dbService = new db_service_js_1.FraimDbService();
+        await dbService.connect();
+        // Privacy check: manager must have active relationship with member
+        await resolveManagerMember(dbService, apiKeyData.userId, memberId);
+        // Fetch interview quality scores (chronological)
+        const interviewScores = await dbService.getQualityScores(memberId, 'process-interview-notes', undefined, repoIdentifier);
+        // Fetch latest triage/gate decision
+        const latestGate = await dbService.getLatestQualityScore(memberId, 'triage-customer-needs', repoIdentifier);
+        // Compute trend from interview scores
+        let trend = 'stable';
+        if (interviewScores.length >= 3) {
+            const midpoint = Math.floor(interviewScores.length / 2);
+            const firstHalf = interviewScores.slice(0, midpoint);
+            const secondHalf = interviewScores.slice(midpoint);
+            const firstAvg = firstHalf.reduce((sum, s) => sum + (s.scores.composite ?? 0), 0) / firstHalf.length;
+            const secondAvg = secondHalf.reduce((sum, s) => sum + (s.scores.composite ?? 0), 0) / secondHalf.length;
+            if (secondAvg > firstAvg + 0.5)
+                trend = 'improving';
+            else if (secondAvg < firstAvg - 0.5)
+                trend = 'declining';
+        }
+        // Compute average composite
+        const avgComposite = interviewScores.length > 0
+            ? interviewScores.reduce((sum, s) => sum + (s.scores.composite ?? 0), 0) / interviewScores.length
+            : 0;
+        // Format response
+        const interviews = interviewScores.map(s => ({
+            interviewee: s.scores.interviewee ?? s.scores.participant?.name ?? 'Unknown',
+            company: s.scores.company ?? s.scores.participant?.company ?? '',
+            composite: s.scores.composite ?? 0,
+            participantFit: s.scores.participant?.fit ?? 0,
+            evidenceQuality: s.scores.evidence?.quoteSpecificityAvg ?? 0,
+            completeness: s.scores.completeness ?? 0,
+            coaching: s.scores.coaching ?? '',
+            createdAt: s.createdAt
+        }));
+        res.json({
+            interviews,
+            count: interviews.length,
+            avgComposite: Math.round(avgComposite * 10) / 10,
+            trend,
+            latestGate: latestGate ? {
+                decision: latestGate.scores.gateDecision,
+                interviewsAnalyzed: latestGate.scores.interviewsAnalyzed,
+                targetInterviews: latestGate.scores.targetInterviews,
+                distinctPainPatterns: latestGate.scores.distinctPainPatterns,
+                customersPerPattern: latestGate.scores.customersPerPattern,
+                gaps: latestGate.scores.gaps ?? [],
+                coaching: latestGate.scores.coaching ?? '',
+                createdAt: latestGate.createdAt
+            } : null
+        });
+    }
+    catch (error) {
+        res.status(error.status || 500).json({ error: error.message || 'Failed to load quality data' });
+    }
+    finally {
+        if (dbService)
+            await dbService.close();
+    }
+});
+/**
+ * POST /api/analytics/quality
+ * Ingest quality score events from the local proxy batch pipeline.
+ */
+router.post('/quality', async (req, res) => {
+    let dbService;
+    try {
+        const apiKeyData = req.apiKeyData;
+        if (!apiKeyData)
+            return res.status(401).json({ error: 'Authentication required' });
+        const { userId, jobName, jobId, sessionId, scores, artifactPath } = req.body;
+        if (!userId || !jobName || !jobId || !scores) {
+            return res.status(400).json({ error: 'Missing required fields: userId, jobName, jobId, scores' });
+        }
+        dbService = new db_service_js_1.FraimDbService();
+        await dbService.connect();
+        await dbService.insertQualityScore({
+            userId,
+            jobName,
+            jobId,
+            sessionId: sessionId ?? 'unknown',
+            scores,
+            artifactPath,
+            createdAt: new Date()
+        });
+        res.json({ success: true });
+    }
+    catch (error) {
+        res.status(500).json({ error: error.message || 'Failed to ingest quality score' });
+    }
+    finally {
+        if (dbService)
+            await dbService.close();
+    }
+});
+/**
+ * GET /api/analytics/quality/scorecard/:userId
+ * Returns quality scorecard: one summary per founder journey stage.
+ * Used by the quality tile grid in both personal and manager views.
+ */
+router.get('/quality/scorecard/:userId', async (req, res) => {
+    let dbService;
+    try {
+        const apiKeyData = req.apiKeyData;
+        if (!apiKeyData)
+            return res.status(401).json({ error: 'Authentication required' });
+        const { userId } = req.params;
+        const { repoIdentifier } = req.query;
+        const timeframe = resolveAnalyticsTimeframe(req.query);
+        const periodDays = timeframe.startDate ? undefined : parsePeriodDays(timeframe.period);
+        dbService = new db_service_js_1.FraimDbService();
+        await dbService.connect();
+        // If requesting another user's data, verify manager-member relationship
+        if (apiKeyData.userId !== userId) {
+            await resolveManagerMember(dbService, apiKeyData.userId, userId);
+        }
+        const stages = await dbService.getQualityScorecard(userId, repoIdentifier, periodDays, timeframe.startDate, timeframe.endDate);
+        res.json({ stages });
+    }
+    catch (error) {
+        res.status(error.status || 500).json({ error: error.message || 'Failed to load quality scorecard' });
+    }
+    finally {
+        if (dbService)
+            await dbService.close();
+    }
+});
+/**
+ * GET /api/analytics/quality/stage/:userId/:stageCategory
+ * Returns full assessment history for a single stage (tile click detail view).
+ */
+router.get('/quality/stage/:userId/:stageCategory', async (req, res) => {
+    let dbService;
+    try {
+        const apiKeyData = req.apiKeyData;
+        if (!apiKeyData)
+            return res.status(401).json({ error: 'Authentication required' });
+        const { userId, stageCategory } = req.params;
+        const { repoIdentifier } = req.query;
+        const timeframe = resolveAnalyticsTimeframe(req.query);
+        const periodDays = timeframe.startDate ? undefined : parsePeriodDays(timeframe.period);
+        dbService = new db_service_js_1.FraimDbService();
+        await dbService.connect();
+        // If requesting another user's data, verify manager-member relationship
+        if (apiKeyData.userId !== userId) {
+            await resolveManagerMember(dbService, apiKeyData.userId, userId);
+        }
+        const detail = await dbService.getQualityStageDetail(userId, stageCategory, repoIdentifier, periodDays, timeframe.startDate, timeframe.endDate);
+        res.json(detail);
+    }
+    catch (error) {
+        res.status(error.status || 500).json({ error: error.message || 'Failed to load stage detail' });
+    }
+    finally {
+        if (dbService)
+            await dbService.close();
+    }
+});
+/**
+ * GET /analytics/
+ * Serve the analytics dashboard HTML
+ */
+router.get('/', (req, res) => {
+    const dashboardPath = path_1.default.join(__dirname, '../../public/analytics/index.html');
+    res.sendFile(dashboardPath);
+});
+exports.default = router;