===============
LIBRARY RULES
===============
From library maintainers:
- Use the REST API endpoints, not the JavaScript library directly
- Include location parameters (lat, lon) for topocentric coordinates
- All times are UTC; convert to local timezone in your client
- Arduino calibration is implementation-specific - API provides raw servo angles and stepper steps
- Physical builders must calibrate their own hardware - no generic calibration data provided
- stepsForInterval appears in /api/display responses ONLY when both dt and stepsPerDegree query parameters are provided
- Use /api/display?dt=5&stepsPerDegree=200 for Arduino stepper motor control with stepsForInterval
- Servo angles from API are theoretical positions - apply your own calibration lookup table
- Use /api/state for multiple bodies, /api/{body} for single bodies
- Use REST API polling for real-time updates - WebSockets not needed or supported
- Batch multiple bodies in single request: /api/state?bodies=sun,moon,mars
- 250ms polling interval provides smooth 4fps animation with low server load
- Response format is consistent across all examples - use the API documentation as source of truth

### Quick Start Installation and Execution

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/PROJECT_SUMMARY.md

Provides commands to clone the repository, install dependencies, and start the application server. Assumes Node.js and npm are installed.

```bash
cd antikythera-engine
npm install
npm start
# Open http://localhost:3000
```

--------------------------------

### Antikythera CLI Quick Start Commands

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/CLI.md

A quick start guide to using the Antikythera CLI for common astronomical tasks, including launching the interactive REPL, getting current states, positions, comparing sources, and live watching.

```bash
# Start interactive REPL (see docs/CLI-REPL.md)
antikythera repl

# Get current astronomical state
antikythera now

# Get Mars position
antikythera position mars

# Compare CLI calculation vs API
antikythera compare mars cli api

# Watch Mars position update live
antikythera watch mars
```

--------------------------------

### Install and Run Antikythera Engine

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/CHEAT_SHEET.md

Installs project dependencies and starts the development server. Assumes Node.js and npm are installed.

```bash
# Install
npm install

# Run
npm start

# Open
http://localhost:3000
```

```bash
npm install && npm start
```

--------------------------------

### Install Antikythera CLI Locally and Globally

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/CLI.md

Instructions for installing the Antikythera CLI tool, including local development setup via cloning the repository and linking, as well as global installation.

```bash
# Clone the repository
git clone https://github.com/mojoatomic/antikythera-engine-2.git
cd antikythera-engine-2

# Install dependencies
npm install

# Link for local use (adds `antikythera` to PATH)
npm link

# Verify installation
antikythera --version

# Install globally from the local repo checkout
npm install -g .
```

--------------------------------

### Install and Start Antikythera Engine (Bash)

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/README.md

Installs project dependencies using npm and starts the Antikythera Engine server. The API will be available at http://localhost:3000.

```bash
npm install
npm start
```

--------------------------------

### Example GitHub Repo Structure for Extension

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/EXTENSION_GUIDE.md

Illustrates a recommended directory structure for sharing Antikythera Engine extensions on GitHub. It includes common folders for components, themes, screenshots, and documentation.

```text
my-antikythera-extension/
├── components/
│   └── MoonTracker.js
├── themes/
│   └── hologram.css
├── screenshots/
│   └── preview.png
└── README.md
```

--------------------------------

### API Response Example: UI Settings

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/docs/TECHNICAL_OPERATIONS_MANUAL.md

Example JSON response from the /api/settings endpoint, showing UI feature toggles derived from environment variables.

```json
{ "showSunriseSunset": true }
```

--------------------------------

### Antikythera Engine Plotting Examples

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/docs/CLI-REPL.md

Demonstrates various plotting capabilities of the Antikythera Engine using ASCII art. Examples include single-series planetary motion (longitude), moon phase (illumination), visibility timeline (altitude), and multi-series plots with unwrapped longitude.

```text
antikythera> plot mars 90d

MARS Longitude over 90d

 237.3°┤      ╭─╮
 235.5°┤    ╭─╯ ╰─╮
 233.7°┤  ╭─╯     ╰─╮
 231.9°┤╭─╯         ╰─╮
 230.1°┼╯             ╰─╮

antikythera> plot moon.illumination 30d

MOON Illumination over 30d

 100%┤ ●     ●     ●
  75%┤╱ ╲   ╱ ╲   ╱
  50%┤   ◐ ◑   ◐ ◑
  25%┤    ╲ ╱    ╲ ╱
   0%┤     ○     ○

antikythera> plot visibility sun 1d

ALT (°)
 90┤
 45┤        ╱‾‾‾╲        
  0┼───────╯─────╰──────  ← Horizon
-45┤   ╱           ╲
-90┤                     
   06:00  12:00  18:00

antikythera> plot mars,jupiter 30d
MARS | JUPITER
<ascii chart with two colored lines>
2025-10-01 12:00  ...  2025-10-31 12:00
```

--------------------------------

### Example Session: Time and Location Control

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/docs/CLI-REPL.md

Demonstrates a complete session of controlling time and location within the Antikythera REPL, including setting a historical time, defining a specific observer location, checking the status, and finally stopping the control mode to return to real-time.

```bash
# Set historical time
antikythera control time 1969-07-20T20:17:00Z
# Display shows: Apollo 11 moon landing

# Check status
antikythera control status
# Control: active
# Display time: 1969-07-20T20:17:00Z

# Return to now
antikythera control stop
# ✓ Control stopped - display reverted to real-time

# Verify
antikythera control status
# Control: inactive
# Display: real-time
```

--------------------------------

### Example 1: Debug Browser Display (Bash)

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/CLI.md

Provides a practical example for debugging. It shows how to obtain the ground truth position of Mars using the CLI with the '--local' option to verify browser display accuracy.

```bash
# 1. Get CLI ground truth
$ antikythera position mars --local
longitude: 245.123°
```

--------------------------------

### API Response Example: UI Language

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/docs/TECHNICAL_OPERATIONS_MANUAL.md

Example JSON response from the /api/language endpoint, indicating the current UI language setting of the server.

```json
{ "language": "english" }
```

--------------------------------

### Antikythera Engine 2 Educator Examples

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/docs/TECHNICAL_OPERATIONS_MANUAL.md

Example usage of the Antikythera Engine's command-line interface for educational purposes. Demonstrates setting location, finding celestial events, plotting astronomical data, sampling data over a time range, and monitoring celestial bodies.

```text
set location 29.9792,31.1342
find next solstice
plot moon.illumination 30d
sample mars from 2025-01-01T00:00:00Z to +14d every 1d csv
watch jupiter compare
```

--------------------------------

### Troubleshoot API Server Not Running

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/CLI.md

Offers guidance for situations where the API server is not running. It recommends starting the server with `npm start` or using the `--local` flag to bypass the API and use the embedded engine.

```bash
# Start the server first
npm start

# Or use --local to bypass
antikythera position mars --local
```

--------------------------------

### Demo REPL API Fallback Test (Bash)

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/docs/CLI-REPL.md

Demonstrates how to test the Antikythera Engine's REPL API fallback mechanism. It involves starting the REPL, setting the source to auto, stopping the API server, and executing a command to trigger the fallback message.

```bash
# Start REPL
antikythera repl

# Use auto source
set source auto

# Stop API server in another terminal (or ensure it isn't running)
# Then run a body command
moon
# Expected: "API timeout... Falling back to local engine"
```

--------------------------------

### Canvas Component Visual Hierarchy Example (JavaScript)

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/EXTENSION_GUIDE.md

Provides an example of setting font styles and colors for different text elements (title, data, labels) on a canvas to create a clear visual hierarchy. Uses specific font sizes and colors, including CSS variables.

```javascript
// Title: large, accent color
this.ctx.font = 'bold 24px Georgia';
this.ctx.fillStyle = 'var(--color-accent)';

// Data: medium, text color
this.ctx.font = '16px Georgia';
this.ctx.fillStyle = 'var(--color-text)';

// Labels: small, slightly dimmed
this.ctx.font = '12px Georgia';
this.ctx.fillStyle = 'rgba(240, 230, 210, 0.7)';
```

--------------------------------

### API Request Example: Get Astronomical State

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/docs/TECHNICAL_OPERATIONS_MANUAL.md

Example of how to make a GET request to the /api/state endpoint to retrieve the astronomical state for a specific date. It demonstrates the use of query parameters for date specification.

```bash
curl "http://localhost:3000/api/state?date=2025-10-26T12:00:00Z"
```

--------------------------------

### Troubleshoot Server Issues - Bash

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/CHEAT_SHEET.md

Commands to diagnose and resolve issues when the server fails to start. Includes checking for port conflicts and terminating runaway processes.

```bash
# Check port 3000 is free
lsof -i :3000

# Kill process if needed
kill -9 <PID>
```

--------------------------------

### Scripting Example - Mars Alert (Bash)

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/CLI.md

An example of using the CLI in a bash script to automate tasks. This script checks Mars' longitude and prints an alert if it exceeds a certain threshold.

```bash
#!/bin/bash
# Alert if Mars longitude changes significantly
CURRENT=$(antikythera position mars --format json | jq '.longitude')
if [ "$CURRENT" -gt 250 ]; then
  echo "Mars entering Sagittarius!"
fi
```

--------------------------------

### Direct Execution of Antikythera CLI

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/CLI.md

Demonstrates how to execute the Antikythera CLI script directly using Node.js without prior installation or linking.

```bash
node cli/index.js now
```

--------------------------------

### Backend Architecture (Node.js + Express)

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/PROJECT_SUMMARY.md

Describes the backend setup using Node.js and Express, emphasizing its simplicity as a wrapper around the astronomy-engine library with no database dependency.

```plaintext
Backend: Dead Simple
- Node.js + Express
- Single wrapper class around astronomy-engine
- Clean REST endpoints
- No database needed
```

--------------------------------

### Open Antikythera REPL

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/docs/CLI-REPL.md

Opens the interactive Read-Eval-Print Loop (REPL) for the Antikythera CLI. This allows for direct command input and real-time feedback. Ensure the API server is running.

```bash
antikythera repl
```

--------------------------------

### Control Endpoint: Animate Time

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/docs/TECHNICAL_OPERATIONS_MANUAL.md

Example of a POST request to the /api/control/animate endpoint to set up an animation between two specified times. Requires authentication via CONTROL_TOKEN.

```json
{ "from": "2025-10-26T12:00:00Z", "to": "2025-10-26T18:00:00Z", "speed": 10 }
```

--------------------------------

### Antikythera CLI 'compare' Command Usage

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/CLI.md

Usage of the `antikythera compare` command for comparing astronomical calculations between different sources (CLI/engine vs. API). Includes syntax, source options, and output examples.

```bash
# Compare Mars position between CLI engine and API
antikythera compare mars cli api

# Compare Jupiter position for a specific date
antikythera compare jupiter engine api --date 2026-01-15T12:00:00Z
```

--------------------------------

### Control API Examples

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/docs/CONTROL_MODE.md

Illustrates common control operations using the Antikythera API, including setting a historical time, checking status, and stopping the control session to revert to live time.

```bash
# Set historical time
antikythera control time 1969-07-20T20:17:00Z

# Check control status
antikythera control status

# Return to live time
antikythera control stop
```

--------------------------------

### Control Endpoint: Set Scene Preset

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/docs/TECHNICAL_OPERATIONS_MANUAL.md

Example of a POST request to the /api/control/scene endpoint to set a predefined scene, optionally specifying which celestial bodies to include. Requires authentication via CONTROL_TOKEN.

```json
{ "preset": "equinox", "bodies": ["sun", "moon"] }
```

--------------------------------

### Load Custom Component Script in HTML

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/EXTENSION_GUIDE.md

Includes the `PlanetDistances.js` script file in the `index.html` before the `display.js` script. This ensures that the custom component's code is available when the display controller attempts to initialize it.

```html
<script src="components/PlanetDistances.js"></script>
```

--------------------------------

### API Response Structure: Display Data

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/docs/TECHNICAL_OPERATIONS_MANUAL.md

Example JSON response structure for the /api/display endpoint, detailing mechanical control data (steppers, servos) and digital display content (text, LEDs), along with next opposition information.

```json
{
  "timestamp": "2025-10-26T15:28:33.459Z",
  "mechanical": {
    "steppers": {
      "sun": { "position": 213.47, "velocity": 0.998, "altitude": 1.26, "azimuth": 253.23 },
      "moon": { "position": 270.00, "velocity": 11.97, "altitude": 20.28, "azimuth": 200.07 }
    },
    "servos": {
      "mercury_retrograde": { "angle": 0, "state": "prograde" }
    }
  },
  "digital": {
    "displays": {
      "oled_main": { "line1": "Next Eclipse: solar", "line2": "114 days", "line3": "2026-02-17" }
    },
    "leds": {
      "visibility": {
        "mercury": { "color": "red", "brightness": 0 }
      }
    }
  },
  "next_opposition": {
    "planet": "Mars",
    "date": "2026-01-09T08:30:00.000Z",
    "daysUntil": 75.2
  },
  "update_hints": {
    "mechanical": 10000,
    "digital": 1000
  }
}
```

--------------------------------

### Access Ecliptic Coordinates via API (Bash)

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/docs/VALIDATION.md

Command-line examples using `curl` and `jq` to retrieve ecliptic coordinate data from the Antikythera Engine API. It shows how to get all coordinates or specific body data.

```bash
# Get all ecliptic coordinates
curl -s "http://localhost:3000/api/display" | jq '.system.debug.ecliptic_coordinates'

# Get just the moon
curl -s "http://localhost:3000/api/display" | jq '.system.debug.ecliptic_coordinates.moon'
```

--------------------------------

### Antikythera Engine Global and Contextual Commands

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/docs/CLI-REPL.md

Lists global commands available in the Antikythera Engine REPL, such as help, exit, and set, along with contextual commands that appear after specific global commands. This enables dynamic command completion based on the current state.

```text
Global: help, exit, clear, context, history, set, format, source, tz, watch, compare, all, bodies

Contextual after 'set': format|source|tz|intent|tolerance
Contextual after 'format': table|json|compact
Contextual after 'source': auto|local|api
Contextual after 'tz': auto|<IANA>
Contextual after 'intent': on|off
Contextual after 'compare|watch': bodies
```

--------------------------------

### JavaScript Validation Example

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/docs/VALIDATION.md

A JavaScript snippet demonstrating how to fetch API data and calculate the delta in longitude and latitude compared to HORIZONS ephemeris data.

```javascript
const apiData = await fetch('http://localhost:3000/api/display').then(r => r.json());
const yourMoon = apiData.system.debug.ecliptic_coordinates.moon;

// Compare with HORIZONS
const delta_lon = Math.abs(horizons.ObsEcLon - yourMoon.lon);
const delta_lat = Math.abs(horizons.ObsEcLat - yourMoon.lat);

console.log(`Δ Longitude: ${delta_lon}°`);
console.log(`Δ Latitude: ${delta_lat}°`);
```

--------------------------------

### Change Observer Location via API (Bash)

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/docs/VALIDATION.md

Example using `curl` to modify the observer's location (latitude and longitude) for API requests. This affects the topocentric coordinates returned.

```bash
curl "http://localhost:3000/api/display?lat=40.7&lon=-74.0"
```

--------------------------------

### Get Display State with Query Parameters (curl)

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/README.md

Retrieves the physical mechanism's state with specific query parameters to customize the output. This example requests data for a 5-second interval and specifies stepper resolution.

```bash
curl "http://localhost:3000/api/display?dt=5&stepsPerDegree=200"
```

--------------------------------

### Command Line Interface (CLI)

Source: https://context7.com/mojoatomic/antikythera-engine-2/llms.txt

Documentation for the Antikythera Engine CLI, covering commands for calculating astronomical state and retrieving specific body positions.

```APIDOC
## CLI Command: `antikythera now`

### Description
Calculates and displays the current astronomical state of celestial bodies. Supports various output formats.

### Usage
```bash
antikythera now [--format <format>] [--debug]
```

### Parameters
#### Options
- **--format** (string) - Optional - The output format. Supported formats: `table` (default), `json`, `csv`.
- **--debug** - Optional - Enables debug information output.

### Example Usage
```bash
# Default table output
antikythera now

# JSON output
antikythera now --format json

# CSV output
antikythera now --format csv

# With debug information
antikythera now --debug
```

### Example Table Output
```
┌─────────┬───────────┬──────────┬─────────┬──────────┬───────────┬──────────────┐
│ Body    │ Longitude │ Latitude │ Azimuth │ Altitude │ Velocity  │ Motion       │
├─────────┼───────────┼──────────┼─────────┼──────────┼───────────┼──────────────┤
│ Sun     │ 213.35°   │ -0.00°   │ 253.23° │ 1.26°    │ 0.998°/d  │ Prograde     │
│ Moon    │ 269.03°   │ -5.82°   │ 200.07° │ 20.28°   │ 12.12°/d  │ Prograde     │
│ Mercury │ 236.97°   │ -2.72°   │ 231.79° │ 11.12°   │ 1.11°/d   │ Prograde     │
│ Mars    │ 235.31°   │ -0.36°   │ 236.73° │ 11.01°   │ 0.71°/d   │ Prograde     │
│ Saturn  │ 355.94°   │ -2.47°   │ 109.05° │ 18.58°   │ -0.049°/d │ Retrograde   │
└─────────┴───────────┴──────────┴─────────┴──────────┴───────────┴──────────────┘
```

## CLI Command: `antikythera position <body_name>`

### Description
Calculates the position for a specific celestial body at a given time.

### Usage
```bash
antikythera position <body_name> [--date "<date_time>"]
```

### Parameters
#### Arguments
- **body_name** (string) - Required - The name of the celestial body (e.g., `sun`, `moon`, `mars`, `venus`).

#### Options
- **--date** (string) - Optional - The specific date and time for the calculation in ISO 8601 format.

### Example Usage
```bash
# Get Mars position at the current time
antikythera position mars

# Get Venus position at a specific date and time
antikythera position venus --date "2024-06-21T12:00:00Z"
```

### Response
(The output format depends on the context, but will contain positional data similar to the API responses for individual bodies.)

```

--------------------------------

### No Build Tools Required

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/PROJECT_SUMMARY.md

Highlights the project's commitment to simplicity by avoiding common build tools like webpack and babel.

```plaintext
No Build Tools Needed
- No webpack
- No babel
- No preprocessors
- Just HTML/CSS/JS
```

--------------------------------

### Project Structure Overview

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/PROJECT_SUMMARY.md

Illustrates the directory and file organization for the Antikythera Engine project. It highlights the core engine (engine.js), server (server.js), frontend components, and static assets.

```tree
antikythera-engine/
├── engine.js              # Core calculation engine (wraps astronomy-engine)
├── server.js              # Express API server
├── package.json           # Dependencies
├── README.md              # Main documentation
├── VISUAL_GUIDE.md        # What each face shows
├── EXTENSION_GUIDE.md     # How to customize
│
└── public/
    ├── index.html         # Main display page
    ├── display.js         # Display controller
    │
    └── components/
        ├── FrontFace.js      # All 7 celestial bodies + zodiac
        ├── BackUpperFace.js  # Metonic cycle spiral
        └── BackLowerFace.js  # Saros eclipse spiral
```

--------------------------------

### Antikythera CLI 'now' Command Usage

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/CLI.md

Documentation for the `antikythera now` command, which displays the complete astronomical state for the current moment. It supports output formatting and debugging options.

```bash
# Get current astronomical state in JSON format
antikythera now --format json

# Show source and timing information
antikythera now --debug
```

--------------------------------

### Start Antikythera API Server

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/docs/CONTROL_MODE.md

Starts the Antikythera API server. On the first run, it generates a persistent control token and logs its location. This token is used by both the server and the CLI for authentication.

```bash
npm start
```

--------------------------------

### Run Development Server with Control Token

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/README.md

This command starts the development server, which will either use an existing control token or generate a new one if none is found. This is the standard way to run the server for development.

```bash
npm run dev
```

--------------------------------

### Run Tests and Linting for Antikythera Engine

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/CLI.md

Provides commands for running tests and linting the Antikythera Engine codebase. This includes executing the test suite with `npm test` and performing linting checks with `npm run lint` and `npm run lint:fix`.

```bash
npm test

npm run lint
npm run lint:fix
```

--------------------------------

### Get Current Display State (curl)

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/README.md

Fetches the complete state of the physical mechanism, including stepper motor positions, servo angles, display text, and LED status. This is a basic GET request to the display API.

```bash
curl http://localhost:3000/api/display
```

--------------------------------

### Control Physical Devices with Antikythera CLI (Bash)

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/README.md

Shows examples of using the Antikythera CLI for physical device control, including setting time, location, animating ranges, running/pausing time, and managing scenes.

```bash
# Start server (generates token on first run)
npm start

# Set time (UTC) — no env needed locally
antikythera control time 2025-10-29T12:00:00Z

# Set location (explicit, timezone required; elevation optional)
antikythera control location 37.9838,23.7275 --timezone "Europe/Athens" --name "Athens, Greece"

# Animate a range
antikythera control animate --from 2025-10-29T00:00:00Z --to 2025-10-30T00:00:00Z --speed 2

# Run/pause time flow
antikythera control run --speed 10
antikythera control pause

# Scene preset
antikythera control scene --preset planets --bodies mercury,venus,mars

# Status / Stop
antikythera control status
antikythera control stop
```

--------------------------------

### GET /api/planets

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/docs/TECHNICAL_OPERATIONS_MANUAL.md

Retrieves the position data for all planets only.

```APIDOC
## GET /api/planets

### Description
Retrieves the position data for all planets only.

### Method
GET

### Endpoint
/api/planets

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **planets_positions** (object) - An object containing the calculated positions of all planets.

#### Response Example
```json
{
  "planets_positions": {
    "mercury": {"right_ascension": "02h", "declination": "+10°"},
    "venus": {"right_ascension": "03h", "declination": "+15°"}
  }
}
```
```

--------------------------------

### GET /api/moon

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/docs/TECHNICAL_OPERATIONS_MANUAL.md

Retrieves the position data for the moon only.

```APIDOC
## GET /api/moon

### Description
Retrieves the position data for the moon only.

### Method
GET

### Endpoint
/api/moon

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **moon_position** (object) - The calculated position of the moon.

#### Response Example
```json
{
  "moon_position": {
    "right_ascension": "20h",
    "declination": "-15°"
  }
}
```
```

--------------------------------

### Troubleshooting - Compare Sources (Bash)

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/CLI.md

Illustrates a troubleshooting scenario where the CLI is used to compare ground truth positions from different sources (CLI vs. API) to identify discrepancies.

```bash
# Compare CLI ground truth vs API
antikythera compare mars cli api
```

--------------------------------

### GET /api/sun

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/docs/TECHNICAL_OPERATIONS_MANUAL.md

Retrieves the position data for the sun only.

```APIDOC
## GET /api/sun

### Description
Retrieves the position data for the sun only.

### Method
GET

### Endpoint
/api/sun

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **sun_position** (object) - The calculated position of the sun.

#### Response Example
```json
{
  "sun_position": {
    "right_ascension": "10h",
    "declination": "+5°"
  }
}
```
```

--------------------------------

### Configure REPL Settings (Location, Source, Format)

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/docs/CLI-REPL.md

Sets the observer's location, data source preference, and output format within the Antikythera REPL. These settings affect subsequent commands. Valid formats include 'table', 'json', and 'compact'.

```bash
set location 29.9792,31.1342      # Giza Pyramids (lat,lon)
set source auto                   # auto uses API with circuit-breaker fallback
set format table                  # table | json | compact
```

--------------------------------

### GET /api/state

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/docs/TECHNICAL_OPERATIONS_MANUAL.md

Retrieves the complete astronomical state of the system.

```APIDOC
## GET /api/state

### Description
Retrieves the complete astronomical state of the system.

### Method
GET

### Endpoint
/api/state

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **state** (object) - The complete astronomical state data.

#### Response Example
```json
{
  "state": {
    "celestial_bodies": {},
    "observer": {},
    "timestamp": ""
  }
}
```
```

--------------------------------

### GET /api/display

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/docs/TECHNICAL_OPERATIONS_MANUAL.md

Retrieves physical device control data for display purposes.

```APIDOC
## GET /api/display

### Description
Retrieves physical device control data for display purposes.

### Method
GET

### Endpoint
/api/display

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **display_data** (object) - Physical device control data.

#### Response Example
```json
{
  "display_data": {
    "brightness": 100,
    "contrast": 50
  }
}
```
```

--------------------------------

### Antikythera Engine Command Structure

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/CLI.md

Outlines the directory structure for CLI commands within the Antikythera Engine project. It lists common commands such as `now`, `position`, `compare`, `watch`, and `validate`.

```javascript
cli/commands/
├── now.js       # Current state
├── position.js  # Specific body
├── compare.js   # Side-by-side
├── watch.js     # Live updates
└── validate.js  # Test suites
```

--------------------------------

### GET /api/planets

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/CHEAT_SHEET.md

Retrieves current data for all planets.

```APIDOC
## GET /api/planets

### Description
Retrieves current data for all planets.

### Method
GET

### Endpoint
/api/planets

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **planets** (array) - An array of objects, each representing a planet with its current data.

#### Response Example
```json
{
  "planets": [ { ... }, { ... } ]
}
```
```

--------------------------------

### GET /api/moon

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/CHEAT_SHEET.md

Retrieves current data for the Moon.

```APIDOC
## GET /api/moon

### Description
Retrieves current data for the Moon.

### Method
GET

### Endpoint
/api/moon

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **moon** (object) - An object containing current lunar data, including phase.

#### Response Example
```json
{
  "moon": { ... }
}
```
```

--------------------------------

### Debugging and Profiling Aids (Bash)

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/CLI.md

Provides options for enhanced debugging and performance insights. '--debug' shows source and timing, '--verbose' includes raw data, and '--profile' shows calculation time. These can be combined.

```bash
antikythera position mars --debug
```

```bash
antikythera position mars --verbose
```

```bash
antikythera position mars --profile
```

```bash
antikythera position mars --debug --verbose --profile
```

--------------------------------

### GET /api/sun

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/CHEAT_SHEET.md

Retrieves current data for the Sun.

```APIDOC
## GET /api/sun

### Description
Retrieves current data for the Sun.

### Method
GET

### Endpoint
/api/sun

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **sun** (object) - An object containing current solar data.

#### Response Example
```json
{
  "sun": { ... }
}
```
```

--------------------------------

### Project Structure Overview

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/README.md

This snippet outlines the directory structure of the Antikythera Engine 2 project. It details the main server file, utility and constant directories, script for validation and diagnostics, documentation folder, and a public folder for an example client.

```tree
antikythera-engine-2/
├── server.js              # Main API server
├── src/
│   ├── constants/
│   │   └── validation.js  # Validation statistics
│   └── utils/
│       └── metadata.js     # Version and git SHA extraction
├── scripts/
│   ├── validate-simple.js      # Quick validation (Moon only)
│   ├── validate-all-bodies.js  # Comprehensive HORIZONS comparison
│   └── dump-horizons.js        # HORIZONS API diagnostic tool
├── docs/
│   └── VALIDATION.md      # Complete validation methodology
└── public/
    └── index.html         # Example visualization client
```

--------------------------------

### GET /api/control/status

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/README.md

Retrieves the current status of the control system.

```APIDOC
## GET /api/control/status

### Description
Retrieves the current status of the control system.

### Method
GET

### Endpoint
`/api/control/status`

### Parameters
#### Query Parameters
None

### Request Example
```bash
curl http://localhost:3000/api/control/status
```

### Response
#### Success Response (200)
* **status** (string) - The current status of the control system.

#### Response Example
```json
{
  "status": "Running"
}
```
```

--------------------------------

### Technical Stack - Backend

Source: https://github.com/mojoatomic/antikythera-engine-2/blob/main/PROJECT_SUMMARY.md

Lists the backend technologies and versions used, including Node.js, Express, and astronomy-engine.

```plaintext
Backend
- Node.js 18+
- Express 4.x
- astronomy-engine 2.x
- CORS enabled
```