feat(openspec): propose phase-6-market-expansion change

Analytics Dashboard, API Gateway Tiers, AGNTCY Compliance — 62 tasks across 8 groups.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

openspec/changes/phase-6-market-expansion/specs/analytics-dashboard/spec.md

@@ -0,0 +1,67 @@
+## ADDED Requirements
+
+### Requirement: Analytics events are recorded for token issuances and agent activity
+The system SHALL record an analytics event row in `analytics_events` for every OAuth2 token issuance and every agent registration, update, and deactivation, scoped to the tenant. Each row SHALL contain: `tenant_id`, `date` (UTC date), `metric_type` (e.g., `token_issued`, `agent_registered`), and `count` (aggregated daily).
+
+#### Scenario: Token issuance recorded in analytics
+- **WHEN** `POST /oauth2/token` succeeds for a tenant
+- **THEN** the `analytics_events` table SHALL have a row incremented for `metric_type=token_issued` for that tenant on today's UTC date
+
+#### Scenario: Agent registration recorded in analytics
+- **WHEN** `POST /api/agents` succeeds
+- **THEN** the `analytics_events` table SHALL have a row incremented for `metric_type=agent_registered` for the owning tenant on today's UTC date
+
+#### Scenario: Analytics recording does not block the primary response
+- **WHEN** the analytics write fails (e.g., DB timeout)
+- **THEN** the primary API response SHALL still succeed and the error SHALL be logged
+
+### Requirement: Tenant can retrieve token issuance trend data
+The system SHALL expose `GET /api/analytics/tokens` returning daily token issuance counts for the authenticated tenant over a configurable date range (default: last 30 days, max: 90 days). Response SHALL include an array of `{ date, count }` objects sorted ascending by date.
+
+#### Scenario: Successful token trend retrieval
+- **WHEN** an authenticated tenant admin calls `GET /api/analytics/tokens?days=30`
+- **THEN** the response SHALL be HTTP 200 with a JSON array of up to 30 `{ date, count }` objects
+
+#### Scenario: Date range exceeding maximum is rejected
+- **WHEN** the request specifies `days` greater than 90
+- **THEN** the response SHALL be HTTP 400 with an error indicating the maximum is 90 days
+
+#### Scenario: Tenant sees only their own data
+- **WHEN** tenant A retrieves analytics
+- **THEN** the response SHALL contain only rows where `tenant_id` matches tenant A — no cross-tenant data leakage
+
+### Requirement: Tenant can retrieve agent activity heatmap data
+The system SHALL expose `GET /api/analytics/agents/activity` returning per-agent event counts grouped by day-of-week and hour-of-day for the authenticated tenant (last 30 days). Response SHALL include an array of `{ agent_id, dow, hour, count }` objects suitable for rendering a heatmap.
+
+#### Scenario: Successful activity heatmap retrieval
+- **WHEN** an authenticated tenant admin calls `GET /api/analytics/agents/activity`
+- **THEN** the response SHALL be HTTP 200 with a JSON array of activity buckets
+
+#### Scenario: Tenant with no agents returns empty array
+- **WHEN** the tenant has no registered agents
+- **THEN** the response SHALL be HTTP 200 with an empty array
+
+### Requirement: Tenant can retrieve a per-agent usage summary
+The system SHALL expose `GET /api/analytics/agents` returning a list of agents with their total token issuances for the current billing period (current calendar month). Response SHALL include `{ agent_id, name, token_count }` sorted descending by `token_count`.
+
+#### Scenario: Successful per-agent summary
+- **WHEN** an authenticated tenant admin calls `GET /api/analytics/agents`
+- **THEN** the response SHALL be HTTP 200 with a sorted list of agent usage summaries
+
+#### Scenario: Analytics endpoint requires authentication
+- **WHEN** a request to any `/api/analytics/*` endpoint is made without a valid JWT
+- **THEN** the response SHALL be HTTP 401
+
+### Requirement: Analytics data is accessible via the developer portal
+The portal SHALL include an Analytics page at `/analytics` with:
+- A line chart showing token issuance trend (last 30 days) rendered with `recharts`
+- A heatmap chart showing agent activity by day/hour rendered with `recharts`
+- A table listing per-agent usage for the current month
+
+#### Scenario: Analytics page loads token trend chart
+- **WHEN** a tenant admin navigates to `/analytics` in the portal
+- **THEN** the page SHALL render a line chart with token issuance data from `GET /api/analytics/tokens`
+
+#### Scenario: Analytics page is code-split (lazy loaded)
+- **WHEN** the portal bundle is built
+- **THEN** `recharts` and analytics page components SHALL be in a separate chunk (via `next/dynamic`) and NOT included in the main bundle