docs: demonstrate chinese astrology and feng shui

This README has no per-domain example sections, so the two new domains go
where the others already live: one runnable example file each, listed
beside human-design.php and forecast.php. Both were run against the live
API before committing, so the printed field paths are the real ones.

The breadth prose outside the DOMAINS markers is hand-written and had
gone stale in the same way it did in the other SDKs.

Author: ph33nx

AGENTS.md

@@ -1,6 +1,6 @@
 # roxyapi/sdk - Agent Guide
 
-PHP 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, one Composer package, zero hand-written endpoint code.
+PHP SDK for RoxyAPI. 14+ domains (Western astrology, Vedic astrology, forecast, human design, Chinese astrology, feng shui, numerology, tarot, biorhythm, I Ching, crystals, dreams, angel numbers, location) plus utility namespaces (usage, languages). One API key, one Composer package, zero hand-written endpoint code.
 
 ## Install and initialize
 
@@ -54,7 +54,7 @@ $result = $roxy->location->searchCities(q: 'New York');
 | `$roxy->languages` | List the response languages accepted by the `lang` query parameter on every i18n-aware endpoint |
 <!-- END:DOMAINS -->
 
-160+ endpoints across 12+ product domains plus usage and languages. The table above auto-syncs from `specs/openapi.json` at release time.
+209+ endpoints across 14+ product domains plus usage and languages. The table above auto-syncs from `specs/openapi.json` at release time.
 
 ## Critical patterns
 
@@ -112,7 +112,7 @@ $roxy->tarot->getDailyCard(date: '2026-04-22', lang: 'es');
 $roxy->numerology->calculateLifePath(year: 1990, month: 1, day: 15, lang: 'hi');
 ```
 
-Supported: `astrology`, `vedicAstrology`, `numerology`, `tarot`, `biorhythm`, `iching`, `crystals`, `angelNumbers`. English-only: `dreams`, `location`, `usage`, `languages`. To list supported codes at runtime, call `$roxy->languages->listLanguages()`.
+Supported: `astrology`, `vedicAstrology`, `forecast`, `humanDesign`, `chineseAstrology`, `fengShui`, `numerology`, `tarot`, `biorhythm`, `iching`, `crystals`, `angelNumbers`. English-only: `dreams`, `location`, `usage`, `languages`. The two Chinese scripts (`zh-Hans`, `zh-Hant`) currently ship on Chinese astrology and feng shui; every other domain answers those codes in English per field. To list supported codes at runtime, call `$roxy->languages->listLanguages()`.
 
 ### Error handling
 

README.md

@@ -9,7 +9,7 @@
 [![Packagist](https://img.shields.io/packagist/v/roxyapi/sdk.svg)](https://packagist.org/packages/roxyapi/sdk)
 [![PHP Version](https://img.shields.io/packagist/php-v/roxyapi/sdk.svg)](https://packagist.org/packages/roxyapi/sdk)
 
-Official PHP SDK for [RoxyAPI](https://roxyapi.com): natal charts, daily horoscopes, synastry, Vedic kundli, tarot spreads, human design bodygraphs, and transit forecasts across Western and Vedic astrology, numerology, tarot, human design, forecast, biorhythm, I Ching, crystals, dreams, angel numbers, and location geocoding. 160+ endpoints across 12+ domains, one API key, one dependency (Saloon).
+Official PHP SDK for [RoxyAPI](https://roxyapi.com): natal charts, daily horoscopes, synastry, Vedic kundli, tarot spreads, human design bodygraphs, and transit forecasts across Western and Vedic astrology, forecast, human design, Chinese astrology, feng shui, numerology, tarot, biorhythm, I Ching, crystals, dreams, angel numbers, and location geocoding. 209+ endpoints across 14+ domains, one API key, one dependency (Saloon).
 
 ## Install
 
@@ -135,6 +135,8 @@ $result = $roxy->astrology->getDailyHoroscope(sign: 'aries');
 - `examples/laravel.php` - Laravel service provider snippet
 - `examples/human-design.php` - full Human Design bodygraph, prints type, strategy, and profile
 - `examples/forecast.php` - cross-domain forecast timeline, prints the event count and a sample event
+- `examples/chinese-astrology.php` - BaZi four pillars plus the zodiac sign, prints the pillars and the conventions used
+- `examples/feng-shui.php` - Kua number and a flying star natal chart, prints the eight sectors and the nine palaces
 - `examples/render-with-ui.html` - server-side fetch + browser render via `@roxyapi/ui`
 
 ## Documentation

examples/chinese-astrology.php

@@ -0,0 +1,67 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Chinese astrology example: BaZi four pillars plus the zodiac sign.
+ *
+ *   ROXY_API_KEY=your-key php examples/chinese-astrology.php
+ */
+
+require __DIR__ . '/../vendor/autoload.php';
+
+use RoxyAPI\Sdk\RoxyApiException;
+
+use function RoxyAPI\Sdk\createRoxy;
+
+$apiKey = getenv('ROXY_API_KEY') ?: '';
+if ('' === $apiKey) {
+    fwrite(STDERR, "Set ROXY_API_KEY before running this example.\n");
+    exit(1);
+}
+
+$roxy = createRoxy($apiKey);
+
+try {
+    // The anchor call of the domain: the rest of it reads off these four pillars.
+    // timezone is an IANA name, decimal hours (5.5 = IST), or a fixed offset.
+    // Prefer the IANA name: it resolves to the DST-correct offset for the birth date.
+    $bazi = $roxy->chineseAstrology->generateBaziChart(
+        date: '1990-07-04',
+        time: '10:12:00',
+        timezone: 'America/New_York',
+    );
+
+    echo "=== BaZi four pillars (1990-07-04 10:12 America/New_York) ===\n";
+    foreach ($bazi['pillars'] ?? [] as $pillar) {
+        printf(
+            "%-6s %-10s %s %s / %s %s   %s\n",
+            $pillar['position'] ?? '?',
+            $pillar['id'] ?? '?',
+            $pillar['stem']['chinese'] ?? '?',
+            $pillar['stem']['element'] ?? '?',
+            $pillar['branch']['chinese'] ?? '?',
+            $pillar['branch']['animal'] ?? '?',
+            $pillar['tenGod']['name'] ?? '?',
+        );
+    }
+    echo 'Day Master: ' . ($bazi['dayMaster']['element'] ?? '?')
+        . ' (' . ($bazi['dayMaster']['polarity'] ?? '?') . ")\n";
+
+    // The conventions echo is what lets a caller reproduce a chart drawn elsewhere:
+    // the three school splits are typed parameters, not hidden defaults.
+    echo 'Conventions: ' . json_encode($bazi['conventions'] ?? []) . "\n\n";
+
+    // The most searched question in the domain. Defaults yearBoundary to
+    // "lunar-new-year", the folk rule people mean when they say which animal
+    // they are; pass "li-chun" to match the classical BaZi boundary above.
+    $sign = $roxy->chineseAstrology->calculateZodiacAnimal(date: '1990-07-04');
+
+    echo "=== Chinese zodiac sign ===\n";
+    echo 'Animal: ' . ($sign['animal']['name'] ?? '?')
+        . ' (' . ($sign['animal']['element'] ?? '?') . ' ' . ($sign['animal']['polarity'] ?? '?') . ")\n";
+    echo 'Year boundary used: ' . ($sign['conventions']['yearBoundary'] ?? '?') . "\n";
+} catch (RoxyApiException $e) {
+    fwrite(STDERR, "[{$e->statusCode}] {$e->errorCode}: {$e->error}\n");
+    exit(3);
+}

examples/feng-shui.php

@@ -0,0 +1,73 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Feng shui example: Kua number plus a flying star natal chart.
+ *
+ *   ROXY_API_KEY=your-key php examples/feng-shui.php
+ */
+
+require __DIR__ . '/../vendor/autoload.php';
+
+use RoxyAPI\Sdk\RoxyApiException;
+
+use function RoxyAPI\Sdk\createRoxy;
+
+$apiKey = getenv('ROXY_API_KEY') ?: '';
+if ('' === $apiKey) {
+    fwrite(STDERR, "Set ROXY_API_KEY before running this example.\n");
+    exit(1);
+}
+
+$roxy = createRoxy($apiKey);
+
+try {
+    // The entry point of the family: one birth date and a gender gives the
+    // personal directions everything else reads off.
+    $kua = $roxy->fengShui->calculateKuaNumber(date: '1990-07-04', gender: 'female');
+
+    echo "=== Kua number (1990-07-04, female) ===\n";
+    echo 'Kua ' . ($kua['kua'] ?? '?')
+        . ', ' . ($kua['group'] ?? '?') . ' group'
+        . ', trigram ' . ($kua['trigram']['english'] ?? '?') . "\n";
+    // Chinese years resolve at Li Chun, computed astronomically, so a January or
+    // early February birth date can belong to the previous solar year.
+    echo 'Solar year ' . ($kua['solarYear'] ?? '?')
+        . ' (boundary ' . ($kua['boundaryDate'] ?? '?') . ")\n";
+
+    foreach ($kua['sectors'] ?? [] as $sector) {
+        printf(
+            "  %-10s %-10s %-13s rank %d  %s\n",
+            $sector['direction'] ?? '?',
+            $sector['starName'] ?? '?',
+            $sector['nature'] ?? '?',
+            $sector['rank'] ?? 0,
+            $sector['domain'] ?? '?',
+        );
+    }
+    echo "\n";
+
+    // Period plus facing gives the nine palaces with base, mountain and water stars.
+    // Send facing (a mountain id like "bing" or a compass label like "S2") or
+    // facingDegrees, not neither.
+    $chart = $roxy->fengShui->generateFlyingStarChart(facing: 'S2', period: 9);
+
+    echo "=== Flying star natal chart (period 9, facing S2) ===\n";
+    echo 'Facing ' . ($chart['facing']['label'] ?? '?')
+        . ', sitting ' . ($chart['sitting']['label'] ?? '?')
+        . ' - ' . ($chart['structure']['name'] ?? '?') . "\n";
+
+    foreach ($chart['palaces'] ?? [] as $palace) {
+        printf(
+            "  %-10s base %d  mountain %d  water %d\n",
+            $palace['palace'] ?? '?',
+            $palace['base'] ?? 0,
+            $palace['mountain'] ?? 0,
+            $palace['water'] ?? 0,
+        );
+    }
+} catch (RoxyApiException $e) {
+    fwrite(STDERR, "[{$e->statusCode}] {$e->errorCode}: {$e->error}\n");
+    exit(3);
+}