Status: Active
Owner: OSHUN Product, OSHUN Mobile, OSHUN Platform
Date: April 9, 2026
Related:
docs/releases/v1/specs/todos.mddocs/releases/v1/reports/metis-v1-scorecard.mddocs/releases/v1/reports/metis-v1-workstream-tracking.mdapps/oshun/mobile/app/domain/[domainId].tsxapps/oshun/mobile/src/navigation/routes.tsapps/oshun/mobile/src/navigation/deepLinkHydration.tsapps/oshun/mobile/src/notifications/notificationRouting.tsapps/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:
- What is the canonical native entry model for Metis on mobile?
- How is continuity preserved across shell, notifications, search, and resume?
- How should Metis reminders behave on mobile in V1?
- 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].tsxapps/oshun/mobile/app/(tabs)/index.tsxapps/oshun/mobile/app/(tabs)/explore.tsxapps/oshun/mobile/app/(tabs)/activity.tsxapps/oshun/mobile/src/navigation/routes.tsapps/oshun/mobile/src/navigation/deepLinkHydration.tsapps/oshun/mobile/src/navigation/mobileHomeMetisModels.tsapps/oshun/mobile/src/navigation/mobileExploreMetisSearch.tsapps/oshun/mobile/src/notifications/types.tsapps/oshun/mobile/src/notifications/notificationRouting.tsapps/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/webfor 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/...andhttps://oshun.app/d/metis/...)
4.2 Canonical Launch Rule#
Every learner-facing Metis launch on mobile should preserve the shell envelope:
domainId=metisorigin=<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:
originstackpathref
Optional continuity enrichers:
notificationIdnotificationKindcourseIdsessionIdassessmentId
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:
- active timed or due assessment
- in-progress tutoring session requiring follow-up
- in-progress course lesson
- recent course detail
- 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=metiskind=reminderactionPath- 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.