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.