chore: polish pubspec, add wiki docs and CHANGELOG

.claude/AGENTS.md

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

.github/wiki/Home.md

@@ -2,7 +2,15 @@
 
 Lunar crescent visibility for Dart and Flutter. Computes moon phase, topocentric position, illumination, and Yallop/Odeh crescent visibility criteria using Meeus algorithms. Zero dependencies.
 
-## Quick Start
+Uses Meeus lite algorithms with approximately 0.3 degree accuracy. The companion JavaScript
+package (`moon-sighting` on npm) uses JPL DE442S ephemeris for sub-arcminute precision.
+
+## Install
+
+```yaml
+dependencies:
+  moon_sighting: ^1.0.0
+```
 
 ```dart
 import 'package:moon_sighting/moon_sighting.dart';
@@ -12,13 +20,16 @@ print('${phase.phaseName} (${phase.illumination.toStringAsFixed(1)}%)');
 
 final vis = getMoonVisibilityEstimate(
   DateTime.utc(2025, 3, 31, 18, 30),
-  21.4225, 39.8262, // Mecca
+  21.4225, 39.8262, // Makkah
 );
 print('Zone: ${vis.zone.label}');
 print('Visible naked eye: ${vis.isVisibleNakedEye}');
 ```
 
-## Pages
+## Contents
 
-- [API Reference](API-Reference): Full function and type reference
+- [Quickstart Guide](guides/quickstart) — install, first call, phase and position
-- [Visibility Criteria](Visibility-Criteria): Yallop and Odeh crescent visibility criteria
+- [Advanced Usage](guides/advanced) — visibility criteria, new moon finding
+- [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
+
+## Tonight's Moon
+
+```dart
+import 'package:moon_sighting/moon_sighting.dart';
+
+void main() {
+  final now = DateTime.now().toUtc();
+  final phase = getMoonPhase(now);
+  final position = getMoonPosition(now, 40.7128, -74.0060);
+
+  print('Moon tonight (New York):');
+  print('  Phase:        ${phase.phaseName}');
+  print('  Illumination: ${phase.illumination.toStringAsFixed(1)}%');
+  print('  Altitude:     ${position.altitude.toStringAsFixed(2)}°');
+  print('  Azimuth:      ${position.azimuth.toStringAsFixed(2)}°');
+  print('  Distance:     ${position.distanceKm.toStringAsFixed(0)} km');
+}
+```
+
+## Ramadan Crescent Visibility Check
+
+```dart
+import 'package:moon_sighting/moon_sighting.dart';
+
+void main() {
+  // Check crescent visibility for major Muslim cities on Ramadan eve
+  final eveningOfCheck = DateTime.utc(2026, 2, 17, 18, 0);
+
+  final cities = [
+    ('Makkah',   21.4225,  39.8262,  3.0),
+    ('Istanbul', 41.0082,  28.9784,  3.0),
+    ('London',   51.5074,  -0.1278,  0.0),
+    ('New York', 40.7128, -74.0060, -5.0),
+  ];
+
+  print('City              Zone');
+  print('${'─' * 30}');
+  for (final (city, lat, lng, _) in cities) {
+    final vis = getMoonVisibilityEstimate(eveningOfCheck, lat, lng);
+    print('${city.padRight(18)}${vis.zone.label}');
+  }
+}
+```
+
+## Moon Phase Calendar
+
+```dart
+import 'package:moon_sighting/moon_sighting.dart';
+
+void main() {
+  print('Date,Phase,Illumination');
+  for (int day = 1; day <= 30; day++) {
+    final date = DateTime.utc(2025, 3, day, 12, 0);
+    final phase = getMoonPhase(date);
+    print('2025-03-${day.toString().padLeft(2, "0")},'
+          '${phase.phaseName},${phase.illumination.toStringAsFixed(1)}%');
+  }
+}
+```

.github/wiki/guides/advanced.md

@@ -0,0 +1,70 @@
+# Advanced Usage
+
+## Yallop vs Odeh Criteria
+
+The package implements two published crescent visibility criteria. Both are returned in `getMoonVisibilityEstimate`:
+
+```dart
+import 'package:moon_sighting/moon_sighting.dart';
+
+final vis = getMoonVisibilityEstimate(
+  DateTime.utc(2025, 3, 31, 18, 30),
+  21.4225, 39.8262,
+);
+
+print('Yallop zone: ${vis.yallopZone.label}');
+print('Odeh zone:   ${vis.odehZone.label}');
+print('Combined:    ${vis.zone.label}');
+```
+
+Yallop and Odeh zones:
+
+| Zone | Label | Description |
+| --- | --- | --- |
+| A | Easily visible | Visible to naked eye |
+| B | Visible under good conditions | May be visible to naked eye |
+| C | May need optical aid | Visible with binoculars |
+| D | Optical aid and perfect conditions | Telescope only |
+| E | Not visible | Below horizon at sunset |
+| F | Below new moon | Moon sets before sun |
+
+## Finding the Next New Moon
+
+```dart
+final newMoon = nearestNewMoon(DateTime.utc(2025, 3, 15));
+print('Next new moon: ${newMoon.toIso8601String()}');
+```
+
+Pass `next: false` for the previous new moon:
+
+```dart
+final prev = nearestNewMoon(DateTime.utc(2025, 3, 15), next: false);
+```
+
+## Monthly Crescent Calendar
+
+```dart
+import 'package:moon_sighting/moon_sighting.dart';
+
+void main() {
+  // Find when Ramadan crescent might be visible in 2026
+  final newMoon = nearestNewMoon(DateTime.utc(2026, 3, 20));
+  print('New moon: ${newMoon.toIso8601String()}');
+
+  // Check 3 successive evenings
+  for (int d = 1; d <= 3; d++) {
+    final check = newMoon.add(Duration(days: d, hours: 18));
+    final vis = getMoonVisibilityEstimate(check, 21.4225, 39.8262);
+    print('Day $d: ${vis.zone.label}');
+  }
+}
+```
+
+## Accuracy and JS Comparison
+
+| Aspect | moon_sighting (Dart) | moon-sighting (npm/JS) |
+| --- | --- | --- |
+| Algorithm | Meeus Chapter 47 | JPL DE442S ephemeris |
+| Position accuracy | ~0.3 degrees | Sub-arcminute |
+| Bundle size | Minimal | ~500 KB (ephemeris data) |
+| Best for | Flutter apps, mobile | Server-side, high precision |

.github/wiki/guides/quickstart.md

@@ -0,0 +1,61 @@
+# Quickstart
+
+## Install
+
+Add to `pubspec.yaml`:
+
+```yaml
+dependencies:
+  moon_sighting: ^1.0.0
+```
+
+Run `dart pub get`.
+
+## Moon Phase
+
+```dart
+import 'package:moon_sighting/moon_sighting.dart';
+
+void main() {
+  final phase = getMoonPhase();
+  print('Phase:        ${phase.phaseName}');
+  print('Illumination: ${phase.illumination.toStringAsFixed(1)}%');
+}
+```
+
+Pass a specific date for historical or future phases:
+
+```dart
+final phase = getMoonPhase(DateTime.utc(2025, 3, 31));
+```
+
+## Moon Position
+
+```dart
+final position = getMoonPosition(
+  DateTime.utc(2025, 3, 31, 18, 30),
+  21.4225,  // Makkah latitude
+  39.8262,  // longitude
+);
+
+print('Altitude:  ${position.altitude.toStringAsFixed(2)}°');
+print('Azimuth:   ${position.azimuth.toStringAsFixed(2)}°');
+print('Distance:  ${position.distanceKm.toStringAsFixed(0)} km');
+```
+
+## Crescent Visibility
+
+```dart
+final vis = getMoonVisibilityEstimate(
+  DateTime.utc(2025, 3, 31, 18, 30),
+  21.4225, 39.8262,
+);
+
+print('Zone:            ${vis.zone.label}');
+print('Visible (naked): ${vis.isVisibleNakedEye}');
+print('Visible (aided): ${vis.isVisibleWithAid}');
+```
+
+## Accuracy Note
+
+This package uses Meeus lite algorithms with approximately 0.3 degree positional accuracy. The companion JavaScript package (`moon-sighting` on npm) uses JPL DE442S ephemeris for sub-arcminute precision. Use the JS package when observatory-grade accuracy is required.

CHANGELOG.md

@@ -0,0 +1,29 @@
+# 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.
+- `getMoonPhase` — returns moon phase name and illumination percentage for any date.
+- `getMoonPosition` — computes topocentric altitude and azimuth using Meeus Chapter 47 algorithms.
+- `getMoon` — combined output: phase, position, and illumination in one call.
+- `getMoonVisibilityEstimate` — Yallop and Odeh crescent visibility criteria.
+- `nearestNewMoon` — finds the next or previous new moon from a given date.
+- `arcvMinimum` — polynomial helper for Yallop arc of vision minimum.
+- `distanceKm` — lunar distance in kilometres.
+- Meeus lite algorithms (Astronomical Algorithms, Jean Meeus, 2nd ed.) — no JPL ephemeris dependency.
+- Pure Dart implementation. Zero runtime dependencies.
+- Dart SDK `^3.7.0` compatibility.
+- 64 unit tests covering all 7 SPORT features.
+
+### Notes
+
+This package uses Meeus lite algorithms with approximately 0.3 degree positional accuracy.
+The companion JavaScript package (`moon-sighting` on npm) uses JPL DE442S ephemeris for
+sub-arcminute precision. Use the JS package when observatory-grade accuracy is required.

pubspec.yaml

@@ -4,8 +4,10 @@ description: >
   illumination, and Yallop/Odeh visibility criteria using Meeus algorithms.
   Zero dependencies.
 version: 1.0.0
+homepage: https://github.com/acamarata/moon-sighting-dart
 repository: https://github.com/acamarata/moon-sighting-dart
 issue_tracker: https://github.com/acamarata/moon-sighting-dart/issues
+publisher: ariccamarata.com
 topics:
   - moon
   - lunar