chore: polish pubspec, add wiki docs and CHANGELOG

.claude/AGENTS.md

@@ -1 +0,0 @@
-CLAUDE.md

.github/wiki/Home.md

@@ -1,20 +1,34 @@
 # 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.
+Islamic prayer times for Dart and Flutter. Calculates Fajr, Dhuhr, Asr, Maghrib, Isha, midnight, and Qiyam for any date and location. Implements the MCW seasonal model and Dynamic Prayer Calculation (DPC) algorithm. Depends on `nrel_spa` for solar positioning.
 
-## Quick Start
+## Install
+
+```yaml
+dependencies:
+  pray_calc_dart: ^1.0.0
+```
 
 ```dart
 import 'package:pray_calc_dart/pray_calc_dart.dart';
 
-final times = getTimes(DateTime(2024, 3, 15), 40.7128, -74.0060, -5.0);
+final times = getTimes(
-print('Fajr:    ${formatTime(times.fajr)}');
+  DateTime.utc(2024, 3, 15),
-print('Dhuhr:   ${formatTime(times.dhuhr)}');
+  21.3891,   // Makkah latitude
-print('Maghrib: ${formatTime(times.maghrib)}');
+  39.8579,   // longitude
-print('Isha:    ${formatTime(times.isha)}');
+  3.0,       // UTC offset (AST)
+);
+
+print('Fajr:    ${times.fajr.toStringAsFixed(4)} h');
+print('Dhuhr:   ${times.dhuhr.toStringAsFixed(4)} h');
+print('Maghrib: ${times.maghrib.toStringAsFixed(4)} h');
+print('Isha:    ${times.isha.toStringAsFixed(4)} h');
 ```
 
-## Pages
+## Contents
 
-- [API Reference](API-Reference): Full function and type reference
+- [Quickstart Guide](guides/quickstart) — install, first call, config options
-- [Dynamic Angle Algorithm](Dynamic-Algorithm): Physics-grounded twilight angle computation
+- [Advanced Usage](guides/advanced) — madhab, custom angles, seasonal model
+- [API Reference](API-Reference) — full function and type reference
+- [Examples](examples/basic-usage) — real-world snippets
+- [Contributing](CONTRIBUTING)

.github/wiki/examples/basic-usage.md

@@ -0,0 +1,53 @@
+# Basic Usage Examples
+
+## Daily Prayer Times for Multiple Cities
+
+```dart
+import 'package:pray_calc_dart/pray_calc_dart.dart';
+
+void printPrayers(String city, double lat, double lng, double utcOffset) {
+  final times = getTimes(DateTime.utc(2024, 3, 15), lat, lng, utcOffset);
+
+  String fmt(double h) {
+    if (h.isNaN) return '--:--';
+    final hh = h.truncate();
+    final mm = ((h - hh) * 60).round();
+    return '${hh.toString().padLeft(2, '0')}:${mm.toString().padLeft(2, '0')}';
+  }
+
+  print('$city');
+  print('  Fajr:    ${fmt(times.fajr)}');
+  print('  Dhuhr:   ${fmt(times.dhuhr)}');
+  print('  Asr:     ${fmt(times.asr)}');
+  print('  Maghrib: ${fmt(times.maghrib)}');
+  print('  Isha:    ${fmt(times.isha)}');
+}
+
+void main() {
+  printPrayers('Makkah',   21.3891,  39.8579,  3.0);
+  printPrayers('Istanbul', 41.0082,  28.9784,  3.0);
+  printPrayers('London',   51.5074,  -0.1278,  0.0);
+  printPrayers('New York', 40.7128, -74.0060, -5.0);
+}
+```
+
+## Monthly Calendar
+
+```dart
+import 'package:pray_calc_dart/pray_calc_dart.dart';
+
+void main() {
+  const lat = 40.7128;
+  const lng = -74.0060;
+  const utcOffset = -5.0;
+
+  print('Date,Fajr,Dhuhr,Asr,Maghrib,Isha');
+  for (int day = 1; day <= 30; day++) {
+    final date = DateTime.utc(2024, 3, day);
+    final t = getTimes(date, lat, lng, utcOffset);
+
+    String h(double v) => v.toStringAsFixed(4);
+    print('2024-03-${day.toString().padLeft(2, "0")},${h(t.fajr)},${h(t.dhuhr)},${h(t.asr)},${h(t.maghrib)},${h(t.isha)}');
+  }
+}
+```

.github/wiki/guides/advanced.md

@@ -0,0 +1,49 @@
+# Advanced Usage
+
+## Madhab Selection
+
+The Asr time differs between the Hanafi and standard (Shafi'i/Maliki/Hanbali) methods:
+
+```dart
+import 'package:pray_calc_dart/pray_calc_dart.dart';
+
+final standard = getTimes(
+  DateTime.utc(2024, 3, 15),
+  40.7128, -74.0060, -5.0,
+  config: const PrayerConfig(madhab: Madhab.standard),
+);
+
+final hanafi = getTimes(
+  DateTime.utc(2024, 3, 15),
+  40.7128, -74.0060, -5.0,
+  config: const PrayerConfig(madhab: Madhab.hanafi),
+);
+
+print('Asr (standard): ${standard.asr.toStringAsFixed(4)} h');
+print('Asr (Hanafi):   ${hanafi.asr.toStringAsFixed(4)} h');
+```
+
+## MCW Seasonal Model
+
+The MCW (Mohammed Camille Widad) seasonal model adjusts Fajr and Isha depression angles across the year to match observed sighting data. This is the default behavior. The DPC (Dynamic Prayer Calculation) variant uses ML-calibrated angles derived from verified sighting observations.
+
+Both models are used automatically based on latitude and date. No configuration is needed.
+
+## Fixed Angle Override
+
+For interoperability with fixed-angle calculation methods (ISNA, MWL, etc.):
+
+```dart
+final times = getTimes(
+  DateTime.utc(2024, 3, 15),
+  40.7128, -74.0060, -5.0,
+  config: const PrayerConfig(
+    fajrAngle: 15.0,   // ISNA
+    ishaAngle: 15.0,
+  ),
+);
+```
+
+## High Latitude Adjustments
+
+At latitudes above 48°N or below 48°S, Fajr and Isha times may behave unusually due to near-continuous twilight. The library applies the Middle of Night method automatically for extreme latitudes. Check `times.fajr.isNaN` to detect fallback conditions.

.github/wiki/guides/quickstart.md

@@ -0,0 +1,61 @@
+# Quickstart
+
+## Install
+
+Add to `pubspec.yaml`:
+
+```yaml
+dependencies:
+  pray_calc_dart: ^1.0.0
+```
+
+Run `dart pub get`.
+
+## First Call
+
+```dart
+import 'package:pray_calc_dart/pray_calc_dart.dart';
+
+void main() {
+  final times = getTimes(
+    DateTime.utc(2024, 3, 15),
+    21.3891,  // Makkah latitude
+    39.8579,  // longitude
+    3.0,      // UTC offset (Arabia Standard Time)
+  );
+
+  print('Fajr:    ${times.fajr.toStringAsFixed(4)} h');
+  print('Dhuhr:   ${times.dhuhr.toStringAsFixed(4)} h');
+  print('Asr:     ${times.asr.toStringAsFixed(4)} h');
+  print('Maghrib: ${times.maghrib.toStringAsFixed(4)} h');
+  print('Isha:    ${times.isha.toStringAsFixed(4)} h');
+}
+```
+
+## Output Fields
+
+`getTimes` returns a `PrayerTimes` object:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `fajr` | `double` | Fajr time (decimal hours, local) |
+| `dhuhr` | `double` | Dhuhr time |
+| `asr` | `double` | Asr time |
+| `maghrib` | `double` | Maghrib time (sunset) |
+| `isha` | `double` | Isha time |
+| `midnight` | `double` | Islamic midnight |
+| `qiyam` | `double` | Last third of night start |
+
+All times are decimal hours in the local timezone defined by `utcOffset`.
+
+## Converting to DateTime
+
+```dart
+DateTime timeToDateTime(DateTime date, double hours, double utcOffset) {
+  final totalMinutes = (hours * 60).round();
+  final h = totalMinutes ~/ 60;
+  final m = totalMinutes % 60;
+  return DateTime(date.year, date.month, date.day, h, m)
+    .subtract(Duration(hours: utcOffset.truncate(), minutes: ((utcOffset % 1) * 60).round()));
+}
+```

CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+This project adheres to [Semantic Versioning](https://semver.org/).
+
+## [1.0.0] - 2026-05-25
+
+### Added
+
+- Initial public release.
+- `getTimes` — calculates Fajr, Dhuhr, Asr, Maghrib, Isha, midnight, and Qiyam times for any date and location.
+- MCW seasonal model for Fajr and Isha twilight angles.
+- Dynamic Prayer Calculation (DPC) algorithm with ML-calibrated depression angles.
+- `PrayerConfig` — configurable madhab (Hanafi/standard Asr), calculation method, and UTC offset.
+- Pure Dart implementation. Zero runtime dependencies beyond `nrel_spa`.
+- Depends on `nrel_spa ^1.0.0` for NREL Solar Position Algorithm.
+- Dart SDK `^3.7.0` compatibility.
+- 24 unit tests covering all 7 prayer outputs across known locations and dates.

pubspec.yaml

@@ -4,8 +4,10 @@ description: >
   library implementing the MCW seasonal model and dynamic twilight angles.
   Uses nrel_spa for the NREL Solar Position Algorithm.
 version: 1.0.0
+homepage: https://github.com/acamarata/pray-calc-dart
 repository: https://github.com/acamarata/pray-calc-dart
 issue_tracker: https://github.com/acamarata/pray-calc-dart/issues
+publisher: ariccamarata.com
 topics:
   - prayer-times
   - islamic