ether-to-astro 1.0.2 → 1.2.0

package/README.md

@@ -12,26 +12,90 @@
 
 Astrology tooling for agent workflows.
 
-`ether-to-astro` is a local-first astrology toolkit with two surfaces: `e2a`, a CLI, and `e2a-mcp`, an MCP server.
+`ether-to-astro` is a local-first astrology toolkit with a unified `e2a` binary for CLI and MCP usage, plus an `e2a-mcp` compatibility alias for existing MCP setups.
 
 This started as a side project because my wife is the real user, and I wasn’t impressed with the tooling around her astrology fascination. I’ve worked on plenty of AI tools and have a pretty high bar for them. Most of what I found in this space felt flimsy, closed-off, or not designed for serious agent workflows.
 
-So I built the version I wanted to exist: local-first, scriptable, tested, and structured to work well both from the command line and through MCP. I’m the builder. She’s the user. That turned out to be a pretty good way to make the product better.
+So I built the version I wanted to exist: local-first, scriptable, tested, and structured to work well both from the command line and through MCP. I built it, she uses it daily, and that feedback loop has made the product better.
+
+## Quick Start
+
+### MCP
+
+Add this to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "astro": {
+      "command": "npx",
+      "args": ["--yes", "--package=ether-to-astro", "e2a", "--mcp"]
+    }
+  }
+}
+```
+
+Then restart your MCP client and call `set_natal_chart`.
+
+### CLI
+
+Run the CLI directly with `npx`:
+
+```bash
+npx --yes --package=ether-to-astro e2a --help
+```
+
+Or install globally:
+
+```bash
+npm install -g ether-to-astro
+e2a --help
+e2a --mcp --help
+```
+
+### Product Setup
+
+- End-user setup and examples: [SETUP.md](/Users/salted/Code/astro-mcp/SETUP.md)
+- Local repo setup and contributor workflow: [DEVELOPER.md](/Users/salted/Code/astro-mcp/DEVELOPER.md)
+
+### Agent Skills
+
+This repo also includes repo-owned agent skills in a standard `skills/` layout.
+
+If you use the [Vercel `skills` CLI](https://github.com/vercel-labs/skills), you can inspect or install them from a local checkout:
+
+```bash
+# List skills available in this repo
+npx skills add . --list
+
+# Install the repo's skills to Codex for this project
+npx skills add . --agent codex --skill daily-brief --skill weekly-overview --skill electional-overlay
+
+# Install the repo's write-skill helper to Codex for this project
+npx skills add . --agent codex --skill write-skill
+```
+
+You can also install from GitHub instead of a local checkout:
+
+```bash
+npx skills add unsalted/ether-to-astro --agent codex --skill write-skill
+```
 
 ## Features
 
-Your wife can ask her AI agent about:
+You can ask your AI agent about:
 
 ### Transits
-- **Daily mundane transits** - Current planetary positions
+- **Daily mundane positions** - Current planetary positions
 - **Moon transits** - Fast-moving Moon aspects to natal planets
 - **Personal planet transits** - Sun, Mercury, Venus, Mars aspects to natal chart
 - **Outer planet transits** - Jupiter, Saturn, Uranus, Neptune, Pluto aspects
 - **Exact transit times** - Precise timing when transits become exact (0° orb)
-- **Upcoming transits** - Multi-day forecast for transits approaching within 2°
+- **Upcoming transit preview** - Best upcoming hits across a requested date range
 
 ### Advanced Features
 - **House cusps** - Ascendant, Midheaven, and all 12 houses (multiple systems)
+- **Electional context** - Stateless ascendant, sect, Moon phase, and applying-aspect context for a specific date, time, and location
 - **Retrograde status** - Which planets are currently retrograde
 - **Rise/Set times** - Sunrise, sunset, moonrise, moonset
 - **Asteroids & Nodes** - Chiron, Ceres, Pallas, Juno, Vesta, North Node
@@ -40,8 +104,29 @@ Your wife can ask her AI agent about:
 
 ## Installation
 
+### From npm
+
+For normal product usage, install from npm or use `npx`.
+
+```bash
+npx --yes --package=ether-to-astro e2a --help
+```
+
+Or:
+
+```bash
+npm install -g ether-to-astro
+```
+
+You do not need to run `npm run build` when installing from npm.
+
+### From a local repo checkout
+
+If you cloned this repository and want to run the local source checkout:
+
 ```bash
-./setup.sh
+npm install
+npm run build
 ```
 
 ### Ephemeris Data Configuration
@@ -68,81 +153,32 @@ EPHEMERIS_VERSION=moshier npm install
 Or manually:
 ```bash
 npm install
-npm run build
-```
-
-## Engineering Contract
-
-This repo uses a lightweight, agent-friendly operating contract:
-
-- Keep changes focused and avoid unrelated churn in the same diff.
-- Treat Biome as the source of truth for formatting, import order, and linting.
-- Use conventional commit messages: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `build`, `ci`.
-- Keep PR descriptions short and explicit about what changed and how it was verified.
-
-Required routine quality gate:
-
-```bash
-npm run quality:gate
 ```
 
-This runs:
-
-- `npm run build`
-- `npm run lint`
-- `npm test -- --run`
-
-Use `npm run validate:astro` for high-risk astrology engine work such as ephemeris/root-solver/transit-timing changes. It is intentionally not part of the default routine gate.
-
-Commit examples:
+## Package Names
 
-```text
-fix(cli): resolve injected cwd for relative profile paths
-test(profiles): cover default profile precedence
-refactor(transits): simplify exact-time formatting
-docs(readme): document remote-ready repo contract
-```
-
-Pull request checklist:
-
-- Scope is focused and coherent.
-- `npm run quality:gate` passed locally.
-- Tests were added or updated when behavior changed.
-- Docs were updated when workflow or interfaces changed.
-- PR description includes:
-  - What changed
-  - How it was verified
+- Package: `ether-to-astro`
+- CLI command: `e2a`
+- Canonical MCP command: `e2a --mcp`
+- Compatibility MCP alias: `e2a-mcp`
 
-## Setup
+## Runtime Surfaces
 
-1. Run setup script or install manually (see above)
+### MCP server (stateful per process)
 
-2. Build:
+Launch MCP mode with:
 
 ```bash
-npm run build
+e2a --mcp --help
 ```
 
-3. Add MCP to your MCP settings (e.g., Claude Desktop config):
+Optional deterministic startup defaults:
 
-```json
-{
-  "mcpServers": {
-    "astro": {
-      "command": "e2a-mcp"
-    }
-  }
-}
+```bash
+e2a --mcp --preferred-tz America/Los_Angeles --preferred-house-style W --weekday-labels
 ```
 
-Package/binary names:
-- Package: `ether-to-astro`
-- CLI command: `e2a`
-- MCP command: `e2a-mcp`
-
-## Runtime Surfaces
-
-### MCP server (stateful per process)
+The `e2a-mcp` binary remains available as a compatibility alias and starts MCP mode automatically.
 
 ### In-Memory Storage
 The MCP server uses **in-memory storage** for natal chart data:
@@ -158,17 +194,20 @@ This design is **MCP-compliant** for stdio transport and ensures complete isolat
 
 `e2a` is JSON-first for agent usage and supports `--pretty` for human-readable output.
 
+`npx` usage note: this package is named `ether-to-astro`, so invoke bins with `--package`.
+`npx e2a` will not work by itself because npm resolves package names first.
+
 Examples:
 
 ```bash
 # Help
-npx e2a --help
+npx --yes --package=ether-to-astro e2a --help
 
 # Set natal chart and print JSON
-npx e2a set-natal-chart --name "Test" --year 1990 --month 1 --day 1 --hour 12 --minute 0 --latitude 40.7 --longitude -74.0 --timezone America/New_York
+npx --yes --package=ether-to-astro e2a set-natal-chart --name "Test" --year 1990 --month 1 --day 1 --hour 12 --minute 0 --latitude 40.7 --longitude -74.0 --timezone America/New_York
 
 # Human-readable transit output
-npx e2a get-transits --natal-file ./natal.json --date 2026-03-27 --pretty
+npx --yes --package=ether-to-astro e2a get-transits --natal-file ./natal.json --date 2026-03-27 --pretty
 ```
 
 ### CLI Profiles (`.astro.json`)
@@ -193,9 +232,9 @@ Profile name resolution order:
 Read-only helper commands:
 
 ```bash
-npx e2a profiles list
-npx e2a profiles show --profile elwyn
-npx e2a profiles validate
+npx --yes --package=ether-to-astro e2a profiles list
+npx --yes --package=ether-to-astro e2a profiles show --profile default
+npx --yes --package=ether-to-astro e2a profiles validate
 ```
 
 Recommended: add project-local `.astro.json` to `.gitignore` because it contains birth data.
@@ -249,7 +288,17 @@ Ask your AI agent:
 - `set_natal_chart` - Store birth chart data
 
 ### Transits
-- `get_transits` - Category-filtered transits with optional exact-time data
+- `get_transits` - Category-filtered transits with optional exact-time data and explicit mode semantics:
+  - `snapshot`: single-day view for the selected date
+  - `best_hit`: compressed multi-day preview across the selected date window
+  - `forecast`: day-grouped transit output across the selected date window
+  - if `mode` is omitted, legacy behavior is preserved: `days_ahead=0` resolves to `snapshot`, and `days_ahead>0` resolves to `best_hit`
+  - each transit now includes additive placement metadata for both sides: sign, degree, and house
+
+In this release, `include_mundane` remains anchored to the forecast start date even when `mode=forecast`. Range-aware mundane output is tracked separately.
+
+### Electional
+- `get_electional_context` - Stateless electional context for a local date, time, and location. Returns deterministic ascendant, sect/day-night classification, Moon phase, applying aspects, and optional ASC-ruler basics without requiring a natal chart.
 
 ### Advanced Tools
 - `get_houses` - House cusps, Ascendant, Midheaven (Placidus, Koch, Whole Sign, Equal)
@@ -292,6 +341,10 @@ Ask your AI agent:
 - **Exact time calculation**: Uses binary search interpolation for precision
 - **Advance warnings**: Shows transits within 2° orb
 
+## Development
+
+Contributor workflow, local repo setup, quality gates, and release-oriented notes live in [DEVELOPER.md](/Users/salted/Code/astro-mcp/DEVELOPER.md).
+
 ## License
 
 AGPL-3.0-or-later

package/SETUP.md

@@ -1,70 +1,129 @@
-# Quick Setup Guide
+# Setup Guide
 
-## Installation
+This guide is for using `ether-to-astro` as a product, not for local development on the repo itself.
 
-```bash
-./setup.sh
-```
+For contributor setup, local builds, tests, and release workflow, see [DEVELOPER.md](/Users/salted/Code/astro-mcp/DEVELOPER.md).
+
+## Quick Start
 
-This will:
-1. Install npm dependencies (including WebAssembly Swiss Ephemeris)
-2. Build TypeScript to JavaScript
+### Use as an MCP server
 
-## Add to Claude Desktop
+Add this to your MCP client config:
 
-Edit your Claude Desktop config file:
-- **Mac**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+```json
+{
+  "mcpServers": {
+    "astro": {
+      "command": "npx",
+      "args": ["--yes", "--package=ether-to-astro", "e2a", "--mcp"]
+    }
+  }
+}
+```
 
-Add this MCP server:
+Alternative after global install:
 
 ```json
 {
   "mcpServers": {
     "astro": {
-      "command": "node",
-      "args": ["/path/to/ether-to-astro-mcp/dist/index.js"]
+      "command": "e2a",
+      "args": ["--mcp"]
     }
   }
 }
 ```
 
-**Important**: Replace `/path/to/ether-to-astro-mcp` with your actual path!
+Then restart your MCP client and call `set_natal_chart` before requesting transits or charts.
 
-## First Use
+### Use as a CLI
 
-1. Restart Claude Desktop
-2. Set your wife's natal chart:
+Run directly with `npx`:
 
+```bash
+npx --yes --package=ether-to-astro e2a --help
 ```
-Please set my natal chart:
-- Name: [Name]
-- Birth: [Month] [Day], [Year] at [Hour]:[Minute] 
-- Location: [City] ([Latitude], [Longitude])
-- Timezone: [e.g., America/Los_Angeles]
+
+Or install globally:
+
+```bash
+npm install -g ether-to-astro
+e2a --help
+e2a --mcp --help
+```
+
+## Notes
+
+- You do not need to run `npm run build` when installing from npm.
+- `npx e2a` does not work by itself because npm resolves package names first. Use `npx --package=ether-to-astro e2a`.
+- The package downloads Swiss Ephemeris data during install unless you choose `EPHEMERIS_VERSION=moshier`.
+
+## Ephemeris Data Options
+
+The package downloads Swiss Ephemeris data files during installation. You can control which version with `EPHEMERIS_VERSION`.
+
+- `long` (default): 6000 years, recommended for professional use
+- `short`: 600 years, smaller download for modern charts
+- `moshier`: no ephemeris download, lower precision fallback
+
+Examples:
+
+```bash
+npm install -g ether-to-astro
+EPHEMERIS_VERSION=short npm install -g ether-to-astro
+EPHEMERIS_VERSION=moshier npm install -g ether-to-astro
 ```
 
-3. Query transits:
+## First Use
+
+Typical flow:
 
+1. Start the MCP server or use the CLI.
+2. Set the natal chart.
+3. Request transits, houses, or chart rendering.
+
+Example CLI call:
+
+```bash
+npx --yes --package=ether-to-astro e2a set-natal-chart \
+  --name "Test" \
+  --year 1990 \
+  --month 1 \
+  --day 1 \
+  --hour 12 \
+  --minute 0 \
+  --latitude 40.7 \
+  --longitude -74.0 \
+  --timezone America/New_York
 ```
-What are my transits today?
-Show me upcoming transits this week
-When will the Moon conjunct my Venus be exact?
+
+Then:
+
+```bash
+npx --yes --package=ether-to-astro e2a get-transits --natal-file ./natal.json --date 2026-03-27 --pretty
 ```
 
-## MCP Tools Available
+## Product Surfaces
+
+- `e2a --mcp`: canonical stateful MCP server launch
+- `e2a-mcp`: compatibility alias for MCP launch
+- `e2a`: stateless CLI
 
-- `set_natal_chart` - Store birth data
-- `get_daily_transits` - Current planetary positions
-- `get_moon_transits` - Moon aspects to natal planets
-- `get_personal_planet_transits` - Sun/Mercury/Venus/Mars aspects
-- `get_outer_planet_transits` - Jupiter/Saturn/Uranus/Neptune/Pluto aspects
-- `get_exact_transit_times` - Calculate exact times for current transits
-- `get_upcoming_transits` - Multi-day forecast (default 7 days)
+Optional MCP startup defaults:
 
-## Technical Notes
+```bash
+e2a --mcp --preferred-tz America/Los_Angeles --preferred-house-style W --weekday-labels
+```
 
-- Uses WebAssembly Swiss Ephemeris (no native compilation!)
-- Moshier mode provides ~1 arcsecond precision
-- No ephemeris data files needed
-- Works on Mac/Linux (Node.js required)
+## Available Tools
+
+- `set_natal_chart`
+- `get_transits`
+- `get_houses`
+- `get_retrograde_planets`
+- `get_rise_set_times`
+- `get_asteroid_positions`
+- `get_next_eclipses`
+- `generate_natal_chart`
+- `generate_transit_chart`
+- `get_server_status`

package/dist/astro-service.d.ts

@@ -1,11 +1,12 @@
 import { ChartRenderer } from './charts.js';
 import { EclipseCalculator } from './eclipses.js';
+import type { McpStartupDefaults } from './entrypoint.js';
 import { EphemerisCalculator } from './ephemeris.js';
 import { HouseCalculator } from './houses.js';
 import { RiseSetCalculator } from './riseset.js';
 import { type Disambiguation } from './time-utils.js';
 import { TransitCalculator } from './transits.js';
-import { type HouseSystem, type NatalChart } from './types.js';
+import { type AspectType, type ElectionalHouseSystem, type HouseSystem, type NatalChart, type PlanetPosition } from './types.js';
 interface AstroServiceDependencies {
     ephem?: EphemerisCalculator;
     transitCalc?: TransitCalculator;
@@ -13,6 +14,7 @@ interface AstroServiceDependencies {
     riseSetCalc?: RiseSetCalculator;
     eclipseCalc?: EclipseCalculator;
     chartRenderer?: ChartRenderer;
+    mcpStartupDefaults?: McpStartupDefaults;
     now?: () => Date;
     writeFile?: (path: string, data: string | Buffer, encoding?: BufferEncoding) => Promise<void>;
 }
@@ -34,13 +36,32 @@ export interface GetTransitsInput {
     categories?: string[];
     include_mundane?: boolean;
     days_ahead?: number;
+    mode?: 'snapshot' | 'best_hit' | 'forecast';
     max_orb?: number;
     exact_only?: boolean;
     applying_only?: boolean;
 }
+export interface GetElectionalContextInput {
+    date: string;
+    time: string;
+    timezone: string;
+    latitude: number;
+    longitude: number;
+    house_system?: ElectionalHouseSystem;
+    include_ruler_basics?: boolean;
+    include_planetary_applications?: boolean;
+    orb_degrees?: number;
+}
 export interface GetHousesInput {
     system?: string;
 }
+export interface GetRisingSignWindowsInput {
+    date: string;
+    latitude: number;
+    longitude: number;
+    timezone: string;
+    mode?: 'approximate' | 'exact';
+}
 export interface GenerateChartInput {
     theme?: 'light' | 'dark';
     format?: 'svg' | 'png' | 'webp';
@@ -53,7 +74,17 @@ export interface ServiceResult<T> {
     data: T;
     text: string;
 }
-export interface ChartServiceResult {
+export interface MundaneAspect {
+    id: string;
+    planetA: PlanetPosition['planet'];
+    planetB: PlanetPosition['planet'];
+    aspect: AspectType;
+    orb: number;
+    isApplying: boolean;
+    longitudeA: number;
+    longitudeB: number;
+}
+interface ChartServiceResult {
     format: 'svg' | 'png' | 'webp';
     outputPath?: string;
     text: string;
@@ -77,16 +108,34 @@ export declare class AstroService {
     readonly riseSetCalc: RiseSetCalculator;
     readonly eclipseCalc: EclipseCalculator;
     readonly chartRenderer: ChartRenderer;
+    readonly mcpStartupDefaults: Readonly<McpStartupDefaults>;
     private readonly now;
     private readonly writeFileFn;
     constructor(deps?: AstroServiceDependencies);
+    private formatTimestamp;
+    private normalizeLongitude;
+    private getSignAndDegree;
+    private getHouseNumber;
+    private resolveHouseSystem;
+    private resolveTimezones;
+    resolveReportingTimezone(explicitTimezone?: string, natalTimezone?: string): string;
     init(): Promise<void>;
     isInitialized(): boolean;
     setNatalChart(input: SetNatalChartInput): ServiceResult<Record<string, unknown>> & {
         chart: NatalChart;
     };
     getTransits(natalChart: NatalChart, input?: GetTransitsInput): ServiceResult<Record<string, unknown>>;
+    private getMundaneWeather;
+    private getMundaneAspects;
+    private getMundaneDay;
+    getElectionalContext(input: GetElectionalContextInput): ServiceResult<Record<string, unknown>>;
     getHouses(natalChart: NatalChart, input?: GetHousesInput): ServiceResult<Record<string, unknown>>;
+    getRisingSignWindows(input: GetRisingSignWindowsInput): ServiceResult<Record<string, unknown>>;
+    private getElectionalApplyingAspects;
+    private isElectionalAspectApplying;
+    private getSignedAngularDifference;
+    private getElectionalPhaseName;
+    private getTraditionalSignRuler;
     getRetrogradePlanets(timezone?: string): ServiceResult<Record<string, unknown>>;
     getRiseSetTimes(natalChart: NatalChart): Promise<ServiceResult<Record<string, unknown>>>;
     getAsteroidPositions(timezone?: string): ServiceResult<Record<string, unknown>>;