kerykeion 5.0.1__py3-none-any.whl → 5.1.8__py3-none-any.whl

{kerykeion-5.0.1.dist-info → kerykeion-5.1.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kerykeion
-Version: 5.0.1
+Version: 5.1.8
 Summary: A Python library for astrological calculations, including natal charts, houses, planetary aspects, and SVG chart generation.
 Project-URL: Homepage, https://www.kerykeion.net/
 Project-URL: Repository, https://github.com/g-battaglia/kerykeion
@@ -68,7 +68,7 @@ Here is an example of a birthchart:
 
 ## **Web API**
 
-If you want to use Kerykeion in a web application, you can try the dedicated web API:
+If you want to use Kerykeion in a web application or for commercial or *closed-source* purposes, you can try the dedicated web API:
 
 **[AstrologerAPI](https://rapidapi.com/gbattaglia/api/astrologer/pricing)**
 
@@ -86,12 +86,17 @@ Maintaining this project requires substantial time and effort. The Astrologer AP
 - [**Donate**](#donate)
 - [Table of Contents](#table-of-contents)
 - [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Documentation Map](#documentation-map)
 - [Basic Usage](#basic-usage)
 - [Generate a SVG Chart](#generate-a-svg-chart)
   - [Birth Chart](#birth-chart)
   - [External Birth Chart](#external-birth-chart)
   - [Synastry Chart](#synastry-chart)
   - [Transit Chart](#transit-chart)
+  - [Solar Return Chart (Dual Wheel)](#solar-return-chart-dual-wheel)
+  - [Solar Return Chart (Single Wheel)](#solar-return-chart-single-wheel)
+  - [Lunar Return Chart](#lunar-return-chart)
   - [Composite Chart](#composite-chart)
 - [Wheel Only Charts](#wheel-only-charts)
   - [Birth Chart](#birth-chart-1)
@@ -99,6 +104,7 @@ Maintaining this project requires substantial time and effort. The Astrologer AP
   - [Synastry Chart](#synastry-chart-1)
   - [Change the Output Directory](#change-the-output-directory)
   - [Change Language](#change-language)
+  - [Minified SVG](#minified-svg)
   - [SVG without CSS Variables](#svg-without-css-variables)
   - [Grid Only SVG](#grid-only-svg)
 - [Report Generator](#report-generator)
@@ -148,6 +154,48 @@ Kerykeion requires **Python 3.9** or higher.
 pip3 install kerykeion
 ```
 
+## Quick Start
+
+```python
+from pathlib import Path
+from kerykeion import AstrologicalSubjectFactory
+from kerykeion.chart_data_factory import ChartDataFactory
+from kerykeion.charts.chart_drawer import ChartDrawer
+
+subject = AstrologicalSubjectFactory.from_birth_data(
+    name="Example Person",
+    year=1990, month=7, day=15,
+    hour=10, minute=30,
+    lng=12.4964,
+    lat=41.9028,
+    tz_str="Europe/Rome",
+    online=False,
+)
+
+chart_data = ChartDataFactory.create_natal_chart_data(subject)
+chart_drawer = ChartDrawer(chart_data=chart_data)
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+
+chart_drawer.save_svg(output_path=output_dir, filename="example-natal")
+print("Chart saved to", (output_dir / "example-natal.svg").resolve())
+```
+
+This script shows the recommended workflow:
+1. Create an `AstrologicalSubject` with explicit coordinates and timezone (offline mode).
+2. Build a `ChartDataModel` through `ChartDataFactory`.
+3. Render the SVG via `ChartDrawer`, saving it to a controlled folder (`charts_output`).
+
+Use the same pattern for synastry, composite, transit, or return charts by swapping the factory method.
+
+## Documentation Map
+
+- **README (this file):** Quick start, common recipes, and v5 migration notes.
+- **`site-docs/` (offline Markdown guides):** Deep dives for each factory (`chart_data_factory.md`, `charts.md`, `planetary_return_factory.md`, etc.) with runnable snippets. Run `python scripts/test_markdown_snippets.py site-docs` to validate them locally.
+- **[Auto-generated API Reference](https://www.kerykeion.net/pydocs/kerykeion.html):** Detailed model and function signatures straight from the codebase.
+- **[Kerykeion website](https://www.kerykeion.net/docs/):** Rendered documentation with additional context, tutorials, and showcase material.
+
 ## Basic Usage
 
 Below is a simple example illustrating the creation of an astrological subject and retrieving astrological details:
@@ -157,7 +205,13 @@ from kerykeion import AstrologicalSubjectFactory
 
 # Create an instance of the AstrologicalSubjectFactory class.
 # Arguments: Name, year, month, day, hour, minutes, city, nation
-john = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
+john = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # Retrieve information about the Sun:
 print(john.sun.model_dump_json())
@@ -172,6 +226,9 @@ print(john.moon.element)
 # > 'Air'
 ```
 
+> **Working offline:** pass `online=False` and specify `lng`, `lat`, and `tz_str` as shown above.  
+> **Working online:** set `online=True` and provide `city`, `nation`, and a valid GeoNames username (see `AstrologicalSubjectFactory.from_birth_data()` for details).
+
 **To avoid using GeoNames online, specify longitude, latitude, and timezone instead of city and nation:**
 
 ```python
@@ -186,6 +243,8 @@ john = AstrologicalSubjectFactory.from_birth_data(
 
 ## Generate a SVG Chart
 
+All chart-rendering examples below create a local `charts_output/` folder so the tests can write without touching your home directory. Feel free to change the path when integrating into your own projects.
+
 To generate a chart, use the `ChartDataFactory` to pre-compute chart data, then `ChartDrawer` to create the visualization. This two-step process ensures clean separation between astrological calculations and chart rendering.
 
 **Tip:**
@@ -195,40 +254,60 @@ To improve compatibility across different applications, you can use the `remove_
 ### Birth Chart
 
 ```python
+from pathlib import Path
 from kerykeion import AstrologicalSubjectFactory
 from kerykeion.chart_data_factory import ChartDataFactory
 from kerykeion.charts.chart_drawer import ChartDrawer
 
 # Step 1: Create subject
-john = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
+john = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # Step 2: Pre-compute chart data
 chart_data = ChartDataFactory.create_natal_chart_data(john)
 
 # Step 3: Create visualization
 birth_chart_svg = ChartDrawer(chart_data=chart_data)
-birth_chart_svg.save_svg()
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+birth_chart_svg.save_svg(output_path=output_dir, filename="john-lennon-natal")
 ```
 
-The SVG file will be saved in the home directory.
+The SVG file is saved under `charts_output/john-lennon-natal.svg`.
 ![John Lennon Birth Chart](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/main/tests/charts/svg/John%20Lennon%20-%20Natal%20Chart.svg)
 
 ### External Birth Chart
 
 ```python
+from pathlib import Path
 from kerykeion import AstrologicalSubjectFactory
 from kerykeion.chart_data_factory import ChartDataFactory
 from kerykeion.charts.chart_drawer import ChartDrawer
 
 # Step 1: Create subject
-birth_chart = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
+birth_chart = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # Step 2: Pre-compute chart data for external natal chart
-chart_data = ChartDataFactory.create_external_natal_chart_data(birth_chart)
+chart_data = ChartDataFactory.create_natal_chart_data(birth_chart)
 
 # Step 3: Create visualization
 birth_chart_svg = ChartDrawer(chart_data=chart_data)
-birth_chart_svg.save_svg()
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+birth_chart_svg.save_svg(output_path=output_dir, filename="john-lennon-natal-external")
 ```
 
 ![John Lennon External Birth Chart](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/main/tests/charts/svg/John%20Lennon%20-%20ExternalNatal%20-%20Natal%20Chart.svg)
@@ -236,20 +315,36 @@ birth_chart_svg.save_svg()
 ### Synastry Chart
 
 ```python
+from pathlib import Path
 from kerykeion import AstrologicalSubjectFactory
 from kerykeion.chart_data_factory import ChartDataFactory
 from kerykeion.charts.chart_drawer import ChartDrawer
 
 # Step 1: Create subjects
-first = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
-second = AstrologicalSubjectFactory.from_birth_data("Paul McCartney", 1942, 6, 18, 15, 30, "Liverpool", "GB")
+first = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
+second = AstrologicalSubjectFactory.from_birth_data(
+    "Paul McCartney", 1942, 6, 18, 15, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # Step 2: Pre-compute synastry chart data
 chart_data = ChartDataFactory.create_synastry_chart_data(first, second)
 
 # Step 3: Create visualization
 synastry_chart = ChartDrawer(chart_data=chart_data)
-synastry_chart.save_svg()
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+synastry_chart.save_svg(output_path=output_dir, filename="lennon-mccartney-synastry")
 ```
 
 ![John Lennon and Paul McCartney Synastry](https://www.kerykeion.net/img/examples/synastry-chart.svg)
@@ -257,35 +352,192 @@ synastry_chart.save_svg()
 ### Transit Chart
 
 ```python
+from pathlib import Path
 from kerykeion import AstrologicalSubjectFactory
 from kerykeion.chart_data_factory import ChartDataFactory
 from kerykeion.charts.chart_drawer import ChartDrawer
 
 # Step 1: Create subjects
-transit = AstrologicalSubjectFactory.from_birth_data("Transit", 2025, 6, 8, 8, 45, "Atlanta", "US")
-subject = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
+transit = AstrologicalSubjectFactory.from_birth_data(
+    "Transit", 2025, 6, 8, 8, 45,
+    lng=-84.3880,
+    lat=33.7490,
+    tz_str="America/New_York",
+    online=False,
+)
+subject = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # Step 2: Pre-compute transit chart data
 chart_data = ChartDataFactory.create_transit_chart_data(subject, transit)
 
 # Step 3: Create visualization
 transit_chart = ChartDrawer(chart_data=chart_data)
-transit_chart.save_svg()
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+transit_chart.save_svg(output_path=output_dir, filename="john-lennon-transit")
 ```
 
 ![John Lennon Transit Chart](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/main/tests/charts/svg/John%20Lennon%20-%20Transit%20Chart.svg)
 
+### Solar Return Chart (Dual Wheel)
+
+```python
+from pathlib import Path
+from kerykeion import AstrologicalSubjectFactory
+from kerykeion.planetary_return_factory import PlanetaryReturnFactory
+from kerykeion.chart_data_factory import ChartDataFactory
+from kerykeion.charts.chart_drawer import ChartDrawer
+
+# Step 1: Create natal subject
+john = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
+
+# Step 2: Calculate Solar Return subject (offline example with manual coordinates)
+return_factory = PlanetaryReturnFactory(
+    john,
+    lng=-2.9833,
+    lat=53.4000,
+    tz_str="Europe/London",
+    online=False
+)
+solar_return_subject = return_factory.next_return_from_year(1964, "Solar")
+
+# Step 3: Pre-compute return chart data (dual wheel: natal + solar return)
+chart_data = ChartDataFactory.create_return_chart_data(john, solar_return_subject)
+
+# Step 4: Create visualization
+solar_return_chart = ChartDrawer(chart_data=chart_data)
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+solar_return_chart.save_svg(output_path=output_dir, filename="john-lennon-solar-return-dual")
+```
+
+![John Lennon Solar Return Chart (Dual Wheel)](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/main/tests/charts/svg/John%20Lennon%20-%20DualReturnChart%20Chart%20-%20Solar%20Return.svg)
+
+### Solar Return Chart (Single Wheel)
+
+```python
+from pathlib import Path
+from kerykeion import AstrologicalSubjectFactory
+from kerykeion.planetary_return_factory import PlanetaryReturnFactory
+from kerykeion.chart_data_factory import ChartDataFactory
+from kerykeion.charts.chart_drawer import ChartDrawer
+
+# Step 1: Create natal subject
+john = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
+
+# Step 2: Calculate Solar Return subject (offline example with manual coordinates)
+return_factory = PlanetaryReturnFactory(
+    john,
+    lng=-2.9833,
+    lat=53.4000,
+    tz_str="Europe/London",
+    online=False
+)
+solar_return_subject = return_factory.next_return_from_year(1964, "Solar")
+
+# Step 3: Build a single-wheel return chart
+chart_data = ChartDataFactory.create_single_wheel_return_chart_data(solar_return_subject)
+
+# Step 4: Create visualization
+single_wheel_chart = ChartDrawer(chart_data=chart_data)
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+single_wheel_chart.save_svg(output_path=output_dir, filename="john-lennon-solar-return-single")
+```
+
+![John Lennon Solar Return Chart (Single Wheel)](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/main/tests/charts/svg/John%20Lennon%20Solar%20Return%20-%20SingleReturnChart%20Chart.svg)
+
+### Lunar Return Chart
+
+```python
+from pathlib import Path
+from kerykeion import AstrologicalSubjectFactory
+from kerykeion.planetary_return_factory import PlanetaryReturnFactory
+from kerykeion.chart_data_factory import ChartDataFactory
+from kerykeion.charts.chart_drawer import ChartDrawer
+
+# Step 1: Create natal subject
+john = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
+
+# Step 2: Calculate Lunar Return subject
+return_factory = PlanetaryReturnFactory(
+    john,
+    lng=-2.9833,
+    lat=53.4000,
+    tz_str="Europe/London",
+    online=False
+)
+lunar_return_subject = return_factory.next_return_from_year(1964, "Lunar")
+
+# Step 3: Build a dual wheel (natal + lunar return)
+lunar_return_chart_data = ChartDataFactory.create_return_chart_data(john, lunar_return_subject)
+dual_wheel_chart = ChartDrawer(chart_data=lunar_return_chart_data)
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+dual_wheel_chart.save_svg(output_path=output_dir, filename="john-lennon-lunar-return-dual")
+
+# Optional: create a single-wheel lunar return
+single_wheel_data = ChartDataFactory.create_single_wheel_return_chart_data(lunar_return_subject)
+single_wheel_chart = ChartDrawer(chart_data=single_wheel_data)
+single_wheel_chart.save_svg(output_path=output_dir, filename="john-lennon-lunar-return-single")
+```
+
+![John Lennon Lunar Return Chart (Dual Wheel)](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/main/tests/charts/svg/John%20Lennon%20-%20DualReturnChart%20Chart%20-%20Lunar%20Return.svg)
+
+![John Lennon Lunar Return Chart (Single Wheel)](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/main/tests/charts/svg/John%20Lennon%20Lunar%20Return%20-%20SingleReturnChart%20Chart.svg)
+
 ### Composite Chart
 
 ```python
+from pathlib import Path
 from kerykeion import CompositeSubjectFactory, AstrologicalSubjectFactory
 from kerykeion.chart_data_factory import ChartDataFactory
 from kerykeion.charts.chart_drawer import ChartDrawer
 
-# Step 1: Create subjects
-angelina = AstrologicalSubjectFactory.from_birth_data("Angelina Jolie", 1975, 6, 4, 9, 9, "Los Angeles", "US", lng=-118.15, lat=34.03, tz_str="America/Los_Angeles")
+# Step 1: Create subjects (offline configuration)
+angelina = AstrologicalSubjectFactory.from_birth_data(
+    "Angelina Jolie", 1975, 6, 4, 9, 9,
+    lng=-118.2437,
+    lat=34.0522,
+    tz_str="America/Los_Angeles",
+    online=False,
+)
 
-brad = AstrologicalSubjectFactory.from_birth_data("Brad Pitt", 1963, 12, 18, 6, 31, "Shawnee", "US", lng=-96.56, lat=35.20, tz_str="America/Chicago")
+brad = AstrologicalSubjectFactory.from_birth_data(
+    "Brad Pitt", 1963, 12, 18, 6, 31,
+    lng=-96.7069,
+    lat=35.3273,
+    tz_str="America/Chicago",
+    online=False,
+)
 
 # Step 2: Create composite subject
 factory = CompositeSubjectFactory(angelina, brad)
@@ -296,7 +548,10 @@ chart_data = ChartDataFactory.create_composite_chart_data(composite_model)
 
 # Step 4: Create visualization
 composite_chart = ChartDrawer(chart_data=chart_data)
-composite_chart.save_svg()
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+composite_chart.save_svg(output_path=output_dir, filename="jolie-pitt-composite")
 ```
 
 ![Angelina Jolie and Brad Pitt Composite Chart](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/main/tests/charts/svg/Angelina%20Jolie%20and%20Brad%20Pitt%20Composite%20Chart%20-%20Composite%20Chart.svg)
@@ -308,19 +563,29 @@ For _all_ the charts, you can generate a wheel-only chart by using the method `m
 ### Birth Chart
 
 ```python
+from pathlib import Path
 from kerykeion import AstrologicalSubjectFactory
 from kerykeion.chart_data_factory import ChartDataFactory
 from kerykeion.charts.chart_drawer import ChartDrawer
 
 # Step 1: Create subject
-birth_chart = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
+birth_chart = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # Step 2: Pre-compute chart data
 chart_data = ChartDataFactory.create_natal_chart_data(birth_chart)
 
 # Step 3: Create visualization
 birth_chart_svg = ChartDrawer(chart_data=chart_data)
-birth_chart_svg.save_wheel_only_svg_file()
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+birth_chart_svg.save_wheel_only_svg_file(output_path=output_dir, filename="john-lennon-natal-wheel")
 ```
 
 ![John Lennon Birth Chart](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/main/tests/charts/svg/John%20Lennon%20-%20Wheel%20Only%20-%20Natal%20Chart%20-%20Wheel%20Only.svg)
@@ -328,22 +593,29 @@ birth_chart_svg.save_wheel_only_svg_file()
 ### Wheel Only Birth Chart (External)
 
 ```python
+from pathlib import Path
 from kerykeion import AstrologicalSubjectFactory
 from kerykeion.chart_data_factory import ChartDataFactory
 from kerykeion.charts.chart_drawer import ChartDrawer
 
 # Step 1: Create subject
-birth_chart = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
+birth_chart = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # Step 2: Pre-compute external natal chart data
-chart_data = ChartDataFactory.create_external_natal_chart_data(birth_chart)
+chart_data = ChartDataFactory.create_natal_chart_data(birth_chart)
 
-# Step 3: Create visualization
-birth_chart_svg = ChartDrawer(chart_data=chart_data)
-birth_chart_svg.save_wheel_only_svg_file(
-    wheel_only=True,
-    wheel_only_external=True
-)
+# Step 3: Create visualization (external wheel view)
+birth_chart_svg = ChartDrawer(chart_data=chart_data, external_view=True)
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+birth_chart_svg.save_wheel_only_svg_file(output_path=output_dir, filename="john-lennon-natal-wheel-external")
 ```
 
 ![John Lennon Birth Chart](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/main/tests/charts/svg/John%20Lennon%20-%20Wheel%20External%20Only%20-%20ExternalNatal%20Chart%20-%20Wheel%20Only.svg)
@@ -351,20 +623,36 @@ birth_chart_svg.save_wheel_only_svg_file(
 ### Synastry Chart
 
 ```python
+from pathlib import Path
 from kerykeion import AstrologicalSubjectFactory
 from kerykeion.chart_data_factory import ChartDataFactory
 from kerykeion.charts.chart_drawer import ChartDrawer
 
 # Step 1: Create subjects
-first = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
-second = AstrologicalSubjectFactory.from_birth_data("Paul McCartney", 1942, 6, 18, 15, 30, "Liverpool", "GB")
+first = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
+second = AstrologicalSubjectFactory.from_birth_data(
+    "Paul McCartney", 1942, 6, 18, 15, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # Step 2: Pre-compute synastry chart data
 chart_data = ChartDataFactory.create_synastry_chart_data(first, second)
 
 # Step 3: Create visualization
 synastry_chart = ChartDrawer(chart_data=chart_data)
-synastry_chart.save_wheel_only_svg_file()
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+synastry_chart.save_wheel_only_svg_file(output_path=output_dir, filename="lennon-mccartney-synastry-wheel")
 ```
 
 ![John Lennon and Paul McCartney Synastry](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/main/tests/charts/svg/John%20Lennon%20-%20Wheel%20Synastry%20Only%20-%20Synastry%20Chart%20-%20Wheel%20Only.svg)
@@ -374,20 +662,37 @@ synastry_chart.save_wheel_only_svg_file()
 To save the SVG file in a custom location, specify the `output_path` parameter in `save_svg()`:
 
 ```python
+from pathlib import Path
 from kerykeion import AstrologicalSubjectFactory
 from kerykeion.chart_data_factory import ChartDataFactory
 from kerykeion.charts.chart_drawer import ChartDrawer
 
 # Step 1: Create subjects
-first = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
-second = AstrologicalSubjectFactory.from_birth_data("Paul McCartney", 1942, 6, 18, 15, 30, "Liverpool", "GB")
+first = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
+second = AstrologicalSubjectFactory.from_birth_data(
+    "Paul McCartney", 1942, 6, 18, 15, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # Step 2: Pre-compute synastry chart data
 chart_data = ChartDataFactory.create_synastry_chart_data(first, second)
 
 # Step 3: Create visualization with custom output directory
 synastry_chart = ChartDrawer(chart_data=chart_data)
-synastry_chart.save_svg(output_path=".")
+
+output_dir = Path("my_charts")
+output_dir.mkdir(exist_ok=True)
+synastry_chart.save_svg(output_path=output_dir)
+print("Saved to", (output_dir / f"{synastry_chart.first_obj.name} - Synastry Chart.svg").resolve())
 ```
 
 ### Change Language
@@ -395,12 +700,19 @@ synastry_chart.save_svg(output_path=".")
 You can switch chart language by passing `chart_language` to the `ChartDrawer` class:
 
 ```python
+from pathlib import Path
 from kerykeion import AstrologicalSubjectFactory
 from kerykeion.chart_data_factory import ChartDataFactory
 from kerykeion.charts.chart_drawer import ChartDrawer
 
 # Step 1: Create subject
-birth_chart = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
+birth_chart = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # Step 2: Pre-compute chart data
 chart_data = ChartDataFactory.create_natal_chart_data(birth_chart)
@@ -410,13 +722,31 @@ birth_chart_svg = ChartDrawer(
     chart_data=chart_data,
     chart_language="IT"  # Change to Italian
 )
-birth_chart_svg.save_svg()
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+birth_chart_svg.save_svg(output_path=output_dir, filename="john-lennon-natal-it")
+```
 
 You can also provide custom labels (or introduce a brand-new language) by passing
 a dictionary to `language_pack`. Only the keys you supply are merged on top of the
 built-in strings:
 
 ```python
+from pathlib import Path
+from kerykeion import AstrologicalSubjectFactory
+from kerykeion.chart_data_factory import ChartDataFactory
+from kerykeion.charts.chart_drawer import ChartDrawer
+
+birth_chart = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
+chart_data = ChartDataFactory.create_natal_chart_data(birth_chart)
+
 custom_labels = {
     "PT": {
         "info": "Informações",
@@ -424,12 +754,15 @@ custom_labels = {
     }
 }
 
-birth_chart_svg = ChartDrawer(
+custom_chart = ChartDrawer(
     chart_data=chart_data,
     chart_language="PT",
     language_pack=custom_labels["PT"],
 )
-```
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+custom_chart.save_svg(output_path=output_dir, filename="john-lennon-natal-pt")
 ```
 
 More details [here](https://www.kerykeion.net/docs/chart-language).
@@ -451,20 +784,32 @@ The available languages are:
 To generate a minified SVG, set `minify_svg=True` in the `makeSVG()` method:
 
 ```python
+from pathlib import Path
 from kerykeion import AstrologicalSubjectFactory
 from kerykeion.chart_data_factory import ChartDataFactory
 from kerykeion.charts.chart_drawer import ChartDrawer
 
 # Step 1: Create subject
-birth_chart = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
+birth_chart = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # Step 2: Pre-compute chart data
 chart_data = ChartDataFactory.create_natal_chart_data(birth_chart)
 
 # Step 3: Create visualization
 birth_chart_svg = ChartDrawer(chart_data=chart_data)
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
 birth_chart_svg.save_svg(
-    minify=True
+    output_path=output_dir,
+    filename="john-lennon-natal-minified",
+    minify=True,
 )
 ```
 
@@ -473,20 +818,32 @@ birth_chart_svg.save_svg(
 To generate an SVG without CSS variables, set `remove_css_variables=True` in the `makeSVG()` method:
 
 ```python
+from pathlib import Path
 from kerykeion import AstrologicalSubjectFactory
 from kerykeion.chart_data_factory import ChartDataFactory
 from kerykeion.charts.chart_drawer import ChartDrawer
 
 # Step 1: Create subject
-birth_chart = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
+birth_chart = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # Step 2: Pre-compute chart data
 chart_data = ChartDataFactory.create_natal_chart_data(birth_chart)
 
 # Step 3: Create visualization
 birth_chart_svg = ChartDrawer(chart_data=chart_data)
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
 birth_chart_svg.save_svg(
-    remove_css_variables=True
+    output_path=output_dir,
+    filename="john-lennon-natal-no-css-variables",
+    remove_css_variables=True,
 )
 ```
 
@@ -497,20 +854,36 @@ This will inline all styles and eliminate CSS variables, resulting in an SVG tha
 It's possible to generate a grid-only SVG, useful for creating a custom layout. To do this, use the `save_aspect_grid_only_svg_file()` method:
 
 ```python
+from pathlib import Path
 from kerykeion import AstrologicalSubjectFactory
 from kerykeion.chart_data_factory import ChartDataFactory
 from kerykeion.charts.chart_drawer import ChartDrawer
 
 # Step 1: Create subjects
-birth_chart = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
-second = AstrologicalSubjectFactory.from_birth_data("Paul McCartney", 1942, 6, 18, 15, 30, "Liverpool", "GB")
+birth_chart = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
+second = AstrologicalSubjectFactory.from_birth_data(
+    "Paul McCartney", 1942, 6, 18, 15, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # Step 2: Pre-compute synastry chart data
 chart_data = ChartDataFactory.create_synastry_chart_data(birth_chart, second)
 
 # Step 3: Create visualization with dark theme
 aspect_grid_chart = ChartDrawer(chart_data=chart_data, theme="dark")
-aspect_grid_chart.save_aspect_grid_only_svg_file()
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+aspect_grid_chart.save_aspect_grid_only_svg_file(output_path=output_dir, filename="lennon-mccartney-aspect-grid")
 ```
 
 ![John Lennon Birth Chart](https://raw.githubusercontent.com/g-battaglia/kerykeion/refs/heads/main/tests/charts/svg/John%20Lennon%20-%20Aspect%20Grid%20Only%20-%20Natal%20Chart%20-%20Aspect%20Grid%20Only.svg)
@@ -526,7 +899,11 @@ from kerykeion import ReportGenerator, AstrologicalSubjectFactory, ChartDataFact
 
 # Subject-only report
 subject = AstrologicalSubjectFactory.from_birth_data(
-    "Sample Natal", 1990, 7, 21, 14, 45, "Rome", "IT"
+    "Sample Natal", 1990, 7, 21, 14, 45,
+    lng=12.4964,
+    lat=41.9028,
+    tz_str="Europe/Rome",
+    online=False,
 )
 ReportGenerator(subject).print_report(include_aspects=False)
 
@@ -536,7 +913,11 @@ ReportGenerator(natal_data).print_report(max_aspects=10)
 
 # Dual-chart data (synastry, transit, dual return, …)
 partner = AstrologicalSubjectFactory.from_birth_data(
-    "Sample Partner", 1992, 11, 5, 9, 30, "Rome", "IT"
+    "Sample Partner", 1992, 11, 5, 9, 30,
+    lng=12.4964,
+    lat=41.9028,
+    tz_str="Europe/Rome",
+    online=False,
 )
 synastry_data = ChartDataFactory.create_synastry_chart_data(subject, partner)
 ReportGenerator(synastry_data).print_report(max_aspects=12)
@@ -558,11 +939,21 @@ Each report contains:
 All section helpers remain available for targeted output:
 
 ```python
+from kerykeion import ReportGenerator, AstrologicalSubjectFactory, ChartDataFactory
+
+subject = AstrologicalSubjectFactory.from_birth_data(
+    "Sample Natal", 1990, 7, 21, 14, 45,
+    lng=12.4964,
+    lat=41.9028,
+    tz_str="Europe/Rome",
+    online=False,
+)
+natal_data = ChartDataFactory.create_natal_chart_data(subject)
+
 report = ReportGenerator(natal_data)
-print(report.get_subject_data_report())
-print(report.get_celestial_points_report())
-print(report.get_elements_report())
-print(report.get_aspects_report(max_aspects=5))
+sections = report.generate_report(max_aspects=5).split("\n\n")
+for section in sections[:3]:
+    print(section)
 ```
 
 Refer to the refreshed [Report Documentation](https://www.kerykeion.net/report/) for end-to-end examples covering every supported chart model.
@@ -575,22 +966,32 @@ Kerykeion provides a unified `AspectsFactory` class for calculating astrological
 from kerykeion import AspectsFactory, AstrologicalSubjectFactory
 
 # Create astrological subjects
-jack = AstrologicalSubjectFactory.from_birth_data("Jack", 1990, 6, 15, 15, 15, "Roma", "IT")
-jane = AstrologicalSubjectFactory.from_birth_data("Jane", 1991, 10, 25, 21, 0, "Roma", "IT")
+jack = AstrologicalSubjectFactory.from_birth_data(
+    "Jack", 1990, 6, 15, 15, 15,
+    lng=12.4964,
+    lat=41.9028,
+    tz_str="Europe/Rome",
+    online=False,
+)
+jane = AstrologicalSubjectFactory.from_birth_data(
+    "Jane", 1991, 10, 25, 21, 0,
+    lng=12.4964,
+    lat=41.9028,
+    tz_str="Europe/Rome",
+    online=False,
+)
 
 # For single chart aspects (natal, return, composite, etc.)
-single_chart_aspects = AspectsFactory.single_chart_aspects(jack)
-print(f"Found {len(single_chart_aspects)} aspects in Jack's chart")
-print(single_chart_aspects[0])
-# Output: AspectModel with details like aspect type, orb, planets involved, etc.
+single_chart_result = AspectsFactory.single_chart_aspects(jack)
+print(f"Found {len(single_chart_result.aspects)} aspects in Jack's chart")
+print(single_chart_result.aspects[0])
 
 # For dual chart aspects (synastry, transits, comparisons, etc.)
-dual_chart_aspects = AspectsFactory.dual_chart_aspects(jack, jane)
-print(f"Found {len(dual_chart_aspects)} aspects between Jack and Jane's charts")
-print(dual_chart_aspects[0])
-# Output: AspectModel with cross-chart aspect details
+dual_chart_result = AspectsFactory.dual_chart_aspects(jack, jane)
+print(f"Found {len(dual_chart_result.aspects)} aspects between Jack and Jane's charts")
+print(dual_chart_result.aspects[0])
 
-# The factory returns structured AspectModel objects with properties like:
+# Each AspectModel includes:
 # - p1_name, p2_name: Planet/point names
 # - aspect: Aspect type (conjunction, trine, square, etc.)
 # - orbit: Orb tolerance in degrees
@@ -622,7 +1023,11 @@ You can refine the weighting without rebuilding the dictionary: pass lowercase p
 from kerykeion import AstrologicalSubjectFactory, ChartDataFactory
 
 subject = AstrologicalSubjectFactory.from_birth_data(
-    "Sample", 1986, 4, 12, 8, 45, "Bologna", "IT"
+    "Sample", 1986, 4, 12, 8, 45,
+    lng=11.3426,
+    lat=44.4949,
+    tz_str="Europe/Rome",
+    online=False,
 )
 
 # Equal weighting: every active point counts once
@@ -656,7 +1061,10 @@ By default, the zodiac type is **Tropical**. To use **Sidereal**, specify the si
 ```python
 johnny = AstrologicalSubjectFactory.from_birth_data(
     "Johnny Depp", 1963, 6, 9, 0, 0,
-    "Owensboro", "US",
+    lng=-87.1112,
+    lat=37.7719,
+    tz_str="America/Chicago",
+    online=False,
     zodiac_type="Sidereal",
     sidereal_mode="LAHIRI"
 )
@@ -673,8 +1081,11 @@ By default, houses are calculated using **Placidus**. Configure a different hous
 ```python
 johnny = AstrologicalSubjectFactory.from_birth_data(
     "Johnny Depp", 1963, 6, 9, 0, 0,
-    "Owensboro", "US",
-    houses_system="M"
+    lng=-87.1112,
+    lat=37.7719,
+    tz_str="America/Chicago",
+    online=False,
+    houses_system_identifier="M"
 )
 ```
 
@@ -691,7 +1102,10 @@ By default, Kerykeion uses the **Apparent Geocentric** perspective (the most sta
 ```python
 johnny = AstrologicalSubjectFactory.from_birth_data(
     "Johnny Depp", 1963, 6, 9, 0, 0,
-    "Owensboro", "US",
+    lng=-87.1112,
+    lat=37.7719,
+    tz_str="America/Chicago",
+    online=False,
     perspective_type="Heliocentric"
 )
 ```
@@ -718,43 +1132,56 @@ The Black & White theme renders glyphs, rings, and aspects in solid black on lig
 Here's an example of how to set the theme:
 
 ```python
+from pathlib import Path
 from kerykeion import AstrologicalSubjectFactory
 from kerykeion.chart_data_factory import ChartDataFactory
 from kerykeion.charts.chart_drawer import ChartDrawer
 
 # Step 1: Create subject
-dark_theme_subject = AstrologicalSubjectFactory.from_birth_data("John Lennon - Dark Theme", 1940, 10, 9, 18, 30, "Liverpool", "GB")
+dark_theme_subject = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon - Dark Theme", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # Step 2: Pre-compute chart data
 chart_data = ChartDataFactory.create_natal_chart_data(dark_theme_subject)
 
 # Step 3: Create visualization with dark high contrast theme
 dark_theme_natal_chart = ChartDrawer(chart_data=chart_data, theme="dark-high-contrast")
-dark_theme_natal_chart.save_svg()
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+dark_theme_natal_chart.save_svg(output_path=output_dir, filename="john-lennon-natal-dark-high-contrast")
 ```
 
 ![John Lennon](https://www.kerykeion.net/img/showcase/John%20Lennon%20-%20Dark%20-%20Natal%20Chart.svg)
 
 ## Alternative Initialization
 
-Create an `AstrologicalSubject` from a UTC ISO 8601 string:
-
-```python
-subject = AstrologicalSubject.get_from_iso_utc_time(
-    "Johnny Depp", "1963-06-09T05:00:00Z", "Owensboro", "US"
-)
-```
-
-If you set `online=True`, provide a `geonames_username` to allow city-based geolocation:
+Create an `AstrologicalSubjectModel` from a UTC ISO 8601 string:
 
 ```python
-from kerykeion.astrological_subject import AstrologicalSubjectFactory
+from kerykeion import AstrologicalSubjectFactory
 
-subject = AstrologicalSubject.get_from_iso_utc_time(
-    "Johnny Depp", "1963-06-09T05:00:00Z", "Owensboro", "US", online=True
+subject = AstrologicalSubjectFactory.from_iso_utc_time(
+    name="Johnny Depp",
+    iso_utc_time="1963-06-09T05:00:00Z",
+    city="Owensboro",
+    nation="US",
+    lng=-87.1112,
+    lat=37.7719,
+    tz_str="America/Chicago",
+    online=False,
 )
+
+print(subject.iso_formatted_local_datetime)
 ```
 
+If you prefer automatic geocoding, set `online=True` and provide your GeoNames credentials via `geonames_username`.
+
 ## Lunar Nodes (Rahu & Ketu)
 
 Kerykeion supports both **True** and **Mean** Lunar Nodes:
@@ -769,12 +1196,19 @@ In instances of the classes used to generate aspects and SVG charts, only the me
 Example:
 
 ```python
+from pathlib import Path
 from kerykeion import AstrologicalSubjectFactory
 from kerykeion.chart_data_factory import ChartDataFactory
 from kerykeion.charts.chart_drawer import ChartDrawer
 
 # Step 1: Create subject
-subject = AstrologicalSubjectFactory.from_birth_data("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
+subject = AstrologicalSubjectFactory.from_birth_data(
+    "John Lennon", 1940, 10, 9, 18, 30,
+    lng=-2.9833,
+    lat=53.4,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # Step 2: Pre-compute chart data with custom active points including true nodes
 chart_data = ChartDataFactory.create_natal_chart_data(
@@ -803,7 +1237,10 @@ chart_data = ChartDataFactory.create_natal_chart_data(
 
 # Step 3: Create visualization
 chart = ChartDrawer(chart_data=chart_data)
-chart.save_svg()
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+chart.save_svg(output_path=output_dir, filename="johnny-depp-custom-points")
 ```
 
 ## JSON Support
@@ -813,9 +1250,15 @@ You can serialize the astrological subject (the base data used throughout the li
 ```python
 from kerykeion import AstrologicalSubjectFactory
 
-johnny = AstrologicalSubjectFactory.from_birth_data("Johnny Depp", 1963, 6, 9, 0, 0, "Owensboro", "US")
+johnny = AstrologicalSubjectFactory.from_birth_data(
+    "Johnny Depp", 1963, 6, 9, 0, 0,
+    lng=-87.1112,
+    lat=37.7719,
+    tz_str="America/Chicago",
+    online=False,
+)
 
-print(johnny.json(dump=False, indent=2))
+print(johnny.model_dump_json(indent=2))
 ```
 
 ## Auto Generated Documentation
@@ -847,24 +1290,44 @@ The old class-based approach has been replaced with a modern factory pattern:
 **Old v4 API:**
 
 ```python
+from pathlib import Path
 from kerykeion import AstrologicalSubject, KerykeionChartSVG
 
 # v4 - Class-based approach
-subject = AstrologicalSubject("John", 1990, 1, 1, 12, 0, "London", "GB")
-chart = KerykeionChartSVG(subject)
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+
+subject = AstrologicalSubject(
+    "John", 1990, 1, 1, 12, 0,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
+chart = KerykeionChartSVG(subject, new_output_directory=output_dir)
 chart.makeSVG()
 ```
 
 **New v5 API:**
 
 ```python
+from pathlib import Path
 from kerykeion import AstrologicalSubjectFactory, ChartDataFactory, ChartDrawer
 
 # v5 - Factory-based approach with separation of concerns
-subject = AstrologicalSubjectFactory.from_birth_data("John", 1990, 1, 1, 12, 0, "London", "GB")
+subject = AstrologicalSubjectFactory.from_birth_data(
+    "John", 1990, 1, 1, 12, 0,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
 chart_data = ChartDataFactory.create_natal_chart_data(subject)
 drawer = ChartDrawer(chart_data=chart_data)
-drawer.save_svg()
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+drawer.save_svg(output_path=output_dir, filename="john-factory-demo")
 ```
 
 #### Pydantic 2 Models & Type Safety
@@ -873,7 +1336,7 @@ All data structures are now strongly typed Pydantic models:
 
 -   **`AstrologicalSubjectModel`**: Subject data with full validation
 -   **`ChartDataModel`**: Enriched chart data with elements, qualities, aspects
--   **`SingleChartAspectsModel` / `DualChartAspectsModel`**: Typed aspect collections
+-   **`AspectModel` list**: Raw aspect entries directly on `ChartDataModel.aspects`
 -   **`PlanetReturnModel`**: Planetary return data
 -   **`ElementDistributionModel`**: Element statistics (fire, earth, air, water)
 -   **`QualityDistributionModel`**: Quality statistics (cardinal, fixed, mutable)
@@ -970,11 +1433,27 @@ All lunar node fields have been renamed for clarity:
 **Migration example:**
 
 ```python
-# v4
-print(subject.mean_node)
-
-# v5
-print(subject.mean_north_lunar_node)
+from kerykeion import AstrologicalSubject, AstrologicalSubjectFactory
+
+# v4 alias (still available, emits DeprecationWarning)
+legacy_subject = AstrologicalSubject(
+    "John", 1990, 1, 1, 12, 0,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
+print(legacy_subject.mean_node)
+
+# v5 canonical name
+modern_subject = AstrologicalSubjectFactory.from_birth_data(
+    "John", 1990, 1, 1, 12, 0,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
+print(modern_subject.mean_north_lunar_node)
 ```
 
 #### 5. Axis Orb Filtering
@@ -988,16 +1467,43 @@ The two-step process (data + rendering) is now required:
 **Old v4:**
 
 ```python
-chart = KerykeionChartSVG(subject)
+from pathlib import Path
+from kerykeion import AstrologicalSubject, KerykeionChartSVG
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+
+subject = AstrologicalSubject(
+    "John", 1990, 1, 1, 12, 0,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
+chart = KerykeionChartSVG(subject, new_output_directory=output_dir)
 chart.makeSVG()
 ```
 
 **New v5:**
 
 ```python
+from pathlib import Path
+from kerykeion import AstrologicalSubjectFactory, ChartDataFactory
+from kerykeion.charts.chart_drawer import ChartDrawer
+
+subject = AstrologicalSubjectFactory.from_birth_data(
+    "John", 1990, 1, 1, 12, 0,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
 chart_data = ChartDataFactory.create_natal_chart_data(subject)
 drawer = ChartDrawer(chart_data=chart_data)
-drawer.save_svg()
+
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
+drawer.save_svg(output_path=output_dir, filename="john-v5-demo")
 ```
 
 #### 7. Aspects API Changes
@@ -1007,7 +1513,23 @@ Aspects are now calculated through the factory:
 **Old v4:**
 
 ```python
-from kerykeion import NatalAspects, SynastryAspects
+from kerykeion import AstrologicalSubjectFactory, NatalAspects, SynastryAspects
+
+subject = AstrologicalSubjectFactory.from_birth_data(
+    "John", 1990, 1, 1, 12, 0,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
+subject1 = subject
+subject2 = AstrologicalSubjectFactory.from_birth_data(
+    "Jane", 1990, 6, 5, 8, 30,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
 
 natal_aspects = NatalAspects(subject)
 synastry_aspects = SynastryAspects(subject1, subject2)
@@ -1016,12 +1538,30 @@ synastry_aspects = SynastryAspects(subject1, subject2)
 **New v5:**
 
 ```python
-from kerykeion import AspectsFactory
+from kerykeion import AstrologicalSubjectFactory, AspectsFactory
+
+subject = AstrologicalSubjectFactory.from_birth_data(
+    "John", 1990, 1, 1, 12, 0,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
+subject1 = subject
+subject2 = AstrologicalSubjectFactory.from_birth_data(
+    "Jane", 1990, 6, 5, 8, 30,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
 
 natal_aspects = AspectsFactory.single_chart_aspects(subject)
 synastry_aspects = AspectsFactory.dual_chart_aspects(subject1, subject2)
 ```
 
+Note (v5.1): The two lists `relevant_aspects` and `all_aspects` were unified into a single, cleaned list: `aspects`. If you previously used either property, switch to `aspects`. The legacy properties still work via the backward-compatibility layer but both return the same unified list.
+
 ### 🔄 Migration Guide
 
 #### Using the Backward Compatibility Layer
@@ -1031,7 +1571,13 @@ For a gradual migration, use the `kerykeion.backword` module:
 ```python
 from kerykeion import AstrologicalSubject  # Legacy wrapper
 
-subject = AstrologicalSubject("John Doe", 1990, 1, 1, 12, 0, "London", "GB")
+subject = AstrologicalSubject(
+    "John Doe", 1990, 1, 1, 12, 0,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
 
 # These still work but show DeprecationWarnings
 print(subject.mean_node)  # Maps to mean_north_lunar_node
@@ -1044,58 +1590,127 @@ print(subject.true_node)  # Maps to true_north_lunar_node
 
 1. **Update imports**
 
-    ```python
-    # Old
-    from kerykeion import AstrologicalSubject, KerykeionChartSVG
+```python
+# Old (v4)
+from kerykeion import AstrologicalSubject, KerykeionChartSVG
 
-    # New
-    from kerykeion import AstrologicalSubjectFactory, ChartDataFactory, ChartDrawer
-    ```
+# New (v5)
+from kerykeion import AstrologicalSubjectFactory, ChartDataFactory, ChartDrawer
+```
 
 2. **Update subject creation**
 
-    ```python
-    # Old
-    subject = AstrologicalSubject("John", 1990, 1, 1, 12, 0, "London", "GB")
+```python
+from kerykeion import AstrologicalSubject, AstrologicalSubjectFactory
+
+# Old (v4)
+subject = AstrologicalSubject(
+    "John", 1990, 1, 1, 12, 0,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
 
-    # New
-    subject = AstrologicalSubjectFactory.from_birth_data("John", 1990, 1, 1, 12, 0, "London", "GB")
-    ```
+# New (v5)
+subject = AstrologicalSubjectFactory.from_birth_data(
+    "John", 1990, 1, 1, 12, 0,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
+```
 
 3. **Update chart generation**
 
-    ```python
-    # Old
-    chart = KerykeionChartSVG(subject)
-    chart.makeSVG()
+```python
+from pathlib import Path
+from kerykeion import AstrologicalSubject, AstrologicalSubjectFactory, ChartDataFactory, KerykeionChartSVG
+from kerykeion.charts.chart_drawer import ChartDrawer
 
-    # New
-    chart_data = ChartDataFactory.create_natal_chart_data(subject)
-    drawer = ChartDrawer(chart_data=chart_data)
-    drawer.save_svg()
-    ```
+# Old (v4)
+legacy_subject = AstrologicalSubject(
+    "John", 1990, 1, 1, 12, 0,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
+output_dir = Path("charts_output")
+output_dir.mkdir(exist_ok=True)
 
-4. **Update field access** (lunar nodes)
+chart = KerykeionChartSVG(legacy_subject, new_output_directory=output_dir)
+chart.makeSVG()
 
-    ```python
-    # Old
-    print(subject.mean_node.position)
+# New (v5)
+modern_subject = AstrologicalSubjectFactory.from_birth_data(
+    "John", 1990, 1, 1, 12, 0,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
+chart_data = ChartDataFactory.create_natal_chart_data(modern_subject)
+drawer = ChartDrawer(chart_data=chart_data)
+drawer.save_svg(output_path=output_dir, filename="john-v5-migration")
+```
 
-    # New
-    print(subject.mean_north_lunar_node.position)
-    ```
+4. **Update field access** (lunar nodes)
 
-5. **Update aspects**
+```python
+from kerykeion import AstrologicalSubject, AstrologicalSubjectFactory
+
+# Old (v4)
+legacy_subject = AstrologicalSubject(
+    "John", 1990, 1, 1, 12, 0,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
+legacy_mean_node = legacy_subject.mean_node
+print(getattr(legacy_mean_node, "position", "Legacy mean node not active"))
+
+# New (v5)
+modern_subject = AstrologicalSubjectFactory.from_birth_data(
+    "John", 1990, 1, 1, 12, 0,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
+modern_mean_node = modern_subject.mean_north_lunar_node
+print(getattr(modern_mean_node, "position", "Modern mean node not active"))
+```
 
-    ```python
-    # Old
-    from kerykeion import NatalAspects
-    aspects = NatalAspects(subject)
+5. **Update aspects**
 
-    # New
-    from kerykeion import AspectsFactory
-    aspects = AspectsFactory.single_chart_aspects(subject)
-    ```
+```python
+from kerykeion import AstrologicalSubject, AstrologicalSubjectFactory, NatalAspects, AspectsFactory
+
+# Old (v4)
+legacy_subject = AstrologicalSubject(
+    "John", 1990, 1, 1, 12, 0,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
+legacy_aspects = NatalAspects(legacy_subject)
+print(f"Legacy aspects count: {len(legacy_aspects.relevant_aspects)}")
+
+# New (v5)
+modern_subject = AstrologicalSubjectFactory.from_birth_data(
+    "John", 1990, 1, 1, 12, 0,
+    lng=-0.1276,
+    lat=51.5074,
+    tz_str="Europe/London",
+    online=False,
+)
+modern_aspects = AspectsFactory.single_chart_aspects(modern_subject)
+print(f"Modern aspects count: {len(modern_aspects.aspects)}")
+```
 
 #### Automated Migration Script
 
@@ -1166,6 +1781,8 @@ Since the AstrologerAPI is an external third-party service, using it does _not_
 
 Contributions are welcome! Feel free to submit pull requests or report issues.
 
+By submitting a contribution, you agree to assign the copyright of that contribution to the maintainer. The project stays openly available under the AGPL for everyone, while the re-licensing option helps sustain future development. Your authorship remains acknowledged in the commit history and release notes.
+
 ## Citations
 
 If using Kerykeion in published or academic work, please cite as follows: