ml
bd739ccfdf
deck-engine gains --format json (language-independent, slug-based) so a new dist/interpreter-cli can score how significant a day's transits are without linking the engine itself — it depends only on the JSON shape, via its own minimal parser. Also documents the full reading pipeline end to end (CLAUDE.md, README, docs/) and adds docs/reading.md, a non-technical explanation of what a daily reading contains and means.
4.7 KiB
Your daily reading, explained
This page describes what actually happens when you get a reading — no code, no jargon you haven't already agreed to. If you just want to know "what am I looking at", start here.
The one-time setup: telling it who you are
Before you can get a personal reading, you tell it a few things about your birth, once:
- the date and time you were born, and which time zone that clock time was in
- where you were born (latitude/longitude)
That's it. This information never changes and is only used to work out exactly where the planets were, and which zodiac sign was rising, at the moment you were born — your natal chart. Everything else the app does is compared against that one fixed reference point.
What happens every day
Each day, the app does two independent things and then combines them:
- It looks at the sky right now and compares it to your natal chart from step one — this tells you what's changing today, relative to your own personal baseline (not a generic horoscope).
- It shuffles a tarot deck, using today's date as the shuffle "seed". This means: if you check your reading three times on the same day, you get the exact same 10 cards, in the same order, every time — it only changes when the date changes. There's no randomness involved beyond that; today's date fully determines today's spread.
The three parts of a reading
1. Your natal chart
A snapshot of the sky at the moment you were born: where the Sun, Moon, and each planet were, which zodiac sign was rising on the eastern horizon at that moment (your Ascendant), and which of the 12 astrological "houses" each planet falls into as a result. Think of this as your personal baseline — it doesn't change day to day, and every other part of the reading is measured against it.
2. Today's sky (your "transits")
Where the Sun, Moon, and planets are positioned today, plus:
- the current Moon phase (New, Waxing Crescent, Full, and so on)
- any aspects — meaningful angles formed between where a planet is today and where a planet sat in your natal chart. For example, "the Sun is opposite your natal Moon today" is one aspect. These are the traditional signals astrologers use to say a day is emotionally charged, a good day for decisions, a day of tension, etc. Not every day has aspects; some days are quiet.
Each planet's position today is also placed into one of your 12 houses (not a fresh chart for right now) — that's the standard way astrologers read "what house is this transit happening in for me".
3. Your tarot spread (the Celtic Cross)
A classic 10-card tarot layout, drawn from the 22 Major Arcana cards (The Fool, The Magician, and so on through The World). Each of the 10 positions asks a different question about your day or situation — for example, "what covers you right now", "what crosses/challenges you", "your hopes and fears", "the likely outcome". Every card can land upright or reversed, which traditionally shades or inverts its meaning. The order and meanings of the 10 positions, and the meaning of each card, come from A. E. Waite's original 1911 description of the spread — the same source most modern tarot decks trace back to.
How "big" is today?
Not every day is equally eventful astrologically. A separate, optional step can look at today's aspects (part 2, above) and works out an overall significance level for the day — Quiet, Notable, Significant, or Major — based on which planets are involved, how exact the angle is, and whether it touches your Sun or Moon (the two most personally weighted points in a chart). On a genuinely Major day, it also calls out the single most important thing happening, as a hint that it's worth paying closer attention to your tarot spread that day rather than treating it as routine. Quiet days still get a full reading — this step only adds a "pay attention today" flag, it never removes anything.
What a day's reading actually gives you
Put together, one day's reading contains: your natal chart (for reference), today's sky and how it's speaking to your chart, how significant today is overall, and your 10-card Celtic Cross spread for the day. Right now these sit side by side — the astrology tells you how eventful today is and where to pay attention, and the tarot spread gives you the actual guidance to sit with. They don't yet get woven into a single narrative (e.g. a spread explained in light of today's significant transit) — that combined storytelling is the next piece to build, not something you get today.
(This page, like that piece, is still a work in progress — expect it to grow as the reading itself does.)