diff --git a/.github/workflows/wiki-sync.yml b/.github/workflows/wiki-sync.yml
new file mode 100644
index 0000000..974c6c6
--- /dev/null
+++ b/.github/workflows/wiki-sync.yml
@@ -0,0 +1,42 @@
+name: Sync Wiki
+
+on:
+  push:
+    branches: [main]
+    paths: [".wiki/**"]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Checkout wiki
+        id: clone_wiki
+        run: |
+          if git clone "https://x-access-token:${{ github.token }}@github.com/${{ github.repository }}.wiki.git" .wiki-remote 2>&1; then
+            echo "wiki_exists=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "wiki_exists=false" >> "$GITHUB_OUTPUT"
+            echo "Wiki not yet initialized — skipping sync. Initialize via GitHub web UI first."
+          fi
+
+      - name: Sync wiki pages
+        if: steps.clone_wiki.outputs.wiki_exists == 'true'
+        run: |
+          cp .wiki/*.md .wiki-remote/
+          cd .wiki-remote
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add -A
+          if git diff --cached --quiet; then
+            echo "No wiki changes to commit"
+          else
+            git commit -m "Sync wiki from repo"
+            git push origin HEAD:master
+          fi
diff --git a/.wiki/API-Reference.md b/.wiki/API-Reference.md
new file mode 100644
index 0000000..46b837f
--- /dev/null
+++ b/.wiki/API-Reference.md
@@ -0,0 +1,127 @@
+# API Reference
+
+## getTimes
+
+```dart
+PrayerTimes getTimes(
+  DateTime date,
+  double lat,
+  double lng,
+  double tz, {
+  double elevation = 0,
+  double temperature = 15,
+  double pressure = 1013.25,
+  bool hanafi = false,
+})
+```
+
+Computes all prayer times for a given date and location.
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `date` | `DateTime` | required | Local date (time-of-day ignored) |
+| `lat` | `double` | required | Latitude (-90 to 90, south negative) |
+| `lng` | `double` | required | Longitude (-180 to 180, west negative) |
+| `tz` | `double` | required | UTC offset in hours (e.g., -5 for EST) |
+| `elevation` | `double` | 0 | Observer elevation in meters |
+| `temperature` | `double` | 15 | Ambient temperature in Celsius |
+| `pressure` | `double` | 1013.25 | Atmospheric pressure in mbar |
+| `hanafi` | `bool` | false | Hanafi Asr (2x shadow ratio) vs Shafi'i (1x) |
+
+### PrayerTimes fields
+
+All time values are fractional hours in local time.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `qiyam` | `double` | Last third of the night (between Isha and Fajr) |
+| `fajr` | `double` | Dawn prayer |
+| `sunrise` | `double` | Sunrise |
+| `noon` | `double` | True solar noon |
+| `dhuhr` | `double` | Midday prayer (solar noon + small offset) |
+| `asr` | `double` | Afternoon prayer |
+| `maghrib` | `double` | Sunset prayer |
+| `isha` | `double` | Night prayer |
+| `angles` | `TwilightAngles` | The computed dynamic angles used for Fajr/Isha |
+
+---
+
+## getAngles
+
+```dart
+TwilightAngles getAngles(
+  DateTime date,
+  double lat,
+  double lng, {
+  double elevation = 0,
+  double temperature = 15,
+  double pressure = 1013.25,
+})
+```
+
+Computes dynamic twilight depression angles using the three-layer model:
+
+1. MCW seasonal base (piecewise-linear, latitude-dependent)
+2. Ephemeris corrections (Earth-Sun distance, Fourier season smoothing)
+3. Environmental corrections (elevation dip, atmospheric refraction)
+
+### TwilightAngles fields
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `fajrAngle` | `double` | Fajr depression angle (degrees, clipped to [10, 22]) |
+| `ishaAngle` | `double` | Isha depression angle (degrees, clipped to [10, 22]) |
+
+---
+
+## getSpa
+
+```dart
+SpaResult getSpa(
+  DateTime date,
+  double lat,
+  double lng,
+  double tz, {
+  double elevation = 0,
+  double temperature = 15,
+  double pressure = 1013.25,
+  List<double> customAngles = const [],
+})
+```
+
+Full NREL Solar Position Algorithm. Accurate to +/- 0.0003 degrees for zenith angle. Supports custom zenith angles for twilight calculations. This is a re-export from [nrel_spa](https://pub.dev/packages/nrel_spa).
+
+---
+
+## formatTime
+
+```dart
+String formatTime(double hours)
+```
+
+Converts a fractional-hour value to an `HH:MM:SS` string. Returns `"N/A"` for non-finite values (e.g., no sunrise at extreme latitudes).
+
+```dart
+print(formatTime(5.75));  // "05:45:00"
+print(formatTime(18.5));  // "18:30:00"
+```
+
+---
+
+## Additional Functions
+
+| Function | Description |
+| --- | --- |
+| `solarEphemeris(double jd)` | Jean Meeus Ch. 25 low-precision solar ephemeris |
+| `toJulianDate(DateTime date)` | Convert a DateTime to Julian Date |
+| `getAsr(double solarNoon, double latitude, double declination, {bool hanafi})` | Compute Asr time |
+| `getQiyam(double fajrTime, double ishaTime)` | Compute the last third of the night |
+| `getMscFajr(DateTime date, double latitude)` | MCW Fajr seasonal offset in minutes |
+| `getMscIsha(DateTime date, double latitude, [String shafaq])` | MCW Isha seasonal offset in minutes |
+| `minutesToDepression(double minutes, double latDeg, double declDeg)` | Convert time offset to solar depression angle |
+
+---
+
+[Home](Home)
diff --git a/.wiki/Home.md b/.wiki/Home.md
new file mode 100644
index 0000000..2187d86
--- /dev/null
+++ b/.wiki/Home.md
@@ -0,0 +1,20 @@
+# pray_calc_dart
+
+Islamic prayer times for Dart and Flutter. Implements the MCW seasonal model and dynamic twilight angles. Uses [nrel_spa](https://pub.dev/packages/nrel_spa) for the NREL Solar Position Algorithm.
+
+## Quick Start
+
+```dart
+import 'package:pray_calc_dart/pray_calc_dart.dart';
+
+final times = getTimes(DateTime(2024, 3, 15), 40.7128, -74.0060, -5.0);
+print('Fajr:    ${formatTime(times.fajr)}');
+print('Dhuhr:   ${formatTime(times.dhuhr)}');
+print('Maghrib: ${formatTime(times.maghrib)}');
+print('Isha:    ${formatTime(times.isha)}');
+```
+
+## Pages
+
+- [API Reference](API-Reference) — Full function and type reference
+- [Dynamic Angle Algorithm](Dynamic-Algorithm) — Physics-grounded twilight angle computation