docs: server-side usage, drop publishable-key promise, add Human Design and Forecast

Rewrite getting-started and integration docs around server-side usage with a secret key, since browser-safe publishable keys are not shipped yet. Start with one component now mirrors the SDK quick start: one typed call, render the result. Remove every publishable-key instruction from the README, AGENTS, and examples; widgets auto-mount is labelled coming soon. The server-rendered section loads the bundle once.

Add Human Design and Forecast to the most-used-components guide in canonical order, and rework the vanilla, vue, and WordPress examples to fetch server side and inline the response so no key ships to the browser.

Author: ph33nx

AGENTS.md

@@ -120,16 +120,13 @@ const { data: chart } = await roxy.astrology.generateNatalChart({
 
 Every chart endpoint accepts `timezone` as either a decimal-hour offset (`5.5` for IST, `-5` for EST) or an IANA name (`'Asia/Kolkata'`, `'America/New_York'`). The decimal form is what `/location/search` returns; the IANA form is correct over DST boundaries. Pick one and stay consistent in a single integration. Mixing them does not break the API but makes the bug surface area larger.
 
-### 4. Secret key in the browser
+### 4. API key in the browser
 
-There are two key classes. **Secret keys are unprefixed** and grant full access; they belong server-side only (Node, Bun, Hono, Next.js route handlers, Workers, Edge functions). **Publishable keys** are prefixed `pk_live_*` or `pk_test_*` and are safe in the browser; they are locked to an origin allowlist at the API gateway. For widgets, embeds, vanilla HTML, and `data-publishable-key` use the publishable key. For the typed SDK on a server, use the secret key.
+Keys are server side only. Call `createRoxy(process.env.ROXY_API_KEY!)` on your server (Node, Bun, Hono, Next.js route handlers, Workers, Edge functions), then send the response, not the key, to the component. Never ship the key in a client bundle. Browser-safe keys for direct client-side embedding are on the roadmap, not yet available.
 
 ```ts
-// Server (Next.js route handler, Workers, Bun): secret key
+// Server side only
 const roxy = createRoxy(process.env.ROXY_API_KEY!);
-
-// Browser (widgets auto-mount): publishable key
-<div data-roxy-widget="natal-chart" data-publishable-key="pk_live_xxx" ...></div>
 ```
 
 ### 5. Missing `'use client'` in Next.js App Router
@@ -194,49 +191,49 @@ import type { NatalChartResponse } from '@roxyapi/sdk';
 
 ### Pattern 1: vanilla HTML, no build step
 
+Fetch on your server with the secret key, then inline the response into the component as a child `<script type="application/json" class="roxy-data">`. The component reads it on load. No key in the browser.
+
 ```html
 <script
 	src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/roxy-ui.js"
 	crossorigin="anonymous"
 ></script>
 
-<roxy-natal-chart id="chart"></roxy-natal-chart>
-
-<script type="module">
-	import { createRoxy } from 'https://cdn.jsdelivr.net/npm/@roxyapi/sdk@latest/dist/factory.js';
-	const roxy = createRoxy('pk_live_xxx');
-	const { data } = await roxy.astrology.generateNatalChart({
-		body: { date: '1990-01-15', time: '14:30:00', latitude: 19.07, longitude: 72.88, timezone: 5.5 },
-	});
-	document.getElementById('chart').data = data;
-</script>
+<roxy-natal-chart>
+	<script type="application/json" class="roxy-data">
+		{ "planets": [ ... ], "houses": [ ... ], "aspects": [ ... ] }
+	</script>
+</roxy-natal-chart>
 ```
 
-### Pattern 2: React, with the typed SDK
+Setting the JavaScript `data` property always wins over the inlined JSON, so the same element also drives dynamic pages.
+
+### Pattern 2: React, interactive
+
+`<RoxyLocationSearch>` runs in the browser. On select, call your own route, which holds the secret key, and set the returned data on the chart. The key never reaches the client.
 
 ```tsx
 'use client';
 
-import { createRoxy } from '@roxyapi/sdk';
 import {
 	RoxyNatalChart,
 	RoxyLocationSearch,
 	type RoxyNatalChartProps,
 } from '@roxyapi/ui-react';
 import { useState } from 'react';
 
-const roxy = createRoxy(process.env.NEXT_PUBLIC_ROXY_API_KEY!);
-
 export function BirthChartView() {
 	const [chart, setChart] = useState<RoxyNatalChartProps['data']>(undefined);
 
 	const onLocationSelect = async (e: CustomEvent<{ latitude?: number; longitude?: number; timezone?: number | string }>) => {
 		const { latitude, longitude, timezone } = e.detail;
 		if (latitude == null || longitude == null) return;
-		const { data } = await roxy.astrology.generateNatalChart({
-			body: { date: '1990-01-15', time: '14:30:00', latitude, longitude, timezone },
+		// Your route calls roxy.astrology.generateNatalChart with the secret key.
+		const res = await fetch('/api/natal-chart', {
+			method: 'POST',
+			body: JSON.stringify({ date: '1990-01-15', time: '14:30:00', latitude, longitude, timezone }),
 		});
-		setChart(data);
+		setChart(await res.json());
 	};
 
 	return (
@@ -248,51 +245,33 @@ export function BirthChartView() {
 }
 ```
 
+For a static chart with no picker, fetch in a Server Component and pass `data` to a client component (Pattern 6).
+
 ### Pattern 3: schema-driven form
 
-`<roxy-endpoint-form>` reads the OpenAPI spec and renders the inputs for any endpoint. Listen for the `roxy-submit` event with the validated payload.
+`<roxy-endpoint-form>` reads the OpenAPI spec and renders the inputs for any endpoint. On `roxy-submit`, POST the validated values to your own route, which calls the SDK with the secret key, then set the returned data on the target component.
 
 ```html
 <roxy-endpoint-form
 	data-endpoint="vedic-astrology/birth-chart"
 	method="POST"
 	submit-label="Generate kundli"
 ></roxy-endpoint-form>
+<roxy-vedic-kundli chart-style="south"></roxy-vedic-kundli>
 
 <script type="module">
-	import { createRoxy } from 'https://cdn.jsdelivr.net/npm/@roxyapi/sdk@latest/dist/factory.js';
-	const roxy = createRoxy('pk_live_xxx');
 	const form = document.querySelector('roxy-endpoint-form');
 	form.addEventListener('roxy-submit', async (e) => {
-		const { values } = e.detail;
-		const { data: kundli } = await roxy.vedicAstrology.generateBirthChart({ body: values });
-		document.querySelector('roxy-vedic-kundli').data = kundli;
+		// Your route calls roxy.vedicAstrology.generateBirthChart with the secret key.
+		const res = await fetch('/api/kundli', { method: 'POST', body: JSON.stringify(e.detail.values) });
+		document.querySelector('roxy-vedic-kundli').data = await res.json();
 	});
 </script>
 ```
 
-### Pattern 4: widgets auto-mount (no JavaScript wiring)
-
-Use a publishable key (`pk_live_*` or `pk_test_*`) for client-side embeds. Get one at <https://roxyapi.com/account>. Publishable keys are origin-restricted at the API gateway. Register the customer domain (e.g. `https://customer.com`) when creating the key, and the gateway will reject requests from any other origin. Never use a secret key in client-side code (secret keys are unprefixed and live server-side only).
-
-```html
-<script
-	src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/widgets.js"
-	defer
-></script>
-
-<div
-	data-roxy-widget="natal-chart"
-	data-publishable-key="pk_live_xxx"
-	data-date="1990-01-15"
-	data-time="14:30:00"
-	data-latitude="19.07"
-	data-longitude="72.88"
-	data-timezone="5.5"
-></div>
-```
+### Pattern 4: widgets auto-mount (coming soon)
 
-The auto-mount script reads `data-*` attributes, calls the matching endpoint, and renders the matching component.
+A zero-wiring embed that reads `data-*` attributes and renders the matching component is on the roadmap. It needs browser-safe keys, which are not yet available. Until then, use Pattern 1 (inline JSON) for no-build pages.
 
 ### Pattern 5: MCP tool-call response
 
@@ -396,7 +375,7 @@ Every visible aspect of the chart is driven by `--roxy-*` CSS custom properties
 
 ## Domain ordering
 
-When listing domains in user-visible copy, use the canonical order: Western astrology, Vedic astrology, numerology, tarot, biorhythm, I Ching, crystals, dreams, angel numbers. Location is utility, not a selling domain.
+When listing domains in user-visible copy, use the canonical order: Western astrology, Vedic astrology, numerology, tarot, human design, forecast, biorhythm, I Ching, crystals, dreams, angel numbers. Location is utility, not a selling domain.
 
 ## What not to ship
 

README.md

@@ -221,42 +221,24 @@ Tables, cards, forms, and helper components in the [live demo](https://roxyapi.g
 
 ## Start with one component
 
-Vanilla HTML. No build step. Replace `YOUR_API_KEY` with a publishable key from <https://roxyapi.com/account>.
+Fetch with the typed SDK, pass `data` to the component. No glue code.
 
-```html
-<script
-	src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/roxy-ui.js"
-	crossorigin="anonymous"
-	defer
-></script>
-<roxy-natal-chart id="chart"></roxy-natal-chart>
-<script type="module">
-	import { createRoxy } from 'https://cdn.jsdelivr.net/npm/@roxyapi/sdk@latest/dist/factory.js';
-	const roxy = createRoxy('YOUR_API_KEY');
-	const { data } = await roxy.astrology.generateNatalChart({
-		body: { date: '1990-01-15', time: '14:30:00', latitude: 19.07, longitude: 72.88, timezone: 5.5 },
-	});
-	document.getElementById('chart').data = data;
-</script>
-```
+```tsx
+import { createRoxy } from '@roxyapi/sdk';
+import { RoxyHoroscopeCard } from '@roxyapi/ui-react';
 
-> **Unwrap `data` before passing to the component.** The SDK returns `{ data, error, request, response }`. Pass the envelope and the chart renders `[object Object]`. This is the most common integration bug.
+const roxy = createRoxy(process.env.ROXY_API_KEY!);
 
-Want a Vedic kundli instead? Same shape, different SDK method:
+const { data } = await roxy.astrology.getDailyHoroscope({ path: { sign: 'aries' } });
 
-```html
-<roxy-vedic-kundli id="kundli" chart-style="south"></roxy-vedic-kundli>
-<script type="module">
-	import { createRoxy } from 'https://cdn.jsdelivr.net/npm/@roxyapi/sdk@latest/dist/factory.js';
-	const roxy = createRoxy('YOUR_API_KEY');
-	const { data } = await roxy.vedicAstrology.generateBirthChart({
-		body: { date: '1990-01-15', time: '14:30:00', latitude: 19.07, longitude: 72.88, timezone: 5.5 },
-	});
-	document.getElementById('kundli').data = data;
-</script>
+return <RoxyHoroscopeCard data={data} />;
 ```
 
-In production, geocode the user's city with `<roxy-location-search>` (see [Quick start](#quick-start)) instead of hardcoding coordinates.
+Then expand into natal charts, kundli, dasha, tarot, and every other domain. The SDK returns `data`, the component renders it; the same pairing holds for all 32 components.
+
+> **Pass `data`, not the envelope.** The SDK returns `{ data, error, request, response }`. Pass `data`, or the component renders `[object Object]`. This is the most common integration bug.
+
+The key stays on your server. Vanilla HTML or a server-rendered page fetches the same way, then [inlines the JSON into the component](#server-rendered-no-javascript-wiring): no build step, no key in the browser. Try every component in the [live demo](https://roxyapi.github.io/ui/), each with Preview, Code, and shadcn tabs and a live color customizer.
 
 ## Install
 
@@ -312,7 +294,12 @@ Always call `/location/search` first. Every chart endpoint expects latitude, lon
 
 Server-rendered and cached pages (WordPress, JSX SSR, static HTML) cannot always run JavaScript to set the `data` property per element. Render the response into a child `<script type="application/json" class="roxy-data">` on the server instead. The component reads it on load. No per-element script, no API key in the browser.
 
+Load the bundle once anywhere on the page. It registers every `roxy-*` element, so every component on the page renders from that single tag.
+
 ```html
+<!-- Once per page: defines every roxy-* element -->
+<script src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/roxy-ui.js" crossorigin="anonymous" defer></script>
+
 <roxy-natal-chart>
 	<script type="application/json" class="roxy-data">
 		{ "planets": [ ... ], "houses": [ ... ], "aspects": [ ... ] }
@@ -464,7 +451,48 @@ const { data: cc } = await roxy.tarot.castCelticCross({
 <RoxyTarotSpread data={cc} />
 ```
 
-### 5. Biorhythm (daily, forecast)
+### 5. Human Design (bodygraph)
+
+The breakout 2026 self-knowledge category, computed from the same ephemeris as Western astrology plus the I Ching gate wheel and chakra-style centers. Self-discovery apps, dating and compatibility products, and AI coaching bots ship the full bodygraph first. No coordinates needed; Human Design uses the birth instant, not the observer location.
+
+```tsx
+import { RoxyBodygraph } from '@roxyapi/ui-react';
+
+// Full bodygraph. The head term every Human Design app leads with ("human design chart").
+// Type, strategy, authority, profile, the nine centers, channels, and every gate
+// activation in one call. Pass the birth instant only, no latitude or longitude.
+const { data: bodygraph } = await roxy.humanDesign.generateBodygraph({
+  body: { date: '1990-01-15', time: '14:30:00', timezone: 5.5 },
+});
+<RoxyBodygraph data={bodygraph} />
+```
+
+### 6. Forecast (transits, cross-domain timeline)
+
+The first cross-domain, stateless forecast in the catalog: one call merges Western transits, Vedic Vimshottari dasha boundaries, and biorhythm critical days into a single significance-scored, time-ordered timeline. Forecast feeds, transit alerts, and timing tools are the buyers. Acquire on the high-volume `astrology transits` search, convert on the cross-domain timeline no competitor ships. No coordinates needed.
+
+```tsx
+import { RoxyForecastTimeline } from '@roxyapi/ui-react';
+
+// Transit forecast. The demand leader. Western transit-to-natal aspects, sign
+// ingresses, and retrograde stations over the window.
+const { data: transits } = await roxy.forecast.forecastTransits({
+  body: { birthData: { date: '1990-01-15', time: '14:30:00', timezone: 5.5 } },
+});
+<RoxyForecastTimeline data={transits} />
+
+// Cross-domain timeline. The same window merged with Vedic dasha boundaries and
+// biorhythm critical days into one significance-scored timeline.
+const { data: timeline } = await roxy.forecast.generateTimeline({
+  body: {
+    birthData: { date: '1990-01-15', time: '14:30:00', timezone: 5.5 },
+    domains: ['western', 'vedic', 'biorhythm'],
+  },
+});
+<RoxyForecastTimeline data={timeline} />
+```
+
+### 7. Biorhythm (daily, forecast)
 
 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.
 
@@ -485,7 +513,7 @@ const { data: forecast } = await roxy.biorhythm.getForecast({
 <RoxyBiorhythmChart data={forecast} mode="forecast" />
 ```
 
-### 6. I Ching (cast a reading, hexagram lookup)
+### 8. I Ching (cast a reading, hexagram lookup)
 
 Meditation apps, decision-making tools, and wisdom chatbots. `i ching API` and `hexagram API` are the keywords.
 
@@ -505,12 +533,13 @@ const { data: random } = await roxy.iching.getRandomHexagram();
 
 ## API keys
 
-Get keys at <https://roxyapi.com/account>.
+Get a key at <https://roxyapi.com/account>.
+
+Today every key is a **secret key**: use it server side only (Node, Bun, Hono, Next.js route handlers, Workers). Never commit it, never ship it in a client bundle. Fetch on your server and send the rendered response, not the key, to the browser. The [Start with one component](#start-with-one-component) section and the [framework recipes](#most-used-components-per-domain) show the pattern.
 
-- **Secret key** (server-side only). Use in Node, Bun, Hono, Next.js route handlers, Workers. Never commit, never ship in client bundles.
-- **Publishable key** (`pk_live_*` / `pk_test_*`). Safe in browsers, locked to the origins you register on the key. Use with the widgets auto-mount script for WordPress, Shopify, static HTML, embed scenarios. The API gateway rejects requests from any origin not on the allowlist.
+Set `ROXY_API_KEY` to your secret key in your server env for every SDK example on this page.
 
-For the SDK examples on this page, set `ROXY_API_KEY` to a secret key in your server env. For the widgets auto-mount path (`data-publishable-key="pk_live_xxx"`), use a publishable key with your domain registered on it.
+Browser-safe keys for direct client-side embedding are on the roadmap, not yet available. Until they ship, keep the fetch on your server.
 
 ## Distribution
 
@@ -520,7 +549,7 @@ For the SDK examples on this page, set `ROXY_API_KEY` to a secret key in your se
 | npm `@roxyapi/ui-react` | `npmjs.com/package/@roxyapi/ui-react` |
 | jsDelivr CDN (full bundle) | `cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/roxy-ui.js` |
 | jsDelivr CDN (per component) | `cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/components/{name}.js` |
-| Widgets auto-mount | `cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/widgets.js` |
+| Widgets auto-mount (with browser keys, coming soon) | `cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/widgets.js` |
 | shadcn registry | `npx shadcn@latest add https://cdn.jsdelivr.net/gh/RoxyAPI/ui@latest/registry/{name}.json` |
 
 ## Components
@@ -770,7 +799,7 @@ Components ship in Shadow DOM for style isolation; Tailwind utilities are scoped
 <details>
 <summary><strong>What is the security model for API keys?</strong></summary>
 
-Two key classes. Secret keys (unprefixed) live server-side only and grant full access. Publishable keys (`pk_live_*` / `pk_test_*`) are browser-safe and locked to an origin allowlist registered on the key. The API gateway rejects requests from any other origin and counts the failed attempt against the rate limit, so a stolen key cannot be brute-fired from elsewhere.
+Today keys are secret keys: they live server side only and grant full access, so never ship one in a client bundle. Fetch on your server and pass the rendered response, not the key, to the browser. Browser-safe keys with an origin allowlist for direct client-side embedding are on the roadmap and not yet available.
 
 For CSP, allow `script-src https://cdn.jsdelivr.net` if loading the bundle from the CDN. Subresource Integrity hashes are available via the jsDelivr SRI API for any pinned version.
 </details>
@@ -781,11 +810,11 @@ For CSP, allow `script-src https://cdn.jsdelivr.net` if loading the bundle from
 Semver. Pre-1.0, minor bumps may include breaking changes (we will note them in the changelog). Patch bumps are always backwards-compatible. Pin a concrete version in production code:
 
 ```bash
-npm install @roxyapi/ui@0.1.x
+npm install @roxyapi/ui@0.8.x
 ```
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@0.1.5/dist/cdn/roxy-ui.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@0.8.0/dist/cdn/roxy-ui.js"></script>
 ```
 
 The `@latest` URL on this page is for paste-friendly marketing; production code should pin.