astral-transit-snapshot

Astral Transit Snapshot

When to use

Use when the user asks "what are the transits now?", "what's hitting my chart?", "any big transits today?", or any short, present-tense ask about current sky activity in relation to a natal chart. This is the succinct transit skill — not a full reading, not a calendar.

For long horizons / calendar feeds / .ics files → use astral-transit-calendar. For a full multi-lens reading → use astrology-reading-compose.

Parameters

• subject (optional) — whose chart the transits should be measured against.
• Default: the user's own natal chart (self profile in tenant KB, falling back to USER.md birth data).
• When the user names someone else ("transits on Kathleen", "what's hitting my brother's chart"), apply astral-tenant-kb's disambiguation policy (slug → name → alias → fuzzy → none) to resolve the subject. If ambiguous, ask before computing.
• focus (optional) — a life-area hint ("career", "relationship", "health") to bias the synthesis. Never invented; only if supplied.

Required workflow

1. Time + subject

• Capture wall-clock UTC and the user's local time. For Alex: TZ=America/Los_Angeles date '+%Y-%m-%d %H:%M %Z' plus date -u '+%Y-%m-%dT%H:%M:%SZ'.
• Resolve the subject. For self, pull birth data from the tenant KB self profile or USER.md. For other, recall via astral-tenant-kb (scripts/kb.py recall_person <name>).

2. Get current transits

curl -sS https://transit-list-demo.apps.poofc.com/api/transits/current

Returns current positions (sign, degree) for all planets + nodes.

3. Get / load natal chart

If a cached chart exists in the KB (charts/<slug>-<hash>.json), load it. Otherwise compute:

curl -sS "https://transit-list-demo.apps.poofc.com/api/chart?utc=DD/MM/YYYY/HH/mm/0&coordinates=LAT%20LON"

Then save via kb.py save_chart.

4. Compute transit→natal aspects in code (the snapshot core)

The API doesn't return a ranked transit-to-natal aspect list, so compute it locally. Compare every transiting body's longitude to every natal planet/angle (Asc, MC, IC, Desc included).

Aspects: conjunction (0°), opposition (180°), trine (120°), square (90°), sextile (60°). Optionally semi-square (45°) and quincunx (150°) if the orb is very tight.

Orb rules (snapshot — tighter than calendar): | Transiting body | Orb | |---|---| | Moon | 1.0° | | Mercury, Venus, Mars, Nodes | 1.5° | | Sun | 2.0° | | Jupiter, Saturn | 2.0° | | Uranus, Neptune, Pluto | 1.5° |

Tighter than calendar orbs because a snapshot is about what's loud right now, not what's possible across a window.

Rank by exactness: sort by absolute orb ascending. The tightest 3–5 aspects are the headline.

Tag applying vs separating if you can compute it (transit speed vs natal position): applying = sharper, near-future; separating = fading. If you can't compute speed reliably, omit the tag rather than guess.

5. Layer fast-mover spotlight

Independent of the ranked aspect list, surface what the fast movers (Moon, Mercury, Venus, Sun, Mars) are doing right now: - What sign + house they're in (use the natal house framework). - Any current aspect to a personal natal body or angle that's within orb. - Any imminent ingress within ~48 hours (use a quick scan: take the body's current longitude and current daily speed; if it crosses a sign boundary within 48h, mention it).

These short-term layers are what give the snapshot its temporal punch.

Reply formatting (succinct)

Aim for a mobile-readable response — short, scannable, no walls of text. Strict order:

1. Header line. One line, italic: subject name + local time + UTC.

   Alex · 2026-05-23 08:30 PDT (15:30 UTC)

2. 🎯 Exact now (the headline). A bulleted list of the 3–5 tightest transit→natal aspects, in transit-first format:

   • Moon ☌ natal Venus — 0°12′ (applying) — Cancer 14° • Mars △ natal Sun — 0°48′ — Scorpio 4° → Libra 3° • Saturn □ natal Mercury — 1°30′ (separating) — Pisces 18° → Sagittarius 19°

Bold the aspect, show exact orb in degrees/minutes, tag applying/separating only if confidently computed.

3. 🌙 Fast layer. 2–4 short bullets on Moon / Mercury / Venus / Sun / Mars positions and any sign change within 48h. House placement (in the natal chart) in parentheses.

   • Moon in Cancer (4th) — quiet/private register today • Mercury 28° Gemini → enters Cancer in ~14h

4. 📖 Story (1 short paragraph). 2–4 sentences synthesizing the headline aspects into a coherent present-moment picture. Lead with the tightest aspect — that's the most temporally significant signal. If a focus was supplied, tie it in here. No long lists. No "folk" language.

5. One-breath summary. A single bold sentence at the bottom.

If there are NO aspects within snapshot orbs, say so plainly and lean on the fast-layer + sign/house framing for the story. Don't pad.

Pitfalls

• Don't echo the calendar. Calendar-orb aspects (3°+) belong in astral-transit-calendar. The snapshot is the exact-now layer.
• Don't invent applying/separating. If you don't have transit-body daily motion, omit the tag.
• Don't read slow-planet aspects as short-term. A Pluto square within orb has been there for months and will be there for months — frame it as backdrop, not breaking news. Lead with fast-mover aspects when they're tight.
• Subject defaults to the user. Never silently switch to Alex when someone else asks for their own chart in another tenant.
• Disambiguation is non-negotiable if the user names someone whose slug/alias is ambiguous in the KB — ask before computing (per astral-tenant-kb policy).
• No invented focus. If the user didn't supply one, read generally.
• Transit-first labeling. Always <transit body> <aspect> natal <natal body> in the user-facing summary, never the reverse.
• Stay grounded. Use API output for positions. Do not estimate longitudes from memory.

Verification

• curl -sS https://transit-list-demo.apps.poofc.com/api/health returns ok.
• The tightest reported orb in the headline list must be ≤ the orb table above for its transiting body.
• Subject's birth data (or the canonical resolved chart) is the one referenced — confirm slug/utc match before computing.