# OSHUN Implementation Guide

Status: Active Owner: OSHUN Engineering Last Updated: March 23, 2026 Related:
`OSHUN_APP_TODOS.md`, `docs/releases/v1/specs/program-charter.md`,
`docs/releases/v1/specs/web-app-admin-v1-prd.md`,
`docs/releases/v1/specs/product-brief.md`, `docs/releases/v1/scope/mvp-scope.md`

## 1. Purpose

This document is the execution entrypoint for the OSHUN shell workstream:

- Mobile shell (`apps/oshun/mobile`)
- Web + PWA shell (`apps/oshun/web`)
- BFF aggregator (`apps/oshun/bff`)
- Shared OSHUN platform libraries (`libs/oshun/*`)

It provides a project map plus command references for local development and
autonomous agent execution.

The project inventory below reflects the current repository implementation. The
canonical OSHUN V1 target model is defined by
`docs/releases/v1/specs/program-charter.md` and includes the March 23, 2026
Metis corrective scope even where shell implementation work is still incomplete.

## 2. Project Map

### 2.1 Applications

| Nx Project      | Path                | Role                                                |
| --------------- | ------------------- | --------------------------------------------------- |
| `@oshun/mobile` | `apps/oshun/mobile` | Expo Router shell for iOS/Android (+ web preview)   |
| `@oshun/web`    | `apps/oshun/web`    | Next.js site and installable PWA surface            |
| `@oshun/bff`    | `apps/oshun/bff`    | Fastify backend-for-frontend for unified shell APIs |

### 2.2 Shared Libraries

| Nx Project               | Path                         | Role                                              |
| ------------------------ | ---------------------------- | ------------------------------------------------- |
| `@oshun/ui`              | `libs/oshun/ui`              | Shared UI primitives and theme bindings           |
| `@oshun/design-tokens`   | `libs/oshun/design-tokens`   | Design tokens and semantic theme definitions      |
| `@oshun/navigation`      | `libs/oshun/navigation`      | Typed routes, deep-link and web-link helpers      |
| `@oshun/auth-client`     | `libs/oshun/auth`            | Shared auth/session client abstractions           |
| `@oshun/analytics`       | `libs/oshun/analytics`       | Typed analytics contracts and sink APIs           |
| `@oshun/domain-registry` | `libs/oshun/domain-registry` | Tara/Veritas/Nyx/Arete metadata + launch links    |
| `@oshun/domain-tara`     | `libs/oshun/domain-tara`     | Tara domain API adapter contracts + typed client  |
| `@oshun/offline`         | `libs/oshun/offline`         | Offline cache, queue, retry, connectivity helpers |

### 2.3 OSHUN Documentation Map

- Documentation standards: `docs/releases/v1/specs/documentation-standards.md`
- Domain remediation checklist:
  `docs/releases/v1/reports/domain-doc-remediation-checklist.md`
- Domain reference index: `docs/releases/v1/domains/README.md`
- Per-domain Oshun-local folders:
  `docs/releases/v1/domains/<domain>/{README.md,feature-inventory.md,implementation-map.md}`
- Canonical V1 program framing: `docs/releases/v1/specs/program-charter.md`
- Metis corrective-scope report:
  `docs/releases/v1/reports/metis-domain-gap-analysis-and-full-integration-report-2026-03-23.md`
- Canonical V1 PRD: `docs/releases/v1/specs/web-app-admin-v1-prd.md`
- Current V1 ownership boundaries:
  `docs/releases/v1/reports/subsystem-ownership-matrix.md`, plus
  `docs/releases/v1/specs/program-charter.md` section 3.3 and
  `docs/releases/v1/specs/web-app-admin-v1-prd.md` section 16
- Current V1 subsystem call-routing guide:
  `docs/releases/v1/specs/when-to-call-which-subsystem-guide.md`
- Current V1 standalone-domain consolidation strategy:
  `docs/releases/v1/specs/domain-service-consolidation-strategy.md`
- Current V1 domain-service routing and discovery rules:
  `docs/releases/v1/scope/domain-service-routing-and-discovery-rules.md`
- Current V1 domain-service health, readiness, and circuit-breaker conventions:
  `docs/releases/v1/specs/domain-service-health-readiness-and-circuit-breaker-conventions.md`
- Current V1 contract-to-Prisma alignment audit and authoritative ownership map:
  `docs/releases/v1/audits/cross-cutting/contract/to-prisma-alignment.md`
- Current V1 canonical contract index and query-pattern requirements:
  `docs/releases/v1/specs/canonical-contract-index-and-query-requirements.md`
- Current V1 standalone-frontend deprecation and sunset criteria:
  `docs/releases/v1/specs/standalone-frontend-deprecation-and-sunset-criteria.md`
- Current V1 standalone-domain backend-only compatibility audit:
  - Current V1 public-web and app-distribution tracker:
    `docs/releases/v1/specs/public-web-and-app-distribution-tracking.md`
- Current V1 in-memory runtime-state audit:
  `docs/releases/v1/audits/cross-cutting/in/memory-runtime-state.md`
- Current V1 in-memory runtime-state classification:
  `docs/releases/v1/specs/in-memory-runtime-state-classification.md`
- Current V1 release-blocker replacement plans:
  `docs/releases/v1/specs/release-blocking-in-memory-state-replacement-plans.md`
- Legacy cross-domain ownership snapshot:
  `docs/reference/data-ownership-matrix.md` (historical migration context only;
  not the authoritative V1 ownership source)
- Product framing (historical MVP baseline):
  `docs/releases/v1/specs/product-brief.md`
- Brand system: `docs/releases/v1/design/brand-system.md`
- Customer visual thesis: `docs/releases/v1/design/customer-visual-thesis.md`
- Admin visual thesis: `docs/releases/v1/design/admin-visual-thesis.md`
- Current-state redesign inventory:
  `docs/releases/v1/reports/current-state-redesign-inventory.md`
- Surface redesign ranking: `docs/releases/v1/specs/surface-redesign-ranking.md`
- Experience scorecards: `docs/releases/v1/specs/experience-scorecards.md`
- Metis readiness scorecard: `docs/releases/v1/reports/metis-v1-scorecard.md`
- Metis workstream tracking:
  `docs/releases/v1/reports/metis-v1-workstream-tracking.md`
- Metis mobile strategy: `docs/releases/v1/specs/metis-mobile-strategy.md`
- Metis operator workflows runbook:
  `docs/releases/v1/runbooks/metis-operator-workflows-runbook.md`
- Metis generation and tutoring SLOs:
  `docs/releases/v1/specs/metis-generation-and-tutoring-slos.md`
- Metis media and runtime tiers:
  `docs/releases/v1/specs/metis-media-runtime-tiers.md`
- Metis persistence, migration, and backfill plan:
  `docs/releases/v1/specs/metis-persistence-migration-backfill-plan.md`
- Metis `LearningSourceBundle` contract:
  `docs/releases/v1/specs/metis-learning-source-bundle-contract.md`
- Metis `GroundingPack` contract:
  `docs/releases/v1/specs/metis-grounding-pack-contract.md`
- Metis `CourseBuild` contract:
  `docs/releases/v1/specs/metis-course-build-contract.md`
- Metis `LessonAssetBundle` contract:
  `docs/releases/v1/specs/metis-lesson-asset-bundle-contract.md`
- Metis `PublicationPackage` contract:
  `docs/releases/v1/specs/metis-publication-package-contract.md`
- Metis `AvatarTeacherProfile` contract:
  `docs/releases/v1/specs/metis-avatar-teacher-profile-contract.md`
- Metis `VoiceLikenessConsentRecord` contract:
  `docs/releases/v1/specs/metis-voice-likeness-consent-record-contract.md`
- Metis canonical OpenAPI artifact: `services/metis/openapi/metis.openapi.json`
- Metis generated TypeScript OpenAPI surface:
  `libs/openapi/src/generated/metis.ts`
- Minimal chrome rules: `docs/releases/v1/scope/minimal-chrome-rules.md`
- Layout density tiers: `docs/releases/v1/specs/layout-density-tiers.md`
- Scan-first content hierarchy rules:
  `docs/releases/v1/scope/scan-first-content-hierarchy-rules.md`
- Ergonomic budgets: `docs/releases/v1/specs/ergonomic-budgets.md`
- Immersive vs utilitarian posture rules:
  `docs/releases/v1/scope/immersive-vs-utilitarian-posture-rules.md`
- Redesign sequencing plan: `docs/releases/v1/specs/redesign-sequencing-plan.md`
- Partial failure and degraded mode rules:
  `docs/releases/v1/scope/partial-failure-and-degraded-mode-rules.md`
- Grid, gutter, and max-width rules:
  `docs/releases/v1/scope/grid-gutter-max-width-rules.md`
- Typography measure, line-length, and reading-rhythm rules:
  `docs/releases/v1/scope/typography-measure-line-length-reading-rhythm-rules.md`
- Imagery, illustration, texture, and ambient-media rules:
  `docs/releases/v1/scope/imagery-illustration-texture-ambient-media-rules.md`
- Card-avoidance rules: `docs/releases/v1/scope/card-avoidance-rules.md`
- Motion hierarchy rules: `docs/releases/v1/scope/motion-hierarchy-rules.md`
- Reduced-motion behavior rules:
  `docs/releases/v1/scope/reduced-motion-behavior-rules.md`
- Canonical loading, skeleton, empty, offline, and error-state rules:
  `docs/releases/v1/scope/canonical-loading-skeleton-empty-offline-error-state-rules.md`
- Action-placement rules: `docs/releases/v1/scope/action-placement-rules.md`
- Interaction-feedback rules:
  `docs/releases/v1/scope/interaction-feedback-rules.md`
- Shared component accessibility standards:
  `docs/releases/v1/specs/shared-component-accessibility-standards.md`
- Tara content tone standards:
  `docs/releases/v1/specs/tara-content-tone-standards.md`
- Veritas content tone standards:
  `docs/releases/v1/specs/veritas-content-tone-standards.md`
- Nisaba content tone standards:
  `docs/releases/v1/specs/nisaba-content-tone-standards.md`
- AI disclosure copy guidance:
  `docs/releases/v1/design/ai-disclosure-copy-guidance.md`
- Error, outage, and fallback copy guidance:
  `docs/releases/v1/design/error-outage-and-fallback-copy-guidance.md`
- One-handed mobile ergonomic rules:
  `docs/releases/v1/scope/one-handed-mobile-ergonomic-rules.md`
- Dense-data admin ergonomic rules:
  `docs/releases/v1/scope/dense-data-admin-ergonomic-rules.md`
- Form-entry ergonomic rules:
  `docs/releases/v1/scope/form-entry-ergonomic-rules.md`
- Copy-compression rules: `docs/releases/v1/scope/copy-compression-rules.md`
- Contrast and focus-indicator rules:
  `docs/releases/v1/scope/contrast-and-focus-indicator-rules.md`
- One-handed reachability audit:
  - Visual rhythm and notification density audit:
    `docs/releases/v1/audits/visual/rhythm-notification-density.md`
- Keyboard and focus-path audit:
  `docs/releases/v1/audits/keyboard/and-focus-path.md`
- Dashboard-card sprawl audit:
  - Long-form readability audit:
  - MVP boundary: `docs/releases/v1/scope/mvp-scope.md`
- Post-MVP scope: `docs/releases/v1/specs/post-mvp-scope.md`
- UX principles: `docs/releases/v1/design/ux-principles.md`
- Motion language: `docs/releases/v1/design/motion-language.md`
- Android FPS validation:
  `docs/releases/v1/runbooks/android-60fps-validation.md`
- Readability standards: `docs/releases/v1/design/readability-standards.md`
- Metrics taxonomy: `docs/releases/v1/reports/metrics.md`
- Entitlement schema: `docs/releases/v1/specs/entitlement-schema.md`
- Certificate pinning strategy:
  `docs/releases/v1/runbooks/certificate-pinning-strategy.md`
- Search ranking strategy: `docs/releases/v1/specs/search-ranking-strategy.md`
- Notification deduplication strategy:
  `docs/releases/v1/runbooks/notification-deduplication-strategy.md`
- Studio dependency and data contracts:
  `docs/releases/v1/specs/studio-domain-dependency-and-data-contract-map.md`
- Studio IA journeys and edge cases:
  `docs/releases/v1/specs/studio-ia-user-journeys-and-edge-cases.md`
- Studio IA runbook and ownership:
  `docs/releases/v1/runbooks/studio-ia-runbook.md`
- Studio design language dependency and data contracts:
  `docs/releases/v1/specs/studio-design-language-dependency-and-data-contract-map.md`
- Studio design language journeys and edge cases:
  `docs/releases/v1/specs/studio-design-language-user-journeys-and-edge-cases.md`
- Studio design language runbook and ownership:
  `docs/releases/v1/runbooks/studio-design-language-runbook.md`
- Studio typography dependency and data contracts:
  `docs/releases/v1/specs/studio-typography-dependency-and-data-contract-map.md`
- Studio typography journeys and edge cases:
  `docs/releases/v1/specs/studio-typography-user-journeys-and-edge-cases.md`
- Studio typography runbook and ownership:
  `docs/releases/v1/runbooks/studio-typography-runbook.md`
- Studio color-system dependency and data contracts:
  `docs/releases/v1/specs/studio-color-system-dependency-and-data-contract-map.md`
- Studio color-system journeys and edge cases:
  `docs/releases/v1/specs/studio-color-system-user-journeys-and-edge-cases.md`
- Studio color-system runbook and ownership:
  `docs/releases/v1/runbooks/studio-color-system-runbook.md`
- Studio spacing/layout dependency and data contracts:
  `docs/releases/v1/specs/studio-spacing-layout-dependency-and-data-contract-map.md`
- Studio spacing/layout journeys and edge cases:
  `docs/releases/v1/specs/studio-spacing-layout-user-journeys-and-edge-cases.md`
- Studio spacing/layout runbook and ownership:
  `docs/releases/v1/runbooks/studio-spacing-layout-runbook.md`
- Studio component-primitives dependency and data contracts:
  `docs/releases/v1/specs/studio-component-primitives-dependency-and-data-contract-map.md`
- Studio component-primitives journeys and edge cases:
  `docs/releases/v1/specs/studio-component-primitives-user-journeys-and-edge-cases.md`
- Studio component-primitives runbook and ownership:
  `docs/releases/v1/runbooks/studio-component-primitives-runbook.md`
- Studio complex-interaction dependency and data contracts:
  `docs/releases/v1/specs/studio-complex-interaction-patterns-dependency-and-data-contract-map.md`
- Studio complex-interaction journeys and edge cases:
  `docs/releases/v1/specs/studio-complex-interaction-patterns-user-journeys-and-edge-cases.md`
- Studio complex-interaction runbook and ownership:
  `docs/releases/v1/runbooks/studio-complex-interaction-patterns-runbook.md`
- Studio navigation/command dependency and data contracts:
  `docs/releases/v1/specs/studio-navigation-and-command-surfaces-dependency-and-data-contract-map.md`
- Studio navigation/command journeys and edge cases:
  `docs/releases/v1/specs/studio-navigation-and-command-surfaces-user-journeys-and-edge-cases.md`
- Studio navigation/command runbook and ownership:
  `docs/releases/v1/runbooks/studio-navigation-and-command-surfaces-runbook.md`
- Studio search/discovery dependency and data contracts:
  `docs/releases/v1/specs/studio-search-and-global-discovery-dependency-and-data-contract-map.md`
- Studio search/discovery journeys and edge cases:
  `docs/releases/v1/specs/studio-search-and-global-discovery-user-journeys-and-edge-cases.md`
- Studio search/discovery runbook and ownership:
  `docs/releases/v1/runbooks/studio-search-and-global-discovery-runbook.md`
- Studio cross-domain entity-model dependency and data contracts:
  `docs/releases/v1/specs/studio-cross-domain-entity-model-dependency-and-data-contract-map.md`
- Studio cross-domain entity-model journeys and edge cases:
  `docs/releases/v1/specs/studio-cross-domain-entity-model-user-journeys-and-edge-cases.md`
- Studio cross-domain entity-model runbook and ownership:
  `docs/releases/v1/runbooks/studio-cross-domain-entity-model-runbook.md`
- Studio workspace context-switching dependency and data contracts:
  `docs/releases/v1/specs/studio-workspace-context-switching-dependency-and-data-contract-map.md`
- Studio workspace context-switching journeys and edge cases:
  `docs/releases/v1/specs/studio-workspace-context-switching-user-journeys-and-edge-cases.md`
- Studio workspace context-switching runbook and ownership:
  `docs/releases/v1/runbooks/studio-workspace-context-switching-runbook.md`
- Studio multi-project operations dependency and data contracts:
  `docs/releases/v1/specs/studio-multi-project-operations-dependency-and-data-contract-map.md`
- Studio multi-project operations journeys and edge cases:
  `docs/releases/v1/specs/studio-multi-project-operations-user-journeys-and-edge-cases.md`
- Studio multi-project operations runbook and ownership:
  `docs/releases/v1/runbooks/studio-multi-project-operations-runbook.md`
- Studio authentication architecture dependency and data contracts:
  `docs/releases/v1/specs/studio-authentication-architecture-dependency-and-data-contract-map.md`
- Studio authentication architecture journeys and edge cases:
  `docs/releases/v1/specs/studio-authentication-architecture-user-journeys-and-edge-cases.md`
- Studio authentication architecture runbook and ownership:
  `docs/releases/v1/runbooks/studio-authentication-architecture-runbook.md`
- Studio session/device management dependency and data contracts:
  `docs/releases/v1/specs/studio-session-and-device-management-dependency-and-data-contract-map.md`
- Studio session/device management journeys and edge cases:
  `docs/releases/v1/specs/studio-session-and-device-management-user-journeys-and-edge-cases.md`
- Studio session/device management runbook and ownership:
  `docs/releases/v1/runbooks/studio-session-and-device-management-runbook.md`
- Studio RBAC/permission-policy UX dependency and data contracts:
  `docs/releases/v1/specs/studio-rbac-and-permission-policy-ux-dependency-and-data-contract-map.md`
- Studio RBAC/permission-policy UX journeys and edge cases:
  `docs/releases/v1/specs/studio-rbac-and-permission-policy-ux-user-journeys-and-edge-cases.md`
- Studio RBAC/permission-policy UX runbook and ownership:
  `docs/releases/v1/runbooks/studio-rbac-and-permission-policy-ux-runbook.md`
- Studio enterprise tenant-isolation dependency and data contracts:
  `docs/releases/v1/specs/studio-enterprise-tenant-isolation-dependency-and-data-contract-map.md`
- Studio enterprise tenant-isolation journeys and edge cases:
  `docs/releases/v1/specs/studio-enterprise-tenant-isolation-user-journeys-and-edge-cases.md`
- Studio enterprise tenant-isolation runbook and ownership:
  `docs/releases/v1/runbooks/studio-enterprise-tenant-isolation-runbook.md`
- Studio audit/compliance surfaces dependency and data contracts:
  `docs/releases/v1/specs/studio-audit-and-compliance-surfaces-dependency-and-data-contract-map.md`
- Studio audit/compliance surfaces journeys and edge cases:
  `docs/releases/v1/specs/studio-audit-and-compliance-surfaces-user-journeys-and-edge-cases.md`
- Studio audit/compliance surfaces runbook and ownership:
  `docs/releases/v1/runbooks/studio-audit-and-compliance-surfaces-runbook.md`
- Studio notification center dependency and data contracts:
  `docs/releases/v1/specs/studio-notification-center-dependency-and-data-contract-map.md`
- Studio notification center journeys and edge cases:
  `docs/releases/v1/specs/studio-notification-center-user-journeys-and-edge-cases.md`
- Studio notification center runbook and ownership:
  `docs/releases/v1/runbooks/studio-notification-center-runbook.md`
- Studio activity/change feeds dependency and data contracts:
  `docs/releases/v1/specs/studio-activity-and-change-feeds-dependency-and-data-contract-map.md`
- Studio activity/change feeds journeys and edge cases:
  `docs/releases/v1/specs/studio-activity-and-change-feeds-user-journeys-and-edge-cases.md`
- Studio activity/change feeds runbook and ownership:
  `docs/releases/v1/runbooks/studio-activity-and-change-feeds-runbook.md`
- Studio real-time collaboration substrate dependency and data contracts:
  `docs/releases/v1/specs/studio-real-time-collaboration-substrate-dependency-and-data-contract-map.md`
- Studio real-time collaboration substrate journeys and edge cases:
  `docs/releases/v1/specs/studio-real-time-collaboration-substrate-user-journeys-and-edge-cases.md`
- Studio real-time collaboration substrate runbook and ownership:
  `docs/releases/v1/runbooks/studio-real-time-collaboration-substrate-runbook.md`
- Studio presence/cursor systems dependency and data contracts:
  `docs/releases/v1/specs/studio-presence-and-cursor-systems-dependency-and-data-contract-map.md`
- Studio presence/cursor systems journeys and edge cases:
  `docs/releases/v1/specs/studio-presence-and-cursor-systems-user-journeys-and-edge-cases.md`
- Studio presence/cursor systems runbook and ownership:
  `docs/releases/v1/runbooks/studio-presence-and-cursor-systems-runbook.md`
- Studio commenting/annotation dependency and data contracts:
  `docs/releases/v1/specs/studio-commenting-and-annotation-system-dependency-and-data-contract-map.md`
- Studio commenting/annotation journeys and edge cases:
  `docs/releases/v1/specs/studio-commenting-and-annotation-system-user-journeys-and-edge-cases.md`
- Studio commenting/annotation runbook and ownership:
  `docs/releases/v1/runbooks/studio-commenting-and-annotation-system-runbook.md`
- Studio review/approval workflows dependency and data contracts:
  `docs/releases/v1/specs/studio-review-and-approval-workflows-dependency-and-data-contract-map.md`
- Studio review/approval workflows journeys and edge cases:
  `docs/releases/v1/specs/studio-review-and-approval-workflows-user-journeys-and-edge-cases.md`
- Studio review/approval workflows runbook and ownership:
  `docs/releases/v1/runbooks/studio-review-and-approval-workflows-runbook.md`
- Studio file/media ingestion dependency and data contracts:
  `docs/releases/v1/specs/studio-file-and-media-ingestion-dependency-and-data-contract-map.md`
- Studio file/media ingestion journeys and edge cases:
  `docs/releases/v1/specs/studio-file-and-media-ingestion-user-journeys-and-edge-cases.md`
- Studio file/media ingestion runbook and ownership:
  `docs/releases/v1/runbooks/studio-file-and-media-ingestion-runbook.md`
- Studio asset preview pipeline dependency and data contracts:
  `docs/releases/v1/specs/studio-asset-preview-pipeline-dependency-and-data-contract-map.md`
- Studio asset preview pipeline journeys and edge cases:
  `docs/releases/v1/specs/studio-asset-preview-pipeline-user-journeys-and-edge-cases.md`
- Studio asset preview pipeline runbook and ownership:
  `docs/releases/v1/runbooks/studio-asset-preview-pipeline-runbook.md`
- Studio background jobs/progress UX dependency and data contracts:
  `docs/releases/v1/specs/studio-background-jobs-and-progress-ux-dependency-and-data-contract-map.md`
- Studio background jobs/progress UX journeys and edge cases:
  `docs/releases/v1/specs/studio-background-jobs-and-progress-ux-user-journeys-and-edge-cases.md`
- Studio background jobs/progress UX runbook and ownership:
  `docs/releases/v1/runbooks/studio-background-jobs-and-progress-ux-runbook.md`
- Studio resilience/error UX dependency and data contracts:
  `docs/releases/v1/specs/studio-resilience-and-error-ux-dependency-and-data-contract-map.md`
- Studio resilience/error UX journeys and edge cases:
  `docs/releases/v1/specs/studio-resilience-and-error-ux-user-journeys-and-edge-cases.md`
- Studio resilience/error UX runbook and ownership:
  `docs/releases/v1/runbooks/studio-resilience-and-error-ux-runbook.md`
- Studio metrics/analytics instrumentation dependency and data contracts:
  `docs/releases/v1/specs/studio-metrics-and-analytics-instrumentation-dependency-and-data-contract-map.md`
- Studio metrics/analytics instrumentation journeys and edge cases:
  `docs/releases/v1/specs/studio-metrics-and-analytics-instrumentation-user-journeys-and-edge-cases.md`
- Studio metrics/analytics instrumentation runbook and ownership:
  `docs/releases/v1/runbooks/studio-metrics-and-analytics-instrumentation-runbook.md`
- Studio observability/operational dashboards dependency and data contracts:
  `docs/releases/v1/specs/studio-observability-and-operational-dashboards-dependency-and-data-contract-map.md`
- Studio observability/operational dashboards journeys and edge cases:
  `docs/releases/v1/specs/studio-observability-and-operational-dashboards-user-journeys-and-edge-cases.md`
- Studio observability/operational dashboards runbook and ownership:
  `docs/releases/v1/runbooks/studio-observability-and-operational-dashboards-runbook.md`
- Studio experimentation/feature flags dependency and data contracts:
  `docs/releases/v1/specs/studio-experimentation-and-feature-flags-dependency-and-data-contract-map.md`
- Studio experimentation/feature flags journeys and edge cases:
  `docs/releases/v1/specs/studio-experimentation-and-feature-flags-user-journeys-and-edge-cases.md`
- Studio experimentation/feature flags runbook and ownership:
  `docs/releases/v1/runbooks/studio-experimentation-and-feature-flags-runbook.md`
- Studio performance budgets dependency and data contracts:
  `docs/releases/v1/specs/studio-performance-budgets-dependency-and-data-contract-map.md`
- Studio performance budgets journeys and edge cases:
  `docs/releases/v1/specs/studio-performance-budgets-user-journeys-and-edge-cases.md`
- Studio performance budgets runbook and ownership:
  `docs/releases/v1/runbooks/studio-performance-budgets-runbook.md`
- Studio accessibility governance dependency and data contracts:
  `docs/releases/v1/specs/studio-accessibility-governance-dependency-and-data-contract-map.md`
- Studio accessibility governance journeys and edge cases:
  `docs/releases/v1/specs/studio-accessibility-governance-user-journeys-and-edge-cases.md`
- Studio accessibility governance runbook and ownership:
  `docs/releases/v1/runbooks/studio-accessibility-governance-runbook.md`
- Studio internationalization/localization dependency and data contracts:
  `docs/releases/v1/specs/studio-internationalization-and-localization-dependency-and-data-contract-map.md`
- Studio internationalization/localization journeys and edge cases:
  `docs/releases/v1/specs/studio-internationalization-and-localization-user-journeys-and-edge-cases.md`
- Studio internationalization/localization runbook and ownership:
  `docs/releases/v1/runbooks/studio-internationalization-and-localization-runbook.md`
- Studio API gateway/BFF composition dependency and data contracts:
  `docs/releases/v1/specs/studio-api-gateway-and-bff-composition-dependency-and-data-contract-map.md`
- Studio API gateway/BFF composition journeys and edge cases:
  `docs/releases/v1/specs/studio-api-gateway-and-bff-composition-user-journeys-and-edge-cases.md`
- Studio API gateway/BFF composition runbook and ownership:
  `docs/releases/v1/runbooks/studio-api-gateway-and-bff-composition-runbook.md`
- Studio webhooks/external automation dependency and data contracts:
  `docs/releases/v1/specs/studio-webhooks-and-external-automation-dependency-and-data-contract-map.md`
- Studio webhooks/external automation journeys and edge cases:
  `docs/releases/v1/specs/studio-webhooks-and-external-automation-user-journeys-and-edge-cases.md`
- Studio webhooks/external automation runbook and ownership:
  `docs/releases/v1/runbooks/studio-webhooks-and-external-automation-runbook.md`
- Studio SDK/documentation integration dependency and data contracts:
  `docs/releases/v1/specs/studio-sdk-and-documentation-integration-dependency-and-data-contract-map.md`
- Studio SDK/documentation integration journeys and edge cases:
  `docs/releases/v1/specs/studio-sdk-and-documentation-integration-user-journeys-and-edge-cases.md`
- Studio SDK/documentation integration runbook and ownership:
  `docs/releases/v1/runbooks/studio-sdk-and-documentation-integration-runbook.md`
- Studio security hardening program dependency and data contracts:
  `docs/releases/v1/specs/studio-security-hardening-program-dependency-and-data-contract-map.md`
- Studio security hardening program journeys and edge cases:
  `docs/releases/v1/specs/studio-security-hardening-program-user-journeys-and-edge-cases.md`
- Studio security hardening program runbook and ownership:
  `docs/releases/v1/runbooks/studio-security-hardening-program-runbook.md`
- Studio data retention/lifecycle controls dependency and data contracts:
  `docs/releases/v1/specs/studio-data-retention-and-lifecycle-controls-dependency-and-data-contract-map.md`
- Studio data retention/lifecycle controls journeys and edge cases:
  `docs/releases/v1/specs/studio-data-retention-and-lifecycle-controls-user-journeys-and-edge-cases.md`
- Studio data retention/lifecycle controls runbook and ownership:
  `docs/releases/v1/runbooks/studio-data-retention-and-lifecycle-controls-runbook.md`
- Studio backup/disaster recovery UX dependency and data contracts:
  `docs/releases/v1/specs/studio-backup-and-disaster-recovery-ux-dependency-and-data-contract-map.md`
- Studio backup/disaster recovery UX journeys and edge cases:
  `docs/releases/v1/specs/studio-backup-and-disaster-recovery-ux-user-journeys-and-edge-cases.md`
- Studio backup/disaster recovery UX runbook and ownership:
  `docs/releases/v1/runbooks/studio-backup-and-disaster-recovery-ux-runbook.md`
- Studio launch-readiness governance dependency and data contracts:
  `docs/releases/v1/specs/studio-launch-readiness-governance-dependency-and-data-contract-map.md`
- Studio launch-readiness governance journeys and edge cases:
  `docs/releases/v1/specs/studio-launch-readiness-governance-user-journeys-and-edge-cases.md`
- Studio launch-readiness governance runbook and ownership:
  `docs/releases/v1/runbooks/studio-launch-readiness-governance-runbook.md`
- Studio Bellona live-engine bridges route map:
  `docs/releases/v1/specs/studio-bellona-live-engine-bridges-route-map.md`
- Studio Bellona Unity Bridge Commands route map:
  `docs/releases/v1/specs/studio-bellona-unity-bridge-commands-route-map.md`
- Studio Bellona Unreal Bridge Commands route map:
  `docs/releases/v1/specs/studio-bellona-unreal-bridge-commands-route-map.md`
- Studio Bellona Asset Interchange Formats route map:
  `docs/releases/v1/specs/studio-bellona-asset-interchange-formats-route-map.md`
- Studio Bellona Build Job Authoring route map:
  `docs/releases/v1/specs/studio-bellona-build-job-authoring-route-map.md`
- Studio Bellona Format Registry troubleshooting:
  `docs/releases/v1/runbooks/studio-bellona-format-registry-troubleshooting.md`
- Architecture decisions: `docs/adr/`
- Existing-domain audits: `docs/releases/v1/audits/`

## 3. Environment Setup

### 3.1 Prerequisites

- Node.js `>=20`
- pnpm `>=10`

### 3.2 Install Workspace Dependencies

```bash
pnpm install
```

### 3.3 Create Local Env Files

```bash
cp apps/oshun/mobile/.env.example apps/oshun/mobile/.env
cp apps/oshun/web/.env.example apps/oshun/web/.env.local
cp apps/oshun/bff/.env.example apps/oshun/bff/.env
```

## 4. Development Commands

### 4.1 Run Core OSHUN Surfaces

```bash
pnpm nx run @oshun/bff:dev
pnpm nx run @oshun/web:dev
pnpm nx run @oshun/mobile:start
```

### 4.2 Mobile Commands

```bash
pnpm nx run @oshun/mobile:start
pnpm nx run @oshun/mobile:start:ios
pnpm nx run @oshun/mobile:start:android
pnpm nx run @oshun/mobile:start:web
pnpm nx run @oshun/mobile:build
pnpm nx run @oshun/mobile:typecheck
pnpm nx run @oshun/mobile:lint
pnpm nx run @oshun/mobile:test
cd apps/oshun/mobile && pnpm run perf:fps:android com.oshun.mobile swipe-back
cd apps/oshun/mobile && pnpm run perf:fps:android com.oshun.mobile pull-to-refresh
cd apps/oshun/mobile && pnpm run perf:fps:android com.oshun.mobile sheet-drag
```

### 4.3 Web Commands

```bash
pnpm nx run @oshun/web:dev
pnpm nx run @oshun/web:build
pnpm nx run @oshun/web:start
pnpm nx run @oshun/web:typecheck
pnpm nx run @oshun/web:lint
pnpm nx run @oshun/web:test
```

### 4.4 BFF Commands

```bash
pnpm nx run @oshun/bff:dev
pnpm nx run @oshun/bff:build
pnpm nx run @oshun/bff:start
pnpm nx run @oshun/bff:typecheck
pnpm nx run @oshun/bff:lint
pnpm nx run @oshun/bff:test
```

### 4.5 Shared OSHUN Library Commands

```bash
pnpm nx run-many -t lint --projects=tag:scope:oshun
pnpm nx run-many -t typecheck --projects=tag:scope:oshun
pnpm nx run-many -t test --projects=tag:scope:oshun
pnpm nx run-many -t build --projects=tag:scope:oshun
```

## 5. Agent Execution Notes

- Execute tasks in `OSHUN_APP_TODOS.md` in order.
- For each completed task:
  - update the checklist item
  - stage relevant file changes
  - commit with a task-scoped message
  - push to `origin/main`
- Prefer project-local commands (`pnpm nx run <project>:<target>`) before
  workspace-wide runs.
