@openephemeris/mcp-server 3.13.9 → 3.13.10

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

@@ -1,15 +1,21 @@
 /**
  * bi-wheel-app.ts — MCP App tool registration for the Bi-Wheel Explorer.
  *
- * Registers 3 tools:
- *   • explore_bi_wheel               — primary entry point: fetches two charts, computes
- *                                      cross-aspects, returns data + UI resource [model]
+ * Registers 6 tools:
+ *   • explore_bi_wheel               — primary entry point [model + app]
+ *   • bi_wheel_recalculate           — re-fetch with new params [app-only]
  *   • bi_wheel_on_cross_aspect_click — cross-aspect click handler [app-only]
- *   • bi_wheel_on_planet_click       — planet click handler (inner or outer wheel) [app-only]
+ *   • bi_wheel_on_planet_click       — planet click handler [app-only]
+ *   • bi_wheel_on_house_click        — house cusp click handler [app-only]
+ *   • bi_wheel_synopsis              — full reading overview [model + app]
  *
- * Modes:
- *   synastry — fetch two natal charts in parallel (person1 inner, person2 outer)
- *   transit  — fetch one natal chart (inner) + one transit chart (outer)
+ * 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)
+ *   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)
  *
  * 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.
@@ -42,6 +48,53 @@ export function getBiWheelBundle() {
 export function clearBiWheelBundleCache() {
     cachedBiWheelBundle = null;
 }
+const ALL_MODES = [
+    "synastry", "transit", "progressed", "solar_return", "lunar_return", "solar_arc",
+];
+const MODE_META = {
+    synastry: {
+        outerLabel: (_, name) => name ?? "Person 2",
+        innerRole: "Person 1 (inner)",
+        outerRole: "Person 2 (outer)",
+        credits: 1,
+        modeLabel: "Synastry",
+    },
+    transit: {
+        outerLabel: (dt) => `Transit · ${dt.slice(0, 10)}`,
+        innerRole: "Natal (inner)",
+        outerRole: "Transits (outer)",
+        credits: 1,
+        modeLabel: "Transit",
+    },
+    progressed: {
+        outerLabel: (dt) => `Progressions · ${dt.slice(0, 10)}`,
+        innerRole: "Natal (inner)",
+        outerRole: "Progressed (outer)",
+        credits: 1,
+        modeLabel: "Secondary Progressions",
+    },
+    solar_return: {
+        outerLabel: (dt) => `Solar Return · ${dt.slice(0, 4)}`,
+        innerRole: "Natal (inner)",
+        outerRole: "Solar Return (outer)",
+        credits: 5,
+        modeLabel: "Solar Return",
+    },
+    lunar_return: {
+        outerLabel: (dt) => `Lunar Return · ${dt.slice(0, 10)}`,
+        innerRole: "Natal (inner)",
+        outerRole: "Lunar Return (outer)",
+        credits: 5,
+        modeLabel: "Lunar Return",
+    },
+    solar_arc: {
+        outerLabel: (dt) => `Solar Arc · ${dt.slice(0, 10)}`,
+        innerRole: "Natal (inner)",
+        outerRole: "Solar Arc Directions (outer)",
+        credits: 1,
+        modeLabel: "Solar Arc Directions",
+    },
+};
 // ── House system helpers (shared with chart-wheel) ────────────────────────────
 const HOUSE_SYSTEM_MAP = {
     placidus: "P", whole_sign: "W", equal: "E", koch: "K",
@@ -81,6 +134,108 @@ function buildTransitBody(transitDate, natalDatetime, lat, lon, 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 };
+    }
+    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"] },
+    };
+    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).
+ */
+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,
+            }));
+        }
+        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 {
+        ...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));
+        case "transit":
+            return client.post("/ephemeris/natal-chart", buildNatalBody(dt2, lat2 ?? lat1, lon2 ?? lon1, tz2 ?? tz1));
+        case "progressed":
+            return client.post("/ephemeris/progressed", buildProgressedBody(dt1, lat1, lon1, tz1, dt2));
+        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);
+        }
+    }
+}
 const CROSS_ASPECT_DEFS = [
     { type: "conjunction", angle: 0, orb: 8 },
     { type: "opposition", angle: 180, orb: 8 },
@@ -196,10 +351,10 @@ function buildBiWheelSummary(innerPlanets, outerPlanets, crossAspects, mode, loc
         square: "□", sextile: "⚹",
     };
     const top5 = crossAspects.slice(0, 5).map((ca) => `• ${capitalize(ca.planet1)} ${ASPECT_SYMBOL[ca.type] ?? ca.type} ${capitalize(ca.planet2)} (${ca.orb.toFixed(1)}° orb${ca.applying ? ", applying" : ""})`);
-    const modeLabel = mode === "synastry" ? "Synastry" : "Transit";
-    const label1 = mode === "synastry" ? "Person 1 (inner)" : "Natal (inner)";
-    const label2 = mode === "synastry" ? "Person 2 (outer)" : "Transit (outer)";
-    return (`**${modeLabel} Bi-Wheel**\n\n` +
+    const meta = MODE_META[mode];
+    const label1 = meta.innerRole;
+    const label2 = meta.outerRole;
+    return (`**${meta.modeLabel} Bi-Wheel**\n\n` +
         `${label1}: ${location1} — ${innerBasics || "chart loaded"}\n` +
         `${label2}: ${location2}\n\n` +
         `**Top Cross-Aspects:**\n${top5.join("\n") || "No major cross-aspects within orb."}\n\n` +
@@ -208,12 +363,16 @@ function buildBiWheelSummary(innerPlanets, outerPlanets, crossAspects, mode, loc
 // ── Tool: explore_bi_wheel ─────────────────────────────────────────────────────
 registerTool({
     name: "explore_bi_wheel",
-    description: "Generate an interactive bi-wheel chart for synastry (two natal charts) or transit analysis " +
-        "(natal chart + transiting planets). In synastry mode, the inner wheel shows Person 1's natal " +
-        "chart and the outer ring shows Person 2's natal chart. In transit mode, the inner wheel shows " +
-        "the natal chart and the outer ring shows transiting planets for the given date. " +
+    description: "Generate an interactive bi-wheel chart comparing two astrological chart positions. " +
+        "The inner wheel is always Person 1's natal chart. The outer ring depends on mode:\n" +
+        "• synastry     — Person 2's natal chart (two-person compatibility). 1 credit.\n" +
+        "• transit      — Transiting planets for a given date. 1 credit.\n" +
+        "• progressed   — Secondary progressed positions (person2_datetime = target date). 1 credit.\n" +
+        "• solar_return — Nearest solar return chart (person2_datetime = year to return for). 5 credits.\n" +
+        "• lunar_return — Nearest lunar return chart (person2_datetime = target month). 5 credits.\n" +
+        "• solar_arc    — Solar arc directed positions (person2_datetime = target date). 1 credit.\n" +
         "Cross-aspects between both wheels are computed and displayed as coloured dashed lines. " +
-        "Click any planet or cross-aspect line for interpretation.",
+        "Click any planet, aspect line, or house cusp for interpretation.",
     inputSchema: {
         type: "object",
         properties: {
@@ -230,14 +389,16 @@ registerTool({
             },
             person2_datetime: {
                 type: "string",
-                description: "ISO 8601 datetime for Person 2 (synastry) or the transit date (transit mode). Required.",
+                description: "ISO 8601 datetime for the outer wheel. Meaning depends on mode: " +
+                    "synastry = Person 2 birth datetime; transit/progressed/solar_arc = target date; " +
+                    "solar_return/lunar_return = any date within the target year/month.",
             },
-            person2_latitude: { type: "number", description: "Birth latitude for Person 2 / transit location (decimal degrees)." },
-            person2_longitude: { type: "number", description: "Birth longitude for Person 2 / transit location (decimal degrees)." },
-            person2_timezone: { type: "string", description: "IANA timezone for Person 2 / transit (e.g. 'America/Chicago')." },
+            person2_latitude: { type: "number", description: "Birth latitude for Person 2 (synastry) or return/transit location. Defaults to Person 1 coords for single-person modes." },
+            person2_longitude: { type: "number", description: "Birth longitude for Person 2 (synastry) or return/transit location. Defaults to Person 1 coords for single-person modes." },
+            person2_timezone: { type: "string", description: "IANA timezone for Person 2 / outer chart (e.g. 'America/Chicago')." },
             person2_name: {
                 type: "string",
-                description: "Display name for Person 2 / Transit chart (e.g. 'Bob'). Used in the badge and summary.",
+                description: "Display name for Person 2 (synastry mode). Used in the badge and summary.",
             },
             location: {
                 type: "string",
@@ -245,13 +406,12 @@ registerTool({
             },
             mode: {
                 type: "string",
-                enum: ["synastry", "transit"],
-                description: "Chart mode: 'synastry' (two natal charts) or 'transit' (natal + transits). Defaults to 'synastry'.",
+                enum: ["synastry", "transit", "progressed", "solar_return", "lunar_return", "solar_arc"],
+                description: "Chart comparison mode. Defaults to 'synastry'.",
             },
         },
         required: ["person1_datetime", "person2_datetime",
-            "person1_latitude", "person1_longitude",
-            "person2_latitude", "person2_longitude"],
+            "person1_latitude", "person1_longitude"],
     },
     annotations: {
         title: "Interactive Bi-Wheel Explorer",
@@ -278,25 +438,12 @@ registerTool({
         const lon2 = args.person2_longitude;
         const tz2 = args.person2_timezone;
         const loc1 = String(args.person1_name ?? args.location ?? `${lat1 ?? "?"},${lon1 ?? "?"}`);
-        const loc2 = mode === "transit"
-            ? `Transit ${dt2.slice(0, 10)}`
-            : String(args.person2_name ?? `${lat2 ?? ""},${lon2 ?? ""}`);
-        // Fetch both charts in parallel
-        let innerData;
-        let outerData;
-        if (mode === "synastry") {
-            [innerData, outerData] = await Promise.all([
-                client.post("/ephemeris/natal-chart", buildNatalBody(dt1, lat1, lon1, tz1)),
-                client.post("/ephemeris/natal-chart", buildNatalBody(dt2, lat2, lon2, tz2)),
-            ]);
-        }
-        else {
-            // Transit mode: inner = natal (dt1), outer = transits for dt2 at natal location
-            [innerData, outerData] = await Promise.all([
-                client.post("/ephemeris/natal-chart", buildNatalBody(dt1, lat1, lon1, tz1)),
-                client.post("/ephemeris/natal-chart", buildNatalBody(dt2, lat2 ?? lat1, lon2 ?? lon1, tz2 ?? tz1)),
-            ]);
-        }
+        const loc2 = MODE_META[mode].outerLabel(dt2, args.person2_name);
+        // Fetch inner (natal) and outer (mode-dependent) charts in parallel where possible
+        const [innerData, outerData] = await Promise.all([
+            client.post("/ephemeris/natal-chart", buildNatalBody(dt1, lat1, lon1, tz1)),
+            fetchOuterChart(client, mode, dt1, lat1, lon1, tz1, dt2, lat2, lon2, tz2),
+        ]);
         const innerPlanets = normalizePlanets(innerData.planets);
         const outerPlanets = normalizePlanets(outerData.planets);
         const crossAspects = computeCrossAspects(innerPlanets, outerPlanets);
@@ -324,11 +471,11 @@ registerTool({
 // ── Tool: bi_wheel_recalculate ──────────────────────────────────────────────
 registerTool({
     name: "bi_wheel_recalculate",
-    description: "Recalculates a bi-wheel chart (synastry, transit, or progressed mode) with new parameters.",
+    description: "Recalculates a bi-wheel chart with new parameters. Supports all modes: synastry, transit, progressed, solar_return, lunar_return, solar_arc.",
     inputSchema: {
         type: "object",
         properties: {
-            mode: { type: "string", enum: ["synastry", "transit", "progressed"] },
+            mode: { type: "string", enum: ALL_MODES },
             person1_datetime: { type: "string" },
             person1_latitude: { type: "number" },
             person1_longitude: { type: "number" },
@@ -339,7 +486,7 @@ registerTool({
             person2_longitude: { type: "number" },
             person2_timezone: { type: "string" },
             person2_name: { type: "string" },
-            location: { type: "string" }, // fallback
+            location: { type: "string" },
         },
         required: ["mode", "person1_datetime", "person1_latitude", "person1_longitude", "person2_datetime"],
     },
@@ -357,30 +504,11 @@ registerTool({
         const lon2 = args.person2_longitude;
         const tz2 = args.person2_timezone;
         const loc1 = String(args.person1_name ?? args.location ?? `${lat1 ?? "?"},${lon1 ?? "?"}`);
-        const loc2 = mode === "transit" ? `Transit ${dt2.slice(0, 10)}` : String(args.person2_name ?? `${lat2 ?? ""},${lon2 ?? ""}`);
-        let innerData;
-        let outerData;
-        if (mode === "synastry") {
-            [innerData, outerData] = await Promise.all([
-                client.post("/ephemeris/natal-chart", buildNatalBody(dt1, lat1, lon1, tz1)),
-                client.post("/ephemeris/natal-chart", buildNatalBody(dt2, lat2, lon2, tz2)),
-            ]);
-        }
-        else if (mode === "progressed") {
-            [innerData, outerData] = await Promise.all([
-                client.post("/ephemeris/natal-chart", buildNatalBody(dt1, lat1, lon1, tz1)),
-                client.post("/predictive/progressed", {
-                    subject: { birth_datetime: { iso: dt1 }, birth_location: { latitude: { decimal: lat1 ?? 0 }, longitude: { decimal: lon1 ?? 0 }, timezone: tz1 ? { iana_name: tz1 } : undefined } },
-                    configuration: { target_datetime: { iso: dt2 }, method: "secondary" }
-                }),
-            ]);
-        }
-        else {
-            [innerData, outerData] = await Promise.all([
-                client.post("/ephemeris/natal-chart", buildNatalBody(dt1, lat1, lon1, tz1)),
-                client.post("/ephemeris/natal-chart", buildNatalBody(dt2, lat2 ?? lat1, lon2 ?? lon1, tz2 ?? tz1)),
-            ]);
-        }
+        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)),
+            fetchOuterChart(client, mode, dt1, lat1, lon1, tz1, dt2, lat2, lon2, tz2),
+        ]);
         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 };
         const payload = buildBiWheelPayload(innerData, outerData, mode, params1, params2);
@@ -393,19 +521,19 @@ registerTool({
 registerTool({
     name: "bi_wheel_on_cross_aspect_click",
     description: "Event handler called when the user clicks a cross-aspect line in the bi-wheel. " +
-        "Returns a synastry or transit interpretation of that aspect between the two wheels. " +
+        "Returns an interpretation of that aspect contextualised by chart mode (synastry, transit, progressed, etc.). " +
         "This tool is called automatically by the bi-wheel UI; you do not need to call it directly.",
     inputSchema: {
         type: "object",
         properties: {
             planet1: { type: "string", description: "Planet name from the inner (natal) wheel" },
             wheel1: { type: "string", enum: ["inner", "outer"], description: "Which wheel planet1 belongs to" },
-            planet2: { type: "string", description: "Planet name from the outer (synastry/transit) wheel" },
+            planet2: { type: "string", description: "Planet name from the outer wheel" },
             wheel2: { type: "string", enum: ["inner", "outer"], description: "Which wheel planet2 belongs to" },
             aspect_type: { type: "string", description: "Aspect type: conjunction, opposition, trine, square, sextile" },
             orb: { type: "number", description: "Orb in degrees" },
             applying: { type: "boolean", description: "True if the aspect is applying (tightening)" },
-            mode: { type: "string", enum: ["synastry", "transit"], description: "Chart mode (synastry or transit). Determines interpretation style." },
+            mode: { type: "string", enum: ALL_MODES, description: "Chart mode. Determines interpretation style." },
         },
         required: ["planet1", "planet2", "aspect_type"],
     },
@@ -438,12 +566,12 @@ registerTool({
         type: "object",
         properties: {
             planet: { type: "string", description: "Planet name (e.g. 'saturn')" },
-            wheel: { type: "string", enum: ["inner", "outer"], description: "Which wheel (inner=natal/person1, outer=synastry/transit)" },
+            wheel: { type: "string", enum: ["inner", "outer"], description: "Which wheel (inner=natal/person1, outer=mode-dependent)" },
             longitude: { type: "number", description: "Ecliptic longitude in degrees" },
             sign: { type: "string", description: "Zodiac sign" },
             house: { type: "number", description: "House number (1–12) if available" },
             retrograde: { type: "boolean", description: "Whether the planet is retrograde" },
-            mode: { type: "string", enum: ["synastry", "transit"], description: "Chart mode" },
+            mode: { type: "string", enum: ALL_MODES, description: "Chart mode" },
         },
         required: ["planet", "wheel", "longitude"],
     },
@@ -452,16 +580,17 @@ registerTool({
     handler: async (args) => {
         const planet = String(args.planet);
         const wheel = args.wheel ?? "inner";
+        const mode = args.mode ?? "synastry";
         const sign = args.sign ? String(args.sign) : zodSignFromLon(Number(args.longitude));
         const houseNum = args.house != null ? Number(args.house) : null;
         const house = houseNum != null && houseNum > 0 ? ` in the ${ordinal(houseNum)} house` : "";
-        const wheelLabel = wheel === "inner" ? "Natal / Person 1" : "Synastry / Transit";
+        const wheelLabel = wheel === "inner" ? MODE_META[mode].innerRole : MODE_META[mode].outerRole;
         const deg = `${Math.floor(Number(args.longitude) % 30)}° ${sign}`;
         return {
             content: [{
                     type: "text",
                     text: `**${capitalize(planet)} at ${deg}${house}** *(${wheelLabel})*\n\n` +
-                        interpretBiWheelPlanet(planet, sign, houseNum ?? 0, wheel, Boolean(args.retrograde)),
+                        interpretBiWheelPlanet(planet, sign, houseNum ?? 0, wheel, Boolean(args.retrograde), mode),
                 }],
         };
     },
@@ -555,7 +684,24 @@ function interpretBiWheelPlanet(planet, sign, house, wheel, retrograde = false,
         return (`**Transiting Planet:** Transiting ${capitalize(planet)} represents ${theme}. Moving through ${capitalize(sign)}, it carries the quality of ${signQuality}.${houseCtx}${retroCtx}\n\n` +
             `As a **transit**, this planet is temporarily activating the natal chart. Its influence is current and time-limited — watch for events, shifts in awareness, or opportunities related to its themes in the houses and planets it touches.`);
     }
+    else if (mode === "progressed") {
+        return (`**Progressed Planet:** Progressed ${capitalize(planet)} in ${capitalize(sign)} shows how the natal ${capitalize(planet)} archetype has evolved through lived experience.${houseCtx}${retroCtx}\n\n` +
+            `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` +
+            `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") {
+        return (`**Solar Return ${capitalize(planet)}:** In this solar return chart, ${capitalize(planet)} falls at ${Math.floor((Number(sign) || 0) % 30)}° ${capitalize(sign)}.${houseCtx}${retroCtx}\n\n` +
+            `Solar return planets describe themes that will be especially prominent during this **solar year** — from this birthday to the next. ${capitalize(planet)} in the return chart highlights where the energy of ${theme} will be most active, especially in the house it occupies and through contacts to natal planets.`);
+    }
+    else if (mode === "lunar_return") {
+        return (`**Lunar Return ${capitalize(planet)}:** In this lunar return chart, ${capitalize(planet)} sets the tone for the coming **lunar month**.${houseCtx}${retroCtx}\n\n` +
+            `Lunar returns reset monthly as the Moon returns to its natal degree. ${capitalize(planet)}'s position here — through ${signQuality} — shapes the emotional and circumstantial flavour of the next four weeks. Contacts to natal planets or angles sharpen its influence considerably.`);
+    }
     else {
+        // synastry fallback
         return (`**Synastry Planet:** ${capitalize(planet)} represents ${theme}. In ${capitalize(sign)}, this manifests through ${signQuality}.${houseCtx}${retroCtx}\n\n` +
             `This is the **outer person's natal ${capitalize(planet)}** — when this planet makes contact with the inner chart, it activates the natal themes of both parties simultaneously, creating a dynamic of mutual recognition and activation.`);
     }
@@ -584,8 +730,11 @@ const CROSS_ASPECT_NATURE = {
 };
 function interpretCrossAspect(p1, p2, type, applying, mode) {
     const natures = CROSS_ASPECT_NATURE[type.toLowerCase()];
+    // Single-person time-based modes share the transit nature text; synastry/solar arc use synastry
+    const isTimeBased = mode === "transit" || mode === "progressed" || mode === "solar_arc" ||
+        mode === "solar_return" || mode === "lunar_return";
     const nature = natures
-        ? (mode === "transit" ? natures.transit : natures.synastry)
+        ? (isTimeBased ? natures.transit : natures.synastry)
         : "creates a notable connection across the two charts.";
     let timing;
     if (mode === "transit") {
@@ -593,6 +742,17 @@ function interpretCrossAspect(p1, p2, type, applying, mode) {
             ? "This aspect is **applying** — its influence is building and moving toward maximum expression. The themes involved are intensifying now."
             : "This aspect is **separating** — its peak has passed; the energy is waning and the lessons of this transit are moving into integration.";
     }
+    else if (mode === "progressed" || mode === "solar_arc") {
+        timing = applying
+            ? "This aspect is **applying** — progressed and directed aspects move slowly, often unfolding over months or years before reaching exactitude. The themes it represents are gradually intensifying."
+            : "This aspect is **separating** — it has passed its peak of exactitude and is now in a phase of integration. The defining moment of this developmental aspect lies in the recent past.";
+    }
+    else if (mode === "solar_return") {
+        timing = "As a **solar return aspect**, this connection is active for the entire solar year from this birthday to the next. It describes a consistent theme or dynamic that will colour the whole year rather than arriving as a dated event.";
+    }
+    else if (mode === "lunar_return") {
+        timing = "As a **lunar return aspect**, this connection is active for the coming lunar month. It shapes the emotional atmosphere and events of the next four weeks before the next lunar return resets the cycle.";
+    }
     else {
         timing = "As a **synastry aspect**, this connection exists as a permanent feature of this relationship dynamic — it neither builds nor fades, but remains as a constant undercurrent in how these two people interact.";
     }
@@ -611,7 +771,7 @@ registerTool({
             house_number: { type: "number", description: "House number (1–12)" },
             sign: { type: "string", description: "Sign on the house cusp (inner natal wheel)" },
             cusp_longitude: { type: "number", description: "Cusp longitude in degrees" },
-            mode: { type: "string", enum: ["synastry", "transit"], description: "Chart mode" },
+            mode: { type: "string", enum: ALL_MODES, description: "Chart mode" },
         },
         required: ["house_number"],
     },
@@ -625,14 +785,19 @@ registerTool({
         const signFlavor = sign
             ? `\n\n${capitalize(sign)} on this cusp emphasizes ${SIGN_HOUSE_FLAVOR[sign.toLowerCase()] ?? "its natural qualities"} in the matters of this house.`
             : "";
-        const modeNote = mode === "transit"
-            ? "\n\nWatch for transiting planets moving through this house — they will activate and bring events related to these life areas during their passage."
-            : "\n\nIn synastry, planets from the outer chart falling in this house create experiences related to these themes in the relationship — often powerfully felt by the person whose house is being activated.";
+        const HOUSE_MODE_NOTES = {
+            synastry: "\n\nIn synastry, planets from the outer natal chart falling in this house create experiences related to these themes in the relationship — often powerfully felt by the person whose house is being activated.",
+            transit: "\n\nWatch for transiting planets moving through this house — they will activate and bring events related to these life areas during their passage.",
+            progressed: "\n\nAs progressed planets move through this house, they gradually shift the inner developmental focus toward these life themes. Natal house boundaries mark important life-chapter transitions in secondary progression work.",
+            solar_arc: "\n\nSolar arc directed planets entering this house signal a new chapter of life experience in these domains. The ingress year often corresponds to a major shift in the themes of this house.",
+            solar_return: "\n\nPlanets in this house in the solar return chart will be emphasised life areas for the coming year. A concentration of solar return planets here intensifies activity and attention in this domain.",
+            lunar_return: "\n\nPlanets in this house in the lunar return chart highlight the month's dominant emotional themes and practical focus areas. The lunar return ascendant and its house emphasis set the tone for the entire lunar cycle.",
+        };
         return {
             content: [{
                     type: "text",
                     text: `**House ${num}${sign ? ` — ${capitalize(sign)} on the cusp` : ""}** *(Inner Natal Wheel)*\n\n` +
-                        meaning + signFlavor + modeNote,
+                        meaning + signFlavor + HOUSE_MODE_NOTES[mode],
                 }],
         };
     },
@@ -648,9 +813,9 @@ registerTool({
     inputSchema: {
         type: "object",
         properties: {
-            mode: { type: "string", enum: ["synastry", "transit"], description: "Chart mode" },
-            person1_name: { type: "string", description: "Name or label for the inner wheel (natal/person 1)" },
-            person2_name: { type: "string", description: "Name or label for the outer wheel (synastry person 2 or transit date)" },
+            mode: { type: "string", enum: ALL_MODES, description: "Chart mode" },
+            person1_name: { type: "string", description: "Name or label for the inner wheel (natal / person 1)" },
+            person2_name: { type: "string", description: "Name or label for the outer wheel (person 2, transit date, progression target, etc.)" },
             cross_aspects: {
                 type: "array",
                 description: "Array of cross-aspects from the bi-wheel payload (up to 30, sorted by orb)",
@@ -673,8 +838,9 @@ registerTool({
     _meta: { ui: { resourceUri: BI_WHEEL_RESOURCE_URI, visibility: ["app", "model"] } },
     handler: async (args) => {
         const mode = args.mode ?? "synastry";
-        const label1 = args.person1_name ? String(args.person1_name) : (mode === "transit" ? "Natal Chart" : "Person 1");
-        const label2 = args.person2_name ? String(args.person2_name) : (mode === "transit" ? "Transits" : "Person 2");
+        const meta = MODE_META[mode];
+        const label1 = args.person1_name ? String(args.person1_name) : meta.innerRole;
+        const label2 = args.person2_name ? String(args.person2_name) : meta.outerRole;
         const topN = args.top_n ? Number(args.top_n) : 8;
         const rawAspects = args.cross_aspects ?? [];
         const aspects = rawAspects.slice(0, topN);
@@ -684,36 +850,55 @@ registerTool({
         const harmonious = aspects.filter((a) => ["trine", "sextile"].includes((a.aspect_type ?? a.type ?? "").toLowerCase()));
         const dynamic = aspects.filter((a) => ["square", "opposition"].includes((a.aspect_type ?? a.type ?? "").toLowerCase()));
         const fusing = aspects.filter((a) => (a.aspect_type ?? a.type ?? "").toLowerCase() === "conjunction");
+        // For time-based modes, show applying/separating; for relational modes show tightness
+        const isTimeBased = mode !== "synastry";
         const lines = aspects.map((ca) => {
             const type = ca.aspect_type ?? ca.type ?? "aspect";
             const sym = ASPECT_SYM[type.toLowerCase()] ?? type;
-            const dir = mode === "transit"
+            const dir = isTimeBased
                 ? (ca.applying ? "↗ applying" : "↘ separating")
                 : (ca.orb <= 1 ? "exact" : ca.orb <= 3 ? "tight" : "wide");
             return `• ${capitalize(ca.planet1)} ${sym} ${capitalize(ca.planet2)} (${ca.orb.toFixed(1)}° — ${dir})`;
         });
-        const themeSummary = mode === "synastry"
-            ? [
-                fusing.length > 0 ? `**${fusing.length} conjunction${fusing.length > 1 ? "s" : ""}** — areas of deep merging and fusion between the two charts.` : "",
-                harmonious.length > 0 ? `**${harmonious.length} flowing aspect${harmonious.length > 1 ? "s" : ""}** (trines/sextiles) — natural ease, support, and compatibility.` : "",
-                dynamic.length > 0 ? `**${dynamic.length} dynamic aspect${dynamic.length > 1 ? "s" : ""}** (squares/oppositions) — areas of growth, friction, and mutual challenge.` : "",
-            ].filter(Boolean).join("\n")
-            : [
-                fusing.length > 0 ? `**${fusing.length} conjunction${fusing.length > 1 ? "s" : ""}** — direct activation of natal points; peak transit influence.` : "",
-                harmonious.length > 0 ? `**${harmonious.length} flowing transit${harmonious.length > 1 ? "s" : ""}** — periods of ease, opportunity, and support.` : "",
-                dynamic.length > 0 ? `**${dynamic.length} challenging transit${dynamic.length > 1 ? "s" : ""}** — active pressure points requiring conscious engagement.` : "",
-            ].filter(Boolean).join("\n");
-        const intro = mode === "synastry"
-            ? `**Synastry Overview: ${label1} × ${label2}**\n\nThis synastry bi-wheel compares two natal charts to reveal the dynamics of interaction and connection between these two individuals. The cross-aspects show how their planetary energies align, challenge, and transform each other.`
-            : `**Transit Overview: ${label1} × ${label2}**\n\nThis transit bi-wheel overlays current planetary positions onto the natal chart, revealing which natal points are being activated right now and the nature of those influences.`;
+        // Theme summary copy varies by mode
+        const synastryTheme = [
+            fusing.length > 0 ? `**${fusing.length} conjunction${fusing.length > 1 ? "s" : ""}** — areas of deep merging and fusion between the two charts.` : "",
+            harmonious.length > 0 ? `**${harmonious.length} flowing aspect${harmonious.length > 1 ? "s" : ""}** (trines/sextiles) — natural ease, support, and compatibility.` : "",
+            dynamic.length > 0 ? `**${dynamic.length} dynamic aspect${dynamic.length > 1 ? "s" : ""}** (squares/oppositions) — areas of growth, friction, and mutual challenge.` : "",
+        ].filter(Boolean).join("\n");
+        const timeBasedTheme = [
+            fusing.length > 0 ? `**${fusing.length} conjunction${fusing.length > 1 ? "s" : ""}** — direct activation of natal points; peak influence for this ${meta.modeLabel.toLowerCase()}.` : "",
+            harmonious.length > 0 ? `**${harmonious.length} flowing aspect${harmonious.length > 1 ? "s" : ""}** (trines/sextiles) — periods of ease, opportunity, and natural support.` : "",
+            dynamic.length > 0 ? `**${dynamic.length} dynamic aspect${dynamic.length > 1 ? "s" : ""}** (squares/oppositions) — active pressure points requiring conscious engagement.` : "",
+        ].filter(Boolean).join("\n");
+        const themeSummary = mode === "synastry" ? synastryTheme : timeBasedTheme;
+        const SYNOPSIS_INTRO = {
+            synastry: `**Synastry Overview: ${label1} × ${label2}**\n\n` +
+                `This synastry bi-wheel compares two natal charts to reveal the dynamics of interaction and connection between these two individuals. The cross-aspects show how their planetary energies align, challenge, and transform each other.`,
+            transit: `**Transit Overview: ${label1} × ${label2}**\n\n` +
+                `This transit bi-wheel overlays current planetary positions onto the natal chart, revealing which natal points are being activated right now and the nature of those influences.`,
+            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.`,
+            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` +
+                `This lunar return bi-wheel compares the natal chart against the lunar return. The outer ring shows planetary positions when the Moon returned to its natal degree, setting the emotional tone and circumstantial focus of the coming lunar month.`,
+        };
+        const SYNOPSIS_CLOSING = {
+            synastry: "\n\nClick any planet or aspect line in the bi-wheel for a deeper interpretation of individual connections.",
+            transit: "\n\nClick any planet or cross-aspect line for a detailed transit interpretation. Navigate the date forward or backward using the step controls to track how transits evolve.",
+            progressed: "\n\nClick any progressed planet or cross-aspect line for a detailed interpretation. The most significant turning points occur when a progressed planet reaches exactitude with a natal planet or angle.",
+            solar_arc: "\n\nClick any directed planet or cross-aspect line for interpretation. Solar arc contacts to natal angles (ASC, MC, IC, DSC) are among the most powerful triggers in predictive astrology.",
+            solar_return: "\n\nClick any solar return planet or cross-aspect line for interpretation. The solar return ascendant and its ruler are the master theme-setters for the year.",
+            lunar_return: "\n\nClick any lunar return planet or cross-aspect line for interpretation. The lunar return Moon's house placement describes this month's emotional centre of gravity.",
+        };
         const body = lines.length > 0
             ? `\n\n**Top Cross-Aspects by Orb:**\n${lines.join("\n")}\n\n**Thematic Summary:**\n${themeSummary || "No major aspects within standard orbs."}`
             : "\n\nNo major cross-aspects are within orb at this time.";
-        const closing = mode === "synastry"
-            ? "\n\nClick any planet or aspect line in the bi-wheel for a deeper interpretation of individual connections."
-            : "\n\nClick any planet or cross-aspect line for a detailed transit interpretation. Navigate the date forward or backward using the step controls to track how transits evolve.";
         return {
-            content: [{ type: "text", text: intro + body + closing }],
+            content: [{ type: "text", text: SYNOPSIS_INTRO[mode] + body + SYNOPSIS_CLOSING[mode] }],
         };
     },
 });