Eve library

OSHUN Implementation Guide

Spec

Revision 1

On this page

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.