@openephemeris/mcp-server 4.15.1 → 4.17.0

package/CHANGELOG.md

@@ -7,6 +7,39 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [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
+- **Synastry, composite, bi-wheel, returns, progressions, relocation, HD transit/connection overlays
+  and advanced BaZi are now available on the free tier (credits only).** Tool descriptions no longer
+  say "Pro tier" for any of them; astrocartography and electional window search stay Pro.
+- **Credit-exhausted responses now link directly to a one-tap $5 top-up.** A `402` from the API hands
+  the model a single link (`https://openephemeris.com/topup?pack=payg_5`) that signs the user in if
+  needed and goes straight to checkout, instead of a dashboard wallet tab.
+
+### Added
+- **Listed in the ChatGPT app directory** (approved 2026-09-14). ChatGPT users install Open Ephemeris
+  in one click from [the listing](https://chatgpt.com/plugins/plugin_asdk_app_6a9c2787bc48819197698e71b29ef7c2)
+  — no Developer Mode, no URL to paste. Same server, same interactive charts as Claude.
+
 ## [4.15.1] — 2026-09-10
 
 ### Fixed

package/README.md

@@ -177,7 +177,8 @@ Cursor deeplink payload:
 | Claude Desktop (macOS) | Manual | `~/Library/Application Support/Claude/claude_desktop_config.json` |
 | Claude Desktop (Windows) | Manual | `%APPDATA%\Claude\claude_desktop_config.json` |
 | Windsurf | Manual | `~/.codeium/windsurf/mcp_config.json` (or legacy `~/.codeium/mcp_config.json`) |
-| Claude Web / ChatGPT / remote clients | Hosted URL | `https://mcp.openephemeris.com/mcp` |
+| ChatGPT | One-click | [Open Ephemeris in the ChatGPT app directory](https://chatgpt.com/plugins/plugin_asdk_app_6a9c2787bc48819197698e71b29ef7c2) |
+| Claude Web / remote clients | Hosted URL | `https://mcp.openephemeris.com/mcp` |
 
 ### Client install walkthroughs
 
@@ -198,14 +199,12 @@ Cursor deeplink payload:
 The server is hosted at `https://mcp.openephemeris.com/mcp` with full Streamable HTTP support (MCP 2025-11-25 spec). Remote-only clients can connect directly — no bridge/proxy required:
 
 - **Claude Web**: Add `https://mcp.openephemeris.com/mcp` as a custom connector URL — leave OAuth Client ID and Secret **blank**. The server uses OAuth 2.1 + PKCE (Dynamic Client Registration), so Claude handles authentication via a browser popup automatically.
-- **ChatGPT**: OpenEphemeris is not in the ChatGPT app directory — you add it yourself.
-  Turn on **Settings → Plugins → Advanced → Developer mode**, then use the **+ (Create app)**
-  button on [chatgpt.com/plugins](https://chatgpt.com/plugins). Server URL:
-  `https://mcp.openephemeris.com/mcp` (append `?profile=core` for the curated 39-tool
-  surface, which still includes every interactive chart). Leave Authentication on **OAuth**;
-  the same PKCE + Dynamic Client Registration flow applies, so there is no client ID or
-  secret to enter. Charts render inline, exactly as they do in Claude. *Developer mode was
-  available on a Free plan when this was last checked (2026-09-04); availability may vary.*
+- **ChatGPT**: Open Ephemeris is an approved app in the ChatGPT app directory. Open
+  [the listing](https://chatgpt.com/plugins/plugin_asdk_app_6a9c2787bc48819197698e71b29ef7c2), click **Install plugin**, approve the sign-in (that also creates your
+  free OpenEphemeris account), then type `@Open Ephemeris` in any chat. Charts render inline,
+  exactly as they do in Claude. Prefer to wire it yourself? **Settings → Plugins → Advanced →
+  Developer mode → + Create app** accepts `https://mcp.openephemeris.com/mcp` with
+  Authentication on **OAuth** — no client ID or secret to enter.
 - **Via Smithery**: Use the [Smithery listing](https://smithery.ai/servers/open-ephemeris/openephemeris) for managed connections with any client
 - **Legacy SSE**: retired in 3.20.0 — use Streamable HTTP at `/mcp`
 
@@ -246,8 +245,8 @@ This matters more than it sounds. A natal chart returned as JSON is a list of nu
 These need a host that supports MCP Apps. **Claude and ChatGPT both do**, and they render
 the same widget — there is no separate ChatGPT build. MCP Apps ([SEP-1865][sep1865]) was
 co-authored by Anthropic and OpenAI and became the first official MCP extension in January
-2026, so one `ui://` resource serves both. In ChatGPT you add the server yourself as a
-custom app (see [Setup](#setup)); OpenEphemeris is not in the ChatGPT app directory.
+2026, so one `ui://` resource serves both. In ChatGPT, install it from
+[the app directory](https://chatgpt.com/plugins/plugin_asdk_app_6a9c2787bc48819197698e71b29ef7c2); in Claude, add the connector (see [Setup](#setup)).
 
 In a client without app support the same tools still work; you get the underlying data
 instead of the picture, so nothing breaks, you just don't get the wheel.
@@ -282,24 +281,24 @@ Screenshots of each are on the way.
 | Moon phase / VOC | `ephemeris_moon_phase` | Explorer |
 | Eclipse next visible | `ephemeris_next_eclipse` | Explorer |
 | Electional window | `ephemeris_electional` | Developer |
-| Moment analysis | `electional_moment_analysis` | Developer |
-| Station tracker | `electional_station_tracker` | Developer |
+| Moment analysis | `electional_moment_analysis` | Explorer |
+| Station tracker | `electional_station_tracker` | Explorer |
 | Aspect search | `electional_aspect_search` | Developer |
 | Human Design chart | `human_design_chart` | Explorer |
-| HD composite | `human_design_composite` | Developer |
-| HD transit overlay | `explore_human_design_transit` | Developer |
-| HD connection (synastry) | `explore_human_design_connection` | Developer |
+| HD composite | `human_design_composite` | Explorer |
+| HD transit overlay | `explore_human_design_transit` | Explorer |
+| HD connection (synastry) | `explore_human_design_connection` | Explorer |
 | HD penta | `human_design_penta` | Explorer |
 | HD return / opposition | `hd_planetary_return`, `hd_opposition` | Explorer |
 | Vedic chart | `vedic_chart` | Explorer |
 | BaZi (Chinese) | `chinese_bazi` | Explorer |
-| Synastry | `ephemeris_synastry` | Developer |
-| Composite chart | `ephemeris_composite` | Developer |
-| Relocation chart | `ephemeris_relocation` | Developer |
+| Synastry | `ephemeris_synastry` | Explorer |
+| Composite chart | `ephemeris_composite` | Explorer |
+| Relocation chart | `ephemeris_relocation` | Explorer |
 | Progressed chart | `ephemeris_progressed_chart` | Explorer |
-| Solar return | `ephemeris_solar_return` | Developer |
-| Lunar return | `ephemeris_lunar_return` | Developer |
-| Planetary return | `ephemeris_planetary_return` | Developer |
+| Solar return | `ephemeris_solar_return` | Explorer |
+| 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 |
 | Venus Star Points | `venus_star_points` + 4 more | Explorer |
@@ -491,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`
@@ -508,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

@@ -24,6 +24,8 @@ export interface BinaryBackendResponse {
 export declare const DASHBOARD_ACCOUNT_URL = "https://openephemeris.com/dashboard?tab=account";
 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 WALLET_TOPUP_URL = "https://openephemeris.com/wallet";
 export declare class BackendError extends Error {
     readonly status: number;

package/dist/backend/client.js

@@ -22,6 +22,8 @@ const BINARY_ENDPOINT_PREFIXES = [
 export const DASHBOARD_ACCOUNT_URL = "https://openephemeris.com/dashboard?tab=account";
 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 WALLET_TOPUP_URL = "https://openephemeris.com/wallet";
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
@@ -277,7 +279,6 @@ export class BackendClient {
                 // suggest enabling overages; suggest the next tier instead. Keep every
                 // number below in sync with that file; do NOT hand-edit independently.
                 const dataObj = data && typeof data === "object" ? data : {};
-                const walletUrl = dataObj.upgrade?.wallets_url || "https://openephemeris.com/dashboard?tab=wallet";
                 const currentTier = dataObj.upgrade?.current_tier || dataObj.tier || "explorer";
                 // Next-tier upgrade path (SSOT: BILLING_PLANS order in billing-plans.ts).
                 const NEXT_TIER = {
@@ -285,25 +286,29 @@ export class BackendClient {
                     startup: { plan: "scale", label: "Scale ($199/mo, 2,000,000 credits)" },
                     scale: { plan: "enterprise", label: "Enterprise (custom volume)" },
                 };
+                // 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.
                 let upsellMsg = "";
+                let actionUrl = TOPUP_URL;
                 if (currentTier === 'explorer') {
                     upsellMsg =
-                        `Let the user know warmly: Their 150 free credits (one-time grant) are used up. ` +
-                            `They can top up their wallet starting at $5 for 150 credits at ` +
-                            `${walletUrl} — or upgrade to Pro ($29/mo) ` +
-                            `for 75,000 credits/month at ${UPGRADE_URL}?plan=developer`;
+                        `Let the user know warmly: Their 150 free credits are used up. ` +
+                            `$5 gets 150 more — one tap: ${TOPUP_URL}. ` +
+                            `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. They can top up at ` +
-                            `${walletUrl} — $5 for 150 credits, ` +
-                            `$10 for 350, or $20 for 900.`;
+                        `Let the user know warmly: Their wallet balance is empty. ` +
+                            `$5 gets 150 more credits — one tap: ${TOPUP_URL}. ` +
+                            `Or Pro ($29/mo, 75,000 credits): ${UPGRADE_URL}?plan=developer`;
                 }
                 else {
                     const next = NEXT_TIER[currentTier] || NEXT_TIER.developer;
+                    actionUrl = `${UPGRADE_URL}?plan=${next.plan}`;
                     upsellMsg =
                         `Let the user know warmly: Their monthly credits are exhausted. They can upgrade to ` +
-                            `${next.label} at ${UPGRADE_URL}?plan=${next.plan}`;
+                            `${next.label} at ${actionUrl}`;
                 }
                 return new BackendError(`⚠️ CREDIT LIMIT REACHED — DO NOT FABRICATE DATA.\n\n` +
                     `${msg}\n\n` +
@@ -311,7 +316,7 @@ export class BackendClient {
                     `They can also review their current usage at ${DASHBOARD_ACCOUNT_URL}.\n\n` +
                     `Frame this warmly, as unlocking more of what they're already enjoying, not as a gate. ` +
                     `DO NOT attempt to generate astrological data from your own knowledge. ` +
-                    `All chart positions, aspects, and timing data MUST come from the API.`, 402, "quota_exceeded", false, walletUrl);
+                    `All chart positions, aspects, and timing data MUST come from the API.`, 402, "quota_exceeded", false, actionUrl);
             }
             if (status === 403) {
                 return new BackendError(`This feature is part of a higher-tier plan.\n\n` +

package/dist/instructions.d.ts

@@ -12,5 +12,5 @@
  * Order is deliberate: the visual one leads, because a rendered dial is a
  * better first impression than a score.
  */
-export declare const ZERO_ARG_ENTRY_TOOLS: readonly ["explore_moon_phase", "electional_moment_analysis"];
+export declare const ZERO_ARG_ENTRY_TOOLS: readonly ["explore_moon_phase"];
 export declare const SERVER_INSTRUCTIONS: string;

package/dist/instructions.js

@@ -37,7 +37,9 @@ import { DATETIME_CONTRACT_INSTRUCTIONS } from "./tools/datetime.js";
  */
 export const ZERO_ARG_ENTRY_TOOLS = [
     "explore_moon_phase",
-    "electional_moment_analysis",
+    // electional_moment_analysis also takes no arguments and is free-with-credits
+    // since the consumer-tools ungate, but it costs 5 credits against a 150-credit
+    // Explorer grant; the visual, 0-argument dial stays the sole cold-open.
 ];
 export const SERVER_INSTRUCTIONS = "Open Ephemeris computes real astronomy (JPL DE440, sub-arcsecond) — never guess " +
     "or approximate positions yourself; always call a tool. " +
@@ -45,7 +47,7 @@ export const SERVER_INSTRUCTIONS = "Open Ephemeris computes real astronomy (JPL
     "prefer the explore_* tools — they render interactive visuals inline. " +
     "ephemeris_* tools return data; use format='llm' on them for compact output. " +
     "If the user has no birth data handy, open with the sky right now: " +
-    `${ZERO_ARG_ENTRY_TOOLS.join(" and ")} take no arguments at all — ` +
-    "call one rather than asking for a birth date first. " +
+    `${ZERO_ARG_ENTRY_TOOLS.join(" and ")} ${ZERO_ARG_ENTRY_TOOLS.length === 1 ? "takes" : "take"} no arguments at all — ` +
+    `call ${ZERO_ARG_ENTRY_TOOLS.length === 1 ? "it" : "one"} rather than asking for a birth date first. ` +
     "See the 'welcome_to_open_ephemeris' prompt for orientation.\n\n" +
     DATETIME_CONTRACT_INSTRUCTIONS;

package/dist/prompts.js

@@ -888,9 +888,9 @@ export const PROMPTS = [
             "| ACG city hits | `acg_hits` | `POST /acg/hits` | 15 |\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 /ephemeris/moon/next-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` | 1 |\n" +
+            "| Electional score | `electional_moment_analysis` | `GET /electional/moment-analysis` | 1 |\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" +

package/dist/tools/apps/bazi-app.js

@@ -111,17 +111,17 @@ function buildSummary(payload) {
 // ── Tool: explore_bazi_chart ─────────────────────────────────────────────────
 registerTool({
     name: "explore_bazi_chart",
-    description: "Generate an interactive BaZi (四柱命盘 Four Pillars of Destiny) chart with clickable pillars.\n\n" +
-        "Returns an embedded visual Four Pillars explorer showing the Year, Month, Day, and Hour " +
-        "pillars — each with its Heavenly Stem (天干) and Earthly Branch (地支), Ten God label, and " +
-        "element color — plus the Day Master identity and a Wu Xing (五行) element balance bar. " +
-        "Click any pillar for an instant interpretation of what it reveals about that life domain " +
-        "(Year = ancestry/early life, Month = parents/career, Day = self/spouse, Hour = children/later life).\n\n" +
+    description: "Use this when the user asks 'what's my BaZi', 'my Four Pillars', 'what's my Day Master', 'my " +
+        "Chinese astrology chart', 'what's my Chinese element' or 'my Chinese birth chart' — the PRIMARY " +
+        "tool for BaZi, with or without a renderer. Returns an interactive Four Pillars (四柱命盘) explorer " +
+        "(inline in Claude and ChatGPT; text summary elsewhere): the Year, Month, Day and Hour pillars — " +
+        "each with Heavenly Stem (天干), Earthly Branch (地支), Ten God label and element color — plus the " +
+        "Day Master identity and a Wu Xing (五行) element balance bar; click any pillar for what it reveals " +
+        "about that life domain.\n\n" +
         "CREDIT COST: 3 credits per call (1 base + 2 visual render).\n\n" +
-        "Use this for a rich, interactive BaZi experience in MCP Apps-capable hosts (Claude and ChatGPT). " +
-        "Falls back to a text summary in other hosts, so it is also the right call without a " +
-        "renderer. Deeper derivations (Ten Gods, element balance, luck pillars) and a plain " +
-        "non-visual pillars lookup have dedicated tools on the full surface (`?profile=full`).",
+        "Do not use for a single year's zodiac animal or pillar — use bazi_annual_pillar. Deeper " +
+        "derivations (Ten Gods, element balance, luck pillars) and a plain non-visual pillars lookup have " +
+        "dedicated tools on the full surface (`?profile=full`).",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/apps/bi-wheel-app.js

@@ -417,20 +417,20 @@ function buildBiWheelSummary(innerPlanets, outerPlanets, crossAspects, mode, loc
 // ── Tool: explore_bi_wheel ─────────────────────────────────────────────────────
 registerTool({
     name: "explore_bi_wheel",
-    description: "Generate an interactive bi-wheel chart comparing two astrological chart positions.\n\n" +
-        "CREDIT COST: 2 credits per call for most modes (1 per wheel computed); " +
-        "solar_return/lunar_return modes cost 6 (5 for the return + 1 for the natal wheel).\n\n" +
-        "The inner wheel is always Person 1's natal chart. The outer ring depends on mode:\n" +
-        "• synastry     — Person 2's natal chart (needs Person 2's own birthplace).\n" +
-        "• transit      — Transiting planets for a given date.\n" +
-        "• progressed   — Secondary progressed positions (person2_datetime = target date).\n" +
-        "• solar_return — Nearest solar return chart (person2_datetime = year to return for).\n" +
-        "• lunar_return — Nearest lunar return chart (person2_datetime = target month).\n" +
-        "• solar_arc    — Solar arc directed positions (person2_datetime = target date).\n" +
-        "Cross-aspects are drawn as coloured dashed lines; click any planet, aspect line, or " +
-        "house cusp for interpretation. Prefer this whenever the user should SEE the comparison " +
-        "— it renders interactively in MCP Apps hosts and falls back to static SVG elsewhere. " +
-        "For raw synastry data without a visual, use ephemeris_synastry.",
+    description: "Use this when the user asks 'are we compatible', 'compare my chart with my partner's', 'what's " +
+        "my horoscope for today', 'what's hitting my chart right now', 'what's my solar return chart this " +
+        "year' or 'my progressed chart on my birth chart' — any two-ring comparison they should SEE. " +
+        "Returns an interactive bi-wheel (inline in Claude and ChatGPT; text summary elsewhere): inner " +
+        "wheel Person 1's natal chart, outer ring by mode — synastry (Person 2's natal; needs their " +
+        "birthplace), transit (a date; today for a daily horoscope), progressed, solar_arc (target date), " +
+        "solar_return (target year), lunar_return (target month) — with cross-aspects drawn and every " +
+        "planet, aspect line and cusp clickable. Birthplaces may be place names (`location`, " +
+        "`person2_location`).\n\n" +
+        "CREDIT COST: 2 credits per call for most modes (1 per wheel; +1 to resolve a place name); " +
+        "solar_return/lunar_return modes cost 6.\n\n" +
+        "Do not use for synastry numbers without a visual — use ephemeris_synastry; for a dated list of " +
+        "upcoming transit hits use explore_transit_timeline; for a single chart use explore_natal_chart; " +
+        "with no birth data use explore_moon_phase.",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/apps/bodygraph-app.js

@@ -227,8 +227,10 @@ function buildHdModelPayload(data, birthParams) {
     const personality_gates = [...new Set(extractGateNums(pGateList))].sort((a, b) => a - b);
     const design_gates = [...new Set(extractGateNums(dGateList))].sort((a, b) => a - b);
     // Convert activation arrays or maps → planet-keyed Record<string, ActivationSummary>
-    // The Go API returns arrays like [{ planet: "Sun", gate: 62, line: 1, color: 3, tone: 4 }].
-    // The renderer needs a map keyed by planet name: { "Sun": { gate, line, color, tone } }.
+    // The Go API returns arrays like
+    // [{ planet: "Sun", gate: 62, line: 1, color: 3, tone: 4, base: 5 }]. The renderer needs a
+    // map keyed by planet name: { "Sun": { gate, line, color, tone, base } }. All five are kept
+    // so a gate click can quote the full gate.line.color.tone.base address.
     function toActivationMap(raw) {
         if (!raw || (typeof raw !== 'object'))
             return undefined;
@@ -258,6 +260,7 @@ function buildHdModelPayload(data, birthParams) {
                 line: Number(item.line ?? 0),
                 color: Number(item.color ?? 0),
                 tone: Number(item.tone ?? 0),
+                base: Number(item.base ?? 0),
             };
         }
         return Object.keys(map).length > 0 ? map : undefined;
@@ -305,19 +308,17 @@ function buildHdSummary(payload, location) {
 // ── Tool: explore_human_design ────────────────────────────────────────────
 registerTool({
     name: "explore_human_design",
-    description: "Generate an interactive Human Design Bodygraph with clickable centers, gates, and channels.\n\n" +
-        "CREDIT COST: 4 credits where the bodygraph renders (2 for the chart + 2 for the " +
-        "visual), 2 in text-only hosts that skip the render. For chart data alone at 2 " +
-        "credits — including the activations, design, personality, strategy and variables " +
-        "this tool does not return — use human_design_chart.\n\n" +
-        "Returns an embedded visual bodygraph explorer that lets you click any center or gate " +
-        "for instant Human Design interpretation. " +
-        "Shows defined/undefined centers, active gates, channels, Type, Profile, Authority, " +
-        "and Incarnation Cross. " +
-        "The chart is calculated using NASA JPL DE440 ephemerides for both Personality and Design positions. " +
-        "Use this instead of human_design_chart for a richer, interactive HD " +
-        "experience in MCP Apps-capable hosts (Claude and ChatGPT). " +
-        "Falls back to a text summary in other hosts." +
+    description: "Use this when the user asks 'what's my Human Design', 'am I a Generator / Projector / Manifestor " +
+        "/ Reflector', 'show my bodygraph', 'what's my HD type and profile', 'what's my strategy and " +
+        "authority' or 'what's my incarnation cross' — the PRIMARY tool for a Human Design chart. Returns " +
+        "an interactive bodygraph (inline in Claude and ChatGPT; text summary elsewhere) showing " +
+        "defined/undefined centers, active gates, channels, Type, Profile, Authority and Incarnation " +
+        "Cross, with any center or gate clickable for interpretation. Birthplace may be a place name " +
+        "(`location`).\n\n" +
+        "CREDIT COST: 4 credits per call (2 chart + 2 render; +1 to resolve a place name).\n\n" +
+        "Do not use when the user needs the activations, design/personality positions, strategy and " +
+        "variables this view omits — use human_design_chart (2 credits); for today's transits on their " +
+        "chart use explore_human_design_transit; for two people use explore_human_design_connection." +
         HD_DISCLAIMER,
     inputSchema: {
         type: "object",
@@ -1305,15 +1306,18 @@ registerTool({
 });
 // ── Tool: explore_human_design_transit ───────────────────────────────────────
 // Personalized Human Design transit overlay (natal chart + a transiting moment).
-// Premium (Pro tier). Calls POST /human-design/transit-chart.
+// Calls POST /human-design/transit-chart.
 registerTool({
     name: "explore_human_design_transit",
-    description: "Overlay the current (or a chosen) planetary transit on a person's natal Human Design bodygraph.\n\n" +
-        "CREDIT COST: 3 credits per call.\n\n" +
-        "Highlights the channels a transit temporarily COMPLETES with the natal chart and any centers it " +
-        "newly defines — the core of a Human Design transit reading. " +
-        "Returns an interactive overlay bodygraph in MCP Apps-capable hosts (Claude and ChatGPT), with a text " +
-        "summary fallback elsewhere. Premium (Pro tier). Calculated with NASA JPL DE440 ephemerides." +
+    description: "Use this when the user asks 'what are today's Human Design transits for me', 'what gates are " +
+        "being activated for me right now', 'which channels does this transit complete in my chart' or " +
+        "'how is the current sky affecting my bodygraph'. Returns an interactive overlay bodygraph " +
+        "(inline in Claude and ChatGPT; text summary elsewhere) highlighting the channels the transit " +
+        "temporarily COMPLETES with the natal chart and any centers it newly defines, for now or a chosen " +
+        "datetime. Birthplace may be a place name (`location`).\n\n" +
+        "CREDIT COST: 3 credits per call (+1 to resolve a place name).\n\n" +
+        "Do not use for the person's own natal bodygraph — use explore_human_design; for another person's " +
+        "chart overlaid on theirs use explore_human_design_connection." +
         HD_DISCLAIMER,
     inputSchema: {
         type: "object",
@@ -1439,17 +1443,19 @@ registerTool({
     },
 });
 // ── Tool: explore_human_design_connection ────────────────────────────────────
-// Two-person Human Design connection (synastry) overlay. Premium (Pro tier).
+// Two-person Human Design connection (synastry) overlay.
 // Calls POST /human-design/composite.
 registerTool({
     name: "explore_human_design_connection",
-    description: "Compare two people's Human Design charts and classify every connected channel by HD connection " +
-        "theory.\n\n" +
+    description: "Use this when the user asks 'are we compatible in Human Design', 'what's our connection chart', " +
+        "'what channels do we make together' or 'show our composite bodygraph' — two people's HD charts " +
+        "overlaid. Returns an interactive two-person overlay bodygraph (inline in Claude and ChatGPT; " +
+        "text summary elsewhere) with every connected channel classified by HD connection theory: " +
+        "electromagnetic (attraction), companionship (sameness), dominance (one defines), compromise " +
+        "(friction).\n\n" +
         "CREDIT COST: 3 credits per call.\n\n" +
-        "Classifications: " +
-        "electromagnetic (attraction), companionship (sameness), dominance (one defines), and " +
-        "compromise (friction). Returns an interactive two-person overlay bodygraph in MCP Apps-capable " +
-        "hosts, with a text summary fallback elsewhere. Premium (Pro tier). NASA JPL DE440 ephemerides." +
+        "Do not use for one person's chart — use explore_human_design; for the sky's transit on one chart " +
+        "use explore_human_design_transit; for Western compatibility use explore_bi_wheel." +
         HD_DISCLAIMER,
     inputSchema: {
         type: "object",