feat: improve AGENTS.md gotchas, remove hardcoded counts, add AI agents section to README

Author: ph33nx

AGENTS.md

@@ -1,11 +1,15 @@
 # @roxyapi/sdk — Agent Guide
 
-TypeScript SDK for RoxyAPI. 8 spiritual/metaphysical domains, 113 endpoints, one API key. Zero runtime dependencies.
+TypeScript SDK for RoxyAPI. Multi-domain spiritual and metaphysical intelligence API. 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.
 
 ## Install and initialize
 
+```bash
+npm install @roxyapi/sdk
+```
+
 ```typescript
 import { createRoxy } from '@roxyapi/sdk';
 
@@ -16,27 +20,26 @@ const roxy = createRoxy(process.env.ROXY_API_KEY!);
 
 ## Domains
 
-Type `roxy.` to see all 10 namespaces:
-
-| Namespace | Methods | What it covers |
-|-----------|---------|----------------|
-| `roxy.astrology` | 23 | Western astrology: natal charts, horoscopes, synastry, moon phases, transits |
-| `roxy.vedicAstrology` | 42 | Vedic/Jyotish: birth charts, dashas, nakshatras, panchang, KP system |
-| `roxy.tarot` | 10 | 78-card Rider-Waite-Smith: spreads, daily pulls, yes/no, Celtic Cross |
-| `roxy.numerology` | 13 | Life path, expression, soul urge, personal year, karmic analysis |
-| `roxy.crystals` | 12 | Crystal healing properties, zodiac/chakra pairings, birthstones |
-| `roxy.iching` | 9 | I Ching: 64 hexagrams, trigrams, coin casting, daily readings |
-| `roxy.angelNumbers` | 4 | Angel number meanings, pattern analysis, daily guidance |
-| `roxy.dreams` | 5 | Dream symbol dictionary (2,000+ symbols) |
-| `roxy.location` | 3 | City geocoding for birth chart coordinates |
-| `roxy.usage` | 1 | API usage stats and subscription info |
+Type `roxy.` to see all available namespaces. Type `roxy.{domain}.` to see every method in that domain.
+
+| Namespace | What it covers |
+|-----------|----------------|
+| `roxy.astrology` | Western astrology: natal charts, horoscopes, synastry, moon phases, transits, compatibility |
+| `roxy.vedicAstrology` | Vedic/Jyotish: birth charts, dashas, nakshatras, panchang, KP system, doshas, yogas |
+| `roxy.tarot` | Rider-Waite-Smith deck: spreads, daily pulls, yes/no, Celtic Cross, custom layouts |
+| `roxy.numerology` | Life path, expression, soul urge, personal year, karmic analysis, compatibility |
+| `roxy.crystals` | Crystal healing properties, zodiac/chakra pairings, birthstones, search |
+| `roxy.iching` | I Ching: hexagrams, trigrams, coin casting, daily readings |
+| `roxy.angelNumbers` | Angel number meanings, pattern analysis, daily guidance |
+| `roxy.dreams` | Dream symbol dictionary and interpretations |
+| `roxy.location` | City geocoding for birth chart coordinates |
+| `roxy.usage` | API usage stats and subscription info |
 
 ## Critical patterns
 
 ### GET endpoints — use `path` for URL parameters
 
 ```typescript
-// Path params go in { path: { ... } }
 const { data } = await roxy.astrology.getDailyHoroscope({
   path: { sign: 'aries' },
 });
@@ -72,6 +75,14 @@ const { data } = await roxy.numerology.calculateLifePath({
 });
 ```
 
+### Query parameters
+
+```typescript
+const { data } = await roxy.crystals.searchCrystals({
+  query: { q: 'amethyst' },
+});
+```
+
 ### Error handling
 
 ```typescript
@@ -81,24 +92,14 @@ const { data, error, response } = await roxy.astrology.getDailyHoroscope({
 
 if (error) {
   // error is { error: string } on 4xx/5xx
-  console.error(error);
+  console.error('Status:', response?.status, 'Error:', error);
   return;
 }
-// data is fully typed here
+// data is fully typed after error check
 console.log(data.sign, data.overview);
 ```
 
-### Query parameters
-
-```typescript
-const { data } = await roxy.crystals.searchCrystals({
-  query: { q: 'amethyst' },
-});
-
-const { data } = await roxy.dreams.searchDreamSymbols({
-  query: { q: 'flying' },
-});
-```
+Common error codes: `401` invalid/missing API key, `403` subscription expired or limit reached, `429` rate limited, `404` resource not found.
 
 ## Common tasks
 
@@ -131,17 +132,20 @@ const city = cities[0];
 // Use city.latitude and city.longitude in chart requests
 ```
 
-## What NOT to do
+## Gotchas
 
-- Do not call endpoints with raw `fetch` — use the typed SDK methods
-- Do not hardcode the base URL — `createRoxy` sets it
-- Do not expose the API key client-side — call from server/API routes only
-- Do not guess method names — type `roxy.domain.` and use autocomplete
-- Parameters are `{ path }`, `{ body }`, or `{ query }` — not positional arguments
+- **Parameters are objects, not positional.** Always `{ path: {...} }`, `{ body: {...} }`, or `{ query: {...} }` — never positional arguments.
+- **Do not guess method names.** Type `roxy.domain.` and let autocomplete show available methods. Method names come from `operationId` in the OpenAPI spec, not URL paths.
+- **Do not use raw `fetch`.** The SDK handles auth headers, base URL, and typed responses.
+- **Do not expose API keys client-side.** Call Roxy from server code, API routes, or server components only.
+- **Chart endpoints need coordinates.** Use `roxy.location.searchCities()` to get latitude/longitude before calling any birth chart or panchang method.
+- **Date format is `YYYY-MM-DD`, time is `HH:MM:SS`.** Both are strings. Timezone is optional (IANA format like `America/New_York`).
+- **All list endpoints may return paginated objects** (e.g. `{ items: [...], total: N }`) rather than raw arrays. Check the type.
+- **`data` and `error` are mutually exclusive.** If `error` is set, `data` is `undefined` and vice versa.
 
 ## Links
 
 - Full method reference: `docs/llms-full.txt` (bundled in this package)
 - Interactive API docs: https://roxyapi.com/api-reference
 - Pricing and API keys: https://roxyapi.com/pricing
-- MCP setup for AI agents: https://roxyapi.com/docs/mcp
+- MCP for AI agents: https://roxyapi.com/docs/mcp

README.md

@@ -5,7 +5,7 @@
 [![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). 8 domains, 120+ endpoints, one API key.
+TypeScript SDK for [RoxyAPI](https://roxyapi.com). Multiple domains, fully typed endpoints, one API key.
 
 Build astrology apps, tarot platforms, birth chart generators, and compatibility tools without writing a single calculation.
 
@@ -107,7 +107,18 @@ if (error) {
 
 ## TypeScript
 
-Every request and response is fully typed. IDE autocomplete shows available methods per domain and exact parameter shapes:no docs tab needed.
+Every request and response is fully typed. IDE autocomplete shows available methods per domain and exact parameter shapes — no docs tab needed.
+
+## AI agents (Cursor, Claude Code, Copilot, Codex)
+
+This package ships with bundled documentation that AI coding agents can read directly from `node_modules/`:
+
+- **`AGENTS.md`** — Quick start, patterns, gotchas, and a common tasks reference table
+- **`docs/llms-full.txt`** — Complete method reference with code examples for every domain
+
+AI agents that support `AGENTS.md` (Claude Code, Cursor, GitHub Copilot, OpenAI Codex, Gemini CLI) will read it automatically. For other tools, point your agent to `node_modules/@roxyapi/sdk/AGENTS.md`.
+
+Also available: [MCP server](https://roxyapi.com/docs/mcp) for AI agents that support the Model Context Protocol.
 
 ## Links
 

docs/llms-full.txt

@@ -1,6 +1,6 @@
 # @roxyapi/sdk — Complete Method Reference
 
-> TypeScript SDK for RoxyAPI. 8 spiritual/metaphysical domains, 113 typed endpoints, zero runtime dependencies. Install: `npm install @roxyapi/sdk`
+> TypeScript SDK for RoxyAPI. Multi-domain spiritual and metaphysical intelligence API. Fully typed, zero runtime dependencies. Install: `npm install @roxyapi/sdk`
 
 Every method returns `{ data, error, response }`. Parameters use `{ path }` for URL segments, `{ body }` for POST data, `{ query }` for query strings.
 
@@ -13,7 +13,7 @@ const roxy = createRoxy(process.env.ROXY_API_KEY!);
 
 ## Astrology (Western) — `roxy.astrology`
 
-23 methods. Tropical zodiac, Placidus houses, NASA JPL DE405 validated positions.
+Tropical zodiac, Placidus houses, NASA JPL DE405 validated positions.
 
 ### Horoscopes
 
@@ -149,7 +149,7 @@ const { data } = await roxy.astrology.getMoonCalendar({ path: { year: 2026, mont
 
 ## Vedic Astrology — `roxy.vedicAstrology`
 
-42 methods. Sidereal zodiac (Lahiri ayanamsa), Placidus houses, KP system support.
+Sidereal zodiac (Lahiri ayanamsa), Placidus houses, KP system support.
 
 ### Birth Charts
 
@@ -389,7 +389,7 @@ const { data } = await roxy.vedicAstrology.calculateShadbala({
 
 ## Tarot — `roxy.tarot`
 
-10 methods. 78-card Rider-Waite-Smith deck (22 Major Arcana, 56 Minor Arcana).
+78-card Rider-Waite-Smith deck (22 Major Arcana, 56 Minor Arcana).
 
 ```typescript
 // List all 78 cards
@@ -429,7 +429,7 @@ const { data } = await roxy.tarot.castCustomSpread({
 
 ## Numerology — `roxy.numerology`
 
-13 methods. Pythagorean system.
+Pythagorean system.
 
 ```typescript
 // Life Path number
@@ -492,7 +492,7 @@ const { data } = await roxy.numerology.getDailyNumber({ body: { date: '2026-03-2
 
 ## Crystals — `roxy.crystals`
 
-12 methods. Healing properties, zodiac/chakra associations, birthstones.
+Healing properties, zodiac/chakra associations, birthstones.
 
 ```typescript
 // All crystals (paginated)
@@ -536,7 +536,7 @@ const { data } = await roxy.crystals.listCrystalPlanets();
 
 ## I Ching — `roxy.iching`
 
-9 methods. 64 hexagrams, 8 trigrams, traditional coin casting.
+64 hexagrams, 8 trigrams, traditional coin casting.
 
 ```typescript
 // Cast a reading (3-coin method)
@@ -572,7 +572,7 @@ const { data } = await roxy.iching.getTrigram({ path: { identifier: 'heaven' } }
 
 ## Angel Numbers — `roxy.angelNumbers`
 
-4 methods. 43 angel numbers with spiritual meanings.
+Angel numbers with spiritual meanings and pattern analysis.
 
 ```typescript
 // All angel numbers
@@ -592,7 +592,7 @@ const { data } = await roxy.angelNumbers.getDailyAngelNumber();
 
 ## Dreams — `roxy.dreams`
 
-5 methods. 2,000+ dream symbol dictionary.
+Dream symbol dictionary and interpretations.
 
 ```typescript
 // Search symbols
@@ -615,7 +615,7 @@ const { data } = await roxy.dreams.getDailyDreamSymbol({ body: { date: '2026-03-
 
 ## Location — `roxy.location`
 
-3 methods. Geocoding helper for birth chart coordinates.
+Geocoding helper for birth chart coordinates.
 
 ```typescript
 // Search cities (autocomplete)
@@ -633,7 +633,7 @@ const { data } = await roxy.location.getCitiesByCountry({ path: { iso2: 'IN' } }
 
 ## Usage — `roxy.usage`
 
-1 method. Check your API usage and subscription.
+Check your API usage and subscription.
 
 ```typescript
 const { data } = await roxy.usage.getUsageStats();