# OSHUN Web App

Next.js + TypeScript baseline for the OSHUN website and future installable PWA.

## Commands

- `pnpm nx run @oshun/web:dev`
- `pnpm nx run @oshun/web:build`
- `pnpm nx run @oshun/web:start`
- `pnpm nx run @oshun/web:lint`
- `pnpm nx run @oshun/web:typecheck`
- `pnpm nx run @oshun/web:test`
- `pnpm nx run @oshun/web:lighthouse`
- `pnpm nx run @oshun/web:lighthouse:collect`
- `pnpm nx run @oshun/web:lighthouse:assert`

## Critical Route Performance Budgets

- `src/performance/criticalRouteBudgets.ts` defines the canonical V1 budgets for
  the home dashboard, dedicated search results, and Nisaba reading surfaces.
- `src/__tests__/performance-web-vitals.test.ts` validates that those budgets
  stay aligned to official "good" Web Vitals thresholds and remain close to the
  current emitted route bundle baselines. bundle-baseline method, rationale,
  verification evidence, and remaining repo blockers before Lighthouse
  enforcement lands in `V1-WEB-027`.

## Lighthouse Critical Route Budgets

- `src/performance/criticalRouteLighthouseArtifacts.ts` converts the canonical
  route budgets into Lighthouse-compatible route URLs plus `budget.json` timing,
  resource, and request thresholds.
- `scripts/syncCriticalRouteLighthouseArtifacts.ts` regenerates
  `lighthouse-budget.json` and `lighthouse-routes.json` before local or CI
  Lighthouse runs.
- `lighthouserc.cjs` now audits only the three launch-critical V1 routes, while
  `lighthouse-budget.json` enforces per-route LCP, CLS, responsiveness-proxy,
  transfer, and request budgets. The responsiveness timing uses Lighthouse's
  `max-potential-fid` budget as the lab gate for the canonical INP ≤ 200 ms
  route target because Lighthouse page-load audits do not directly measure INP.
- `src/__tests__/critical-route-lighthouse-artifacts.test.ts` prevents drift
  between the committed Lighthouse artifacts and the canonical TypeScript budget
  source.

## PWA Playwright Signoff

- `e2e/pwa-install-update-offline.spec.ts` covers install-prompt dismissal
  persistence plus standard-route service-worker update states.
- `e2e/pwa-smoke.spec.ts` covers manifest/installability plus staged reading-
  route update behavior with entitled Nisaba fixtures.
- `e2e/offline-shell-routes.spec.ts` signs off on authenticated shell-route
  availability after offline warmup.
- `e2e/support/pwa.ts` centralizes the PWA/browser mocks used by those specs.
- `playwright.config.ts` now launches the BFF from the workspace root and uses
  explicit readiness URLs so Playwright can boot the OSHUN web harness correctly
  from `apps/oshun/web`.

## Shell Route Accessibility Automation

- `e2e/shell-route-accessibility.spec.ts` runs `@axe-core/playwright` scans
  against the authenticated home, explore, library, activity, notifications, and
  profile shell routes.
- `e2e/support/accessibility.ts` centralizes the axe runner, WCAG A/AA tag
  defaults, and local Next.js dev-overlay exclusions used by the route scans.
- Run the focused suite with:
  `pnpm --dir apps/oshun/web e2e -- e2e/shell-route-accessibility.spec.ts`

## Shell Keyboard Workflow Automation

- `e2e/shell-keyboard-workflows.spec.ts` covers skip links, shell route
  shortcuts, command palette keyboard selection, assistant entry, notifications
  drawer focus containment, and cross-domain quick actions without pointer
  input.
- `src/components/AccessibilityShell.tsx` now filters skip links to real route
  targets, focuses those targets after activation, resolves wrapper-based search
  inputs for `Alt+/`, and parses `Alt+1..5` shortcuts from `KeyboardEvent.code`
  so layout-specific option characters do not break shell navigation.
- `src/components/ShellLayout.tsx` now exposes programmatic skip-link targets
  for `#main-content` and `#shell-nav`, plus focus guards so the notifications
  drawer traps keyboard focus and restores the bell trigger on close.
- Run the focused suite with:
  `pnpm --dir apps/oshun/web e2e -- e2e/shell-keyboard-workflows.spec.ts`

## Critical Web Journey Coverage

- `e2e/support/critical-web-journeys.ts` is the customer-web coverage matrix for
  the V1 critical journeys. Each journey must point to Playwright evidence for
  keyboard-only operation, accessibility, visual regression, and resilience.
- `e2e/critical-web-journey-coverage.spec.ts` fails when a journey is missing a
  coverage dimension, a referenced spec disappears, or a referenced test title
  drifts.
- `e2e/visual-regression-pages.spec.ts` includes all six domain entries,
  including Metis desktop and mobile shell-entry screenshots.
- `.github/workflows/oshun-web-visual-regression.yml` runs the committed
  Playwright visual specs against the checked-in Chromium baselines: the main
  shell/page set on macOS and the Metis baselines on Linux. CI never updates
  snapshots.
- Run the focused gate with:
  `E2E_BASE_URL=http://127.0.0.1:3010 pnpm --dir apps/oshun/web e2e -- e2e/critical-web-journey-coverage.spec.ts`

## Home First-View Workspace

- `src/components/home/HomeWorkspace.tsx` now stages the home route as a
  workspace-first composition: one Tara-led anchor plus a compact context rail
  before the heavier continuity, evidence, and study panels.
- `src/components/home/HomeAnchorContextRail.tsx` carries the narrow first-view
  context stack for room sequencing, Veritas briefing context, and Nisaba study
  continuity.
- `src/components/home/HeroBanner.tsx` now exposes tracked quick room links
  inside the anchor itself so the home route reads like a working surface
  instead of a generic dashboard.
- Focused verification commands:
  - `pnpm --dir apps/oshun/web exec vitest run src/components/home/__tests__/HeroBanner.test.tsx src/components/home/__tests__/HomeWorkspace.test.tsx src/components/home/__tests__/HomeAnchorContextRail.test.tsx`
  - `E2E_BASE_URL=http://127.0.0.1:3010 pnpm --dir apps/oshun/web e2e -- e2e/home-tara-centering-continuity.spec.ts --workers=1`
  - `E2E_BASE_URL=http://127.0.0.1:3010 pnpm --dir apps/oshun/web e2e -- e2e/home-domain-narrative-order.spec.ts --workers=1`
  - `E2E_BASE_URL=http://127.0.0.1:3010 pnpm --dir apps/oshun/web e2e -- e2e/viewport-fit.spec.ts -g "home keeps redesigned panels inside the viewport across audited breakpoints" --workers=1`
  - `E2E_BASE_URL=http://127.0.0.1:3010 pnpm --dir apps/oshun/web e2e -- e2e/shell-first-impression-visual.spec.ts -g "captures home" --workers=1`

## Landing Focal Compositions

- `src/components/ShellLandingFocalStage.tsx` provides the shared first-view
  stage primitives used across Explore, Library, Activity, and Profile.
- `src/components/explore/ExploreDashboard.tsx`,
  `src/components/library/LibraryDashboard.tsx`,
  `src/components/activity/ActivityDashboard.tsx`, and
  `src/components/ProfileSettingsPanel.tsx` now open on one deliberate focal
  plane plus a calmer support rail instead of card-mosaic headers.
- `src/app/activity/page.tsx` now lets `ActivityDashboard` own the route anchor
  so Activity's first view reads as one continuity surface.
- `e2e/viewport-fit.spec.ts` now uses route-ready navigation plus PWA prompt
  dismissal for shell-route viewport audits instead of brittle `networkidle`
  waits.
- Focused verification commands:
  - `pnpm --dir apps/oshun/web exec vitest run src/components/explore/__tests__/ExploreDashboard.test.tsx src/components/library/__tests__/LibraryDashboard.test.tsx src/components/activity/__tests__/ActivityDashboard.test.tsx src/components/__tests__/ProfileSettingsPanel.test.tsx`
  - `E2E_BASE_URL=http://127.0.0.1:3010 pnpm --dir apps/oshun/web e2e -- e2e/explore-blended-discovery.spec.ts e2e/library-collection-management.spec.ts e2e/activity-cross-domain-continuity.spec.ts e2e/profile-assistant-controls.spec.ts e2e/profile-data-rights.spec.ts --workers=1`
  - `E2E_BASE_URL=http://127.0.0.1:3010 pnpm --dir apps/oshun/web e2e -- e2e/viewport-fit.spec.ts -g "explore keeps blended discovery lanes inside the viewport across audited breakpoints|activity keeps continuity threads inside the viewport across audited breakpoints|library keeps typed save filters and lanes inside the viewport across audited breakpoints|profile notifications keeps domain delivery controls inside the viewport across audited breakpoints|profile assistant controls keep disclosure and guide rails inside the viewport across audited breakpoints|profile data-rights controls keep export and deletion surfaces inside the viewport across audited breakpoints" --workers=1`
  - `E2E_BASE_URL=http://127.0.0.1:3010 pnpm --dir apps/oshun/web e2e -- e2e/shell-route-accessibility.spec.ts e2e/shell-route-signoff.spec.ts --workers=1`
  - `E2E_BASE_URL=http://127.0.0.1:3010 pnpm --dir apps/oshun/web e2e -- e2e/shell-first-impression-visual.spec.ts -g "captures explore desktop|captures library desktop|captures activity desktop|captures profile desktop|captures profile notifications desktop" --workers=1`

## Desktop Shell Chrome

- `src/design-system/components/TopBar.tsx`,
  `src/design-system/components/Sidebar.tsx`, `src/components/ShellLayout.tsx`,
  and `src/components/routines/ActiveExecutionStatusBar.tsx` now present the
  customer desktop shell as calmer matte chrome with stronger breadcrumb and
  wordmark hierarchy, quieter utility controls, and a restrained assistant and
  routine strip treatment.
- `e2e/shell-redesign-validation.spec.ts`, `e2e/shell-utility-dock.spec.ts`, and
  `e2e/shell-first-impression-visual.spec.ts` now assert the calmer shell tone
  markers directly, use authenticated route helpers instead of brittle
  `networkidle` waits, dismiss late PWA update prompts before shell actions that
  would otherwise be intercepted, and keep the dedicated Search first-view state
  in the same shell baseline suite as Home, Explore, Library, Activity, Profile,
  and the notifications drawer.
- Focused verification commands:
  - `pnpm --dir apps/oshun/web exec vitest run src/design-system/components/__tests__/TopBar.test.tsx src/design-system/components/__tests__/Sidebar.test.tsx src/components/__tests__/ShellLayout.test.tsx`
  - `E2E_BASE_URL=http://127.0.0.1:3010 pnpm --dir apps/oshun/web e2e -- e2e/shell-redesign-validation.spec.ts --workers=1`
  - `E2E_BASE_URL=http://127.0.0.1:3010 pnpm --dir apps/oshun/web e2e -- e2e/shell-utility-dock.spec.ts --workers=1`
  - `E2E_BASE_URL=http://127.0.0.1:3010 pnpm --dir apps/oshun/web e2e -- e2e/shell-keyboard-workflows.spec.ts e2e/shell-route-accessibility.spec.ts e2e/shell-route-signoff.spec.ts --workers=1`
  - `E2E_BASE_URL=http://127.0.0.1:3010 pnpm --dir apps/oshun/web e2e -- e2e/viewport-fit.spec.ts -g "home keeps redesigned panels inside the viewport across audited breakpoints|assistant dock preserves viewport fit across overlay and desktop-dock modes|explore keeps blended discovery lanes inside the viewport across audited breakpoints|activity keeps continuity threads inside the viewport across audited breakpoints|library keeps typed save filters and lanes inside the viewport across audited breakpoints|profile notifications keeps domain delivery controls inside the viewport across audited breakpoints|profile assistant controls keep disclosure and guide rails inside the viewport across audited breakpoints|profile data-rights controls keep export and deletion surfaces inside the viewport across audited breakpoints" --workers=1`
  - `E2E_BASE_URL=http://127.0.0.1:3010 pnpm --dir apps/oshun/web e2e -- e2e/shell-first-impression-visual.spec.ts --workers=1 --update-snapshots`
  - `E2E_BASE_URL=http://127.0.0.1:3010 pnpm --dir apps/oshun/web e2e -- e2e/shell-first-impression-visual.spec.ts --workers=1`

## Workspace Filter Toolbars

- `src/design-system/components/WorkspaceControls.tsx` provides the shared
  segmented rails, chips, badges, and quiet toolbar container used by the calmer
  V1 control strips.
- `src/components/search/SearchResultsView.tsx` now keeps domain and sort in a
  primary strip, moves secondary search filters behind an advanced disclosure,
  and uses the shared toolbar primitives so dense search still feels deliberate.
- `src/components/explore/ExploreDashboard.tsx`,
  `src/components/library/LibraryDashboard.tsx`,
  `src/components/activity/ActivityDashboard.tsx`,
  `src/components/NotificationsCenterPanel.tsx`, and
  `src/components/UniversalSearchPanel.tsx` now share the same low-noise
  segmented-rail and chip language instead of local pill stacks.
- `e2e/library-assistant-flow.spec.ts`, `e2e/search-scan-density.spec.ts`,
  `e2e/search-scan-density-accessibility.spec.ts`, and
  `e2e/visual-regression-pages.spec.ts` were updated so route-ready shell checks
  match the redesigned control-strip semantics instead of stale `networkidle`
  assumptions.
- Focused verification commands:
  - `pnpm --dir apps/oshun/web exec vitest run src/components/search/__tests__/SearchResultsView.test.tsx src/components/__tests__/NotificationsCenterPanel.test.tsx src/components/activity/__tests__/ActivityDashboard.test.tsx src/components/explore/__tests__/ExploreDashboard.test.tsx src/components/library/__tests__/LibraryDashboard.test.tsx src/components/__tests__/UniversalSearchPanel.test.tsx`
  - `E2E_BASE_URL=http://127.0.0.1:3010 pnpm --dir apps/oshun/web e2e -- e2e/search-scan-density.spec.ts e2e/search-scan-density-accessibility.spec.ts e2e/search-workspace-layout.spec.ts e2e/search-workspace-accessibility.spec.ts e2e/search-result-analytics.spec.ts e2e/nisaba-search-filters.spec.ts e2e/explore-blended-discovery.spec.ts e2e/library-collection-management.spec.ts e2e/library-assistant-flow.spec.ts e2e/notifications-center-mixed-context.spec.ts e2e/activity-cross-domain-continuity.spec.ts e2e/shell-route-accessibility.spec.ts e2e/shell-route-signoff.spec.ts --workers=1`
  - `E2E_BASE_URL=http://127.0.0.1:3010 pnpm --dir apps/oshun/web e2e -- e2e/viewport-fit.spec.ts -g "home keeps redesigned panels inside the viewport across audited breakpoints|explore keeps blended discovery lanes inside the viewport across audited breakpoints|activity keeps continuity threads inside the viewport across audited breakpoints|library keeps typed save filters and lanes inside the viewport across audited breakpoints" --workers=1`
  - `E2E_BASE_URL=http://127.0.0.1:3010 pnpm --dir apps/oshun/web e2e -- e2e/shell-first-impression-visual.spec.ts -g "captures explore desktop|captures library desktop|captures activity desktop|captures shell notifications drawer desktop" --workers=1 --update-snapshots`
  - `E2E_BASE_URL=http://127.0.0.1:3010 pnpm --dir apps/oshun/web e2e -- e2e/shell-first-impression-visual.spec.ts -g "captures explore desktop|captures library desktop|captures activity desktop|captures shell notifications drawer desktop" --workers=1`
  - `E2E_BASE_URL=http://127.0.0.1:3010 pnpm --dir apps/oshun/web e2e -- e2e/visual-regression-pages.spec.ts -g "Home universal search results|Notifications drawer|Explore page|Explore live search results|Library page|Activity page|Search results" --workers=1 --update-snapshots`
  - `E2E_BASE_URL=http://127.0.0.1:3010 pnpm --dir apps/oshun/web e2e -- e2e/visual-regression-pages.spec.ts -g "Home universal search results|Notifications drawer|Explore page|Explore live search results|Library page|Activity page|Search results" --workers=1`

## Search Workspace

- `src/components/search/SearchResultsView.tsx` now stages the dedicated search
  route as a true workspace: persistent continuity strip on the left, dense
  result list in the main lane, and a desktop preview/evidence/assistant lane
  that keeps the selected result live before navigation.
- `src/components/search/SearchScanCard.tsx` now provides the shared
  high-density card treatment for the Home universal search lane, Explore live
  search results, and the generic search-result surfaces that do not need the
  dedicated `/search` route's richer object body templates.
- `src/components/home/HomeWorkspace.tsx` now mounts the legacy home-origin
  `src/components/UniversalSearchPanel.tsx` as an explicit Home search lane, so
  the live Home route exposes the same search path already covered by analytics
  and search browser tests.
- Search result cards now expose one primary open action plus a sibling save
  action so keyboard focus, preview-follow behavior, and Library saves remain
  accessible without nested interactive controls.
- Search headers and generic cards now expose family labels, scan labels, action
  labels, and explicit relevance badges so object type and likely next move
  remain legible at a glance.
- `e2e/search-workspace-layout.spec.ts` signs off on desktop split behavior,
  assistant handoff, and tablet stacked fallback.
- `e2e/search-workspace-accessibility.spec.ts` runs the dedicated WCAG A/AA axe
  scan for the desktop search workspace with preview context visible.
- `e2e/search-scan-density.spec.ts` and
  `e2e/search-scan-density-accessibility.spec.ts` cover the Home universal
  search lane, Explore live search results, and the dedicated search route's
  scan-density cues.
- `e2e/search-result-analytics.spec.ts`, `e2e/nisaba-search-filters.spec.ts`,
  `e2e/shell-first-impression-visual.spec.ts`, and the search slices inside
  `e2e/visual-regression-pages.spec.ts` now cover the redesigned search
  workspace posture, its first-impression shell state, and the contextual
  assistant-dock handoff from the live preview lane.
- Focused verification commands:
  - `pnpm --dir apps/oshun/web exec vitest run src/components/search/search-config.test.ts src/components/search/__tests__/SearchResultsView.test.tsx src/components/__tests__/UniversalSearchPanel.test.tsx src/components/explore/__tests__/ExploreDashboard.test.tsx src/components/home/__tests__/HomeWorkspace.test.tsx`
  - `E2E_BASE_URL=http://127.0.0.1:3010 pnpm --dir apps/oshun/web e2e -- e2e/search-scan-density.spec.ts e2e/search-scan-density-accessibility.spec.ts e2e/search-workspace-layout.spec.ts e2e/search-workspace-accessibility.spec.ts e2e/search-result-analytics.spec.ts e2e/nisaba-search-filters.spec.ts e2e/explore-blended-discovery.spec.ts --workers=1`
  - `E2E_BASE_URL=http://127.0.0.1:3010 pnpm --dir apps/oshun/web e2e -- e2e/shell-first-impression-visual.spec.ts -g "captures search desktop" --workers=1`
  - `E2E_BASE_URL=http://127.0.0.1:3010 pnpm --dir apps/oshun/web e2e -- e2e/visual-regression-pages.spec.ts -g "Assistant dock|Search results page" --workers=1`
  - `E2E_BASE_URL=http://127.0.0.1:3010 pnpm --dir apps/oshun/web e2e -- e2e/visual-regression-pages.spec.ts -g "Home universal search results|Explore live search results|Search results" --workers=1`

## Nisaba Long-Form Reading Desk

- `src/components/domains/NisabaSurface.tsx` now stages Nisaba passage, compare,
  concept, notebook, evidence, and note routes as one long-form study desk with
  a study preface, multi-paragraph `62ch` reading frame, compare slips, and a
  note-ready support rail.
- `e2e/support/nisaba-fixtures.ts` now ships longer fixture passage bodies and
  richer compare reasons so browser coverage exercises a realistic reading
  posture instead of generic short paragraph blocks.
- `e2e/nisaba-reading-accessibility.spec.ts` runs dedicated WCAG A/AA axe scans
  against the desktop compare desk and the mobile note sheet, while the Nisaba
  slice in `e2e/visual-regression-pages.spec.ts` captures the passage desk,
  compare desk, notebook desk, evidence inspector, desktop and mobile note
  workspaces, and the mobile source-lineage sheet after the redesign. The
  page-level visual suite now blocks service workers and dismisses late PWA
  update prompts inside the shared search helper so those baselines stay
  deterministic.
- Focused verification commands:
  - `pnpm --dir apps/oshun/web exec vitest run src/components/domains/__tests__/NisabaSurface.test.tsx`
  - `E2E_BASE_URL=http://127.0.0.1:3010 pnpm --dir apps/oshun/web e2e -- e2e/nisaba-split-view.spec.ts e2e/domain-readability.spec.ts e2e/viewport-fit.spec.ts e2e/nisaba-reading-accessibility.spec.ts --workers=1 -g "Nisaba"`
  - `E2E_BASE_URL=http://127.0.0.1:3010 pnpm --dir apps/oshun/web e2e -- e2e/visual-regression-pages.spec.ts --workers=1 -g "Assistant dock|Nisaba|Search results page" --update-snapshots`
  - `E2E_BASE_URL=http://127.0.0.1:3010 pnpm --dir apps/oshun/web e2e -- e2e/visual-regression-pages.spec.ts --workers=1 -g "Assistant dock|Nisaba|Search results page"`
  - `E2E_BASE_URL=http://127.0.0.1:3010 pnpm --dir apps/oshun/web e2e -- e2e/visual-regression-pages.spec.ts --workers=1 -g "Nisaba" --update-snapshots`
  - `E2E_BASE_URL=http://127.0.0.1:3010 pnpm --dir apps/oshun/web e2e -- e2e/visual-regression-pages.spec.ts --workers=1 -g "Nisaba"`

## Reduced Motion Support

- Home hero/card entrance motion is implemented in `src/app/globals.css`.
- `prefers-reduced-motion: reduce` disables animations/transitions and keeps
  static final states.

## Home Dashboard

- `src/app/page.tsx` implements the web/PWA OSHUN dashboard shell with:
  - shell route navigator (`Home`, `Explore`, `Activity`, `Library`, `Profile`)
  - Tara-centered home anchor defined by
    `docs/adr/ADR-0053-oshun-customer-information-architecture-and-tara-centered-spine.md`
    plus `docs/adr/ADR-0055-oshun-web-shell-relationship-model.md` and
    `@oshun/navigation`
  - canonical daypart journey rail for morning anchoring, midday reorientation,
    and evening integration, published from
    `docs/adr/ADR-0058-oshun-daypart-cross-domain-journey-model.md`
  - greeting hero panel
  - KPI metric strip
  - reusable domain switcher panel with preserved Home launch context
  - universal search lane with domain filters, shared scan-density cards, and
    cross-domain results mounted directly inside
    `src/components/home/HomeWorkspace.tsx`
  - reusable domain switcher panel with preserved Explore launch context
  - notifications center panel with unread/priority filters and read-state
    actions
  - profile/settings panel with account, preferences, privacy, and connected
    domains
  - daily plan + quick actions tray trigger (`resume`, `save`, `continue`,
    `streak`)
  - cross-domain activity panel
  - four-card domain hub with per-domain CTA
- Domain launch UI labels/CTA/accent metadata come from `@oshun/domain-registry`
  launch contracts.

## Shell Boundary

- The web app now renders two explicit shells inside one platform surface:
  customer shell routes under `/`, `/explore`, `/activity`, `/library`, and
  `/profile`, plus admin shell routes under `/studio/...`.
- `src/components/ShellLayout.tsx` resolves `/studio` into distinct admin shell
  chrome instead of reusing customer navigation, assistant entry, mobile bottom
  nav, and routine overlays.
- `src/navigation/shells.ts` groups Studio routes into admin wayfinding sections
  (`Studio Home`, `Workspace`, `Operations`, `Governance`, `Observability`,
  `Identity`, `Configuration`).
- `src/components/OperatorAccessPanel.tsx` exposes the governed
  customer-to-admin handoff from Profile rather than treating Studio as a
  customer discovery destination.

## Profile and Settings UX

- `src/components/ProfileSettingsPanel.tsx` implements account and settings
  controls with:
  - profile identity header and quick stats
  - shared profile identity/stats/domain state from `@oshun/auth-client`
    (`src/profile/store.ts`)
  - shared preferences model (theme/language/notifications) from
    `@oshun/auth-client` (`src/profile/store.ts`)
  - shared privacy + consent model from `@oshun/auth-client`
    (`src/profile/store.ts`)
  - shared billing status + recovery model from `@oshun/auth-client`
    (`src/profile/store.ts`)
  - general preferences (`theme`, `language`, accessibility toggles)
  - notifications controls
  - privacy/access toggles
  - consent controls (`legal agreements`, `analytics`, `personalization`,
    `marketing`)
  - data rights requests UX (`export account data`,
    `request/cancel account deletion` with status history)
  - purchase/upgrade entry points with plan cards and route intent hydration
    (`intent=upgrade`, `domain`, `requiredTier`)
  - billing status and recovery actions (`retry payment`, `schedule retry`,
    `update payment method`, recovery notice states)
  - connected-domain state rows
  - account actions (`export`, `sign out all devices`)

## Next App Router Mapping

- `src/navigation/routes.ts` defines typed web route contracts.
- `src/navigation/shells.ts` defines customer/admin shell resolution,
  breadcrumbing, and Studio nav grouping for the web implementation.
- Domain routes support cross-domain back-stack query context (`origin`,
  `stack`).
- Canonical shell/domain routes hydrate deep/shared URL context into supported
  query params (`path`, `q`, `query`, `ref`) before redirecting to app routes.
- Route pages are mapped under:
  - `src/app/explore/page.tsx`
  - `src/app/activity/page.tsx`
  - `src/app/library/page.tsx`
  - `src/app/profile/page.tsx`
  - `src/app/studio/page.tsx`
  - `src/app/studio/design-language/page.tsx`
  - `src/app/studio/typography/page.tsx`
  - `src/app/studio/color-system/page.tsx`
  - `src/app/studio/spacing-layout/page.tsx`
  - `src/app/studio/component-primitives/page.tsx`
  - `src/app/studio/complex-interactions/page.tsx`
  - `src/app/studio/navigation-commands/page.tsx`
  - `src/app/studio/search-discovery/page.tsx`
  - `src/app/studio/cross-domain-entity-model/page.tsx`
  - `src/app/studio/workspace-context-switching/page.tsx`
  - `src/app/studio/multi-project-operations/page.tsx`
  - `src/app/studio/authentication-architecture/page.tsx`
  - `src/app/studio/session-device-management/page.tsx`
  - `src/app/studio/rbac-permission-policy/page.tsx`
  - `src/app/studio/enterprise-tenant-isolation/page.tsx`
  - `src/app/studio/audit-compliance-surfaces/page.tsx`
  - `src/app/studio/notification-center/page.tsx`
  - `src/app/studio/activity-change-feeds/page.tsx`
  - `src/app/studio/real-time-collaboration-substrate/page.tsx`
  - `src/app/studio/presence-cursor-systems/page.tsx`
  - `src/app/studio/commenting-annotation-system/page.tsx`
  - `src/app/studio/review-approval-workflows/page.tsx`
  - `src/app/studio/file-media-ingestion/page.tsx`
  - `src/app/studio/asset-preview-pipeline/page.tsx`
  - `src/app/studio/background-jobs-progress-ux/page.tsx`
  - `src/app/studio/resilience-error-ux/page.tsx`
  - `src/app/domains/[domainId]/page.tsx`
- `src/components/DomainSwitcherEntryPanel.tsx` provides shared home/explore
  domain-switch entry UX.
- `src/design-system/components/DomainSwitcher.tsx` provides the reusable
  domain-switcher primitive consumed by those shell panels.
- `src/design-system/components/ContinuityCard.tsx` provides the reusable
  compact/feature continuity card primitive consumed by the home hero and the
  Library resume lane.
- `src/design-system/components/EvidenceCard.tsx` and
  `src/design-system/components/EvidenceSidebar.tsx` provide reusable grounded
  evidence summary primitives for cards, sidebars, claim timelines, and RAG
  citation panels.
- `src/design-system/components/ClaimListItem.tsx`,
  `src/design-system/components/SourceListItem.tsx`, and
  `src/design-system/components/PassageListItem.tsx` provide reusable claim,
  source, and passage list primitives for Veritas claim/source surfaces and the
  Nisaba study rail.
- `src/design-system/components/NotebookCard.tsx` and
  `src/design-system/components/CollectionCard.tsx` provide reusable notebook
  and collection card primitives for Nisaba notebook launches plus Explore and
  Library collection bundles.
- `src/design-system/components/AssistantDisclosureStrip.tsx` and
  `src/design-system/components/AssistantMemoryState.tsx` provide reusable
  assistant trust-state primitives for the customer assistant panel plus Studio
  avatar/voice disclosure governance previews.
- `src/design-system/components/ProvenanceBadge.tsx` provides the reusable
  provenance badge primitive for Veritas claim cards and reading-queue trust
  indicators plus Studio provenance and watermark governance previews.
- `src/design-system/components/AdminQueueRow.tsx` and
  `src/design-system/components/AdminQueueFilter.tsx` provide reusable operator
  queue-row rails and filter-field wrappers for Studio render queues,
  background-job records, and design-language admin-state previews.
- `src/design-system/components/IncidentSeverityBadge.tsx` and
  `src/design-system/components/SlaTimerPill.tsx` provide reusable severity
  badges and SLA-timer pills for Launch Readiness blockers/incidents, Background
  Jobs escalation context, Bellona queue detail panels, and Studio
  design-language admin-state previews.
- `src/design-system/components/ReviewDecisionControl.tsx` provides a reusable
  review-decision selector for Studio Bellona collaboration approvals, Studio
  review-approval workflow context controls, and Studio design-language review
  governance previews.
- `src/design-system/components/PolicyEditPanel.tsx` and
  `src/design-system/components/PolicyDiffPanel.tsx` provide reusable
  policy-context editing and baseline-vs-current permission diff panels for
  Bellona policy-governed admin workspaces plus Studio design-language
  governance previews.
- `src/components/QuickActionsTrayPanel.tsx` provides shared home/explore
  quick-actions tray UX, with save continuity handed into `/library`.
- `src/design-system/tokens.ts` now adapts the canonical `oshun-v1-foundation`
  bundle from `@oshun/design-tokens` so color, typography, spacing, elevation,
  and motion remain shared rather than redefined inside the app.
- `src/design-system/globals-v2.css` and the shared design-system primitives now
  consume one shell-level domain accent behavior contract so Tara, Arete,
  Veritas, Nyx, and Nisaba keep one restrained identity model inside the same
  shell.
- `src/design-system/grounded-evidence.ts`, `src/design-system/globals-v2.css`,
  `src/components/domains/veritas/VeritasRAG.tsx`, and
  `src/components/domains/veritas/VeritasClaimChecker.tsx` now consume one
  grounded-evidence behavior contract so evidence summaries, status chips,
  citation cards, and quoted passages share the same shell grammar.
- `src/design-system/disclosure.ts`, `src/design-system/globals-v2.css`,
  `src/components/assistant/AssistantPanel.tsx`,
  `src/components/studio/StudioAjaAvatarPreviewUiWorkspace.tsx`, and
  `src/components/studio/StudioIsisTextToSpeechWorkspace.tsx` now consume one
  disclosure-and-synthetic-indicator behavior contract so AI identity, memory
  scope, and synthetic voice/avatar states stay explicit across customer and
  operator surfaces.
- `src/design-system/assistant-persona-switching.ts`,
  `src/design-system/globals-v2.css`,
  `src/components/assistant/AssistantPanel.tsx`,
  `src/components/studio/StudioDesignLanguageWorkspace.tsx`, and
  `src/components/studio/StudioIsisTextToSpeechWorkspace.tsx` now consume one
  assistant-persona-switching behavior contract so the active persona,
  domain-aware recommendations, preview/restricted states, and continuity notes
  follow one explicit shell grammar instead of being implied or hidden inside
  settings.
- `src/design-system/avatar-voice-identity.ts`,
  `src/design-system/globals-v2.css`,
  `src/components/assistant/AssistantPanel.tsx`,
  `src/components/studio/StudioDesignLanguageWorkspace.tsx`,
  `src/components/studio/StudioIsisTextToSpeechWorkspace.tsx`, and
  `src/components/studio/StudioAjaAvatarPreviewUiWorkspace.tsx` now consume one
  avatar-and-voice-identity behavior contract so named voice profiles and avatar
  packs, their linked personas, live/preview/partial/blocked states, and lineage
  notes follow one explicit shell grammar instead of disappearing into settings
  or secondary inspectors.
- `src/design-system/components/AvatarVoicePackCard.tsx` provides reusable
  avatar-pack and voice-pack identity cards for Studio design-language previews
  plus the Isis text-to-speech and Aja avatar preview workspaces, so those
  surfaces reuse one asset-card layout instead of reimplementing identity,
  readiness, metadata, and lineage details inline.
- `src/design-system/rights-license-summary.ts` and
  `src/design-system/components/RightsLicenseSummaryCard.tsx` provide reusable
  rights-summary and license-summary cards for Studio design-language previews
  plus the Isis text-to-speech and Aja avatar preview workspaces, so consent
  posture, distribution scope, restrictions, and renewal timing stay adjacent to
  named voice/avatar assets instead of disappearing into route-local copy.
- `src/design-system/review-approval-states.ts`,
  `src/design-system/globals-v2.css`,
  `src/components/studio/StudioDesignLanguageWorkspace.tsx`,
  `src/components/studio/StudioReviewApprovalWorkflowsWorkspace.tsx`, and
  `src/components/studio/StudioBellonaRenderQueueManagementWorkspace.tsx` now
  consume one review-and-approval behavior contract so pending/in-review
  posture, approved/changes-requested/rejected decisions, escalations, approved
  exceptions, and adjacent governance evidence follow one explicit Studio
  grammar instead of local badge variants.
- `src/design-system/trust-signals.ts`, `src/design-system/globals-v2.css`,
  `src/components/domains/VeritasSurface.tsx`,
  `src/components/domains/veritas/VeritasReadingQueue.tsx`,
  `src/components/studio/StudioIsisProvenanceTrackingWorkspace.tsx`, and
  `src/components/studio/StudioAjaContentWatermarkingWorkspace.tsx` now consume
  one trust-signal behavior contract so confidence, provenance, and watermark
  badges stay explicit without conflating source lineage with factual certainty.
- `src/design-system/admin-states.ts`, `src/design-system/globals-v2.css`,
  `src/components/studio/StudioLaunchReadinessGovernanceDashboard.tsx`,
  `src/components/studio/StudioBellonaRenderQueueManagementWorkspace.tsx`,
  `src/components/studio/StudioBackgroundJobsProgressUxWorkspace.tsx`, and
  `src/components/studio/StudioDesignLanguageWorkspace.tsx` now consume one
  admin-state behavior contract so severity, queue posture, escalation timers,
  and operator-facing rails/badges follow one dense operational grammar instead
  of being styled locally per workspace.
- `src/app/library/page.tsx` and `src/components/library/LibraryDashboard.tsx`
  provide the canonical web library surface for saved items, collections, resume
  points, and assistant excerpts.
- `src/navigation/research-practice-journey.ts` maps the canonical
  research-to-practice journey into concrete Library, Veritas, Nisaba, Tara,
  Arete, and assistant handoff actions.
- `src/components/library/ResearchPracticeJourneyRail.tsx` renders the canonical
  Library research-to-practice rail so grounded study visibly hands off into
  practice and durable save points.
- `src/navigation/story-source-journey.ts` maps the canonical story-to-source
  journey into contextual Veritas, Nisaba, Sophia-backed source trail, and
  Library handoff actions.
- `src/components/domains/veritas/StorySourceJourneyRail.tsx` renders the
  canonical story-to-source rail inside the Veritas article reader so current
  reporting can open into citations, lineage, related texts, and notebooks.
- `src/navigation/sky-text-journey.ts` maps the canonical sky-to-text journey
  into contextual Nyx, Nisaba, and Library handoff actions.
- `src/components/domains/nyx/SkyTextJourneyRail.tsx` renders the canonical
  sky-to-text rail inside the Nyx celestial calendar so sky events can open into
  cosmology passages, calendar sources, comparative texts, and notebooks.
- `src/navigation/assistant-continuity-journey.ts` maps the canonical
  assistant-led continuity journey into seeded assistant asks, return-to-surface
  routes, Activity follow-up, and Library assistant-memory preservation.
- `src/components/assistant/AssistantContinuityJourneyRail.tsx` renders the
  canonical assistant continuity rail inside the global assistant panel so entry
  context, grounded brief shaping, and preserve routes stay visible while the
  user is still in the assistant flow.
- `src/components/assistant/AssistantPanel.tsx` now also renders a persistent
  disclosure strip so AI identity, active memory scope, and synthetic voice
  state remain visible throughout the assistant flow.
- `src/navigation/assistant-entry.ts` provides the shared assistant-invocation
  event contract so assistant entry remains a global layer rather than a peer
  shell route.
- `src/navigation/daypart-journeys.ts` maps the shared morning/midday/evening
  journey contract into concrete web links and assistant entry actions.
- `src/components/home/DaypartJourneyRail.tsx` renders the canonical home
  continuity rail for morning anchoring, midday recovery, and evening closure.
- `src/components/OperatorAccessPanel.tsx` and
  `docs/adr/ADR-0057-oshun-customer-admin-shell-relationship-model.md` define
  the explicit customer/admin shell handoff and boundary rule.
- `src/components/studio/StudioInformationArchitectureWorkspace.tsx` provides
  Studio IA execution flows with optimistic and explicit error/retry states.
- `src/components/studio/StudioDesignLanguageWorkspace.tsx` provides Studio
  visual identity governance flows for token publish, domain identity sync,
  accessibility certification, and live inspection of the canonical V1
  foundation bundle.
- `src/components/studio/StudioTypographyWorkspace.tsx` provides Studio
  typography governance flows for bundle publish, readability validation, and
  domain parity sync.
- `src/components/studio/StudioColorSystemWorkspace.tsx` provides Studio
  color-system governance flows for bundle publish, contrast validation, and
  domain parity synchronization.
- `src/components/studio/StudioSpacingLayoutWorkspace.tsx` provides Studio
  spacing/layout governance flows for bundle publish, density validation, and
  grid parity synchronization.
- `src/components/studio/StudioComponentPrimitivesWorkspace.tsx` provides Studio
  component-primitives governance flows for bundle publish, composition
  validation, and domain parity synchronization.
- `src/components/studio/StudioComplexInteractionPatternsWorkspace.tsx` provides
  Studio complex-interaction governance flows for orchestration bundle publish,
  transition/recovery validation, and domain parity synchronization.
- `src/components/studio/StudioNavigationCommandWorkspace.tsx` provides Studio
  navigation/command governance flows for command-catalog publish, route-context
  validation, and cross-domain navigation synchronization.
- `src/components/studio/StudioSearchDiscoveryWorkspace.tsx` provides Studio
  search/discovery governance flows for discovery-index publish, relevance
  calibration, and cross-domain parity synchronization.
- `src/components/studio/StudioCrossDomainEntityModelWorkspace.tsx` provides
  Studio cross-domain entity-model governance flows for canonical envelope
  publish, entity-resolution validation, and relation-graph synchronization.
- `src/components/studio/StudioWorkspaceContextSwitchingWorkspace.tsx` provides
  Studio workspace context-switching governance flows for switch-commit
  execution, continuity validation, and rollback recovery drills.
- `src/components/studio/StudioMultiProjectOperationsWorkspace.tsx` provides
  Studio multi-project-operations governance flows for operation-baseline
  publish, readiness-stage start, and rollback-orchestration recovery.
- `src/components/studio/StudioAuthenticationArchitectureWorkspace.tsx` provides
  Studio authentication-architecture governance flows for auth-context
  validation, step-up challenge execution, and privileged action grants.
- `src/components/studio/StudioSessionDeviceManagementWorkspace.tsx` provides
  Studio session/device-management governance flows for session inventory sync,
  trusted-device enrollment, and session revocation execution.
- `src/components/studio/StudioRbacPermissionPolicyUxWorkspace.tsx` provides
  Studio RBAC/permission-policy UX governance flows for role-catalog sync,
  policy-decision simulation, and deny-guidance publishing.
- `src/components/studio/StudioEnterpriseTenantIsolationWorkspace.tsx` provides
  Studio enterprise tenant-isolation governance flows for tenant-context
  validation, boundary-policy simulation, and cross-tenant exception review.
- `src/components/studio/StudioAuditComplianceSurfacesWorkspace.tsx` provides
  Studio audit/compliance governance flows for evidence-query execution,
  compliance-review decisions, and retention-policy verification.
- `src/components/studio/StudioNotificationCenterWorkspace.tsx` provides Studio
  notification-center governance flows for feed triage, assignment transitions,
  closure workflows, critical escalation routing, and deduplication integrity
  review.
- `src/components/studio/StudioActivityChangeFeedsWorkspace.tsx` provides Studio
  activity/change-feed governance flows for timeline triage, actor-attribution
  verification, cursor replay reconstruction, follow-up routing, and compliance
  export packaging.
- `src/components/studio/StudioRealTimeCollaborationSubstrateWorkspace.tsx`
  provides Studio real-time collaboration-substrate governance flows for session
  join/capability handshake, live multi-actor editing, conflict resolution
  orchestration, disconnect replay recovery, and governance evidence export.
- `src/components/studio/StudioPresenceCursorSystemsWorkspace.tsx` provides
  Studio presence/cursor governance flows for presence session join, liveness
  transition orchestration, cursor progression execution, replay/resume
  recovery, and governance visibility review.
- `src/components/studio/StudioCommentingAnnotationSystemWorkspace.tsx` provides
  Studio commenting/annotation governance flows for context-bound annotation
  creation, thread reply expansion, lifecycle acknowledge/resolve/reopen
  transitions, and moderation governance review.
- `src/components/studio/StudioReviewApprovalWorkflowsWorkspace.tsx` provides
  Studio review/approval governance flows for review package submission, stage
  assignment orchestration, decision lifecycle execution, delegation/escalation
  routing, and governance closure export.
- `src/components/studio/StudioFileMediaIngestionWorkspace.tsx` provides Studio
  file/media ingestion governance flows for ingestion envelope submission,
  validation gate execution, processing lifecycle progression, failure recovery,
  and governance evidence export.
- `src/components/studio/StudioAssetPreviewPipelineWorkspace.tsx` provides
  Studio asset preview governance flows for preview request intake, rendering
  lifecycle orchestration, fidelity fallback execution, cache invalidation
  refresh, and governance evidence export.
- `src/components/studio/StudioBackgroundJobsProgressUxWorkspace.tsx` provides
  Studio background-job governance flows for job envelope submission, progress
  heartbeat streaming, control-action execution, recovery orchestration, and
  governance closure export.
- `src/components/studio/StudioResilienceErrorUxWorkspace.tsx` provides Studio
  resilience/error governance flows for canonical error capture/classification,
  guided recovery execution, degraded-mode transitions, escalation routing, and
  governance closure export.
- Color flow telemetry (`studio_color_flow_requested`,
  `studio_color_flow_completed`, `studio_color_audit_event`) is emitted via
  `src/analytics/studioColorSystemTelemetry.ts`.
- Typography flow telemetry (`studio_typography_flow_requested`,
  `studio_typography_flow_completed`, `studio_typography_audit_event`) is
  emitted via `src/analytics/studioTypographyTelemetry.ts`.
- Spacing/layout flow telemetry (`studio_spacing_flow_requested`,
  `studio_spacing_flow_completed`, `studio_spacing_audit_event`) is emitted via
  `src/analytics/studioSpacingLayoutTelemetry.ts`.
- Component-primitives flow telemetry
  (`studio_component_primitives_flow_requested`,
  `studio_component_primitives_flow_completed`,
  `studio_component_primitives_audit_event`) is emitted via
  `src/analytics/studioComponentPrimitivesTelemetry.ts`.
- Complex-interactions flow telemetry
  (`studio_complex_interactions_flow_requested`,
  `studio_complex_interactions_flow_completed`,
  `studio_complex_interactions_audit_event`) is emitted via
  `src/analytics/studioComplexInteractionsTelemetry.ts`.
- Navigation/command flow telemetry (`studio_navigation_command_flow_requested`,
  `studio_navigation_command_flow_completed`,
  `studio_navigation_command_audit_event`) is emitted via
  `src/analytics/studioNavigationCommandTelemetry.ts`.
- Search/discovery flow telemetry (`studio_search_discovery_flow_requested`,
  `studio_search_discovery_flow_completed`,
  `studio_search_discovery_audit_event`) is emitted via
  `src/analytics/studioSearchDiscoveryTelemetry.ts`.
- Cross-domain entity-model flow telemetry
  (`studio_cross_domain_entity_model_flow_requested`,
  `studio_cross_domain_entity_model_flow_completed`,
  `studio_cross_domain_entity_model_audit_event`) is emitted via
  `src/analytics/studioCrossDomainEntityModelTelemetry.ts`.
- Workspace context-switching flow telemetry
  (`studio_workspace_context_switching_flow_requested`,
  `studio_workspace_context_switching_flow_completed`,
  `studio_workspace_context_switching_audit_event`) is emitted via
  `src/analytics/studioWorkspaceContextSwitchingTelemetry.ts`.
- Multi-project operations flow telemetry
  (`studio_multi_project_operations_flow_requested`,
  `studio_multi_project_operations_flow_completed`,
  `studio_multi_project_operations_audit_event`) is emitted via
  `src/analytics/studioMultiProjectOperationsTelemetry.ts`.
- Authentication architecture flow telemetry
  (`studio_authentication_architecture_flow_requested`,
  `studio_authentication_architecture_flow_completed`,
  `studio_authentication_architecture_audit_event`) is emitted via
  `src/analytics/studioAuthenticationArchitectureTelemetry.ts`.
- Session/device management flow telemetry
  (`studio_session_device_management_flow_requested`,
  `studio_session_device_management_flow_completed`,
  `studio_session_device_management_audit_event`) is emitted via
  `src/analytics/studioSessionDeviceManagementTelemetry.ts`.
- RBAC/permission-policy UX flow telemetry
  (`studio_rbac_permission_policy_ux_flow_requested`,
  `studio_rbac_permission_policy_ux_flow_completed`,
  `studio_rbac_permission_policy_ux_audit_event`) is emitted via
  `src/analytics/studioRbacPermissionPolicyUxTelemetry.ts`.
- Enterprise tenant-isolation flow telemetry
  (`studio_enterprise_tenant_isolation_flow_requested`,
  `studio_enterprise_tenant_isolation_flow_completed`,
  `studio_enterprise_tenant_isolation_audit_event`) is emitted via
  `src/analytics/studioEnterpriseTenantIsolationTelemetry.ts`.
- Audit/compliance surfaces flow telemetry
  (`studio_audit_compliance_surfaces_flow_requested`,
  `studio_audit_compliance_surfaces_flow_completed`,
  `studio_audit_compliance_surfaces_audit_event`) is emitted via
  `src/analytics/studioAuditComplianceSurfacesTelemetry.ts`.
- Notification-center flow telemetry
  (`studio_notification_center_flow_requested`,
  `studio_notification_center_flow_completed`,
  `studio_notification_center_audit_event`) is emitted via
  `src/analytics/studioNotificationCenterTelemetry.ts`.
- Activity/change-feeds flow telemetry
  (`studio_activity_change_feeds_flow_requested`,
  `studio_activity_change_feeds_flow_completed`,
  `studio_activity_change_feeds_audit_event`) is emitted via
  `src/analytics/studioActivityChangeFeedsTelemetry.ts`.
- Real-time collaboration-substrate flow telemetry
  (`studio_realtime_collaboration_substrate_flow_requested`,
  `studio_realtime_collaboration_substrate_flow_completed`,
  `studio_realtime_collaboration_substrate_audit_event`) is emitted via
  `src/analytics/studioRealTimeCollaborationSubstrateTelemetry.ts`.
- Presence/cursor systems flow telemetry
  (`studio_presence_cursor_systems_flow_requested`,
  `studio_presence_cursor_systems_flow_completed`,
  `studio_presence_cursor_systems_audit_event`) is emitted via
  `src/analytics/studioPresenceCursorSystemsTelemetry.ts`.
- Commenting/annotation system flow telemetry
  (`studio_commenting_annotation_system_flow_requested`,
  `studio_commenting_annotation_system_flow_completed`,
  `studio_commenting_annotation_system_audit_event`) is emitted via
  `src/analytics/studioCommentingAnnotationSystemTelemetry.ts`.
- Review/approval workflows flow telemetry
  (`studio_review_approval_workflows_flow_requested`,
  `studio_review_approval_workflows_flow_completed`,
  `studio_review_approval_workflows_audit_event`) is emitted via
  `src/analytics/studioReviewApprovalWorkflowsTelemetry.ts`.
- File/media ingestion flow telemetry
  (`studio_file_media_ingestion_flow_requested`,
  `studio_file_media_ingestion_flow_completed`,
  `studio_file_media_ingestion_audit_event`) is emitted via
  `src/analytics/studioFileMediaIngestionTelemetry.ts`.
- Asset preview pipeline flow telemetry
  (`studio_asset_preview_pipeline_flow_requested`,
  `studio_asset_preview_pipeline_flow_completed`,
  `studio_asset_preview_pipeline_audit_event`) is emitted via
  `src/analytics/studioAssetPreviewPipelineTelemetry.ts`.
- Background jobs/progress UX flow telemetry
  (`studio_background_jobs_progress_ux_flow_requested`,
  `studio_background_jobs_progress_ux_flow_completed`,
  `studio_background_jobs_progress_ux_audit_event`) is emitted via
  `src/analytics/studioBackgroundJobsProgressUxTelemetry.ts`.
- Resilience/error UX flow telemetry
  (`studio_resilience_error_ux_flow_requested`,
  `studio_resilience_error_ux_flow_completed`,
  `studio_resilience_error_ux_audit_event`) is emitted via
  `src/analytics/studioResilienceErrorUxTelemetry.ts`.
- `docs/studio-ia-validation.md` maps integration/e2e/accessibility/performance
  validation evidence for Studio IA flows.
- `docs/studio-design-language-validation.md` maps
  integration/e2e/accessibility/performance validation evidence for Studio
  design-language flows.
- `docs/studio-typography-validation.md` maps
  integration/e2e/accessibility/performance validation evidence for Studio
  typography flows.
- `docs/studio-color-system-validation.md` maps
  integration/e2e/accessibility/performance validation evidence for Studio
  color-system flows.
- `docs/studio-spacing-layout-validation.md` maps
  integration/e2e/accessibility/performance validation evidence for Studio
  spacing/layout flows.
- `docs/studio-component-primitives-validation.md` maps
  integration/e2e/accessibility/performance validation evidence for Studio
  component-primitives flows.
- `docs/studio-complex-interactions-validation.md` maps
  integration/e2e/accessibility/performance validation evidence for Studio
  complex-interaction flows.
- `docs/studio-navigation-commands-validation.md` maps
  integration/e2e/accessibility/performance validation evidence for Studio
  navigation/command flows.
- `docs/studio-search-discovery-validation.md` maps
  integration/e2e/accessibility/performance validation evidence for Studio
  search/discovery flows.
- `docs/studio-cross-domain-entity-model-validation.md` maps
  integration/e2e/accessibility/performance validation evidence for Studio
  cross-domain entity-model flows.
- `docs/studio-workspace-context-switching-validation.md` maps
  integration/e2e/accessibility/performance validation evidence for Studio
  workspace context-switching flows.
- `docs/studio-multi-project-operations-validation.md` maps
  integration/e2e/accessibility/performance validation evidence for Studio
  multi-project operations flows.
- `docs/studio-authentication-architecture-validation.md` maps
  integration/e2e/accessibility/performance validation evidence for Studio
  authentication architecture flows.
- `docs/studio-session-device-management-validation.md` maps
  integration/e2e/accessibility/performance validation evidence for Studio
  session/device management flows.
- `docs/studio-rbac-permission-policy-validation.md` maps
  integration/e2e/accessibility/performance validation evidence for Studio
  RBAC/permission-policy UX flows.
- `docs/studio-enterprise-tenant-isolation-validation.md` maps
  integration/e2e/accessibility/performance validation evidence for Studio
  enterprise tenant-isolation flows.
- `docs/studio-audit-compliance-surfaces-validation.md` maps
  integration/e2e/accessibility/performance validation evidence for Studio
  audit/compliance surfaces flows.
- `docs/studio-notification-center-validation.md` maps
  integration/e2e/accessibility/performance validation evidence for Studio
  notification-center flows.
- `docs/studio-activity-change-feeds-validation.md` maps
  integration/e2e/accessibility/performance validation evidence for Studio
  activity/change-feeds flows.
- `docs/studio-realtime-collaboration-substrate-validation.md` maps
  integration/e2e/accessibility/performance validation evidence for Studio
  real-time collaboration-substrate flows.
- `docs/studio-presence-cursor-systems-validation.md` maps
  integration/e2e/accessibility/performance validation evidence for Studio
  presence/cursor systems flows.
- `docs/studio-commenting-annotation-system-validation.md` maps
  integration/e2e/accessibility/performance validation evidence for Studio
  commenting/annotation system flows.
- `docs/studio-review-approval-workflows-validation.md` maps
  integration/e2e/accessibility/performance validation evidence for Studio
  review/approval workflows.
- `docs/studio-file-media-ingestion-validation.md` maps
  integration/e2e/accessibility/performance validation evidence for Studio
  file/media ingestion workflows.
- `docs/studio-asset-preview-pipeline-validation.md` maps
  integration/e2e/accessibility/performance validation evidence for Studio asset
  preview pipeline workflows.
- `docs/studio-background-jobs-progress-ux-validation.md` maps
  integration/e2e/accessibility/performance validation evidence for Studio
  background jobs/progress UX workflows.
- `docs/studio-resilience-error-ux-validation.md` maps
  integration/e2e/accessibility/performance validation evidence for Studio
  resilience/error UX workflows.
- `src/components/DomainStartupGate.tsx` provides domain module startup skeleton
  loading UX.
- `src/components/DomainRouteExperience.tsx` now enforces shell-side entitlement
  middleware checks from shared profile state (`@oshun/auth-client`), including
  deny states and upgrade/back routing.
- `src/app/domains/[domainId]/page.tsx` includes graceful domain-unavailable
  fallback UI (`unavailable`, `reason` query support).
- `src/app/domains/[domainId]/page.tsx` also includes per-domain offline
  fallback cards (`offline` query support).
- Domain launch telemetry (`domain_launch_requested`, `domain_launch_completed`,
  latency + success) is emitted via:
  - `src/analytics/domainLaunchTelemetry.ts`
  - `src/components/DomainStartupGate.tsx`
  - `src/components/DomainLaunchFailureTelemetry.tsx`
- Canonical HTTPS compatibility routes:
  - `src/app/app/[surface]/[[...path]]/page.tsx` (`/app/{surface}`)
  - `src/app/d/[domain]/[[...path]]/page.tsx` (`/d/{domain}/{path}`)