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

---
 .github/workflows/wiki-sync.yml |  42 +++++++++++++
 .wiki/API-Reference.md          | 105 ++++++++++++++++++++++++++++++++
 .wiki/Home.md                   |  21 +++++++
 3 files changed, 168 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..60d18e6
--- /dev/null
+++ b/.wiki/API-Reference.md
@@ -0,0 +1,105 @@
+# API Reference
+
+## qiblaAngle
+
+```dart
+double qiblaAngle(double lat, double lng)
+```
+
+Computes the initial bearing (forward azimuth) from the given coordinates to the Ka'bah using the spherical forward azimuth formula.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `lat` | `double` | Latitude in decimal degrees (-90 to 90) |
+| `lng` | `double` | Longitude in decimal degrees (-180 to 180) |
+| Returns | `double` | Bearing in degrees clockwise from north (0-360) |
+
+Throws `RangeError` if coordinates are out of bounds.
+
+```dart
+final bearing = qiblaAngle(40.7128, -74.006); // ~58.48
+```
+
+---
+
+## compassDir
+
+```dart
+String compassDir(double bearing)
+```
+
+Returns an eight-point compass abbreviation for the given bearing.
+
+| Bearing range | Returns |
+| --- | --- |
+| 337.5 - 22.5 | N |
+| 22.5 - 67.5 | NE |
+| 67.5 - 112.5 | E |
+| 112.5 - 157.5 | SE |
+| 157.5 - 202.5 | S |
+| 202.5 - 247.5 | SW |
+| 247.5 - 292.5 | W |
+| 292.5 - 337.5 | NW |
+
+---
+
+## compassName
+
+```dart
+String compassName(double bearing)
+```
+
+Returns the full compass direction name for the given bearing: North, Northeast, East, Southeast, South, Southwest, West, or Northwest.
+
+---
+
+## qiblaGreatCircle
+
+```dart
+List<LatLng> qiblaGreatCircle(double lat, double lng, [int steps = 120])
+```
+
+Generates waypoints along the great circle from the observer's location to the Ka'bah using spherical linear interpolation (Slerp). Returns `steps + 1` points including both endpoints.
+
+Useful for drawing the Qibla direction line on a map.
+
+```dart
+final path = qiblaGreatCircle(40.7128, -74.006);
+// path[0] = observer location
+// path[path.length - 1] = Ka'bah
+```
+
+### LatLng fields
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `lat` | `double` | Latitude in decimal degrees |
+| `lng` | `double` | Longitude in decimal degrees |
+
+---
+
+## distanceKm
+
+```dart
+double distanceKm(double lat1, double lng1, double lat2, double lng2)
+```
+
+Haversine distance between two points in kilometers. Uses a spherical Earth model with R = 6,371 km.
+
+```dart
+final km = distanceKm(40.7128, -74.006, kaabaLat, kaabaLng); // ~9634
+```
+
+---
+
+## Constants
+
+| Constant | Value | Description |
+| --- | --- | --- |
+| `kaabaLat` | 21.422511 | Ka'bah center latitude (degrees north) |
+| `kaabaLng` | 39.826150 | Ka'bah center longitude (degrees east) |
+| `earthRadiusKm` | 6371 | WGS-84 volumetric mean radius in km |
+
+---
+
+[Home](Home)
diff --git a/.wiki/Home.md b/.wiki/Home.md
new file mode 100644
index 0000000..2d23a2d
--- /dev/null
+++ b/.wiki/Home.md
@@ -0,0 +1,21 @@
+# qibla
+
+Qibla direction, great-circle path, and haversine distance for Dart and Flutter. Pure math, zero dependencies.
+
+## Quick Start
+
+```dart
+import 'package:qibla/qibla.dart';
+
+final bearing = qiblaAngle(40.7128, -74.006);
+print(bearing);             // ~58.48
+print(compassDir(bearing)); // NE
+
+final km = distanceKm(40.7128, -74.006, kaabaLat, kaabaLng);
+print(km); // ~9634
+```
+
+## Pages
+
+- [API Reference](API-Reference) — Full function and constant reference
+- [Architecture](Architecture) — Spherical trigonometry and Slerp implementation