docs: globalize examples, front-load high-demand keywords, sync domains to 12+

Lead-with-global: the Western examples (natal chart, daily horoscope, synastry,
human design, forecast) use global cities while the Vedic section keeps Indian
coordinates. The README opening now front-loads the high-demand surface (natal
charts, daily horoscopes, synastry, Vedic kundli, tarot spreads, numerology,
human design bodygraphs, transit forecasts). Domain count reads 12+ and the
breadth lists include human design and forecast.

Author: ph33nx

AGENTS.md

@@ -1,6 +1,6 @@
 # roxy-sdk (Python) - Agent Guide
 
-Python SDK for RoxyAPI. Spiritual domains (Western astrology, Vedic astrology, numerology, tarot, Human Design, forecast, biorhythm, I Ching, crystals, dreams, angel numbers) plus utility namespaces (location, usage, languages). One API key, sync and async.
+Python SDK for RoxyAPI. 12+ domains (Western astrology, Vedic astrology, numerology, tarot, human design, forecast, biorhythm, I Ching, crystals, dreams, angel numbers, location) plus utility namespaces (usage, languages). One API key, sync and async.
 
 ## Install and initialize
 
@@ -31,16 +31,16 @@ roxy = create_roxy("your-api-key")
 Every chart, horoscope, panchang, dasha, dosha, navamsa, KP, synastry, compatibility, and natal endpoint needs `latitude`, `longitude`, and (for Western) `timezone`. **Never ask the user for coordinates.** Always call `roxy.location.search_cities` first.
 
 ```python
-result = roxy.location.search_cities(q="Mumbai")
+result = roxy.location.search_cities(q="New York")
 city = result["cities"][0]
 lat, lng, tz = city["latitude"], city["longitude"], city["timezone"]
-# `timezone` is the IANA string ("Asia/Kolkata"). Pass it directly to any chart endpoint.
+# `timezone` is the IANA string ("America/New_York"). Pass it directly to any chart endpoint.
 # The server resolves it to the DST-correct decimal offset using the request's own date,
 # so a January 1990 New York chart gets EST (-5) even when you looked the city up in July.
 # If you prefer numbers, city["utcOffset"] (decimal: 5.5, -5, ...) also works.
 ```
 
-`q` accepts bare city (`"Mumbai"`), city + country (`"Berlin Germany"`), or comma-qualified (`"Springfield, Illinois"`). Use the qualified form to disambiguate same-named cities.
+`q` accepts bare city (`"Paris"`), city + country (`"Berlin Germany"`), or comma-qualified (`"Springfield, Illinois"`). Use the qualified form to disambiguate same-named cities.
 
 ## Domains
 
@@ -68,7 +68,7 @@ Type `roxy.` to see all available namespaces. Type `roxy.{domain}.` in an IDE wi
 ### Two-step pattern for coordinate-dependent endpoints
 
 ```python
-result = roxy.location.search_cities(q="Delhi")
+result = roxy.location.search_cities(q="London")
 city = result["cities"][0]
 
 chart = roxy.astrology.generate_natal_chart(
@@ -102,7 +102,7 @@ Most valuable endpoints are POST:
 ```python
 natal = roxy.astrology.generate_natal_chart(
     date="1990-01-15", time="14:30:00",
-    latitude=28.6139, longitude=77.209, timezone="Asia/Kolkata",
+    latitude=40.7128, longitude=-74.006, timezone="America/New_York",
 )
 
 kundli = roxy.vedic_astrology.generate_birth_chart(
@@ -195,7 +195,7 @@ Ordered by domain priority (Western, Vedic, Numerology, Tarot, Human Design, For
 | Dream symbol lookup | `roxy.dreams.get_dream_symbol(id="flying")` |
 | Angel number meaning | `roxy.angel_numbers.get_angel_number(number="1111")` |
 | Universal number lookup | `roxy.angel_numbers.analyze_number_sequence(number="1234")` |
-| Find city coordinates | `roxy.location.search_cities(q="Mumbai")` |
+| Find city coordinates | `roxy.location.search_cities(q="Berlin")` |
 | Check API usage | `roxy.usage.get_usage_stats()` |
 | List supported languages | `roxy.languages.list_languages()` |
 
@@ -208,8 +208,8 @@ These are the fields AI agents most often get wrong. Copy the format column exac
 | `timezone` | IANA string (typed kwarg) OR decimal number (inside a `dict[str, Any]`) | `"Asia/Kolkata"`, `"America/New_York"`, `"Europe/London"` as the top-level `timezone=` kwarg (server resolves to the DST-correct offset for the chart date). Decimal hours (`5.5`, `-5`, `0`) work as JSON numbers and are accepted only inside `person1`/`person2` dicts because the dict is typed `dict[str, Any]` - the top-level `timezone=` kwarg is typed `str`, so a quoted decimal like `"5.5"` is rejected server-side (validation_error). | `"5.5"` as `timezone=` (rejected, server expects IANA string or a JSON number), `"5:30"`, `"+0530"`, `"GMT-5"` |
 | `date` | ISO date string | `"1990-01-15"` | `"Jan 15 1990"`, `datetime.now()`, `"15/01/1990"`, `"1990-1-15"` |
 | `time` | 24-hour string | `"14:30:00"`, `"09:00:00"` | `"2:30 PM"`, `"14:30"` (no seconds), `"9:0:0"` (no leading zeros) |
-| `latitude` | Decimal degrees (float) | `28.6139` (Delhi), `-33.8688` (Sydney), `40.7128` (NYC) | `"28°36'N"`, `"28 36 50"`, strings |
-| `longitude` | Decimal degrees (float) | `77.209` (Delhi), `-74.006` (NYC), `139.6917` (Tokyo) | Same as latitude - no DMS strings |
+| `latitude` | Decimal degrees (float) | `51.5074` (London), `-33.8688` (Sydney), `40.7128` (NYC) | `"28°36'N"`, `"28 36 50"`, strings |
+| `longitude` | Decimal degrees (float) | `-0.1278` (London), `-74.006` (NYC), `139.6917` (Tokyo) | Same as latitude - no DMS strings |
 | `sign` (horoscope kwarg) | Lowercase zodiac name | `"aries"`, `"taurus"`, `"gemini"`, ... `"pisces"` | `"Aries"`, `"♈"`, `"1"`, `"ARIES"` (case-insensitive but prefer lowercase) |
 | `full_name` (numerology) | Birth-certificate name | `"John William Smith"`, `"Priya Rajesh Sharma"` | Nickname, married name, partial name - affects all letter-based calcs |
 | `seed` | Any string (deterministic) | `"user-42"`, `"session-abc-123"`, email hash | Numbers, objects - must be string |
@@ -226,7 +226,7 @@ These are the fields AI agents most often get wrong. Copy the format column exac
 
 ### Timezone cheat sheet (most-asked locations)
 
-Values are decimal hours. For the typed top-level `timezone=` kwarg, pass the IANA name from `roxy.location.search_cities` (`timezone="Asia/Kolkata"`) - the server resolves it to the correct DST offset for the chart date. Inside a `person1`/`person2` dict the bare decimal works because the dict is typed `dict[str, Any]`, so the JSON-number form below is accepted.
+Values are decimal hours. For the typed top-level `timezone=` kwarg, pass the IANA name from `roxy.location.search_cities` (`timezone="America/New_York"`) - the server resolves it to the correct DST offset for the chart date. Inside a `person1`/`person2` dict the bare decimal works because the dict is typed `dict[str, Any]`, so the JSON-number form below is accepted.
 
 
 | Region | Decimal | Region | Decimal |

README.md

@@ -16,7 +16,7 @@ Python SDK for astrology, Vedic astrology, tarot, numerology, and more.
 
 One API key. Sync and async (every method has an `_async` suffix). Verified against NASA JPL Horizons.
 
-The fastest way to add natal charts, kundli matching, daily horoscopes, tarot readings, and spiritual insights to FastAPI, Django, Flask, or any Python project. Twelve domains behind a single [Roxy](https://roxyapi.com) subscription, interpretations in eight languages.
+The fastest way to add natal charts, daily horoscopes, synastry, Vedic kundli, tarot spreads, numerology, human design bodygraphs, and transit forecasts to FastAPI, Django, Flask, or any Python project. 12+ domains behind a single [Roxy](https://roxyapi.com) subscription, interpretations in eight languages.
 
 ## Install
 
@@ -47,22 +47,22 @@ from roxy_sdk import create_roxy
 roxy = create_roxy("your-api-key")
 
 # Step 1: geocode the birth city (required for any chart endpoint)
-result = roxy.location.search_cities(q="Mumbai, India")
+result = roxy.location.search_cities(q="London, UK")
 city = result["cities"][0]
 lat, lng, tz = city["latitude"], city["longitude"], city["timezone"]
 
-# Step 2: Vedic kundli. `timezone` can be the IANA string ("Asia/Kolkata").
+# Step 2: Western natal chart. `timezone` can be the IANA string ("Europe/London").
 # The server resolves it to the DST-correct offset for the chart's own date.
-kundli = roxy.vedic_astrology.generate_birth_chart(
+natal = roxy.astrology.generate_natal_chart(
     date="1990-01-15",
     time="14:30:00",
     latitude=lat,
     longitude=lng,
     timezone=tz,
 )
 
-# Or Western natal chart (same timezone semantics)
-natal = roxy.astrology.generate_natal_chart(
+# Vedic kundli takes the same inputs (timezone optional, defaults to 5.5 IST).
+kundli = roxy.vedic_astrology.generate_birth_chart(
     date="1990-01-15",
     time="14:30:00",
     latitude=lat,
@@ -116,7 +116,7 @@ The global astrology app market is $6.27B and almost entirely Western. These end
 # Natal chart. The #1 Western query, called on every onboarding.
 natal = roxy.astrology.generate_natal_chart(
     date="1990-01-15", time="14:30:00",
-    latitude=28.6139, longitude=77.209, timezone="Asia/Kolkata",
+    latitude=40.7128, longitude=-74.006, timezone="America/New_York",
 )
 
 # Daily horoscope. Highest per-user call frequency in the catalog, drives DAUs and push.
@@ -125,8 +125,8 @@ horoscope = roxy.astrology.get_daily_horoscope(sign="aries")
 
 # Synastry. The dating-app pro-tier feature, full inter-aspect analysis.
 synastry = roxy.astrology.calculate_synastry(
-    person1={"date": "1990-01-15", "time": "14:30:00", "latitude": 28.61, "longitude": 77.20, "timezone": 5.5},
-    person2={"date": "1992-07-22", "time": "09:00:00", "latitude": 19.07, "longitude": 72.87, "timezone": 5.5},
+    person1={"date": "1990-01-15", "time": "14:30:00", "latitude": 40.71, "longitude": -74.01, "timezone": -5},
+    person2={"date": "1992-07-22", "time": "09:00:00", "latitude": 51.51, "longitude": -0.13, "timezone": 1},
 )
 # synastry["compatibilityScore"], synastry["interAspects"], synastry["analysis"]["strengths"]
 
@@ -218,9 +218,9 @@ The breakout 2026 spiritual category, computed from the same ephemeris as Wester
 
 ```python
 # Full bodygraph. The #1 Human Design query, the whole chart in one call.
-# `timezone` is the IANA string ("Asia/Kolkata"), same as the chart endpoints.
+# `timezone` is the IANA string ("America/New_York"), same as the chart endpoints.
 bodygraph = roxy.human_design.generate_bodygraph(
-    date="1990-07-04", time="10:12:00", timezone="Asia/Kolkata",
+    date="1990-07-04", time="10:12:00", timezone="America/New_York",
 )
 # bodygraph["type"] ("Generator", "Projector", "Manifestor", ...)
 print(bodygraph["type"], bodygraph["strategy"], bodygraph["profile"], bodygraph["definition"])
@@ -236,8 +236,8 @@ The first cross-domain, stateless forecast in the catalog. One call merges Weste
 # Response keys are camelCase passthrough: result["count"], result["events"].
 timeline = roxy.forecast.generate_timeline(
     birth_data={
-        "date": "1990-07-04", "time": "10:12:00", "timezone": "Asia/Kolkata",
-        "latitude": 28.6139, "longitude": 77.209,
+        "date": "1990-07-04", "time": "10:12:00", "timezone": "America/New_York",
+        "latitude": 40.7128, "longitude": -74.006,
     },
     start_date="2026-06-01", end_date="2026-06-30",
 )