deck_in_a_dash/README.md

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.

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.
Makefile                         Single root Makefile, builds both engine/ and
                                  interpreter/, and packages a release (`make package`).

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

Building

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:

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

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:

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:

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:

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.

engine/third_party/astronomy/ is vendored from 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.