docs: auto-sync domain tables from OpenAPI spec

- Add scripts/sync-docs.ts to regenerate the domains table in
  README.md and AGENTS.md between HTML markers, driven by
  scripts/tag-descriptions.ts. Fails loudly on unknown tags,
  stale entries, or missing llms-full.txt sections.
- Wire into bun run generate, lefthook pre-commit (auto-stage
  re-synced files), lefthook pre-push (drift gate), and
  release.yml (runs before the spec-diff check).
- Document biorhythm domain (6 endpoints) missed in last 2
  releases, and add multi-language note (8 languages) to
  README.md, AGENTS.md, and docs/llms-full.txt.

Author: ph33nx

.github/workflows/release.yml

@@ -35,6 +35,9 @@ jobs:
       - name: Regenerate SDK
         run: bun run generate
 
+      - name: Sync docs from spec
+        run: bun run docs:sync
+
       - name: Check if spec changed
         id: diff
         run: |
@@ -74,7 +77,7 @@ jobs:
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
           VERSION=$(node -p "require('./package.json').version")
-          git add package.json src/version.ts specs/openapi.json src/
+          git add package.json src/version.ts specs/openapi.json src/ README.md AGENTS.md
           git commit -m "release: v$VERSION"
           git tag "v$VERSION"
           git push --follow-tags

AGENTS.md

@@ -22,18 +22,23 @@ const roxy = createRoxy(process.env.ROXY_API_KEY!);
 
 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 |
+<!-- BEGIN:DOMAINS -->
+| Namespace | Endpoints | What it covers |
+|-----------|-----------|----------------|
+| `roxy.astrology` | 22 | Western astrology: natal charts, horoscopes, synastry, moon phases, transits, compatibility |
+| `roxy.vedicAstrology` | 42 | Vedic/Jyotish: birth charts, dashas, nakshatras, panchang, KP system, doshas, yogas |
+| `roxy.tarot` | 10 | Rider-Waite-Smith deck: spreads, daily pulls, yes/no, Celtic Cross, custom layouts |
+| `roxy.numerology` | 16 | Life path, expression, soul urge, personal year, karmic analysis, compatibility |
+| `roxy.dreams` | 5 | Dream symbol dictionary and interpretations |
+| `roxy.angelNumbers` | 4 | Angel number meanings, pattern analysis, daily guidance |
+| `roxy.iching` | 9 | I Ching: hexagrams, trigrams, coin casting, daily readings |
+| `roxy.crystals` | 12 | Crystal healing properties, zodiac/chakra pairings, birthstones, search |
+| `roxy.biorhythm` | 6 | 10-cycle biorhythm readings, forecasts, critical days, compatibility, daily check-ins (wellness, dating, productivity) |
+| `roxy.location` | 3 | City geocoding for birth chart coordinates |
+| `roxy.usage` | 1 | API usage stats and subscription info |
+<!-- END:DOMAINS -->
+
+**Total:** 130 endpoints across 10 domains + usage. Counts auto-sync from `specs/openapi.json` at release time.
 
 ## Critical patterns
 
@@ -83,6 +88,24 @@ const { data } = await roxy.crystals.searchCrystals({
 });
 ```
 
+### Multi-language responses via `query: { lang }`
+
+Interpretations are available in 8 languages: `en`, `tr`, `de`, `es`, `fr`, `hi`, `pt`, `ru`. Pass `lang` as a query param on any supported endpoint. Defaults to `en`.
+
+```typescript
+const { data } = await roxy.tarot.getDailyCard({
+  body: { date: '2026-04-14' },
+  query: { lang: 'es' },
+});
+
+const { data } = await roxy.numerology.calculateLifePath({
+  body: { year: 1990, month: 1, day: 15 },
+  query: { lang: 'hi' },
+});
+```
+
+Supported: `astrology`, `vedicAstrology`, `tarot`, `numerology`, `crystals`, `iching`, `angelNumbers`, `biorhythm`. Not supported (English-only): `dreams`, `location`, `usage`. Languages without translations yet fall back to English.
+
 ### Error handling
 
 All errors return `{ error: string, code: string }`. The `error` field is human-readable (may change wording). The `code` field is machine-readable (stable, safe to switch on).
@@ -130,6 +153,9 @@ Error codes:
 | I Ching reading | `roxy.iching.castReading()` |
 | Angel number meaning | `roxy.angelNumbers.getAngelNumber({ path: { number: '1111' } })` |
 | Dream symbol lookup | `roxy.dreams.getDreamSymbol({ path: { id: 'flying' } })` |
+| Biorhythm reading | `roxy.biorhythm.getReading({ body: { birthDate: '1990-01-15' } })` |
+| Biorhythm forecast | `roxy.biorhythm.getForecast({ body: { birthDate: '1990-01-15', endDate: '2026-05-01' } })` |
+| Biorhythm compatibility | `roxy.biorhythm.calculateBioCompatibility({ body: { person1: { birthDate }, person2: { birthDate } } })` |
 | Find city coordinates | `roxy.location.searchCities({ query: { q: 'Mumbai' } })` |
 | Check API usage | `roxy.usage.getUsageStats()` |
 

README.md

@@ -49,18 +49,21 @@ const { data: reading } = await roxy.tarot.castCelticCross({
 
 ## Domains
 
-| Namespace | What it covers |
-|-----------|----------------|
-| `roxy.angelNumbers` | Angel number lookup, pattern analysis, daily guidance |
-| `roxy.astrology` | Western astrology:natal charts, horoscopes, synastry, moon phases |
-| `roxy.vedicAstrology` | Vedic/Jyotish:birth charts, dashas, nakshatras, panchang, KP system |
-| `roxy.tarot` | 78-card readings:spreads, daily pulls, yes/no, Celtic Cross |
-| `roxy.numerology` | Life path, expression, soul urge, personal year, karmic lessons |
-| `roxy.iching` | I Ching hexagrams, trigrams, daily readings |
-| `roxy.crystals` | Crystal meanings, healing properties, zodiac and chakra pairings |
-| `roxy.dreams` | Dream symbol interpretations:3,000+ symbols |
-| `roxy.location` | City and country search for birth chart coordinates |
-| `roxy.usage` | API usage stats, rate limits, subscription info |
+<!-- BEGIN:DOMAINS -->
+| Namespace | Endpoints | What it covers |
+|-----------|-----------|----------------|
+| `roxy.astrology` | 22 | Western astrology: natal charts, horoscopes, synastry, moon phases |
+| `roxy.vedicAstrology` | 42 | Vedic/Jyotish: birth charts, dashas, nakshatras, panchang, KP system |
+| `roxy.tarot` | 10 | 78-card readings: spreads, daily pulls, yes/no, Celtic Cross |
+| `roxy.numerology` | 16 | Life path, expression, soul urge, personal year, karmic lessons |
+| `roxy.dreams` | 5 | Dream symbol dictionary: 3,000+ interpretations |
+| `roxy.angelNumbers` | 4 | Angel number lookup, pattern analysis, daily guidance |
+| `roxy.iching` | 9 | I Ching hexagrams, trigrams, daily readings |
+| `roxy.crystals` | 12 | Crystal meanings, healing properties, zodiac and chakra pairings |
+| `roxy.biorhythm` | 6 | 10-cycle biorhythm readings, forecasts, critical days, compatibility |
+| `roxy.location` | 3 | City and country search for birth chart coordinates |
+| `roxy.usage` | 1 | API usage stats, rate limits, subscription info |
+<!-- END:DOMAINS -->
 
 ## Authentication
 
@@ -89,6 +92,19 @@ const client = createClient(
 const roxy = new Roxy({ client });
 ```
 
+## Multi-language responses
+
+Interpretations, readings, and editorial text are available in 8 languages: English (`en`), Turkish (`tr`), German (`de`), Spanish (`es`), French (`fr`), Hindi (`hi`), Portuguese (`pt`), Russian (`ru`). Pass `query: { lang }` on any supported endpoint:
+
+```typescript
+const { data } = await roxy.tarot.getDailyCard({
+  body: { date: '2026-04-14' },
+  query: { lang: 'es' },
+});
+```
+
+Supported domains: `astrology`, `vedicAstrology`, `tarot`, `numerology`, `crystals`, `iching`, `angelNumbers`, `biorhythm`. `dreams`, `location`, and `usage` are English-only (dream content is pre-authored, and the other two are structural). Languages without translations yet fall back to English.
+
 ## Error handling
 
 Every method returns `{ data, error, response }`. Errors have `{ error: string, code: string }` — switch on `code` for programmatic handling.

docs/llms-full.txt

@@ -9,6 +9,15 @@ import { createRoxy } from '@roxyapi/sdk';
 const roxy = createRoxy(process.env.ROXY_API_KEY!);
 ```
 
+**Multi-language responses.** Interpretations are available in 8 languages: `en`, `tr`, `de`, `es`, `fr`, `hi`, `pt`, `ru`. Pass `query: { lang }` on any supported endpoint. Supported: astrology, vedicAstrology, tarot, numerology, crystals, iching, angelNumbers, biorhythm. English-only: dreams, location, usage. Languages without translations yet fall back to English.
+
+```typescript
+const { data } = await roxy.astrology.getDailyHoroscope({
+  path: { sign: 'aries' },
+  query: { lang: 'es' },
+});
+```
+
 ---
 
 ## Astrology (Western) — `roxy.astrology`
@@ -613,6 +622,48 @@ const { data } = await roxy.dreams.getDailyDreamSymbol({ body: { date: '2026-03-
 
 ---
 
+## Biorhythm — `roxy.biorhythm`
+
+10-cycle biorhythm calculations (physical, emotional, intellectual, intuitive, aesthetic, awareness, spiritual, passion, mastery, wisdom). All methods are POST. Only `birthDate` (`YYYY-MM-DD`) is required; dates default to today (UTC) when omitted. Every method accepts an optional `query: { lang }` (`en`, `tr`, `de`, `es`, `hi`, `pt`, `fr`, `ru`).
+
+```typescript
+// Complete reading for a target date — all 10 cycles, phase detection, energy rating, interpretation, advice, critical day alerts
+const { data } = await roxy.biorhythm.getReading({
+  body: { birthDate: '1990-01-15', targetDate: '2026-04-14' },
+});
+
+// Multi-day forecast (max 90-day range). Returns daily cycle values, energy ratings, critical days, best/worst day summary
+const { data } = await roxy.biorhythm.getForecast({
+  body: { birthDate: '1990-01-15', startDate: '2026-04-14', endDate: '2026-05-14' },
+});
+
+// Critical days (zero crossings) in a range (max 180 days). Flags rare double and triple critical days
+const { data } = await roxy.biorhythm.getCriticalDays({
+  body: { birthDate: '1990-01-15', startDate: '2026-04-14', endDate: '2026-07-14' },
+});
+
+// Compatibility between two people on a target date (per-cycle scores, overall rating, strengths, challenges, advice)
+const { data } = await roxy.biorhythm.calculateBioCompatibility({
+  body: {
+    person1: { birthDate: '1990-01-15' },
+    person2: { birthDate: '1988-06-22' },
+    targetDate: '2026-04-14',
+  },
+});
+
+// Lightweight phase info for dashboards and widgets — no editorial text
+const { data } = await roxy.biorhythm.getPhases({
+  body: { birthDate: '1990-01-15' },
+});
+
+// Daily check-in with seeded randomness — same seed + same date = same reading (perfect for push notifications)
+const { data } = await roxy.biorhythm.getDailyBiorhythm({
+  body: { birthDate: '1990-01-15', seed: 'user-123' },
+});
+```
+
+---
+
 ## Location — `roxy.location`
 
 Geocoding helper for birth chart coordinates.

lefthook.yml

@@ -7,6 +7,10 @@ pre-commit:
       stage_fixed: true
     typecheck:
       run: bun typecheck
+    docs-sync:
+      glob: "{specs/openapi.json,scripts/tag-descriptions.ts,scripts/sync-docs.ts,docs/llms-full.txt}"
+      run: bun run docs:sync && git add README.md AGENTS.md
+      stage_fixed: true
 
 pre-push:
   parallel: false
@@ -17,6 +21,9 @@ pre-push:
     biome-full:
       run: bun run check
       priority: 2
+    docs-drift:
+      run: bun run docs:sync && git diff --exit-code -- README.md AGENTS.md || { echo "✗ README.md/AGENTS.md drifted from spec — commit the sync output"; exit 1; }
+      priority: 3
     test:
       run: bun run test
-      priority: 3
+      priority: 4

package.json

@@ -26,6 +26,7 @@
 	],
 	"scripts": {
 		"generate": "bun run scripts/generate.ts",
+		"docs:sync": "bun run scripts/sync-docs.ts",
 		"build": "tsup src/factory.ts src/client/index.ts --format esm,cjs && tsc -p tsconfig.build.json --emitDeclarationOnly",
 		"typecheck": "tsc --noEmit",
 		"test": "vitest run",

scripts/generate.ts

@@ -28,3 +28,6 @@ console.log('Spec saved to', SPEC_PATH);
 console.log('Running hey-api generator...');
 execSync('bunx openapi-ts', { stdio: 'inherit' });
 console.log('SDK generated successfully.');
+
+console.log('Syncing README.md and AGENTS.md from spec...');
+execSync('bun run scripts/sync-docs.ts', { stdio: 'inherit' });

scripts/sync-docs.ts

@@ -0,0 +1,116 @@
+#!/usr/bin/env bun
+/**
+ * Regenerate the domain tables in README.md and AGENTS.md from
+ * `specs/openapi.json`. Also verifies every spec tag is mentioned
+ * somewhere in `docs/llms-full.txt`.
+ *
+ * Run with: bun run docs:sync
+ *
+ * Fails loudly if:
+ *   - A new OpenAPI tag lands that has no entry in `scripts/tag-descriptions.ts`.
+ *   - An entry in `scripts/tag-descriptions.ts` refers to a tag that no
+ *     longer exists in the spec.
+ *   - A tag is missing a section in `docs/llms-full.txt`.
+ *   - README.md or AGENTS.md is missing the `<!-- BEGIN:DOMAINS -->` markers.
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { tagDescriptions } from './tag-descriptions';
+
+type OpenApiSpec = {
+	tags?: Array<{ name: string }>;
+	paths?: Record<string, Record<string, { tags?: string[] }>>;
+};
+
+const SPEC_PATH = 'specs/openapi.json';
+const LLMS_PATH = 'docs/llms-full.txt';
+const README_PATH = 'README.md';
+const AGENTS_PATH = 'AGENTS.md';
+const BEGIN = '<!-- BEGIN:DOMAINS -->';
+const END = '<!-- END:DOMAINS -->';
+
+function fail(msg: string): never {
+	console.error(`\n✗ sync-docs: ${msg}\n`);
+	process.exit(1);
+}
+
+const spec = JSON.parse(readFileSync(SPEC_PATH, 'utf-8')) as OpenApiSpec;
+
+const specTags = (spec.tags ?? []).map((t) => t.name);
+if (specTags.length === 0)
+	fail(`${SPEC_PATH} has no .tags[] — spec is malformed?`);
+
+const unknown = specTags.filter((t) => !(t in tagDescriptions));
+if (unknown.length > 0) {
+	fail(
+		`Unknown tag(s) in spec: ${unknown.map((t) => `"${t}"`).join(', ')}. Add entries to scripts/tag-descriptions.ts before releasing.`,
+	);
+}
+
+const stale = Object.keys(tagDescriptions).filter((t) => !specTags.includes(t));
+if (stale.length > 0) {
+	fail(
+		`Stale tag(s) in scripts/tag-descriptions.ts (not in spec): ${stale.map((t) => `"${t}"`).join(', ')}. Remove them.`,
+	);
+}
+
+const endpointCounts = new Map<string, number>();
+for (const methods of Object.values(spec.paths ?? {})) {
+	for (const op of Object.values(methods)) {
+		const tag = op.tags?.[0];
+		if (tag) endpointCounts.set(tag, (endpointCounts.get(tag) ?? 0) + 1);
+	}
+}
+
+const llms = readFileSync(LLMS_PATH, 'utf-8');
+const missingInLlms = specTags.filter((t) => {
+	const entry = tagDescriptions[t];
+	return entry && !llms.includes(entry.namespace);
+});
+if (missingInLlms.length > 0) {
+	fail(
+		`Tag(s) missing from ${LLMS_PATH}: ${missingInLlms.map((t) => `"${t}"`).join(', ')}. Add a section for each before releasing.`,
+	);
+}
+
+function renderTable(kind: 'readme' | 'agent'): string {
+	const rows = specTags.map((tag) => {
+		const entry = tagDescriptions[tag];
+		if (!entry) throw new Error(`unreachable: tag ${tag} missing after check`);
+		const count = endpointCounts.get(tag) ?? 0;
+		const desc =
+			kind === 'readme' ? entry.readmeDescription : entry.agentDescription;
+		return `| \`${entry.namespace}\` | ${count} | ${desc} |`;
+	});
+	return [
+		BEGIN,
+		'| Namespace | Endpoints | What it covers |',
+		'|-----------|-----------|----------------|',
+		...rows,
+		END,
+	].join('\n');
+}
+
+function syncFile(path: string, kind: 'readme' | 'agent'): boolean {
+	const src = readFileSync(path, 'utf-8');
+	const beginIdx = src.indexOf(BEGIN);
+	const endIdx = src.indexOf(END);
+	if (beginIdx === -1 || endIdx === -1 || endIdx < beginIdx) {
+		fail(`${path} is missing ${BEGIN} / ${END} markers`);
+	}
+	const before = src.slice(0, beginIdx);
+	const after = src.slice(endIdx + END.length);
+	const next = `${before}${renderTable(kind)}${after}`;
+	if (next === src) return false;
+	writeFileSync(path, next);
+	return true;
+}
+
+const readmeChanged = syncFile(README_PATH, 'readme');
+const agentsChanged = syncFile(AGENTS_PATH, 'agent');
+
+const totalEndpoints = [...endpointCounts.values()].reduce((a, b) => a + b, 0);
+console.log(
+	`✓ sync-docs: ${specTags.length} tags, ${totalEndpoints} endpoints. ` +
+		`README ${readmeChanged ? 'updated' : 'unchanged'}, ` +
+		`AGENTS ${agentsChanged ? 'updated' : 'unchanged'}.`,
+);