@openephemeris/mcp-server 4.16.0 → 4.18.0

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

@@ -12,10 +12,10 @@
  * Supported modes (BiWheelMode):
  *   synastry     — two natal charts (person1 inner, person2 outer)
  *   transit      — natal inner + transiting planets outer
- *   progressed   — natal inner + secondary progressions outer  (POST /ephemeris/progressed)
+ *   progressed   — natal inner + secondary progressions outer  (POST /ephemeris/progressed, method=secondary)
  *   solar_return — natal inner + solar return chart outer      (POST /predictive/returns/solar)
  *   lunar_return — natal inner + lunar return chart outer      (POST /predictive/returns/lunar)
- *   solar_arc    — natal inner + solar arc directions outer    (client-side Naibod approximation)
+ *   solar_arc    — natal inner + solar arc directions outer    (POST /ephemeris/progressed, method=solar_arc)
  *
  * Cross-aspects are computed client-side (UI) AND server-side (for summary/fallback).
  * The payload cross_aspects array is capped at 30 tightest-orb aspects.
@@ -26,7 +26,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, timezoneProperty } from "../datetime.js";
+import { DATETIME_DESC, timezoneProperty, toDateTimeInputBody } from "../datetime.js";
 import { coordsFromArgsOrLocation } from "./_location-resolver.js";
 // ── Constants ─────────────────────────────────────────────────────────────────
 export const BI_WHEEL_RESOURCE_URI = "ui://openephemeris/bi-wheel";
@@ -130,120 +130,68 @@ function buildNatalBody(datetime, lat, lon, timezone, houseSystem = "placidus")
     }
     return body;
 }
-function buildTransitBody(transitDate, natalDatetime, lat, lon, timezone) {
+function locationBody(lat, lon, timezone) {
     return {
-        subject: {
-            name: "MCP Request",
-            birth_datetime: { iso: natalDatetime },
-            birth_location: {
-                latitude: { decimal: lat ?? 0 },
-                longitude: { decimal: lon ?? 0 },
-            },
-        },
-        transit_datetime: { iso: transitDate },
+        latitude: { decimal: lat },
+        longitude: { decimal: lon },
         ...(timezone ? { timezone: { iana_name: timezone } } : {}),
-        configuration: { house_system: HOUSE_SYSTEM_MAP["placidus"] },
     };
 }
-/** POST /ephemeris/progressed — secondary progressions */
-function buildProgressedBody(natalDatetime, lat, lon, timezone, targetDatetime) {
-    const body = {
-        subject: {
-            name: "MCP Request",
-            birth_datetime: { iso: natalDatetime },
-            birth_location: {
-                latitude: { decimal: lat ?? 0 },
-                longitude: { decimal: lon ?? 0 },
-            },
-        },
-        configuration: {
-            target_datetime: { iso: targetDatetime },
-            method: "secondary",
-            house_system: HOUSE_SYSTEM_MAP["placidus"],
-        },
-    };
-    if (timezone) {
-        body.subject.birth_location.timezone = { iana_name: timezone };
-    }
+/**
+ * POST /ephemeris/progressed. `method` picks secondary progressions or true
+ * solar arc directions — the server directs planets, angles AND house cusps by
+ * the Sun's real arc (ProgressedChartRequest; target_datetime is top-level,
+ * the method rides in progression_options).
+ */
+function buildProgressedBody(natalDatetime, lat, lon, timezone, targetDatetime, targetTimezone, method, houseSystem) {
+    const body = buildNatalBody(natalDatetime, lat, lon, timezone, houseSystem);
+    body.target_datetime = toDateTimeInputBody("person2_datetime", targetDatetime, targetTimezone);
+    body.progression_options = { method };
     return body;
 }
-/** POST /predictive/returns/solar or /predictive/returns/lunar */
-function buildReturnBody(natalDatetime, natalLat, natalLon, timezone, targetDatetime, returnLat, returnLon) {
-    const body = {
-        subject: {
-            name: "MCP Request",
-            birth_datetime: { iso: natalDatetime },
-            birth_location: {
-                latitude: { decimal: natalLat ?? 0 },
-                longitude: { decimal: natalLon ?? 0 },
-            },
-        },
-        return_location: {
-            latitude: { decimal: returnLat ?? natalLat ?? 0 },
-            longitude: { decimal: returnLon ?? natalLon ?? 0 },
-        },
-        target_datetime: { iso: targetDatetime },
-        configuration: { house_system: HOUSE_SYSTEM_MAP["placidus"] },
+/**
+ * POST /predictive/returns/solar or /predictive/returns/lunar. These take a
+ * flat body (birth_datetime at the top level, no `subject`) — see
+ * SolarReturnRequest / LunarReturnRequest in openapi.json.
+ */
+function buildReturnBody(natalDatetime, natalLat, natalLon, timezone, targetDatetime, targetTimezone, returnLat, returnLon, houseSystem) {
+    return {
+        birth_datetime: toDateTimeInputBody("person1_datetime", natalDatetime, timezone, "person1_timezone"),
+        birth_location: locationBody(natalLat, natalLon, timezone),
+        return_location: locationBody(returnLat, returnLon),
+        target_datetime: toDateTimeInputBody("person2_datetime", targetDatetime, targetTimezone, "person2_timezone"),
+        house_system: HOUSE_SYSTEM_MAP[houseSystem] ?? HOUSE_SYSTEM_MAP["placidus"],
     };
-    if (timezone) {
-        body.subject.birth_location.timezone = { iana_name: timezone };
-    }
-    return body;
 }
 /**
- * Client-side solar arc: advance every natal planet longitude by elapsed years in degrees.
- * Uses the Naibod rate (1 tropical year ≈ 0.9856°). The natal data object is cloned and
- * the planets array/map is offset — houses are left at natal positions (standard practice).
+ * Route outer-wheel fetch to the correct API endpoint based on mode, and hand
+ * back a chart in the natal-chart shape (top-level planets/houses/angles):
+ * /ephemeris/progressed nests it under `data`, the return endpoints under `chart`.
  */
-function applySolarArcOffset(natalData, natalDatetime, targetDatetime) {
-    const natalYear = new Date(natalDatetime).getFullYear() +
-        new Date(natalDatetime).getMonth() / 12;
-    const targetYear = new Date(targetDatetime).getFullYear() +
-        new Date(targetDatetime).getMonth() / 12;
-    const arcDegrees = (targetYear - natalYear) * 0.9856; // Naibod rate
-    const offsetPlanets = (raw) => {
-        if (Array.isArray(raw)) {
-            return raw.map((p) => ({
-                ...p,
-                longitude: ((p.longitude ?? 0) + arcDegrees + 360) % 360,
-            }));
+export async function fetchOuterChart(client, mode, dt1, lat1, lon1, tz1, dt2, lat2, lon2, tz2, houseSystem = "placidus") {
+    const post = (path, body) => client.post(path, body);
+    const unwrap = (resp, key) => {
+        const inner = resp?.[key];
+        if (!inner || typeof inner !== "object") {
+            throw new Error(`Unexpected ${mode} response: no \`${key}\` chart in the API reply.`);
         }
-        if (raw && typeof raw === "object" && !Array.isArray(raw)) {
-            const out = {};
-            for (const [k, v] of Object.entries(raw)) {
-                if (v && typeof v === "object" && "longitude" in v) {
-                    out[k] = { ...v, longitude: ((v.longitude ?? 0) + arcDegrees + 360) % 360 };
-                }
-                else {
-                    out[k] = v;
-                }
-            }
-            return out;
-        }
-        return raw;
+        return inner;
     };
-    return {
-        ...natalData,
-        planets: offsetPlanets(natalData.planets),
-        _solar_arc_degrees: Math.round(arcDegrees * 1000) / 1000,
-    };
-}
-/** Route outer-wheel fetch to the correct API endpoint based on mode. */
-async function fetchOuterChart(client, mode, dt1, lat1, lon1, tz1, dt2, lat2, lon2, tz2) {
     switch (mode) {
         case "synastry":
-            return client.post("/ephemeris/natal-chart", buildNatalBody(dt2, lat2, lon2, tz2));
+            return post("/ephemeris/natal-chart", buildNatalBody(dt2, lat2, lon2, tz2, houseSystem));
         case "transit":
-            return client.post("/ephemeris/natal-chart", buildNatalBody(dt2, lat2 ?? lat1, lon2 ?? lon1, tz2 ?? tz1));
+            return post("/ephemeris/natal-chart", buildNatalBody(dt2, lat2 ?? lat1, lon2 ?? lon1, tz2 ?? tz1, houseSystem));
         case "progressed":
-            return client.post("/ephemeris/progressed", buildProgressedBody(dt1, lat1, lon1, tz1, dt2));
+        case "solar_arc":
+            return unwrap(await post("/ephemeris/progressed", buildProgressedBody(dt1, lat1, lon1, tz1, dt2, tz2 ?? tz1, mode === "progressed" ? "secondary" : "solar_arc", houseSystem)), "data");
         case "solar_return":
-            return client.post("/predictive/returns/solar", buildReturnBody(dt1, lat1, lon1, tz1, dt2, lat2 ?? lat1, lon2 ?? lon1));
-        case "lunar_return":
-            return client.post("/predictive/returns/lunar", buildReturnBody(dt1, lat1, lon1, tz1, dt2, lat2 ?? lat1, lon2 ?? lon1));
-        case "solar_arc": {
-            const natal = await client.post("/ephemeris/natal-chart", buildNatalBody(dt1, lat1, lon1, tz1));
-            return applySolarArcOffset(natal, dt1, dt2);
+        case "lunar_return": {
+            if (lat1 == null || lon1 == null) {
+                throw new Error(`Internal: ${mode} requires Person 1's latitude and longitude.`);
+            }
+            const path = mode === "solar_return" ? "/predictive/returns/solar" : "/predictive/returns/lunar";
+            return unwrap(await post(path, buildReturnBody(dt1, lat1, lon1, tz1, dt2, tz2 ?? tz1, lat2 ?? lat1, lon2 ?? lon1, houseSystem)), "chart");
         }
     }
 }
@@ -292,25 +240,35 @@ export function computeCrossAspects(planets1, planets2) {
 const CLASSICAL_PLANETS = new Set([
     "sun", "moon", "mercury", "venus", "mars",
     "jupiter", "saturn", "uranus", "neptune", "pluto",
-    "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 must never share a name.
+    "north node (mean)", "north node (true)", "south node (mean)", "south node (true)",
 ]);
 /**
- * Normalise the Go backend's verbose planet key (e.g. "North Node (Mean)")
- * to the canonical lowercase underscore form the renderer expects.
+ * Normalise the Go backend's verbose planet key to the canonical lowercase form
+ * the renderer expects. The lunar nodes keep their full names ("north node
+ * (mean)" etc.), matching packages/widget-ui/shared/lunar-nodes.ts.
  */
 function canonicalizePlanetName(raw) {
     const lower = raw.toLowerCase();
     // Various node/chiron aliases the Go PlanetName() function emits.
-    // Keep mean vs true DISTINCT so the UI can offer a node toggle; collapsing
-    // both to "north_node" (the old behaviour) produced two overlapping ☊ glyphs.
+    // Keep mean vs true DISTINCT (North and South alike) so the UI can offer a
+    // node toggle and every label says which node it is.
     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)")
-        return "south_node";
-    if (lower === "mean apogee" || lower === "black moon lilith" || lower === "lilith (mean)" || lower === "lilith (true)")
-        return "lilith";
+        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)";
+    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)";
     // Strip parenthetical qualifiers for any other bodies just in case
     return lower.replace(/\s*\(.*?\)/g, "").replace(/\s+/g, "_");
 }
@@ -613,7 +571,7 @@ registerTool({
         const loc2 = MODE_META[mode].outerLabel(dt2, args.person2_name);
         const [innerData, outerData] = await Promise.all([
             client.post("/ephemeris/natal-chart", buildNatalBody(dt1, lat1, lon1, tz1, houseSystem)),
-            fetchOuterChart(client, mode, dt1, lat1, lon1, tz1, dt2, lat2, lon2, tz2),
+            fetchOuterChart(client, mode, dt1, lat1, lon1, tz1, dt2, lat2, lon2, tz2, houseSystem),
         ]);
         const params1 = { datetime: dt1, timezone: tz1 ?? null, latitude: lat1 ?? null, longitude: lon1 ?? null, location: loc1 };
         const params2 = { datetime: dt2, timezone: tz2 ?? null, latitude: lat2 ?? null, longitude: lon2 ?? null, location: loc2 };
@@ -721,9 +679,10 @@ const PLANET_THEMES = {
     neptune: "dreams, idealism, compassion, and dissolution",
     pluto: "transformation, power dynamics, and profound change",
     chiron: "the wounded healer — deep vulnerability, mastery through pain, and the gift of empathy forged in suffering",
-    north_node: "soul direction and karmic growth edge; the evolutionary path forward in this lifetime",
-    south_node: "accumulated karma and innate past-life gifts; the comfort zone that must be transcended",
-    true_node: "soul direction and karmic growth edge; the evolutionary path forward in this lifetime",
+    "north node (mean)": "soul direction and karmic growth edge; the evolutionary path forward in this lifetime",
+    "north node (true)": "soul direction and karmic growth edge; the evolutionary path forward in this lifetime",
+    "south node (mean)": "accumulated karma and innate past-life gifts; the comfort zone that must be transcended",
+    "south node (true)": "accumulated karma and innate past-life gifts; the comfort zone that must be transcended",
     asc: "the rising sign and outer personality mask; the social self, physical appearance, and the lens through which life is encountered",
     mc: "public vocation, highest ambition, and the world's face; the pinnacle of achievement this person strives toward",
 };
@@ -797,7 +756,7 @@ function interpretBiWheelPlanet(planet, sign, house, wheel, retrograde = false,
             `Unlike transits, progressed planets move slowly — a sign ingress can take years to unfold. This position describes a chapter of inner development: the themes of ${capitalize(planet)} are now being expressed with the colouring of ${signQuality}. Aspects from this progressed position to natal points mark turning points in that developmental arc.`);
     }
     else if (mode === "solar_arc") {
-        return (`**Solar Arc ${capitalize(planet)}:** This directed position represents natal ${capitalize(planet)} advanced by approximately 1° per year of life.${houseCtx}${retroCtx}\n\n` +
+        return (`**Solar Arc ${capitalize(planet)}:** This directed position represents natal ${capitalize(planet)} advanced by the solar arc — the distance the progressed Sun has travelled since birth (roughly 1° a year).${houseCtx}${retroCtx}\n\n` +
             `Solar arc directions symbolise the symbolic maturation of each natal archetype. Where the directed ${capitalize(planet)} now falls — and especially which natal planets or angles it contacts — marks a significant chapter in the long development of ${theme}. Conjunctions, squares, and oppositions to natal points are the most potent activation signals.`);
     }
     else if (mode === "solar_return") {
@@ -990,7 +949,7 @@ registerTool({
             progressed: `**Secondary Progressions Overview: ${label1} × ${label2}**\n\n` +
                 `This progression bi-wheel places the natal chart inside and secondary progressed positions in the outer ring. Progressed planets reflect the gradual inner maturation of natal archetypal themes using the day-for-a-year method. Cross-aspects from progressed to natal points mark the defining chapters of inner development.`,
             solar_arc: `**Solar Arc Directions Overview: ${label1} × ${label2}**\n\n` +
-                `This solar arc bi-wheel shows natal positions inside and solar arc directed positions in the outer ring. Solar arc direction advances every natal planet by approximately 1° per year of life (Naibod rate). Contacts from directed positions to natal points — especially conjunctions — mark pivotal life moments.`,
+                `This solar arc bi-wheel shows natal positions inside and solar arc directed positions in the outer ring. Solar arc direction advances every natal planet, angle and house cusp by the same arc: the distance the progressed Sun has travelled since birth (roughly 1° a year). Contacts from directed positions to natal points — especially conjunctions — mark pivotal life moments.`,
             solar_return: `**Solar Return Overview: ${label1} × ${label2}**\n\n` +
                 `This solar return bi-wheel compares the natal chart against the solar return for the target year. The outer ring shows where planets fall at the exact moment the Sun returns to its natal degree, describing the dominant themes and developmental focus of the coming solar year.`,
             lunar_return: `**Lunar Return Overview: ${label1} × ${label2}**\n\n` +

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) {