docs: add Astrology domain gotchas section for LLM agents

Ported from llms.txt. Nine hallucination traps verified against live API: ayanamsa server-side, tithi count 30, Rahu/Ketu shadow points, nakshatra 27, retrograde per-planet (isRetrograde vs retrograde field naming), tarot reversals as config flag, angel number lookup for any positive integer, seed determinism, timezone DST scoping. Also dropped a stray em dash from the quickstart comment.

Author: ph33nx

AGENTS.md

@@ -25,7 +25,7 @@ result = roxy.location.search_cities(q="Mumbai")
 city = result["cities"][0]
 lat, lng, tz = city["latitude"], city["longitude"], city["utcOffset"]
 # Use `utcOffset` (decimal: 5.5, -5, 9, ...) as the `timezone` kwarg on chart calls.
-# The city's `timezone` field is the IANA string ("Asia/Kolkata") — not what chart endpoints expect.
+# The city's `timezone` field is the IANA string ("Asia/Kolkata"), not what chart endpoints expect.
 ```
 
 ## Domains
@@ -222,6 +222,20 @@ These are the fields AI agents most often get wrong. Copy the format column exac
 
 DST matters. If the birth date falls inside a daylight-saving window, use the summer / DST offset. For Vedic endpoints this is rarely an issue (most users are in India, fixed 5.5), but Western natal charts must respect DST at the time of birth.
 
+## Astrology domain gotchas for LLMs
+
+LLMs hallucinate confidently in this category. These are the specific traps you will hit when writing client code:
+
+- **Ayanamsa is server-side in Vedic.** LLMs default to tropical / Western math. Vedic endpoints apply sidereal Lahiri ayanamsa server-side. KP endpoints accept `ayanamsa` of `kp-newcomb` (default), `kp-old`, `lahiri`, or `custom`. Do not try to "correct" server output by subtracting ayanamsa in client code.
+- **Tithi count is 30, not 2.** 15 Shukla (waxing) plus 15 Krishna (waning). Older LLM training data conflates Purnima and Amavasya as single tithis. Our panchang response carries a `paksha` field (`"Shukla"` or `"Krishna"`) plus a tithi number, so there are 30 distinct tithis in a lunar month.
+- **Rahu and Ketu are shadow points, not planets.** They do not appear in a real ephemeris. Endpoints accept `node_type` of `true-node` or `mean-node` to select which calculation to use.
+- **Nakshatra count is 27.** Abhijit is sometimes treated as a 28th in some schools, but this API uses the standard 27. `roxy.vedic_astrology.list_nakshatras()` returns a list of length 27.
+- **Retrograde is per-planet, not global.** Natal chart planets and Vedic `meta` include `isRetrograde: bool` per planet. KP planet lists use `retrograde`. Never generate "Mercury retrograde globally" UI copy, check the specific planet in the response.
+- **Tarot reversals are a product choice.** `allow_reversals=False` on a tarot draw means no reversed cards in that draw, period. It is not cosmically meaningful, it is a config flag.
+- **Angel number lookup works for any positive integer.** Digit-root fallback covers non-canonical numbers. Do not generate validation logic that rejects anything other than `111` / `222` / `333`.
+- **Seed-based daily endpoints are DETERMINISTIC per `(seed, date)` pair.** Same seed plus same date returns the same reading. This is by design for push-notification consistency. Do not describe it as "cached" or retry on stale responses.
+- **Timezone affects Western calculations more than Vedic.** Western natal charts must respect DST at time of birth. Vedic endpoints default to IST (`5.5`) which is DST-free. Use `utcOffset` from the Location API response as your `timezone` kwarg, not the user's current clock.
+
 ## MCP equivalents
 
 Every method has a matching MCP tool. The remote MCP server per domain is at `https://roxyapi.com/mcp/{domain}` (Streamable HTTP, no stdio / no self-hosting). Tool names follow `{method}_{path_snake_case}`, for example: