chore: Audit PostHog events and build principal/identity analytics dashboard

[manojbajaj95]

Summary

Review and improve PostHog telemetry for the Authsome library/daemon so registered principals and identities are reliably tracked, then create an equivalent analytics dashboard in PostHog.

Current state

Client: src/authsome/server/analytics.py

• Initialized in src/authsome/server/app.py lifespan when settings.analytics_enabled is true.
• Enabled when: AUTHSOME_ENV=prod + AUTHSOME_POSTHOG_API_KEY set + AUTHSOME_DO_NOT_TRACK is false.
• Compose defaults AUTHSOME_DO_NOT_TRACK=1 — telemetry off in Docker quick start.

Events captured today (grep capture_event):

Event	Source	distinct_id
account_registered	routes/ui.py	session email
account_logged_in	routes/ui.py	session email
account_logged_out	routes/ui.py	session email
identity_claimed	routes/ui.py	pending identity handle
identity registered	routes/identities.py	identity handle
auth session completed / auth session failed	routes/auth.py	session identity or principal_id
provider registered / provider deleted / provider configuration updated	routes/providers.py	identity handle
connection logout / connection revoked / connection made global / global connection removed / credentials exported	routes/connections.py	identity or principal
credentials resolved	routes/proxy.py	identity handle

Gaps

• No explicit "principal registered" lifecycle event beyond account_registered (email-based distinct_id).
• Identity registration fires identity registered but properties may not include stable principal linkage in all paths.
• distinct_id inconsistency: mix of email, identity handle, and fallback "account-ui" — hard to build unified principal/identity funnels.
• No PostHog dashboard documented or checked into the repo for monitoring adoption (registered principals, claimed identities, active connections).
• Library/CLI usage (proxy runs, credential resolves) may be under-represented vs UI events.

Proposed work

• Inventory all capture_event call sites; normalize event names (snake_case vs spaces inconsistency today).
• Ensure every principal registration and identity claim emits events with principal_id, identity_handle, and did where available.
• Standardize distinct_id strategy (e.g. principal_id for account events, handle for agent events) and use PostHog identify properties for cross-linking.
• Add missing events if registry writes happen without telemetry (e.g. principal creation, claim rejection).
• Build a PostHog dashboard: registered principals over time, identities registered/claimed, auth session success rate, top providers connected.
• Document opt-in telemetry setup in self-hosting guide (AUTHSOME_POSTHOG_API_KEY, AUTHSOME_DO_NOT_TRACK=0).

Relevant files

• src/authsome/server/analytics.py
• src/authsome/server/config.py — analytics_enabled, posthog_api_key, posthog_host
• src/authsome/server/routes/ui.py, identities.py, auth.py, connections.py, providers.py, proxy.py
• docs/guides/self-hosting.md

Acceptance criteria

• Principal and identity registration/claim events are queryable in PostHog with stable properties.
• A PostHog dashboard exists (link or export config in repo/docs).
• Event naming and distinct_id conventions are documented.
• No PII beyond what is necessary (email as distinct_id — evaluate privacy implications).