# OSHUN V1 Customer Web Shell Navigation Audit

Date: 2026-05-13. Mandate: `V1-DOC-002` (launch-readiness manifest entry
`customer_ia_oshun_consumer_doc`).

## Scope

Captures the five-domain consumer IA exposed by the OSHUN customer web shell at
`apps/oshun/web/src/app/`, the navigation primitives that bind those domains
together, and the automated coverage that defends them. Companion documents:

- Customer IA reference: `docs/oshun/ia-and-experience-quality.md`.
- Documentation index: `docs/oshun/v1-documentation-index.md`.
- Launch-readiness manifest:
  `libs/oshun/analytics/src/v1-launch-readiness-manifest.ts` (mandates
  `V1-DOC-001..021`).

## Five-domain consumer IA

The customer shell exposes the six top-level nav slots from
`libs/oshun/i18n/src/index.ts`
(`shell.nav.{home,explore,activity,library,assistant,profile}`) and the five
domain entry points exercised by signoff:

| Slot      | Route       | Purpose                                                             |
| --------- | ----------- | ------------------------------------------------------------------- |
| Home      | `/`         | Tara-first continuity, recent activity surface, assistant handoff.  |
| Explore   | `/explore`  | Cross-domain discovery dashboard, domain switcher.                  |
| Activity  | `/activity` | Continuity timeline across domains.                                 |
| Library   | `/library`  | Saved-continuity dashboard, Nisaba compare desk, reading desk.      |
| Assistant | shell dock  | Assistant invocation surface; persona disclosure and memory toggle. |
| Profile   | `/profile`  | Account dashboard, notification settings, privacy controls.         |

Domain entry points (each renders into the shell with the matching domain accent
and Sophia evidence rail where claims surface):

| Domain  | Route      | Notes                                                                        |
| ------- | ---------- | ---------------------------------------------------------------------------- |
| Tara    | `/tara`    | Ritual continuity; reduced-motion parity per `ia-and-experience-quality.md`. |
| Veritas | `/veritas` | Daily-briefing rails; per-claim confidence band; counterclaim view.          |
| Nyx     | `/nyx`     | Sky events; calendar-sync; concept-graph link to Nisaba/Tara.                |
| Arete   | `/arete`   | Habits, goals; Lilith-bound coach personas.                                  |
| Nisaba  | `/nisaba`  | Passages, editions, compare desk, evidence inspector.                        |
| Metis   | `/metis`   | Tutor sessions; mastery surfaces; assistant-bound study paths.               |

The legacy `app/domains/<domain>` routes remain as compatibility entry points
for deep links; the canonical entries are the top-level domain routes above.

## Automated coverage

Browser-level signoff lives in `apps/oshun/web/e2e/`:

- `shell-route-signoff.spec.ts` — desktop signoff for home, explore, library,
  activity, search, notifications, profile, plus Nisaba compare and reading
  desks; covers loading/empty/offline/error preview states via `?shellState=…`.
- `shell-navigation-analytics.spec.ts` — captures the canonical analytics events
  emitted by shell startup, library-tab navigation, and library-origin domain
  launches against the customer-taxonomy contract.
- `shell-domain-nav.spec.ts` (+ snapshots) — visual signoff of the domain
  switcher and per-domain entry chrome.
- `shell-domain-unavailable-fallback.spec.ts` — partial-outage fallback when a
  domain card cannot render.
- `shell-first-impression-visual.spec.ts` (+ snapshots) — landing first-frame
  visual signoff against the redesigned chrome.
- `shell-boundary.spec.ts` — adapter/contract boundary between the shell and
  per-domain adapters.
- `shell-experimentation-bootstrap.spec.ts` — feature-flag fan-out from
  bootstrap.
- `metis-shell-entry-points.spec.ts` — Metis-specific entry-point regression.
- `offline-shell-routes.spec.ts` — service-worker behavior and offline-read
  parity per `ia-and-experience-quality.md` QA checklist.

Accessibility regression for the shell is locked by
`apps/oshun/web/e2e/support/accessibility.ts` (the `@axe-core/playwright`
wrapper invoked through `apps/oshun/admin/e2e/fixtures.ts`'s `axeAfterEach`
companion), with a WCAG 2.x A/AA budget asserting zero serious/critical
violations on every audited route.

Mobile-shell navigation coverage lives in
`apps/oshun/mobile/e2e/flows/common/{create-account,sign-in-existing}.yaml`
(Maestro flows) and is referenced from the launch-readiness manifest entry
`five_domain_shell_demo_seed`.

## Localization

The shell nav copy is fully externalized to `libs/oshun/i18n/src/index.ts` and
covered for every launch locale (`en-US`, `es-US`, `fr-FR`, `de-DE`, `ar`, `he`,
`ja-JP`, `pt-BR`). Direction (`rtl` for `ar`/`he`) and per-locale text-expansion
budgets are asserted by the i18n catalog test. Layout shells honor the budgets
per `docs/launch/locale-coverage.md`.

## Assistant disclosure

The assistant slot surfaces the canonical disclosure copy
(`assistant.disclosure.{ai,persona_changed,voice_changed,avatar_changed}` and
`assistant.memory.{on,off}`) on every persona/voice/avatar transition and
exposes the memory control inline. Evidence links from assistant answers route
through Sophia provenance per `evidence.provenance.{open,unavailable}`.

## Gaps observed (and where they are tracked)

- Domain switcher discoverability on first run — tracked via the customer-shell
  onboarding checklist in
  `apps/oshun/web/e2e/shell-first-impression-visual.spec.ts` snapshots; no GA
  blocker.
- Notifications drawer empty-state copy is shared between web and admin; long-
  form copy review owned by the support training program
  (`docs/training/oshun-v1-support.md`).
- `app/domains/<domain>` legacy redirects: scheduled for removal post-GA; cohort
  tracked in the release-taxonomy redirect manifest.

No gaps in this audit block launch. The five-domain consumer IA is fully wired
through routes, navigation, analytics, accessibility, localization, and
assistant disclosure, with signoff and visual regression locked in CI.

## Companion artifacts

- `docs/oshun/ia-and-experience-quality.md` — IA + QA checklist.
- `docs/content/v1-bundles.md` — per-domain content bundles + accessibility
  plan.
- `libs/oshun/analytics/src/customer-taxonomy.ts` — analytics taxonomy for shell
  startup, navigation, and domain launches.
- `libs/oshun/analytics/src/web-playwright-journey-coverage.ts` — journey
  coverage matrix for the customer shell.
