From b732ff0c38c52a7affb6a35b665c637c05a0c6b5 Mon Sep 17 00:00:00 2001
From: codex-bot <codex-bot@bots.com>
Date: Wed, 9 Sep 2026 17:52:22 +0100
Subject: [PATCH] README: document actual app (was stale hello-world copy)

---
 README.md | 238 ++++++++++--------------------------------------------
 1 file changed, 41 insertions(+), 197 deletions(-)

diff --git a/README.md b/README.md
index 3fe2b80..3bd7e3d 100644
--- a/README.md
+++ b/README.md
@@ -1,209 +1,53 @@
-# Xiaomi Vela Hello World for Watch S4
+# SUNDIAL — sun-path dial for Xiaomi Watch S4
 
-This is the smallest practical Xiaomi Vela JS watch application. It shows two centered lines on a round black screen:
+A round watch face-style app: an amber sun orbits the upper arc during daylight
+(sunrise left → sunset right), a grey moon traces the lower arc at night. Center
+shows the clock, DAYLIGHT/NIGHT phase, and a countdown to the next sunrise/sunset.
+Location is hardcoded (Paris by default — edit `LAT`/`LON` in `src/pages/index/index.ux`).
+
+**Status: WORKING ON WATCH** (user-confirmed since v0.2).
+
+## Features
+
+- NOAA solar-position algorithm (Meeus), fully offline — no GPS/network
+- Two-tone day/night dial with horizon line, bezel ring, and hour ticks
+- Sun halo glow; moon marker at night
+- 30s refresh; timer cleared on hide/destroy (battery-friendly)
+- designWidth 466 = 1:1 mapping to the S4 41mm round screen
+
+## Project layout
 
 ```text
-Hello World!
-Xiaomi Watch S4
+src/
+├── app.ux                  # app lifecycle (must wrap JS in <script>export default…)
+├── manifest.json           # com.ilias.sundial, watch, designWidth 466
+├── common/
+│   ├── solar.js            # pure solar math (no Vela APIs) — unit-tested
+│   └── icon.png            # 192×192 circular app icon
+└── pages/index/index.ux    # dial page: template + logic + styles
+tests/                      # Node test harnesses (plain `node`, no framework)
+sign/                       # private.pem + certificate.pem (NOT committed)
 ```
 
-It compiles entirely from a Linux terminal. Xiaomi AIoT-IDE is not required.
-
-## 1. What you need
-
-- A 64-bit Linux system
-- Node.js and npm
-- OpenSSL, but only if you want a signed release package
-- Internet access for the first `npm install`
-
-Node.js 20 LTS is a conservative choice. The included project has also been build-tested with Node.js 24 and npm 11.
-
-On Ubuntu or Debian, install the basic tools:
+## Build & release
 
 ```bash
-sudo apt update
-sudo apt install -y curl openssl
+npm ci                 # installs locked aiot-toolkit 2.0.5
+npm run release        # signed .rpk → dist/
+node tests/solar.cjs   # math tests
+node tests/visual.cjs  # geometry/contrast tests parsed from the .ux
 ```
 
-Install Node.js using your preferred package manager or a version manager such as `nvm`. Confirm that it works:
+## Install
 
-```bash
-node --version
-npm --version
-```
+Side-load `dist/com.ilias.sundial.release.*.rpk` onto the watch via AstroBox.
+Releases: https://gitea.oimcloud.myaddr.tools/codex-bot/vela-sundial
 
-## 2. Understand the tiny project
+## Version history
 
-```text
-xiaomi-vela-s4-hello-world/
-├── package.json
-├── README.md
-├── sign/
-└── src/
-    ├── app.ux
-    ├── manifest.json
-    ├── common/
-    │   ├── icon.png
-    │   └── icon.svg
-    └── pages/
-        └── index/
-            └── index.ux
-```
-
-- `package.json` installs Xiaomi's command-line build tool and defines the build commands.
-- `src/manifest.json` defines the package, icon, watch target, design width, and start page.
-- `src/app.ux` contains application lifecycle hooks.
-- `src/pages/index/index.ux` contains the UI and its styles.
-- `sign/` is where release certificate files go. Keep private keys private.
-
-Vela `.ux` files resemble small single-file web components. A page may contain `template`, `style`, and `script` blocks. This Hello World page needs only `template` and `style`.
-
-## 3. Compile a debug RPK without Xiaomi's IDE
-
-Open a terminal in the project folder and run:
-
-```bash
-npm install
-npm run build
-```
-
-The important output is created under `dist/` and ends in `.debug.rpk`:
-
-```bash
-find dist -maxdepth 1 -type f -name '*.rpk' -print
-```
-
-The `build/` directory contains intermediate generated files. You normally do not edit either `build/` or `dist/`.
-
-To include a separate source map while debugging:
-
-```bash
-npm run build:source-map
-```
-
-To see every compiler option supported by your installed toolkit:
-
-```bash
-npm run help
-```
-
-## 4. Create a signed release RPK
-
-The release builder expects these two files:
-
-```text
-sign/private.pem
-sign/certificate.pem
-```
-
-Generate a local development certificate from the project root:
-
-```bash
-openssl req \
-  -newkey rsa:2048 \
-  -nodes \
-  -keyout sign/private.pem \
-  -x509 \
-  -days 3650 \
-  -out sign/certificate.pem \
-  -subj '/CN=Hello Vela Development/O=Example/C=US'
-```
-
-Then compile the release package:
-
-```bash
-npm run release
-find dist -maxdepth 1 -type f -name '*.release.*.rpk' -print
-```
-
-Do not commit or share `sign/private.pem`. If a companion Android application communicates with the watch app, Xiaomi's wearable integration may require matching signing identity; changing certificates later can also prevent an update from being accepted as the same app.
-
-## 5. Change the app
-
-Edit `src/pages/index/index.ux`. For example, replace:
-
-```xml
-<text class="hello">Hello World!</text>
-```
-
-with:
-
-```xml
-<text class="hello">My first app</text>
-```
-
-Then rebuild:
-
-```bash
-npm run build
-```
-
-When publishing an update, increase `versionCode` in `src/manifest.json`. Also update `versionName` when you want the visible version string to change.
-
-## 6. Important Vela rules
-
-- A template must have exactly one root element.
-- Visible text must be inside a `<text>` component.
-- Vela uses flex layout, but its CSS support is smaller than a browser's CSS support.
-- Package names should use reverse-domain form, such as `com.yourname.hello`.
-- `designWidth: 480` lets Vela scale the 480-pixel design to the physical display.
-- APIs such as sensors, storage, network, or vibration must usually be declared in the manifest's `features` array before use. This Hello World app requests no APIs.
-
-## 7. Installing on a real Watch S4
-
-Compilation and installation are separate. The terminal workflow above reliably creates the `.rpk`; transferring it to a physical watch depends on the exact Watch S4 model, firmware region, Mi Fitness version, and whether developer or debugging access is enabled for that firmware.
-
-Do not treat the `.rpk` as an Android APK, and do not flash random firmware. Use Xiaomi's supported wearable deployment route for your device/account. Some retail or global firmware builds do not expose the same development or sideload controls as Chinese developer setups.
-
-## 8. Troubleshooting
-
-### `aiot: command not found`
-
-Always run the local tool through npm:
-
-```bash
-npm install
-npm run build
-```
-
-Do not rely on a global `aiot` installation.
-
-### Dependency installation fails
-
-Clear only this project's installed dependencies and retry:
-
-```bash
-rm -rf node_modules
-npm install
-```
-
-If you use a company proxy, configure npm for that proxy instead of disabling TLS verification.
-
-### No `.rpk` appears
-
-Read the first compiler error, then verify:
-
-```bash
-npx aiot build -h
-find src -maxdepth 4 -type f -print
-```
-
-The required files are `src/manifest.json`, `src/app.ux`, and the routed page component.
-
-### Release build says signing files are missing
-
-Run the OpenSSL command in section 4 and confirm:
-
-```bash
-test -s sign/private.pem && test -s sign/certificate.pem && echo 'Signing files exist'
-```
-
-## Official references
-
-- Xiaomi Vela JS documentation: <https://iot.mi.com/vela/quickapp/en/>
-- Project structure: <https://iot.mi.com/vela/quickapp/zh/guide/start/project-overview.html>
-- Manifest configuration: <https://iot.mi.com/vela/quickapp/zh/guide/framework/manifest.html>
-- Compiler parameters: <https://iot.mi.com/vela/quickapp/zh/guide/start/toolkit-params.html>
-- UI introduction: <https://iot.mi.com/vela/quickapp/zh/guide/start/user-interface.html>
-
-The project intentionally uses only the public `aiot-toolkit` command-line package. It does not require Xiaomi AIoT-IDE.
+- **0.1** — first build; black-screened + soft-rebooted on watch (crash suspect: chained
+  percentage transforms on a zero-size container)
+- **0.2** — replaced % transforms with bound px coordinates (`markerStyle`); WORKS
+- **0.3** — designWidth 480→466 (fixed off-center sky disc), bezel ring, hour ticks,
+  two-tone dial, sun halo, orbit r=150
+- **0.5** — user-supplied circular icon