docs: clarify APScheduler cron usage and day-of-week numbering

- Updated `config.ini.example`, `command-reference.md`, and `configuration.md` to clarify the use of APScheduler for cron scheduling, emphasizing the difference in day-of-week numbering compared to Vixie cron.
- Added examples and notes to prevent confusion regarding the interpretation of cron expressions, particularly for users transitioning from Vixie cron conventions.
- Enhanced documentation to guide users in using the correct syntax for scheduling messages, ensuring better understanding and usability.

config.ini.example

@@ -505,12 +505,18 @@ category.funfact = fun
 # <schedule> is one of:
 #   - 5-field crontab (minute hour day-of-month month day-of-week), e.g.
 #       0 8 * * *     = every day at 08:00 (in [Bot] timezone)
-#       30 12 * * 1   = every Monday at 12:30
-#   - Preset aliases (same semantics as common cron @macros):
-#       @yearly @annually  @monthly  @weekly  @daily  @midnight  @hourly
+#       30 12 * * mon = every Monday at 12:30
+#       30 12 * * 0   = same (Monday) — see APScheduler note below
+#   - Preset aliases (@yearly @annually @monthly @weekly @daily @midnight @hourly).
+#     These expand to the 5-field forms above; @weekly is Monday 00:00 (not Sunday).
 #   - Deprecated (still accepted, logs a warning): HHMM = daily at that 24h clock time
 #       0800          = same as 0 8 * * *   — migrate to cron; HHMM will be removed later.
 #
+# APScheduler day-of-week (not Vixie cron):
+#   Numeric DOW is 0=Monday … 6=Sunday. Vixie cron uses 0=Sunday (and often allows 7=Sunday);
+#   APScheduler rejects 7. Prefer mon–sun names to avoid mixing conventions.
+#   Example trap: Vixie `0 12 * * 1` is Monday; here `0 12 * * 1` is Tuesday.
+#
 # Newlines: use \n in the message for a line break (e.g. general:Line one\nLine two).
 # Literal backslash: use \\n for backslash+n; \\t for tab.
 # 

docs/command-reference.md

@@ -1083,7 +1083,7 @@ schedule
 
 **Response:** Lists configured scheduled posts (each line shows the cron or preset schedule, or legacy `HH:MM` if you still use deprecated HHMM keys) plus current advert timing.
 
-**Note:** DM-only command by default.
+**Note:** DM-only command by default. Cron day-of-week uses APScheduler numbering (0=Monday), not Vixie cron — see [Scheduled messages](configuration.md#scheduled-messages-scheduled_messages).
 
 ---
 

docs/configuration.md

@@ -206,3 +206,19 @@ Admins can DM **`channelpause`** or **`channelresume`** (see `[Admin_ACL]` in `c
 ## Scheduled messages (`[Scheduled_Messages]`)
 
 Each entry is `<schedule_key> = <value>` where the value is normally **`channel:message`** (first colon separates channel from body). For **regional flood scope** on that send only, use **`channel:#scope:message`**: the middle segment must start with `#` (same convention as `flood_scopes` / `outgoing_flood_scope_override`). The message body may contain more colons. Omit the middle field for classic global flood. See `config.ini.example` under `[Scheduled_Messages]` for examples. The **`schedule`** command lists each job with `(#scope)` when set.
+
+### Schedule keys (APScheduler cron, not Vixie)
+
+Schedule keys are parsed by **APScheduler** `CronTrigger.from_crontab` (plus `@` presets and deprecated `HHMM`). Field order is the usual five: `minute hour day-of-month month day-of-week`.
+
+**Day-of-week numbering differs from classic Vixie / crontab(5):**
+
+| | APScheduler (this bot) | Vixie cron |
+| --- | --- | --- |
+| `0` | Monday | Sunday |
+| `1` … `6` | Tuesday … Sunday | Monday … Saturday |
+| `7` | Invalid | Often accepted as Sunday |
+
+Prefer **`mon`–`sun`** names in the DOW field so expressions stay unambiguous. Example: Monday 12:30 is `30 12 * * mon` or `30 12 * * 0` — **not** Vixie’s `30 12 * * 1` (that is Tuesday here).
+
+Preset aliases expand to those same APScheduler forms. In particular **`@weekly`** is Monday 00:00 (`0 0 * * 0`), not Sunday midnight as on many Unix crons.

modules/scheduled_message_cron.py

@@ -7,6 +7,10 @@ Supports (schedule keys):
 - Standard 5-field crontab: minute hour day-of-month month day-of-week
 - Preset aliases: @yearly, @annually, @monthly, @weekly, @daily, @midnight, @hourly
 - Deprecated legacy HHMM (24-hour, no colon) for daily firing at that clock time
+
+Day-of-week uses APScheduler numbering (0=Monday … 6=Sunday), not Vixie cron
+(0=Sunday; 7 often allowed). Prefer mon–sun names. ``@weekly`` expands to
+``0 0 * * 0`` (Monday 00:00). See docs/configuration.md and config.ini.example.
 """
 
 from __future__ import annotations