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

**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.

## Related Decisions

- `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`