docs: add quickstart, advanced guide, and examples for pray-calc

.github/wiki/examples/daily-schedule.md

@@ -0,0 +1,36 @@
+# Example: Daily Prayer Schedule
+
+Print a formatted prayer schedule for any date and location.
+
+```js
+import { getPrayerTimes, Method } from 'pray-calc';
+
+const date = new Date('2025-03-20'); // spring equinox
+const LAT  = 21.3891;  // Mecca
+const LON  = 39.8579;
+const TZ   = 3;        // AST (Arabia Standard Time)
+
+const times = getPrayerTimes(date, LAT, LON, TZ, { method: Method.UmmAlQura });
+
+console.log(`Prayer times for ${date.toDateString()} — Mecca`);
+console.log('');
+console.log(`  Fajr:    ${times.fajr}`);
+console.log(`  Sunrise: ${times.sunrise}`);
+console.log(`  Dhuhr:   ${times.dhuhr}`);
+console.log(`  Asr:     ${times.asr}`);
+console.log(`  Maghrib: ${times.maghrib}`);
+console.log(`  Isha:    ${times.isha}`);
+```
+
+Sample output:
+
+```
+Prayer times for Thu Mar 20 2025 — Mecca
+
+  Fajr:    04:45:00
+  Sunrise: 06:07:00
+  Dhuhr:   12:14:00
+  Asr:     15:37:00
+  Maghrib: 18:21:00
+  Isha:    19:51:00
+```

.github/wiki/examples/multi-city-comparison.md

@@ -0,0 +1,49 @@
+# Example: Multi-City Prayer Time Comparison
+
+Compare Fajr and Isha times across multiple cities for the same date.
+
+```js
+import { getPrayerTimes, Method } from 'pray-calc';
+
+const date = new Date('2025-06-21'); // summer solstice
+
+const cities = [
+  { name: 'Mecca',        lat: 21.3891,   lon:  39.8579, tz:  3, method: Method.UmmAlQura },
+  { name: 'London',       lat: 51.5074,   lon:  -0.1278, tz:  1, method: Method.MWL       },
+  { name: 'New York',     lat: 40.7128,   lon: -74.0060, tz: -4, method: Method.ISNA      },
+  { name: 'Kuala Lumpur', lat:  3.1390,   lon: 101.6869, tz:  8, method: Method.JAKIM     },
+  { name: 'Jakarta',      lat: -6.2088,   lon: 106.8456, tz:  7, method: Method.Kemenag   },
+];
+
+console.log(`Prayer times for ${date.toDateString()}\n`);
+console.log('City'.padEnd(16) + 'Method'.padEnd(12) + 'Fajr     Isha');
+console.log('-'.repeat(52));
+
+for (const city of cities) {
+  const times = getPrayerTimes(date, city.lat, city.lon, city.tz, {
+    method: city.method,
+  });
+  const method = city.method.toString().slice(0, 10);
+  console.log(
+    city.name.padEnd(16) +
+    method.padEnd(12) +
+    `${times.fajr}  ${times.isha}`,
+  );
+}
+```
+
+Sample output:
+
+```
+Prayer times for Sat Jun 21 2025
+
+City            Method      Fajr     Isha
+----------------------------------------------------
+Mecca           UmmAlQura   04:19    21:20
+London          MWL         01:44    23:17
+New York        ISNA        03:43    21:37
+Kuala Lumpur    JAKIM       05:50    19:49
+Jakarta         Kemenag     04:37    18:06
+```
+
+> **Note:** London in summer has very short nights. Fajr and Isha times shown here use the MWL method without a high-latitude adjustment. See [High Latitude](../High-Latitude) for adjustment options.

.github/wiki/guides/advanced.md

@@ -0,0 +1,94 @@
+# Advanced Usage
+
+## High-latitude handling
+
+At latitudes above ~48°N or below ~48°S, Fajr and Isha may not have valid solar depression angles during summer. Several adjustment methods are available:
+
+```js
+import { getPrayerTimes, HighLatRule } from 'pray-calc';
+
+// Angle-based: uses the ratio of Fajr/Isha night fraction from a reference latitude
+const times = getPrayerTimes(date, lat, lon, tz, {
+  highLat: HighLatRule.AngleBased,
+});
+
+// Middle of night: splits the night equally
+const times2 = getPrayerTimes(date, lat, lon, tz, {
+  highLat: HighLatRule.MiddleOfNight,
+});
+
+// One seventh: Fajr/Isha at 1/7 of the night duration
+const times3 = getPrayerTimes(date, lat, lon, tz, {
+  highLat: HighLatRule.OneSeventh,
+});
+```
+
+See [High Latitude](../High-Latitude) for background on why these rules exist and how to choose.
+
+## Custom angles
+
+Override the Fajr and Isha angles directly:
+
+```js
+const times = getPrayerTimes(date, lat, lon, tz, {
+  fajrAngle: 15,   // degrees below horizon
+  ishaAngle: 15,
+});
+```
+
+## Time adjustments
+
+Apply minute-based adjustments to individual prayers:
+
+```js
+const times = getPrayerTimes(date, lat, lon, tz, {
+  adjustments: {
+    fajr: 2,     // +2 minutes
+    maghrib: -1, // -1 minute
+  },
+});
+```
+
+## Midnight calculation
+
+```js
+import { getPrayerTimes, MidnightMethod } from 'pray-calc';
+
+// Standard: midpoint between Maghrib and Fajr
+const times = getPrayerTimes(date, lat, lon, tz, {
+  midnight: MidnightMethod.Standard,
+});
+
+// Jafari: midpoint between Maghrib and sunrise
+const times2 = getPrayerTimes(date, lat, lon, tz, {
+  midnight: MidnightMethod.Jafari,
+});
+```
+
+## Dynamic algorithm
+
+The DPC (Dynamic Prayer Calculation) algorithm uses verified observational data to determine Fajr and Isha angles based on the observer's latitude and season, rather than fixed angles from a single authority.
+
+```js
+import { getPrayerTimes, Method } from 'pray-calc';
+
+const times = getPrayerTimes(date, lat, lon, tz, {
+  method: Method.Dynamic, // research-based angles
+});
+```
+
+See [Dynamic Algorithm](../Dynamic-Algorithm) and [Research](../Research) for how the data was collected and validated.
+
+## Elevation
+
+At high elevations, atmospheric refraction differs slightly. Pass elevation in metres:
+
+```js
+const times = getPrayerTimes(date, lat, lon, tz, { elevation: 2000 });
+```
+
+## Related pages
+
+- [High Latitude](../High-Latitude) — deep dive on the problem and solutions
+- [Asr Calculation](../Asr-Calculation) — shadow length derivation
+- [Twilight Physics](../Twilight-Physics) — what defines Fajr and Isha astronomically

.github/wiki/guides/quickstart.md

@@ -0,0 +1,77 @@
+# Quick Start
+
+Five minutes from install to prayer times.
+
+## Install
+
+```sh
+npm install pray-calc
+```
+
+## Basic usage
+
+```js
+import { getPrayerTimes } from 'pray-calc';
+
+const times = getPrayerTimes(
+  new Date('2025-06-21'),
+  40.7128,   // latitude
+  -74.0060,  // longitude
+  -4,        // UTC offset in hours (EDT)
+);
+
+console.log(times.fajr);    // "04:01:12"
+console.log(times.sunrise); // "05:25:44"
+console.log(times.dhuhr);   // "12:59:58"
+console.log(times.asr);     // "16:47:23"
+console.log(times.maghrib); // "20:34:47"
+console.log(times.isha);    // "22:08:33"
+```
+
+Times are returned as `HH:MM:SS` strings in the local timezone defined by the UTC offset.
+
+## Choosing a calculation method
+
+```js
+import { getPrayerTimes, Method } from 'pray-calc';
+
+// ISNA — commonly used in North America
+const times = getPrayerTimes(date, lat, lon, tz, { method: Method.ISNA });
+
+// MWL — Muslim World League
+const times2 = getPrayerTimes(date, lat, lon, tz, { method: Method.MWL });
+
+// Egyptian — Egyptian General Authority of Survey
+const times3 = getPrayerTimes(date, lat, lon, tz, { method: Method.Egyptian });
+```
+
+See [Traditional Methods](../Traditional-Methods) for a full comparison of all built-in methods.
+
+## Asr calculation schools
+
+```js
+import { getPrayerTimes, AsrSchool } from 'pray-calc';
+
+// Standard (Shafi, Maliki, Hanbali) — shadow length = 1× object height
+const standard = getPrayerTimes(date, lat, lon, tz, { asr: AsrSchool.Standard });
+
+// Hanafi — shadow length = 2× object height
+const hanafi = getPrayerTimes(date, lat, lon, tz, { asr: AsrSchool.Hanafi });
+```
+
+## Moon data
+
+```js
+import { getMoonData } from 'pray-calc';
+
+const moon = getMoonData(new Date('2025-06-21'), 40.7128, -74.0060);
+console.log(moon.phase);      // 0-1 (0=new, 0.5=full)
+console.log(moon.illumination); // percentage illuminated
+```
+
+## Next steps
+
+- [API Reference](../API-Reference) — all functions and options
+- [Traditional Methods](../Traditional-Methods) — angle-based calculation methods explained
+- [Dynamic Algorithm](../Dynamic-Algorithm) — how pray-calc's research-based DPC works
+- [Advanced Guide](advanced) — high-latitude handling, edge cases