# OSHUN V1 Metis Mobile Strategy

Status: Active  
Owner: OSHUN Product, OSHUN Mobile, OSHUN Platform  
Date: April 9, 2026

Related:

- `docs/releases/v1/specs/todos.md`
- `docs/releases/v1/reports/metis-v1-scorecard.md`
- `docs/releases/v1/reports/metis-v1-workstream-tracking.md`
- `apps/oshun/mobile/app/domain/[domainId].tsx`
- `apps/oshun/mobile/src/navigation/routes.ts`
- `apps/oshun/mobile/src/navigation/deepLinkHydration.ts`
- `apps/oshun/mobile/src/notifications/notificationRouting.ts`
- `apps/oshun/mobile/e2e/flows/shell/activity-metis-continuity.yaml`

## 1. Purpose

Define the canonical V1 mobile strategy for Metis inside the Oshun native shell.

This document answers four questions:

1. What is the canonical native entry model for Metis on mobile?
2. How is continuity preserved across shell, notifications, search, and resume?
3. How should Metis reminders behave on mobile in V1?
4. What remains intentionally out of scope for native Metis until later tasks
   land?

This is a strategy and execution-boundary document. It is not a marketing plan
and it is not a promise that every Metis surface is already fully native.

## 2. Existing Implementations Reviewed First

Before defining the strategy, the current implementation seams were reviewed in:

- `apps/oshun/mobile/app/domain/[domainId].tsx`
- `apps/oshun/mobile/app/(tabs)/index.tsx`
- `apps/oshun/mobile/app/(tabs)/explore.tsx`
- `apps/oshun/mobile/app/(tabs)/activity.tsx`
- `apps/oshun/mobile/src/navigation/routes.ts`
- `apps/oshun/mobile/src/navigation/deepLinkHydration.ts`
- `apps/oshun/mobile/src/navigation/mobileHomeMetisModels.ts`
- `apps/oshun/mobile/src/navigation/mobileExploreMetisSearch.ts`
- `apps/oshun/mobile/src/notifications/types.ts`
- `apps/oshun/mobile/src/notifications/notificationRouting.ts`
- `apps/oshun/mobile/e2e/flows/shell/activity-metis-continuity.yaml`

That review establishes the current truth:

- Metis already exists as a first-class mobile shell domain route.
- The mobile shell already understands canonical Metis deep links.
- Activity and push payloads can already resolve into `/domain/metis`.
- The mobile domain screen still presents Metis as a planned preview lane rather
  than a launch-grade learner runtime.
- Reminder preferences and continuity behavior are not yet fully specialized for
  Metis and must not be improvised differently across surfaces.

## 3. Canonical Decision

### 3.1 Primary Product Posture

For OSHUN V1, Metis on mobile is a shell-owned native route, not a separate
mobile product.

The canonical learner-facing mobile surface is:

- `apps/oshun/mobile`
- route family: `/domain/metis`
- continuity envelope: `origin`, `stack`, `path`, `ref`, plus optional
  notification metadata

This means:

- Home, Explore, Activity, notification taps, and canonical deep links all
  converge on the same native shell route.
- Mobile should not invent a second navigation model for Metis.
- Mobile should not deep link users directly into `apps/metis/web` for normal
  learner entry, resume, or reminder journeys.

### 3.2 Secondary Product Posture

`apps/metis/web` remains the specialist learner and heavy workflow runtime while
the native shell expands.

In V1:

- native shell owns entry, continuity, resume, reminders, notification routing,
  and lightweight educational orientation
- specialist web may still own heavier or denser learner execution until the
  corresponding shell/mobile tasks are complete
- authoring is explicitly not a native-first mobile commitment in V1

### 3.3 Non-Negotiable Rule

There is exactly one canonical mobile Metis identity in V1:

- domain id: `metis`
- shell route: `/domain/metis`
- shell label: `Metis`
- shell role: learning lane inside Oshun, not an external detached app

## 4. Native Entry Strategy

All mobile Metis entry points must resolve into the shared domain route.

### 4.1 Allowed Entry Surfaces

- Home continuation and recommendation cards
- Explore search and spotlight cards
- Activity feed entries
- Push notifications
- Domain switcher and domain rail
- Canonical deep links (`oshun://metis/...` and `https://oshun.app/d/metis/...`)

### 4.2 Canonical Launch Rule

Every learner-facing Metis launch on mobile should preserve the shell envelope:

- `domainId=metis`
- `origin=<home|explore|activity|library|profile>`
- `stack=<previous-domain-stack when relevant>`
- `path=<target learner path>`
- `ref=<launch source>`

No entry surface should bypass that envelope by navigating straight to an opaque
internal screen without origin and return semantics.

### 4.3 Path Semantics

The `path` parameter is the learner-intent target.

Canonical V1 targets:

- `/courses`
- `/courses/:courseId`
- `/tutoring`
- `/tutoring/:sessionId`
- `/assessments`
- `/assessments/:assessmentId`

V1 mobile should treat these as the only stable reminder and continuity targets
for learner flows.

### 4.4 Native-First vs Web-Fallback Rule

Native-first:

- browse entry
- resume course entry
- tutoring resume entry
- assessment resume entry
- reminder intake
- continuity summary

Web-specialist fallback allowed:

- dense authoring workflows
- institutional management flows
- any learner flow not yet implemented natively but still reachable through the
  canonical shell contract

If a fallback is required, the user should still enter through `/domain/metis`
first so Oshun can preserve continuity and communicate the handoff.

## 5. Continuity Strategy

### 5.1 Canonical Continuity Object

For mobile Metis, continuity is defined by this tuple:

- `origin`
- `stack`
- `path`
- `ref`

Optional continuity enrichers:

- `notificationId`
- `notificationKind`
- `courseId`
- `sessionId`
- `assessmentId`

The first tuple is canonical. The enrichers are support metadata only.

### 5.2 Continuity Rules

- Home continuation must reopen the most recent resumable learner target, not a
  generic Metis landing page.
- Explore launches should preserve that they originated from discovery and must
  remain analytically distinguishable from Home or reminder re-entry.
- Activity and push launches should preserve `ref=notification:<id>` or an
  equivalent canonical source marker.
- Returning from a Metis mobile flow should always preserve the originating tab
  and prior domain stack where provided.

### 5.3 Resume Priority Order

When multiple resumable targets exist, mobile should prefer:

1. active timed or due assessment
2. in-progress tutoring session requiring follow-up
3. in-progress course lesson
4. recent course detail
5. general `/courses`

This ordering is the canonical V1 resume doctrine for later implementation
tasks. It prevents mobile from reopening a low-value catalog view while a
higher-urgency mastery step exists.

### 5.4 Continuity Storage Rule

Mobile may cache the latest Metis route context locally for shell continuity,
but the durable source of truth for learner progress remains backend-owned.

Local state may remember:

- most recent Metis target path
- most recent source ref
- last-opened timestamp

Local state must not pretend to be the durable learner record for:

- lesson completion
- assessment due state
- tutoring transcript truth
- reminder completion state

## 6. Reminder Strategy

### 6.1 Product Principle

Metis reminders on mobile exist to restart a concrete learning thread, not to
generate generic engagement traffic.

Reminder behavior should be:

- specific
- resumable
- tier-aware
- respectful of quiet hours
- anchored to a canonical learner target

### 6.2 Canonical V1 Reminder Families

- Study continuation reminder
  - target: in-progress course lesson or course path
- Assessment due reminder
  - target: due assessment or assessment list
- Tutoring follow-up reminder
  - target: active tutoring session or tutoring lane

Unsupported in V1:

- generic “come back to Metis” reminders with no concrete target
- reminders that deep link to authoring
- reminders that claim offline functionality not actually implemented

### 6.3 Routing Rule

All Metis reminders must route through the shared mobile notification layer and
resolve into `/domain/metis`.

Allowed payload forms:

- canonical deep link:
  - `oshun://metis/courses/crs-002?...`
- canonical web link:
  - `https://oshun.app/d/metis/courses/crs-002?...`
- relative learner path:
  - `/courses/crs-002`
  - `/tutoring/session-2`
  - `/assessments/asmt-4`

Every reminder payload should include:

- `domain=metis`
- `kind=reminder`
- `actionPath`
- stable reminder id

### 6.4 Reminder Copy Rule

Reminder copy must identify:

- what the learner is resuming
- why it matters now
- where the tap will land

Good examples:

- “Resume Calculus I Lesson 4 before the mastery check cools off.”
- “Your matrix quiz is due today. Reopen the checkpoint in Metis.”
- “Return to tutoring to finish the misconception repair thread.”

Bad examples:

- “Come back to Metis”
- “Continue learning”
- “You have updates”

### 6.5 Reminder Eligibility Rule

Metis reminders should only fire when there is an actual resumable or due item.

No reminder should be scheduled if the learner has:

- no in-progress course
- no due assessment
- no active tutoring thread needing follow-up

### 6.6 Reminder Preference Rule

Metis must be represented as its own notification preference lane in the shared
mobile notification model, with copy oriented around:

- study continuity
- tutoring follow-up
- assessment timing

This is a launch requirement for `V1-MET-028`, but this strategy makes the
policy canonical now so Home, Activity, notifications, and preferences do not
drift.

## 7. Native Scope Boundaries

### 7.1 In Scope for V1 Mobile

- shell-native entry and routing
- shell-native continuity
- shell-native reminder intake
- shell-native resume targeting
- shell-native lightweight Metis orientation
- learner-legible tier and upgrade handling
- coherent handoff into deeper learner execution where implemented

### 7.2 Explicitly Out of Scope for V1-MET-023

- shipping a separate Metis mobile app
- promising native mobile authoring
- promising full offline course playback before offline work exists
- widening shared library persistence before `V1-MET-024`
- building the reminder runtime itself before `V1-MET-028`

## 8. Execution Implications for Next Tasks

This strategy sets the implementation contract for the following backlog items:

| Task         | Strategy implication                                                                                                                                                 |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `V1-MET-024` | saved courses, queues, recent sessions, and resume surfaces must plug into the canonical mobile continuity tuple rather than inventing a separate Metis memory model |
| `V1-MET-025` | loading/offline/degraded states must explain whether the learner is viewing a shell preview, resumable target, or fallback handoff                                   |
| `V1-MET-027` | learner profile, pace, and goals must influence reminder eligibility and resume prioritization, not only desktop/web surfaces                                        |
| `V1-MET-028` | reminder scheduling, copy, preferences, and notification payloads must implement the reminder doctrine defined in section 6                                          |

## 9. Acceptance Criteria

`V1-MET-023` should be considered satisfied when all of the following are true:

- the canonical Metis mobile posture is documented as shell-owned, not
  standalone-app-owned
- native entry surfaces and fallback rules are explicit
- continuity rules are explicit
- reminder families, routing rules, and eligibility rules are explicit
- the strategy is linked from the Oshun documentation map
- later Metis mobile tasks can reference this document as the source of truth

## 10. Current Gaps Against This Strategy

As of April 9, 2026, the current implementation still has known gaps relative to
this strategy:

- Metis is present in mobile notification typing and routing, but Metis-specific
  reminder preference copy is not yet fully specialized.
- Mobile Metis still presents primarily as a planned preview lane rather than a
  native learner runtime.
- Home/activity/library/resume surfaces are not yet unified around the full
  canonical Metis continuity tuple.
- Reminder runtime, scheduling, and learner-specific eligibility are not yet
  implemented.

These gaps are expected and are addressed by `V1-MET-024` through `V1-MET-028`.
