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 @@
 # @roxyapi/sdk - Agent Guide
 
-TypeScript SDK for RoxyAPI. Twelve domains (Western astrology, Vedic astrology, numerology, tarot, biorhythm, I Ching, crystals, dreams, angel numbers, location, usage, languages). One API key, fully typed, zero runtime dependencies.
+TypeScript 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, fully typed, zero runtime dependencies.
 
 > Before writing any code with this SDK, read `docs/llms-full.txt` in this package for the complete method reference with examples.
 
@@ -23,16 +23,16 @@ const roxy = createRoxy(process.env.ROXY_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.searchCities` first.
 
 ```typescript
-const { data } = await roxy.location.searchCities({ query: { q: 'Mumbai' } });
+const { data } = await roxy.location.searchCities({ query: { q: 'New York' } });
 const { latitude, longitude, timezone } = data.cities[0];
-// `timezone` is the IANA string ("Asia/Kolkata"). Pass it directly to any chart
+// `timezone` is the IANA string ("America/New_York"). Pass it directly to any chart
 // endpoint and the server resolves it to the DST-correct decimal offset using
 // the chart's own `date`, so a January 1990 New York chart picks EST (-5) even
 // when you looked the city up in July. If you prefer numbers, `utcOffset`
 // (5.5, -5, 9, ...) also works and produces identical charts.
 ```
 
-`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
 
@@ -57,7 +57,7 @@ Type `roxy.` to see all available namespaces. Type `roxy.{domain}.` to see every
 | `roxy.languages` | 1 | List the response languages accepted by the `lang` query parameter on every i18n-aware endpoint |
 <!-- END:DOMAINS -->
 
-**Total:** 148 endpoints across 12 product domains plus usage and languages. Counts auto-sync from `specs/openapi.json` at release time.
+**Total:** 150+ endpoints across 12+ product domains plus usage and languages. Per-domain counts in the table above auto-sync from `specs/openapi.json` at release time.
 
 ## Quality guidelines for agents
 
@@ -74,7 +74,7 @@ Five rules to follow when writing any call with this SDK. Get these right and th
 ### Two-step pattern for coordinate-dependent endpoints
 
 ```typescript
-const { data } = await roxy.location.searchCities({ query: { q: 'Delhi' } });
+const { data } = await roxy.location.searchCities({ query: { q: 'London' } });
 const { latitude, longitude, timezone } = data.cities[0];
 
 const { data: chart } = await roxy.astrology.generateNatalChart({
@@ -190,7 +190,7 @@ Ordered by domain priority (Western, Vedic, Numerology, Tarot, Biorhythm, I Chin
 | Dream symbol lookup | `roxy.dreams.getDreamSymbol({ path: { id: 'flying' } })` |
 | Angel number meaning | `roxy.angelNumbers.getAngelNumber({ path: { number: '1111' } })` |
 | Universal number lookup | `roxy.angelNumbers.analyzeNumberSequence({ query: { number: '1234' } })` |
-| Find city coordinates | `roxy.location.searchCities({ query: { q: 'Mumbai' } })` |
+| Find city coordinates | `roxy.location.searchCities({ query: { q: 'Berlin' } })` |
 | Check API usage | `roxy.usage.getUsageStats()` |
 | List supported languages | `roxy.languages.listLanguages()` |
 
@@ -203,8 +203,8 @@ These are the fields AI agents most often get wrong. Copy the format column exac
 | `timezone` | Decimal hours (number) OR IANA string | `5.5`, `-5`, `0` (decimal) OR `"Asia/Kolkata"`, `"America/New_York"` (IANA, resolved to DST-correct offset for the chart date) | `"5:30"`, `"+0530"`, `"GMT-5"`, partial names |
 | `date` | ISO date string | `"1990-01-15"` | `"Jan 15 1990"`, `new Date()`, `"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 (number) | `28.6139` (Delhi), `-33.8688` (Sydney), `40.7128` (NYC) | `"28°36'N"`, `"28 36 50"`, strings |
-| `longitude` | Decimal degrees (number) | `77.209` (Delhi), `-74.006` (NYC), `139.6917` (Tokyo) | Same as latitude - no DMS strings |
+| `latitude` | Decimal degrees (number) | `51.5074` (London), `-33.8688` (Sydney), `40.7128` (NYC) | `"28°36'N"`, `"28 36 50"`, strings |
+| `longitude` | Decimal degrees (number) | `-0.1278` (London), `-74.006` (NYC), `139.6917` (Tokyo) | Same as latitude - no DMS strings |
 | `sign` (horoscope path) | Lowercase zodiac name | `aries`, `taurus`, `gemini`, ... `pisces` | `"Aries"`, `"♈"`, `"1"`, `"ARIES"` (case-insensitive but prefer lowercase) |
 | `chakra` (crystals path) | Title-case English name from the fixed enum | `"Root"`, `"Sacral"`, `"Solar Plexus"`, `"Heart"`, `"Throat"`, `"Third Eye"`, `"Crown"` | `"heart"`, `"third-eye"`, `"solar plexus"` - route is case-insensitive at runtime, but the generated TS enum is title-case; lowercase fails `tsc --strict`. |
 | `fullName` (numerology) | Birth-certificate name | `"John William Smith"`, `"Priya Rajesh Sharma"` | Nickname, married name, partial name - affects all letter-based calcs |

README.md

@@ -15,7 +15,7 @@ TypeScript SDK for astrology, Vedic astrology, numerology, tarot, and more.
 
 One API key. Fully typed. Verified against NASA JPL Horizons.
 
-The fastest way to add natal charts, kundli matching, daily horoscopes, tarot readings, and spiritual insights to Node.js apps, backends, and AI agents. Ten 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 Node.js apps, backends, and AI agents. 12+ domains behind a single [Roxy](https://roxyapi.com) subscription, interpretations in eight languages.
 
 ## Install
 
@@ -49,7 +49,7 @@ const roxy = createRoxy(process.env.ROXY_API_KEY!);
 
 // Step 1: geocode the birth city (required for any chart endpoint)
 const { data } = await roxy.location.searchCities({
-  query: { q: 'Mumbai, India' },
+  query: { q: 'London, UK' },
 });
 const { latitude, longitude, timezone } = data.cities[0];
 
@@ -112,7 +112,7 @@ The global astrology app market is $6.27B and almost entirely Western. These end
 ```typescript
 // Natal chart. The #1 Western query, called on every onboarding.
 const { data: natal } = await roxy.astrology.generateNatalChart({
-  body: { date: '1990-01-15', time: '14:30:00', latitude: 28.6139, longitude: 77.209, timezone: 5.5 },
+  body: { date: '1990-01-15', time: '14:30:00', latitude: 40.7128, longitude: -74.006, timezone: -5 },
 });
 
 // Daily horoscope. Highest per-user call frequency in the catalog, drives DAUs and push.
@@ -122,8 +122,8 @@ const { data: horoscope } = await roxy.astrology.getDailyHoroscope({ path: { sig
 // Synastry. The dating-app pro-tier feature, full inter-aspect analysis between two charts.
 const { data: synastry } = await roxy.astrology.calculateSynastry({
   body: {
-    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
@@ -227,9 +227,9 @@ const { data: hd } = await roxy.humanDesign.generateBodygraph({
   body: {
     date: '1990-07-04',
     time: '10:12:00',
-    latitude: 28.6139,
-    longitude: 77.209,
-    timezone: 5.5,
+    latitude: 40.7128,
+    longitude: -74.006,
+    timezone: -4,
   },
 });
 // hd.type, hd.strategy, hd.profile, hd.definition
@@ -247,9 +247,9 @@ const { data: timeline } = await roxy.forecast.generateTimeline({
     birthData: {
       date: '1990-07-04',
       time: '10:12:00',
-      latitude: 28.6139,
-      longitude: 77.209,
-      timezone: 5.5,
+      latitude: 40.7128,
+      longitude: -74.006,
+      timezone: -4,
     },
     startDate: '2026-06-01',
     endDate: '2026-06-30',