astro_chart 0.2.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 203914237dcef72fb6ebc852749cf78811321155c0a509c0c8f711c1646cf7da
-  data.tar.gz: 87661219e2c6f29aa8b9330a5af0a4408ce65d342899a3e085ea3dee9a9f43f2
+  metadata.gz: 373643f3dc987aeb880aad6a15a5dd6a509367683c7ee1463ce7086b3e06980f
+  data.tar.gz: ec28b6b542ae7aaaa03997e744718b62dcf6a69c4372e1fcdb5196cb87110e4e
 SHA512:
-  metadata.gz: 81b2fd730e85708ecb9a9264bbfbd7bee4d6ea848c3554b12f4f98303a6f1f9432e7713e071191193035facb0a46f3c886efc1d7767c27711eb9384990766c6c
-  data.tar.gz: bd6534cf3b77dcd81e9b800a343cc594a08e48bfbc8419024b897e59af9f0beef41c4c6d3bdc01d1011c7568659c8322c9b71ff3f2f1cefb8c2931eb4e17aca3
+  metadata.gz: e5a812f264e71b82bbe09489d7098254b29f0e7fb648c2eb84aa244091d7e62cebab9cfaa7420da59b44392227bc3dc1b110c1aaa6f6dbe02de60ab6a80e5a3a
+  data.tar.gz: 9c8e709366b24a5c28db55223c68edbfe1e705f9b9ec4d95f1e5dae1a6a72e6d8419597d900c80f832126b2bb53c930ddf636d4e7db93bc4ca7208346f8e8905

data/CHANGELOG.md

@@ -1,5 +1,127 @@
 # Changelog
 
+## 0.5.1 (2026-08-07)
+
+**Ecliptic latitude → accurate astrocartography.** Additive.
+
+- New `AstroChart::Ephemeris.ecliptic_latlon(jd, id)` — apparent geocentric
+  ecliptic [longitude, latitude] for the Sun, Moon, VSOP87 planets and Pluto
+  (the geocentric vector was already computed; latitude was simply discarded).
+- `Astrocartography.lines` now forms RA/Dec from each body's **true** ecliptic
+  latitude instead of β = 0, so the Moon and Pluto lines (β up to ~5° / ~17°)
+  are placed correctly. The longitude methods delegate to the new latitude-
+  aware ones, so planetary longitudes remain byte-identical (Swiss oracle spec
+  still passes).
+
+## 0.5.0 (2026-08-07)
+
+**Astrocartography (星象地圖).** All pure Ruby, additive.
+
+- New `AstroChart::Astrocartography.lines(jd)` — the relocational map lines for
+  the ten bodies at a birth instant: the MC and IC meridian longitudes, and
+  the ASC (rising) and DSC (setting) horizon curves as latitude/longitude
+  segments (broken where a body is circumpolar). Built from the body's RA/Dec
+  and Greenwich apparent sidereal time; verified independently (body altitude
+  ≈ 0 along every ASC/DSC point, LST = RA on the MC). Ecliptic latitude is
+  approximated as 0 (exact for the Sun; largest error for the Moon/Pluto).
+
+## 0.4.0 (2026-08-06)
+
+**Traditional dignities, transit timing, two more house systems, minor
+aspects, four new configurations, antiscia, draconic charts, solar arc,
+lunar & annual predictive tools.** All pure Ruby, additive and
+backward-compatible.
+
+- **Minor aspects**: `Aspects.calculate(a, b, minor: true)` also matches
+  十二分相 (30°), 半四分相 (45°), 補八分相 (135°) and 補十二分相 (quincunx,
+  150°). Default stays major-only; minor aspects carry tighter orbs and never
+  shadow a major one.
+- **New aspect patterns** in `Patterns.detect` (and every `Chart#generate`
+  output): 上帝之指 (Yod: sextile base + quincunx apex), 風箏 (Kite: a 大三角
+  plus an opposing/sextiling focal body, reported alongside the trine), 神祕
+  矩形 (Mystic Rectangle: two oppositions joined by sextiles and trines) and
+  星群 (Stellium: 3+ bodies in one sign). Existing 大三角/T三角/大十字 output is
+  unchanged; the node-axis exclusion rules extend to the new configurations.
+- **Antiscia**: `Points.antiscion` (reflection across the 巨蟹–摩羯 solstice
+  axis) and `Points.contra_antiscion` (across the 牡羊–天秤 equinox axis).
+- **Draconic charts (龍盤)**: new `AstroChart::Draconic` — `.positions` shifts
+  every longitude so the natal 北交點 sits at 0° 牡羊; `.chart` adds draconic
+  signs, in-sign degrees and inter-aspects.
+- **Two more house systems**: Equal (`"E"`, from the ascendant) and Porphyry
+  (`"O"`, quadrant trisection), joining Placidus (`"P"`) and Whole Sign
+  (`"W"`). Both are pure geometry off the ASC/MC and are defined at every
+  latitude |lat| < 90° (including inside the polar circle, where Placidus
+  raises). Ord aliases 69/79 mirror the C-extension int argument.
+- **Essential dignities (必然尊貴)**: new `AstroChart::Dignities` — 廟/旺/三分性/
+  界/外觀 with the traditional rulerships and Dorothean triplicities.
+  `.of(planet, longitude, sect:)` reports a planet's dignities/debilities and
+  Lilly-weighted score (+5/+4/+3/+2/+1); `.almuten(longitude, sect:)` returns
+  the winning planet at a degree; plus `.domicile_ruler`/`detriment_ruler`/
+  `exaltation_ruler`/`fall_ruler`/`triplicity_ruler`/`term_ruler`/`face_ruler`.
+  界 ships both 埃及界 (Egyptian, `scheme: :egyptian`, the default) and 托勒密界
+  (Ptolemaic, `scheme: :ptolemaic`); both are cross-validated against Astrolog
+  and the Egyptian table matches several independent references.
+- **Annual profection (小限法)**: new `AstroChart::Profection` — `.annual(asc,
+  age)` and `.at(asc, birth_date, target_date)` give the profected house/sign
+  and Lord of the Year (年主星).
+- **Transit timing (行運精確時點)**: new `AstroChart::TransitTiming.events` —
+  the exact UTC instants in a date range when a transiting body perfects an
+  aspect to a natal point, found by bracket-and-bisect on the ephemeris
+  (robust through retrograde stations, so all three passes of an outer-planet
+  contact are caught). `minor:`, `step_days:` and `bodies:` options.
+- **Solar arc directions (太陽弧推運)**: new `AstroChart::SolarArc.directions`
+  — directs the whole chart rigidly by the secondary-progressed Sun's arc and
+  reports directed-to-natal aspects.
+- **Lunar returns (月亮回歸)**: new `AstroChart::LunarReturn.for_date` — the
+  chart at the Moon's monthly return to its natal longitude, relocatable like
+  the solar return.
+
+## 0.3.0 (2026-07-24)
+
+**Predictive & comparison modules, whole-sign houses, retrograde flags,
+derived points, pattern detection.** All pure Ruby, MIT.
+
+- **Whole-sign houses**: `Chart.new(..., house_system: "W")` ("P" Placidus
+  remains the default; anything else raises `ArgumentError`). Whole-sign
+  works at all latitudes |lat| < 90° (including polar latitudes, where
+  Placidus still raises); Placidus output is byte-identical to 0.2.0.
+  `Ephemeris.houses` / `Pure.houses` accept `"W"` too.
+- **Retrograde flags**: every planet entry in `Chart#generate` gains
+  `"retrograde" => true/false` (central-difference daily motion via the new
+  `Ephemeris.speed(jd, id)` / `Ephemeris.retrograde?(jd, id)`). 太陽/月亮
+  are hard-false, 南交點 mirrors 北交點, derived/ruler points are false.
+  Within half a day of a body's valid ephemeris window edge (e.g. the
+  Pluto series' 1885–2099 range) the speed stencil falls back to a
+  one-sided difference, so edge-of-range charts still generate.
+- **Derived points** (`AstroChart::Points`): 福點 (Part of Fortune,
+  day/night formula; sect judged from the horizon — ASC–DSC axis — so it
+  is independent of the display house system) and 莉莉絲 (mean Black Moon
+  Lilith, Meeus mean lunar apogee + 180°, verified < 0.13° vs Swiss
+  Ephemeris across 1900–2050). Both appended to `Chart#generate` planets,
+  before the ruler points.
+- **Transits** (`AstroChart::Transits`): `.at(jd)` sky snapshot;
+  `.against(natal, jd, orb_limit: 3.0)` places transiting bodies in natal
+  houses and lists transit-to-natal aspects sorted by orb.
+- **Secondary progressions** (`AstroChart::Progressions`):
+  `.secondary(natal, "YYYY-MM-DD", orb_limit: 1.0)` — day-for-a-year
+  progressed positions, natal house placement, aspects to natal.
+- **Composite charts** (`AstroChart::Composite`): `.between(a, b)` —
+  shorter-arc midpoint chart of two natal charts, with internal aspects.
+- **Solar returns** (`AstroChart::SolarReturn`): `.for_year(natal, year,
+  latitude:, longitude:, timezone:)` — Newton-iterated exact return
+  instant, full relocated chart at that moment.
+- **Aspect patterns** (`AstroChart::Patterns.detect`): 大三角 (with
+  element), T三角 (with apex), 大十字; node-axis oppositions excluded
+  from opposition legs; 大十字 subsumes its own T三角s; an opposition
+  squared by the node axis is reported as a single T三角 (apex 北交點)
+  rather than mirrored 北/南交點 twins. `Chart#generate` now includes
+  `"patterns"`.
+- **Element statistics** (`AstroChart::Stats.elements`): 火土風水 element
+  and 基本固定變動 modality counts over the 10 classical planets.
+  `Chart#generate` now includes `"element_stats"` and `"house_system"`.
+- `Houses.calculate` now takes the house system as a keyword
+  (`system: "P"`).
+
 ## 0.2.0 (2026-07-24)
 
 **License change: AGPL-3.0 → MIT.**

data/README.md

@@ -0,0 +1,417 @@
+<p align="center">
+  <img src="logo.png" alt="AstroChart — Pure-Ruby astrology chart calculation" width="600">
+</p>
+
+# AstroChart
+
+Pure-Ruby gem for astrology chart calculation: apparent planetary
+longitudes, four house systems (Placidus, whole-sign, equal, Porphyry),
+retrograde flags, major & minor aspects, derived points (福點/莉莉絲/映點),
+aspect patterns, element statistics, essential dignities & almuten,
+synastry, transits, transit timing, secondary progressions, solar arc
+directions, composite & draconic charts, solar & lunar returns, and annual
+profection.
+
+**No C extension, no external data files, MIT licensed.** Implemented from
+public formulas (Jean Meeus, *Astronomical Algorithms* 2nd ed.; VSOP87D;
+ELP-2000/82B), verified against Swiss Ephemeris to < 0.014° (most bodies
+< 0.001°) across 1900–2026 with zero zodiac sign flips.
+
+## Hosted Service（線上服務）
+
+A live web UI and open JSON API built on this gem:
+
+- **Web 星盤查詢**: https://astro-chart-api.fly.dev/ （本命盤、合盤、行運、二次推運、組合盤、太陽回歸，繁體中文）
+- **API 文件**: https://astro-chart-api.fly.dev/docs
+- Currently in open beta: no API key, no rate limit, free. CORS enabled.
+
+```bash
+curl -X POST https://astro-chart-api.fly.dev/api/v1/charts \
+  -H "Content-Type: application/json" \
+  -d '{"birth_date":"1990-01-01","birth_time":"12:00",
+       "latitude":25.033,"longitude":121.5654,"timezone":"Asia/Taipei"}'
+```
+
+Endpoints: `POST /api/v1/charts` (natal chart), `POST /api/v1/synastry`
+(合盤), `POST /api/v1/transits` (行運), `POST /api/v1/progressions`
+(二次推運), `POST /api/v1/composite` (組合盤), `POST /api/v1/solar-return`
+(太陽回歸), `GET /api/v1/cities` (城市搜尋), `GET /api/v1/health`.
+The hosted web app and MCP server live in a separate repository and depend
+on `astro_chart` as a normal gem.
+
+## Installation
+
+```ruby
+gem "astro_chart", "~> 0.3"
+```
+
+Then `bundle install`. Nothing to compile.
+
+## Usage
+
+```ruby
+require "astro_chart"
+
+chart = AstroChart::Chart.new(
+  birth_date: "1990-01-01",
+  birth_time: "12:00",
+  latitude:   25.0330,
+  longitude:  121.5654,
+  timezone:   "Asia/Taipei",
+  house_system: "P"          # "P" Placidus (default) or "W" Whole Sign
+)
+
+result = chart.generate
+```
+
+### Return Value
+
+`generate` returns a Hash with string keys:
+
+```ruby
+{
+  "input" => {
+    "birth_date"  => "1990-01-01",
+    "birth_time"  => "12:00",
+    "coordinates" => { "latitude" => 25.033, "longitude" => 121.5654 },
+    "timezone"    => "Asia/Taipei"
+  },
+  "chart" => {
+    "ascendant" => {
+      "zodiac"       => "牡羊座",
+      "degree"       => 16.4422,
+      "total_degree" => 16.4422
+    },
+    "house_system" => "P",
+    "planets" => [
+      {
+        "planet"       => "太陽",
+        "zodiac"       => "摩羯座",
+        "house"        => 9,
+        "degree"       => 10.4744,
+        "total_degree" => 280.4744,
+        "retrograde"   => false,
+        "aspects"      => [
+          { "planet" => "土星", "aspect_type" => "合相", "orb" => 5.14 }
+        ]
+      },
+      # ... 月亮, 水星, 金星, 火星, 木星, 土星, 天王星, 海王星, 冥王星,
+      #     北交點, 南交點, 福點, 莉莉絲,
+      #     北交點定位星, 南交點定位星, 上升星座定位星  (17 entries)
+    ],
+    "houses" => [
+      { "house_number" => 1, "degree" => 16.4422, "zodiac" => "牡羊座" },
+      # ... 2-12
+    ],
+    "patterns" => [
+      { "pattern_type" => "T三角", "planets" => ["太陽", "月亮", "火星"],
+        "apex" => "火星" }
+      # 大三角 (with "element"), T三角/上帝之指/風箏 (with "apex"), 大十字,
+      # 神祕矩形, 星群 (with "zodiac")
+    ],
+    "element_stats" => {
+      "elements"   => { "火" => 1, "土" => 5, "風" => 2, "水" => 2 },
+      "modalities" => { "基本" => 6, "固定" => 3, "變動" => 1 }
+    }
+  }
+}
+```
+
+### Planets Included
+
+太陽, 月亮, 水星, 金星, 火星, 木星, 土星, 天王星, 海王星, 冥王星, 北交點（真交點）, 南交點
+
+Plus derived points 福點 (Part of Fortune) and 莉莉絲 (mean Black Moon
+Lilith), and three ruler points: 北交點定位星, 南交點定位星, 上升星座定位星
+— 17 entries total, in that order.
+
+Every entry carries `"retrograde"` (central-difference daily motion;
+太陽/月亮 and derived/ruler points are always `false`, 南交點 mirrors
+北交點).
+
+### House Systems
+
+Four systems, via `Chart.new(..., house_system: ...)`:
+
+| Code | System | Notes |
+|------|--------|-------|
+| `"P"` | Placidus (default) | time-based; undefined inside the polar circle (raises) |
+| `"W"` | Whole Sign | cusps on sign boundaries from the ascendant's sign |
+| `"E"` | Equal | cusp 1 = ASC, then +30°; the true MC is still reported |
+| `"O"` | Porphyry | quadrant trisection between the four angles |
+
+Any other value raises `ArgumentError`. `W`/`E`/`O` are pure ASC/MC geometry
+and are defined at every latitude |lat| < 90° — including polar latitudes,
+where Placidus is undefined. (`Ephemeris.houses` also accepts the ord aliases
+`80`/`87`/`69`/`79`.)
+
+### Aspects
+
+Major: 合相 (0°, orb 15°), 六分相 (60°, orb 6°), 四分相 (90°, orb 8°), 三分相 (120°, orb 8°), 對分相 (180°, orb 10°).
+
+Minor (opt-in via `Aspects.calculate(a, b, minor: true)`): 十二分相 (30°), 半四分相 (45°), 補八分相 (135°), 補十二分相/quincunx (150°) — tighter orbs, and they never shadow a major aspect.
+
+### Synastry (合盤)
+
+```ruby
+result = AstroChart::Synastry.between(chart_a, chart_b, orb_limit: 6.0)
+
+result["aspects"]
+#=> [{ "a_planet" => "太陽", "b_planet" => "月亮",
+#      "aspect_type" => "三分相", "orb" => 1.23 }, ...]  # sorted by orb
+
+result["a_planets_in_b_houses"]  #=> { "太陽" => 7, ... }  (house overlay)
+result["b_planets_in_a_houses"]  #=> { "月亮" => 12, ... }
+```
+
+Lower-level: `Synastry.cross_aspects(positions_a, positions_b)` and
+`Synastry.house_overlay(positions, cusps)` work on raw longitude hashes.
+
+### Transits (行運)
+
+```ruby
+jd = AstroChart::TimeConversion.to_julian_day("2026-07-24", "12:00", "Asia/Taipei")
+
+AstroChart::Transits.at(jd)
+#=> { "太陽" => 121.9, ... }  # sky snapshot, 12 bodies
+
+result = AstroChart::Transits.against(natal_chart, jd, orb_limit: 3.0)
+result["planets"]  # 12 transiting bodies with "natal_house"
+result["aspects"]  # [{ "transit_planet" => "土星", "natal_planet" => "太陽",
+                   #    "aspect_type" => "四分相", "orb" => 1.23 }, ...] sorted by orb
+```
+
+### Secondary Progressions (二次推運)
+
+```ruby
+result = AstroChart::Progressions.secondary(natal_chart, "2026-07-24", orb_limit: 1.0)
+result["progressed_jd"]     # day-for-a-year progressed Julian Day
+result["years_elapsed"]     # e.g. 36.56
+result["planets"]           # progressed positions + natal house placement
+result["aspects_to_natal"]  # [{ "progressed_planet" => ..., "natal_planet" => ... }]
+```
+
+### Composite Charts (組合盤)
+
+```ruby
+result = AstroChart::Composite.between(chart_a, chart_b)
+result["planets"]  # shorter-arc midpoints of the 12 bodies
+result["aspects"]  # aspects among the composite positions, sorted by orb
+```
+
+(No composite houses — midpoint houses are not well-defined.)
+
+### Solar Returns (太陽回歸)
+
+```ruby
+result = AstroChart::SolarReturn.for_year(natal_chart, 2026)
+result["return_jd"]        # exact JD (UT) the Sun returns to its natal longitude
+result["return_time_utc"]  # "2026-07-03T05:12:34Z"
+result["chart"]            # full chart at that instant (relocate with
+                           # latitude:/longitude:/timezone: overrides)
+```
+
+### Transit Timing (行運精確時點)
+
+The exact UTC instants, within a date range, when a transiting body perfects
+an aspect to a natal point — the "when" that `Transits.against` (a snapshot)
+can't give:
+
+```ruby
+events = AstroChart::TransitTiming.events(natal_chart, "2026-01-01", "2026-12-31")
+events.first
+#=> { "transit_planet" => "土星", "natal_planet" => "太陽",
+#     "aspect_type" => "四分相", "jd" => 2461...,
+#     "time_utc" => "2026-03-14T07:22:10Z", "transit_zodiac" => "牡羊座",
+#     "retrograde" => false }
+```
+
+Found by bracket-and-bisect on the ephemeris, so it is robust through
+retrograde stations — all three passes of an outer-planet contact are caught.
+Options: `minor:` (also time the minor aspects), `step_days:` (sampling
+stride, default 1.0), `bodies:` (restrict transiting bodies, e.g. drop `"月亮"`
+to avoid the Moon's monthly hits). Events are sorted by time.
+
+### Solar Arc Directions (太陽弧推運)
+
+```ruby
+result = AstroChart::SolarArc.directions(natal_chart, "2026-07-24")
+result["arc"]              # degrees the chart is directed (~1° per year of life)
+result["planets"]          # every natal point advanced rigidly by the arc
+result["aspects_to_natal"] # directed→natal aspects, sorted by orb
+```
+
+The arc is the secondary-progressed Sun's travel since birth; unlike secondary
+progressions, the whole chart moves at that single rate.
+
+### Lunar Returns (月亮回歸)
+
+```ruby
+result = AstroChart::LunarReturn.for_date(natal_chart, "2026-07-24")
+result["return_jd"]        # JD (UT) of the lunar return nearest the date
+result["return_time_utc"]  # "2026-07-31T09:54:22Z"
+result["chart"]            # full chart at that instant (relocatable)
+```
+
+The monthly (~27.32-day) analogue of the solar return.
+
+### Draconic Charts (龍盤)
+
+```ruby
+positions = AstroChart::Planets.calculate_positions(jd)  # or any { name => longitude }
+AstroChart::Draconic.positions(positions, north_node)    # shift so 北交點 = 0° 牡羊
+AstroChart::Draconic.chart(positions, north_node)
+#=> { "planets" => [{ "planet" =>, "zodiac" =>, "degree" =>, "total_degree" => }...],
+#     "aspects" => [...] }   # draconic signs + inter-aspects
+```
+
+### Essential Dignities (必然尊貴)
+
+Traditional 廟/旺/三分性/界/外觀 with the traditional rulerships, Dorothean
+triplicities, and both Egyptian and Ptolemaic terms. Pure lookup tables.
+
+```ruby
+D = AstroChart::Dignities
+
+D.of("火星", 5.0)                    # 火星 at 5° 牡羊
+#=> { "planet" => "火星", "dignities" => ["廟", "外觀"],
+#     "debilities" => [], "score" => 6 }
+
+D.almuten(5.0, sect: :day)          #=> { "planet" => "太陽", "score" => 7, "tied" => ["太陽"] }
+
+D.term_ruler(13.0, scheme: :ptolemaic) #=> "金星"   (:egyptian is the default)
+D.domicile_ruler(215)  #=> "火星"    D.triplicity_ruler(5, sect: :night) #=> "木星"
+D.face_ruler(120)      #=> "土星"    D.exaltation_ruler(5)               #=> "太陽"
+```
+
+Dignities score +5/+4/+3/+2/+1 (廟/旺/三分性/界/外觀); debilities 陷 (detriment),
+弱 (fall). Rulers are the seven traditional planets (dignity theory predates
+the outer planets), so these differ from `Zodiac.ruler`'s modern rulerships.
+
+### Annual Profection (小限法)
+
+```ruby
+AstroChart::Profection.annual(ascendant_longitude, 36)
+#=> { "age" => 36, "profected_house" => 1, "profected_sign" => "牡羊座",
+#     "year_lord" => "火星" }
+
+AstroChart::Profection.at(ascendant_longitude, "1990-01-01", "2026-08-05")
+# derives the age from the two dates, then profects
+```
+
+Each completed year advances one whole sign from the ascendant; the
+traditional ruler of the profected sign is the Lord of the Year (年主星).
+
+### Patterns & Element Stats
+
+Included in `Chart#generate` output, or usable standalone on any
+`{ name => longitude }` hash:
+
+```ruby
+AstroChart::Patterns.detect(positions)
+#=> [{ "pattern_type" => "大三角",   "planets" => [...], "element" => "火" },
+#    { "pattern_type" => "T三角",    "planets" => [...], "apex" => "火星" },
+#    { "pattern_type" => "大十字",   "planets" => [...] },
+#    { "pattern_type" => "上帝之指", "planets" => [...], "apex" => "水星" },  # Yod
+#    { "pattern_type" => "風箏",     "planets" => [...], "apex" => "月亮" },  # Kite
+#    { "pattern_type" => "神祕矩形", "planets" => [...] },                   # Mystic Rectangle
+#    { "pattern_type" => "星群",     "planets" => [...], "zodiac" => "牡羊座" }] # Stellium
+
+AstroChart::Stats.elements(positions)
+#=> { "elements"   => { "火" => 3, "土" => 2, "風" => 3, "水" => 2 },
+#    "modalities" => { "基本" => 4, "固定" => 3, "變動" => 3 } }
+```
+
+### Derived Points
+
+```ruby
+AstroChart::Points.lilith(jd)  #=> 216.47 (mean Black Moon Lilith, 0-360)
+AstroChart::Points.fortune(asc: asc, sun: sun, moon: moon, day_chart: true)
+AstroChart::Points.day_chart?(sun_longitude, cusps)  #=> true / false / nil
+AstroChart::Points.day_chart_from_horizon?(sun_longitude, ascendant)
+# Chart#generate determines 福點 sect from the horizon (ASC-DSC axis),
+# so the same birth instant yields the same 福點 under "P" and "W".
+
+# 映點 / 反映點 (antiscia / contra-antiscia)
+AstroChart::Points.antiscion(15.0)        #=> 165.0  (across the 巨蟹–摩羯 axis)
+AstroChart::Points.contra_antiscion(15.0) #=> 345.0  (across the 牡羊–天秤 axis)
+```
+
+### Individual Modules
+
+```ruby
+# Zodiac sign from ecliptic longitude
+AstroChart::Zodiac.sign_name(280.5)  #=> "摩羯座"
+AstroChart::Zodiac.ruler("摩羯座")    #=> "土星"
+
+# Aspect between two positions
+AstroChart::Aspects.calculate(0, 90)  #=> ["四分相", 0.0]
+
+# Julian Day conversion
+jd = AstroChart::TimeConversion.to_julian_day("1990-01-01", "12:00", "Asia/Taipei")
+
+# Raw ephemeris access (planet ids follow the SE convention)
+AstroChart::Ephemeris.julday(2000, 1, 1, 12.0)
+AstroChart::Ephemeris.calc_ut(jd, AstroChart::Ephemeris::PLANETS["太陽"])
+AstroChart::Ephemeris.houses(jd, 25.033, 121.565)        # Placidus
+AstroChart::Ephemeris.houses(jd, 25.033, 121.565, "W")   # Whole Sign
+AstroChart::Ephemeris.houses(jd, 25.033, 121.565, "E")   # Equal
+AstroChart::Ephemeris.houses(jd, 25.033, 121.565, "O")   # Porphyry
+
+# Daily motion / retrograde detection
+AstroChart::Ephemeris.speed(jd, 2)        #=> degrees/day (negative = retrograde)
+AstroChart::Ephemeris.retrograde?(jd, 2)  #=> true / false
+```
+
+## Backends
+
+The default backend is `:pure` (pure Ruby, always available). The legacy
+Swiss Ephemeris C extension backend can still be selected **if you compile
+and provide the extension yourself** — it is no longer shipped with this gem
+(it is AGPL-licensed, see 0.1.x):
+
+```ruby
+AstroChart.backend          #=> :pure
+AstroChart.backend = :swiss # raises LoadError unless the extension is present
+```
+
+## Accuracy & Limits
+
+- Verified against Swiss Ephemeris (Moshier), 1900–2026, 400 samples per
+  body: Sun ≤ 0.0002°, Moon ≤ 0.0013°, planets ≤ 0.0006°, Pluto ≤ 0.0005°,
+  true node ≤ 0.014°, house cusps ≤ 0.0003°. Zero zodiac sign flips.
+- 莉莉絲 (mean Black Moon Lilith) uses the Meeus mean lunar perigee
+  polynomial + 180°; verified ≤ 0.13° vs Swiss Ephemeris across 1900–2050.
+- Whole-sign cusps verified identical to Swiss Ephemeris, including inside
+  the polar circle. Retrograde flags verified against Swiss central-difference
+  speeds (Mercury 2020–2024, every sample matches).
+- Transit / progression / solar-return positions verified within 0.003° of
+  Swiss Ephemeris at sampled instants (1962–2033).
+- Pluto series is valid 1885–2099 (raises outside this range).
+- **House systems: Placidus (`"P"`), Whole Sign (`"W"`), Equal (`"E"`) and
+  Porphyry (`"O"`)** on the pure backend. Other systems raise `ArgumentError`.
+  Polar latitudes (|lat| ≳ 66.5°) raise `AstroChart::Pure::Core::DomainError`
+  on Placidus — it is undefined there; use whole-sign, equal or Porphyry for
+  polar charts. Porphyry shares the four angles with Placidus and trisects
+  each quadrant; verified against those invariants.
+
+## Geocoding
+
+This gem does **not** handle geocoding. Pass latitude, longitude, and
+timezone directly. For city-to-coordinate conversion, use the
+[geocoder](https://github.com/alexreisner/geocoder) gem or your own lookup
+table.
+
+## Development
+
+```bash
+bundle install
+rake spec
+```
+
+The hosted web app and MCP server that build on this gem live in a
+separate repository and depend on `astro_chart` as a normal gem.
+
+## License
+
+MIT

data/astro_chart.gemspec

@@ -4,16 +4,20 @@ Gem::Specification.new do |spec|
   spec.name          = "astro_chart"
   spec.version       = AstroChart::VERSION
   spec.authors       = ["Huang Yudi"]
-  spec.summary       = "Pure-Ruby natal chart calculation (planets, Placidus houses, aspects, synastry)"
-  spec.description   = "Natal astrology chart calculation in pure Ruby: apparent planetary longitudes " \
-                       "(VSOP87D, ELP-2000/82B moon, Meeus Pluto), Placidus houses, aspects and synastry. " \
+  spec.summary       = "Pure-Ruby astrology chart calculation (planets, Placidus/whole-sign houses, " \
+                       "aspects, synastry, transits, progressions, composite, solar returns)"
+  spec.description   = "Astrology chart calculation in pure Ruby: apparent planetary longitudes " \
+                       "(VSOP87D, ELP-2000/82B moon, Meeus Pluto), Placidus and whole-sign houses, " \
+                       "retrograde flags, aspects, derived points (Part of Fortune, mean Lilith), " \
+                       "aspect-pattern detection and element statistics, plus synastry, transits, " \
+                       "secondary progressions, composite charts and solar returns. " \
                        "No C extension, no external data files. Implemented from public formulas " \
                        "(Meeus, Astronomical Algorithms 2nd ed.)."
   spec.homepage      = "https://github.com/morriedig/astro_chart"
   spec.license       = "MIT"
   spec.required_ruby_version = ">= 3.0"
 
-  spec.files         = Dir["lib/**/*.rb", "LICENSE", "CHANGELOG.md", "astro_chart.gemspec"]
+  spec.files         = Dir["lib/**/*.rb", "README.md", "LICENSE", "CHANGELOG.md", "astro_chart.gemspec"]
   spec.require_paths = ["lib"]
 
   spec.add_dependency "tzinfo", "~> 2.0"

data/lib/astro_chart/aspects.rb

@@ -1,6 +1,6 @@
 module AstroChart
   module Aspects
-    # Major aspects: angle => [name, max_orb]
+    # Major aspects (托勒密相位): angle => [name, max_orb]
     MAJOR = {
       60  => ["六分相", 6],   # Sextile
       90  => ["四分相", 8],   # Square
@@ -8,11 +8,31 @@ module AstroChart
       180 => ["對分相", 10],  # Opposition
     }.freeze
 
+    # Minor aspects (次要相位): angle => [name, max_orb]. Opt-in via
+    # `minor: true` — they carry tighter orbs and are checked only after the
+    # major set, so no minor aspect can shadow a major one (the angle bands
+    # do not overlap given these orbs).
+    #
+    #   30°  十二分相  (semi-sextile)
+    #   45°  半四分相  (semi-square)
+    #   135° 補八分相  (sesquiquadrate)
+    #   150° 補十二分相 (quincunx / inconjunct)
+    MINOR = {
+      30  => ["十二分相", 2],
+      45  => ["半四分相", 2],
+      135 => ["補八分相", 2],
+      150 => ["補十二分相", 3],
+    }.freeze
+
     CONJUNCTION_ORB = 15
 
     # Calculate the aspect between two ecliptic positions.
+    #
+    # By default only conjunction + the four major aspects are considered
+    # (backward-compatible). Pass `minor: true` to also match the minor set.
+    #
     # Returns [aspect_name, orb] or [nil, nil].
-    def self.calculate(pos1, pos2)
+    def self.calculate(pos1, pos2, minor: false)
       return [nil, nil] if pos1.nil? || pos2.nil?
 
       p1 = pos1 % 360.0
@@ -34,6 +54,15 @@ module AstroChart
         end
       end
 
+      if minor
+        MINOR.each do |angle, (name, max_orb)|
+          orb = (diff - angle).abs
+          if orb <= max_orb
+            return [name, orb.round(2)]
+          end
+        end
+      end
+
       [nil, nil]
     end
   end