# ADR-0056: OSHUN Mobile Shell Relationship Model

**Status**: Accepted  
**Date**: 2026-03-24  
**Authors**: OSHUN Product, OSHUN Design, OSHUN Mobile Engineering  
**Reviewers**: Tara, Arete, Veritas, Nyx, Nisaba leads  
**Supersedes**: N/A  
**Superseded by**: N/A

## Context and Problem Statement

The PRD already required the mobile app to support `home`, `explore`,
`activity`, `library`, `assistant`, and `profile`, but the implemented mobile
shell still exposed only four structural tabs:

- `home`
- `explore`
- `activity`
- `profile`

That left two major gaps:

- `library` existed as shared saved-state infrastructure and an embedded view
  inside `Explore`, but not as a canonical mobile shell surface
- `assistant` did not exist as a first-class mobile continuity layer at all

This created ambiguity in the most interruption-prone runtime:

- saved material had no dedicated mobile return point
- explore was carrying both discovery and preservation responsibilities
- there was no global mobile assistant entry with contextual carry-over
- docs, QA, and route contracts could not point to one explicit mobile
  relationship model

The PRD already points to the intended outcome:

- the mobile app must support `home`, `explore`, `activity`, `library`,
  `assistant`, and `profile`
- the customer shell must provide one library/save model and one assistant entry
  layer
- assistant interaction should work anywhere in the app

## Decision Drivers

- **Continuity under interruption**: mobile needs a durable preserve surface for
  small-session, stop-start behavior.
- **Thumb-reachable clarity**: the shell should not hide saved-state management
  inside Explore.
- **Non-flattening IA**: assistant should remain contextual help, not a sixth
  peer tab competing with structural destinations.
- **Cross-platform coherence**: web and mobile should publish the same
  conceptual relationship while keeping platform-appropriate behavior.
- **Contractability**: shared IA, routes, docs, analytics, and QA need one
  explicit mobile model.

## Considered Options

### Option 1: Keep mobile at four tabs and leave library inside Explore

**Pros**:

- Lowest implementation cost.
- Avoids tab-bar changes.

**Cons**:

- Leaves the PRD only partially implemented.
- Collapses discovery and preservation into one surface.
- Makes saved-state return paths inconsistent on the platform that needs them
  most.

### Option 2: Add both Library and Assistant as peer tabs

**Pros**:

- Simple mental model for tab inventory.
- Easy to expose both capabilities in visible chrome.

**Cons**:

- Misstates assistant behavior, which should inherit context from anywhere.
- Produces a crowded mobile tab bar.
- Treats assistant as a destination instead of a continuity layer.

### Option 3: Make Library a structural tab and Assistant a global continuity sheet (Chosen)

**Pros**:

- Matches the PRD's "one library and save model" and "one assistant entry layer"
  language.
- Gives mobile saved-state behavior a real shell home.
- Preserves assistant as context-carrying help instead of a competing tab.
- Produces one reusable model for IA, routes, telemetry, docs, and QA.

**Cons**:

- Requires refactoring Explore to hand preserved material into Library instead
  of containing the full library view.
- Requires explicit documentation so Assistant is not mistaken for a missing
  route.

## Decision Outcome

**Chosen option**: Option 3.

### Normative Mobile-Shell Rule

The mobile customer shell has five structural tab surfaces and one global
continuity layer:

- `Home` anchors
- `Explore` branches
- `Activity` reflects
- `Library` preserves
- `Profile` governs
- `Assistant` guides as a global sheet

### Structural-Tab Rule

On mobile, `Home`, `Explore`, `Activity`, `Library`, and `Profile` are the
structural shell tabs. They may appear in the tab bar, route contracts, and
primary wayfinding.

### Library Rule

`Library` is the canonical mobile surface for saved, queued, highlighted,
downloaded, and preserved cross-domain material. Explore may preview recent
saves, but durable saved-state management belongs in `Library`.

### Assistant Rule

`Assistant` is **not** a peer mobile tab. It is the global mobile assistant
continuity layer. It should open as a contextual sheet from anywhere in the app,
inherit the current shell or domain context, and route the user back into the
correct structural tab or domain destination.

### Handoff Rule

The core mobile-shell handoffs are:

1. `Home -> Explore` when centered intent branches into discovery.
2. `Home -> Activity` when the user wants quick continuity review.
3. `Explore -> Library` when promising material becomes worth preserving.
4. `Activity -> Library` when reflected continuity needs a durable return point.
5. `Library -> Activity` when saved material becomes the next active step.
6. `Library -> Explore` when preserved context should seed fresh discovery.
7. `Assistant -> any structural tab` when contextual help should resolve into a
   real destination.

### Contract Publication

The shared representation of this rule lives in
`libs/oshun/navigation/src/customer-ia.ts`.

The mobile route publication for structural tabs lives in
`apps/oshun/mobile/src/navigation/routes.ts`.

## Scope Boundaries

- This ADR is **mobile-only**. Web relationship work is defined in `ADR-0055`.
- This ADR does **not** define the customer/admin shell relationship; that
  remains `V1-UX-005`.
- This ADR does **not** require the final production assistant backend or
  streaming architecture. It defines the mobile shell relationship and entry
  behavior.

## Architecture Implications

- The mobile shell must expose a real `Library` tab route.
- Explore should preview saves and hand preserved context into `Library` instead
  of acting as the full library surface.
- Assistant must be mounted at the mobile app root so it can open from shell
  tabs and domain routes alike.
- Mobile telemetry, deep-link hydration, and smoke coverage should understand
  `library` as a structural tab.

## Acceptance Criteria

`V1-UX-004` is complete only when all criteria below are true:

1. A canonical ADR defines the mobile relationship among `home`, `explore`,
   `activity`, `library`, `assistant`, and `profile`.
2. Shared IA code publishes the same mobile-shell model.
3. The mobile route contract exposes `library` as a structural tab route.
4. The mobile shell exposes a real library surface instead of only an embedded
   Explore section.
5. The mobile app exposes assistant as a global continuity layer rather than a
   peer tab.
6. Mobile docs and QA artifacts no longer describe the shell as only four tabs.

## Related Decisions

- `docs/adr/ADR-0059-oshun-customer-information-architecture-and-tara-centered-spine.md`
- `docs/adr/ADR-0060-oshun-nisaba-first-class-customer-domain.md`
- `docs/adr/ADR-0061-oshun-web-shell-relationship-model.md`

## References

- `docs/releases/v1/specs/web-app-admin-v1-prd.md`
- `apps/oshun/mobile/README.md`
- `libs/oshun/navigation/src/customer-ia.ts`
- `apps/oshun/mobile/src/navigation/routes.ts`