# Nyx expansion: source-review findings and learning routes

Reviewed against `1ceae52c7896a59ac74a4429d410f3218f0b91c6` on 2026-09-06. This
is an authoring map, not published teaching or a completed assignment. The
current nine-slide Nyx guide is an orientation. Completing its narration does
not cover the full feature page, architecture, contracts or implementations.

The source review read all of `V1/features/domain-nyx.md` and compared its depth
inventory with the pinned Git tree. The routes below are learning outcomes, not
a fixed number of guides. Split mechanisms and worked examples as needed, and
reconcile the full documentation and non-Markdown inventories before claiming
complete Nyx coverage.

## Surface and journey orientation

Teach the consumer hub and `/nyx/events`, `/nyx/observation`, `/nyx/sky-almanac`
and `/nyx/tonight`, followed by all twenty named deep-tool routes and their
distinct responsibilities. Map routes to components, entry actions, data owners
and tests. Capture actual UI states with revision and viewport provenance;
distinguish captures from proposals. Preserve the source's mobile boundary:
embedded companion cards are not a standalone Nyx screen tree.

## Astronomy fundamentals and worked computation

Explain the eleven exported ephemeris functions from UTC and Julian Day through
solar/lunar positions, illumination, sidereal time, horizontal coordinates and
rise/transit/set. Work the documented reference inputs and outputs, with units,
east-positive longitude, north-origin azimuth, modulo-before-sidereal-division,
standard altitude constants and circumpolar flags. Explain the lunar
approximation and separate numerical accuracy from provider and UI behavior.
Read and execute the applicable implementation tests; a source description of
known-answer tests is not a newly observed passing run.

## Almanac composition and interpretation

Cover all depth computations and their input/output contracts: phase calendar,
twilight schedule/current phase, astronomical night, equation of time, solar
noon/terms/season markers, daylight extremes, zodiac position, planetary hours,
lunar nodes, Moon distance/phase detail, Sun distance, chart angles, object
transit and horizon-point helpers. Trace `depth-page` into the rendered almanac.
Use calculation diagrams and worked values, while keeping cultural frameworks
distinct from physical measurements.

The pinned `libs/oshun/domain-nyx/src/depth/` has **41 files: 21 implementation
files and 20 `.test.ts` files**, including the page builder. The feature page's
later phrase “41 depth modules” must not be repeated as a module count.
`horizon-point.ts` has no same-stem `.test.ts`; that alone does not establish
that the helper is untested, since consumer tests can exercise it indirectly.
Inspect the actual test imports and assertions before describing coverage.

## Event, window and provenance contracts

Teach all eleven event families, twenty-seven types and their mapping;
per-family detail blocks, nullable versus required detail, subtype consistency,
field ranges and representative invalid inputs. Explain the complete event
envelope, timestamp ordering, unique identifiers and window/source references.

Follow a worked observation window through site, timing, equipment and every
quality input. Teach the exact excellent-band guards (Bortle at most four, cloud
cover at most twenty-five percent, astronomical twilight or night) and both
directions of the not-visible consistency rule. A useful next slide should show
accepted and rejected examples, not merely say “a declared threshold.”

Explain all eleven prediction-source kinds, their family-support matrix and
version/license/attribution/freshness fields. Show why weather can augment a
window without independently supporting an event, and why a valid provenance
record does not establish a live NASA, IMO or NOAA ingestion path.

## Observation, calendar and reminder lifecycles

Trace the full logged-observation fields, unscheduled sights, condition checks,
attachments, sharing and source clients into actual persistence. Reconcile the
page's older local-storage account with its later dated POST/GET read-back
evidence after local storage is cleared; neither passage alone proves complete
cross-device synchronization. Teach event-detail handoff, Home/KPI updates and
the observation-equipment versus telescope-control boundary.

Explain all provider/cadence/direction/sync states and field guards, including
ICS, conflict reasons, reminder consistency and provider acknowledgements. Trace
the BFF adapters and per-user stores. The reminder bridge delivers
already-created reminders with per-user/reminder deduplication and per-user
failure isolation; it is not their creation owner. Exercise the real supported
paths separately from mocked provider OAuth and source ingestion.

## Shared machinery and cross-domain companions

Reconcile `libs/oshun/domain-nyx` with the separate `libs/nyx` package family
and the V9 consumers; one ephemeris overview does not explain both
implementation trees. Trace Tara, Nisaba, Veritas, assistant and Living Scenes
handoffs through their owners and release scope. Review opt-in location,
hemisphere parity, per-night materialization and the stated briefing
synchronization bound against actual evidence. Keep V1.2-only exposure, URL-only
telemetry, configured providers and measured playback distinct.

Before publication, bind each complete source unit to the actual explanatory
slides, then verify screenshots, diagrams, narration, navigation and PDF output.
No source unit is marked reviewed merely because it appears in this map.
