@openephemeris/mcp-server 4.16.0 → 4.18.0

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

@@ -21,7 +21,7 @@ import { fileURLToPath } from "node:url";
 import { registerTool, SERVER_VERSION } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
-import { DATETIME_DESC, TIMEZONE_PROPERTY } from "../datetime.js";
+import { DATETIME_DESC, TIMEZONE_PROPERTY, toDateTimeInputBody } from "../datetime.js";
 import { coordsFromArgsOrLocation } from "./_location-resolver.js";
 // ── Constants ─────────────────────────────────────────────────────────────
 export const CHART_WHEEL_RESOURCE_URI = "ui://openephemeris/chart-wheel";
@@ -159,9 +159,10 @@ registerTool({
                 items: { type: "string" },
                 description: "Optional list of body names to include. " +
                     "Defaults to 13 classical bodies (Sun through Pluto + Chiron + Nodes). " +
-                    "Use 'all' as a single item to include every available body (Lilith, Ceres, Juno, Vesta, Pallas, Vertex, " +
+                    "Use 'all' as a single item to include every available body (the three Liliths — mean, true and interpolated — Ceres, Juno, Vesta, Pallas, Pholus, " +
                     "the 8 trans-Neptunian objects — eris, sedna, makemake, haumea, quaoar, orcus, ixion, varuna — and the " +
                     "8 Uranian/Hamburg-School points — cupido, hades, zeus, kronos, apollon, admetos, vulkanus, poseidon). " +
+                    "Lilith slugs: 'lilith' (mean), 'lilith_true', 'lilith_interpolated'. " +
                     "Example: ['sun','moon','lilith','sedna'].",
             },
         },
@@ -410,19 +411,40 @@ registerTool({
         const baseBody = buildNatalBody(datetime, lat, lon, houseSystem, args.timezone);
         let endpoint = "/ephemeris/natal-chart";
         let requestBody = baseBody;
+        // Where the chart sits in the reply: natal-chart returns it top-level,
+        // /ephemeris/progressed under `data`, the return endpoints under `chart`.
+        let chartKey = null;
+        const target = toDateTimeInputBody("target_datetime", String(args.target_datetime ?? datetime), args.timezone);
         if (chartType === "solar_return") {
+            // SolarReturnRequest is flat — birth_datetime at the top level, no `subject`.
             endpoint = "/predictive/returns/solar";
-            requestBody.configuration.target_datetime = { iso: args.target_datetime ?? datetime };
+            const subject = baseBody.subject;
+            requestBody = {
+                birth_datetime: toDateTimeInputBody("datetime", datetime, args.timezone),
+                birth_location: subject.birth_location,
+                target_datetime: target,
+                house_system: baseBody.configuration.house_system,
+            };
+            chartKey = "chart";
         }
         else if (chartType === "progressed") {
             // openapi.json exposes /ephemeris/progressed — /predictive/progressed
             // does not exist and 404'd every progressed recalculate in the iframe.
             endpoint = "/ephemeris/progressed";
-            requestBody.configuration.target_datetime = { iso: args.target_datetime ?? datetime };
-            requestBody.configuration.method = "secondary";
+            requestBody = {
+                subject: baseBody.subject,
+                configuration: { house_system: baseBody.configuration.house_system },
+                target_datetime: target,
+                progression_options: { method: "secondary" },
+            };
+            chartKey = "data";
         }
         // Fetch updated chart JSON only — chart renders client-side in the iframe
-        const chartData = await client.post(endpoint, requestBody);
+        const reply = await client.post(endpoint, requestBody);
+        const chartData = chartKey ? reply[chartKey] : reply;
+        if (!chartData || typeof chartData !== "object") {
+            throw new Error(`Unexpected ${chartType} response: no \`${chartKey}\` chart in the API reply.`);
+        }
         // Normalise through buildModelPayload so house-switch results use the same
         // format as the initial response.
         const payload = buildModelPayload(chartData, {
@@ -457,7 +479,10 @@ const CLASSICAL_PLANETS = new Set([
     "sun", "moon", "mercury", "venus", "mars",
     "jupiter", "saturn", "uranus", "neptune", "pluto",
     // Nodes use space form to match the renderer's glyph table (chart-renderer.ts).
-    "chiron", "north node", "south node", "true node", "asc", "mc",
+    "chiron", "asc", "mc",
+    // The four lunar nodes keep the API's own names (lowercased): Mean and True
+    // are different points and never share a name.
+    "north node (mean)", "north node (true)", "south node (mean)", "south node (true)",
 ]);
 /**
  * Canonicalise the Go backend's verbose node keys ("North Node (Mean)" /
@@ -469,25 +494,40 @@ const CLASSICAL_PLANETS = new Set([
 function canonicalizeBodyName(raw) {
     const lower = raw.toLowerCase().trim();
     if (lower === "north node (true)" || lower === "true node")
-        return "true node";
+        return "north node (true)";
     if (lower === "north node (mean)" || lower === "mean node" || lower === "north node")
-        return "north node";
-    if (lower === "south node (mean)" || lower === "south node (true)" || lower === "south node")
-        return "south node";
+        return "north node (mean)";
+    if (lower === "south node (true)" || lower === "true south node")
+        return "south node (true)";
+    if (lower === "south node (mean)" || lower === "south node")
+        return "south node (mean)";
+    // Lilith: three different points (mean apogee 12, osculating 13, interpolated
+    // 40), each kept under the API's own name — never merged into one "lilith".
+    if (lower === "lilith (true)" || lower === "lilith_true" || lower === "true_lilith" || lower === "osculating apogee")
+        return "lilith (true)";
+    if (lower === "lilith (interpolated)" || lower === "lilith_interpolated" || lower === "lilith_natural" || lower === "interpolated apogee")
+        return "lilith (interpolated)";
+    if (lower === "lilith (mean)" || lower === "lilith" || lower === "mean_lilith" || lower === "mean apogee" || lower === "black moon lilith")
+        return "lilith (mean)";
     return lower;
 }
 const EXTENDED_BODIES = new Set([
     // Slugs match the Go API's ephemerisIDForSlug (handler_wheel_resolver.go) so
-    // additional_objects entries actually resolve server-side.
-    "mean_lilith", "lilith", "lilith_true",
+    // additional_objects entries actually resolve server-side. Only ephemeris
+    // bodies belong here: vertex / part_of_fortune are not additional_objects and
+    // made the API reject every bodies:["all"] request.
+    "lilith", "mean_lilith", "lilith_true", "lilith_interpolated",
     "ceres", "juno", "vesta", "pallas", "pholus",
-    "vertex", "part_of_fortune",
     // Trans-Neptunian objects (all 8 — #603 catalog expansion)
     "eris", "sedna", "makemake", "haumea", "quaoar", "orcus", "ixion", "varuna",
     // Uranian / Hamburg School hypothetical points (all 8 — #603 catalog expansion)
     "cupido", "hades", "zeus", "kronos", "apollon", "admetos", "vulkanus", "poseidon",
 ]);
-const ALL_KNOWN_BODIES = new Set([...CLASSICAL_PLANETS, ...EXTENDED_BODIES]);
+// Names as they come back from the API (canonicalised), for display filtering.
+const ALL_KNOWN_BODIES = new Set([
+    ...CLASSICAL_PLANETS, ...EXTENDED_BODIES,
+    "lilith (mean)", "lilith (true)", "lilith (interpolated)",
+]);
 /**
  * Build a lean, SVG-free payload for Claude's text context.
  * Strips SVG, filters to classical planets only, and packages birth params.
@@ -617,7 +657,7 @@ function buildChartSummary(data, location, houseSystem) {
     const CLASSICAL_ORDER = [
         "sun", "moon", "mercury", "venus", "mars",
         "jupiter", "saturn", "uranus", "neptune", "pluto",
-        "chiron", "north_node", "south_node", "true_node", "asc", "mc",
+        "chiron", "north node (mean)", "north node (true)", "south node (mean)", "south node (true)", "asc", "mc",
     ];
     planetsArray.sort((a, b) => {
         const ai = CLASSICAL_ORDER.indexOf(a.name.toLowerCase());

package/dist/tools/apps/location-tools.js

@@ -1,5 +1,5 @@
 import { registerTool, validateRequired } from "../index.js";
-import { getActiveClient } from "../../backend/client.js";
+import { getActiveClient, isBillingOrAuthError } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 import { TZDATA_AUTHORITATIVE_FROM_YEAR } from "../datetime-historical.js";
 import { isQualifiedForTopHit } from "./_location-resolver.js";
@@ -245,7 +245,11 @@ registerTool({
                     });
                 }
             }
-            catch {
+            catch (err) {
+                // The credit wall / auth / tier gate is not "server unavailable":
+                // surface it with its top-up link instead of a quiet estimate.
+                if (isBillingOrAuthError(err))
+                    throw err;
                 // Server path unavailable — the tzdata estimate stands, still
                 // labelled historical_estimate. Degrading to a labelled
                 // estimate is acceptable; failing the whole search is not.
@@ -349,7 +353,10 @@ registerTool({
                         };
                     }
                 }
-                catch {
+                catch (err) {
+                    // Credit wall / auth / tier gate: surface it, don't degrade.
+                    if (isBillingOrAuthError(err))
+                        throw err;
                     // Server path unavailable — fall through to the local
                     // tzdata estimate below, flagged as such.
                 }

package/dist/tools/apps/moon-phase-app.js

@@ -15,7 +15,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { registerTool, validateCoordinates, SERVER_VERSION } from "../index.js";
-import { getActiveClient } from "../../backend/client.js";
+import { getActiveClient, rethrowBillingOrAuth } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 import { TIMEZONE_PROPERTY } from "../datetime.js";
 import { localToUtcIsoHistorical } from "../datetime-historical.js";
@@ -111,8 +111,16 @@ async function computeMoonData(args) {
         client.request("GET", "/ephemeris/moon/void-of-course", { params }),
         client.request("GET", "/ephemeris/moon/aspects", { params }),
     ]);
+    // A credit wall (402), expired auth (401) or tier gate (403) on ANY of the
+    // three calls must surface as the thrown error — with its top-up / sign-in
+    // link — not as an "Unknown ?%" dial that reads like real data. Only
+    // non-billing partial failures (VOC or aspects down) degrade gracefully.
+    rethrowBillingOrAuth([phase, voc, aspects]);
+    // Without the phase there is no dial to draw; fail rather than render "Unknown".
+    if (phase.status === "rejected")
+        throw phase.reason;
     const mergedData = {
-        phase: phase.status === "fulfilled" ? phase.value : { error: phase.reason?.message },
+        phase: phase.value,
         void_of_course: voc.status === "fulfilled" ? voc.value : { error: voc.reason?.message },
         aspects: aspects.status === "fulfilled" ? aspects.value : null,
     };

package/dist/tools/apps/transit-timeline-app.d.ts

@@ -8,6 +8,9 @@
  * chart to extract real planetary longitudes, searches predictive transits
  * against those targets, then flattens the (planet@target → hits) result map
  * into a single chronological array the iframe renders as a vertical timeline.
+ * The search asks for orb windows (orb_deg) too, so every exact hit carries the
+ * in-orb window it belongs to — when the transit starts and ends, and which
+ * pass it is when a retrograde brings the planet back over the same point.
  *
  * Also exports resource helpers (getTransitTimelineBundle, etc.) for use in
  * index.ts and server-sse.ts.

package/dist/tools/apps/transit-timeline-app.js

@@ -8,6 +8,9 @@
  * chart to extract real planetary longitudes, searches predictive transits
  * against those targets, then flattens the (planet@target → hits) result map
  * into a single chronological array the iframe renders as a vertical timeline.
+ * The search asks for orb windows (orb_deg) too, so every exact hit carries the
+ * in-orb window it belongs to — when the transit starts and ends, and which
+ * pass it is when a retrograde brings the planet back over the same point.
  *
  * Also exports resource helpers (getTransitTimelineBundle, etc.) for use in
  * index.ts and server-sse.ts.
@@ -67,18 +70,32 @@ function normDeg(d) {
     return ((d % 360) + 360) % 360;
 }
 // ── Summary builder ──────────────────────────────────────────────────────────
-function buildSummary(transits, aspectLabel, win) {
+function shortDate(iso) {
+    return iso ? new Date(iso).toISOString().slice(0, 10) : "?";
+}
+function buildSummary(transits, windows, aspectLabel, orbDeg, win) {
+    const active = windows.filter((w) => w.phase_at_start);
+    const activeLines = active.slice(0, 6).map((w) => "  • " + w.planet_name + " " + (w.aspect ?? aspectLabel) + (w.natal_point ? " natal " + w.natal_point : "") +
+        " — " + w.phase_at_start + ", " + (Math.round((w.orb_at_start ?? 0) * 100) / 100) + "° from exact, in orb until " +
+        shortDate(w.leave));
+    const activeBlock = activeLines.length
+        ? "\n\nAlready in orb (" + orbDeg + "°) at the start:\n" + activeLines.join("\n")
+        : "";
     if (transits.length === 0) {
-        return "**Transit Timeline** — no exact transit hits matched the search window and criteria.";
+        return "**Transit Timeline** — no exact transit hits matched the search window and criteria." + activeBlock;
     }
     const planets = [...new Set(transits.map((t) => t.planet_name).filter(Boolean))];
     const lines = transits.slice(0, 8).map((t) => {
         const asp = t.aspect ?? aspectLabel;
         const natal = t.natal_point ? " natal " + t.natal_point : "";
         const when = new Date(t.date).toISOString().slice(0, 10);
+        const passes = t.pass_count > 1 ? ", pass " + t.pass_index + " of " + t.pass_count : "";
+        const inOrb = t.window_start !== undefined
+            ? " — in orb " + shortDate(t.window_start) + " → " + shortDate(t.window_end) + passes
+            : "";
         return "  • " + when + " — " + t.planet_name + " " + asp + natal +
             (t.zodiac_sign ? " (" + (t.zodiac_degree ?? 0) + "° " + t.zodiac_sign + ")" : "") +
-            (t.is_retrograde ? " ℞" : "");
+            (t.is_retrograde ? " ℞" : "") + inOrb;
     });
     let summary = "**Transit Timeline** — " + transits.length + (transits.length === 1 ? " event" : " events") +
         " from " + win.start_date + " to " + win.end_date +
@@ -86,6 +103,7 @@ function buildSummary(transits, aspectLabel, win) {
         lines.join("\n");
     if (transits.length > 8)
         summary += "\n  … and " + (transits.length - 8) + " more.";
+    summary += activeBlock;
     summary += "\n\nClick any transit for details and interpretation.";
     return summary;
 }
@@ -97,12 +115,13 @@ registerTool({
         "astrologically for me in 2027' — a forecast they should SEE. Returns an interactive, " +
         "date-ordered timeline (inline in Claude and ChatGPT; text summary elsewhere) of exact transit " +
         "hits grouped by month — transiting planet glyph, the natal point it contacts, the aspect, zodiac " +
-        "position and retrograde markers — each clickable for a focused interpretation.\n\n" +
+        "position and retrograde markers — each clickable for a focused interpretation. Every hit carries its " +
+        "in-orb window (when the transit starts and ends, and which pass it is when a retrograde repeats it), " +
+        "and transits already in orb at the start are listed with applying/separating.\n\n" +
         "ASPECT ANGLES: 0 = conjunction/return (default), 180 = opposition, 90 = square, 120 = trine, 60 " +
-        "= sextile. EFFICIENCY: specify transiting_planets and natal_points to keep compute fast. DEFAULT " +
-        "natal_points: sun, moon, mercury, venus, mars, jupiter, saturn. SEARCH RANGE LIMITS: " +
-        "Explorer/PayG → 1 year; Pro → 5 years; Startup → 10 years.\n\n" +
-        "CREDIT COST: 6 credits per call (natal chart + predictive transit search).\n\n" +
+        "= sextile. EFFICIENCY: specify transiting_planets and natal_points to keep compute fast. " +
+        "MAX SPAN and CREDIT COST as " +
+        "ephemeris_transits (6 for ≤1 year).\n\n" +
         "Do not use for transit data as JSON — use ephemeris_transits; for the sky today with no birth " +
         "data use electional_moment_analysis; to see one date's transits drawn around the natal wheel use " +
         "explore_bi_wheel (mode='transit').",
@@ -127,6 +146,10 @@ registerTool({
                 type: "number",
                 description: "Aspect angle in degrees. 0 = conjunction/return (default), 180 = opposition, 90 = square, 120 = trine, 60 = sextile.",
             },
+            orb_deg: {
+                type: "number",
+                description: "Orb in degrees that defines when a transit starts and ends (the in-orb window around each exact hit). Default 1. Greater than 0, at most 15.",
+            },
         },
         required: ["natal_datetime", "natal_latitude", "natal_longitude", "start_date", "end_date"],
         additionalProperties: false,
@@ -222,10 +245,12 @@ registerTool({
         let endStr = args.end_date;
         if (/^\d{4}-\d{2}-\d{2}$/.test(endStr))
             endStr += "T23:59:59Z";
+        const orbDeg = typeof args.orb_deg === "number" && args.orb_deg > 0 ? Math.min(args.orb_deg, 15) : 1;
         const transitBody = {
             start_date: startStr,
             end_date: endStr,
             target_degrees: effectiveTargets,
+            orb_deg: orbDeg,
         };
         if (args.transiting_planets)
             transitBody.planet_names = args.transiting_planets;
@@ -278,10 +303,53 @@ registerTool({
             }
         }
         transits.sort((a, b) => new Date(a.date).getTime() - new Date(b.date).getTime());
+        // ── Step 5: orb windows → attach each exact hit to its window ────────────
+        // A window groups every pass the planet makes without leaving the orb, so
+        // a retrograde triple pass is one window with three exacts. Hits are
+        // matched to windows by planet, target degree and exact time.
+        const rawWindows = Array.isArray(transitResult?.windows) ? transitResult.windows : [];
+        const windows = rawWindows.map((w) => {
+            const target = typeof w?.target_longitude === "number" ? w.target_longitude : null;
+            return {
+                planet: String(w?.planet_name ?? "").toLowerCase(),
+                planet_name: String(w?.planet_name ?? ""),
+                natal_point: target != null ? nearestPoint(target) : "",
+                aspect: aspectLabel,
+                target_longitude: target,
+                orb_deg: w?.orb_deg ?? orbDeg,
+                enter: w?.enter ?? null,
+                leave: w?.leave ?? null,
+                exacts: Array.isArray(w?.exacts)
+                    ? w.exacts.map((e) => ({ time: e?.time, is_retrograde: Boolean(e?.is_retrograde) }))
+                    : [],
+                duration_days: w?.duration_days ?? null,
+                phase_at_start: w?.phase_at_start ?? null,
+                orb_at_start: w?.orb_at_start ?? null,
+            };
+        });
+        for (const t of transits) {
+            const hitMs = new Date(t.date).getTime();
+            for (const w of windows) {
+                if (w.planet_name !== t.planet_name || w.target_longitude == null || t.target_longitude == null)
+                    continue;
+                if (Math.abs(w.target_longitude - t.target_longitude) > 0.01)
+                    continue;
+                const idx = w.exacts.findIndex((e) => Math.abs(new Date(e.time).getTime() - hitMs) <= 60_000);
+                if (idx < 0)
+                    continue;
+                t.window_start = w.enter;
+                t.window_end = w.leave;
+                t.pass_index = idx + 1;
+                t.pass_count = w.exacts.length;
+                break;
+            }
+        }
         const win = { start_date: startStr.slice(0, 10), end_date: endStr.slice(0, 10) };
-        const summary = buildSummary(transits, aspectLabel, win);
+        const summary = buildSummary(transits, windows, aspectLabel, orbDeg, win);
         const uiPayload = {
             transits,
+            windows,
+            orb_deg: orbDeg,
             natal_positions: natalPositionMap,
             aspect_angle: aspectAngle,
             aspect_label: aspectLabel,

package/dist/tools/apps/vedic-chart-app.js

@@ -25,6 +25,7 @@ import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 import { localToUtcIsoHistorical } from "../datetime-historical.js";
 import { coordsFromArgsOrLocation } from "./_location-resolver.js";
+import { RENDER_TOKEN_PROPERTY, renderTokenFromVisual, renderTokenHeaders } from "./_render-token.js";
 // ── Constants ─────────────────────────────────────────────────────────────────
 export const VEDIC_CHART_RESOURCE_URI = "ui://openephemeris/vedic-chart";
 export const VEDIC_CHART_MIME_TYPE = "text/html;profile=mcp-app";
@@ -75,12 +76,14 @@ function buildVedicModelPayload(chartData, birthParams, theme) {
         is_retrograde: retrogradeSet.has(String(p.planet ?? "")),
     }));
     const visual = chartData.visual;
+    const renderToken = renderTokenFromVisual(visual);
     return {
         ayanamsa: String(meta.ayanamsha ?? "lahiri").replace(/\b\w/g, (c) => c.toUpperCase()),
         lagna: lagnaSign,
         planets,
         _svg: visual?.data,
         _theme: theme,
+        ...(renderToken ? { _render_token: renderToken } : {}),
         _birth_params: birthParams,
     };
 }
@@ -237,6 +240,7 @@ registerTool({
                 enum: ["light", "dark"],
                 description: "Render palette for the Rashi grid SVG. Mirrors the MCP host's light/dark color scheme.",
             },
+            render_token: RENDER_TOKEN_PROPERTY,
         },
         required: ["datetime"],
     },
@@ -259,7 +263,12 @@ registerTool({
         };
         if (ayanamsa)
             body.ayanamsa = ayanamsa;
-        const chartData = await client.request("POST", "/vedic/chart", { data: body });
+        // A theme reconcile of the chart explore_vedic_chart just rendered presents
+        // that render's token and is not billed again (same account + inputs).
+        const chartData = await client.request("POST", "/vedic/chart", {
+            data: body,
+            headers: renderTokenHeaders(args.render_token),
+        });
         const modelPayload = buildVedicModelPayload(chartData, {
             datetime,
             location: null,

package/dist/tools/datetime-historical.js

@@ -23,7 +23,7 @@
  * beats an outage; the server remains the single authority whenever it is
  * reachable.
  */
-import { getActiveClient } from "../backend/client.js";
+import { getActiveClient, isBillingOrAuthError } from "../backend/client.js";
 import { hasZoneSuffix, isNaiveClockTime, localToUtcIso } from "./datetime.js";
 /** Where IANA tzdata stops being reference-city best effort. */
 export const TZDATA_AUTHORITATIVE_FROM_YEAR = 1970;
@@ -69,7 +69,12 @@ export async function localToUtcIsoHistorical(field, dt, tz, coords, timezoneFie
             return res.resolved_utc;
         }
     }
-    catch {
+    catch (err) {
+        // Out of credits / signed out / tier-gated: surface the credit wall
+        // now rather than silently converting with the pre-1970-wrong tzdata
+        // offset (the chart call that follows would hit the same wall anyway).
+        if (isBillingOrAuthError(err))
+            throw err;
         // Server unreachable or rejected the request — fall through to the
         // local conversion rather than failing the chart call.
     }

package/dist/tools/datetime.js

@@ -81,7 +81,8 @@ export const DATETIME_CONTRACT_INSTRUCTIONS = "Datetime contract: every clock ti
     "the naive local time and name the zone in the sibling `timezone` argument (IANA name, " +
     "e.g. `America/Chicago`). A zone-less clock time is a hard 400 — the engine never " +
     "guesses UTC, because an unstated zone shifts the Ascendant by ~15° per hour and moves " +
-    "every house placement. A bare date (no clock time) resolves to 12:00 UTC.\n\n" +
+    "every house placement. A bare date (no clock time) resolves to 12:00 UTC. A pre-1970 " +
+    "local time with coordinates adds 1 credit (historical timezone lookup).\n\n" +
     "PREFER the local-time + `timezone` form over converting to UTC yourself. The server " +
     "resolves the IANA zone against the actual date, including historical DST rules — that " +
     "arithmetic (which offset applied on that specific day, in that specific year) is easy " +

package/dist/tools/dev.js

@@ -46,10 +46,11 @@ const DEV_API_REFERENCE = "Target API: Open Ephemeris REST API (https://api.open
     "Call dev_list_allowed to see all currently available endpoint paths.\n\n" +
     // Prices mirror go-sidecar/internal/api/auth/usage_meter.go; tiers mirror
     // auth/middleware.go requiredTierForPath. /iching/* aliases /human-design/*.
-    "CREDIT COST: 1 for most GET calls; /calendar/* 10; /acg/* 10 (Pro tier); /electional/* 5 " +
-    "(find-window and aspect-search are Pro tier; moment-analysis and station-tracker are free); " +
-    "/human-design/* and /iching/* 2; catalogs/health 0; requests over 30s add 1 " +
-    "per 30s. Pass query {format: 'llm'} for compact output.\n\n";
+    "CREDIT COST: 1 for most; /predictive/* 5 (transits/search 5-70 by span); /comparative/* 3; " +
+    "/calendar/* 10 (moon-phases, lunar-standstill 2; cross-quarter 5); /acg/* 10 (Pro); " +
+    "/electional/* 5 (Pro, span-priced searches; moment-analysis, station-tracker free); " +
+    "/human-design/*, /iching/* 2 (composite, transit-chart 3; penta 2/member); catalogs 0; " +
+    "4xx/5xx refunded. Query {format: 'llm'} = compact output.\n\n";
 const READ_COMMON_CALLS = "COMMON CALLS:\n" +
     "  GET  /ephemeris/moon/phase             — Current/queried moon phase\n" +
     "  GET  /ephemeris/moon/void-of-course    — Next void-of-course period\n" +
@@ -60,13 +61,13 @@ const READ_COMMON_CALLS = "COMMON CALLS:\n" +
     "  GET  /eclipse/solar/global             — Next global solar eclipse (query: date=YYYY-MM-DD)\n" +
     "  GET  /eclipse/solar/local              — Local solar eclipse (query: lat, lon)\n" +
     "  GET  /tidal/forcing                    — Gravitational tidal forcing index\n" +
-    "  GET  /calendar/astrology/moon-phases   — Moon phase calendar for a date range\n" +
+    "  GET  /calendar/astrology/moon-phases   — next New/Quarter/Full Moon after a date or jd\n" +
     "  GET  /location/autocomplete            — Geocode a place name (query: query=City Name)\n" +
     "  GET  /chinese/zodiac                   — Chinese zodiac year element/animal\n" +
     "  GET  /catalogs/bodies                  — List all supported celestial bodies\n";
 const WRITE_COMMON_CALLS = "COMMON CALLS:\n" +
     "  POST /ephemeris/natal-chart            — Full natal chart (body: {subject: {name: 'Name', birth_datetime: {iso: '1990-04-15T14:30:00-05:00'}, birth_location: {latitude: {decimal: 40.0}, longitude: {decimal: -70.0}, timezone: {}}}})\n" +
-    "  POST /ephemeris/natal/batch            — Up to 50 natal charts in one request\n" +
+    "  POST /ephemeris/natal/batch            — Up to 100 natal charts in one request (Startup tier)\n" +
     "  POST /ephemeris/relocation             — Relocated chart (same natal, new location)\n" +
     "  POST /predictive/transits/search       — Transit event search over a date range\n" +
     "  POST /predictive/returns/solar         — Solar return chart\n" +

package/dist/tools/specialized/electional.js

@@ -10,7 +10,8 @@ registerTool({
         "date range, 'find me a good day next month' or 'pick an auspicious window'. Returns the best " +
         "continuous timing windows in the range, scored hourly on essential dignity, aspect quality, sect " +
         "and void-of-course Moon penalties, with optional filters (avoid_voc, lunar_phase).\n\n" +
-        "CREDIT COST: 5 credits per call. Pro tier.\n\n" +
+        "CREDIT COST: ≤30 days 5, ≤60 days 8, ≤120 days 12. Pro tier; max window Pro 30 days, Startup " +
+        "60, Scale 120.\n\n" +
         "Do not use to score one specific moment or 'right now' — use electional_moment_analysis; for " +
         "retrograde dates use electional_station_tracker.",
     inputSchema: {
@@ -222,7 +223,7 @@ registerTool({
     description: "Find all active aspects between planets at a specific moment. Returns aspect type, " +
         "orb, quality score, and whether it's applying or separating. Great for checking " +
         "the 'weather' of a given day.\n\n" +
-        "CREDIT COST: 5 credits per call.\n\n" +
+        "CREDIT COST: 5 credits per call. Pro tier.\n\n" +
         "EXAMPLE: What aspects are active on March 21, 2026?\n" +
         "  date='2026-03-21T12:00:00Z'",
     inputSchema: {
@@ -276,7 +277,7 @@ registerTool({
         "Sun, Moon, Mercury, Venus, Mars and the lunar nodes — the same body set and formula the CCG hybrid " +
         "transit map (/acg/ccg mode=ccg_hybrid) draws with; every other body stays a transit. Progressed " +
         "crossings carry progressed: true and search_summary.progression names what was progressed.\n\n" +
-        "CREDIT COST: 5 credits per call.\n\n" +
+        "CREDIT COST: priced by start→end span — ≤1 month 5, ≤3 months 8, ≤6 months 10, ≤1 year 12. Pro tier.\n\n" +
         "EXAMPLE: When does Mercury cross the Descendant over Warsaw on 2026-07-30?\n" +
         "  latitude=52.2297, longitude=21.0122, bodies='Mercury', angles='DC',\n" +
         "  start='2026-07-30T00:00:00Z', end='2026-07-31T00:00:00Z'",

package/dist/tools/specialized/ephemeris_extended.js

@@ -1,5 +1,5 @@
 import { registerTool, validateRequired, validateCoordinates } from "../index.js";
-import { getActiveClient } from "../../backend/client.js";
+import { getActiveClient, rethrowBillingOrAuth } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 import { DATETIME_DESC, TIMEZONE_PROPERTY, assertZonedDatetime, toDateTimeInputBody } from "../datetime.js";
 // `field`/`timezoneField` name the caller's own argument path (e.g.
@@ -134,10 +134,19 @@ registerTool({
         }
         // Fan-out: the backend only handles one planet per call; query all 10 in parallel.
         const PLANET_IDS = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
-        const results = await Promise.all(PLANET_IDS.map((pid) => client.post("/ephemeris/retrograde-status", {
+        const settled = await Promise.allSettled(PLANET_IDS.map((pid) => client.post("/ephemeris/retrograde-status", {
             date_time: toDateTimeInputBody("datetime", args.datetime, args.timezone),
             planet_id: pid,
-        }).catch(() => null)));
+        })));
+        // Out of credits / signed out / tier-gated: throw the credit-wall (or
+        // auth) error so its top-up link reaches the assistant. Swallowing it
+        // used to return `{planets: {}, success: true}` at zero credits.
+        rethrowBillingOrAuth(settled);
+        const results = settled.map((s) => (s.status === "fulfilled" ? s.value : null));
+        if (results.every((r) => r == null)) {
+            // Every planet failed for a non-billing reason — never report success with no data.
+            throw settled[0].reason;
+        }
         // Merge into a keyed object: { planet_name: {...status} }
         const merged = {};
         for (const res of results) {
@@ -151,7 +160,13 @@ registerTool({
                 };
             }
         }
-        return { planets: merged, datetime: args.datetime, success: true };
+        const failed = PLANET_IDS.filter((_, i) => results[i] == null);
+        return {
+            planets: merged,
+            datetime: args.datetime,
+            success: true,
+            ...(failed.length ? { failed_planet_ids: failed } : {}),
+        };
     },
 });
 // POST /ephemeris/midpoints

package/dist/tools/specialized/hd_group.js

@@ -8,7 +8,7 @@ registerTool({
     name: "human_design_composite",
     description: "Calculate a Human Design composite chart for two people. Merges both bodygraphs " +
         "to show shared channels, authority dynamics, and relationship type.\n\n" +
-        "CREDIT COST: 4 credits per call.\n\n" +
+        "CREDIT COST: 3 credits per call.\n\n" +
         "EXAMPLE (local times + zones):\n" +
         "  person_a_datetime='1990-04-15T14:30:00', person_a_timezone='America/Chicago',\n" +
         "  person_b_datetime='1988-09-22T08:15:00', person_b_timezone='America/Los_Angeles'\n" +
@@ -74,7 +74,7 @@ registerTool({
     name: "human_design_penta",
     description: "Calculate a Human Design Penta (group) chart for 3-5 people. Shows functional " +
         "attributes, leadership dynamics, channels, redundancies, and a group stability score.\n\n" +
-        "CREDIT COST: 6 credits per call.\n\n" +
+        "CREDIT COST: 2 credits per member (6-10 for 3-5 people).\n\n" +
         "EXAMPLE (3 people — each datetime states its zone):\n" +
         "  group_name='Team Alpha',\n" +
         "  members=[\n" +

package/dist/tools/specialized/moon.d.ts

@@ -1 +1 @@
-export {};
+export declare const NEXT_LUNAR_PHASE_MAX_COUNT = 12;