<p align="center">
  <img src="res/logo.png" width="200" alt="Deck in a Dash logo">
</p>

# Deck in a Dash

A Pebble smartwatch app that produces a daily personalized tarot (Celtic
Cross) and astrology (natal chart + transits) reading.

**Status:** only the core engine exists so far — a plain-C, dependency-free
library and standalone CLI (`dist/deck-engine`) that computes a full
reading without needing a Pebble device, emulator, or SDK. The watchapp
itself hasn't been built yet; the engine is designed so it can be linked
into it later without rework.

## What it computes

- **Astrology**: a personalized natal chart (Sun through Pluto, plus the
  Ascendant and whole-sign houses) from a birth date, time, and location,
  and the day's transits — including moon phase and aspects — against
  that chart.
- **Tarot**: a 10-card Celtic Cross spread, drawn from the 22 Major
  Arcana, with upright/reversed orientation per card. The full spread is
  deterministic: the same seed string always produces the same cards, in
  the same positions, with the same orientations. Card meanings and
  spread positions are sourced from A. E. Waite's *The Pictorial Key to
  the Tarot* (1911, public domain), in his own original drawing order.

Readings are available in **English and German** (`--lang en`/`--lang
de`, or `lang=` in `user.properties`); adding another language is just
dropping a translated `key=value` file into `engine/i18n/` — see
[`docs/input-output-format.md`](docs/input-output-format.md).

## Repository layout

```
res/                             Tarot card art (22 RWS Major Arcana), the
                                  Waite PDF, logo, research notes.
engine/
  third_party/astronomy/         Vendored cosinekitty/astronomy C library (MIT).
  src/                           Engine source (rng, tarot, astro, i18n, reading, CLI).
  i18n/                          Translation files (en.lang, de.lang, ...).
  tests/smoke_test.c             Determinism, ephemeris, and i18n regression checks.
  scripts/                       run.sh and the user.properties template.
  Makefile
dist/                            Build output (gitignored) — see below.
docs/                            Architecture/dataflow diagrams, input/output format reference.
```

See [`CLAUDE.md`](CLAUDE.md) for the detailed architecture and the sharp
edges worth knowing before changing the engine, or the
[`docs/`](docs/) directory for diagrams
([`docs/architecture.md`](docs/architecture.md)) and the full CLI/file/
struct format reference
([`docs/input-output-format.md`](docs/input-output-format.md)).

## Building

```bash
cd engine
make          # -> dist/deck-engine, dist/img/, dist/i18n/, dist/run.sh, dist/user.properties
make test     # builds and runs engine/tests/smoke_test.c
```

Requires only a C99 compiler and `make` — no other dependencies.

## Running

**Daily use**, via `dist/run.sh`: pulls today's date and the current UTC
time from the OS clock (used as the tarot seed and the transit moment)
and reads your birth data from `dist/user.properties`. Edit that file
first — it's seeded once from a placeholder template and is never
overwritten by later builds:

```bash
dist/run.sh              # text output, language from user.properties (default en)
dist/run.sh html          # HTML report with card art, open in a browser
dist/run.sh html de       # override the language for this run
```

**Direct CLI**, with every input explicit:

```bash
dist/deck-engine --seed "2026-07-03" \
  --birth-date 1990-05-14 --birth-time 14:32 --birth-utc-offset 2 \
  --birth-lat 52.5200 --birth-lon 13.4050 \
  [--date YYYY-MM-DDTHH:MM] [--format text|html] [--lang en|de]
```

## License

The engine source code in this repository (`engine/src/`, `engine/scripts/`,
`engine/Makefile`) is released under the **MIT License** — see
[`LICENSE`](LICENSE).

`engine/third_party/astronomy/` is vendored from
[cosinekitty/astronomy](https://github.com/cosinekitty/astronomy) (MIT,
unmodified) — see its `VENDORED.md` for the pinned commit.

Card and spread text in `engine/src/tarot_data.c` is condensed from A. E.
Waite's *The Pictorial Key to the Tarot* (1911), which is in the public
domain.