# OSHUN V1 Nisaba Adoption and Cross-Domain Attachment Dashboards

Status: Canonical Date: 2026-04-26 Owners: OSHUN Nisaba Product, OSHUN
Cross-Domain, OSHUN Product Analytics Tracks: `V1-OBS-007` from
`OSHUN_V1_TODOS.md` Spec source: `libs/oshun/analytics/src/dashboards-nisaba.ts`

This document is the canonical, human-readable companion to the machine-readable
V1 Nisaba dashboard manifest in `@oshun/analytics`.

The machine-readable manifest is the single source of truth.

---

## 1. Scope

This manifest defines the two V1 Nisaba dashboards mandated by V1-OBS-007:

- `oshun-v1-nisaba-adoption` — Nisaba customer adoption: launches, study
  actions, inspector opens, expert-mode adoption, note-savers, passage opens,
  and a D7/D30 cohort grid.
- `oshun-v1-nisaba-cross-domain-attachment` — how Nisaba attaches to Tara and
  the companion domains: bidirectional cross-domain recommendations,
  Nisaba-filtered universal search, activity reentry into Nisaba, and the Nisaba
  share of home continuation impressions and clicks.

Pairs with:

- the customer taxonomy (`customer-taxonomy.ts`, V1-OBS-001) — the source of
  every event a metric reads from
- the customer KPI dashboard manifest (`dashboards-customer-kpi.ts`, V1-OBS-006)
  — the shared metric/panel/visualization shape

Out-of-scope:

- assistant quality / disclosure dashboards (V1-OBS-008)

---

## 2. Manifest shape

Nisaba dashboards reuse the metric/panel shape from
`dashboards-customer-kpi.ts`. The dashboard identifier and owner enums are
extended to cover the Nisaba surface:

- `id`: `oshun-v1-nisaba-adoption` | `oshun-v1-nisaba-cross-domain-attachment`
- `owner`: `nisaba_product` | `cross_domain` | `product_analytics`

---

## 3. Adoption dashboard

Metrics:

- `nisaba_adoption.domain_launched` — count of `oshun.domain.launched` filtered
  to `domain=nisaba`
- `nisaba_adoption.unique_users` — unique users who launched Nisaba
- `nisaba_adoption.study_action_count` — `nisaba.study.action_triggered` by
  `action`
- `nisaba_adoption.inspector_opens_by_pane` — `nisaba.inspector.opened` by
  `inspector`
- `nisaba_adoption.expert_mode_enabled_share` — `nisaba.expert_mode.toggled`
  filtered to `enabled=true`
- `nisaba_adoption.note_saved_unique_users` — unique users who saved a note via
  `nisaba.note.saved`
- `nisaba_adoption.passage_opens_by_origin` — `nisaba.passage.opened` by
  `origin` surface
- `nisaba_adoption.cohort_d7_d30_resume` — D7/D30 cohort retention for Nisaba
  launchers, anchored on `oshun.domain.launched` filtered to `domain=nisaba`

Panels: launches, unique users, study actions, inspector opens, expert-mode
adoption, note-savers, passage opens, cohort grid.

---

## 4. Cross-domain attachment dashboard

Metrics:

- `nisaba_attachment.recommendations_into_nisaba` —
  `oshun.recommendation.impressed` filtered to `target_domain=nisaba`, grouped
  by `source_domain`
- `nisaba_attachment.recommendations_from_nisaba` — same event filtered to
  `source_domain=nisaba`, grouped by `target_domain`
- `nisaba_attachment.recommendation_tap_rate_into_nisaba` — conversion ratio of
  `oshun.recommendation.tapped / oshun.recommendation.impressed` filtered to
  `target_domain=nisaba`
- `nisaba_attachment.search_with_nisaba_filter` — `oshun.search.executed`
  filtered to `domain_filter=nisaba`
- `nisaba_attachment.activity_reentry_into_nisaba` —
  `oshun.activity.reentry_opened` filtered to `primary_domain=nisaba`, grouped
  by `trigger`
- `nisaba_attachment.home_continuation_nisaba_share` — share of
  `oshun.home_continuation.impressed` emissions where `surface=nisaba`
- `nisaba_attachment.home_continuation_click_rate_nisaba` — conversion of
  `oshun.home_continuation.clicked / oshun.home_continuation.impressed` for
  `surface=nisaba`

Panels: recommendations into Nisaba, recommendations from Nisaba, recommendation
tap-rate into Nisaba, Nisaba-filtered search, activity reentries, home
continuation share, home continuation click-rate.

---

## 5. KPI parity and integrity

Tests in `dashboards-nisaba.test.ts` enforce:

- the four-dashboard manifest is published (two Nisaba dashboards in V1)
- every metric event reference resolves to the customer taxonomy
- every panel references only same-dashboard metrics
- every Nisaba-scoped string filter targets the literal `"nisaba"` value
- the adoption dashboard exercises every Nisaba-namespace event in the customer
  taxonomy (`nisaba.study.action_triggered`, `nisaba.inspector.opened`,
  `nisaba.expert_mode.toggled`, `nisaba.note.saved`, `nisaba.passage.opened`)
- the cross-domain dashboard tracks attachment in both directions

---

## 6. Governance

### 6.1 Amendments

Adding or changing a Nisaba dashboard, metric, or panel requires:

1. updating `dashboards-nisaba.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

### 6.2 Versioning

Same rules as the customer KPI dashboard manifest.

---

## 7. Out-of-scope

- assistant quality / disclosure dashboards (V1-OBS-008)

---

## 8. Change log

- 2026-04-26 — Initial canonical V1 Nisaba dashboard manifest published
  alongside `libs/oshun/analytics/src/dashboards-nisaba.ts` (V1-OBS-007).
