From 9fdc60d06ff558b8c8195d28b1a117710903d4e1 Mon Sep 17 00:00:00 2001
From: Aric Camarata <aric.camarata@gmail.com>
Date: Sun, 8 Mar 2026 17:14:42 -0400
Subject: [PATCH] docs: add wiki pages and wiki-sync workflow

---
 .github/workflows/wiki-sync.yml |  42 +++++++++
 .wiki/API-Reference.md          | 147 ++++++++++++++++++++++++++++++++
 .wiki/Home.md                   |  24 ++++++
 3 files changed, 213 insertions(+)
 create mode 100644 .github/workflows/wiki-sync.yml
 create mode 100644 .wiki/API-Reference.md
 create mode 100644 .wiki/Home.md

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..1610054
--- /dev/null
+++ b/.wiki/API-Reference.md
@@ -0,0 +1,147 @@
+# API Reference
+
+## getMoonPhase
+
+```dart
+MoonPhaseResult getMoonPhase([DateTime? date])
+```
+
+Returns the moon phase for the given UTC date, or the current moment if `date` is null.
+
+### MoonPhaseResult fields
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `phase` | `MoonPhaseName` | Enum: `newMoon`, `waxingCrescent`, `firstQuarter`, `waxingGibbous`, `fullMoon`, `waningGibbous`, `lastQuarter`, `waningCrescent` |
+| `phaseName` | `String` | Human-readable phase name |
+| `phaseSymbol` | `String` | Moon emoji for the current phase |
+| `illumination` | `double` | Percent illuminated (0-100) |
+| `age` | `double` | Hours since the last new moon |
+| `elongationDeg` | `double` | Moon-Sun elongation in degrees |
+| `isWaxing` | `bool` | True when illumination is increasing |
+| `nextNewMoon` | `DateTime` | Next new moon (UTC) |
+| `nextFullMoon` | `DateTime` | Next full moon (UTC) |
+| `prevNewMoon` | `DateTime` | Previous new moon (UTC) |
+
+---
+
+## getMoonPosition
+
+```dart
+MoonPosition getMoonPosition(
+  DateTime? date,
+  double lat,
+  double lon, {
+  double elevation = 0,
+})
+```
+
+Computes the topocentric position of the moon for an observer at the given location. Applies atmospheric refraction to the altitude.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `date` | `DateTime?` | now | UTC date and time |
+| `lat` | `double` | required | Observer latitude (-90 to 90) |
+| `lon` | `double` | required | Observer longitude (-180 to 180) |
+| `elevation` | `double` | 0 | Observer elevation in meters |
+
+### MoonPosition fields
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `azimuth` | `double` | Degrees from North, clockwise (0-360) |
+| `altitude` | `double` | Degrees above horizon (refraction applied) |
+| `distance` | `double` | Earth-Moon distance in km |
+| `parallacticAngle` | `double` | Parallactic angle in radians |
+
+---
+
+## getMoonIllumination
+
+```dart
+MoonIlluminationResult getMoonIllumination([DateTime? date])
+```
+
+Returns illumination data for the given UTC date, or now if null.
+
+### MoonIlluminationResult fields
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `fraction` | `double` | Illuminated fraction (0-1) |
+| `phase` | `double` | Phase cycle position (0=new, 0.25=first quarter, 0.5=full, 0.75=last quarter) |
+| `angle` | `double` | Bright limb position angle in radians |
+| `isWaxing` | `bool` | True when waxing |
+
+---
+
+## getMoonVisibilityEstimate
+
+```dart
+MoonVisibilityEstimate getMoonVisibilityEstimate(
+  DateTime? date,
+  double lat,
+  double lon, {
+  double elevation = 0,
+})
+```
+
+Estimates lunar crescent visibility using the Odeh (2006) criterion. Pass a post-sunset time for meaningful results.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `date` | `DateTime?` | now | UTC date and time (use post-sunset) |
+| `lat` | `double` | required | Observer latitude |
+| `lon` | `double` | required | Observer longitude |
+| `elevation` | `double` | 0 | Observer elevation in meters |
+
+### MoonVisibilityEstimate fields
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `v` | `double` | Odeh V parameter |
+| `zone` | `OdehZone` | Visibility zone (a, b, c, or d) |
+| `description` | `String` | Human-readable zone description |
+| `isVisibleNakedEye` | `bool` | True for zone A |
+| `isVisibleWithOpticalAid` | `bool` | True for zones A and B |
+| `arcl` | `double` | Sun-Moon elongation in degrees |
+| `arcv` | `double` | Arc of vision in degrees |
+| `w` | `double` | Crescent width in arc minutes |
+| `moonAboveHorizon` | `bool` | True if the moon is above the horizon at the given time |
+
+### OdehZone values
+
+| Zone | V threshold | Meaning |
+| --- | --- | --- |
+| A | V >= 5.65 | Visible with naked eye |
+| B | V >= 2.00 | Visible with optical aid, may be naked-eye visible |
+| C | V >= -0.96 | Visible with optical aid only |
+| D | V < -0.96 | Not visible even with optical aid |
+
+---
+
+## getMoon
+
+```dart
+MoonSnapshot getMoon(
+  DateTime? date,
+  double lat,
+  double lon, {
+  double elevation = 0,
+})
+```
+
+Convenience function that runs all four computations in one call.
+
+### MoonSnapshot fields
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `phase` | `MoonPhaseResult` | Phase result |
+| `position` | `MoonPosition` | Position result |
+| `illumination` | `MoonIlluminationResult` | Illumination result |
+| `visibility` | `MoonVisibilityEstimate` | Visibility estimate |
+
+---
+
+[Home](Home)
diff --git a/.wiki/Home.md b/.wiki/Home.md
new file mode 100644
index 0000000..d18314f
--- /dev/null
+++ b/.wiki/Home.md
@@ -0,0 +1,24 @@
+# moon_sighting
+
+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
+
+```dart
+import 'package:moon_sighting/moon_sighting.dart';
+
+final phase = getMoonPhase();
+print('${phase.phaseName} (${phase.illumination.toStringAsFixed(1)}%)');
+
+final vis = getMoonVisibilityEstimate(
+  DateTime.utc(2025, 3, 31, 18, 30),
+  21.4225, 39.8262, // Mecca
+);
+print('Zone: ${vis.zone.label}');
+print('Visible naked eye: ${vis.isVisibleNakedEye}');
+```
+
+## Pages
+
+- [API Reference](API-Reference) — Full function and type reference
+- [Visibility Criteria](Visibility-Criteria) — Yallop and Odeh crescent visibility criteria