chore: add changelog and documentation updates

- Created a new `CHANGELOG.md` file to document all notable changes to the project, adhering to the Keep a Changelog format.
- Updated `CONTRIBUTING.md` to include instructions for building and previewing documentation using MkDocs.
- Added `mkdocs.yml` configuration for documentation generation, including navigation structure and theme settings.
- Enhanced various documentation files, including API reference, architecture overview, configuration reference, and runbook, to provide comprehensive guidance for users and developers.
- Included new sections in the README for changelog and documentation links, improving accessibility to project information.

duty_teller/api/telegram_auth.py

@@ -15,7 +15,16 @@ def validate_init_data(
     bot_token: str,
     max_age_seconds: int | None = None,
 ) -> str | None:
-    """Validate initData and return username; see validate_init_data_with_reason for failure reason."""
+    """Validate Telegram Web App initData and return username if valid.
+
+    Args:
+        init_data: Raw initData string from tgWebAppData.
+        bot_token: Bot token (must match the bot that signed the data).
+        max_age_seconds: Reject if auth_date older than this; None to disable.
+
+    Returns:
+        Username (lowercase, no @) or None if validation fails.
+    """
     _, username, _, _ = validate_init_data_with_reason(
         init_data, bot_token, max_age_seconds
     )
@@ -35,12 +44,19 @@ def validate_init_data_with_reason(
     bot_token: str,
     max_age_seconds: int | None = None,
 ) -> tuple[int | None, str | None, str, str]:
-    """
-    Validate initData signature and return (telegram_user_id, username, reason, lang).
-    reason is one of: "ok", "empty", "no_hash", "hash_mismatch", "auth_date_expired",
-    "no_user", "user_invalid", "no_user_id", "no_username" (legacy; no_user_id used when user.id missing).
-    lang is from user.language_code normalized to 'ru' or 'en'; 'en' when no user.
-    On success: (user.id, user.get('username') or None, "ok", lang) — username may be None.
+    """Validate initData signature and return user id, username, reason, and lang.
+
+    Args:
+        init_data: Raw initData string from tgWebAppData.
+        bot_token: Bot token (must match the bot that signed the data).
+        max_age_seconds: Reject if auth_date older than this; None to disable.
+
+    Returns:
+        Tuple (telegram_user_id, username, reason, lang). reason is one of: "ok",
+        "empty", "no_hash", "hash_mismatch", "auth_date_expired", "no_user",
+        "user_invalid", "no_user_id". lang is from user.language_code normalized
+        to 'ru' or 'en'; 'en' when no user. On success: (user.id, username or None,
+        "ok", lang).
     """
     if not init_data or not bot_token:
         return (None, None, "empty", "en")