docs: add user-friendly Furo documentation site

.github/workflows/docs.yml

@@ -0,0 +1,74 @@
+name: Deploy Docs to GitHub Pages
+
+# Builds the Sphinx (Furo) documentation in docs/ and publishes it to GitHub Pages.
+#
+# The build job uses actions/configure-pages with enablement, which programmatically
+# sets the repo's Pages source to "GitHub Actions" — so you do NOT need to manually
+# flip Settings -> Pages -> Source. It also stops the automatic Jekyll builder
+# ("pages build and deployment") from serving raw Markdown.
+#
+# Publishes to: https://<your-username>.github.io/<your-repo>/
+# No secrets required — GitHub Pages uses the built-in GITHUB_TOKEN.
+#
+# NOTE: "docs/user-guide" is included below so the site can be previewed before the
+#       PR is merged. After merging, that branch line can be removed (master is enough).
+
+on:
+  push:
+    branches: [main, master, docs/user-guide]
+    paths:
+      - "docs/**"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+# Allow the workflow to publish to GitHub Pages.
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Only one Pages deployment at a time; don't cancel an in-progress one.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Configure GitHub Pages (sets source to GitHub Actions)
+        uses: actions/configure-pages@v5
+        with:
+          enablement: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+          cache-dependency-path: docs/requirements.txt
+
+      - name: Install documentation dependencies
+        run: pip install -r docs/requirements.txt
+
+      - name: Build the documentation
+        run: sphinx-build -b html -W --keep-going docs docs/_build/html
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

docs/.gitignore

@@ -0,0 +1,5 @@
+# Sphinx build output
+_build/
+
+# Local virtual environment used to build the docs
+.venv/

docs/_static/custom.css

@@ -0,0 +1,21 @@
+/* Small visual tweaks on top of the Furo theme. */
+
+/* Make callout boxes a touch more prominent. */
+.admonition {
+    border-radius: 8px;
+}
+
+/* Nicer tables that stretch to full width. */
+table.docutils {
+    width: 100%;
+}
+
+/* Slightly rounder code blocks. */
+div.highlight {
+    border-radius: 8px;
+}
+
+/* Emoji-friendly headings keep their spacing. */
+h1, h2, h3 {
+    scroll-margin-top: 1.5rem;
+}

docs/admin-panel.md

@@ -0,0 +1,97 @@
+# Admin Panel
+
+The web admin panel is your control center — no command line needed for daily tasks. Log
+in at `/login` (default `admin` / `admin`, which you should change immediately).
+
+```{admonition} Beginner Tip
+:class: tip
+Almost everything you'd ever want to do lives here as a button or form. The old bot
+commands for stats, logs, scanning, and restarting have all moved into this panel.
+```
+
+## Dashboard
+
+Your landing page after login. Shows an at-a-glance overview of your library and system —
+counts, recent activity, and quick links to the main sections.
+
+## Media Library
+
+Under **Media Management** you can browse **Movies** and **TV Shows**, search, and page
+through everything. For each title you can:
+
+- **Edit** its details or **Scan Metadata** to fix a wrong match.
+- Delete a single **quality**, **episode**, **season**, or the whole title.
+- **Manually add** custom movies, shows, seasons, episodes, or extra qualities.
+
+See {doc}`media-management` for the details.
+
+## Catalogs
+
+Create and manage **custom catalogs**, set their **visibility**, and configure which
+**automatic catalogs** are enabled. See {doc}`catalogs`.
+
+## Users & Access
+
+**Access Management** and **Subscription Management** let you handle tokens, plans, and
+subscribers. See {doc}`user-management`.
+
+## Content Requests
+
+A public **request page** (`/request`) lets viewers ask for titles. Admins review incoming
+requests under **Admin → Requests**, and can approve, update, or delete them. Fulfilled
+requests can notify the requester automatically.
+
+## Analytics
+
+See live and recent **streaming stats** — active streams, throughput, and history — plus
+tools to clear analytics. Helpful for spotting heavy usage or dead content.
+
+## Health Dashboard
+
+A **Health** report checks that your key pieces — Telegram connection, databases,
+streaming — are responsive. Use it as your first stop when something feels off.
+
+## Tools
+
+The **Tools** page replaces the old scanning bot commands:
+
+- **Scan** a channel to index existing files (start / cancel / view status).
+- **DB Check** to verify database integrity (start / cancel / status).
+- **Dead Links** detection and purge, to clean up entries whose Telegram files are gone.
+
+```{admonition} Good to Know
+:class: note
+A **scan** is how you import files that were already in a channel *before* you set up the
+bot. New uploads are indexed automatically without scanning.
+```
+
+## Settings
+
+The full configuration page (`/admin/settings`) — general options, admin login, media
+keys, subscriptions, proxy, extra databases, and multi-token clients. Everything here is
+applied instantly. See {doc}`configuration`.
+
+## Backup & Restore
+
+From Settings you can **export** your configuration to a JSON file and **import** it later
+— useful before migrating servers or making big changes. See {doc}`updating`.
+
+## Bot commands
+
+A few things still live in the Telegram bot itself:
+
+```{list-table}
+:header-rows: 1
+:widths: 20 80
+
+* - Command
+  - What it does
+* - `/start`
+  - Returns your **addon URL** (or the subscription flow, if enabled)
+* - `/set <imdb-url>`
+  - Sets a metadata override for the files you upload next; send `/set` alone to clear it
+* - `/log`
+  - Sends the latest log file for debugging
+* - `/restart`
+  - Restarts the bot and pulls the latest updates from your upstream repo
+```

docs/api-reference.md

@@ -0,0 +1,120 @@
+# API Reference
+
+This page documents the HTTP endpoints your server exposes. Most users never touch these
+directly — Stremio calls them for you — but they're useful for debugging and integrations.
+
+```{admonition} Beginner Tip
+:class: tip
+You don't need to understand this page to use the app. It's here for the curious and for
+developers building on top of it.
+```
+
+## Authentication
+
+There are two kinds of protected routes:
+
+**Addon token** (`{token}` in the URL)
+: Every Stremio-facing route is scoped to a per-user token, e.g.
+  `/stremio/{token}/manifest.json`. Invalid or expired tokens are rejected (or shown a
+  subscription prompt).
+
+**Admin session** (web panel)
+: All `/api/admin/**` and management routes require you to be logged into the web panel.
+  Unauthenticated requests are redirected to `/login`.
+
+## Stremio addon endpoints
+
+These follow the standard Stremio addon protocol.
+
+```{list-table}
+:header-rows: 1
+:widths: 55 45
+
+* - Endpoint
+  - Purpose
+* - `GET /stremio/{token}/manifest.json`
+  - The addon manifest — declares catalogs and capabilities for this user
+* - `GET /stremio/{token}/catalog/{media_type}/{id}.json`
+  - A catalog listing (latest / popular / custom)
+* - `GET /stremio/{token}/catalog/{media_type}/{id}/{extra}.json`
+  - Same, with extra filters (genre, search, skip/pagination)
+* - `GET /stremio/{token}/meta/{media_type}/{id}.json`
+  - Detailed metadata for one title, including the episode list for series
+* - `GET /stremio/{token}/subtitles/{media_type}/{id}.json`
+  - Subtitles for a title/episode, sourced from subtitle files in your channels
+```
+
+### The manifest
+
+The manifest is **dynamic per user**. Its name and description reflect subscription state
+(e.g. `Telegram — Expires 28 Mar 2026`), and its version encodes the expiry so Stremio
+detects updates when you change a subscription.
+
+## Streaming endpoints
+
+```{list-table}
+:header-rows: 1
+:widths: 55 45
+
+* - Endpoint
+  - Purpose
+* - `GET` / `HEAD` `/dl/{token}/{id}/{name}`
+  - The actual video stream (supports range requests for seeking)
+* - `GET /thumb/{id}`
+  - A public thumbnail image for a Telegram file (used as artwork)
+* - `GET /sub/{token}/{id}/{name}`
+  - Serves a subtitle file (small, served fully in memory)
+* - `GET /stream/stats`
+  - Live and recent stream telemetry
+* - `GET /stream/stats/{stream_id}`
+  - Detailed telemetry for a single stream
+```
+
+```{admonition} How proxying affects the stream URL
+:class: note
+When an **HTTP Proxy URL** is configured, the app builds the stream link by prepending the
+proxy address in front of the `/dl/...` URL. With "Show Both" enabled, both the proxied and
+direct links are offered to the player.
+```
+
+## Admin & management API (session-protected)
+
+The web panel is powered by a large set of `/api/...` endpoints. Highlights:
+
+```{list-table}
+:header-rows: 1
+:widths: 50 50
+
+* - Area
+  - Example endpoints
+* - Media
+  - `GET /api/media/list`, `PUT /api/media/update`, `DELETE /api/media/delete`
+* - Rescan / metadata
+  - `GET /api/media/rescan/search`, `POST /api/media/rescan/apply`
+* - Manual add
+  - `POST /api/media/resolve-telegram`, `POST /api/media/manual-add`
+* - Custom catalogs
+  - `GET/POST /api/custom-catalogs`, `.../items`, `.../auto-sync`, `.../auto-sync/settings`
+* - Tokens & access
+  - `POST /api/tokens`, `DELETE /api/tokens/{token}`, `/api/admin/access/**`
+* - Subscriptions
+  - `/api/admin/subscriptions/plans`, `/api/admin/subscriptions/users`
+* - Requests
+  - `GET /api/admin/requests`, public `POST /api/request/submit`
+* - System & tools
+  - `/api/admin/health`, `/api/admin/tools/scan/**`, `/api/admin/tools/dbcheck/**`, `/api/admin/backup/export`
+```
+
+## Response format & errors
+
+- Successful API calls return **JSON**.
+- Stremio endpoints return the shapes Stremio expects (manifest, catalog metas, streams).
+- Common error behaviors:
+  - **401 / redirect to `/login`** — you're not authenticated to the admin panel.
+  - **Token rejected** — an invalid or expired addon token.
+  - **Empty catalog/streams** — usually means nothing matched or the item has no files yet.
+
+```{admonition} Good to Know
+:class: note
+CORS is open (`*`) so Stremio clients on any origin can talk to your addon.
+```