Status: Canonical Date: 2026-04-26 Owners: OSHUN Product Analytics, OSHUN
Growth, OSHUN Retention, OSHUN Cross-Domain, OSHUN Continuity Tracks:
V1-OBS-006 from OSHUN_V1_TODOS.md Spec source:
libs/oshun/analytics/src/dashboards-customer-kpi.ts
This document is the canonical, human-readable companion to the machine-readable
V1 customer KPI dashboard manifest in @oshun/analytics.
The machine-readable manifest is the single source of truth. Dashboards in Grafana / Looker / Metabase / internal admin BFF surfaces should be compiled from the manifest rather than maintained by hand.
1. Scope#
This manifest defines the four V1 customer KPI dashboards mandated by V1-OBS-006:
oshun-v1-activation— activation funnel and ADR-0006 KPIsoshun-v1-retention— D1/D7/D14/D30 cohort retention plus engagement and re-engagement signalsoshun-v1-cross-domain-usage— domain launches, recommendation funnel, multi-domain customer share, universal search by domain filteroshun-v1-continuity— home continuation, activity reentry, item resume
Pairs with:
- the customer taxonomy (
customer-taxonomy.ts, V1-OBS-001) — the source of every event a metric reads from - the canonical KPI event list
OSHUN_V1_CANONICAL_KPI_EVENT_NAMESfrom ADR-0006
Out-of-scope:
- Nisaba adoption / cross-domain attachment dashboards (V1-OBS-007)
- Assistant quality / disclosure dashboards (V1-OBS-008)
2. Manifest shape#
Each dashboard exposes:
id— stable dashboard identifiertitle,description,ownermetrics— typed metric definitions withkind,eventNames,valueProperty,groupBy,filters,funnelSteps,cohortStartEvent,retentionOffsetsDayspanels— typed panel definitions withvisualization,metricIds,defaultRangeDays,granularity
Allowed metric kinds: count, unique_users, rate, funnel_step_completion,
percentile, cohort_retention, segment_share.
Allowed panel visualizations: time_series, bar, stacked_bar, funnel,
cohort_grid, big_number, pie, distribution.
Allowed panel granularities: hour, day, week, month.
3. Activation dashboard#
Tracks new-user activation per ADR-0006. Metrics:
activation.app_opened_unique_users—oshun.app.openedunique usersactivation.auth_completion_rate—oshun.auth.completedoveroshun.app.openedactivation.profile_initialized_count—oshun.profile.initializedactivation.first_value_action_rate— D7 cohort overoshun.value_action.completed, anchored to the firstoshun.app.openedevent (matches ADR-0006 §"Activation Definition")activation.onboarding_funnel—started → step_completed → completedactivation.onboarding_abandonment_by_step
Panels: unique users, auth completion, D7 activation cohort grid, onboarding funnel, abandonment by step, profile initialized.
4. Retention dashboard#
Tracks cohort retention per ADR-0006 §"Retention Definition" plus engagement and re-engagement KPIs. Metrics:
retention.cohort_d1_d7_d14_d30—oshun.app.openedcohort grid, offsets[1, 7, 14, 30]daysretention.session_duration_p50_p90— percentiles overoshun.app.backgrounded.session_msretention.sessions_per_active_user—oshun.app.openedper userretention.churn_signal_signed_out_reasons—oshun.auth.signed_outbyreasonretention.app_resumed_lag— percentiles overoshun.app.resumed.background_msretention.item_saved_unique_users—oshun.item.savedunique usersretention.notification_opened_unique_users—oshun.notification.openedunique users
Panels: cohort grid, session duration, sessions per user, sign-out reasons, resume lag, item saves, notifications opened.
5. Cross-domain usage dashboard#
Tracks how customers move between Tara and the companion domains. Metrics:
cross_domain.launches_by_domain—oshun.domain.launchedbydomaincross_domain.launch_success_rate—oshun.domain.launchedfiltered tosuccess=truecross_domain.launch_latency_p50_p90— percentiles overoshun.domain.launched.latency_mscross_domain.recommendation_impression_to_tap—oshun.recommendation.tapped / oshun.recommendation.impressedcross_domain.recommendation_feedback_distribution—oshun.recommendation.feedbackbysignalcross_domain.cross_domain_set_partial_failure_rate—oshun.cross_domain_recommendations.servedfiltered topartial_failure=truecross_domain.multi_domain_user_share— share of users who launched ≥ 2 distinct domainscross_domain.search_executed_by_domain_filter—oshun.search.executedbydomain_filter
Panels: launches by domain, launch success rate, launch latency, recommendation funnel, recommendation feedback, cross-domain set partial failure, multi-domain user share, search by domain filter.
6. Continuity dashboard#
Tracks the cross-session continuity signals that prove customers experience continuous progress. Metrics:
continuity.home_continuation_impression_to_click—oshun.home_continuation.clicked / oshun.home_continuation.impressedcontinuity.home_continuation_state_distribution—oshun.home_continuation.impressedbystatecontinuity.activity_reentry_count—oshun.activity.reentry_openedbytriggercontinuity.activity_reentry_cross_domain_rate—oshun.activity.reentry_openedfiltered tois_cross_domain=truecontinuity.item_resumed_count—oshun.item.resumedbydomaincontinuity.item_resume_gap_p50_p90— percentiles overoshun.item.resumed.gap_seconds
Panels: home continuation funnel, state mix, reentries by trigger, cross-domain reentry rate, item resumes by domain, time-to-resume distribution.
7. KPI parity#
Every event listed in OSHUN_V1_CANONICAL_KPI_EVENT_NAMES (oshun.app.opened,
oshun.auth.completed, oshun.profile.initialized, oshun.domain.launched,
oshun.value_action.completed, oshun.item.saved, oshun.item.resumed,
oshun.search.executed, oshun.notification.opened) is referenced by at least
one dashboard metric. A test in dashboards-customer-kpi.test.ts enforces this
invariant.
8. Governance#
8.1 Amendments#
Adding or changing a dashboard, metric, or panel requires:
- updating
dashboards-customer-kpi.ts - updating tests (lock-style tests fail closed if metrics drift away from the customer taxonomy)
- updating this document if the change is structurally significant
- signoff from the listed
ownerplus platform analytics
8.2 Versioning#
Same rules as the sibling taxonomies. The manifest publishes unversioned identifiers on the assumption that downstream platforms own their own versioning of compiled dashboards.
9. Out-of-scope#
This manifest does not implement an actual rendering pipeline; downstream analytics platforms compile the manifest into concrete dashboards. Activation/retention/cross-domain/continuity dashboards are the only V1 mandate; Nisaba adoption (V1-OBS-007) and assistant quality (V1-OBS-008) will register their own manifests against the same shape.
10. Change log#
- 2026-04-26 — Initial canonical V1 customer KPI dashboard manifest published
alongside
libs/oshun/analytics/src/dashboards-customer-kpi.ts(V1-OBS-006).