deck_in_a_dash/README.md

<p align="center">
  <img src="res/logo.png" width="290" 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.

This repository holds the core engine: 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, designed so
it links straight into Pebble watch code 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 and Sepharial PDFs, 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-engine.sh, run-interpreter.sh, and
                                  the user.properties template.
dist/                            Build output (gitignored) — see below.
interpreter/                     Separate module + binary (dist/interpreter-cli):
                                  scores how significant a day's transits are,
                                  reads out the full Celtic Cross spread with
                                  every card's meaning, and closes with guidance
                                  (every day, tailored to how significant it is)
                                  tying the top transit to the spread, reading
                                  deck-engine's --format json output. Supports
                                  --format text|html|json and --lang en|de for
                                  its own output too (see CLAUDE.md).
watch/                            The actual Pebble watchapp - links engine/src/
                                  and interpreter/src/ in directly (see CLAUDE.md's
                                  "Portability to the watch"), plus its own
                                  persistence, reading recompute, UI, daily
                                  notification, and config page. Built separately
                                  from the rest of this repo (`make watchapp`,
                                  below) - requires the Pebble SDK.
docs/                            Architecture/dataflow diagrams, input/output format reference.
build-image/                     Dockerfile for the reproducible build environment
                                  (C toolchain + Pebble SDK) used by CI and by the
                                  build-image.sh/run-image.sh/upload-image.sh scripts
                                  at the repo root (see "Building" below).
Makefile                         Single root Makefile, builds both engine/ and
                                  interpreter/, and packages a release (`make package`).
```

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
make          # -> dist/deck-engine, dist/interpreter-cli, dist/img/, dist/i18n/,
              #    dist/run-engine.sh, dist/run-interpreter.sh, dist/user.properties
make test     # builds and runs engine/tests/smoke_test.c and interpreter/tests/*_test.c
make package  # -> dist/deck-in-a-dash-<version>-linux-<arch>.tar.gz, a
              #    self-contained release bundle (binaries, scripts, img/, i18n/,
              #    LICENSE, docs) - version from the current git tag, or
              #    VERSION=1.2.3 make package to override
```

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

**Building the watch app itself** (`watch/`, the actual Pebble app)
needs the separate Pebble SDK (`pebble` on `PATH`), so it's a separate
target, not part of `make`/`make test`/`make package` above:

```bash
make watchapp # -> dist/deck-in-a-dash-<version>.pbw, same version
              #    resolution as `make package`
```

**CI runs `make watchapp` too** — `.gitea/workflows/build.yml` builds
and tests everything inside a container built from `build-image/`,
which bundles the Pebble SDK alongside the C toolchain so the runner
itself doesn't need either installed. To build/test that image
yourself, copy `registry.env.example` to `registry.env` and fill in
your registry credentials, then:

```bash
./build-image.sh   # build and locally tag the image
./run-image.sh     # run `make test package watchapp` inside it, against
                    # this checkout, for a CI-equivalent local build
./upload-image.sh  # push the image so CI can pull it
```

## Running

**Daily use**, via `dist/run-engine.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-engine.sh              # text output, language from user.properties (default en)
dist/run-engine.sh html          # HTML report with card art, open in a browser
dist/run-engine.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|json] [--lang en|de]
```

**Interpreter** (`interpreter/`, built by the same root `make`):
scores how significant a day's transits are, reads out the full Celtic
Cross spread with every card's meaning, and closes with guidance tying
the day's biggest transit to the Attitude/Outcome cards - reading
`deck-engine`'s `--format json` output. Its own output supports the same
`--format text|html|json` and `--lang en|de` as `deck-engine` (note this
`--lang` is independent of whatever language `deck-engine` was run
with - `--format json` is always language-independent, see
`docs/input-output-format.md`). `dist/run-interpreter.sh` is the
daily-use equivalent of `run-engine.sh` (same OS clock + `user.properties`
inputs, including `user.properties`' `lang=`), piping straight into
`interpreter-cli`:

```bash
dist/deck-engine ... --format json | dist/interpreter-cli [--format text|html|json] [--lang en|de]
# or, for daily use:
dist/run-interpreter.sh              # text output, language from user.properties
dist/run-interpreter.sh html de      # HTML report with card art, override the language
```

## License

The engine source code in this repository (`engine/src/`, `engine/scripts/`)
and the root `Makefile` are 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.

Transit narrative text in `interpreter/src/narrative.c` is condensed
from Sepharial's *Transits and Planetary Periods* (1920), also in the
public domain, except the Moon and Pluto entries, which are original
(see the file's own comment).

Guidance text in `interpreter/src/guidance.c` is original, written for
this project.

`engine/i18n/de.lang`'s translations of the above two files' text
(`narrative.*`/`guidance.*` keys) are original German translations made
for this project, same status as its card/spread text.