docs(design): add OKF user story catalog

design/us-010-audit-events.md

@@ -0,0 +1,39 @@
+---
+type: User Story
+title: Preserve a CloudEvents-style audit trail
+description: Authentication, UI, account, Discord, network, and game actions create searchable immutable-style events.
+tags: [audit, cloudevents, security, events]
+timestamp: 2026-08-01T18:43:58Z
+story_id: US-010
+status: verified
+---
+
+# User Story
+
+As an operator, I want security and identity activity recorded consistently, so that incidents and account changes can be reconstructed and later published to Kafka.
+
+# Acceptance Criteria
+
+- [x] Events preserve CloudEvents-style ID, specification version, source, type, subject, time, content type, and JSON data.
+- [x] Events can include user actor, IP address, and correlation ID.
+- [x] Portal access, magic-link creation and consumption, account changes, nickname changes, VPN blocks, and game decisions are recorded.
+- [x] Username changes learned from Velocity create their own event.
+- [x] Administrative actions include the acting SSO identity in event data.
+- [x] Events can be inspected globally and from an individual admin user view.
+- [x] `published_at` reserves an outbox path for future Kafka publishing.
+
+# Implementation
+
+- [`packages/database/src/events.ts`](../packages/database/src/events.ts)
+- [`packages/database/src/schema.ts`](../packages/database/src/schema.ts)
+- [`apps/web/src/lib/audit.ts`](../apps/web/src/lib/audit.ts)
+- [`apps/web/src/app/admin/(console)/events/page.tsx`](../apps/web/src/app/admin/%28console%29/events/page.tsx)
+
+# Validation
+
+The shared CloudEvent contract is covered by [`packages/contracts/test/contracts.test.ts`](../packages/contracts/test/contracts.test.ts), and event-producing routes pass full type and production-build validation.
+
+# Related Stories
+
+- [Enrich login IPs](us-007-ip-intelligence.md)
+- [Administer users](us-013-admin-user-management.md)