hoshi-astro 1.7.0__tar.gz

hoshi_astro-1.7.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --python ${{ matrix.python-version }}
+
+      - name: Run tests
+        run: uv run --python ${{ matrix.python-version }} pytest

hoshi_astro-1.7.0/.github/workflows/release.yml

@@ -0,0 +1,83 @@
+name: Release
+
+on:
+  workflow_run:
+    workflows: ["CI"]
+    branches: [main]
+    types: [completed]
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    concurrency: release
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    permissions:
+      id-token: write
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Release hoshi
+        id: release-hoshi
+        uses: python-semantic-release/python-semantic-release@v10
+        with:
+          directory: .
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Release hoshi-api
+        id: release-hoshi-api
+        uses: python-semantic-release/python-semantic-release@v10
+        with:
+          directory: packages/hoshi-api
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Release hoshi-ui
+        id: release-hoshi-ui
+        uses: python-semantic-release/python-semantic-release@v10
+        with:
+          directory: packages/hoshi-ui
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Publish hoshi to GitHub Release
+        uses: python-semantic-release/publish-action@v10
+        if: steps.release-hoshi.outputs.released == 'true'
+        with:
+          directory: .
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          tag: ${{ steps.release-hoshi.outputs.tag }}
+
+      - name: Build hoshi for PyPI
+        run: uv build
+        if: steps.release-hoshi.outputs.released == 'true'
+
+      - name: Publish hoshi to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        if: steps.release-hoshi.outputs.released == 'true'
+
+      - name: Publish hoshi-api to GitHub Release
+        uses: python-semantic-release/publish-action@v10
+        if: steps.release-hoshi-api.outputs.released == 'true'
+        with:
+          directory: packages/hoshi-api
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          tag: ${{ steps.release-hoshi-api.outputs.tag }}
+
+      - name: Publish hoshi-ui to GitHub Release
+        uses: python-semantic-release/publish-action@v10
+        if: steps.release-hoshi-ui.outputs.released == 'true'
+        with:
+          directory: packages/hoshi-ui
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          tag: ${{ steps.release-hoshi-ui.outputs.tag }}

hoshi_astro-1.7.0/.gitignore

@@ -0,0 +1,17 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+.history
+
+# Runtime caches (Horizons responses, JPL ephemeris)
+.chiron_cache.json
+.lunar_cache.json
+*.bsp

hoshi_astro-1.7.0/CHANGELOG.md

@@ -0,0 +1 @@
+# CHANGELOG

hoshi_astro-1.7.0/CLAUDE.md

@@ -0,0 +1,213 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Goal
+
+Hoshi is a Python CLI for astrological charting, with a focus on real-sky astrology. Real-sky charts use IAU constellation boundaries (13 signs of unequal width, including Ophiuchus) rather than the traditional 12-sign tropical wheel — this makes charting significantly harder to do by hand, which is where Hoshi helps. Planetary positions come from [Skyfield](https://rhodesmill.org/skyfield/) (JPL ephemerides) for accuracy.
+
+## Repo contents
+
+- `pyproject.toml` / `.python-version` — packaging and pinned interpreter. Requires Python 3.11+ (CI tests 3.11–3.13). The root `pyproject.toml` also configures a **uv workspace** (`[tool.uv.workspace]`) with members under `packages/`.
+- `hoshi/` — core Python package. Exposed as the `hoshi` console script via `[project.scripts]`; build backend is `hatchling`. After dependency changes, run `uv sync` to reinstall.
+- `packages/hoshi-api/` — FastAPI REST API package (workspace member). Depends on `hoshi` as a workspace dependency. Run with `uv run --package hoshi-api hoshi-api` (starts uvicorn on port 8000). Tests in `packages/hoshi-api/tests/`.
+- `charts/` — user-saved charts (one JSON file per chart). Names are normalized to lowercase on save. Not a cache — treat as user data. Persists only inputs; charts are recomputed on `hoshi chart show`.
+- `~/.cache/hoshi/chiron.json` — per-minute cache of Horizons OBSERVER responses for Chiron. Safe to delete.
+- `~/.cache/hoshi/lunar.json` — per-minute cache of Horizons ELEMENTS responses for the Moon (true nodes and true Lilith). Safe to delete.
+
+## Package modules (`hoshi/`)
+
+| Module | Purpose |
+|--------|---------|
+| `ephemeris.py` | Skyfield positions (`positions(when, include_chiron=...)`), Horizons HTTP fetch (`HorizonsError` on failure), shared `timescale()`/`cache_dir()`, JSON cache helpers, `ecliptic_precession()` |
+| `zodiac.py` | IAU real-sky boundaries, tropical/sidereal placements (`Placement.for_mode(lon, mode, ...)`), `ZodiacMode` enum, `TROP_SIGNS`/`SIGN_ATTRS` sign tables |
+| `houses.py` | Placidus, Porphyry, Equal, Arc-13 house cusps; angle computation (shared `_ramc_obliquity`/`_mc_from_ramc`) |
+| `points.py` | True lunar nodes, Black Moon Lilith, Hermetic lots |
+| `chart.py` | `Chart.build()` / `Chart.from_input()` — assembles all bodies; `Chart.bodies()`/`Chart.body(id)` uniform `BodyRef` iteration; `uncertain_signs()`; `Placed.for_longitude(...)` and `Placed.placement(mode)`; `location_known`/`time_known` flags; `house` is `None` when location unknown |
+| `aspects.py` | Aspect definitions and orbs; `compute_aspects()`, `compute_inter_aspects()` |
+| `dignities.py` | Planetary dignities table, element/modality tally |
+| `output.py` | Pydantic output models for every command (`ChartOutput`, `TransitsOutput`, etc.) with `.build()` classmethods that assemble models from SDK types. Shared by CLI and API. |
+| `store.py` | Save/load/list/delete named charts in `./charts/` |
+| `utils.py` | Shared utilities (`fuzzy_match`) used by both CLI and API |
+| `adb.py` | Astro-Databank import via MediaWiki API; `adb_to_chart_input()` fetches + parses `ASTRODATABANK_dma` template into `ChartInput`; coordinate/time/timezone converters; `ADBError` on failure |
+| `cli.py` | Typer entry point — all `hoshi chart` subcommands |
+
+## Public SDK surface
+
+Hoshi is usable as a library, not just a CLI. The top-level `hoshi` package
+(`hoshi/__init__.py`) re-exports the stable domain types and functions with an
+explicit `__all__`; **import from `hoshi`, not the submodules**, when consuming
+Hoshi from another project. A `py.typed` marker ships so downstream
+type-checkers see the annotations. See `docs/sdk.md` for a worked example.
+
+Guidance when changing the package:
+- New public constructs go in `__all__` (and ideally `docs/sdk.md`).
+- Keep computation in the SDK layer (`chart.py`, `zodiac.py`, …); `cli.py`
+  should only handle argument parsing and display. `Chart.from_input()`,
+  `Chart.bodies()`, and `uncertain_signs()` exist so the CLI doesn't own domain
+  logic — prefer extending these over adding logic to `cli.py`.
+- `Chart.from_input(ChartInput)` substitutes placeholder coordinates for an
+  unknown location and records `location_known` / `time_known` on the chart so
+  consumers can drive their own suppression.
+- Zodiac mode is the `ZodiacMode` StrEnum (in `zodiac.py`); functions accept it
+  or its plain-string value interchangeably.
+
+## CLI commands
+
+```
+hoshi chart add      NAME DATE [TIME] [--lat] [--lon] [--tz] [--mode] [--houses] [--details] [--aspects] [--group-by] [--cusps] [--force]
+hoshi chart show     NAME|DATE [TIME] [--lat --lon] ...   [--format table|json] [--compare-houses]
+hoshi chart cusps    NAME|DATE [TIME] [--lat --lon] ...   [--mode] [--houses]
+hoshi chart transits NAME [DATE [TIME]]                   [--tz] [--mode] [--houses] [--details] [--aspects] [--natal] [--group-by]
+hoshi chart compare  NAME1 NAME2                          [--mode] [--houses] [--aspects] [--details] [--group-by]
+hoshi chart import   SOURCE [NAME]                        [--force] [--mode] [--houses] [--details] [--aspects] [--group-by] [--cusps] [--format]
+hoshi chart list
+hoshi chart delete   NAME [--yes]
+```
+
+## Optional birth data and uncertainty
+
+`ChartInput` stores `time`, `lat`, and `lon` as `str | None` and `float | None` respectively — all three are optional. Store whatever is known; omit the rest.
+
+When displaying a chart with missing data:
+- **Time unknown** — noon UTC is used for computation; all planet sign/degree/lon cells render in **yellow** as a warning; `⚠` note is printed above the table. Moon sign is particularly uncertain (moves ~13°/day).
+- **Location unknown** — angles (ASC/MC/etc.), house numbers, and Hermetic lots are **suppressed entirely**; `⚠` note is printed.
+- **Both unknown** — both sets of rules apply.
+
+`ChartInput` properties `time_known` and `location_known` drive all suppression logic in `cli.py`. `--compare-houses` and `chart cusps` require both to be known and error if not.
+
+## Three zodiac modes
+
+- `'realsky'` — IAU real-sky boundaries (13 signs incl. Ophiuchus, unequal widths). Default. See `IAU[]` in `hoshi/zodiac.py`.
+- `'tropical'` — standard 12 equal 30° signs from the vernal equinox.
+- `'vedic'` — sidereal, Lahiri ayanamsa offset applied.
+
+## Reference frame: of-date, not J2000
+
+All ecliptic longitudes are in the **equinox of date** frame (measured from
+the vernal equinox at the chart moment), matching standard astrological
+convention. This requires explicit `epoch=t` in Skyfield calls —
+**`ecliptic_latlon()` default returns J2000**, contrary to what the Skyfield
+docs suggest. The two differ by precession (~50.3″/year).
+
+The IAU constellation table is J2000-fixed. `Placement.realsky()` accepts a
+`precession` argument (degrees since J2000 from `ecliptic_precession(when)`)
+to shift the boundaries into the of-date frame before the sign lookup.
+`Placed.for_longitude()` threads this through automatically when built via
+`Chart.build()`.
+
+## Horizons-backed bodies
+
+Skyfield/jplephem can't read JPL Horizons' small-body SPKs (SPK data type 21
+is unsupported). Two bodies use Horizons HTTP APIs directly:
+
+- **Chiron** (`_chiron_position` in `hoshi/ephemeris.py`) — Horizons
+  **OBSERVER** ephemeris at chart time + 1 minute for ecliptic lon/lat and
+  retrograde state.
+- **True lunar nodes & Black Moon Lilith** (`lunar_elements` in
+  `hoshi/points.py`) — Horizons **ELEMENTS** API at chart time, parses
+  OM (ascending node) and W (argument of perigee) for the Moon. True Lilith
+  = OM + W + 180°.
+
+Shared HTTP/SSL/cache helpers (`horizons_fetch`, `json_cache_get/put`) live
+in `hoshi/ephemeris.py`. The SSL context uses `certifi` because macOS
+stdlib `urllib` ships with an incomplete root bundle.
+
+## Aspects
+
+Five major aspects (4° orb), four minor (2° orb), three micro (1° orb). See
+`hoshi/aspects.py`. Single-chart aspects via `compute_aspects(chart, details)`;
+synastry inter-aspects via `compute_inter_aspects(chart_a, chart_b, details)`.
+Without `--details`, only planets + Asc are included. Axis pairs (Asc/Dsc,
+MC/IC, etc.) are filtered from single-chart aspects.
+
+`--group-by` controls grouping for both bodies and aspects: `category`
+(default — bodies by kind, aspects by Major/Minor/Micro), `sign`, `house`,
+or `planet` (aspects only).
+
+## Dignities
+
+`hoshi/dignities.py` holds the domicile/exaltation/detriment/fall table for
+the 13-sign real-sky scheme (Chiron domicile = Ophiuchus). Assignments follow
+standard conventions adapted for 13 signs.
+`element_modality_tally()` returns separate primary (planets) and total (all
+bodies) counts.
+
+## REST API (`packages/hoshi-api/`)
+
+A FastAPI application exposing the same chart functionality as the CLI via
+JSON endpoints. It imports the `hoshi` SDK and uses the `.build()` classmethods
+on the output models — the same models that back `--format json` in the CLI.
+
+**Running:** `uv run --package hoshi-api hoshi-api` (starts on `0.0.0.0:8000`
+with auto-reload). Interactive docs at `/docs`.
+
+**Route overview:**
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `POST` | `/charts` | Save a new chart |
+| `GET` | `/charts` | List saved charts |
+| `POST` | `/charts/compute` | Compute a one-off chart (no save) |
+| `POST` | `/charts/import` | Import from Astro-Databank |
+| `GET` | `/charts/{name}` | Show a saved chart |
+| `DELETE` | `/charts/{name}` | Delete a saved chart |
+| `GET` | `/charts/{name}/cusps` | House cusps |
+| `GET` | `/charts/{name}/transits` | Transits against natal |
+| `GET` | `/charts/{name}/compare/{other}` | Synastry |
+| `GET` | `/info/{category}` | List reference info |
+| `GET` | `/info/{category}/{name}` | Single item detail |
+
+All route handlers are synchronous (`def`, not `async def`) so uvicorn
+dispatches them to a thread pool — blocking Horizons/Skyfield calls work
+correctly without async wrappers.
+
+**Testing:** `uv run --package hoshi-api pytest packages/hoshi-api/tests/`
+
+## Conventions
+
+- Use `uv` for dependency and run management (`uv add`, `uv run`).
+
+## Commit message format
+
+This repo uses [Conventional Commits](https://www.conventionalcommits.org/) for
+`python-semantic-release` to automate versioning. Every commit message must
+follow this format:
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+**Types** (only these trigger releases):
+- `fix:` — bug fix → **patch** bump (0.0.x)
+- `feat:` — new feature → **minor** bump (0.x.0)
+- Append `!` after the type/scope (e.g. `feat!:`) or add a `BREAKING CHANGE:` footer → **major** bump (x.0.0)
+
+**Types** (no release, but still use them):
+- `chore:` — maintenance, dependency updates
+- `docs:` — documentation only
+- `refactor:` — code restructuring with no behavior change
+- `test:` — adding or updating tests
+- `ci:` — CI/CD changes
+- `style:` — formatting, whitespace
+
+**Scope** is optional and names the area of change, e.g. `feat(cli):`, `fix(ephemeris):`.
+
+Keep the first line under 72 characters. Use the body for additional context
+when the "why" isn't obvious from the summary line alone.
+
+**Always ask for confirmation before creating a commit.** Show the proposed
+commit message and list of staged files, then wait for approval.
+
+## Code change checklist
+
+Before considering any code change complete, verify all of the following:
+
+1. **Lint and format** — run `uv run ruff check --fix .` and `uv run ruff format .` to fix lint issues and enforce consistent formatting.
+2. **Tests are written** — new or changed functionality must have corresponding tests.
+3. **All tests pass** — run the full test suite (`uv run pytest`) and confirm zero failures.
+4. **Documentation is updated** — update this file (CLAUDE.md), CLI help text, and any other relevant docs to reflect the change.

hoshi_astro-1.7.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Trey Gonsoulin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hoshi_astro-1.7.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: hoshi-astro
+Version: 1.7.0
+Summary: Real-sky astrology birth chart CLI.
+Project-URL: Homepage, https://github.com/trey-gonsoulin/hoshi
+Project-URL: Repository, https://github.com/trey-gonsoulin/hoshi
+Project-URL: Changelog, https://github.com/trey-gonsoulin/hoshi/blob/main/CHANGELOG.md
+License: MIT License
+        
+        Copyright (c) 2026 Trey Gonsoulin
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: certifi>=2026.6.17
+Requires-Dist: geopy>=2.0
+Requires-Dist: pydantic>=2.8
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: rich>=10.0.0
+Requires-Dist: skyfield>=1.49
+Requires-Dist: typer>=0.12.4
+Description-Content-Type: text/markdown
+
+# Hoshi
+
+A CLI for astrological charting, with a focus on real-sky astrology. Inspired by [Nuastro](https://nuastro.com).
+
+Traditional astrology divides the sky into 12 equal 30° signs. Real-sky astrology uses the actual IAU constellation boundaries — 13 unequal signs along the ecliptic, including Ophiuchus — which makes charting by hand significantly more difficult. Hoshi handles the calculation, using JPL-grade ephemerides ([Skyfield](https://rhodesmill.org/skyfield/) DE421 for planets, JPL Horizons for Chiron and the lunar nodes).
+
+## Setup
+
+Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).
+
+```sh
+uv sync
+uv tool install --editable .     # puts `hoshi` on your PATH (~/.local/bin/hoshi)
+```
+
+`--editable` means source changes take effect immediately. If you change `pyproject.toml` dependencies, re-run with `--reinstall`. To remove: `uv tool uninstall hoshi`.
+
+On first run, Skyfield downloads `de421.bsp` (~17 MB) into the current directory. Chiron and lunar (node/Lilith) lookups hit JPL Horizons and are cached in `~/.cache/hoshi/`.
+
+## Commands
+
+```sh
+hoshi chart add      NAME DATE [TIME] [--lat LAT] [--lon LON] [--tz TZ] [--mode MODE] [--houses SYS]
+                                      [--details] [--aspects] [--group-by category|sign|house]
+                                      [--cusps] [--force]
+hoshi chart show     NAME|DATE [TIME] [--lat LAT --lon LON] ...
+                                      [--format table|json] [--compare-houses]
+hoshi chart cusps    NAME|DATE [TIME] [--lat LAT --lon LON] ... [--mode MODE] [--houses SYS]
+hoshi chart transits NAME [DATE [TIME]] [--tz TZ] [--mode MODE] [--houses SYS]
+                                        [--details] [--aspects] [--natal]
+hoshi chart compare  NAME1 NAME2        [--mode MODE] [--houses SYS] [--aspects] [--details]
+hoshi chart list
+hoshi chart delete   NAME [--yes]
+```
+
+`NAME|DATE` — pass a saved chart name, or a `YYYY-MM-DD` date with `--lat`/`--lon` for a one-off chart.
+
+`--lat` and `--lon` are optional for `chart add` — omit either or both if the birth location is unknown. If time is also omitted, only the date is stored. Placements computed from unknown inputs are shown in yellow with a warning; angles and houses are omitted entirely when time or location is unknown.
+
+## Options
+
+### `--mode`
+
+| Mode | Description |
+|------|-------------|
+| `realsky` (default) | IAU real-sky boundaries — 13 unequal signs including Ophiuchus |
+| `tropical` | Standard 12 equal 30° signs from the vernal equinox |
+| `vedic` | Sidereal: tropical longitudes minus the Lahiri ayanamsa |
+
+### `--houses`
+
+| System | Description |
+|--------|-------------|
+| `porphyry` (default) | Trisects the quadrants |
+| `equal` | Equal 30° houses from the Ascendant |
+| `placidus` | Time-based Placidus division |
+| `arc13` | 13-arc wheel with widths matching the IAU constellation boundaries |
+
+### `--details`
+
+Expands the display to include all six angles (Asc, MC, IC, Dsc, Vertex, Antivertex), true lunar nodes, Black Moon Lilith, seven Hermetic lots, planetary dignities, and element/modality tallies.
+
+### `--aspects`
+
+Prints aspect tables grouped by type (Major / Minor / Micro). Without `--details`, aspects are computed for planets + Ascendant only; with `--details`, all chart bodies are included.
+
+### `--group-by sign|house`
+
+Alternative layout grouping bodies by zodiac sign or house instead of category. `--group-by house` labels each house with its cusp sign and includes empty houses.
+
+### `--format json`
+
+Outputs a mode-specific JSON summary instead of the Rich table. Includes body placements, house assignments, and cusp longitudes. Useful for scripting or piping into other tools. When time or location is unknown, the JSON includes a `"warnings"` array and an `"approximate": true` flag on affected body entries.
+
+## Bodies
+
+### Planets
+Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, Chiron
+
+### Angles
+Ascendant, Midheaven (MC), Imum Coeli (IC), Descendant, Vertex, Antivertex
+
+### Calculated points
+- **N.Node / S.Node** — True (osculating) lunar nodes from JPL Horizons
+- **Lilith** — True Black Moon Lilith: ascending node + argument of perigee + 180°
+
+### Hermetic lots
+Fortune, Spirit, Eros, Necessity, Courage, Victory, Nemesis
+
+## Aspects
+
+| Class | Aspects | Orb |
+|-------|---------|-----|
+| Major | Conjunction (0°), Opposition (180°), Trine (120°), Square (90°), Sextile (60°) | 4° |
+| Minor | Inconjunct (150°), Semi-sextile (30°), Semi-square (45°), Sesquiquadrate (135°) | 2° |
+| Micro | Quintile (72°), Bi-quintile (144°), Septile (360°/7) | 1° |
+
+## Dignities
+
+The Planets table in `--details` shows a dignity indicator per planet:
+
+| Symbol | Dignity |
+|--------|---------|
+| ⊕ | Domicile |
+| △ | Exaltation |
+| ▽ | Detriment |
+| ✕ | Fall |
+
+Assignments follow standard conventions adapted for the 13-sign real-sky scheme (Chiron domicile = Ophiuchus).
+
+## Transits
+
+```sh
+hoshi chart transits person               # current moment vs natal
+hoshi chart transits person 2026-01-01    # specific date (noon UTC)
+hoshi chart transits person 2026-01-01 14:30 --tz America/Chicago
+hoshi chart transits person --natal       # side-by-side natal vs transit table
+hoshi chart transits person --aspects     # inter-aspects (natal × transit)
+```
+
+Computes current (or specified date) planetary positions and places them against the saved natal chart. The house column (`H`) always shows which **natal house** each transiting planet falls in, using the natal chart's cusps.
+
+`--natal` adds a side-by-side table showing each body's natal sign/degree alongside its current transit sign/degree. `--details` and `--aspects` work the same as in other commands.
+
+## Synastry
+
+```sh
+hoshi chart compare person1 person2 --aspects
+hoshi chart compare person1 person2 --aspects --details
+```
+
+Computes inter-aspects between two saved charts. Body selection respects `--details` the same way single-chart aspects do.
+
+## Accuracy notes
+
+### Reference frame
+
+All ecliptic longitudes are in the **equinox of date** frame, matching standard astrological convention. Skyfield's `ecliptic_latlon()` defaults to J2000, so `epoch=t` is passed explicitly. The IAU constellation boundaries are J2000-fixed; Hoshi applies the precession offset at lookup time so sign assignments stay consistent with the of-date planet positions.
+
+### Per-body accuracy
+
+- **Planets**: Skyfield + JPL DE421 — sub-arcsecond
+- **Chiron**: Horizons OBSERVER ephemeris, cached per minute
+- **Nodes / Lilith**: Horizons ELEMENTS API (Moon osculating elements), cached per minute
+- **Angles / cusps**: standard formulas with a linear obliquity model — accurate to under 1′ for 20th–21st century dates
+- **Lahiri ayanamsa**: linear approximation anchored at J2000 — adequate for chart display
+
+## Project layout
+
+```
+hoshi/
+  ephemeris.py   Skyfield positions, Horizons fetch, JSON cache helpers
+  zodiac.py      IAU real-sky boundaries, tropical and sidereal placements
+  houses.py      Placidus, Porphyry, Equal, Arc-13 cusps; angles
+  points.py      True lunar nodes, Black Moon Lilith, Hermetic lots
+  chart.py       Chart.build() — assembles all bodies
+  aspects.py     Aspect detection (single-chart and inter-chart)
+  dignities.py   Dignities table, element/modality tallies
+  store.py       JSON persistence for named charts (./charts/)
+  cli.py         Typer entry point
+```