From 670119f93e8b0fda4fea5f927f873da6f69728ea Mon Sep 17 00:00:00 2001
From: Markus Graf <info@markusgraf.ch>
Date: Fri, 31 Jul 2026 16:20:50 +0200
Subject: [PATCH] docs: document alarm styles and per-alarm style selection

Add an Alarm Styles section (simple vs blink), show --style in manual usage,
and update the GraphQL examples (setAlarm/getAlarms/startRinging) to include
the style field/argument. Note backward compat for legacy cron entries.
---
 README.md | 28 ++++++++++++++++++++++++----
 1 file changed, 24 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 42eecde..92960bc 100644
--- a/README.md
+++ b/README.md
@@ -35,8 +35,11 @@ Please refer to the [arcade-button-wiring.md](arcade-button-wiring.md) file for
 
    # Or pass a custom music file directly
    python3 wecker.py --music-file /path/to/your/alarm.mp3
+
+   # Choose an alarm style (default: blink; see Alarm Styles below)
+   python3 wecker.py --style simple
    ```
-   The music file is resolved in this order: `--music-file` argument, `MUSIC_FILE` environment variable, default `Laid Back - Sunshine Reggae.mp3`.
+   The music file is resolved in this order: `--music-file` argument, `MUSIC_FILE` environment variable, default `Laid Back - Sunshine Reggae.mp3`. The `--style` argument selects the alarm behaviour and defaults to `blink` (so existing cron entries keep working unchanged).
 
 ## Automating and Managing Alarms (GraphQL API)
 
@@ -83,6 +86,7 @@ query {
     id
     cronExpression
     isEnabled
+    style
   }
 }
 ```
@@ -92,14 +96,17 @@ query {
 mutation {
   setAlarm(
     cronExpression: "45 6 * * 1-5",
-    isEnabled: true
+    isEnabled: true,
+    style: "simple"
   ) {
     id
     cronExpression
     isEnabled
+    style
   }
 }
 ```
+`style` is optional and defaults to `"simple"` (see [Alarm Styles](#alarm-styles)).
 *(Note: `command` is generated automatically by the API and is **not** accepted as an input parameter on `setAlarm`, to prevent command injection into the system crontab.)*
 
 **Delete an alarm:**
@@ -112,10 +119,10 @@ mutation {
 **Start the alarm immediately:**
 ```graphql
 mutation {
-  startRinging
+  startRinging(style: "blink")
 }
 ```
-Returns `true` if the alarm started, `false` if it was already ringing (ignored).
+Returns `true` if the alarm started, `false` if it was already ringing (ignored). `style` is optional and defaults to `"simple"`.
 
 **Stop the alarm immediately:**
 ```graphql
@@ -134,6 +141,19 @@ Returns `true` if the alarm was stopped, `false` if it wasn't ringing.
 }
 ```
 
+## Alarm Styles
+
+Each alarm has a **style** that decides how you turn it off. Set it per alarm via the `style` field of `setAlarm` (or the `style` argument of `startRinging`). Available styles:
+
+| Style | Behaviour |
+|---|---|
+| `simple` | Press the button once to stop. The LED stays solid on so the button is findable in the dark. **Default for new alarms.** |
+| `blink` | The memory-and-attention puzzle described in [How the Puzzle Works](#how-the-puzzle-works). |
+
+Adding a style is a plugin-style drop-in: add a class under `styles/` implementing the `AlarmStyle` contract (`__init__(set_led)` + `update(now, is_pressed) -> bool`) and register one line in `styles/__init__.py`.
+
+**Backward compatibility:** existing cron entries created before this feature have no `--style` flag and keep running the `blink` puzzle, so an upgrade never silently changes an alarm. To switch an existing alarm to `simple`, re-save it with `setAlarm(id: ..., cronExpression: ..., style: "simple")`.
+
 ## How the Puzzle Works
 1. **Ringing:** The music plays in an endless loop.
 2. **Start:** Press the arcade button once to start the puzzle. Wait 3 seconds.