# ADR-0055: OSHUN Web Shell Relationship Model

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

## Context and Problem Statement

ADR-0053 established Tara as the customer center. ADR-0054 made Nisaba a
first-class companion domain. The remaining gap on web was structural: the PRD
already required one library/save model and one assistant entry layer, but the
implemented web shell still only had explicit primary routes for `Home`,
`Explore`, `Activity`, and `Profile`.

That left the web shell in an ambiguous state:

- `library` existed as scattered links, saved-state copy, and Nisaba subpaths,
  but not as a normative customer-shell surface
- `assistant` existed as a floating panel, but without one explicit rule saying
  whether it is a peer page or a global layer
- save and return flows had no canonical destination on web
- future route, nav, and QA work could not point to one authoritative
  relationship model for the six named shell surfaces

The PRD already points to the intended answer:

- web needs deep library and collection management
- web needs an assistant dock with context carry-over
- the shell must present one coherent relationship among `home`, `explore`,
  `activity`, `library`, `assistant`, and `profile`

## Decision Drivers

- **Clarity**: route, nav, and QA work need one explicit definition of what each
  web shell surface is for.
- **Continuity**: saved material and assistant context must have a durable home.
- **Non-flattening IA**: not every named shell surface should become a peer page
  with the same job.
- **Web fit**: web is the depth, research, dashboard, and workspace runtime, so
  library and assistant need web-native semantics.
- **Contractability**: shared code and docs should publish the same model.

## Considered Options

### Option 1: Treat library and assistant as additional peer top-level pages

**Description**: add `Library` and `Assistant` as ordinary peer shell routes
beside `Home`, `Explore`, `Activity`, and `Profile`.

**Pros**:

- Simple mental model for route lists.
- Easy to mirror in nav code.

**Cons**:

- Misstates assistant behavior on web, which is supposed to carry context from
  anywhere.
- Encourages a flat shell where every surface competes equally.
- Fails to distinguish structural destinations from global help layers.

### Option 2: Keep library and assistant implicit

**Description**: continue using saved-state links, local buttons, and the
existing assistant panel without a formal shell rule.

**Pros**:

- Lowest immediate implementation effort.
- Avoids route and nav changes.

**Cons**:

- Leaves the PRD requirements only partially implemented.
- Makes save and continuity behavior inconsistent across surfaces.
- Prevents shared IA code and docs from naming the actual web-shell model.

### Option 3: Make library a structural shell surface and assistant a global continuity layer (Chosen)

**Description**: declare `Home`, `Explore`, `Activity`, `Library`, and `Profile`
as the structural web-shell surfaces, while `Assistant` remains a global entry
layer that overlays those structural surfaces and carries context across them.

**Pros**:

- Matches the PRD's "one library and save model" and "one assistant entry layer"
  language.
- Gives saved-state and collection management a canonical web destination.
- Preserves assistant as contextual help rather than a competing page.
- Produces a reusable contract for web nav, docs, and QA.

**Cons**:

- Requires explicit documentation so assistant is not mistaken for a missing
  route.
- Requires shell navigation work to incorporate `Library` without flattening the
  Tara-centered model.

## Decision Outcome

**Chosen option**: Option 3.

### Normative Web-Shell Rule

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

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

### Structural-Surface Rule

On web, `Home`, `Explore`, `Activity`, `Library`, and `Profile` are structural
destinations. They may appear in route contracts, shell navigation, and primary
wayfinding.

### Library Rule

`Library` is the canonical web surface for saved, queued, highlighted,
collected, and preserved cross-domain objects. Discovery may create saves and
activity may reference them, but durable saved-state management belongs in
`Library`.

### Assistant Rule

`Assistant` is **not** a peer structural route on web. It is the global
assistant entry layer. It must inherit the current surface context, help the
user act or decide, and then hand them back into the correct structural or
domain destination.

### Handoff Rule

The core web-shell handoffs are:

1. `Home -> Explore` when centered intent branches into discovery.
2. `Home -> Activity` when the user should review or continue in-flight work.
3. `Explore -> Library` when promising material becomes worth saving.
4. `Activity -> Library` when reflected continuity needs a durable return point.
5. `Library -> Explore` when saved context seeds fresh discovery.
6. `Library -> Activity` when a saved object becomes the next active step.
7. `Assistant -> any structural surface` when contextual help should resolve
   into an actual destination rather than linger as detached chat.

### Contract Publication

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

The web route publication for the structural surfaces lives in
`apps/oshun/web/src/navigation/routes.ts`.

## Scope Boundaries

- This ADR is **web-only**. Mobile-specific relationship work remains
  `V1-UX-004`.
- This ADR does **not** define the customer/admin shell relationship; that
  remains `V1-UX-005`.
- This ADR does **not** require the final assistant dock architecture or
  long-lived persistent dock state. That deeper web implementation remains later
  work such as `V1-WEB-003`.

## Architecture Implications

- The web shell must expose a real `/library` route and corresponding shell-nav
  entry.
- Saved-state affordances should route into `Library` when the user needs a
  durable return point.
- Assistant triggers should work from any structural surface and should preserve
  surface context.
- Web QA and accessibility shortcuts can now distinguish structural navigation
  from assistant invocation.

## Acceptance Criteria

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

1. A canonical ADR defines the web relationship among `home`, `explore`,
   `activity`, `library`, `assistant`, and `profile`.
2. Shared IA code publishes the same web-shell model.
3. The web route contract exposes `library` as a shell surface.
4. The assistant is explicitly modeled as a global entry layer rather than a
   missing peer page.
5. Web docs and QA artifacts no longer describe the shell as only
   `Home/Explore/Activity/Profile`.

## 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-0015-deep-linking-and-cross-domain-routing.md`

## References

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