Disciplines · Decisions (ADRs)

ADR-0061: OSHUN Sky-to-Text Journey Model

The PRD and gap analysis already define one of OSHUN's required cross-domain moments: a Nyx event should connect into ancient cosmologies, calendars, and comparative texts through Nisaba.

Accepted · 2026-03-24
9sections5 minread
Markdown source
On this page

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

Context and Problem Statement#

The PRD and gap analysis already define one of OSHUN's required cross-domain moments: a Nyx event should connect into ancient cosmologies, calendars, and comparative texts through Nisaba.

The codebase already had several of the building blocks:

  • Nyx already exposed a celestial calendar, nightly highlights, sky-map, and observation-log surfaces.
  • Nisaba already exposed passage, source, compare, concept, and notebook launch semantics.
  • Nisaba's canonical adapter already recognized a cosmology_context study moment for Nyx-originating event bridges.

But there was no canonical shell-level answer to the question: "How does a sky event become a textual and cosmological study thread?"

That gap mattered because sky-to-text is not a generic cross-link. It is a product-level promise that Nyx wonder can deepen into Nisaba interpretation without dropping the concrete event, its timing, or its observational frame.

Decision Drivers#

  • Nyx depth needs meaning, not just visualization: observing the sky should be able to deepen into inherited interpretation.
  • Nisaba should act as a depth layer: ancient astronomy texts, calendars, and comparative readings should be reachable from Nyx rather than isolated in Nisaba.
  • Context continuity matters: the event, time window, and observation frame should survive the handoff.
  • Durability matters: the cross-domain interpretation should end in a notebook or Library resume point, not a dead-end overlay.
  • Implementation leverage matters: docs, QA, web surfaces, and later mobile work need one typed shell contract.

Considered Options#

Option 1: Leave sky-to-text implicit in Nyx and Nisaba routes#

Description: keep Nyx event/calendar surfaces and Nisaba study routes, but do not publish a canonical journey between them.

Pros:

  • Lowest implementation cost.
  • Reuses existing route depth.

Cons:

  • Leaves the PRD requirement unowned.
  • Makes Nyx-to-Nisaba context transfer optional and inconsistent.
  • Gives QA and future mobile work no normative flow to validate against.

Option 2: Treat sky-to-text as a Nisaba-only study feature#

Description: keep Nyx focused on observation while Nisaba separately hosts cosmology and calendar texts without an explicit Nyx-origin handoff.

Pros:

  • Simple domain boundaries.
  • Keeps astronomy and textual depth conceptually separated.

Cons:

  • Violates the requirement that Nyx events connect to Nisaba.
  • Undercuts OSHUN's cross-domain coherence by making wonder and interpretation feel unrelated.
  • Leaves event context and timing behind during the handoff.

Option 3: Publish an explicit sky-to-text journey model and render it inside the Nyx celestial calendar (Chosen)#

Description: define one four-stage shell journey from event framing through observation context, Nisaba cosmology/calendar/comparative-text study, and durable preservation; publish it in shared navigation contracts; map it into contextual web actions; and render it inside the Nyx event-calendar overlay.

Pros:

  • Makes the PRD's Nyx-to-Nisaba behavior executable.
  • Turns Nyx observation into a real cross-domain meaning loop.
  • Preserves event framing while routing into Nisaba.
  • Produces one reusable contract for docs, QA, web, and later mobile work.

Cons:

  • Adds another cross-domain journey model that later work must respect.
  • Requires discipline so sky-to-text stays distinct from daypart, story-to- source, and research-to-practice journeys.

Decision Outcome#

Chosen option: Option 3.

Normative Rule#

OSHUN owns one canonical Sky to text shell journey.

Its question is:

What inherited texts, calendars, and cosmologies can deepen this sky event?

That journey is not complete when the user has merely opened a Nyx event. It is complete when the shell has preserved a path from the event into textual context, calendar sources, comparative readings, and one durable notebook or Library save.

Stage Rule#

The normative stage order is:

  1. Hold the sky moment
  2. Frame the observation
  3. Open cosmology and texts
  4. Preserve the sky thread

Stage Semantics#

1. Hold the sky moment#

Nyx is the canonical entry surface for choosing one specific celestial event or nightly highlight.

This stage exists to stop the sky moment from dissolving back into a generic astronomy feed.

2. Frame the observation#

Once the event is chosen, the shell should preserve observation context through:

  • sky-map framing
  • observation memory or log context when helpful

This stage ensures Nisaba receives an event with temporal and observational shape, not an abstract keyword.

3. Open cosmology and texts#

After the observation frame is stable, the shell must hand the user into Nisaba for:

  • cosmology passages
  • calendar-source packs
  • comparative sky texts

This is where Nyx wonder turns into inherited meaning and textual depth.

4. Preserve the sky thread#

The journey must end in:

  • a Nisaba notebook or comparable study workspace
  • a Library resume point that preserves the sky-to-text thread

This keeps the event and its interpretation durable beyond one viewing session.

Surface Rule#

  • Nyx is the canonical sky-event entry surface.
  • Nisaba is the canonical cosmology, calendar, and comparative-text surface.
  • Library is the canonical preserve surface for the completed sky thread.

Contract Publication#

The shared sky-to-text model lives in libs/oshun/navigation/src/sky-text-journey.ts.

The web action mapping for that model lives in apps/oshun/web/src/navigation/sky-text-journey.ts.

The current web rendering of that model lives in apps/oshun/web/src/components/domains/nyx/SkyTextJourneyRail.tsx.

Scope Boundaries#

  • This ADR defines the shell-level sky-to-text journey, not a full Nyx event- planning or Nisaba corpus-authoring system.
  • It does not replace Tara- or Arete-linked night-sky moments that other backlog items may add later.
  • It does not require Nyx to expose every cosmology overlay inline; this slice establishes the canonical journey and one concrete entry surface.

Architecture Implications#

  • shared navigation code should expose typed sky-to-text stages and handoffs
  • Nyx event-calendar UI should make the Nisaba handoff explicit and actionable
  • Nisaba launches should preserve Nyx back-stack context so the sky frame is not lost during the handoff
  • future mobile and assistant work can reuse one canonical sky-to-text definition instead of inventing local copies

Acceptance Criteria#

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

  1. A canonical ADR defines the sky-to-text journey model.
  2. Shared navigation code publishes the same stage and handoff model.
  3. The web Nyx event-calendar surface reflects that model as actionable continuity guidance.
  4. The shipped model makes Nyx event framing, observation context, Nisaba cosmology/calendar/comparative-text study, and notebook preservation explicit.
  5. Tests verify the shared model, web action mapping, Nyx rendering, and cross-domain Nisaba handoff behavior.
  • docs/adr/ADR-0060-oshun-nisaba-first-class-customer-domain.md
  • docs/adr/ADR-0064-oshun-daypart-cross-domain-journey-model.md
  • docs/adr/ADR-0065-oshun-research-to-practice-journey-model.md
  • docs/adr/ADR-0066-oshun-story-to-source-journey-model.md

References#

  • docs/releases/v1/specs/web-app-admin-v1-prd.md
  • docs/releases/v1/reports/unified-product-gap-analysis-and-nisaba-integration-report-2026-03-22.md
  • libs/oshun/navigation/src/sky-text-journey.ts
  • apps/oshun/web/src/navigation/sky-text-journey.ts
  • apps/oshun/web/src/components/domains/nyx/SkyTextJourneyRail.tsx