@openephemeris/mcp-server 3.13.7 → 3.13.8

package/README.md

@@ -355,8 +355,8 @@ Generated by `npm run sync:readme` from `config/dev-allowlist.json` and the live
 
 - Allowlisted operations: **28**
 - Methods: `GET=4`, `POST=24`, `PUT=0`, `PATCH=0`, `DELETE=0`
-- Registered tools (`OPENEPHEMERIS_PROFILE=dev`): **64**
-- Typed tools: `acg_hits`, `acg_power_lines`, `auth_login`, `auth_logout`, `auth_status`, `bi_wheel_on_cross_aspect_click`, `bi_wheel_on_planet_click`, `chart_wheel_on_aspect_click`, `chart_wheel_on_house_click`, `chart_wheel_on_planet_click`, `chart_wheel_recalculate`, `chinese_bazi`, `dev_call`, `dev_list_allowed`, `electional_aspect_search`, `electional_moment_analysis`, `electional_station_tracker`, `ephemeris_angles_points`, `ephemeris_aspect_check`, `ephemeris_bi_wheel`, `ephemeris_chart_wheel`, `ephemeris_composite`, `ephemeris_composite_midpoint`, `ephemeris_dignities`, `ephemeris_electional`, `ephemeris_fixed_stars`, `ephemeris_hermetic_lots`, `ephemeris_house_cusps`, `ephemeris_lunar_return`, `ephemeris_midpoints`, `ephemeris_moon_phase`, `ephemeris_natal_batch`, `ephemeris_natal_chart`, `ephemeris_natal_transits`, `ephemeris_next_eclipse`, `ephemeris_next_lunar_phase`, `ephemeris_overlay`, `ephemeris_planet_position`, `ephemeris_planetary_return`, `ephemeris_progressed_chart`, `ephemeris_relocation`, `ephemeris_retrograde_status`, `ephemeris_solar_return`, `ephemeris_synastry`, `ephemeris_transits`, `explore_bi_wheel`, `explore_human_design`, `explore_natal_chart`, `hd_on_center_click`, `hd_on_channel_click`, `hd_on_gate_click`, `hd_opposition`, `hd_planetary_return`, `human_design_bodygraph`, `human_design_chart`, `human_design_composite`, `human_design_penta`, `vedic_chart`, `venus_eight_year_star`, `venus_elongations`, `venus_phase`, `venus_star_points`, `venus_star_points_conjunctions`, `venus_stations`
+- Registered tools (`OPENEPHEMERIS_PROFILE=dev`): **72**
+- Typed tools: `acg_hits`, `acg_power_lines`, `auth_login`, `auth_logout`, `auth_status`, `bi_wheel_on_cross_aspect_click`, `bi_wheel_on_house_click`, `bi_wheel_on_planet_click`, `bi_wheel_recalculate`, `bi_wheel_synopsis`, `bodygraph_recalculate`, `chart_wheel_on_aspect_click`, `chart_wheel_on_house_click`, `chart_wheel_on_planet_click`, `chart_wheel_recalculate`, `chinese_bazi`, `dev_call`, `dev_list_allowed`, `electional_aspect_search`, `electional_moment_analysis`, `electional_station_tracker`, `ephemeris_angles_points`, `ephemeris_aspect_check`, `ephemeris_bi_wheel`, `ephemeris_chart_wheel`, `ephemeris_composite`, `ephemeris_composite_midpoint`, `ephemeris_dignities`, `ephemeris_electional`, `ephemeris_fixed_stars`, `ephemeris_hermetic_lots`, `ephemeris_house_cusps`, `ephemeris_lunar_return`, `ephemeris_midpoints`, `ephemeris_moon_phase`, `ephemeris_natal_batch`, `ephemeris_natal_chart`, `ephemeris_natal_transits`, `ephemeris_next_eclipse`, `ephemeris_next_lunar_phase`, `ephemeris_overlay`, `ephemeris_planet_position`, `ephemeris_planetary_return`, `ephemeris_progressed_chart`, `ephemeris_relocation`, `ephemeris_retrograde_status`, `ephemeris_solar_return`, `ephemeris_synastry`, `ephemeris_transits`, `explore_bi_wheel`, `explore_human_design`, `explore_natal_chart`, `hd_on_center_click`, `hd_on_channel_click`, `hd_on_gate_click`, `hd_on_planet_click`, `hd_on_variable_click`, `hd_opposition`, `hd_planetary_return`, `human_design_bodygraph`, `human_design_chart`, `human_design_composite`, `human_design_penta`, `location_search`, `timezone_resolve`, `vedic_chart`, `venus_eight_year_star`, `venus_elongations`, `venus_phase`, `venus_star_points`, `venus_star_points_conjunctions`, `venus_stations`
 - Generic tools: 
 
 ### Allowlist Families

package/dist/backend/client.js

@@ -15,7 +15,7 @@ const BINARY_ENDPOINT_PREFIXES = [
 ];
 const DASHBOARD_ACCOUNT_URL = "https://openephemeris.com/dashboard?tab=account";
 const LOGIN_SIGNUP_URL = "https://openephemeris.com/login?signup=true&redirect=%2Fdashboard%3Ftab%3Daccount";
-const UPGRADE_URL = "https://openephemeris.com/pay";
+const UPGRADE_URL = "https://openephemeris.com/pricing";
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -251,18 +251,36 @@ export class BackendClient {
                     `or set OPENEPHEMERIS_API_KEY in your MCP server config.`, 401, "auth_required", false, LOGIN_SIGNUP_URL);
             }
             if (status === 402) {
+                const dataObj = data && typeof data === "object" ? data : {};
+                const walletUrl = dataObj.upgrade?.wallets_url || "https://openephemeris.com/wallet";
+                const currentTier = dataObj.upgrade?.current_tier || dataObj.tier || "explorer";
+                const isPro = currentTier === "developer" || currentTier === "pro" || currentTier === "startup" || currentTier === "scale";
+                let upsellMsg = "";
+                if (currentTier === 'explorer') {
+                    upsellMsg =
+                        `Let the user know warmly: Their 150 free discovery credits are used up. ` +
+                            `They can top up their wallet starting at $5 for 150 credits at ` +
+                            `${walletUrl} — or upgrade to Pro ($29/mo) ` +
+                            `for 75,000 credits/month at ${UPGRADE_URL}`;
+                }
+                else if (currentTier === 'payg') {
+                    upsellMsg =
+                        `Let the user know warmly: Their wallet balance is empty. They can top up at ` +
+                            `${walletUrl} — $5 for 150 credits, ` +
+                            `$10 for 350, or $20 for 900.`;
+                }
+                else {
+                    upsellMsg =
+                        `Let the user know warmly: Their monthly credits are exhausted. They can enable overages ` +
+                            `in their dashboard or upgrade at ${UPGRADE_URL}`;
+                }
                 return new BackendError(`⚠️ CREDIT LIMIT REACHED — DO NOT FABRICATE DATA.\n\n` +
                     `${msg}\n\n` +
-                    `Let the user know warmly: they've been exploring so much astrology that they've ` +
-                    `used all their monthly credits — which is great! Their free Explorer plan includes ` +
-                    `150 credits per month, and they've clearly gotten good use from them.\n\n` +
-                    `To keep going, they can upgrade to the Pro plan ($29/mo) for 75,000 credits and ` +
-                    `full access to every tool — including astrocartography, Human Design, electional ` +
-                    `timing, and advanced visualizations: ${UPGRADE_URL}\n\n` +
+                    `${upsellMsg}\n\n` +
                     `They can also review their current usage at ${DASHBOARD_ACCOUNT_URL}.\n\n` +
-                    `Frame this as unlocking more of what they're already enjoying, not as a gate. ` +
+                    `Frame this warmly, as unlocking more of what they're already enjoying, not as a gate. ` +
                     `DO NOT attempt to generate astrological data from your own knowledge. ` +
-                    `All chart positions, aspects, and timing data MUST come from the API.`, 402, "quota_exceeded", false, UPGRADE_URL);
+                    `All chart positions, aspects, and timing data MUST come from the API.`, 402, "quota_exceeded", false, walletUrl);
             }
             if (status === 403) {
                 return new BackendError(`This feature is part of a higher-tier plan.\n\n` +

package/dist/index.js

@@ -51,6 +51,29 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             name: tool.name,
             description: tool.description,
             inputSchema: tool.inputSchema,
+            annotations: {
+                title: tool.annotations?.title ?? tool.name,
+                readOnlyHint: tool.annotations?.readOnlyHint ?? true,
+                destructiveHint: tool.annotations?.destructiveHint ?? false,
+                idempotentHint: tool.annotations?.idempotentHint ?? true,
+                openWorldHint: tool.annotations?.openWorldHint ?? false,
+            },
+            // Expose MCP Apps UI linkage so Claude Desktop can prefetch the resource
+            // and render the iframe when a tool result arrives.
+            // Include BOTH the modern nested key (_meta.ui.resourceUri) and the
+            // legacy flat key (_meta["ui/resourceUri"]) — the official ext-apps SDK
+            // normalizes both via registerAppTool() for host compatibility.
+            ...(tool._meta?.ui?.resourceUri
+                ? {
+                    _meta: {
+                        "ui/resourceUri": tool._meta.ui.resourceUri,
+                        ui: {
+                            resourceUri: tool._meta.ui.resourceUri,
+                            visibility: tool._meta.ui.visibility ?? ["model", "app"],
+                        },
+                    },
+                }
+                : {}),
         })),
     };
 });

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

@@ -137,7 +137,7 @@ function normalizePlanets(raw) {
             speed: (p.longitude_speed ?? p.speed),
             retrograde: Boolean(p.is_retrograde ?? p.retrograde),
             sign: (p.sign_name ?? p.sign),
-            house: p.house,
+            house: (p.house_number ?? p.house),
         }));
     }
     return [];
@@ -145,6 +145,12 @@ function normalizePlanets(raw) {
 function normalizeHouses(raw) {
     if (Array.isArray(raw))
         return raw;
+    if (raw && typeof raw === "object" && "cusps" in raw && Array.isArray(raw.cusps)) {
+        return raw.cusps.map((cusp, i) => ({
+            number: i + 1,
+            cusp_lon: cusp,
+        }));
+    }
     return [];
 }
 // ── Payload builder ────────────────────────────────────────────────────────────
@@ -306,6 +312,7 @@ registerTool({
                     { type: "text", text: JSON.stringify({ ...payload, server_version: SERVER_VERSION }) },
                 ],
                 _meta: {
+                    "ui/resourceUri": BI_WHEEL_RESOURCE_URI,
                     ui: { resourceUri: BI_WHEEL_RESOURCE_URI },
                 },
             };
@@ -314,6 +321,74 @@ registerTool({
         return { content: [{ type: "text", text: summary }] };
     },
 });
+// ── Tool: bi_wheel_recalculate ──────────────────────────────────────────────
+registerTool({
+    name: "bi_wheel_recalculate",
+    description: "Recalculates a bi-wheel chart (synastry, transit, or progressed mode) with new parameters.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            mode: { type: "string", enum: ["synastry", "transit", "progressed"] },
+            person1_datetime: { type: "string" },
+            person1_latitude: { type: "number" },
+            person1_longitude: { type: "number" },
+            person1_timezone: { type: "string" },
+            person1_name: { type: "string" },
+            person2_datetime: { type: "string" },
+            person2_latitude: { type: "number" },
+            person2_longitude: { type: "number" },
+            person2_timezone: { type: "string" },
+            person2_name: { type: "string" },
+            location: { type: "string" }, // fallback
+        },
+        required: ["mode", "person1_datetime", "person1_latitude", "person1_longitude", "person2_datetime"],
+    },
+    annotations: { title: "Recalculate Bi-Wheel", readOnlyHint: true, openWorldHint: false },
+    _meta: { ui: { resourceUri: BI_WHEEL_RESOURCE_URI, visibility: ["app"] } },
+    handler: async (args) => {
+        const client = getActiveClient();
+        const mode = args.mode ?? "synastry";
+        const dt1 = String(args.person1_datetime);
+        const lat1 = args.person1_latitude;
+        const lon1 = args.person1_longitude;
+        const tz1 = args.person1_timezone;
+        const dt2 = String(args.person2_datetime);
+        const lat2 = args.person2_latitude;
+        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 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);
+        return {
+            content: [{ type: "text", text: JSON.stringify({ ...payload, server_version: SERVER_VERSION }) }],
+        };
+    },
+});
 // ── Tool: bi_wheel_on_cross_aspect_click ──────────────────────────────────────
 registerTool({
     name: "bi_wheel_on_cross_aspect_click",
@@ -416,42 +491,229 @@ const PLANET_THEMES = {
     mc: "public vocation, highest ambition, and the world's face; the pinnacle of achievement this person strives toward",
 };
 const HOUSE_AREAS = {
-    1: "self and identity", 2: "values and resources",
-    3: "communication", 4: "home and roots",
-    5: "creativity and joy", 6: "work and health",
-    7: "partnerships", 8: "shared depth and transformation",
-    9: "beliefs and expansion", 10: "career and public life",
-    11: "community and hopes", 12: "solitude and the unconscious",
+    1: "self, appearance, and first impressions",
+    2: "money, material values, and personal resources",
+    3: "communication, siblings, and local environment",
+    4: "home, family, roots, and emotional foundations",
+    5: "creativity, romance, children, and pleasure",
+    6: "work, health, routines, and service",
+    7: "partnerships, marriage, and close one-on-one relationships",
+    8: "transformation, shared resources, sexuality, and the depths",
+    9: "philosophy, higher education, long travel, and belief",
+    10: "career, public reputation, and life calling",
+    11: "friendships, groups, collective causes, and long-term hopes",
+    12: "solitude, the unconscious, hidden matters, and spiritual retreat",
+};
+const HOUSE_MEANINGS = {
+    1: "The 1st house governs identity, appearance, and how we project ourselves into the world. In synastry, planets here from the outer wheel can reshape how this person is perceived or how they see themselves.",
+    2: "The 2nd house governs personal values, self-worth, and material security. Synastry or transit planets here trigger questions around money, possessions, and what one truly values.",
+    3: "The 3rd house governs communication, learning, short journeys, and the immediate environment. Planets here stimulate the mind, increase dialogue, and sharpen or soften communication.",
+    4: "The 4th house (IC) governs the home, family, ancestry, and emotional foundations. This is the most private sector of the chart — planets here reach deep into the inner life.",
+    5: "The 5th house governs creativity, romance, play, and children. Synastry planets here light up pleasure-seeking, creative collaboration, and romantic sparks.",
+    6: "The 6th house governs work, health, and daily rhythm. Planets here affect how one shows up day-to-day — discipline, habits, service, and the body.",
+    7: "The 7th house (Descendant) governs committed partnerships. Planets here activate relationship patterns — the qualities we project onto partners or seek in them.",
+    8: "The 8th house governs deep transformation, shared finances, intimacy, and taboo. Planets here create intense, soul-level connections or power dynamics that cannot be ignored.",
+    9: "The 9th house governs worldview, higher learning, travel, and spiritual quest. Planets here expand perspective, challenge beliefs, and open new intellectual horizons.",
+    10: "The 10th house (Midheaven) governs career, public life, and legacy. Planets here can profoundly affect one's sense of purpose and how the outer world recognizes them.",
+    11: "The 11th house governs friends, networks, social causes, and future visions. Planets here energize collective activity, shared ideals, and the aspiration toward belonging.",
+    12: "The 12th house governs the unconscious, hidden matters, solitude, and spiritual development. Planets here work in subtle and sometimes invisible ways — potent but beneath the surface.",
 };
-function interpretBiWheelPlanet(planet, sign, house, wheel, retrograde = false) {
+const SIGN_QUALITIES = {
+    aries: "directness, initiative, and pioneering courage",
+    taurus: "steady determination, sensory pleasure, and practical patience",
+    gemini: "curiosity, adaptability, and intellectual versatility",
+    cancer: "emotional depth, nurturing instincts, and protective sensitivity",
+    leo: "bold self-expression, generosity, and regal confidence",
+    virgo: "precision, discernment, and devoted service to improvement",
+    libra: "harmony-seeking, relational grace, and aesthetic refinement",
+    scorpio: "intense focus, emotional depth, and transformative power",
+    sagittarius: "philosophical expansiveness, optimism, and adventurous seeking",
+    capricorn: "disciplined ambition, structural mastery, and long-term commitment",
+    aquarius: "innovative originality, humanitarian vision, and detached idealism",
+    pisces: "compassionate empathy, spiritual receptivity, and imaginative flow",
+};
+const SIGN_HOUSE_FLAVOR = {
+    aries: "initiative and directness", taurus: "patience and material stability",
+    gemini: "intellectual curiosity and communication", cancer: "emotional nurturing and memory",
+    leo: "creative expression and leadership", virgo: "analytical precision and service",
+    libra: "balance and relationship dynamics", scorpio: "depth, intensity, and transformation",
+    sagittarius: "expansion and philosophical seeking", capricorn: "discipline, structure, and achievement",
+    aquarius: "innovation, groups, and humanitarian ideals", pisces: "compassion, dreams, and dissolution of boundaries",
+};
+function interpretBiWheelPlanet(planet, sign, house, wheel, retrograde = false, mode = "synastry") {
     const theme = PLANET_THEMES[planet.toLowerCase()] ?? "a deep archetypal force";
-    const houseCtx = house ? ` This energy operates in the sphere of ${HOUSE_AREAS[house] ?? "life experience"}.` : "";
+    const signQuality = SIGN_QUALITIES[sign.toLowerCase()] ?? "the qualities of this sign";
+    const houseCtx = house ? ` This energy is active in the **${ordinal(house)} house** — the sphere of ${HOUSE_AREAS[house] ?? "life experience"}.` : "";
     const retroCtx = retrograde
-        ? ` Note: this planet is **retrograde** — its energy tends to be more internalized, reflective, or nonconforming in its expression.`
+        ? ` Note: this planet is **retrograde** ℞ — its energy turns inward; themes are more private, reflective, and may require more deliberate integration before they can be expressed outward.`
         : "";
-    const wheelCtx = wheel === "inner"
-        ? "This is a **natal planet** — a core, stable part of this person's identity."
-        : "This is an **outer planet** — a transiting or synastry energy currently activating the inner wheel.";
-    return (`${capitalize(planet)} represents ${theme}. In ${capitalize(sign)}, this energy is expressed through the qualities of that sign.${houseCtx}${retroCtx}\n\n${wheelCtx}`);
+    if (wheel === "inner") {
+        return (`**Natal Planet:** ${capitalize(planet)} represents ${theme}. In ${capitalize(sign)}, this energy flows through ${signQuality}.${houseCtx}${retroCtx}\n\n` +
+            `This is a **core natal placement** — a stable, defining feature of this person's chart. It shows how ${capitalize(planet)}'s themes are wired into their fundamental nature.`);
+    }
+    else if (mode === "transit") {
+        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 {
+        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.`);
+    }
 }
 const CROSS_ASPECT_NATURE = {
-    conjunction: "creates a powerful merging of these two planetary energies across the chart boundary. What one person (or the natal chart) embodies, the other amplifies — this can feel fated, intense, and highly activating.",
-    opposition: "creates a magnetic pull-and-push dynamic. The two energies are drawn to each other yet challenge each other to grow. In synastry, this often manifests as fascination and tension; in transit, as external pressure to integrate.",
-    trine: "creates an easy, harmonious flow of energy between the two charts. This aspect supports mutual understanding, natural rapport, and a sense of ease — gifts arrive without much effort.",
-    square: "creates productive friction between the two charts. Growth and evolution are required. In synastry, this generates passion and drive; in transit, it signals action and adjustment.",
-    sextile: "creates a gentle, supportive connection that rewards intentional effort. Opportunities arise where these two energies meet, but initiative is needed to activate them fully.",
+    conjunction: {
+        synastry: "creates a powerful merging of these two planetary energies across both charts. What one person embodies, the other amplifies — this can feel fated, magnetic, and highly activating. The themes of both planets fuse and are difficult to separate.",
+        transit: "marks a moment of direct activation. The transiting planet sits exactly upon a natal planet, amplifying its themes with full force. This is often experienced as an event, a catalytic encounter, or a decisive shift in awareness.",
+    },
+    opposition: {
+        synastry: "creates a magnetic polarity across the chart boundary. The two energies are drawn to each other yet challenge integration — each person may embody qualities the other both desires and finds difficult. Fascination and tension coexist.",
+        transit: "brings an external pressure that demands integration. The transiting planet opposes a natal point, often projecting themes outward through encounters, relationships, or confrontations that mirror what needs to be balanced internally.",
+    },
+    trine: {
+        synastry: "creates an easy, harmonious flow between the two charts. Natural rapport, ease of connection, and effortless support arise where these themes meet. This feels comfortable — even familiar — often from the very first interaction.",
+        transit: "brings a period of natural ease and opportunity. The themes of the transiting planet flow harmoniously into the natal point — doors open, situations resolve with less effort, and the native feels supported by outer circumstances.",
+    },
+    square: {
+        synastry: "creates productive friction between the two charts. Life together requires growth and adjustment. This dynamic generates passion and drive, but also tension that must be consciously worked with rather than avoided. The reward is mutual evolution.",
+        transit: "signals a call to action. Current circumstances are pressing against a natal point, requiring adjustment, decision, or effort. Discomfort is the teacher here — the square challenges, but in doing so, builds capacity and strength.",
+    },
+    sextile: {
+        synastry: "creates a gentle, supportive connection that rewards intentional effort. The ease is more subtle than a trine, but the potential for growth is real. Collaboration, mutual curiosity, and opening to new shared possibilities arise here.",
+        transit: "brings a period of opportunity that rewards initiative. The transiting planet offers a supportive opening — but unlike a trine, it requires the native to consciously engage and take action rather than simply receiving.",
+    },
 };
 function interpretCrossAspect(p1, p2, type, applying, mode) {
-    const nature = CROSS_ASPECT_NATURE[type.toLowerCase()] ?? "creates a notable connection across the two charts.";
+    const natures = CROSS_ASPECT_NATURE[type.toLowerCase()];
+    const nature = natures
+        ? (mode === "transit" ? natures.transit : natures.synastry)
+        : "creates a notable connection across the two charts.";
     let timing;
     if (mode === "transit") {
         timing = applying
-            ? "This aspect is **applying** — its influence is building and moving toward maximum expression."
-            : "This aspect is **separating** — its peak has passed; integration of its themes is underway.";
+            ? "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 {
-        // In synastry, both charts are frozen — applying/separating has no temporal meaning.
-        timing = "As a synastry aspect, this connection exists as a permanent feature of this relationship dynamic — neither building nor fading, but always present as a foundational thread between these two charts.";
+        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.";
     }
     return (`The ${type} between ${capitalize(p1)} and ${capitalize(p2)} ${nature}\n\n${timing}`);
 }
+// ── Tool: bi_wheel_on_house_click ─────────────────────────────────────────────
+registerTool({
+    name: "bi_wheel_on_house_click",
+    description: "Event handler called when the user clicks a house cusp in the inner wheel of the bi-wheel chart. " +
+        "Returns the meaning of that house in the context of synastry or transit — what life area it governs " +
+        "and how outer planets activating it tend to manifest. " +
+        "This tool is called automatically by the bi-wheel UI; you do not need to call it directly.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            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" },
+        },
+        required: ["house_number"],
+    },
+    annotations: { title: "Bi-Wheel House Interpretation", readOnlyHint: true, openWorldHint: false },
+    _meta: { ui: { resourceUri: BI_WHEEL_RESOURCE_URI, visibility: ["app"] } },
+    handler: async (args) => {
+        const num = Number(args.house_number);
+        const sign = args.sign ? String(args.sign) : "";
+        const mode = args.mode ?? "synastry";
+        const meaning = HOUSE_MEANINGS[num] ?? `The ${ordinal(num)} house governs a distinct area of lived experience.`;
+        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.";
+        return {
+            content: [{
+                    type: "text",
+                    text: `**House ${num}${sign ? ` — ${capitalize(sign)} on the cusp` : ""}** *(Inner Natal Wheel)*\n\n` +
+                        meaning + signFlavor + modeNote,
+                }],
+        };
+    },
+});
+// ── Tool: bi_wheel_synopsis ────────────────────────────────────────────────────
+registerTool({
+    name: "bi_wheel_synopsis",
+    description: "Generate a master-astrologer-grade overview of the entire bi-wheel configuration — " +
+        "summarising the mode (synastry or transit), key cross-aspects by quality, dominant themes, " +
+        "stationing or slow-moving outer planet influences, and an interpretive narrative. " +
+        "Use this when the user asks for a full reading, a relationship overview, or a transit overview " +
+        "rather than clicking a specific element. Accepts the cross-aspect data from the chart payload.",
+    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)" },
+            cross_aspects: {
+                type: "array",
+                description: "Array of cross-aspects from the bi-wheel payload (up to 30, sorted by orb)",
+                items: {
+                    type: "object",
+                    properties: {
+                        planet1: { type: "string" },
+                        planet2: { type: "string" },
+                        aspect_type: { type: "string" },
+                        orb: { type: "number" },
+                        applying: { type: "boolean" },
+                    },
+                },
+            },
+            top_n: { type: "number", description: "Number of top aspects to highlight (default 8)" },
+        },
+        required: ["mode"],
+    },
+    annotations: { title: "Bi-Wheel Synopsis", readOnlyHint: true, openWorldHint: false },
+    _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 topN = args.top_n ? Number(args.top_n) : 8;
+        const rawAspects = args.cross_aspects ?? [];
+        const aspects = rawAspects.slice(0, topN);
+        const ASPECT_SYM = {
+            conjunction: "☌", opposition: "☍", trine: "△", square: "□", sextile: "⚹",
+        };
+        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");
+        const lines = aspects.map((ca) => {
+            const type = ca.aspect_type ?? ca.type ?? "aspect";
+            const sym = ASPECT_SYM[type.toLowerCase()] ?? type;
+            const dir = mode === "transit"
+                ? (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.`;
+        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 }],
+        };
+    },
+});