deck_in_a_dash/docs/input-output-format.md

# Input & output formats

See [`architecture.md`](architecture.md) for how these fit together.
There are two ways to provide input (direct CLI flags, or `run-engine.sh`
+ `user.properties`) and three output formats (`text`, `html`, `json`); the
`DailyReading` struct is the programmatic form all three are rendered
from, and the one the future watchapp will consume directly. `json` is
also `interpreter-cli`'s input format — see "The interpreter" at the
bottom of this file.

## Input

### Direct CLI flags (`dist/deck-engine`)

```
deck-engine --seed <string> --birth-date YYYY-MM-DD --birth-time HH:MM
            --birth-utc-offset <hours> --birth-lat <deg> --birth-lon <deg>
            [--date YYYY-MM-DDTHH:MM] [--format text|html|json]
```

| Flag | Required | Format | Meaning |
|---|---|---|---|
| `--seed` | yes | any string | Tarot seed. The same seed always produces the same 10-card spread, positions, and orientations (see `rng.c`/`tarot.c`). |
| `--birth-date` | yes | `YYYY-MM-DD` | Birth date, local calendar. |
| `--birth-time` | yes | `HH:MM` (24h) | Birth time, local clock. |
| `--birth-utc-offset` | yes | decimal hours, e.g. `2` or `-5.5` | Hours to **subtract** from local birth time to get UTC (e.g. `2` for CEST). |
| `--birth-lat` | yes | decimal degrees | Birth latitude, north positive. |
| `--birth-lon` | yes | decimal degrees | Birth longitude, east positive. |
| `--date` | no | `YYYY-MM-DDTHH:MM[:SS]` | UTC moment used for today's transits and as the moment the tarot seed is drawn against. Defaults to the current system time. |
| `--format` | no | `text` \| `html` \| `json` | Output format, defaults to `text`. `json` always uses language-independent identifiers, ignoring `--lang`. |
| `--lang` | no | language code, e.g. `en`, `de` | Reading language, defaults to `en`. Matches a file named `<code>.lang` in `--i18n-dir` (see "Translations" below). Unknown codes or missing files fall back to English with a warning on stderr. |
| `--i18n-dir` | no | path | Directory to look for `<lang>.lang` in. Defaults to an `i18n/` directory next to the binary itself (resolved from `argv[0]`, so `dist/deck-engine` finds `dist/i18n/` regardless of the caller's working directory). |

Birth latitude/longitude only affect the Ascendant/houses — planet signs
are geocentric and location-independent.

### `run-engine.sh` + `user.properties`

`dist/run-engine.sh [text|html|json] [lang]` wraps the binary for daily
use:

- **Seed and `--date`** come from the OS clock: `date +%Y-%m-%d` (stable
  all day) and `date -u +%Y-%m-%dT%H:%M`.
- **Birth data and language** are read from `dist/user.properties`, a
  `key=value` properties file next to the script (`#`-prefixed lines and
  blank lines are comments; whitespace around `=` is trimmed):

  ```properties
  birth_date=1990-05-14
  birth_time=14:32
  birth_utc_offset=2
  birth_lat=52.5200
  birth_lon=13.4050
  lang=en
  ```

  The file is seeded once from `engine/scripts/user.properties.template`
  with placeholder values (`YOUR_BIRTH_DATE_HERE`, etc.). `run-engine.sh`
  checks every birth field for an empty value or a leftover `YOUR_`
  placeholder and refuses to run with a clear error until the file is
  filled in; `lang` has no such check since it always has a usable
  default (`en`). Since `dist/` itself can be wiped (`make clean`, or
  deleting the directory), the build also keeps a durable backup at
  `engine/scripts/user.properties.local` (gitignored) once the file
  looks filled in, and restores from it if `dist/user.properties` is
  ever missing — see `CLAUDE.md`'s "Build & run".
- The optional second argument overrides `lang=` for a single run without
  editing the file, e.g. `dist/run-engine.sh html de`.
- `dist/run-interpreter.sh` (no arguments) is the equivalent wrapper for
  the interpreter: same OS clock + `user.properties` inputs, but calls
  `deck-engine --format json` and pipes it straight into
  `dist/interpreter-cli` — see "The interpreter" below.

### Translations (`--lang`, `dist/i18n/`)

Every piece of display text — planet/sign/moon-phase/aspect names, tarot
card names and meanings, Celtic Cross position names, and the section
headers in the `text`/`html` output — is looked up in a translation
catalog with the built-in English text as the fallback for any key the
catalog doesn't have. See `CLAUDE.md`'s "Translations" section for the
key-naming convention and how to add a new language.

`engine/i18n/en.lang` and `de.lang` are the shipped translation files;
`make` copies `engine/i18n/*.lang` to `dist/i18n/` (refreshed on every
build, like `dist/img/`). Adding a language is just dropping another
`<code>.lang` file into `engine/i18n/` — no code changes needed.

## Output

### `DailyReading` (the real output — `reading.h`)

`reading_generate()` is the actual API; `text`/`html` below are just two
ways of rendering the struct it fills in. This is what the watchapp will
read directly once it exists.

```c
typedef struct {
  NatalChart natal;
  DailyTransits transits;
  CelticCrossSpread spread;
} DailyReading;
```

- **`NatalChart`** (`astro.h`): `bodies[10]` (Sun..Pluto, each a sign +
  degree-in-sign + raw ecliptic longitude + whole-sign `house` 1-12),
  `ascendant_longitude`, `houses[12]` (whole-sign: `houses[0]` is the
  Ascendant's sign).
- **`DailyTransits`** (`astro.h`): `bodies[10]` (today's positions, same
  shape as above — `house` here is the natal chart's house the
  transiting planet currently occupies, not a fresh "houses for right
  now" chart), `moon_phase` (one of 8 named phases), `aspects[]` +
  `aspect_count` (each aspect names a transiting planet, a natal planet,
  an `AspectType` — conjunction/sextile/square/trine/opposition — and
  the orb in degrees).
- **`CelticCrossSpread`** (`tarot.h`): `positions[10]`, indexed by
  `CelticCrossPosition` (Present, Challenge, Crown, Foundation, Recent
  Past, Near Future, Attitude, Environment, Hopes and Fears, Outcome —
  Waite's own drawing order), each holding a `TarotCard` and a `reversed`
  bool.

### `--format text`

Four `=====`-delimited sections, in order: natal chart (each body's sign
+ degree + house, then the Ascendant), today's sky (Moon phase, then each
body's transiting position + the natal house it currently occupies),
today's aspects to the natal chart (one line per aspect, with orb), and
the Celtic Cross (one block per position: name, card, `(Reversed)` if
applicable, the position's meaning, then the card's meaning).

```
===== Natal Chart =====
Sun       23.5° Taurus      (House 3)
Moon      15.2° Capricorn   (House 11)
...
Ascendant  18.4° Pisces

===== Today's Sky =====
Moon phase: Waning Gibbous
Sun       11.5° Cancer      (House 5)
...

===== Today's Aspects to Natal Chart =====
Transiting Sun Opposition natal Moon (orb 3.7°)
...

===== Celtic Cross =====
The Present      The High Priestess (Reversed)
  This covers him: the general influence affecting the matter.
  Passion, moral or physical ardour, conceit, surface knowledge.
...
```

### `--format html`

A single self-contained HTML page (inline `<style>`, no JS, no external
requests) with the same four sections, plus each of the 10 Celtic Cross
cards rendered as an image:

```html
<img class="reversed" src="img/RWS_Tarot_02_High_Priestess.jpeg" alt="The High Priestess">
```

- `src="img/<file>"` is relative to the **HTML file's own location** —
  it expects to sit next to an `img/` directory, exactly like
  `dist/reading.html` next to `dist/img/` (which `make images` populates
  from `res/img/`). Saving the HTML output anywhere else breaks the
  image links.
- Reversed cards get `class="reversed"`, styled with `transform:
  rotate(180deg)` in the page's inline CSS.

### `--format json`

A single JSON object mirroring `DailyReading` exactly — `natal`,
`transits`, `spread` — using the **slug** accessors
(`astro_body_slug()`, `astro_sign_slug()`, `astro_moon_phase_slug()`,
`astro_aspect_slug()`, `tarot_card_slug()`, `tarot_position_slug()`)
rather than the display-name ones, so the output is identical regardless
of `--lang` — this is the one format meant for another program to parse
(`dist/interpreter-cli`, see "The interpreter" below), not for a human to
read.

```json
{
  "natal": {
    "bodies": [
      {"body": "sun", "sign": "taurus", "degree_in_sign": 23.4926, "ecliptic_longitude": 53.4926, "house": 3},
      ...
    ],
    "ascendant_longitude": 348.4123,
    "houses": ["pisces", "aries", ...]
  },
  "transits": {
    "bodies": [
      {"body": "sun", "sign": "cancer", "degree_in_sign": 11.5012, "ecliptic_longitude": 101.5012, "house": 5},
      ...
    ],
    "moon_phase": "waning_gibbous",
    "aspects": [
      {"transiting_planet": "sun", "natal_planet": "moon", "type": "opposition", "orb": 3.7021},
      ...
    ]
  },
  "spread": {
    "positions": [
      {"position": "present", "card": "high_priestess", "reversed": true},
      ...
    ]
  }
}
```

- `bodies` is always `NUM_BODIES` (10) entries, Sun..Pluto in `Body` enum
  order; `spread.positions` is always `TAROT_SPREAD_SIZE` (10) entries in
  `CelticCrossPosition` enum order (Present, Challenge, Crown,
  Foundation, Recent Past, Near Future, Attitude, Environment, Hopes and
  Fears, Outcome — see `CLAUDE.md`'s "Tarot" section for why that's not
  the order most tutorials use).
- `natal.houses[i]` is the sign occupying whole-sign house `i + 1`;
  `houses[0]` is the Ascendant's own sign. `transits.bodies[*].house` is
  a house number (1-12) into the **natal** chart, not a fresh "houses for
  right now" chart — same rule as the `text`/`html` output.
- All angles are decimal degrees, `%.4f`. `aspects` may be an empty array
  (a valid "no aspects today"), but the key itself is always present.

## The interpreter (`interpreter/`, `dist/interpreter-cli`)

`dist/interpreter-cli` is a separate binary — see `CLAUDE.md`'s
"Interpretation" section for the full architecture — that reads a
`--format json` document and scores how significant today's transits
are. It never links the engine; it only depends on the JSON shape
above.

```bash
dist/deck-engine ... --format json | dist/interpreter-cli
# or:
dist/deck-engine ... --format json > reading.json
dist/interpreter-cli reading.json
# or, for daily use (OS clock + user.properties, same inputs as run-engine.sh):
dist/run-interpreter.sh
```

- **Input**: a file path argument, or stdin if no argument (or `-`) is
  given. `"transits"."aspects"` is required (an empty array is valid and
  means "no notable transits today"; a missing key is treated as invalid
  input) and drives scoring. `"natal"."bodies"`/`"transits"."bodies"` are
  read too, for the sign/house context printed alongside each event below
  (not for scoring) — an entry naming an unrecognized body, or a missing
  `house`, is silently skipped rather than failing the load (see
  `parse_bodies()` in `reading_io.c`); `spread` is always ignored.
- **Output**: a plain-text report — the day's overall significance level
  (`Quiet`/`Notable`/`Significant`/`Major`, plus its rank out of the 4
  defined levels, e.g. `Notable (2/4)`), a "worth a deeper Celtic Cross
  look" line on `Major` days only, and up to 5 of today's aspects ranked
  by score, each naming the sign and natal house the transiting planet
  currently occupies and the sign and house of the natal planet it's
  aspecting, followed by a short narrative sentence about what that
  transiting planet classically signifies *and which area of life its
  current house governs* (see `CLAUDE.md`'s `narrative.c` bullet) —
  omitted only if the source material has nothing to say for that
  planet/aspect combination:

  ```
  Day significance: Significant (3/4)
  (a major transit today - worth a deeper Celtic Cross look)

  Top 3 significant transits:
    1. Transiting Saturn in Aries (house 2) Square natal Sun in Taurus (house 3) (orb 0.5°, score 8.10)
       In matters of money, possessions, and personal values (house 2). Brings depression, stagnation, hindrances and obstacles, and some deprivation of the usual benefits.
    2. Transiting Pluto in Aquarius (house 12) Opposition natal Moon in Capricorn (house 11) (orb 0.2°, score 7.92)
       In matters of solitude, the subconscious, and hidden matters (house 12). Brings deep, often hidden transformation - the surfacing or dismantling of something that has outgrown its old form.
    3. Transiting Jupiter in Leo (house 5) Trine natal Venus in Aries (house 2) (orb 2.1°, score 3.40)
       In matters of romance, creativity, and children (house 5). Brings increase and expansion - fullness of fortune and health, and a generally fortunate time.
  ```