ml
1662d550c7
- guidance.c now prints last, after the full spread; both it and main.c's new Celtic Cross readout pull real Waite card meanings via tarot_data.c instead of just naming cards. - interpreter-cli gains --format text|html|json and --lang en|de, matching deck-engine - required linking engine/src/tarot_data.c and i18n.c into the interpreter binary (a narrow, documented exception to its earlier "no engine .c files" policy) and writing German translations for narrative.c's/guidance.c's own text.
144 lines
6.6 KiB
Markdown
144 lines
6.6 KiB
Markdown
<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).
|
|
docs/ Architecture/dataflow diagrams, input/output format reference.
|
|
Makefile Single root Makefile, builds both engine/ and interpreter/.
|
|
```
|
|
|
|
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
|
|
```
|
|
|
|
Requires only a C99 compiler and `make` — no other dependencies.
|
|
|
|
## 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.
|