@openephemeris/mcp-server 4.17.0 → 4.18.0

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

@@ -23,10 +23,11 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { registerTool, SERVER_VERSION } 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 { localToUtcIsoHistorical } from "../datetime-historical.js";
 import { coordsFromArgsOrLocation } from "./_location-resolver.js";
+import { RENDER_TOKEN_PROPERTY, renderTokenFromSvg, renderTokenFromVisual, renderTokenHeaders, withoutRenderToken, } from "./_render-token.js";
 // ── Constants ─────────────────────────────────────────────────────────────
 export const BODYGRAPH_RESOURCE_URI = "ui://openephemeris/bodygraph";
 // Appended to every model-visible HD tool description — trademark hygiene.
@@ -67,7 +68,7 @@ export function clearBodygraphBundleCache() {
 function capitalize(s) {
     return s.charAt(0).toUpperCase() + s.slice(1);
 }
-async function fetchGoBodygraphSVG(body, theme = "dark", view) {
+async function fetchGoBodygraphSVG(body, theme = "dark", view, renderToken) {
     try {
         const client = getActiveClient();
         // /visualization/bodygraph is registered as binary in BINARY_ENDPOINT_PREFIXES.
@@ -89,7 +90,14 @@ async function fetchGoBodygraphSVG(body, theme = "dark", view) {
             qs += `&rings=${encodeURIComponent(view.rings)}`;
         if (view?.houseSystem)
             qs += `&house_system=${encodeURIComponent(view.houseSystem)}`;
-        const resp = await client.post(`/visualization/bodygraph?${qs}`, body);
+        // A re-render of a chart this account already paid for presents its render
+        // token; the API waives the charge only if it verifies for these inputs.
+        // The API returns the (new or echoed) token as data-oe-render-token on the
+        // root <svg> — read it back with renderTokenFromSvg.
+        const resp = await client.request("POST", `/visualization/bodygraph?${qs}`, {
+            data: body,
+            headers: renderTokenHeaders(renderToken),
+        });
         if (typeof resp === "string")
             return resp;
         if (resp && typeof resp === "object") {
@@ -101,6 +109,10 @@ async function fetchGoBodygraphSVG(body, theme = "dark", view) {
         return null;
     }
     catch (err) {
+        // Out of credits / signed out must reach the assistant with the credit-wall
+        // message and top-up link — never be papered over by the client render.
+        if (isBillingOrAuthError(err))
+            throw err;
         console.warn("[bodygraph] Go SVG fetch failed, will fall back to client render:", err);
         return null;
     }
@@ -413,6 +425,9 @@ registerTool({
         });
         if (svg)
             modelPayload._svg = svg;
+        const renderToken = renderTokenFromSvg(svg);
+        if (renderToken)
+            modelPayload._render_token = renderToken;
         const summary = buildHdSummary(modelPayload, location);
         if (bundleAvailable) {
             // MCP Apps wire format: the UI is declared via `_meta.ui.resourceUri` and
@@ -468,6 +483,7 @@ registerTool({
                 type: "string",
                 description: "House system for the mandala house ring. Only used when layout=mandala and rings includes 'houses' with a birth location. Adds 1 credit when the house ring renders.",
             },
+            render_token: RENDER_TOKEN_PROPERTY,
         },
         required: ["datetime"],
     },
@@ -494,11 +510,15 @@ registerTool({
         if (lon != null)
             body.longitude = lon;
         // Recalculate is iframe-only (visibility: ["app"]) — always co-fetch the SVG.
+        // Both halves present the render token: a theme / layout flip of the chart
+        // already on screen is then free (the house ring's 1-credit surcharge still
+        // applies when it renders); new birth data is charged as a new chart.
         const [chartData, svg] = await Promise.all([
             client.request("POST", "/human-design/chart", {
                 data: body,
+                headers: renderTokenHeaders(args.render_token),
             }),
-            fetchGoBodygraphSVG(body, theme, { layout, rings, houseSystem }),
+            fetchGoBodygraphSVG(body, theme, { layout, rings, houseSystem }, args.render_token),
         ]);
         const chart = chartData.chart ?? chartData;
         const modelPayload = buildHdModelPayload(chart, {
@@ -510,6 +530,11 @@ registerTool({
         });
         if (svg)
             modelPayload._svg = svg;
+        // The API echoes the presented token on a waived re-render, or mints a new
+        // one when this was charged as a new chart (e.g. edited birth data).
+        const renderToken = renderTokenFromSvg(svg);
+        if (renderToken)
+            modelPayload._render_token = renderToken;
         return {
             content: [{ type: "text", text: JSON.stringify({ ...modelPayload, server_version: SERVER_VERSION }) }],
         };
@@ -1176,9 +1201,8 @@ registerTool({
         "The Variable describes the four arrow directions attached to the Personality Sun/Earth " +
         "and Design Sun/Earth positions, encoding the PHS (Primary Health System) — the optimal conditions " +
         "for the body-mind to receive information and make decisions. " +
-        "Returns an interpretation of Digestion (right/left Personality Sun arrow), " +
-        "Perspective (right/left Personality Earth arrow), " +
-        "Environment (right/left Design Sun arrow), and Motivation (right/left Design Earth arrow). " +
+        "Returns an interpretation of Motivation (Personality Sun), Digestion (Design Sun), " +
+        "Perspective (Personality Node) and Environment (Design Node). " +
         "This tool is called automatically by the bodygraph UI; you do not need to call it directly.",
     inputSchema: {
         type: "object",
@@ -1224,13 +1248,13 @@ registerTool({
                     "and being drawn by appetite and desire rather than routine. " +
                     "Left Digestion types often thrive with more novelty, conversation, and engagement at the table — " +
                     "your body needs to be activated, not passively nourished.",
-                tones: {
-                    1: "Tone 1 — Consecutive: best with orderly, sequential eating — simple and unvaried meals in a fixed rhythm.",
-                    2: "Tone 2 — Alternating: eat a variety of foods but alternate types — not all mixed together.",
-                    3: "Tone 3 — Cyclic: allow the body to cycle through periods of different dietary focuses.",
-                    4: "Tone 4 — Calm: eat only when the emotional atmosphere is calm and undisturbed.",
-                    5: "Tone 5 — Open: eat in open spaces or with good air circulation; avoid enclosed or stagnant settings.",
-                    6: "Tone 6 — Closed: eat in private, quiet, familiar environments — protected from public exposure.",
+                colors: {
+                    1: { left: "Appetite, Consecutive: orderly, one-at-a-time eating at regular times.", right: "Appetite, Alternating: grazing and switching between kinds of food across the day." },
+                    2: { left: "Taste, Open: sampling first; a bite tells the body what fits today.", right: "Taste, Closed: knowing what fits by sight or smell, without needing to try it." },
+                    3: { left: "Thirst, Hot: warm food, warm drinks, warm settings.", right: "Thirst, Cold: cool food, cool drinks, calm and cool settings." },
+                    4: { left: "Touch, Calm: eating in a quiet, settled atmosphere, often alone.", right: "Touch, Nervous: eating with some activity or buzz around." },
+                    5: { left: "Sound, High: eating with conversation, music or background sound.", right: "Sound, Low: eating in quiet." },
+                    6: { left: "Light, Direct: eating in daylight, earlier in the day.", right: "Light, Indirect: eating in softer light or later in the day." },
                 },
             },
             perspective: {
@@ -1251,13 +1275,13 @@ registerTool({
                     "stimulating environments. This is an Active environment variable: you are designed to encounter " +
                     "variety, new places, and fresh stimulation. Being too long in the same environment can lead to " +
                     "stagnation, restlessness, or decreased vitality.",
-                tones: {
-                    1: "Tone 1 — Caves: you do best in enclosed, cozy, cave-like environments with shelter overhead.",
-                    2: "Tone 2 — Markets: you thrive in places of exchange and activity — social, commercial, varied.",
-                    3: "Tone 3 — Kitchens: hearth-centered environments — where nourishment and community gather.",
-                    4: "Tone 4 — Mountains: elevated, expansive, airy environments with altitude and horizon.",
-                    5: "Tone 5 — Valleys: sheltered, low, protected geographies — river valleys, low land, sheltered bays.",
-                    6: "Tone 6 — Shores: boundary environments — coast, lakeside, edge-of-land — where elements meet.",
+                colors: {
+                    1: { left: "Caves, Exclusive: enclosed, protected spaces with few people.", right: "Caves, Blending: sheltered spaces shared with a trusted group." },
+                    2: { left: "Markets, Internal: places of exchange where you have a clear role inside.", right: "Markets, External: open places of exchange you move through." },
+                    3: { left: "Kitchens, Wet: hearth and gathering places with moisture and life.", right: "Kitchens, Dry: hearth and gathering places that are dry and warm." },
+                    4: { left: "Mountains, Active: high, open ground with movement.", right: "Mountains, Passive: high, open ground to rest in and overlook." },
+                    5: { left: "Valleys, Narrow: sheltered low ground with a close view.", right: "Valleys, Wide: sheltered low ground with a wide view." },
+                    6: { left: "Shores, Natural: edges where land meets water, in nature.", right: "Shores, Artificial: edges and thresholds in built places." },
                 },
             },
             motivation: {
@@ -1267,13 +1291,13 @@ registerTool({
                 left: "**Left Motivation** (Active) \u2014 Your decision-making is best guided by active, intentional pursuit " +
                     "of what aligns with your values and strategy. You are designed to initiate and drive toward what matters to you — " +
                     "though always filtered through your Authority to ensure the body’s wisdom is guiding the mind.",
-                tones: {
-                    1: "Tone 1 — Fear: the motivation to move away from what limits or threatens, turning fear into healthy caution.",
-                    2: "Tone 2 — Hope: the motivation toward a better, more expanded future possibility.",
-                    3: "Tone 3 — Desire: the motivation driven by genuine wanting and attraction.",
-                    4: "Tone 4 — Need: the motivation arising from a felt sense of lack or necessity.",
-                    5: "Tone 5 — Guilt: the motivation arising from responsibility to others and the tribe.",
-                    6: "Tone 6 — Innocence: the motivation of pure openness, not knowing, and beginner’s mind.",
+                colors: {
+                    1: { left: "Fear: the drive to understand the unknown and stay safe.", right: "Fear: the drive to understand the unknown and stay safe." },
+                    2: { left: "Hope: trust in a better possible outcome.", right: "Hope: trust in a better possible outcome." },
+                    3: { left: "Desire: the push to change or affect the world.", right: "Desire: the push to change or affect the world." },
+                    4: { left: "Need: identifying what is necessary.", right: "Need: identifying what is necessary." },
+                    5: { left: "Guilt: the drive to fix and improve.", right: "Guilt: the drive to fix and improve." },
+                    6: { left: "Innocence: acting without a personal agenda.", right: "Innocence: acting without a personal agenda." },
                 },
             },
         };
@@ -1284,11 +1308,8 @@ registerTool({
             };
         }
         const main = direction === "right" ? info.right : info.left;
-        const toneNote = tone != null && info.tones?.[tone]
-            ? `\n\n**Your Specific Tone (${tone}):** ${info.tones[tone]}`
-            : "";
-        const colorNote = color != null
-            ? `\n\n**Color ${color}** subtly modulates this Variable's expression — these nuances are covered in advanced PHS reading.`
+        const colorNote = color != null && info.colors?.[color]
+            ? `\n\n**Your Color ${color}${tone != null ? `, Tone ${tone}` : ""}:** ${info.colors[color][direction]}`
             : "";
         const label = `${capitalize(variable)} Arrow — ${capitalize(direction)} Variable`;
         const icon = variable === "digestion" ? "🔵" : variable === "perspective" ? "🟢" : variable === "environment" ? "⚪" : "🔴";
@@ -1296,7 +1317,7 @@ registerTool({
             content: [{
                     type: "text",
                     text: `**${label}** ${icon}\n\n` +
-                        main + toneNote + colorNote +
+                        main + colorNote +
                         "\n\n*The Variable is a refinement layer within the Primary Health System (PHS). " +
                         "It describes the optimal conditions for the body-brain to receive and process information correctly. " +
                         "Living according to your Variable is an advanced practice that supports deeper health, clarity, and cognitive accuracy.*",
@@ -1315,7 +1336,7 @@ registerTool({
         "(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" +
+        "CREDIT COST: 5 credits per call (chart 3 + render 2; +1 per 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,
@@ -1349,6 +1370,7 @@ registerTool({
                     "concentric ring set the natal chart uses. Set by the in-iframe layout toggle, never by " +
                     "the model.",
             },
+            render_token: RENDER_TOKEN_PROPERTY,
         },
         required: ["datetime"],
     },
@@ -1410,7 +1432,12 @@ registerTool({
             body.include_visual = true;
             body.visual_config = { theme, ...(layout ? { layout } : {}) };
         }
-        const resp = await client.request("POST", "/human-design/transit-chart", { data: body });
+        // The iframe's theme / layout refetch presents the token of the overlay it
+        // is showing; the API waives it only for the same account + inputs.
+        const resp = await client.request("POST", "/human-design/transit-chart", {
+            data: body,
+            headers: renderTokenHeaders(args.render_token),
+        });
         const transit = (resp?.transit ?? {});
         const completed = Array.isArray(transit.completed_channels) ? transit.completed_channels : [];
         const newCenters = Array.isArray(transit.newly_defined_centers) ? transit.newly_defined_centers : [];
@@ -1428,8 +1455,15 @@ registerTool({
             ...resp,
             _svg: svg,
             _theme: theme,
-            // Lets the iframe re-request this overlay in the host's theme.
-            _refetch: { tool: "explore_human_design_transit", args: { ...args } },
+            ...(renderTokenFromVisual(resp?.visual) ? { _render_token: renderTokenFromVisual(resp?.visual) } : {}),
+            // Lets the iframe re-request this overlay in the host's theme. The
+            // resolved coordinates/zone/name are pinned so the refetch neither
+            // re-geocodes (another credit) nor drifts to a different request body,
+            // which would no longer match the render token.
+            _refetch: {
+                tool: "explore_human_design_transit",
+                args: { ...withoutRenderToken(args), latitude: lat, longitude: lon, location, ...(timezone ? { timezone } : {}) },
+            },
             server_version: SERVER_VERSION,
         };
         if (bundleAvailable && svg) {
@@ -1453,7 +1487,7 @@ registerTool({
         "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" +
+        "CREDIT COST: 5 credits per call (composite 3 + render 2).\n\n" +
         "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,
@@ -1498,6 +1532,7 @@ registerTool({
                     "concentric ring set the natal chart uses. Set by the in-iframe layout toggle, never by " +
                     "the model.",
             },
+            render_token: RENDER_TOKEN_PROPERTY,
         },
         required: ["person_a", "person_b"],
     },
@@ -1529,12 +1564,15 @@ registerTool({
                 throw new Error(`${label} requires either \`latitude\` + \`longitude\` or a resolvable \`location\` name. ` +
                     "Human Design is sensitive to birth location; a chart at 0°N 0°E is silently wrong.");
             }
+            // Pin the resolved coordinates for the iframe's refetch (see _refetch).
+            pinned[label] = { ...(p ?? {}), latitude: lat, longitude: lon, ...(tz ? { timezone: tz } : {}) };
             return {
                 birth_datetime_utc: await localToUtcIsoHistorical(`${label}.datetime`, String(p?.datetime), tz, { latitude: lat, longitude: lon }, `${label}.timezone`),
                 latitude: lat,
                 longitude: lon,
             };
         };
+        const pinned = {};
         const body = {
             subject_1: await toSubject(args.person_a, "person_a"),
             subject_2: await toSubject(args.person_b, "person_b"),
@@ -1547,7 +1585,10 @@ registerTool({
             body.include_visual = true;
             body.visual_config = { theme, ...(layout ? { layout } : {}) };
         }
-        const resp = await client.request("POST", "/human-design/composite", { data: body });
+        const resp = await client.request("POST", "/human-design/composite", {
+            data: body,
+            headers: renderTokenHeaders(args.render_token),
+        });
         const connections = Array.isArray(resp?.connections) ? resp.connections : [];
         const svg = resp?.visual?.data;
         const byType = (t) => connections.filter((c) => c?.type === t).map((c) => c.id);
@@ -1566,7 +1607,13 @@ registerTool({
             ...resp,
             _svg: svg,
             _theme: theme,
-            _refetch: { tool: "explore_human_design_connection", args: { ...args } },
+            ...(renderTokenFromVisual(resp?.visual) ? { _render_token: renderTokenFromVisual(resp?.visual) } : {}),
+            // Resolved coordinates pinned so the refetch neither re-geocodes nor
+            // drifts from the request the render token was issued for.
+            _refetch: {
+                tool: "explore_human_design_connection",
+                args: { ...withoutRenderToken(args), person_a: pinned.person_a, person_b: pinned.person_b },
+            },
             server_version: SERVER_VERSION,
         };
         if (bundleAvailable && svg) {

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.js

@@ -119,10 +119,9 @@ registerTool({
         "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').",

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 " +