ether-to-astro 1.1.0 → 1.3.0

package/.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,87 @@
+name: Bug report
+description: Report incorrect, misleading, lossy, or contract-drift behavior.
+title: "[Bug]: "
+labels:
+  - bug
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this template when the current behavior is wrong, misleading, lossy, or does not match docs.
+
+  - type: dropdown
+    id: surface
+    attributes:
+      label: Affected surface
+      options:
+        - MCP
+        - CLI
+        - Docs
+        - Charts / rendering
+        - Validation / tests
+        - Mixed / not sure
+    validations:
+      required: true
+
+  - type: textarea
+    id: current
+    attributes:
+      label: Current behavior
+      description: What happens today?
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What should happen instead?
+    validations:
+      required: true
+
+  - type: textarea
+    id: impact
+    attributes:
+      label: User impact
+      description: Why does this matter in practice?
+      placeholder: This causes incorrect astrology, misleading UX, or broken workflows because...
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      description: Include tool calls, CLI commands, or input parameters.
+      placeholder: |
+        1. Call `...`
+        2. With input `...`
+        3. Observe `...`
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Relevant chart/date/timezone context
+      description: Add sanitized astrology context if it matters.
+      placeholder: Date, timezone, house system, location, planet categories, days_ahead, etc.
+
+  - type: textarea
+    id: docs_drift
+    attributes:
+      label: Docs or contract drift
+      description: If docs/tool descriptions are involved, note the mismatch here.
+
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Fix acceptance criteria
+      description: What would make this bug fixed?
+      placeholder: |
+        - Tool docs say...
+        - Response no longer drops...
+        - Validation covers...
+    validations:
+      required: true
+

package/.github/ISSUE_TEMPLATE/capability-request.yml

@@ -0,0 +1,117 @@
+name: Capability request
+description: Request a new feature, MCP primitive, skill, or reporting capability.
+title: "[Capability]: "
+labels:
+  - feature
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this template for new capabilities across MCP, CLI, skills, or docs.
+
+        Before filing, check:
+        - `docs/product/product-tenets.md`
+        - `docs/product/architecture-boundaries.md`
+        - whether this belongs in MCP, a skill, or docs
+
+  - type: dropdown
+    id: surface
+    attributes:
+      label: Recommended surface
+      description: Where should this capability primarily live?
+      options:
+        - MCP
+        - Skill
+        - CLI
+        - Docs
+        - Mixed / not sure
+    validations:
+      required: true
+
+  - type: dropdown
+    id: type
+    attributes:
+      label: Capability type
+      options:
+        - Feature
+        - Gap
+        - Skill enhancement
+        - Docs enhancement
+        - RFC / decision needed
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem statement
+      description: What is missing or hard today? Write this like a PM problem statement.
+      placeholder: The current product can do X, but it cannot do Y, which blocks Z.
+    validations:
+      required: true
+
+  - type: textarea
+    id: user_story
+    attributes:
+      label: User story
+      description: Use the format “As a..., I want..., so that...”
+      placeholder: As a skill author, I want...
+    validations:
+      required: true
+
+  - type: textarea
+    id: value
+    attributes:
+      label: Why this matters
+      description: What user outcome or product goal does this unlock?
+      placeholder: This matters because...
+    validations:
+      required: true
+
+  - type: textarea
+    id: determinism
+    attributes:
+      label: Determinism and boundary check
+      description: Explain whether the proposed output is deterministic for the same inputs, and why it belongs in MCP, a skill, or another layer.
+      placeholder: The output is deterministic because... It belongs in MCP/Skill because...
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposed_scope
+    attributes:
+      label: Proposed scope
+      description: What should this include? Keep it concrete.
+      placeholder: Add a new endpoint or mode that returns...
+    validations:
+      required: true
+
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance criteria
+      description: Flat list is fine. Focus on observable outcomes.
+      placeholder: |
+        - A client can...
+        - The response includes...
+        - Docs explain...
+    validations:
+      required: true
+
+  - type: textarea
+    id: examples
+    attributes:
+      label: Example input/output or workflow
+      description: Provide a tool call, user flow, or report snippet if helpful.
+
+  - type: textarea
+    id: dependencies
+    attributes:
+      label: Dependencies or related issues
+      description: Link related issues or note prerequisite work.
+
+  - type: textarea
+    id: non_goals
+    attributes:
+      label: Non-goals or constraints
+      description: What should this issue avoid doing?

package/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Product triage backlog
+    url: https://github.com/unsalted/ether-to-astro/blob/main/docs/product/product-tenets.md
+    about: Start here for product boundaries and MCP-vs-skill guidance.

package/.github/ISSUE_TEMPLATE/paper-cut.yml

@@ -0,0 +1,59 @@
+name: Paper-cut
+description: Report small UX, API, formatting, or workflow friction that should be easy to improve.
+title: "[Paper-cut]: "
+labels:
+  - paper-cut
+body:
+  - type: dropdown
+    id: surface
+    attributes:
+      label: Affected surface
+      options:
+        - MCP
+        - CLI
+        - Docs
+        - Skill workflow
+        - Mixed / not sure
+    validations:
+      required: true
+
+  - type: textarea
+    id: friction
+    attributes:
+      label: Current friction
+      description: What is awkward or annoying today?
+    validations:
+      required: true
+
+  - type: textarea
+    id: desired
+    attributes:
+      label: Desired improvement
+      description: What small change would make this noticeably better?
+    validations:
+      required: true
+
+  - type: textarea
+    id: workaround
+    attributes:
+      label: Current workaround
+      description: How are you working around it now?
+
+  - type: textarea
+    id: user_story
+    attributes:
+      label: User story
+      description: Optional but helpful. Use “As a..., I want..., so that...”
+
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance criteria
+      description: Keep this small and concrete.
+      placeholder: |
+        - Response includes...
+        - Docs show...
+        - A client no longer needs to...
+    validations:
+      required: true
+

package/.github/pull_request_template.md

@@ -14,3 +14,4 @@
 - [ ] Scope is focused and avoids unrelated churn
 - [ ] Tests were added or updated when behavior changed
 - [ ] Docs were updated when workflow or interfaces changed
+- [ ] This change respects the MCP vs skill boundary in `docs/product/product-tenets.md` and `docs/product/adrs/0001-mcp-vs-skill-boundary.md`

package/AGENTS.md

@@ -98,6 +98,38 @@ Defined in `tests/validation/utils/tolerances.ts`:
 - Preferred commit types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `build`, `ci`.
 - Keep commits scoped to one coherent change whenever possible.
 
+## Request Triage Guidance
+- When responding to bug reports, feature requests, or product-boundary questions, consult these docs first:
+  - `docs/product/product-tenets.md`
+  - `docs/product/architecture-boundaries.md`
+  - `docs/product/adrs/0001-mcp-vs-skill-boundary.md`
+  - `docs/product/post-iteration-2-triage.private.md` if present locally
+- Use those docs to classify the request before proposing implementation:
+  - `bug` for incorrect, lossy, misleading, or contract-drift behavior
+  - `feature` for reusable product capability
+  - `paper-cut` for small interface or workflow friction
+  - `skill` when the work is primarily synthesis, formatting, ranking, or preference-aware orchestration
+  - `MCP` when the work is deterministic or mostly deterministic, computational, reusable, and risky to reconstruct client-side
+- Apply the determinism rule explicitly:
+  - deterministic and generic astro computation is a strong candidate for MCP
+  - deterministic but policy-heavy or personalized workflow synthesis still belongs in a skill
+- If a competent LLM can solve the request in one or two calls using stable MCP primitives, prefer keeping it out of MCP unless there is strong evidence the pattern should become a reusable primitive.
+- For incoming product requests, prefer extending an existing tool with flags, fields, modes, or range support before proposing a new narrowly scoped MCP tool.
+
+## Writing Skills
+- When a request is classified as a `skill`, default the deliverable to a concrete `SKILL.md` or equivalent workflow spec, not a broad product narrative.
+- Repo-owned `SKILL.md` files should follow the Agent Skills spec, including YAML frontmatter with at least `name` and `description`.
+- Treat repo-owned skills as boring, compliant instruction bundles:
+  - clear purpose
+  - required inputs and assumptions
+  - exact MCP/tools to call
+  - output shape
+  - boundaries and non-goals
+- Prefer one or two stable MCP calls plus synthesis over embedding custom astro math, hidden heuristics, or pseudo-tool contracts in the skill.
+- Keep deterministic astro facts in MCP and user-specific ranking, emphasis, and interpretation in the skill.
+- Do not treat every skill idea in product docs or issues as a committed repo artifact. Many skill ideas are incubation examples unless explicitly promoted.
+- If authoring or revising a skill, prefer following the repo-local skill authoring guidance in `skills/.system/write-skill/SKILL.md`.
+
 ## Release Governance
 - `main` is PR-only and branch-protected; do not push directly.
 - Use Conventional Commits / commitizen-style messages for all commits.

package/DEVELOPER.md

@@ -0,0 +1,78 @@
+# Developer Guide
+
+This guide is for contributors working in the repository.
+
+For product setup and end-user usage, see [SETUP.md](/Users/salted/Code/astro-mcp/SETUP.md).
+
+## Local Repo Setup
+
+Requirements:
+
+- Node.js 22+
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Build the local checkout:
+
+```bash
+npm run build
+```
+
+Use the local CLI after building:
+
+```bash
+npm run start:cli -- --help
+```
+
+## Quality Gates
+
+Routine merge gate:
+
+```bash
+npm run quality:gate
+```
+
+This runs:
+
+- `npm run build`
+- `npm run lint`
+- `npm test -- --run`
+
+Targeted validation for high-risk astrology engine changes:
+
+```bash
+npm run validate:astro
+```
+
+## Contributor 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.
+- Respect the MCP-vs-skill boundary documented in:
+  - [docs/product/product-tenets.md](/Users/salted/Code/astro-mcp/docs/product/product-tenets.md)
+  - [docs/product/architecture-boundaries.md](/Users/salted/Code/astro-mcp/docs/product/architecture-boundaries.md)
+  - [docs/product/adrs/0001-mcp-vs-skill-boundary.md](/Users/salted/Code/astro-mcp/docs/product/adrs/0001-mcp-vs-skill-boundary.md)
+
+## Technical Notes
+
+- Engine: native Swiss Ephemeris via Node `sweph` bindings
+- `sweph` is pinned to an exact version to keep validation fixtures and numerical baselines stable
+- Primary accuracy mode uses Swiss Ephemeris data files
+- `EPHEMERIS_VERSION=moshier` is supported as a lower-precision fallback
+- Chart rendering uses `@astrodraw/astrochart` with JSDOM
+
+## Common Commands
+
+```bash
+npm run build
+npm run lint
+npm test -- --run
+npm run validate:astro
+npm run start:cli -- --help
+```

package/README.md

@@ -12,26 +12,98 @@
 
 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 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 ether-to-astro --help
+```
+
+Or:
+
+```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
 
 You can ask your AI agent about:
 
 ### Transits
-- **Daily mundane transits** - Current planetary positions
+- **Daily mundane positions** - Current planetary positions
+- **Mundane transit-to-transit aspects** - Deterministic aspect signals between transiting bodies
+- **Mundane weather metadata** - Deterministic supportive/challenging grouping references (non-narrative)
 - **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 +112,29 @@ You can ask your 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
-./setup.sh
+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
+npm install
+npm run build
 ```
 
 ### Ephemeris Data Configuration
@@ -68,82 +161,32 @@ EPHEMERIS_VERSION=moshier npm install
 Or manually:
 ```bash
 npm install
-npm run build
 ```
 
-## Contributing 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.
+## Package Names
 
-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:
-
-```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 aliases: `ether-to-astro`, `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": "npx",
-      "args": ["--yes", "--package=ether-to-astro", "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:
@@ -159,16 +202,10 @@ 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.
-
-Install globally if you want direct commands without `--package`:
-
-```bash
-npm install -g ether-to-astro
-e2a --help
-e2a-mcp --help
-```
+`npx` usage note:
+- `npx ether-to-astro ...` works directly (package-name bin alias).
+- `npx e2a ...` does **not** work by itself because npm resolves package names first.
+- `npx --package=ether-to-astro e2a ...` remains supported.
 
 Examples:
 
@@ -261,7 +298,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
+  - with `include_mundane=true`, output includes deterministic mundane positions plus `mundane.aspects` and non-narrative `mundane.weather` grouping metadata
+  - when `include_mundane=true` and `mode=forecast`, output includes `mundane.days[]` with per-day grouped mundane aspects/weather
+
+### 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)
@@ -304,6 +351,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