# OSHUN Product Brief

Status: Draft v1.0 Owner: OSHUN Product + OSHUN Engineering Last Updated: March
22, 2026 Related: `OSHUN_APP_TODOS.md`, `ARCHITECTURE.md`,
`docs/reference/data-ownership-matrix.md` (legacy pre-V1 cross-domain snapshot),
`docs/releases/v1/specs/program-charter.md`,
`docs/releases/v1/specs/web-app-admin-v1-prd.md`

Note: this brief captures the earlier MVP-era shell framing. For canonical OSHUN
V1 end-state governance and product framing, use
`docs/releases/v1/specs/program-charter.md` and
`docs/releases/v1/specs/web-app-admin-v1-prd.md`. The legacy
`docs/reference/data-ownership-matrix.md` remains historical context only and
must not be used to override the V1 ownership model.

## 1. Executive Summary

OSHUN is a unified cross-platform product that, in its original MVP framing,
gave users one elegant entry point into four distinct domains:

- Tara (meditation and mindfulness)
- Veritas (verified intelligence and fact-checking)
- Nyx (astronomy and cosmic exploration)
- Arete (personal development and life mastery)

The product will ship as:

- A React Native mobile app for iOS and Android (`apps/oshun/mobile`)
- A companion website (`apps/oshun/web`)
- An installable Progressive Web App (PWA) experience for core user journeys

The core user promise is simple: one account, one shell, one consistent UX, with
domain-specific depth available in 1-2 interactions.

## 2. Problem Statement

Current domain capabilities are strong but fragmented across separate
applications and implementation styles. Users who would benefit from combining
meditation, verification, astronomy, and life mastery experiences must move
between disconnected interfaces, sessions, and personalization systems.

Fragmentation currently causes:

- Cross-domain friction and navigation overhead
- Duplicate onboarding and preferences setup
- Weak continuity of user intent (no unified "continue where I left off")
- Inconsistent interaction models and visual language
- Reduced retention from context switching

OSHUN addresses this by introducing a single shell product with shared identity,
navigation, recommendations, settings, and design system.

## 3. Product Vision

Build the most beautiful and ergonomic personal intelligence super-app in the
ecosystem, where users can:

- Calm the mind (Tara)
- Verify reality (Veritas)
- Expand perspective (Nyx)
- Improve daily practice (Arete)

without changing apps, accounts, or mental models.

## 4. Goals and Non-Goals

### 4.1 Product Goals (MVP)

- Launch one OSHUN mobile shell that exposes the original Tara, Veritas, Nyx,
  and Arete MVP surface.
- Launch one associated OSHUN web experience with PWA install support.
- Deliver shared auth, navigation, notifications, and saved items across
  domains.
- Deliver a premium UI/UX baseline with clear ergonomic standards.
- Ship measurable retention and cross-domain adoption improvements.

### 4.2 Non-Goals (MVP)

- Rebuild all underlying domain apps from scratch.
- Enforce full feature parity of each standalone domain inside OSHUN at launch.
- Replace domain ownership boundaries for data and business logic.
- Deliver desktop-native applications in MVP.

## 5. Current-State Analysis (Repository-Backed)

The brief is intentionally grounded in existing implementation reality.

### 5.1 Existing Assets

- Tara mobile exists as Expo/React Native app (`apps/tara/mobile`).
- Veritas mobile exists as Expo/React Native app (`apps/veritas/mobile`).
- Nyx mobile currently exists as Vite + PWA app (`apps/nyx/mobile`).
- Arete exists primarily as domain libraries (`libs/arete/*`), no full app
  shell.
- Tara and Veritas already have web applications (`apps/tara/web`,
  `apps/veritas/web`).

### 5.2 Product Implications

- OSHUN can accelerate delivery by reusing Tara/Veritas mobile patterns.
- Nyx requires an explicit integration mode decision (embed-first vs
  native-first).
- Arete requires product surface composition from existing libraries and models.
- A shell + adapter architecture is the lowest-risk path to first release.

## 6. Target Users and JTBD

### 6.1 Primary Personas

- Growth Seeker: wants daily guided improvement with minimal friction.
- Informed Citizen: wants fast access to verified context and evidence.
- Reflective Explorer: wants ritual + curiosity (mindfulness + astronomy).
- Structured Achiever: wants habits, goals, and journaling with accountability.

### 6.2 Core Jobs To Be Done

- "Help me open one app and start a useful session in under 30 seconds."
- "Help me move from discovery to action without navigation fatigue."
- "Help me carry context and progress across experiences and devices."
- "Help me trust what I see through transparent quality signals."

## 7. User Experience Principles

1. One-handed by default: key actions within thumb reach on mobile.
2. Two taps to value: core domain entry <= 2 taps from home.
3. Calm visual hierarchy: reduce clutter; emphasize next-best action.
4. Progressive depth: show essentials first; advanced controls on demand.
5. Trust and explainability: confidence and source signals are explicit.
6. Resilient by design: network failures degrade gracefully with useful
   fallback.
7. Accessibility as baseline: never a post-release add-on.

## 8. MVP Product Scope

### 8.1 Shared Shell Features (All Platforms)

- Unified account/session management
- Personalized home dashboard
- Domain switcher for the initial Tara, Veritas, Nyx, and Arete MVP shell
- Universal search across domains
- Unified save/bookmark system
- Unified activity timeline
- Notification center + per-domain notification controls
- Profile, privacy, accessibility, and preference settings

### 8.2 Domain Entry Features (MVP)

- Tara: launch, resume, and save core meditation content
- Veritas: open trending verified stories, claims, and save/follow
- Nyx: access nightly highlights and sky exploration entry points
- Arete: goals/habits/journal/coach summary surfaces from `libs/arete/*`

### 8.3 Out-of-Scope For Initial MVP

- Full standalone-domain feature parity in shell
- Advanced social/community systems across all domains
- Deep wearable integrations
- Long-tail localization breadth beyond launch set

## 9. Platform Scope

### 9.1 Mobile (Primary Surface)

- React Native + Expo Router architecture
- iOS and Android parity for core shell flows
- Native-feeling transitions, haptics, and gesture ergonomics
- Offline-aware behavior for key views

### 9.2 Website + PWA

- OSHUN website for onboarding, marketing, and authenticated dashboard
- Installable PWA with offline shell and update strategy
- Responsive behavior from small mobile web to desktop

## 10. Functional Requirements

### 10.1 Onboarding and Authentication

- Shared sign-in/up and session persistence across domains
- Social/provider support aligned with platform auth strategy
- Fast relaunch with secure token refresh and re-auth handling

### 10.2 Navigation and IA

- Home, Explore, Activity, Profile top-level model
- Domain switching without context loss
- Deep link support (`oshun://...` + web equivalents)

### 10.3 Home Dashboard

- Personalized greeting and time-context
- Domain cards with continue-state
- Cross-domain quick actions
- Recommendations with basic explainability labels

### 10.4 Search and Discovery

- Unified search endpoint integration
- Domain filters and result blending
- Recent and suggested queries

### 10.5 Save, Activity, and Notifications

- Save any supported item type into one library
- Cross-domain activity timeline
- Unified notification inbox and preferences

### 10.6 Settings and Controls

- Theme, accessibility, language, and notification preferences
- Privacy and consent controls
- Account session/device management

## 11. Non-Functional Requirements

### 11.1 Performance

- Mobile cold start: target <= 2.5s on mid-tier devices
- Primary navigation transition: target <= 300ms perceived latency
- Home data hydration: target p95 <= 2.0s with graceful skeletons

### 11.2 Reliability

- Partial domain outages must not crash shell
- Shell must render with degraded but usable fallback states
- Core read surfaces available with intermittent connectivity

### 11.3 Accessibility

- Screen reader labeling coverage for all core controls
- Dynamic type and large text support on mobile
- Keyboard and focus-visible support on web/PWA
- WCAG AA color contrast minimum for production themes

### 11.4 Security and Privacy

- Secure token storage and refresh practices
- Least-privilege data access through BFF and domain adapters
- Clear consent and user control for telemetry preferences

## 12. Information Architecture

### 12.1 Top-Level Surfaces

- Home: context + recommendations + continue state
- Explore: curated and searchable cross-domain content
- Activity: timeline, streaks, and recent progress
- Profile: account, settings, and preferences

### 12.2 Domain Layer

- Each domain exposes a minimal contract to shell:
  - Launch metadata
  - Preview content model
  - Deep-link resolver
  - Save/unsave support
  - Availability and fallback state

## 13. Integration Strategy

### 13.1 Shell + Adapter Pattern

- OSHUN shell owns UX, navigation, and shared capabilities.
- Domain adapters translate domain-specific APIs/models to shell contracts.
- Domain teams retain ownership of core business logic and data.

### 13.2 Domain-Specific Approach

- Tara: adapter-first integration from existing mobile/web APIs.
- Veritas: adapter-first integration, emphasizing trust and evidence signals.
- Nyx: explicit phase decision between embedded PWA module and native module.
- Arete: build user-facing surfaces by composing existing `@arete/*` libraries.

## 14. Success Metrics

### 14.1 North-Star Metrics

- Cross-domain weekly active users (WAU using >= 2 domains)
- 7-day retention for new OSHUN users
- Median time-to-first-value from app open

### 14.2 Supporting Metrics

- Domain launch conversion from home cards
- Save rate and return rate on saved items
- Notification opt-in quality (opt-in with healthy engagement)
- Crash-free sessions and route failure rates
- PWA install conversion and 7-day usage

## 15. Launch Plan

### 15.1 Milestones

- Milestone A: Product + architecture decisions finalized
- Milestone B: Mobile shell and shared design system live
- Milestone C: Tara + Veritas + Nyx integrated
- Milestone D: Arete surfaces integrated from domain libs
- Milestone E: Website + PWA launch-ready
- Milestone F: Beta release and production hardening

### 15.2 Release Channels

- Mobile: internal QA -> closed beta -> staged store rollout
- Web/PWA: preview environments -> beta -> production

## 16. Risks and Mitigations

- Risk: inconsistent domain maturity causes uneven UX.
  - Mitigation: enforce shell contract and adapter standards per domain.
- Risk: Nyx integration path uncertainty delays delivery.
  - Mitigation: time-box decision and execute embed-first fallback if needed.
- Risk: Arete lacks existing app shell.
  - Mitigation: ship high-value Arete surfaces incrementally from existing libs.
- Risk: overloaded initial scope.
  - Mitigation: strict MVP gating and weekly scope reviews.

## 17. Open Decisions

- Final Nyx MVP mode: embedded module vs native module.
- Final launch locale set and localization depth.
- Final subscription/entitlement packaging for bundled access.
- Final recommendation ranking strategy for cross-domain home feed.

## 18. Acceptance Criteria For This Brief

This product brief is considered complete when:

- The scope is explicit for mobile, web, and PWA.
- Domain integration approach is clear and grounded in current code reality.
- UX principles and non-functional requirements are concrete and testable.
- Success metrics and rollout milestones are defined.
- Risks and unresolved decisions are documented for immediate follow-up.
