spacedata: Instructions file for Codex

spacedata

General

• AGENTS.md is the source of truth. All CLAUDE.md files are references to it — make changes here, not in CLAUDE.md.
• Never add Co-Authored-By in commits or PR bodies.

Architecture

Bun monorepo (packages/*). One package for now:

The MCP server lives inside the cli package (spacedata serve, src/mcp/mcp-server.ts): a lean 15-tool surface over stdio that reuses the source layer verbatim. Tool results carry the same {ok, source, cached, fetchedAt, data} / {ok: false, error} envelopes as the CLI; new sources should be exposed in both surfaces. In serve mode stdout belongs to the MCP transport — never write anything else to it.

Locally computed results (SGP4 position/passes/overhead) are layered: pure math in src/domain/propagation.ts (no I/O, like derive.ts), fetch+compute orchestration in src/compute/, reusing the CelesTrak source. Their envelope uses source: "celestrak+sgp4"; cached/fetchedAt describe the underlying element fetch.

Aggregated reports (spaceweather, aurora, events) fetch several products in parallel; only the core product's failure fails the command — every other section degrades to undefined plus an entry in data.warnings. Their envelope (src/core/aggregate.ts) reports cached: true only when every contributing fetch was cached, and the most recent fetchedAt.

Orbital events combine both patterns. sat events (compute/satellite-events.compute.ts, envelope spacetrack+gfz+analysis): detectors are pure math in domain/events.ts — element jumps against the object's own median/MAD noise floor (drag-detrended, gap-aware), SGP4 propagation residuals (propagationResidualKm in domain/propagation.ts) as corroboration, planetary Kp (GFZ, sources/gfz.source.ts) to separate storms from maneuvers. Events are inferences: they must always carry evidence and confidence, never a bare verdict, and thresholds/heuristics live as named constants with comments. events (compute/orbital-events.compute.ts, envelope spacetrack+launch-library+gfz) is the administrative digest — satcat_debut/satcat_change/TIP/LL2 previous, nothing inferred; grouping/classification helpers are pure in domain/catalog-events.ts. domain/iss-history.fixture.ts is real ISS gp_history (30 days around the 2026-07-02 reboost) and is the detector's ground-truth regression fixture — extend it, don't replace it, when recalibrating.