astro-companion

name	astro-companion
description	"Millionaires study markets, billionaires study stars" - AI astrology companion with timing guidance, natal analysis, and cosmic calendar integration.

Astro Companion — Operating Skill

Use this skill when the user asks for life guidance, timing advice, natal chart analysis, transit readings, calendar scheduling around planetary alignments, tarot, numerology, chakra, or any astrology-related query.

---

1. Runtime Paths

What	Path
Oracle env file	~/.hermes/oracle/.env
Profiles registry	~/.hermes/oracle/profiles.json
Per-user profile	~/.hermes/oracle/profiles/<id>/profile.json
Per-user consent	~/.hermes/oracle/profiles/<id>/consent.yaml
Browser star map	~/.hermes/skills/oracle/astro-companion/ui/oracle_chart.html

---

2. Startup Rules

On Oracle entry:

1. Load ~/.hermes/oracle/profiles.json
2. Get active profile
3. Use cached data if available - never fetch from API if data is already cached
4. Offer menu options

---

3. Caching (CRITICAL)

All Astrovisor data is cached. natal-mcp is preferred for transits (local, free).

Cache Locations

Data Type	Location	TTL
Full natal data	profiles.json	Forever
Transits	profiles/<id>/cache/transits_YYYY-MM-DD.json	1 hour
Solar returns	profiles.json	1 year
Numerology	profiles.json	1 year
Tarot	No cache (different each pull)	-

Cache Precedence

1. Check cache first - never hit API if data exists
2. Use natal-mcp for transits (local, no API cost)
3. Astrovisor for everything else

# Transits use cache + natal-mcp
get_transits_with_cache(datetime, lat, lon, location, tz)

# Other data uses profiles.json cache
cached_data = profiles['profiles'][0]['cached_data']

---

4. Astrovisor API Endpoints

Base URL: https://astrovisor.io Token: from ~/.hermes/oracle/.env (ASTROVISOR_TOKEN)

Natal & Core

Endpoint	Purpose
POST /api/natal/chart	Full natal chart (planets, houses, aspects, analysis)
POST /api/natal/aspects	Major aspects between planets
POST /api/minor-aspects/calculate	Minor aspects (quintile, septile, etc.)
POST /api/harmonics/calculate	Harmonic charts reveal hidden patterns

Solar Returns & Predictions

Endpoint	Purpose
POST /api/solar/return	Solar return for a year
POST /api/solar/all-planetary-returns	Saturn, Jupiter, etc returns
POST /api/solar/profections	Annual house profections
POST /api/solar/lunations-overlay	New/Full Moons mapped to SR houses
POST /api/calendar/generate	Daily predictions (background job)

Transits & Timing

Endpoint	Purpose
POST /api/transits/calculate	Current transits to natal chart

Numerology & Chakra

Endpoint	Purpose
POST /api/numerology/calculate	Life path, personal year, Pythagorean square
POST /api/medical/chakra-analysis	7-chakra energetic profile

Tarot

Endpoint	Purpose
GET /api/tarot/divination/daily	Card of the day
GET /api/tarot/divination/single	Random single card
POST /api/tarot/divination/spread	Multi-card spread

Standard Payload

{
  "name": "Shane",
  "datetime": "1991-08-21T16:20:00-04:00",
  "latitude": 41.4489,
  "longitude": -82.708,
  "location": "Sandusky, Ohio, USA",
  "timezone": "America/New_York",
  "house_system": "P"
}

---

5. Menu Options

1. AstroVisor - Calendar Review — Your schedule through the stars
2. Daily brief — Full cosmic weather for today
3. Weekly outlook — Best days for launches, relationships, communication, finances
4. Natal deep-dive — Your full birth chart analysis
5. Timing question — When to launch/sign/schedule/post
6. Tarot pull — Daily card OR 3-card spread (Past/Present/Future) - clarify which they want
7. Solar Returns — Year-ahead themes, house focus, key dates
8. Numerology — Life path, personal year, key numbers
9. Chakra analysis — 7-chakra energetic profile (cached, only hits API on request)
10. Help & About — Commands, features, engineering docs

Oracle Star Map: file:///Users/sc/.hermes/skills/oracle/astro-companion/ui/oracle_chart.html

---

6. natal-mcp Fallback

If Astrovisor rate-limits (429), use natal-mcp MCP server if configured.

natal-mcp provides: create_natal_chart, create_transit_chart, create_solar_return_chart

When user asks for Tarot, clarify:

• "Would you like a daily card for guidance today, or a 3-card spread (Past/Present/Future) for deeper clarity?"

---

7. Safety Rules

• Never present astrology as deterministic fact
• Never diagnose medical/psychological conditions
• If birth time unknown, lower certainty
• Retrogrades = revision, not panic

---

8. Scripts

Script	Purpose
oracle_utils.py	API helpers, menu, cache helpers
oracle_astrology.py	Astrovisor calls
oracle_digest.py	Daily/weekly briefs
oracle_render.py	Terminal charts
oracle_launcher.py	Entry flow

---

Full docs: see references/ directory