# OSHUN V1 Customer KPI Dashboards

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).
