@openephemeris/mcp-server 4.16.0 → 4.18.0

package/CHANGELOG.md

@@ -7,6 +7,52 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [4.18.0] — 2026-09-26
+
+### Fixed
+- **`explore_bi_wheel` progressed, solar return and lunar return modes work again.** They sent
+  requests the API rejected ("Validation failed" / "birth_datetime is required"); all six modes now
+  return a chart.
+- **Solar arc directions are exact.** `explore_bi_wheel` mode `solar_arc` used a flat ~1°-per-year
+  estimate and left the houses at their birth positions. It now uses the Sun's real arc from the API:
+  every planet, angle and house cusp is directed by the same arc, with correct signs and houses.
+  `ephemeris_progressed_chart` with `method: "solar_arc"` directs the angles and house cusps too.
+- **Every lunar node is named Mean or True.** The charts show "North Node (Mean)", "North Node
+  (True)", "South Node (Mean)" and "South Node (True)" as four separate points. The two South Nodes
+  used to merge into one, and the mean North Node was shown as a bare "North Node". The Mean/True
+  toggle now applies to the South Node as well.
+- **Bi-wheel recalculation keeps the house system you choose** for the outer chart too (it was always
+  Placidus).
+- **Black Moon Lilith appears on the chart wheel, named Mean, True or Interpolated.** Asking
+  `explore_natal_chart` for `lilith` or `lilith_true` returned the chart without it. The three Liliths
+  are now shown as "Lilith (Mean)", "Lilith (True)" and "Lilith (Interpolated)" (new slug
+  `lilith_interpolated`), never merged into one.
+- **`explore_natal_chart` with `bodies: ["all"]` works.** It was rejected because it asked for Vertex and
+  Part of Fortune as extra bodies; "all" now covers every body the chart can add.
+
+### Removed
+- **`include_visual` on `ephemeris_progressed_chart`.** The API never draws a progressed chart
+  image, so the option returned no picture. It was never charged. To see progressions over the natal
+  chart, use `explore_bi_wheel` with mode `progressed`.
+
+## [4.17.0] — 2026-09-24
+
+### Added
+- **Transit timelines show when each transit starts and ends.** `explore_transit_timeline` now asks
+  for orb windows (new `orb_deg` parameter, default 1°): every exact hit carries the in-orb window it
+  belongs to — the date the transit comes into orb and the date it leaves — and "pass 2 of 3" when a
+  retrograde brings the planet back over the same point without leaving the orb. Transits already in
+  orb at the start of the range are listed with whether they are applying or separating. The
+  interactive timeline shows the window on each card.
+- **Two new API capabilities reachable through `dev_read_api`:** orb windows on
+  `POST /predictive/transits/search` (`orb_deg`, `aspect_orbs`, `natal_points`, `aspects`) and the new
+  `POST /human-design/transit-timeline` — every gate (and line) a transiting planet enters and leaves
+  over a date range, and when a transit completes one of your channels. 121 public endpoints.
+
+### Fixed
+- **`dev_read_api` now reaches three endpoints it was missing:** `/ephemeris/draconic`,
+  `/ephemeris/prenatal-lunation` and `/predictive/primary-directions` (124 allowlisted operations).
+
 ## [4.16.0] — 2026-09-21
 
 ### Changed

package/README.md

@@ -212,7 +212,7 @@ The server is hosted at `https://mcp.openephemeris.com/mcp` with full Streamable
 
 - Missing/invalid credentials (`401`): tool call fails with a message that points users to sign up/sign in at `https://openephemeris.com/login?signup=true&redirect=%2Fdashboard%3Ftab%3Daccount`, then create/manage keys in `https://openephemeris.com/dashboard?tab=account`.
 - Tier-gated endpoint (`403`): tool call returns an upgrade-required message with `https://openephemeris.com/pay` and dashboard billing/key management link.
-- Monthly quota exhausted (`402`): tool call returns usage quota guidance with both dashboard (`/dashboard?tab=account`) and upgrade (`/pay`) links.
+- Out of credits (`402`): tool call returns a one-tap top-up link (Explorer's 150 free credits are one-time and do not reset; plan allowances renew each billing period) plus the dashboard usage link. Failed calls (any `4xx`/`5xx`) are refunded.
 - Burst/rate limit (`429`): tool call returns retry guidance and links to dashboard usage monitoring.
 
 ## What You Can Ask
@@ -256,13 +256,13 @@ instead of the picture, so nothing breaks, you just don't get the wheel.
 | Tool | What opens | What you can click | Credits |
 |---|---|---|---|
 | `explore_natal_chart` | Natal wheel — planets, houses, aspects, angles | Planets, houses, aspect lines; recalculate with new settings | 1 |
-| `explore_bi_wheel` | Two charts on one wheel: transits, synastry, progressions | Either wheel's planets, houses, and the aspects between them | 2 |
-| `explore_human_design` | Human Design bodygraph, with a mandala view toggle | Centers, gates, channels, planets, variables | 2 |
-| `explore_human_design_transit` | Today's planets laid over a natal bodygraph | Transit-activated channels | 3 |
-| `explore_human_design_connection` | Two bodygraphs combined, every shared channel classified | Connection channels by type | 3 |
+| `explore_bi_wheel` | Two charts on one wheel: transits, synastry, progressions | Either wheel's planets, houses, and the aspects between them | 2 (6 for solar/lunar return) |
+| `explore_human_design` | Human Design bodygraph, with a mandala view toggle | Centers, gates, channels, planets, variables | 4 |
+| `explore_human_design_transit` | Today's planets laid over a natal bodygraph | Transit-activated channels | 5 |
+| `explore_human_design_connection` | Two bodygraphs combined, every shared channel classified | Connection channels by type | 5 |
 | `explore_vedic_chart` | South Indian Rashi grid — sidereal placements and Lagna | Each rashi, for its placements and nakshatras | 3 |
 | `explore_bazi_chart` | Four Pillars (四柱命盘) — Year, Month, Day, Hour | Each pillar | 3 |
-| `explore_transit_timeline` | Upcoming transit hits in date order | Individual hits | 6 |
+| `explore_transit_timeline` | Upcoming transit hits in date order | Individual hits | 6 for up to 1 year (priced by span) |
 | `explore_moon_phase` | Moon dial — illumination, phase, sign, void-of-course | Recalculate for another moment | 3 |
 
 Ask for these the way you'd ask a person: *"show me my chart"*, *"put today's transits over my Human Design"*, *"what's the moon doing right now"*. The model picks the app.
@@ -300,10 +300,10 @@ Screenshots of each are on the way.
 | Lunar return | `ephemeris_lunar_return` | Explorer |
 | Planetary return | `ephemeris_planetary_return` | Explorer |
 | Astrocartography lines | `acg_power_lines` | Developer |
-| ACG hits at location | `acg_hits` | Scale |
+| ACG hits at location | `acg_hits` | Developer |
 | Venus Star Points | `venus_star_points` + 4 more | Explorer |
-| Chart wheel image | `ephemeris_chart_wheel` | Developer |
-| Bi-wheel image | `ephemeris_bi_wheel` | Developer |
+| Chart wheel image | `ephemeris_chart_wheel` | Explorer |
+| Bi-wheel image | `ephemeris_bi_wheel` | Explorer |
 | Dignities / Midpoints / Fixed stars | `ephemeris_dignities`, `ephemeris_midpoints`, `ephemeris_fixed_stars` | Explorer |
 
 ## Tooling Model
@@ -335,7 +335,7 @@ Screenshots of each are on the way.
 | `OPENEPHEMERIS_PROFILE` | No | `dev` by default |
 | `OPENEPHEMERIS_TOOLS` | No | `core` (default) advertises a focused everyday tool set; `full` advertises every tool. See [Tool surface](#tool-surface) |
 | `OPENEPHEMERIS_TELEMETRY` | No | Set to `0`/`false`/`off` to disable anonymous usage reporting. `DO_NOT_TRACK=1` also works. See [Telemetry](#telemetry) |
-| `OPENEPHEMERIS_SERVICE_KEY` | No | Internal service auth |
+| `OPENEPHEMERIS_SERVICE_KEY` | No | Internal service auth (stdio only; the hosted server refuses to start with one and always authenticates as the signed-in user) |
 | `OPENEPHEMERIS_JWT` | No | Bearer token auth |
 | `OPENEPHEMERIS_DEV_ALLOWLIST_PATH` | No | Override allowlist file path |
 | `MCP_USER_ID` | No | Per-instance user identifier |
@@ -490,8 +490,8 @@ When you update the MCP server logic (handlers, bug fixes, hardening), you shoul
 
 Generated by `npm run sync:readme` from `config/dev-allowlist.json` and the live tool registry.
 
-- Allowlisted operations: **120**
-- Methods: `GET=44`, `POST=76`, `PUT=0`, `PATCH=0`, `DELETE=0`
+- Allowlisted operations: **124**
+- Methods: `GET=44`, `POST=80`, `PUT=0`, `PATCH=0`, `DELETE=0`
 - Registered tools (`OPENEPHEMERIS_PROFILE=dev`): **92**
 - Typed tools: `account_usage`, `acg_hits`, `acg_power_lines`, `auth_login`, `auth_logout`, `auth_status`, `bazi_annual_pillar`, `bazi_chart`, `bazi_compatibility`, `bazi_element_balance`, `bazi_luck_pillars`, `bazi_recalculate`, `bazi_ten_gods`, `bi_wheel_on_cross_aspect_click`, `bi_wheel_on_house_click`, `bi_wheel_on_planet_click`, `bi_wheel_recalculate`, `bi_wheel_synopsis`, `bodygraph_recalculate`, `chart_wheel_on_aspect_click`, `chart_wheel_on_house_click`, `chart_wheel_on_planet_click`, `chart_wheel_recalculate`, `chinese_bazi`, `electional_angle_crossings`, `electional_aspect_search`, `electional_moment_analysis`, `electional_station_tracker`, `ephemeris_angles_points`, `ephemeris_aspect_check`, `ephemeris_bi_wheel`, `ephemeris_chart_wheel`, `ephemeris_composite`, `ephemeris_composite_midpoint`, `ephemeris_dignities`, `ephemeris_electional`, `ephemeris_fixed_stars`, `ephemeris_hermetic_lots`, `ephemeris_house_cusps`, `ephemeris_lunar_return`, `ephemeris_midpoints`, `ephemeris_moon_phase`, `ephemeris_natal_batch`, `ephemeris_natal_chart`, `ephemeris_natal_transits`, `ephemeris_next_eclipse`, `ephemeris_next_lunar_phase`, `ephemeris_overlay`, `ephemeris_planet_position`, `ephemeris_planetary_return`, `ephemeris_progressed_chart`, `ephemeris_relocation`, `ephemeris_retrograde_status`, `ephemeris_solar_return`, `ephemeris_synastry`, `ephemeris_transits`, `explore_bazi_chart`, `explore_bi_wheel`, `explore_human_design`, `explore_human_design_connection`, `explore_human_design_transit`, `explore_moon_phase`, `explore_natal_chart`, `explore_transit_timeline`, `explore_vedic_chart`, `hd_on_center_click`, `hd_on_channel_click`, `hd_on_connection_channel_click`, `hd_on_gate_click`, `hd_on_planet_click`, `hd_on_transit_channel_click`, `hd_on_variable_click`, `hd_opposition`, `hd_planetary_return`, `human_design_bodygraph`, `human_design_chart`, `human_design_composite`, `human_design_penta`, `location_search`, `moon_phase_recalculate`, `timezone_resolve`, `vedic_chart`, `vedic_chart_recalculate`, `venus_eight_year_star`, `venus_elongations`, `venus_phase`, `venus_star_points`, `venus_star_points_conjunctions`, `venus_stations`
 - Generic tools: `dev_list_allowed`, `dev_read_api`, `dev_write_api`
@@ -507,11 +507,11 @@ Generated by `npm run sync:readme` from `config/dev-allowlist.json` and the live
 | `comparative` | 5 | `POST /comparative/composite`, `POST /comparative/composite/midpoint` |
 | `eclipse` | 6 | `GET /eclipse/besselian-elements`, `GET /eclipse/lunar/global` |
 | `electional` | 6 | `GET /electional/angle-crossings`, `GET /electional/aspect-search` |
-| `ephemeris` | 36 | `GET /ephemeris/agro/calendar`, `GET /ephemeris/agro/daily` |
+| `ephemeris` | 38 | `GET /ephemeris/agro/calendar`, `GET /ephemeris/agro/daily` |
 | `health` | 2 | `GET /health`, `GET /health/detailed` |
-| `human-design` | 8 | `POST /human-design/chart`, `POST /human-design/composite` |
+| `human-design` | 9 | `POST /human-design/chart`, `POST /human-design/composite` |
 | `location` | 2 | `GET /location/autocomplete`, `GET /location/reverse` |
-| `predictive` | 10 | `POST /predictive/returns`, `POST /predictive/returns/lunar` |
+| `predictive` | 11 | `POST /predictive/primary-directions`, `POST /predictive/returns` |
 | `root` | 1 | `GET /` |
 | `tidal` | 2 | `GET /tidal/forcing`, `GET /tidal/forcing/deep-time` |
 | `time` | 6 | `GET /time/delta-t`, `GET /time/equation-of-time` |

package/config/dev-allowlist.json

@@ -1,7 +1,7 @@
 {
   "schema": "astromcp-dev-allowlist-v1",
   "description": "Allowlist derived from the Go sidecar openapi.json. Every entry in allow[] corresponds to a real Go endpoint. Run 'npm run check:dev-allowlist' to validate freshness.",
-  "generated_from": "C:\\src\\openephemeris\\.claude\\worktrees\\mcp-allowlist-gaps-b8befc\\apps\\api\\go-sidecar\\openapi.json",
+  "generated_from": "C:\\src\\openephemeris\\.claude\\worktrees\\adoring-rhodes-871fd7\\apps\\api\\go-sidecar\\openapi.json",
   "deny": {
     "path_prefixes": [
       "/auth",
@@ -235,6 +235,10 @@
       "method": "POST",
       "path": "/ephemeris/dispositor-tree"
     },
+    {
+      "method": "POST",
+      "path": "/ephemeris/draconic"
+    },
     {
       "method": "POST",
       "path": "/ephemeris/fixed-stars"
@@ -291,6 +295,10 @@
       "method": "POST",
       "path": "/ephemeris/planet-position"
     },
+    {
+      "method": "POST",
+      "path": "/ephemeris/prenatal-lunation"
+    },
     {
       "method": "POST",
       "path": "/ephemeris/progressed"
@@ -383,6 +391,10 @@
       "method": "POST",
       "path": "/human-design/transit-chart"
     },
+    {
+      "method": "POST",
+      "path": "/human-design/transit-timeline"
+    },
     {
       "method": "POST",
       "path": "/human-design/transit"
@@ -395,6 +407,10 @@
       "method": "GET",
       "path": "/location/reverse"
     },
+    {
+      "method": "POST",
+      "path": "/predictive/primary-directions"
+    },
     {
       "method": "POST",
       "path": "/predictive/returns/lunar"
@@ -496,8 +512,8 @@
       "path": "/visualization/chart-wheel"
     }
   ],
-  "last_generated_at": "2026-08-31T23:51:24.873Z",
-  "openapi_sha256": "4347724c414ef94075a3db63016a4935ca7b533ecf18f37fac1ca16c22ca0195",
+  "last_generated_at": "2026-09-24T18:29:22.473Z",
+  "openapi_sha256": "f5927cecddb0f8629f7c94d380ca878e6780bc491f85490bacb2508e1b721b3d",
   "candidates_get": [
     {
       "method": "GET",
@@ -893,22 +909,6 @@
       ],
       "operationId": "declination_lines_acg_declination_lines_post"
     },
-    {
-      "method": "POST",
-      "path": "/acg/features",
-      "tags": [
-        "ACG"
-      ],
-      "operationId": "features_acg_features_post"
-    },
-    {
-      "method": "POST",
-      "path": "/acg/heatmap/composite",
-      "tags": [
-        "Astrocartography"
-      ],
-      "operationId": "AcgHeatmapCompositeAcgHeatmapCompositePost"
-    },
     {
       "method": "POST",
       "path": "/acg/hermetic-lines",
@@ -1341,6 +1341,14 @@
       ],
       "operationId": "human_design_transit_chart_human_design_transit_chart_post"
     },
+    {
+      "method": "POST",
+      "path": "/human-design/transit-timeline",
+      "tags": [
+        "Human Design"
+      ],
+      "operationId": "human_design_transit_timeline_human_design_transit_timeline_post"
+    },
     {
       "method": "POST",
       "path": "/human-design/transit",
@@ -1538,6 +1546,7 @@
       "Non-GET allowlisted: POST /ephemeris/declinations",
       "Non-GET allowlisted: POST /ephemeris/dignities",
       "Non-GET allowlisted: POST /ephemeris/dispositor-tree",
+      "Non-GET allowlisted: POST /ephemeris/draconic",
       "Non-GET allowlisted: POST /ephemeris/fixed-stars",
       "Non-GET allowlisted: POST /ephemeris/harmonics",
       "Non-GET allowlisted: POST /ephemeris/hermetic-lots",
@@ -1547,6 +1556,7 @@
       "Non-GET allowlisted: POST /ephemeris/natal-chart",
       "Non-GET allowlisted: POST /ephemeris/natal/batch",
       "Non-GET allowlisted: POST /ephemeris/planet-position",
+      "Non-GET allowlisted: POST /ephemeris/prenatal-lunation",
       "Non-GET allowlisted: POST /ephemeris/progressed",
       "Non-GET allowlisted: POST /ephemeris/relocation",
       "Non-GET allowlisted: POST /ephemeris/retrograde-status",
@@ -1563,7 +1573,9 @@
       "Non-GET allowlisted: POST /human-design/cycles/solar-return",
       "Non-GET allowlisted: POST /human-design/penta",
       "Non-GET allowlisted: POST /human-design/transit-chart",
+      "Non-GET allowlisted: POST /human-design/transit-timeline",
       "Non-GET allowlisted: POST /human-design/transit",
+      "Non-GET allowlisted: POST /predictive/primary-directions",
       "Non-GET allowlisted: POST /predictive/returns/lunar",
       "Non-GET allowlisted: POST /predictive/returns/solar",
       "Non-GET allowlisted: POST /predictive/returns",

package/dist/backend/client.d.ts

@@ -6,7 +6,29 @@ export interface BackendConfig {
     apiKey?: string;
     /** Back-compat: previous name for JWT token (Bearer). */
     authToken?: string;
+    /**
+     * When false, the client uses ONLY the credentials passed in this config and
+     * never falls back to the process environment (OPENEPHEMERIS_SERVICE_KEY,
+     * OPENEPHEMERIS_API_KEY, OPENEPHEMERIS_JWT and their legacy aliases).
+     *
+     * The hosted HTTP server builds one client per user session and MUST pass
+     * false: the interceptor sends X-Service-Key ahead of the user's own key, so
+     * an env credential inherited by a per-session client would make every
+     * user's calls unmetered (service key) or billed to one account (API key /
+     * JWT). Defaults to true so the stdio/local server keeps reading its config
+     * from the environment exactly as before.
+     */
+    inheritEnvCredentials?: boolean;
 }
+/** Env vars holding a service key — bypasses metering; never valid on the hosted server. */
+export declare const SERVICE_KEY_ENV_VARS: readonly ["OPENEPHEMERIS_SERVICE_KEY", "ASTROMCP_SERVICE_KEY", "MERIDIAN_SERVICE_KEY"];
+/** Env vars holding one user's credential — on the hosted server they would bill every session to one account. */
+export declare const USER_CREDENTIAL_ENV_VARS: readonly ["OPENEPHEMERIS_API_KEY", "ASTROMCP_API_KEY", "MERIDIAN_API_KEY", "OPENEPHEMERIS_JWT", "ASTROMCP_JWT", "MERIDIAN_AUTH_TOKEN"];
+/** Names of the credential env vars that are set (non-empty) in `env`. */
+export declare function presentCredentialEnvVars(env?: NodeJS.ProcessEnv): {
+    serviceKeys: string[];
+    userCredentials: string[];
+};
 export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
 export interface BackendRequestOptions {
     params?: Record<string, unknown>;
@@ -25,8 +47,33 @@ export declare const DASHBOARD_ACCOUNT_URL = "https://openephemeris.com/dashboar
 export declare const LOGIN_SIGNUP_URL = "https://openephemeris.com/login?signup=true&redirect=%2Fdashboard%3Ftab%3Daccount";
 export declare const UPGRADE_URL = "https://openephemeris.com/pricing";
 /** One-tap $5 → 150-credit top-up (signs the user in if needed, then redirects to the prefilled Stripe Payment Link). */
-export declare const TOPUP_URL = "https://openephemeris.com/topup?pack=payg_5";
+export declare const TOPUP_URL = "https://openephemeris.com/topup?pack=payg_5&src=mcp_402";
+/**
+ * The API's 402 carries `upgrade.topup_url`: the same /topup link, signed with
+ * the caller's account so it opens Stripe checkout without a sign-in step
+ * (most people hitting the wall are in ChatGPT/Claude and not signed in on the
+ * site). Use it when present, re-tagged src=mcp_402 so the funnel can tell MCP
+ * clicks from raw API ones; otherwise fall back to the unsigned link.
+ */
+export declare function resolveTopupUrl(apiTopupUrl: unknown): string;
 export declare const WALLET_TOPUP_URL = "https://openephemeris.com/wallet";
+/**
+ * Whether an error body (typically a 422) is really the credit wall: the
+ * detail / type / field codes mention insufficient credits or an exceeded
+ * quota. Checked over the whole serialized body because the signal can sit in
+ * `detail`, `type`, or a nested `errors[].code`.
+ */
+export declare function looksLikeCreditExhaustion(data: unknown, msg?: string): boolean;
+/**
+ * True for errors that mean "this account cannot be charged / is not allowed"
+ * — the credit wall (402), missing auth (401), or a tier gate (403). Tools
+ * that fan out or degrade gracefully must rethrow these instead of swallowing
+ * them: a placeholder result at zero credits hides the paywall (and its
+ * top-up link) from the assistant and reads as real data.
+ */
+export declare function isBillingOrAuthError(err: unknown): err is BackendError;
+/** Rethrows the first billing/auth BackendError among settled results, if any. */
+export declare function rethrowBillingOrAuth(results: PromiseSettledResult<unknown>[]): void;
 export declare class BackendError extends Error {
     readonly status: number;
     readonly code: string;
@@ -59,6 +106,15 @@ export declare class BackendClient {
      * (JWT is the lowest-priority credential in the interceptor).
      */
     setJwt(jwt: string): void;
+    /**
+     * Drop every credential this client holds (service key, API key, JWT). The
+     * hosted HTTP server calls this on the module singleton at startup: the
+     * singleton is what getActiveClient() falls back to outside a session
+     * context, and it was built from the environment at import time.
+     */
+    clearCredentials(): void;
+    /** Which configured credential the interceptor will send (diagnostics/tests). */
+    credentialKind(): "service_key" | "api_key" | "jwt" | null;
     /**
      * Start the device auth flow in the background if not already running.
      * Called automatically when no credentials are found in the interceptor.

package/dist/backend/client.js

@@ -2,6 +2,29 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import axios, { AxiosError } from "axios";
 import { CredentialManager } from "../auth/credentials.js";
 import { DeviceAuthFlow } from "../auth/device-auth.js";
+/** Env vars holding a service key — bypasses metering; never valid on the hosted server. */
+export const SERVICE_KEY_ENV_VARS = [
+    "OPENEPHEMERIS_SERVICE_KEY",
+    "ASTROMCP_SERVICE_KEY",
+    "MERIDIAN_SERVICE_KEY",
+];
+/** Env vars holding one user's credential — on the hosted server they would bill every session to one account. */
+export const USER_CREDENTIAL_ENV_VARS = [
+    "OPENEPHEMERIS_API_KEY",
+    "ASTROMCP_API_KEY",
+    "MERIDIAN_API_KEY",
+    "OPENEPHEMERIS_JWT",
+    "ASTROMCP_JWT",
+    "MERIDIAN_AUTH_TOKEN",
+];
+/** Names of the credential env vars that are set (non-empty) in `env`. */
+export function presentCredentialEnvVars(env = process.env) {
+    const isSet = (name) => typeof env[name] === "string" && env[name].trim() !== "";
+    return {
+        serviceKeys: SERVICE_KEY_ENV_VARS.filter(isSet),
+        userCredentials: USER_CREDENTIAL_ENV_VARS.filter(isSet),
+    };
+}
 const DEFAULT_TIMEOUT_MS = 45_000;
 const RETRY_DELAYS_MS = [1_000, 2_000, 4_000]; // Three retries with backoff
 // NOTE: 429 is intentionally NOT retryable. Every expensive compute endpoint is
@@ -23,8 +46,64 @@ export const DASHBOARD_ACCOUNT_URL = "https://openephemeris.com/dashboard?tab=ac
 export const LOGIN_SIGNUP_URL = "https://openephemeris.com/login?signup=true&redirect=%2Fdashboard%3Ftab%3Daccount";
 export const UPGRADE_URL = "https://openephemeris.com/pricing";
 /** One-tap $5 → 150-credit top-up (signs the user in if needed, then redirects to the prefilled Stripe Payment Link). */
-export const TOPUP_URL = "https://openephemeris.com/topup?pack=payg_5";
+export const TOPUP_URL = "https://openephemeris.com/topup?pack=payg_5&src=mcp_402";
+/**
+ * The API's 402 carries `upgrade.topup_url`: the same /topup link, signed with
+ * the caller's account so it opens Stripe checkout without a sign-in step
+ * (most people hitting the wall are in ChatGPT/Claude and not signed in on the
+ * site). Use it when present, re-tagged src=mcp_402 so the funnel can tell MCP
+ * clicks from raw API ones; otherwise fall back to the unsigned link.
+ */
+export function resolveTopupUrl(apiTopupUrl) {
+    if (typeof apiTopupUrl !== "string")
+        return TOPUP_URL;
+    try {
+        const url = new URL(apiTopupUrl);
+        if (url.protocol !== "https:" || url.hostname !== "openephemeris.com" || url.pathname !== "/topup") {
+            return TOPUP_URL;
+        }
+        url.searchParams.set("src", "mcp_402");
+        return url.toString();
+    }
+    catch {
+        return TOPUP_URL;
+    }
+}
 export const WALLET_TOPUP_URL = "https://openephemeris.com/wallet";
+const CREDIT_EXHAUSTION_RE = /credits?_insufficient|insufficient[ _-]?credits?|not enough credits|out of credits|credits?[ _-]exhausted|quota[ _-]exceeded|usage_quota|requires \d+ credits/i;
+/**
+ * Whether an error body (typically a 422) is really the credit wall: the
+ * detail / type / field codes mention insufficient credits or an exceeded
+ * quota. Checked over the whole serialized body because the signal can sit in
+ * `detail`, `type`, or a nested `errors[].code`.
+ */
+export function looksLikeCreditExhaustion(data, msg) {
+    let text = msg ?? "";
+    try {
+        text += " " + (typeof data === "string" ? data : JSON.stringify(data ?? ""));
+    }
+    catch {
+        // unserializable body — fall back to the message alone
+    }
+    return CREDIT_EXHAUSTION_RE.test(text);
+}
+/**
+ * True for errors that mean "this account cannot be charged / is not allowed"
+ * — the credit wall (402), missing auth (401), or a tier gate (403). Tools
+ * that fan out or degrade gracefully must rethrow these instead of swallowing
+ * them: a placeholder result at zero credits hides the paywall (and its
+ * top-up link) from the assistant and reads as real data.
+ */
+export function isBillingOrAuthError(err) {
+    return err instanceof BackendError && (err.status === 402 || err.status === 401 || err.status === 403);
+}
+/** Rethrows the first billing/auth BackendError among settled results, if any. */
+export function rethrowBillingOrAuth(results) {
+    for (const r of results) {
+        if (r.status === "rejected" && isBillingOrAuthError(r.reason))
+            throw r.reason;
+    }
+}
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -53,22 +132,24 @@ export class BackendClient {
     _authFlowResult = null;
     constructor(config) {
         this.userId = config.userId || "anonymous";
+        // See BackendConfig.inheritEnvCredentials — per-session hosted clients opt out.
+        const env = config.inheritEnvCredentials === false ? {} : process.env;
         this.jwt =
             config.jwt ||
                 config.authToken ||
-                process.env.OPENEPHEMERIS_JWT ||
-                process.env.ASTROMCP_JWT ||
-                process.env.MERIDIAN_AUTH_TOKEN;
+                env.OPENEPHEMERIS_JWT ||
+                env.ASTROMCP_JWT ||
+                env.MERIDIAN_AUTH_TOKEN;
         this.serviceKey =
             config.serviceKey ||
-                process.env.OPENEPHEMERIS_SERVICE_KEY ||
-                process.env.ASTROMCP_SERVICE_KEY ||
-                process.env.MERIDIAN_SERVICE_KEY;
+                env.OPENEPHEMERIS_SERVICE_KEY ||
+                env.ASTROMCP_SERVICE_KEY ||
+                env.MERIDIAN_SERVICE_KEY;
         this.apiKey =
             config.apiKey ||
-                process.env.OPENEPHEMERIS_API_KEY ||
-                process.env.ASTROMCP_API_KEY ||
-                process.env.MERIDIAN_API_KEY;
+                env.OPENEPHEMERIS_API_KEY ||
+                env.ASTROMCP_API_KEY ||
+                env.MERIDIAN_API_KEY;
         this.credentialManager = new CredentialManager();
         this.client = axios.create({
             baseURL: config.baseURL ||
@@ -138,6 +219,27 @@ export class BackendClient {
     setJwt(jwt) {
         this.jwt = jwt;
     }
+    /**
+     * Drop every credential this client holds (service key, API key, JWT). The
+     * hosted HTTP server calls this on the module singleton at startup: the
+     * singleton is what getActiveClient() falls back to outside a session
+     * context, and it was built from the environment at import time.
+     */
+    clearCredentials() {
+        this.serviceKey = undefined;
+        this.apiKey = undefined;
+        this.jwt = undefined;
+    }
+    /** Which configured credential the interceptor will send (diagnostics/tests). */
+    credentialKind() {
+        if (this.serviceKey)
+            return "service_key";
+        if (this.apiKey)
+            return "api_key";
+        if (this.jwt)
+            return "jwt";
+        return null;
+    }
     /**
      * Start the device auth flow in the background if not already running.
      * Called automatically when no credentials are found in the interceptor.
@@ -270,7 +372,12 @@ export class BackendClient {
                     `through Claude's connector settings, your session expired: in Claude's connector ` +
                     `settings, toggle OpenEphemeris off and on to reconnect — this only takes a moment.`, 401, "auth_required", false, LOGIN_SIGNUP_URL);
             }
-            if (status === 402) {
+            // A 422 whose body says the caller ran out of credits is the credit wall
+            // wearing a validation status (the Go visual add-on reservation returned
+            // 422 `credits_insufficient` before it moved to 402). Route it through
+            // the same 402 path so the assistant gets the one credit-wall message
+            // and top-up link, not "Validation error: ...".
+            if (status === 402 || (status === 422 && looksLikeCreditExhaustion(data, msg))) {
                 // PRICING SSOT: apps/web/config/billing-plans.ts — Explorer grant
                 // (EXPLORER.creditsNumeric = 150, one-time), Pro/`developer`
                 // (monthlyPrice = 29, credits = 75,000), and CREDIT_TOPUPS
@@ -289,18 +396,21 @@ export class BackendClient {
                 // One direct link, not a dashboard tab: /topup?pack=payg_5 signs the
                 // user in if needed and redirects straight to the prefilled Stripe
                 // Payment Link for the $5 → 150-credit pack.
+                const topupUrl = resolveTopupUrl(dataObj.upgrade?.topup_url);
                 let upsellMsg = "";
-                let actionUrl = TOPUP_URL;
+                let actionUrl = topupUrl;
                 if (currentTier === 'explorer') {
                     upsellMsg =
-                        `Let the user know warmly: Their 150 free credits are used up. ` +
-                            `$5 gets 150 more — one tap: ${TOPUP_URL}. ` +
+                        `Let the user know warmly: Their 150 free credits are used up (they do not reset). ` +
+                            `$5 gets 150 more — one tap, no sign-in, opens checkout directly: ${topupUrl} ` +
+                            `(show this exact link to the user as a clickable link). ` +
                             `Or Pro ($29/mo, 75,000 credits): ${UPGRADE_URL}?plan=developer`;
                 }
                 else if (currentTier === 'payg') {
                     upsellMsg =
                         `Let the user know warmly: Their wallet balance is empty. ` +
-                            `$5 gets 150 more credits — one tap: ${TOPUP_URL}. ` +
+                            `$5 gets 150 more credits — one tap, no sign-in, opens checkout directly: ${topupUrl} ` +
+                            `(show this exact link to the user as a clickable link). ` +
                             `Or Pro ($29/mo, 75,000 credits): ${UPGRADE_URL}?plan=developer`;
                 }
                 else {

package/dist/prompts.js

@@ -36,8 +36,8 @@ export const PROMPTS = [
             "| `solar_return_year_ahead` | Annual Solar Return chart — themes for the coming birthday year |\n" +
             "| `developer_api_integration` | Help a dev integrate the Open Ephemeris API into their app |\n\n" +
             "## Before Calling Any Tool — Three Rules\n" +
-            "1. **Coordinates first**: Convert city names to decimal lat/lon before calling tools " +
-            "(e.g. Chicago → 41.8781, -87.6298). Positive = North/East; negative = South/West.\n" +
+            "1. **Coordinates first**: Resolve place names with `location_search` — never recall " +
+            "coordinates from memory. Positive = North/East; negative = South/West.\n" +
             "2. **Datetime format**: Pass birth times as local ISO 8601 + separate `timezone` IANA name " +
             "(e.g. `America/Chicago`), OR as a UTC-offset datetime `1990-04-15T14:30:00-05:00`. " +
             "Never append `Z` to a local birth time — `Z` means UTC.\n" +
@@ -870,7 +870,7 @@ export const PROMPTS = [
             "| Feature | MCP Tool | REST Endpoint | Credits |\n" +
             "|---------|----------|---------------|---------|\n" +
             "| Natal chart | `ephemeris_natal_chart` | `POST /ephemeris/natal-chart` | 1 |\n" +
-            "| Natal batch (up to 100) | `ephemeris_natal_batch` | `POST /ephemeris/natal/batch` | 1/subject |\n" +
+            "| Natal batch (up to 100, Startup+) | `ephemeris_natal_batch` | `POST /ephemeris/natal/batch` | 1/subject |\n" +
             "| Vedic / Jyotish chart | `vedic_chart` | `POST /vedic/chart` | 1 |\n" +
             "| Human Design | `human_design_chart` | `POST /human-design/chart` | 2 |\n" +
             "| BaZi Four Pillars | `chinese_bazi` | `POST /chinese/bazi` | 1 |\n" +
@@ -879,38 +879,39 @@ export const PROMPTS = [
             "| Midpoint composite | `ephemeris_composite_midpoint` | `POST /comparative/composite/midpoint` | 3 |\n" +
             "| House overlay | `ephemeris_overlay` | `POST /comparative/overlay` | 3 |\n" +
             "| Natal transits (now) | `ephemeris_natal_transits` | `POST /comparative/natal-transits` | 3 |\n" +
-            "| Transit search (range) | `ephemeris_transits` | `POST /predictive/transits/search` | 6 |\n" +
+            "| Transit search (range) | `ephemeris_transits` | `POST /predictive/transits/search` | 5–70 by span (≤1y 5 … ≤40y 70); tool +1 for the natal chart |\n" +
             "| Relocation chart | `ephemeris_relocation` | `POST /ephemeris/relocation` | 1 |\n" +
             "| Solar return | `ephemeris_solar_return` | `POST /predictive/returns/solar` | 5 |\n" +
             "| Lunar return | `ephemeris_lunar_return` | `POST /predictive/returns/lunar` | 5 |\n" +
             "| Progressions | `ephemeris_progressed_chart` | `POST /ephemeris/progressed` | 1 |\n" +
-            "| ACG power lines | `acg_power_lines` | `POST /acg/power-lines` | 10 |\n" +
-            "| ACG city hits | `acg_hits` | `POST /acg/hits` | 15 |\n" +
+            "| ACG power lines (Pro+) | `acg_power_lines` | `POST /acg/power-lines` | 10 |\n" +
+            "| ACG city hits (Pro+) | `acg_hits` | `POST /acg/hits` | 10 |\n" +
             "| Eclipse finder | `ephemeris_next_eclipse` | `GET /eclipse/next-visible` | 1 |\n" +
-            "| Moon phase (current) | `ephemeris_moon_phase` | `GET /ephemeris/moon/phase` | 1 |\n" +
-            "| Next lunar phase | `ephemeris_next_lunar_phase` | `GET /calendar/astrology/moon-phases` | 1 |\n" +
-            "| Electional windows | `ephemeris_electional` | `GET /electional/find-window` | 5 |\n" +
-            "| Electional score | `electional_moment_analysis` | `GET /electional/moment-analysis` | 1 |\n" +
+            "| Moon phase (current) | `ephemeris_moon_phase` | `GET /ephemeris/moon/phase` + `/void-of-course` | 2 |\n" +
+            "| Next lunar phase | `ephemeris_next_lunar_phase` | `GET /calendar/astrology/moon-phases` | 2 per occurrence |\n" +
+            "| Electional windows (Pro+) | `ephemeris_electional` | `GET /electional/find-window` | 5 / 8 / 12 for ≤30 / 60 / 120 days |\n" +
+            "| Electional score | `electional_moment_analysis` | `GET /electional/moment-analysis` | 5 |\n" +
             "| Dignities | `ephemeris_dignities` | `POST /ephemeris/dignities` | 1 |\n" +
             "| Hermetic lots | `ephemeris_hermetic_lots` | `POST /ephemeris/hermetic-lots` | 1 |\n" +
             "| Midpoints | `ephemeris_midpoints` | `POST /ephemeris/midpoints` | 1 |\n\n" +
             "## Step 3 — Critical Implementation Patterns\n\n" +
             "### ⚠️ Datetime Handling — Most Common Source of Bugs\n" +
             "```\n" +
-            "# CORRECT — Local birth time + IANA timezone (Western astrology)\n" +
+            "# CORRECT — local wall-clock time + IANA zone (server applies historical DST)\n" +
             "POST /ephemeris/natal-chart\n" +
-            "{ \"datetime\": \"1990-04-15T14:30:00\", \"timezone\": \"America/Chicago\" }\n\n" +
-            "# ALSO CORRECT — Local time with UTC offset embedded\n" +
-            "{ \"datetime\": \"1990-04-15T14:30:00-05:00\" }\n\n" +
-            "# CORRECT — UTC required for HD and Vedic\n" +
+            "{ \"subject\": { \"name\": \"A\", \"birth_datetime\": { \"iso\": \"1990-04-15T14:30:00\" },\n" +
+            "  \"birth_location\": { \"latitude\": { \"decimal\": 41.88 }, \"longitude\": { \"decimal\": -87.63 },\n" +
+            "    \"timezone\": { \"iana_name\": \"America/Chicago\" } } } }\n\n" +
             "POST /human-design/chart\n" +
-            "{ \"datetime\": \"1990-04-15T19:30:00Z\" }  // Z = UTC\n\n" +
-            "# WRONG — Never append Z to a local time\n" +
-            "{ \"datetime\": \"1990-04-15T14:30:00Z\" }  // ❌ reads as UTC 2:30pm, not Central 2:30pm\n" +
+            "{ \"birth_datetime_local\": \"1990-04-15T14:30:00\", \"timezone\": { \"iana_name\": \"America/Chicago\" },\n" +
+            "  \"latitude\": 41.88, \"longitude\": -87.63 }\n\n" +
+            "# ALSO CORRECT — an explicit instant (offset or Z): trusted as-is\n" +
+            "\"1990-04-15T14:30:00-05:00\"   or   \"1990-04-15T19:30:00Z\"\n\n" +
+            "# WRONG — Z on a local time reads as UTC 2:30pm, not Central 2:30pm (no error raised)\n" +
+            "\"1990-04-15T14:30:00Z\"\n" +
             "```\n\n" +
-            "**Rule of thumb**:\n" +
-            "- Natal charts (Western, BaZi, electional): local time + `timezone` IANA name\n" +
-            "- Human Design, Vedic: always UTC with Z\n\n" +
+            "**Rule of thumb**: on every endpoint, prefer local time + IANA zone. A zone-less clock time " +
+            "with no zone is a hard 400; a bare date resolves to 12:00 UTC.\n\n" +
             "### Coordinates\n" +
             "- Decimal degrees, at least 4 decimal places\n" +
             "- Positive = North/East; Negative = South/West\n" +
@@ -938,9 +939,10 @@ export const PROMPTS = [
             "### Credit Optimization\n" +
             "- **Batch natal charts**: use `POST /ephemeris/natal/batch` for multi-user onboarding (1 credit/subject vs N calls)\n" +
             "- **Current transits**: prefer `ephemeris_natal_transits` (3 credits) over " +
-            "`ephemeris_transits` (6 credits) when you only need right-now, not a date range\n" +
-            "- **ACG**: call `acg_hits` (city-level, 15 credits) only for specific targets; " +
-            "use `acg_power_lines` (10 credits) for global maps\n" +
+            "`ephemeris_transits` (6+ credits, priced by span) when you only need right-now, not a date range\n" +
+            "- **Range searches**: priced by the span you ask for, before compute; a span over the plan cap " +
+            "(transit search: Explorer/PAYG 1y, Pro 5y, Startup 10y, Scale 40y) is a 400 `search_span_limit` — split it\n" +
+            "- **Failed calls are free**: every 4xx/5xx response is refunded\n" +
             "- **Format matters**: `format: 'llm'` reduces token usage in your LLM calls significantly\n\n" +
             "## Step 4 — Generate a Code Scaffold\n" +
             "Ask: 'What language would you like the scaffold in? And what is the first feature you want to implement?'\n\n" +