chore: polish pubspec, add wiki docs and CHANGELOG

.claude/AGENTS.md

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

.github/wiki/Home.md

@@ -1,8 +1,13 @@
 # hijri_core
 
-Hijri/Gregorian calendar conversion for Dart and Flutter. Supports Umm al-Qura (UAQ) and FCNA/ISNA calendars. Zero dependencies.
+Hijri/Gregorian calendar conversion for Dart and Flutter. Pluggable engine system with built-in Umm al-Qura (UAQ) and FCNA calendar implementations. Zero dependencies.
 
-## Quick Start
+## Install
+
+```yaml
+dependencies:
+  hijri_core: ^1.0.0
+```
 
 ```dart
 import 'package:hijri_core/hijri_core.dart';
@@ -14,7 +19,10 @@ final greg = toGregorian(1446, 9, 1);
 print(greg!.toIso8601String().substring(0, 10)); // 2025-03-01
 ```
 
-## Pages
+## Contents
 
-- [API Reference](API-Reference): Full function and type reference
+- [Quickstart Guide](guides/quickstart) — install, first call, engine selection
-- [Calendar Systems](Calendar-Systems): UAQ and FCNA algorithm details
+- [Advanced Usage](guides/advanced) — pluggable engines, custom calendars
+- [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,61 @@
+# Basic Usage Examples
+
+## Convert Today's Date
+
+```dart
+import 'package:hijri_core/hijri_core.dart';
+
+void main() {
+  final today = DateTime.now().toUtc();
+  final hijri = toHijri(today);
+
+  if (hijri != null) {
+    final months = [
+      '', 'Muharram', 'Safar', "Rabi' al-Awwal", "Rabi' al-Thani",
+      'Jumada al-Awwal', 'Jumada al-Thani', 'Rajab', "Sha'ban",
+      'Ramadan', 'Shawwal', "Dhu al-Qi'dah", 'Dhu al-Hijjah',
+    ];
+    print('Today in Hijri: ${hijri.hd} ${months[hijri.hm]} ${hijri.hy} AH');
+  }
+}
+```
+
+## Ramadan Calendar for a Year
+
+```dart
+import 'package:hijri_core/hijri_core.dart';
+
+void main() {
+  // Find Ramadan 1446 start and end in Gregorian
+  final ramadanStart = toGregorian(1446, 9, 1);
+  final ramadanEnd   = toGregorian(1446, 9, daysInMonth(1446, 9));
+
+  print('Ramadan 1446: ${ramadanStart?.toIso8601String().substring(0, 10)} '
+        'to ${ramadanEnd?.toIso8601String().substring(0, 10)}');
+}
+```
+
+## UAQ vs FCNA Comparison
+
+```dart
+import 'package:hijri_core/hijri_core.dart';
+
+void main() {
+  final dates = [
+    DateTime.utc(2024, 4, 9),  // Eid al-Fitr 2024
+    DateTime.utc(2024, 6, 16), // Eid al-Adha 2024
+    DateTime.utc(2025, 3, 30), // Eid al-Fitr 2025
+  ];
+
+  print('Gregorian    UAQ           FCNA');
+  print('${'─' * 45}');
+  for (final d in dates) {
+    final uaq  = toHijri(d, calendar: 'uaq');
+    final fcna = toHijri(d, calendar: 'fcna');
+    final greg = d.toIso8601String().substring(0, 10);
+    final uaqStr  = uaq  != null ? '${uaq.hy}/${uaq.hm}/${uaq.hd}'   : 'n/a';
+    final fcnaStr = fcna != null ? '${fcna.hy}/${fcna.hm}/${fcna.hd}' : 'n/a';
+    print('$greg  ${uaqStr.padRight(14)}$fcnaStr');
+  }
+}
+```

.github/wiki/guides/advanced.md

@@ -0,0 +1,76 @@
+# Advanced Usage
+
+## Selecting a Calendar Engine
+
+The default engine is Umm al-Qura (UAQ). Switch to FCNA for North American Islamic Society dates:
+
+```dart
+import 'package:hijri_core/hijri_core.dart';
+
+void main() {
+  final date = DateTime.utc(2025, 3, 1);
+
+  final uaq = toHijri(date, calendar: 'uaq');
+  final fcna = toHijri(date, calendar: 'fcna');
+
+  print('UAQ:  ${uaq?.hy}/${uaq?.hm}/${uaq?.hd}');
+  print('FCNA: ${fcna?.hy}/${fcna?.hm}/${fcna?.hd}');
+}
+```
+
+## Listing Available Calendars
+
+```dart
+final calendars = listCalendars();
+print(calendars); // ['uaq', 'fcna']
+
+final engine = getCalendar('uaq');
+print(engine.name); // 'Umm al-Qura'
+```
+
+## Custom Engine
+
+Implement `CalendarEngine` to plug in your own calendar algorithm:
+
+```dart
+import 'package:hijri_core/hijri_core.dart';
+
+class MyCalendarEngine implements CalendarEngine {
+  @override
+  String get id => 'my-calendar';
+
+  @override
+  String get name => 'My Custom Calendar';
+
+  @override
+  HijriDate? toHijri(DateTime gregorian) {
+    // Your conversion logic here
+    return null;
+  }
+
+  @override
+  DateTime? toGregorian(int hy, int hm, int hd) {
+    // Your reverse conversion logic here
+    return null;
+  }
+
+  @override
+  int daysInMonth(int hy, int hm) => 30; // simplified
+
+  @override
+  bool isValid(int hy, int hm, int hd) => hm >= 1 && hm <= 12 && hd >= 1 && hd <= 30;
+}
+
+// Register and use
+registerCalendar(MyCalendarEngine());
+final result = toHijri(DateTime.utc(2025, 3, 1), calendar: 'my-calendar');
+```
+
+## Ramadan Detection
+
+```dart
+bool isRamadan(DateTime date) {
+  final hijri = toHijri(date);
+  return hijri != null && hijri.hm == 9;
+}
+```

.github/wiki/guides/quickstart.md

@@ -0,0 +1,54 @@
+# Quickstart
+
+## Install
+
+Add to `pubspec.yaml`:
+
+```yaml
+dependencies:
+  hijri_core: ^1.0.0
+```
+
+Run `dart pub get`.
+
+## Gregorian to Hijri
+
+```dart
+import 'package:hijri_core/hijri_core.dart';
+
+void main() {
+  final hijri = toHijri(DateTime.utc(2025, 3, 1));
+  if (hijri != null) {
+    print('${hijri.hy}/${hijri.hm}/${hijri.hd}'); // 1446/9/1
+  }
+}
+```
+
+## Hijri to Gregorian
+
+```dart
+final greg = toGregorian(1446, 9, 1);
+if (greg != null) {
+  print(greg.toIso8601String().substring(0, 10)); // 2025-03-01
+}
+```
+
+Both functions return `null` for dates outside the supported range.
+
+## Days in a Hijri Month
+
+```dart
+final days = daysInMonth(1446, 9); // Ramadan 1446
+print(days); // 29 or 30
+```
+
+## Validate a Hijri Date
+
+```dart
+final valid = isValid(1446, 9, 15);  // true
+final bad   = isValid(1446, 13, 1);  // false (month 13 does not exist)
+```
+
+## Supported Date Range
+
+The Umm al-Qura engine covers 1318 AH (1900 CE) through 1500 AH (2077 CE). Dates outside this range return `null`. The FCNA engine uses a calculated formula with no hard date limit.

.gitignore

@@ -25,3 +25,6 @@ Thumbs.db
 .windsurf/
 .gemini/
 .codeium/
+
+# Secrets
+.env*

CHANGELOG.md

@@ -0,0 +1,23 @@
+# 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.
+- `toHijri` — converts a Gregorian `DateTime` to a Hijri date tuple.
+- `fromHijri` — converts a Hijri date tuple to a Gregorian `DateTime`.
+- `daysInMonth` — returns the number of days in a given Hijri month for a given engine.
+- `isValid` — validates a Hijri date for a given engine.
+- `listCalendars` / `getCalendar` — registry API for available calendar engines.
+- Built-in Umm al-Qura (UAQ) engine with tabular data.
+- Built-in FCNA (Fiqh Council of North America) calculated engine.
+- Pluggable `CalendarEngine` abstract class for custom Hijri calendar implementations.
+- Pure Dart implementation. Zero runtime dependencies.
+- Dart SDK `^3.7.0` compatibility.
+- 42 unit tests covering all 8 SPORT features across both UAQ and FCNA engines.

pubspec.yaml

@@ -3,8 +3,10 @@ description: >
   Hijri/Gregorian calendar conversion for Dart and Flutter. Pluggable engine
   system with built-in Umm al-Qura and FCNA calendars. Zero dependencies.
 version: 1.0.0
+homepage: https://github.com/acamarata/hijri-core-dart
 repository: https://github.com/acamarata/hijri-core-dart
 issue_tracker: https://github.com/acamarata/hijri-core-dart/issues
+publisher: ariccamarata.com
 topics:
   - hijri
   - islamic