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/app.py

@@ -1,4 +1,4 @@
-"""FastAPI app: /api/duties and static webapp."""
+"""FastAPI app: /api/duties, /api/calendar-events, personal ICS, and static webapp at /app."""
 
 import logging
 from datetime import date, timedelta
@@ -33,7 +33,12 @@ app.add_middleware(
 )
 
 
-@app.get("/api/duties", response_model=list[DutyWithUser])
+@app.get(
+    "/api/duties",
+    response_model=list[DutyWithUser],
+    summary="List duties",
+    description="Returns duties for the given date range. Requires Telegram Mini App initData (or MINI_APP_SKIP_AUTH / private IP in dev).",
+)
 def list_duties(
     request: Request,
     dates: tuple[str, str] = Depends(get_validated_dates),
@@ -48,7 +53,12 @@ def list_duties(
     return fetch_duties_response(session, from_date_val, to_date_val)
 
 
-@app.get("/api/calendar-events", response_model=list[CalendarEvent])
+@app.get(
+    "/api/calendar-events",
+    response_model=list[CalendarEvent],
+    summary="List calendar events",
+    description="Returns calendar events for the date range, including external ICS when EXTERNAL_CALENDAR_ICS_URL is set. Auth same as /api/duties.",
+)
 def list_calendar_events(
     dates: tuple[str, str] = Depends(get_validated_dates),
     _username: str = Depends(require_miniapp_username),
@@ -61,7 +71,11 @@ def list_calendar_events(
     return [CalendarEvent(date=e["date"], summary=e["summary"]) for e in events]
 
 
-@app.get("/api/calendar/ical/{token}.ics")
+@app.get(
+    "/api/calendar/ical/{token}.ics",
+    summary="Personal calendar ICS",
+    description="Returns an ICS calendar with only the subscribing user's duties. No Telegram auth; access is by secret token in the URL.",
+)
 def get_personal_calendar_ical(
     token: str,
     session: Session = Depends(get_db_session),