From bb8be7012a8224774ba698d57014b7ae89e499c8 Mon Sep 17 00:00:00 2001
From: codex-bot <codex-bot@bots.com>
Date: Wed, 9 Sep 2026 17:52:24 +0100
Subject: [PATCH] README: app docs

---
 README.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..975fc66
--- /dev/null
+++ b/README.md
@@ -0,0 +1,66 @@
+# SALAH — prayer times for Casablanca (Xiaomi Watch S4)
+
+Offline prayer-time companion: shows today's six times (FAJR, SHURUK, DHUHR,
+ASR, MAGHRIB, ISHA) with the next prayer highlighted and a countdown banner.
+
+**Status: VERIFIED MATH (matches AlAdhan on 3 reference dates); on-watch render
+pending user confirmation.**
+
+## Method
+
+Morocco (Ministry of Habous), matching AlAdhan `method=21`:
+
+- Fajr 19°, Isha 17° (twilight angles)
+- Standard Asr (shadow factor 1× — Maliki default in Morocco)
+- Dhuhr = solar noon + 5 min; Maghrib = sunset + 5 min (AlAdhan's baked offsets)
+- Location hardcoded: Casablanca 33.5731, −7.5898 · TZ = UTC+1 year-round
+  (Morocco dropped DST in 2018)
+
+All computation happens **on the watch** — no GPS, no network. Pure solar math
+(same Meeus approach as the sundial) lives in `src/common/prayer.js`.
+
+## Screen
+
+- Header: CASABLANCA + current clock
+- Purple banner: next prayer name + countdown (`1h 55m`, `+1d …` wraps past midnight)
+- Six chord-tapered rows: widths [380, 412, 424, 406, 368, 304] px computed from
+  the circle chord at each row's position (fixed-width rows clipped off the disc
+  in the first layout — asserted numerically in tests now)
+- Passed prayers dimmed (opacity 0.45); next row purple-highlighted
+- 15s refresh
+
+## Project layout
+
+```text
+src/
+├── app.ux, manifest.json   # com.ilias.salah, watch, designWidth 466
+├── common/
+│   ├── prayer.js           # times/format/nextPrayer/formatCountdown — pure, unit-tested
+│   └── icon.png            # 192×192 circular icon (user-supplied mosque art)
+└── pages/index/index.ux    # layout + update loop
+tests/
+├── prayer.cjs              # 10 tests vs AlAdhan reference times (3 dates)
+├── page.cjs                # 11 wiring/layout tests (incl. chord-fit assertions)
+├── make_icon.py            # icon conversion pipeline (disc detect → round mask → 192²)
+└── check-rpk.py            # verifies icon/manifest inside the built .rpk
+```
+
+## Build & test
+
+```bash
+npm ci
+npm run release
+node tests/prayer.cjs
+node tests/page.cjs
+```
+
+## Install
+
+Side-load `dist/com.ilias.salah.release.*.rpk` via AstroBox.
+Releases: https://gitea.oimcloud.myaddr.tools/codex-bot/vela-salah
+
+## Accuracy note
+
+Verified against AlAdhan API (method 21) for 2026-09-09, 2026-01-15, 2026-07-01 —
+all six times within 2 minutes on every date. Tolerance covers the low-precision
+solar vector (±0.01°) plus rounding.