--- name: transit-tarot-spread description: "Compute the most significant transit→natal aspects (Sun–Saturn only, 2° orb, ranked by time-to-exact), pull the Rider–Waite minor arcana card for each transiting planet's current decan, and composite the cards into a layout shaped by the count. Pairs astrology + tarot — the sky tells us which cards to draw and how to lay them out." version: 0.1.0 author: Hermes Agent + Alex license: MIT metadata: hermes: tags: [astrology, tarot, transits, decans, composite, spread] related_skills: [astral-transit-snapshot, astrology-lens-decans-36-faces, astral-chart-api, astral-tenant-kb] --- # Transit-Driven Tarot Spread The sky picks the cards. The number of qualifying transits picks the shape. ## When to use User asks: "draw me a tarot spread from my current transits", "what tarot cards are the sky pulling for me right now", "transit tarot reading", or any variant of *let the transits dictate a tarot pull*. This is **not** a generic daily-card skill — it's specifically transit-driven and uses decan correspondences. For a written transit reading without cards → `astral-transit-snapshot`. For decan ↔ tarot mapping reference → `concepts/decan-tarot-correspondences.md` in `astro-sources-wiki`. ## Selection rules (the contract) 1. **Bodies considered (transiting AND natal):** Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn. **Exclude outer planets** (Uranus/Neptune/Pluto) and Nodes from both sides. 2. **Natal points also valid:** Asc, MC (as natal targets only). 3. **Aspects:** conjunction (0°), opposition (180°), trine (120°), square (90°), sextile (60°). 4. **Orb:** **2.0° max**, all bodies. Tighter orb ranks higher, but the primary sort key is time-to-exact (see below). 5. **No cap on card count** — if 8 qualify, draw 8. If 0 qualify, say so and stop (do NOT pad). 6. **Decan side = transiting planet.** The card pulled corresponds to the *transiting* planet's current decan (sign + face-i/ii/iii by degree). 7. **Sequence ordering = combined score weighted toward planetary speed.** See ranking formula below. 8. **No centered/anchor card. No reversals.** ## Ranking formula For each qualifying aspect: ``` exact_diff_deg = target_aspect_angle - current_angular_separation # signed hours_to_exact = (exact_diff_deg / transit_speed_deg_per_day) * 24 # signed: + applying, - separating score = abs(hours_to_exact) if applying else abs(hours_to_exact) * 1.5 ``` Sort ascending by `score`. Lowest = position 1 in the spread. This natively combines (a) how close the aspect is to exact and (b) how fast the transiting body is moving, because a fast planet covers a 1° orb in hours while Saturn takes weeks. Moon at 1° orb applying ≈ a few hours; Saturn at 1° orb applying ≈ ~2 weeks. The Moon wins position 1. Separating aspects are penalized 1.5× because they are fading rather than building. ## Layout shapes (count-driven, semantically positioned) Layouts are not abstract geometry — each count maps to a recognized classical spread, with named slots. Rank order maps to slot order below (rank-1 hit → slot 1). | N | Spread | Slot 1 | Slot 2 | Slot 3 | Slot 4 | Slot 5 | Slot 6 | Slot 7 | Slot 8 | |---|---|---|---|---|---|---|---|---|---| | 1 | Daily Draw | the signal | | | | | | | | | 2 | Side-by-side pair | left | right | | | | | | | | 3 | Past / Present / Future (row) | past (L) | present (C) | future (R) | | | | | | | 4 | Four-card cross | situation (L) | obstacle (R) | advice (bottom) | outcome (top) | | | | | | 5 | Five-card cross with center | situation (center) | unconscious infl. (L) | conscious infl. (R) | way through (bottom) | outcome / resolution (top) | | | | | 6 | Two rows of three | top-L | top-C | top-R | bot-L | bot-C | bot-R | | | | 7 | Horseshoe arc | past | present | hidden | obstacles | external | advice | outcome | | | 8 | Two rows of four | top-1 | top-2 | top-3 | top-4 | bot-1 | bot-2 | bot-3 | bot-4 | Positions ascend in **rank order** — the lowest-score (fastest-to-exact-and-tightest) aspect always lands in slot 1. Captions on the composite image show the slot label, the card name, the transit aspect, and the orb. ## Workflow 1. **Time + subject.** Capture UTC + local time. Resolve subject via `astral-tenant-kb` (default = self). 2. **Pull current transits.** `curl -sS https://transit-list-demo.apps.poofc.com/api/transits/current` — includes `speed`. 3. **Load natal chart** (cached or computed via the chart API). 4. **Compute aspects** (Sun–Saturn only on both sides; include Asc/MC as natal targets). Apply 2° orb. 5. **Rank** by the formula above. 6. **Map each transiting planet to its decan card** using `concepts/decan-tarot-correspondences.md`: - decan index = `floor(degree_in_sign / 10)` → I (0), II (1), III (2) - Look up card + asset path from the table. 7. **Pick layout shape** from the count table. 8. **Generate composite image** via `scripts/compose_spread.py` (see scripts/). Output → `/tmp/transit-tarot-spread-.png`. 9. **Reply** with: - Header line (subject + local + UTC) - Numbered list of positions: `**N. ** — natal · orb °′ · · exact in ~` - One short paragraph: what this constellation of cards is saying (lead with position 1). - `MEDIA:/tmp/transit-tarot-spread-.png` so the image renders. ## Pitfalls - **Layouts must be classical/semantic, not abstract geometry.** Alex's explicit preference: when count maps to a recognized spread (3-card row, 4-card cross, 5-card cross with center, horseshoe, etc.), use the spread's named slots — don't default to pentagons/hexagons/octagons just because they fit N points evenly on a circle. The slot semantics ARE the reading. See the layout table above for the canonical mapping. - **Don't draw a card without an aspect.** If zero qualify within 2°, tell the user the sky is quiet — don't pad with random pulls. - **Don't include outer planets** even if their orbs are very tight. The user explicitly excluded them. - **Use the transiting decan, not the natal decan.** Easy to confuse on a transit→natal aspect. - **Boundary degrees:** 9.99° = face I, 10.00° = face II, 19.99° = face II, 20.00° = face III. - **Sign change risk:** if a planet is at e.g. 29°55′ Gemini moving direct, the decan it's in *now* (Gemini III) is the answer for *this moment*, even though it crosses into Cancer in hours. Don't anticipate the ingress. - **Speed sign matters.** Retrograde planets have negative speed — handle separating/applying correctly. A retrograde planet "applying" to an aspect means the angular separation is shrinking even though the planet is moving backward. - **Card images path:** `/home/avalon/apps/alexTarot/public/cards/.jpg`. Card metadata source of truth: `/home/avalon/apps/alexTarot/public/tarot-images.json`. - **Don't standardize the layout.** The shape MUST follow the count table — that's the user's explicit preference. Don't always do a row of 5. ## Verification - [ ] All ranked aspects are Sun–Saturn on both sides (no Uranus/Neptune/Pluto/Nodes). - [ ] Tightest orb in the list ≤ 2.0°. - [ ] Each card filename exists in `/home/avalon/apps/alexTarot/public/cards/`. - [ ] Composite image has exactly N cards arranged in the count-driven shape, each labeled 1..N. - [ ] Position 1 is the lowest-score (fastest-to-exact-and/or-tightest) aspect.