Eve library

OSHUN V1 Customer KPI Dashboards

Guide

Revision 1

On this page

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 KPIs
  • oshun-v1-retention — D1/D7/D14/D30 cohort retention plus engagement and re-engagement signals
  • oshun-v1-cross-domain-usage — domain launches, recommendation funnel, multi-domain customer share, universal search by domain filter
  • oshun-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_NAMES from 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 identifier
  • title, description, owner
  • metrics — typed metric definitions with kind, eventNames, valueProperty, groupBy, filters, funnelSteps, cohortStartEvent, retentionOffsetsDays
  • panels — typed panel definitions with visualization, 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.opened unique users
  • activation.auth_completion_rate — oshun.auth.completed over oshun.app.opened
  • activation.profile_initialized_count — oshun.profile.initialized
  • activation.first_value_action_rate — D7 cohort over oshun.value_action.completed, anchored to the first oshun.app.opened event (matches ADR-0006 §"Activation Definition")
  • activation.onboarding_funnel — started → step_completed → completed
  • activation.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.opened cohort grid, offsets [1, 7, 14, 30] days
  • retention.session_duration_p50_p90 — percentiles over oshun.app.backgrounded.session_ms
  • retention.sessions_per_active_user — oshun.app.opened per user
  • retention.churn_signal_signed_out_reasons — oshun.auth.signed_out by reason
  • retention.app_resumed_lag — percentiles over oshun.app.resumed.background_ms
  • retention.item_saved_unique_users — oshun.item.saved unique users
  • retention.notification_opened_unique_users — oshun.notification.opened unique 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.launched by domain
  • cross_domain.launch_success_rate — oshun.domain.launched filtered to success=true
  • cross_domain.launch_latency_p50_p90 — percentiles over oshun.domain.launched.latency_ms
  • cross_domain.recommendation_impression_to_tap — oshun.recommendation.tapped / oshun.recommendation.impressed
  • cross_domain.recommendation_feedback_distribution — oshun.recommendation.feedback by signal
  • cross_domain.cross_domain_set_partial_failure_rate — oshun.cross_domain_recommendations.served filtered to partial_failure=true
  • cross_domain.multi_domain_user_share — share of users who launched ≥ 2 distinct domains
  • cross_domain.search_executed_by_domain_filter — oshun.search.executed by domain_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.impressed
  • continuity.home_continuation_state_distribution — oshun.home_continuation.impressed by state
  • continuity.activity_reentry_count — oshun.activity.reentry_opened by trigger
  • continuity.activity_reentry_cross_domain_rate — oshun.activity.reentry_opened filtered to is_cross_domain=true
  • continuity.item_resumed_count — oshun.item.resumed by domain
  • continuity.item_resume_gap_p50_p90 — percentiles over oshun.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:

  1. updating dashboards-customer-kpi.ts
  2. updating tests (lock-style tests fail closed if metrics drift away from the customer taxonomy)
  3. updating this document if the change is structurally significant
  4. signoff from the listed owner plus 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).