ether-to-astro 1.0.2 → 1.2.0

package/docs/product/product-tenets.md

@@ -0,0 +1,174 @@
+# Product Tenets
+
+This document defines what `ether-to-astro` is, what it is not, and how we avoid turning the MCP surface into a muddy bundle of personalized workflow logic.
+
+## Mission
+
+Build a trustworthy astrology computation layer for AI-native workflows.
+
+## North-Star
+
+`ether-to-astro` should provide reliable astrological facts and structured primitives that agents can use to build high-quality experiences without reimplementing astro math client-side.
+
+## Primary Jobs To Be Done
+
+- Compute natal, transit, mundane, and electional astrology data accurately.
+- Expose that data through stable MCP and CLI primitives.
+- Make those primitives composable for skills, prompts, and downstream agent workflows.
+- Preserve clear boundaries between computation, interpretation, and personalization.
+
+## What We Build
+
+- Astrology computation and normalization
+- Reusable primitives for transit and chart workflows
+- Structured outputs that reduce fragile client-side reconstruction
+- Docs and examples that help agents compose the system correctly
+
+## What We Do Not Build
+
+- A monolithic “do everything” astrology assistant inside MCP
+- User-specific advice engines hardcoded into the core surface
+- Prompt-shaped tools that mostly duplicate what a competent LLM can do from stable primitives
+- Endless one-off reporting endpoints for every downstream workflow
+
+## Boundary Rules
+
+### MCP Owns
+
+Put a capability in MCP if it is:
+
+- deterministic or mostly deterministic,
+- computational rather than interpretive,
+- reusable across clients or skills,
+- grounded in astro math, house logic, timezone logic, or ephemeris logic,
+- and difficult or risky to reconstruct client-side.
+
+Examples:
+
+- transit calculation
+- range-aware forecast data
+- mundane aspects
+- house activation metadata
+- electional primitives
+- local rising-sign windows
+
+### Skills Own
+
+Put a capability in a skill if it is:
+
+- mostly synthesis, ranking, or formatting,
+- non-deterministic or heavily dependent on judgment,
+- user-specific or preference-heavy,
+- likely to evolve quickly,
+- and doable by a competent LLM in one or two calls to stable MCP primitives.
+
+Examples:
+
+- daily brief generation
+- weekly overview synthesis
+- opportunity/risk framing
+- “best use today” language
+- electional scoring using a specific user’s preferences
+- preference-aware section ordering and tone
+
+Skill ideas are the default incubation layer for new workflow concepts.
+
+That does not make every skill example in this repo a committed product roadmap item.
+
+Treat skill-layer examples and issue ideas as candidate workflows unless they are explicitly promoted into committed work.
+
+### MCP Prompts Own
+
+Use MCP prompts as thin, discoverable entry points into common workflows.
+
+Prompts may:
+
+- guide clients toward the right tools,
+- provide a reusable public starting point,
+- and expose common report workflows for non-local clients.
+
+Prompts should not:
+
+- become the primary place where product logic lives,
+- duplicate full skill logic,
+- or hardcode personalized heuristics that belong in a skill or profile.
+
+### Profiles Or Preferences Own
+
+Put durable personalization in a profile or preference layer, not in generic MCP tools.
+
+Examples:
+
+- Whole Sign-first reporting
+- timezone defaults
+- preferred electional filters
+- section preferences
+- naming and tagging preferences
+
+## Feature Creep Guardrails
+
+- MCP is for astrological facts, not personalized advice.
+- Deterministic and generic astro computation is a strong candidate for MCP.
+- Determinism alone is not enough; deterministic but opinionated workflow synthesis still belongs in a skill.
+- A new MCP feature must justify why it cannot be cleanly handled by a skill in two calls.
+- Prefer extending an existing tool over adding a new narrowly scoped tool.
+- Do not add user-specific heuristics to MCP.
+- Do not add report-generation tools to MCP unless the output is generic, stable, and broadly reusable.
+- If a feature mixes computation and interpretation, split it.
+  Computation belongs in MCP. Interpretation belongs in a skill.
+
+## Promotion Rule
+
+New workflow ideas should start life as skills or prompts.
+
+That is an incubation step, not an automatic commitment to ship a repo-owned skill or workflow.
+
+They should graduate into MCP only when:
+
+- the computational pattern is stable,
+- multiple workflows need the same primitive,
+- and the client-side implementation would otherwise duplicate fragile astro logic.
+
+## Decision Test
+
+Before adding new MCP surface area, answer these questions:
+
+1. Is this astrological computation or interpretation?
+2. Is the output deterministic or mostly deterministic for the same inputs?
+3. Would two different skills or clients need the same structured output?
+4. Would keeping this outside MCP force astro logic duplication?
+5. Can a competent LLM do this in two calls from existing primitives?
+6. Are we adding a generic primitive, or hardcoding one user’s workflow?
+
+If the output is deterministic, generic, and reusable, prefer MCP.
+
+If a competent LLM can already do it in two calls and the remaining value is mostly synthesis or policy, it probably does not belong in MCP.
+
+## Examples
+
+### Belongs In MCP
+
+- “Return a 7-day forecast grouped by day.”
+- “Return mundane aspects between transiting planets.”
+- “Return which natal and transiting houses are activated.”
+- “Return Moon condition and rising-sign windows for a date and location.”
+- “Add an `include_houses` or `include_mundane_aspects` flag to an existing tool.”
+
+### Belongs In A Skill
+
+- “Write a daily brief with top 3 influences.”
+- “Rank today as clean, mixed, or caution.”
+- “Suggest best uses for work, family, health, and spiritual practice.”
+- “Score electional windows according to one user’s preferred rulers and Mars/Saturn cautions.”
+
+### Does Not Belong
+
+- “Best time for my Google QBR” as a first-class MCP tool
+- one-user reporting tags embedded into tool contracts
+- generic tools whose only job is to produce prose a skill could generate from structured data
+- deterministic but policy-heavy labels like “clean”, “mixed”, or “caution” baked into core tools
+
+## Related Docs
+
+- [Architecture Boundaries](/Users/salted/Code/astro-mcp/docs/product/architecture-boundaries.md)
+- [ADR 0001: MCP Vs Skill Boundary](/Users/salted/Code/astro-mcp/docs/product/adrs/0001-mcp-vs-skill-boundary.md)

package/docs/releases/1.2.0-draft.md

@@ -0,0 +1,48 @@
+# ether-to-astro v1.2.0
+
+Suggested release type: `minor`
+
+This release improves transit forecasting, adds new electional and rising-sign primitives, and tightens a few important MCP and timezone edge cases. 🎉
+
+## 1.2.0 (2026-03-29)
+
+### New feature
+
+- add explicit `snapshot`, `best_hit`, and `forecast` transit modes with day-grouped forecast output
+- add sign, degree, and house metadata directly to transit responses for both transit and natal sides
+- add mundane transit-to-transit aspects and supportive/challenging weather output for date and date-range queries
+- add standalone `get_electional_context` for deterministic electional snapshots without requiring a loaded natal chart 🌙
+- add rising-sign window helpers for date and location queries, with approximate and exact modes ⬆️
+- add deterministic MCP startup defaults for reporting and make `e2a --mcp` the canonical MCP entrypoint
+
+### Bug fix
+
+- keep forecast labels and exact-time rendering aligned with the reporting timezone
+- preserve `e2a-mcp` compatibility behavior when launched through bin shims and wrapper paths
+- reject DST-ambiguous or nonexistent local electional times instead of silently normalizing them
+- fix applying-aspect edge cases in electional context, especially for faster-moving bodies
+
+### Documentation Changes
+
+- update docs and setup guidance around the unified `e2a` CLI and MCP entrypoint
+- add repo-owned workflow skills and skill authoring guidance
+- clarify MCP vs skill product boundaries in repo docs
+
+### ⚙️ Chore
+
+- refresh product governance and contributor guidance for issue triage and release workflow
+
+## Upgrade notes
+
+- prefer `e2a --mcp` for MCP launches
+- `e2a-mcp` remains available as a compatibility alias
+- if you consume transit output programmatically, prefer explicit `mode` values over relying on legacy `days_ahead` behavior
+
+## Included PRs
+
+- #32 add rising-sign window helper
+- #34 add mundane transit-to-transit aspects and weather output
+- #38 unify `e2a` entrypoint for CLI and MCP
+- #40 clarify transit mode contract
+- #41 preserve alias mode and reporting timezone consistency
+- #43 fix electional DST and applying-aspect edge cases

package/package.json

@@ -1,22 +1,22 @@
 {
   "name": "ether-to-astro",
-  "version": "1.0.2",
-  "description": "Local-first astrology toolkit with a CLI (e2a) and MCP server (e2a-mcp) for charts, transits, rendering, and agent workflows.",
+  "version": "1.2.0",
+  "description": "Local-first astrology toolkit with a unified e2a binary for CLI and MCP workflows, plus an e2a-mcp compatibility alias.",
   "type": "module",
   "main": "dist/index.js",
   "engines": {
     "node": ">=22"
   },
   "bin": {
-    "e2a-mcp": "dist/loader.js",
-    "e2a": "dist/cli.js"
+    "e2a": "dist/loader.js",
+    "e2a-mcp": "dist/mcp-alias.js"
   },
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
     "dev:watch": "tsx watch src/loader.ts",
-    "start": "node dist/loader.js",
-    "start:cli": "node dist/cli.js",
+    "start": "node dist/loader.js --mcp",
+    "start:cli": "node dist/loader.js",
     "postinstall": "node scripts/download-ephemeris.js",
     "test": "vitest tests/unit",
     "validate:astro": "vitest run tests/validation",
@@ -58,7 +58,7 @@
     "@vitest/ui": "^4.1.2",
     "happy-dom": "^20.8.9",
     "tsx": "^4.21.0",
-    "typescript": "^5.0.0",
+    "typescript": "^6.0.2",
     "vitest": "^4.1.2"
   }
 }

package/skills/.curated/daily-brief/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: daily-brief
+description: Produce a concise daily astrology brief from ether-to-astro MCP primitives. Use when a user wants today's personal transits and collective weather summarized without turning interpretation into MCP logic.
+metadata:
+  repo: ether-to-astro
+---
+
+# Daily Brief
+
+## Purpose
+Use this skill when a user wants a same-day astrology brief grounded in `ether-to-astro` MCP data.
+
+This skill owns synthesis, ordering, and narrative framing. It does not invent astro facts or encode its own computational logic.
+
+## Inputs
+- A loaded natal chart on the MCP side, or enough birth data to load one first.
+- Date to analyze. Default to today in the reporting timezone if the user does not specify a date.
+- Optional deterministic defaults:
+  - preferred reporting timezone
+  - preferred house style for interpretation
+  - weekday labels on or off
+
+## Required MCP Calls
+1. Call `get_server_status`.
+2. If no natal chart is loaded, either:
+   - call `set_natal_chart` when the user has supplied birth data, or
+   - stop and ask for natal-chart setup.
+3. Call `get_transits` for the target date.
+   Recommended arguments:
+   - `date`
+   - `include_mundane: true`
+   - `categories: ["all"]`
+4. Use additional MCP primitives only when they already exist and materially improve the brief:
+   - house-aware transit metadata
+   - electional context
+   - rising-sign windows
+
+## Workflow
+1. Resolve the target date and reporting timezone.
+2. Retrieve same-day transit data.
+3. Separate the output into:
+   - mundane baseline
+   - personal transit modifiers
+4. Rank or group the results for readability, but keep all rankings clearly skill-side.
+5. Produce a concise brief with explicit references back to the underlying astro facts.
+
+## Output Contract
+- Keep the brief short and practical.
+- Default section order:
+  1. `Overview`
+  2. `Mundane Baseline`
+  3. `Personal Modifiers`
+  4. `Optional Timing Notes`
+- Reference actual astro facts directly:
+  - planets
+  - aspects
+  - sign or house context when available
+  - exact timing only when the MCP result provides it
+- Use weekday labels only when enabled by config or clearly requested by the user.
+- If the available MCP data is incomplete, say so plainly instead of implying precision that is not present.
+
+## Boundaries
+- Do not turn the brief into a new MCP contract.
+- Do not describe ranking labels such as `clean`, `mixed`, or `caution` as deterministic truth.
+- Do not invent house activations, electional windows, or mundane-aspect data when the MCP response does not provide them.
+- Do not use multi-day `get_transits` output as if it were a true day-by-day forecast unless the explicit forecast contract exists.
+
+## Good Patterns
+- Summarize mundane weather first, then describe how natal transits personalize it.
+- Use exact-time notes only when the tool returned them.
+- Prefer a compact brief over exhaustive prose.
+
+## Failure Handling
+- If no natal chart is available, stop and request natal-chart setup.
+- If the MCP surface lacks a needed primitive, explain the missing capability and continue with the best truthful same-day brief possible.

package/skills/.curated/electional-overlay/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: electional-overlay
+description: Add a secondary electional timing overlay to an existing daily or weekly astrology workflow. Use when the user wants timing refinement after the main overview has already been established.
+metadata:
+  repo: ether-to-astro
+---
+
+# Electional Overlay
+
+## Purpose
+Use this skill to add timing refinement after a daily brief or weekly overview already exists.
+
+This skill is not the primary report. It is a secondary overlay that narrows candidate windows using electional primitives.
+
+## Inputs
+- An existing daily brief or weekly overview context.
+- Date, time, or narrowed candidate window to evaluate.
+- Location and timezone for electional checks.
+- Optional deterministic defaults:
+  - preferred reporting timezone
+  - weekday labels on or off
+
+## Required MCP Calls
+Use the smallest useful set of electional primitives available. Preferred surfaces include:
+- a standalone electional-context tool for date/time/location
+- rising-sign windows
+- Moon condition or applying-aspect primitives
+
+If the needed primitives are not available, stop and explain the limitation instead of inventing electional logic.
+
+## Workflow
+1. Start from an already-established overview or brief.
+2. Narrow the timing question to a date or candidate window.
+3. Call electional primitives for that narrowed scope.
+4. Summarize the resulting timing implications as secondary notes.
+
+## Elicitation
+- Ask for missing information only when it materially changes the result.
+- Prefer targeted clarifications over open-ended questions:
+  - date or candidate window
+  - location or timezone
+  - action type, if the user wants timing for a specific kind of action
+- If the user asks for a general timing overlay without enough specificity, ask for the narrowest missing detail needed to make the overlay meaningful.
+
+## Output Contract
+- Keep this as an add-on section, not a full replacement report.
+- Default section order:
+  1. `Timing Window`
+  2. `Electional Signals`
+  3. `Why It Stands Out`
+- Reference the underlying deterministic facts directly.
+- Make confidence and limitations clear when the primitive set is incomplete.
+
+## Boundaries
+- Do not invent electional scoring formulas inside the skill.
+- Do not represent subjective ranking as MCP truth.
+- Do not let asteroids or niche filters dominate unless the user explicitly asks for them.
+- Do not replace the main weekly/daily overview with timing-only analysis.
+
+## Good Patterns
+- Treat electional guidance as optional and secondary.
+- Use explicit time windows when the MCP primitive provides them.
+- Explain why a window is notable using raw signals, not just verdict labels.
+
+## Failure Handling
+- If electional primitives are unavailable, say that timing refinement is limited by the current MCP surface.
+- If the user has not narrowed the timing question enough, ask for the date, window, or location needed for a meaningful overlay.

package/skills/.curated/weekly-overview/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: weekly-overview
+description: Produce a weekly astrology overview from ether-to-astro MCP primitives. Use when a user wants an overview-first planning read that can optionally include secondary electional notes.
+metadata:
+  repo: ether-to-astro
+---
+
+# Weekly Overview
+
+## Purpose
+Use this skill when a user wants a seven-day overview, not just a same-day brief.
+
+This skill is only as strong as the underlying forecast primitives. It must not fake a day-by-day weekly report from lossy MCP data.
+
+## Inputs
+- A loaded natal chart on the MCP side, or enough birth data to load one first.
+- Start date for the weekly window. Default to today in the reporting timezone if unspecified.
+- Optional deterministic defaults:
+  - preferred reporting timezone
+  - preferred house style for interpretation
+  - weekday labels on or off
+
+## Required MCP Calls
+1. Call `get_server_status`.
+2. Ensure a natal chart is loaded before continuing.
+3. Prefer a true range-aware transit forecast primitive when available.
+   Examples:
+   - explicit `forecast` mode on `get_transits`
+   - date-grouped transit forecast output
+   - per-day mundane aspect data
+4. Only use electional primitives as a second pass after the weekly overview exists.
+
+## Workflow
+1. Resolve the weekly window and reporting timezone.
+2. Retrieve week-level transit data using a forecast-capable MCP surface.
+3. Build the overview in this order:
+   - collective weather across the week
+   - notable personal modifiers by day or cluster
+   - optional secondary timing suggestions
+4. Keep recommendations clearly secondary to the overview.
+
+## Elicitation
+- If the user does not provide a start date, default to today in the reporting timezone.
+- If the user appears to mean a calendar week rather than the next seven days, ask for the intended start date or state the assumption clearly.
+- Do not ask extra questions if the overview can proceed truthfully with the default seven-day window.
+
+## Output Contract
+- Default section order:
+  1. `Week Overview`
+  2. `Daily Highlights`
+  3. `Interpretive Lens`
+  4. `Optional Timing Suggestions`
+- `Week Overview` should summarize the overall weather first.
+- `Daily Highlights` should preserve actual day boundaries when the MCP data supports them.
+- `Interpretive Lens` should explain why certain days stand out using referenced astro facts.
+- `Optional Timing Suggestions` should remain clearly secondary and should only appear when supported by MCP primitives.
+
+## Boundaries
+- Do not use current lossy multi-day `get_transits` behavior as if it were a true weekly forecast.
+- If the forecast-capable MCP primitive is missing, say so explicitly and do one of the following:
+  - provide a limited best-hit preview, clearly labeled as such, or
+  - stop and explain that a true weekly overview is not yet supported by the current MCP surface.
+- Do not hardcode personal scoring policy into the contract.
+- Do not move prose generation into MCP.
+
+## Good Patterns
+- Overview first, suggestions second.
+- Mundane baseline first, natal modifiers second.
+- Keep optional electional guidance visibly separate from the main weekly read.
+
+## Failure Handling
+- If no natal chart is loaded, stop and request natal-chart setup.
+- If the forecast primitive is missing, do not synthesize a false weekly report.

package/skills/.system/write-skill/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: write-skill
+description: Write or revise repo-owned SKILL.md files for ether-to-astro. Use when a workflow should become a concrete, compliant skill artifact rather than a broad product narrative.
+metadata:
+  repo: ether-to-astro
+---
+
+# Write Skills For `ether-to-astro`
+
+## Purpose
+Use this skill when creating or revising repo-owned skills or workflow specs for `ether-to-astro`.
+
+The goal is not to write aspirational product prose. The goal is to produce a boring, compliant `SKILL.md` that another agent can execute consistently.
+
+## Core Rules
+- Skills own synthesis, ranking, formatting, and user/workflow-specific judgment.
+- MCP owns deterministic astro computation and reusable structured facts.
+- If a skill starts inventing astro math, transit logic, house logic, or electional primitives, stop and move that requirement back into MCP or a product issue.
+- Prefer a one-call or two-call workflow over a large prompt blob.
+- Keep the skill reusable. Do not hardcode one transient conversation unless the request is explicitly private/user-local.
+
+## Default Shape
+Write skills using this structure unless there is a strong reason to simplify:
+
+```md
+---
+name: your-skill-name
+description: What this skill does and when to use it.
+---
+
+# <Skill Name>
+
+## Purpose
+One short paragraph on what this skill does and when to use it.
+
+## Inputs
+- Required context or assumptions
+- Required MCP/tool outputs
+- Optional config/defaults
+
+## Workflow
+1. Call the relevant MCP/tool surface(s).
+2. Transform or rank the results.
+3. Produce the final output in the required shape.
+
+## Output Contract
+- Required sections
+- Ordering rules
+- Required references to underlying astro facts
+- Things that must stay optional
+
+## Boundaries
+- What this skill must not do
+- What stays in MCP
+- What stays user-specific
+```
+
+## Repo-Specific Expectations
+- Prefer concrete nouns over product slogans.
+- Name the actual MCP tools the skill should call.
+- If there is a stable two-call model, spell it out explicitly.
+- If defaults matter, distinguish:
+  - deterministic startup/config defaults
+  - skill-side interpretation preferences
+- Keep output contracts minimal. Define only the sections and fields needed for consistency.
+- Do not turn issue language into fake canonical schema unless the repo has explicitly committed to one.
+
+## Good Patterns
+- “Call `get_transits` with forecast mode, then optionally call `get_electional_context` for narrowed windows.”
+- “Summarize mundane baseline first, natal modifiers second.”
+- “Keep tags and rankings in the skill, not in MCP payloads.”
+
+## Bad Patterns
+- Defining new astro facts inside the skill.
+- Requiring hidden state not available from the documented workflow.
+- Writing a manifesto instead of an execution spec.
+- Hardcoding one user’s private heuristics into a repo-owned shared skill.
+
+## Validation
+- Follow the Agent Skills spec at https://agentskills.io/specification.
+- Validate frontmatter and naming with the reference tooling when available, for example:
+  - `skills-ref validate ./skills/your-skill-name`
+  - or the equivalent validator flow provided by your skills toolchain
+
+## Definition Of Done
+A good repo-owned `SKILL.md` should let a zero-context agent answer:
+- when should I use this skill?
+- which tools do I call, and in what order?
+- what output shape do I produce?
+- what must I avoid putting into MCP?