docs: blind-test fact-check, location envelope, utcOffset vs timezone, SEO keywords

README.md: lead paragraph with SEO keywords, most-used endpoints in canonical order, verified 28 method names live, fixed location cities envelope and utcOffset vs IANA timezone trap
AGENTS.md: same envelope + utcOffset fixes, keeps AI agents on the correct path

Author: ph33nx

AGENTS.md

@@ -23,8 +23,10 @@ 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: cities } = await roxy.location.searchCities({ query: { q: 'Mumbai' } });
-const { latitude, longitude, timezone } = cities[0];
+const { data } = await roxy.location.searchCities({ query: { q: 'Mumbai' } });
+const { latitude, longitude, utcOffset } = data.cities[0];
+// Use `utcOffset` (decimal: 5.5, -5, 9, ...) as the `timezone` number on chart calls.
+// The city's `timezone` field is the IANA string ("Asia/Kolkata") — not what chart endpoints expect.
 ```
 
 ## Domains
@@ -54,11 +56,11 @@ Type `roxy.` to see all available namespaces. Type `roxy.{domain}.` to see every
 ### Two-step pattern for coordinate-dependent endpoints
 
 ```typescript
-const { data: cities } = await roxy.location.searchCities({ query: { q: 'Delhi' } });
-const { latitude, longitude, timezone } = cities[0];
+const { data } = await roxy.location.searchCities({ query: { q: 'Delhi' } });
+const { latitude, longitude, utcOffset } = data.cities[0];
 
 const { data: chart } = await roxy.astrology.generateNatalChart({
-  body: { date: '1990-01-15', time: '14:30:00', latitude, longitude, timezone },
+  body: { date: '1990-01-15', time: '14:30:00', latitude, longitude, timezone: utcOffset },
 });
 ```
 

README.md

@@ -5,9 +5,9 @@
 [![API Reference](https://img.shields.io/badge/api%20reference-roxyapi.com-blue)](https://roxyapi.com/api-reference)
 [![Pricing](https://img.shields.io/badge/pricing-roxyapi.com-blue)](https://roxyapi.com/pricing)
 
-TypeScript SDK for [RoxyAPI](https://roxyapi.com). Natal charts, Vedic kundli, numerology, tarot, biorhythm, I Ching, crystals, dreams, and angel numbers. Eleven domains, one API key, fully typed.
+The TypeScript SDK for [Roxy](https://roxyapi.com), the multi-domain spiritual intelligence API. One key, ten domains, fully typed. Western astrology API, Vedic astrology API, numerology API, tarot API, biorhythm API, I Ching API, crystals API, dream interpretation API, and angel numbers API behind a single subscription.
 
-Build astrology apps, kundli matching, tarot platforms, compatibility tools, and daily-horoscope features without writing a single calculation.
+Build a natal chart app, a kundli matching product, a daily horoscope feature, a tarot reading app, a numerology life path calculator, or a spiritual AI agent without writing a single calculation. Calculations are verified against NASA JPL Horizons; interpretations ship in eight languages.
 
 ## Install
 
@@ -25,19 +25,19 @@ import { createRoxy } from '@roxyapi/sdk';
 const roxy = createRoxy(process.env.ROXY_API_KEY!);
 
 // Step 1: geocode the birth city (required for any chart endpoint)
-const { data: cities } = await roxy.location.searchCities({
+const { data } = await roxy.location.searchCities({
   query: { q: 'Mumbai, India' },
 });
-const { latitude, longitude, timezone } = cities[0];
+const { latitude, longitude, utcOffset } = data.cities[0];
 
-// Step 2: Western natal chart
+// Step 2: Western natal chart. Pass utcOffset as the `timezone` number.
 const { data: chart } = await roxy.astrology.generateNatalChart({
-  body: { date: '1990-01-15', time: '14:30:00', latitude, longitude, timezone },
+  body: { date: '1990-01-15', time: '14:30:00', latitude, longitude, timezone: utcOffset },
 });
 
-// Vedic kundli uses the same inputs
+// Vedic kundli uses the same inputs (timezone optional, defaults to 5.5 IST)
 const { data: kundli } = await roxy.vedicAstrology.generateBirthChart({
-  body: { date: '1990-01-15', time: '14:30:00', latitude, longitude },
+  body: { date: '1990-01-15', time: '14:30:00', latitude, longitude, timezone: utcOffset },
 });
 ```
 
@@ -49,7 +49,10 @@ Every chart, horoscope, panchang, dasha, dosha, navamsa, KP, synastry, compatibi
 
 ```typescript
 const { data } = await roxy.location.searchCities({ query: { q: 'Tokyo' } });
-const { latitude, longitude, timezone } = data[0];
+const { latitude, longitude, utcOffset } = data.cities[0];
+// Pass utcOffset (5.5, -5, 9, ...) as `timezone` to astrology endpoints.
+// The `timezone` field on the city is the IANA string ("Asia/Tokyo"), keep
+// that for your own date formatting, not for RoxyAPI chart calls.
 ```
 
 ## Domains
@@ -70,94 +73,193 @@ const { latitude, longitude, timezone } = data[0];
 | `roxy.usage` | 1 | API usage stats, rate limits, subscription info |
 <!-- END:DOMAINS -->
 
-## Recipes
+## Most-used endpoints
 
-### Daily horoscope (wellness, news, lifestyle apps)
+The highest-demand endpoints by domain, in the order you are most likely to ship them. Each block shows the most-searched API call in that domain so you can pick the feature that drives the most user value first. Full endpoint catalog in the [API reference](https://roxyapi.com/api-reference).
 
-```typescript
-const { data } = await roxy.astrology.getDailyHoroscope({
-  path: { sign: 'aries' },
-});
-// data.overview, data.love, data.career, data.luckyNumber, ...
-```
+### 1. Western astrology API (natal chart, daily horoscope, synastry)
 
-### Vedic kundli (India market, matrimonial, muhurat)
+The global astrology app market is $6.27B and almost entirely Western. These endpoints power zodiac dating apps, Co-Star-style natal chart products, daily horoscope features, and lunar-cycle wellness apps.
 
 ```typescript
-const { data: cities } = await roxy.location.searchCities({ query: { q: 'Delhi' } });
-const { latitude, longitude } = cities[0];
+// 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 },
+});
 
-const { data: kundli } = await roxy.vedicAstrology.generateBirthChart({
-  body: { date: '1990-01-15', time: '14:30:00', latitude, longitude },
+// Daily horoscope. Highest per-user call frequency in the catalog, drives DAUs and push.
+const { data: horoscope } = await roxy.astrology.getDailyHoroscope({ path: { sign: 'aries' } });
+// horoscope.overview, horoscope.love, horoscope.career, horoscope.luckyNumber
+
+// 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 },
+  },
 });
+// synastry.compatibilityScore, synastry.interAspects, synastry.strengths
+
+// Moon phase. Viral for wellness, cycle-tracking, and meditation apps.
+const { data: moon } = await roxy.astrology.getCurrentMoonPhase({});
 ```
 
-### Panchang (daily almanac, ritual planner)
+### 2. Vedic astrology API (kundli, panchang, dasha, Guna Milan, KP)
+
+The depth moat. India astrology market: $163M in 2024, projected $1.8B by 2030 (49% CAGR). Kundli, panchang, dasha, dosha, and KP are the five Google-dominant queries for every matrimonial platform, kundli generator, and muhurat app.
 
 ```typescript
-const { data } = await roxy.vedicAstrology.getDetailedPanchang({
+// Vedic kundli. Top India astrology keyword. Entry point for every Jyotish product.
+const { data: kundli } = await roxy.vedicAstrology.generateBirthChart({
+  body: { date: '1990-01-15', time: '14:30:00', latitude: 28.6139, longitude: 77.209, timezone: 5.5 },
+});
+
+// Panchang. Tithi, nakshatra, yoga, karana, rahu kaal, abhijit muhurta in one call.
+const { data: panchang } = await roxy.vedicAstrology.getDetailedPanchang({
   body: { date: '2026-04-22', latitude: 28.6139, longitude: 77.209 },
 });
-// data.tithi, data.nakshatra, data.rahuKaal, data.abhijitMuhurta, ...
-```
 
-### Guna Milan (matrimonial matching)
+// Vimshottari dasha. Highest-value single-shot Vedic query.
+const { data: dasha } = await roxy.vedicAstrology.getCurrentDasha({
+  body: { date: '1990-01-15', time: '14:30:00', latitude: 28.6139, longitude: 77.209, timezone: 5.5 },
+});
 
-```typescript
-const person1 = { date: '1990-01-15', time: '14:30:00', latitude: 28.61, longitude: 77.20 };
-const person2 = { date: '1992-07-22', time: '09:00:00', latitude: 19.07, longitude: 72.87 };
+// Mangal Dosha. Most-asked matrimonial question in India.
+const { data: dosha } = await roxy.vedicAstrology.checkManglikDosha({
+  body: { date: '1990-01-15', time: '14:30:00', latitude: 28.6139, longitude: 77.209, timezone: 5.5 },
+});
+
+// Guna Milan. 36-point Ashtakoota matrimonial compatibility score.
+const { data: milan } = await roxy.vedicAstrology.calculateGunMilan({
+  body: {
+    person1: { date: '1990-01-15', time: '14:30:00', latitude: 28.61, longitude: 77.20 },
+    person2: { date: '1992-07-22', time: '09:00:00', latitude: 19.07, longitude: 72.87 },
+  },
+});
 
-const { data } = await roxy.vedicAstrology.calculateGunMilan({
-  body: { person1, person2 },
+// KP ruling planets. Horary answers for "will X happen" questions in real time.
+const { data: kp } = await roxy.vedicAstrology.getKpRulingPlanets({
+  body: { latitude: 28.6139, longitude: 77.209, timezone: 5.5 },
 });
-// data.total, data.maxScore (36), data.isCompatible, data.breakdown[8]
 ```
 
-### Numerology life path (numerology calculators)
+### 3. Numerology API (life path, full chart, personal year)
+
+Commodity content with durable demand. `life path number calculator` is among the highest-volume spiritual searches globally. Works without birth time, the easiest domain to integrate.
 
 ```typescript
-const { data } = await roxy.numerology.calculateLifePath({
+// Life Path. The #1 numerology keyword, every calculator page starts here.
+const { data: lp } = await roxy.numerology.calculateLifePath({
   body: { year: 1990, month: 1, day: 15 },
 });
-// data.number, data.type, data.hasKarmicDebt, data.meaning
+// lp.number, lp.type ("single" | "master"), lp.meaning
+
+// Full numerology chart. Premium one-shot: all six core numbers plus karmic, personal year.
+const { data: chart } = await roxy.numerology.generateNumerologyChart({
+  body: { fullName: 'Jane Smith', year: 1990, month: 1, day: 15 },
+});
+
+// Personal Year. Annual forecast, drives January traffic spikes.
+const { data: pyear } = await roxy.numerology.calculatePersonalYear({
+  body: { month: 1, day: 15, year: 2026 },
+});
 ```
 
-### Tarot Celtic Cross (premium-tier tarot feature)
+### 4. Tarot API (daily card, Celtic Cross, three-card, yes / no)
+
+High search volume, evergreen. The tarot card database is the highest per-endpoint call count in the catalog because apps fetch once and cache.
 
 ```typescript
-const { data } = await roxy.tarot.castCelticCross({
-  body: { question: 'What should I focus on?' },
+// Daily card. Stickiest tarot feature. Seed per user for deterministic once-per-day behavior.
+const { data: card } = await roxy.tarot.getDailyCard({ body: { seed: 'user-42' } });
+// card.card.name, card.card.imageUrl, card.interpretation
+
+// Celtic Cross. Professional-reader spread. Premium-tier, ten positions.
+const { data: cc } = await roxy.tarot.castCelticCross({
+  body: { question: 'What should I focus on?', seed: 'user-42' },
+});
+
+// Three-card past-present-future. Most-drawn spread on every tarot platform.
+const { data: three } = await roxy.tarot.castThreeCard({
+  body: { question: 'My next quarter', seed: 'user-42' },
 });
-// data.positions[10], data.reading
+
+// Yes / No. Impulse micro-query, highest conversion-to-first-call on tarot surfaces.
+const { data: answer } = await roxy.tarot.castYesNo({ body: { question: 'Should I take the offer?' } });
+// answer.answer ("Yes" | "No" | "Maybe"), answer.strength
 ```
 
-### Daily biorhythm (wellness, productivity, sports apps)
+### 5. Biorhythm API (daily check-in, forecast, compatibility)
+
+Zero competition domain. Steady search volume with the top Google result being a static calculator page. Pure land-grab for wellness, productivity, sports, and couples apps.
 
 ```typescript
-const { data } = await roxy.biorhythm.getDailyBiorhythm({
-  body: { seed: 'user-123' },
+// Daily biorhythm. Physical, emotional, intellectual, intuitive, plus seven extended cycles.
+const { data: bio } = await roxy.biorhythm.getDailyBiorhythm({
+  body: { seed: 'user-1', date: '2026-04-23' },
 });
+
+// Multi-day forecast. Best-day / worst-day planner for calendar and coaching products.
+const { data: forecast } = await roxy.biorhythm.getForecast({
+  body: { birthDate: '1990-01-15', startDate: '2026-04-01', endDate: '2026-04-30' },
+});
+```
+
+### 6. I Ching API (daily hexagram, coin cast, 64-hexagram catalog)
+
+Meditation apps, decision-making tools, and wisdom chatbots. `i ching API` and `hexagram API` are the keywords.
+
+```typescript
+// Cast a reading. Active divination, primary hexagram plus changing lines and transformed hexagram.
+const { data: reading } = await roxy.iching.castReading({ query: { seed: 'user-42' } });
+// reading.hexagram, reading.changingLinePositions, reading.resultingHexagram
+
+// Hexagram catalog. Cache once for all 64 hexagrams.
+const { data: hexagrams } = await roxy.iching.listHexagrams({});
+// hexagrams.hexagrams has 64 entries
 ```
 
-### I Ching cast (decision-making, meditation)
+### 7. Crystals API (by zodiac, by chakra, birthstone)
+
+Crystal retail and metaphysical shops use these to build "crystals for [sign]" and "[chakra] chakra stones" pages.
 
 ```typescript
-const { data } = await roxy.iching.castReading();
-// data.hexagram, data.changingLinePositions, data.resultingHexagram
+// By zodiac. Highest-search crystal query pattern.
+const { data: bySign } = await roxy.crystals.getCrystalsByZodiac({ path: { sign: 'scorpio' } });
+// bySign.crystals is a list of id, name, color, chakra, properties
+
+// By chakra. Second-highest crystal query pattern.
+const { data: byChakra } = await roxy.crystals.getCrystalsByChakra({ path: { chakra: 'heart' } });
+
+// Birthstone. Evergreen gift and jewelry SEO.
+const { data: birthstone } = await roxy.crystals.getBirthstones({ path: { month: 4 } });
 ```
 
-### Dream symbol lookup (journaling, self-discovery)
+### 8. Dream interpretation API (symbol dictionary, search)
+
+Thousands of dream symbols. `dream meaning` is among the highest-volume spiritual searches on Google. Journal apps, AI therapy chatbots, and self-discovery products are the buyers.
 
 ```typescript
-const { data } = await roxy.dreams.getDreamSymbol({ path: { id: 'flying' } });
+// Symbol detail. Every "what does it mean to dream about X" page lands here.
+const { data: symbol } = await roxy.dreams.getDreamSymbol({ path: { id: 'flying' } });
+// symbol.id, symbol.name, symbol.meaning
+
+// Symbol search. Chatbots cache the dictionary locally after one call.
+const { data: results } = await roxy.dreams.searchDreamSymbols({ query: { q: 'flying' } });
+// results.symbols is an array of matching symbols
 ```
 
-### Angel number meaning (viral content, spiritual apps)
+### 9. Angel Numbers API (1111, 222, 333 meanings plus universal lookup)
+
+Gen Z spiritual-tok fuel. `111 meaning`, `222 meaning`, `333 angel number` are evergreen viral queries with massive shareability.
 
 ```typescript
-const { data } = await roxy.angelNumbers.getAngelNumber({
-  path: { number: '1111' },
-});
+// By number. Every "meaning of 1111" page is backed by this.
+const { data: angel } = await roxy.angelNumbers.getAngelNumber({ path: { number: '1111' } });
+// angel.meaning.spiritual, angel.meaning.love, angel.affirmation
+
+// Universal lookup. Works for any positive integer via digit-root fallback.
+const { data: anyNumber } = await roxy.angelNumbers.analyzeNumberSequence({ query: { number: '4242' } });
 ```
 
 ## Authentication