# OSHUN MVP Scope

Status: Draft v1.0 Owner: OSHUN Product + OSHUN Engineering Last Updated: March
22, 2026 Related: `docs/releases/v1/specs/product-brief.md`,
`OSHUN_APP_TODOS.md`, `docs/releases/v1/specs/program-charter.md`,
`docs/releases/v1/specs/web-app-admin-v1-prd.md`

Note: this document describes the earlier MVP boundary. It is not the canonical
source for OSHUN V1 end-state product shape. For the V1 governance model and
final product posture, use `docs/releases/v1/specs/program-charter.md` and
`docs/releases/v1/specs/web-app-admin-v1-prd.md`.

## 1. Purpose

This document defines the exact minimum viable product (MVP) scope for OSHUN. It
is the execution boundary for the first production release of:

- `apps/oshun/mobile` (React Native iOS + Android)
- `apps/oshun/web` (website + authenticated web app)
- Installable PWA capabilities for the web app

The MVP goal is not feature parity with all standalone domain applications. The
MVP goal is one high-quality OSHUN shell that reliably exposes the original
high-value Tara, Veritas, Nyx, and Arete MVP flows with excellent UX
fundamentals.

## 2. Scope Principles

1. Shell-first architecture over domain rewrites.
2. Two taps to domain value from OSHUN home.
3. Shared identity, navigation, search, save, activity, and notifications.
4. Strong quality floor: accessibility, reliability, and performance are release
   blockers.
5. Domain depth is intentionally constrained to top-value flows.

## 3. Current Implementation Constraints (Validated)

- Tara mobile is already Expo/React Native (`apps/tara/mobile`).
- Veritas mobile is already Expo/React Native (`apps/veritas/mobile`).
- Nyx mobile is currently Vite/PWA (`apps/nyx/mobile`).
- Arete exists as domain libraries (`libs/arete/*`) without a complete
  standalone app shell.

These constraints drive the MVP to adapter-based integration and staged depth.

## 4. MVP In-Scope

### 4.1 Shared OSHUN Shell (Required)

- Unified auth/session handling across domains
- Home dashboard with personalized domain entry cards
- Explore surface with blended cross-domain discovery
- Activity timeline with recent cross-domain interactions
- Profile/settings (theme, notifications, privacy, accessibility)
- Universal search across the original four-domain MVP shell
- Unified save/bookmark library
- Unified notifications center
- Deep links (mobile URI + web route equivalence)

### 4.2 Domain Scope (Required)

### Tara (MVP)

- Launch and resume meditation sessions from OSHUN shell
- Show key Tara recommendations and continue-state
- Save/unsave Tara items in unified library
- Handle unavailable content gracefully

### Veritas (MVP)

- Launch to trending verified stories from shell
- Open core claim/verification views
- Show trust signals (confidence, source context) in shell cards
- Save/unsave Veritas items in unified library

### Nyx (MVP)

- Provide nightly highlights and sky exploration entry points
- Integrate via one explicit mode:
  - embedded/linked PWA module, or
  - native baseline module
- Maintain continuity from OSHUN navigation and auth context where possible

### Arete (MVP)

- Surface daily check-in from existing `@arete/*` capabilities
- Include at least these user-facing modules:
  - goals summary
  - habits summary/streak
  - journal prompt/entry entrypoint
  - AI coach summary card
- Save/unsave Arete items where data model allows

### 4.3 Mobile (iOS + Android) Scope (Required)

- React Native + Expo shell app structure
- Four-tab IA: Home, Explore, Activity, Profile
- Domain switcher and quick actions
- Push notification registration and settings
- Offline-aware loading and retry states for core screens
- Basic crash reporting integration

### 4.4 Web + PWA Scope (Required)

- Public website pages (core value proposition + domain entry)
- Authenticated OSHUN dashboard mirroring shell model
- Installable PWA manifest + service worker
- Offline shell for key routes and cached assets
- Update flow for service worker refresh

### 4.5 API/BFF Scope (Required)

- OSHUN BFF service baseline with auth middleware
- Aggregation endpoints for:
  - home feed
  - continue/resume
  - domains metadata
  - activity timeline
  - unified search
  - notifications
- Partial-failure handling and response normalization

### 4.6 Quality and Observability Scope (Required)

- Analytics instrumentation for core funnels
- Error/crash monitoring for mobile and web
- Basic dashboards for latency and failure rates
- E2E smoke coverage for top user journeys

## 5. MVP Explicitly Out of Scope

- Full feature parity of Tara, Veritas, Nyx, or Arete standalone products
- Complete native Nyx rewrite if embed mode is chosen for MVP
- Complex social/leaderboard/community features across all domains
- Advanced monetization experiments beyond basic entitlement checks
- Desktop-native client applications
- Enterprise/B2B management surfaces

## 6. Platform Feature Matrix

| Capability                    | Mobile App            | Web                    | PWA      |
| ----------------------------- | --------------------- | ---------------------- | -------- |
| Unified auth                  | Required              | Required               | Required |
| Home/Explore/Activity/Profile | Required              | Required               | Required |
| Domain cards + launch         | Required              | Required               | Required |
| Unified save library          | Required              | Required               | Required |
| Unified search                | Required              | Required               | Required |
| Notification center           | Required              | Required               | Required |
| Push notifications            | Required              | Optional               | Optional |
| Offline shell                 | Required (core views) | Required (core routes) | Required |
| Installability                | N/A                   | N/A                    | Required |

## 7. MVP Exit Criteria (Release Blocking)

### 7.1 Product Criteria

- User can reach each domain value entry in <= 2 taps from Home.
- User can authenticate once and navigate cross-domain without re-login loops.
- User can save and retrieve items from at least three of the original four MVP
  domains.
- User can complete one meaningful daily loop in each domain:
  - Tara: launch/resume a meditation
  - Veritas: open and read a verified story/claim
  - Nyx: open nightly highlight and sky exploration path
  - Arete: complete a daily check-in action

### 7.2 Technical Criteria

- Mobile and web pass `lint`, `typecheck`, `test`, and `build` in CI.
- Smoke e2e tests pass for auth, navigation, and one flow per domain.
- Partial outage of one domain does not break shell rendering.
- PWA install flow works on supported browsers.

### 7.3 Non-Functional Criteria

- Accessibility baseline:
  - screen reader labels on all major controls
  - keyboard navigation on web/PWA core routes
  - WCAG AA contrast on primary UI
- Performance baseline:
  - mobile cold start <= 2.5s target on mid-tier profile
  - home hydration p95 <= 2.0s target (excluding external outages)
- Reliability baseline:
  - crash-free session rate >= 99.5% in beta window

## 8. MVP Prioritization (Must/Should/Could)

### 8.1 Must Have (MVP)

- Shell navigation + domain switcher
- Shared auth + session persistence
- Home/Explore/Activity/Profile core surfaces
- Domain launch adapters (Tara, Veritas, Nyx, Arete)
- Unified search, save, and notifications center
- Web + PWA installability
- Core analytics + error monitoring + smoke e2e

### 8.2 Should Have (If Capacity Allows)

- Recommendation explanations ("why this")
- Enhanced offline action queueing
- Richer domain-specific preview cards
- Cross-domain quick routines (morning/evening)

### 8.3 Could Have (Post-MVP Candidate)

- Advanced personalization controls
- Cross-domain achievements system
- Extended social/accountability features
- Deep wearable integrations

## 9. Phased MVP Delivery

### 9.1 MVP-A (Shell Baseline)

- OSHUN mobile/web scaffolding
- Shared auth
- Navigation and shell UX
- Home + profile baseline

### 9.2 MVP-B (Domain Activation)

- Tara and Veritas integration
- Nyx integration path chosen and delivered
- Arete daily check-in surfaces
- Unified search/save/activity

### 9.3 MVP-C (Quality Gate + Launch)

- PWA install/offline readiness
- E2E stability and observability completeness
- Beta rollout and launch readiness checks

## 10. Dependencies

- Domain API stability for Tara, Veritas, Nyx, and Arete data surfaces
- Final auth/identity contract and entitlement policy
- Design system token and interaction standard finalization
- CI/CD readiness for mobile (EAS) and web deployments

## 11. De-Scope Levers (If Timeline Risk Materializes)

If delivery risk is high, de-scope in this order while preserving MVP intent:

1. Reduce depth of domain-specific secondary features, not shell quality.
2. Keep Nyx in embed mode for MVP rather than native rewrite.
3. Limit Arete surfaces to daily check-in + one progress summary view.
4. Defer advanced recommendation logic, keep deterministic fallback ranking.

Do not de-scope:

- Auth/session reliability
- Cross-domain navigation
- Accessibility baseline
- Production observability

## 12. Sign-Off Checklist

- Product sign-off on in-scope/out-of-scope boundaries
- Engineering sign-off on technical feasibility and dependencies
- Design sign-off on shell IA and interaction standards
- QA sign-off on release-blocking test criteria
- Security/privacy sign-off on auth, consent, and data handling
