feat(openapi): add public tRPC API docs

[evanjacobson]

Summary

Usage analytics did not have a reviewer-friendly public OpenAPI surface, which made the available tRPC endpoints and their intended roles harder to understand from generated docs.

This adds an allowlisted Swagger/OpenAPI docs surface for the usage analytics tRPC endpoints, including shared schemas, bearer auth metadata, static Swagger UI assets, and clearer endpoint descriptions that distinguish summary cards, trends, breakdown charts, and detailed table/export usage. The implementation follows the existing explicit registry/schema pattern so only intentionally documented procedures are exposed.

Lower-level notes

• Serves the OpenAPI JSON at /api/openapi.json and Swagger UI at /api/docs.
• Copies pinned Swagger UI assets into ignored generated public assets during web dev/build/prepare flows.
• Keeps usage analytics Zod schemas reusable between the router and OpenAPI document generation.

Verification

• Not manually tested in a browser; this branch only changes generated API documentation and Swagger docs plumbing.

Visual Changes

N/A

Reviewer Notes

Focus areas: the allowlist boundary for documented tRPC procedures, CSP/static asset handling for Swagger UI, and whether the endpoint role descriptions are clear enough for API consumers.

[kilo-code-bot]

Code Review Summary

Status: 1 Issue Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	1
SUGGESTION	0

Issue Details (click to expand)

WARNING

File	Line	Issue
apps/web/src/lib/openapi/trpc-registry.ts	66	Public OpenAPI schema exposes invitation tokens and invite URLs for pending organization invites.

Files Reviewed (14 files)

• .gitignore - 0 issues
• apps/web/next.config.mjs - 0 issues
• apps/web/package.json - 0 issues
• apps/web/scripts/copy-swagger-ui-assets.mjs - 0 issues
• apps/web/src/app/api/docs/route.ts - 0 issues
• apps/web/src/app/api/openapi.json/route.ts - 0 issues
• apps/web/src/lib/openapi/trpc-openapi.test.ts - 0 issues
• apps/web/src/lib/openapi/trpc-openapi.ts - 0 issues
• apps/web/src/lib/openapi/trpc-registry.ts - 1 issue
• apps/web/src/lib/organizations/organization-types.ts - 0 issues
• apps/web/src/routers/usage-analytics-router.ts - 0 issues
• apps/web/src/routers/usage-analytics-schemas.ts - 0 issues
• pnpm-workspace.yaml - 0 issues
• scripts/prepare.sh - 0 issues

Fix these issues in Kilo Cloud

Previous Review Summary (commit eb6be61)

Current summary above is authoritative. Previous snapshots are kept for context only.

Previous review (commit eb6be61)

Status: No Issues Found | Recommendation: Merge

Files Reviewed (13 files)

• .gitignore
• apps/web/next.config.mjs
• apps/web/package.json
• apps/web/scripts/copy-swagger-ui-assets.mjs
• apps/web/src/app/api/docs/route.ts
• apps/web/src/app/api/openapi.json/route.ts
• apps/web/src/lib/openapi/trpc-openapi.test.ts
• apps/web/src/lib/openapi/trpc-openapi.ts
• apps/web/src/lib/openapi/trpc-registry.ts
• apps/web/src/routers/usage-analytics-router.ts
• apps/web/src/routers/usage-analytics-schemas.ts
• pnpm-workspace.yaml
• scripts/prepare.sh

---

_{Reviewed by gpt-5.4-20260305 · Input: 83.5K · Output: 10.9K · Cached: 737.3K}

_{Review guidance: REVIEW.md from base branch main}