@openephemeris/mcp-server 4.17.0 → 4.18.0

package/dist/tools/apps/_render-token.js

@@ -0,0 +1,50 @@
+/**
+ * _render-token.ts — plumbing for the API's server-issued render token.
+ *
+ * The Go API stamps every charged visual on a render-family route
+ * (/human-design/chart + /visualization/bodygraph, /human-design/transit-chart,
+ * /human-design/composite, /chinese/bazi, /vedic/chart) with a short-lived
+ * token bound to the account and the chart-defining inputs
+ * (auth/render_token.go). Presenting it on a re-render of the SAME chart —
+ * the iframe's host light/dark reconciliation, a layout flip — makes that
+ * re-render free (base charge and visual surcharge). Anything else is charged
+ * normally, so passing a stale or foreign token is harmless.
+ *
+ * Flow: explore_* puts the token on the payload as `_render_token`; the iframe
+ * hands it back as the `render_token` argument of its recalc / refetch call;
+ * the tool sends it in the X-OE-Render-Token header.
+ */
+export const RENDER_TOKEN_HEADER = "X-OE-Render-Token";
+/** Input-schema property for the app-only recalc args. Never set by the model. */
+export const RENDER_TOKEN_PROPERTY = {
+    type: "string",
+    description: "Set automatically by the embedded app when it re-renders a chart it already paid for " +
+        "(e.g. to match the host's light/dark theme). Never pass this yourself.",
+};
+/** Request headers presenting `token`, or undefined when there is none. */
+export function renderTokenHeaders(token) {
+    return typeof token === "string" && token.trim() !== ""
+        ? { [RENDER_TOKEN_HEADER]: token.trim() }
+        : undefined;
+}
+/**
+ * The token the API injected on the root <svg> of a /visualization/bodygraph
+ * response (a binary route, whose response headers the backend client does
+ * not surface).
+ */
+export function renderTokenFromSvg(svg) {
+    if (!svg)
+        return undefined;
+    const m = /<svg\b[^>]*\sdata-oe-render-token="([A-Za-z0-9._-]+)"/.exec(svg);
+    return m ? m[1] : undefined;
+}
+/** `visual.render_token` from an include_visual JSON response. */
+export function renderTokenFromVisual(visual) {
+    const t = visual?.render_token;
+    return typeof t === "string" && t !== "" ? t : undefined;
+}
+/** Copy of tool args with the per-call token removed (for `_refetch.args`). */
+export function withoutRenderToken(args) {
+    const { render_token: _drop, ...rest } = args;
+    return rest;
+}

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

@@ -26,6 +26,7 @@ import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 // this replaces used `new Date(naive)`, which resolves in the host process's
 // timezone and silently shifted the hour pillar on any non-UTC server.
 import { parseBaziArgs, buildBaziConventionFields, CONVENTION_PROPERTIES } from "../specialized/bazi.js";
+import { RENDER_TOKEN_PROPERTY, renderTokenFromVisual, renderTokenHeaders } from "./_render-token.js";
 // ── Constants ─────────────────────────────────────────────────────────────────
 export const BAZI_RESOURCE_URI = "ui://openephemeris/bazi";
 export const BAZI_MIME_TYPE = "text/html;profile=mcp-app";
@@ -60,26 +61,39 @@ export function getBaziBundle() {
 export function clearBaziBundleCache() {
     cachedBundle = null;
 }
+const CONVENTION_ARG_KEYS = ["year_boundary", "day_boundary", "true_solar_time", "latitude", "longitude", "timezone"];
+function pickConventionArgs(args) {
+    const out = {};
+    for (const k of CONVENTION_ARG_KEYS) {
+        if (args?.[k] != null && args[k] !== "")
+            out[k] = args[k];
+    }
+    return out;
+}
 /**
  * Fetch the BaZi chart via the include_visual intercept — one call returns
  * both the structured pillar data (year/month/day/hour/day_master) and the
  * Go-rendered SVG (bazi.RenderBaziChartSVG), same shape the strict
  * /chinese/bazi handler returns with a `visual` key attached.
  */
-async function fetchBaziChart(components, theme = "dark", conventionFields = {}, reconcile = false) {
+async function fetchBaziChart(components, theme = "dark", conventionFields = {}, renderToken) {
     const client = getActiveClient();
     const body = {
         ...components,
         ...conventionFields,
         include_visual: true,
         visual_config: { format: "svg", theme, size: 800 },
-        // Set only by bazi_recalculate's theme-reconcile path below — waives the
-        // visual surcharge server-side for a same-birth-data re-render (#551).
-        ...(reconcile ? { _visual_reconcile: true } : {}),
     };
-    return await client.request("POST", "/chinese/bazi", { data: body });
+    // bazi_recalculate's theme reconcile presents the token the first render
+    // was issued; the API waives the whole re-render only when it verifies for
+    // this account and these exact inputs (the old self-serve
+    // `_visual_reconcile` flag is gone).
+    return await client.request("POST", "/chinese/bazi", {
+        data: body,
+        headers: renderTokenHeaders(renderToken),
+    });
 }
-function buildModelPayload(data, components, theme) {
+function buildModelPayload(data, components, theme, conventionArgs = {}) {
     return {
         year: data.year,
         month: data.month,
@@ -88,7 +102,9 @@ function buildModelPayload(data, components, theme) {
         day_master: data.day_master,
         _svg: data.visual?.data,
         _birth_params: components,
+        ...(Object.keys(conventionArgs).length ? { _convention_args: conventionArgs } : {}),
         _theme: theme,
+        ...(renderTokenFromVisual(data.visual) ? { _render_token: renderTokenFromVisual(data.visual) } : {}),
     };
 }
 function buildSummary(payload) {
@@ -180,7 +196,7 @@ registerTool({
             return { content: [{ type: "text", text: buildSummary(payload) }] };
         }
         const data = await fetchBaziChart(components, theme, conventionFields);
-        const payload = buildModelPayload(data, components, theme);
+        const payload = buildModelPayload(data, components, theme, pickConventionArgs(args));
         const summary = buildSummary(payload);
         // MCP Apps wire format: the UI is declared via `_meta.ui.resourceUri` and
         // delivered through resources/read — NOT as a content block.
@@ -199,9 +215,9 @@ registerTool({
     name: "bazi_recalculate",
     description: "Recalculates a BaZi Four Pillars chart with new birth data or theme. " +
         "App-only: called by the embedded chart itself to reconcile the initial " +
-        "server-rendered SVG to the host's actual light/dark theme. Billed at 1 " +
-        "credit (base only) — the visual-render surcharge is waived because this " +
-        "re-renders already-computed data, not a new chart.",
+        "server-rendered SVG to the host's actual light/dark theme. Free when it " +
+        "presents the render_token of the chart it re-renders (same birth data and " +
+        "conventions); otherwise billed like a new chart (3 credits).",
     inputSchema: {
         type: "object",
         properties: {
@@ -209,11 +225,15 @@ registerTool({
             month: { type: "integer" },
             day: { type: "integer" },
             hour: { type: "integer" },
+            minute: { type: "integer" },
+            ...CONVENTION_PROPERTIES,
+            timezone: { type: "string", description: "IANA timezone name the chart was cast in." },
             theme: {
                 type: "string",
                 enum: ["light", "dark"],
                 description: "Render palette for the BaZi SVG. Mirrors the MCP host's light/dark color scheme.",
             },
+            render_token: RENDER_TOKEN_PROPERTY,
         },
         required: ["year", "month", "day"],
     },
@@ -223,8 +243,12 @@ registerTool({
     handler: async (args) => {
         const components = parseBaziArgs(args);
         const theme = args.theme === "light" ? "light" : "dark";
-        const data = await fetchBaziChart(components, theme, {}, true);
-        const payload = buildModelPayload(data, components, theme);
+        // Re-cast under the SAME conventions as the original chart — dropping them
+        // (as this tool used to) rendered a different chart on any non-default
+        // year/day boundary, and would not match the render token either.
+        const conventionArgs = pickConventionArgs(args);
+        const data = await fetchBaziChart(components, theme, buildBaziConventionFields(conventionArgs), args.render_token);
+        const payload = buildModelPayload(data, components, theme, conventionArgs);
         return {
             content: [{ type: "text", text: JSON.stringify({ ...payload, server_version: SERVER_VERSION }) }],
         };

package/dist/tools/apps/bi-wheel-app.d.ts

@@ -12,20 +12,27 @@
  * 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.
  */
+import { getActiveClient } from "../../backend/client.js";
 export declare const BI_WHEEL_RESOURCE_URI = "ui://openephemeris/bi-wheel";
 export declare const BI_WHEEL_MIME_TYPE = "text/html;profile=mcp-app";
 /** Read the pre-built HTML bundle. Returns null if not yet built. */
 export declare function getBiWheelBundle(): string | null;
 export declare function clearBiWheelBundleCache(): void;
 export type BiWheelMode = "synastry" | "transit" | "progressed" | "solar_return" | "lunar_return" | "solar_arc";
+/**
+ * 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`.
+ */
+export declare function fetchOuterChart(client: Pick<ReturnType<typeof getActiveClient>, "post">, mode: BiWheelMode, dt1: string, lat1: number | undefined, lon1: number | undefined, tz1: string | undefined, dt2: string, lat2: number | undefined, lon2: number | undefined, tz2: string | undefined, houseSystem?: string): Promise<Record<string, unknown>>;
 interface PlanetPoint {
     name: string;
     longitude: number;

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