Eve library

OSHUN V1 Metis Mobile Strategy

Spec

Revision 1

On this page

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.