chore: update project configuration and documentation

- Added *.egg-info/ to .gitignore to prevent egg metadata from being tracked.
- Updated virtual environment instructions in CONTRIBUTING.md and README.md to use .venv for consistency.
- Revised mkdocs.yml to include a placeholder for the repository URL when publishing.
- Cleaned up pyproject.toml by removing unnecessary pylint configuration.
- Enhanced import-format.md and runbook.md documentation for clarity on user roles and health check endpoints.

.gitea/workflows/ci.yml

@@ -32,10 +32,10 @@ jobs:
 
       - name: Run tests
         env:
-          PYTHONPATH: src
+          PYTHONPATH: .
         run: |
           pytest tests/ -v
 
       - name: Security check with Bandit
         run: |
-          bandit -r src -ll
+          bandit -r duty_teller -ll

.gitignore

@@ -2,6 +2,7 @@
 __pycache__/
 venv/
 .venv/
+*.egg-info/
 *.pyc
 *.pyo
 data/

CHANGELOG.md

@@ -36,4 +36,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Input validation and initData hash verification for Miniapp access.
 - Optional CORS and init_data_max_age; use env for secrets.
 
-[0.1.0]: https://github.com/your-org/duty-teller/releases/tag/v0.1.0
+[0.1.0]: https://github.com/your-org/duty-teller/releases/tag/v0.1.0  <!-- placeholder: set to your repo URL when publishing -->

CONTRIBUTING.md

@@ -10,9 +10,9 @@
 
 2. **Create a virtual environment**
    ```bash
-   python -m venv venv
+   python -m venv .venv
-   source venv/bin/activate   # Linux/macOS
+   source .venv/bin/activate   # Linux/macOS
-   # or: venv\Scripts\activate  # Windows
+   # or: .venv\Scripts\activate  # Windows
    ```
 
 3. **Install dependencies**

README.md

@@ -19,9 +19,9 @@ A minimal Telegram bot boilerplate using [python-telegram-bot](https://github.co
 
 2. **Create a virtual environment (recommended)**
    ```bash
-   python -m venv venv
+   python -m venv .venv
-   source venv/bin/activate   # Linux/macOS
+   source .venv/bin/activate   # Linux/macOS
-   # or: venv\Scripts\activate  # Windows
+   # or: .venv\Scripts\activate  # Windows
    ```
 
 3. **Install dependencies**
@@ -144,7 +144,7 @@ pytest
 
 Tests cover `api/telegram_auth` (validate_init_data, auth_date expiry), `config` (is_admin, can_access_miniapp), and the API (date validation, 403/200 with mocked auth, plus an E2E auth test without auth mocks).
 
-**CI (Gitea Actions):** Lint (ruff), tests (pytest), security (bandit). If the workflow uses `PYTHONPATH: src` or `bandit -r src`, update it to match the repo layout (no `src/`).
+**CI (Gitea Actions):** Lint (ruff), tests (pytest), security (bandit). Run from the repo root with `PYTHONPATH=.` if needed.
 
 ## Contributing
 

docs/import-format.md

@@ -1,6 +1,6 @@
 # Duty-schedule import format
 
-The **duty-schedule** format is used by the `/import_duty_schedule` command. Only users in `ADMIN_USERNAMES` or `ADMIN_PHONES` can import.
+The **duty-schedule** format is used by the `/import_duty_schedule` command. Only users in `ADMIN_USERNAMES` or `ADMIN_PHONES`, or users with the **admin** role in the database (assigned via `/set_role`), can import.
 
 ## Import flow
 

docs/runbook.md

@@ -31,8 +31,8 @@ On container start, `entrypoint.sh` runs Alembic migrations then starts the app
 
 ## Health check
 
-- **HTTP:** The FastAPI app serves the API and static webapp. A simple way to verify it is up is to open the interactive API docs: **`GET /docs`** (e.g. `http://localhost:8080/docs`). If that page loads, the server is running.
+- **HTTP:** The FastAPI app exposes **`GET /health`**, which returns `{"status": "ok"}` with 200 when the app is up. Use it for readiness checks and in Docker `HEALTHCHECK`.
-- There is no dedicated `/health` endpoint; use `/docs` or a lightweight API call (e.g. `GET /api/duties?from=...&to=...` with valid auth) as needed.
+- Alternatively, open the interactive API docs at **`GET /docs`** (e.g. `http://localhost:8080/docs`) or call a lightweight API endpoint with valid auth.
 
 ## Logs
 
@@ -63,8 +63,8 @@ On container start, `entrypoint.sh` runs Alembic migrations then starts the app
 
 ### User not in allowlist (403)
 
-- **Cause:** Telegram user’s username is not in `ALLOWED_USERNAMES` or `ADMIN_USERNAMES`, and (if using phone) their phone (set via `/set_phone`) is not in `ALLOWED_PHONES` or `ADMIN_PHONES`.
+- **Cause:** Miniapp access is determined by **roles in the database** (see `can_access_miniapp_for_telegram_user` in the repository). If the user has no role in the DB, the app falls back to `ADMIN_USERNAMES` and `ADMIN_PHONES`. A 403 means the user has neither a role granting access nor a match in the admin allowlist.
-- **Check:** [configuration.md](configuration.md) for `ALLOWED_USERNAMES`, `ADMIN_USERNAMES`, `ALLOWED_PHONES`, `ADMIN_PHONES`. Add the user or ask them to set phone and add it to the allowlist.
+- **Check:** Assign a role with `/set_role @username user` or `admin` (admin-only command), or add the user to `ADMIN_USERNAMES` / their phone to `ADMIN_PHONES` in [configuration.md](configuration.md). Ensure at least one admin exists via env so they can use `/set_role`.
 
 ## Database and migrations
 

duty_teller/config.py

@@ -147,7 +147,10 @@ def is_admin(username: str) -> bool:
 
 
 def can_access_miniapp(username: str) -> bool:
-    """Check if username is allowed to open the calendar Miniapp.
+    """Check if username is allowed to open the calendar Miniapp (env allowlist only).
+
+    Legacy: Miniapp access in production is determined by repository.can_access_miniapp_for_telegram_user
+    (DB roles + fallback to ADMIN_*). This function is kept for tests and backward compatibility.
 
     Args:
         username: Telegram username (with or without @; case-insensitive).
@@ -160,7 +163,10 @@ def can_access_miniapp(username: str) -> bool:
 
 
 def can_access_miniapp_by_phone(phone: str | None) -> bool:
-    """Check if phone (set via /set_phone) is allowed to open the Miniapp.
+    """Check if phone (set via /set_phone) is allowed to open the Miniapp (env allowlist only).
+
+    Legacy: Miniapp access in production is determined by repository.can_access_miniapp_for_telegram_user
+    (DB roles + fallback to ADMIN_*). This function is kept for tests and backward compatibility.
 
     Args:
         phone: Raw phone string or None.

mkdocs.yml

@@ -2,6 +2,7 @@
 # Build: mkdocs build. Preview: mkdocs serve.
 site_name: Duty Teller
 site_description: Telegram bot for team duty shift calendar and group reminder
+# Set to your repository URL when publishing (placeholder below).
 site_url: https://github.com/your-org/duty-teller
 
 docs_dir: docs

pyproject.toml

@@ -54,6 +54,3 @@ asyncio_mode = "auto"
 filterwarnings = [
     "ignore::DeprecationWarning:pytest_asyncio.plugin",
 ]
-
-[tool.pylint.messages_control]
-disable = ["C0114", "C0115", "C0116"]