docs: refresh README, INSTALL, CONTRIBUTING, .env.example for v0.7.0 multi-tenant

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: AmmarSaleh50

.env.example

@@ -1,10 +1,10 @@
 # ─── Backend (.env at repo root — read by the openstudy container) ─────────
 
-# Bootstrap-only: the scripts/seed_operator_password.py script reads this on
-# first deploy to set users.password_hash for the operator account in the DB.
-# After that, login uses users.password_hash from the DB — this env var is no
-# longer read at request time. Generate the hash with:
-#   uv run app/tools/hashpw.py
+# Bootstrap-only: scripts/seed_operator_password.py reads this on each deploy
+# to set users.password_hash for the operator account. It only writes the hash
+# if the existing DB row has none — so redeploying never clobbers a password
+# you changed through the UI. Generate the hash with:
+#   uv run python -m app.tools.hashpw
 APP_PASSWORD_HASH=
 
 # Random secret for session signing. REQUIRED — app refuses to start without one.
@@ -40,29 +40,34 @@ INTERNAL_API_SECRET=
 # bot token, chat ID, and webhook secret via the Settings UI; secrets are
 # stored encrypted per-user in the `user_secrets` table.
 
-# Symmetric encryption key for at-rest secrets (Telegram tokens, Moodle
-# creds, etc. — Phase 6 uses this). Mint once with:
-#   python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())'
+# Symmetric encryption key for at-rest per-user secrets (Telegram tokens, etc.).
+# REQUIRED for production — the app will refuse Telegram operations without it.
+# Mint once with:
+#   python3 -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())'
 SECRETS_ENCRYPTION_KEY=
 
-# Phase 1+ — operator identity. Defaults match the seed row created by
-# the users-table migration. Self-hosters can override these — but if you
-# do, also UPDATE the users row in DB to match (or wait for Phase 3's
-# signup endpoints).
+# Operator identity. scripts/seed_operator_password.py reads these on every
+# deploy to reconcile the operator row in the users table. Set OPERATOR_EMAIL
+# to your login address before the first deploy — that is the username you
+# will use at /login. OPERATOR_USER_ID and OPERATOR_DISPLAY_NAME are optional.
 OPERATOR_USER_ID=00000000-0000-0000-0000-000000000001
-OPERATOR_EMAIL=operator@local
+OPERATOR_EMAIL=
 OPERATOR_DISPLAY_NAME=Operator
 
-# Email (Phase 3+). Default backend is 'console' which prints to stdout (tests).
-# For prod: set EMAIL_BACKEND=gmail_smtp and provide app-password creds from
-# https://myaccount.google.com/apppasswords
+# Email backend. Default 'console' prints email bodies to stdout (fine for
+# local dev and testing). For real email delivery:
+#   EMAIL_BACKEND=gmail_smtp
+#   GMAIL_SMTP_USER=you@gmail.com
+#   GMAIL_SMTP_APP_PASSWORD=<16-char app password from myaccount.google.com/apppasswords>
 EMAIL_BACKEND=console
 GMAIL_SMTP_USER=
 GMAIL_SMTP_APP_PASSWORD=
 EMAIL_FROM=hello@openstudy.dev
 EMAIL_FROM_NAME=OpenStudy
+
+# Allow public registration. Default false — only the operator account (seeded
+# from OPERATOR_EMAIL above) can log in. Set to true to open signup.
 SIGNUPS_ENABLED=false
-PUBLIC_URL=http://localhost:5173
 
 # ─── Frontend (web/.env.production for prod, web/.env.local for dev) ───────
 

CONTRIBUTING.md

@@ -18,8 +18,7 @@ phases is easier to reason about.
   multi-tenant migration). Created via `/auth/signup` (post-Phase 3) or
   by the operator via CLI. Many users per deployment.
 
-Pre-multi-tenant (≤ v0.6) the operator and user are the same person.
-Post v0.7, they diverge: the operator administers the server; users sign
+As of v0.7, they diverge: the operator administers the server; users sign
 up and use the product. Auth code paths use `User` (a dataclass in
 `app/auth.py`) to carry the user identity through requests.
 
@@ -33,7 +32,7 @@ Basically anything that makes the app better for someone self-hosting it. A non-
 - **i18n / localization** — the Slot `kind` labels are German (`Vorlesung`, `Übung`) by default. Making those user-configurable or translatable would help non-EU users a lot.
 - **New MCP tools** — if you find yourself wishing Claude could do `X` and there's a natural way to expose it, just add it. Pattern is in `app/mcp_tools.py`.
 - **Performance / bundle size** — the frontend chunk is bigger than it needs to be; someone who knows their way around Vite code-splitting could shave a lot.
-- **Tests** — there's no suite yet. Adding pytest + Vitest scaffolding is its own welcome PR.
+- **Tests** — the backend has 318 pytest tests; the frontend has none yet. A Vitest suite for the frontend is its own welcome PR.
 
 ## Things worth a quick issue first
 
@@ -42,7 +41,7 @@ Not "no" — just "let's talk first so you don't waste a weekend":
 - Major framework swaps (React → Svelte, FastAPI → Django).
 - Replacing the `psycopg` async pool with a different DB driver (SQLAlchemy, asyncpg, etc.) — the pool is small but it's load-bearing; every service file goes through it.
 - New top-level entities beyond the current data model (Course / Schedule slot / Lecture / Study topic / Deliverable / Task / Klausur).
-- Multi-user / team / sharing features — the single-user-per-deploy assumption is load-bearing in a bunch of places, and shifting it is a big project.
+- Replacing the multi-tenant data model — every owned table has a `user_id` FK; any change to that assumption touches a lot of files and is a big conversation first.
 
 A one-liner issue like *"would you take a PR that X?"* is all it takes.
 
@@ -51,7 +50,7 @@ A one-liner issue like *"would you take a PR that X?"* is all it takes.
 See [INSTALL.md](./INSTALL.md) for the full walkthrough. TL;DR:
 
 ```bash
-cp .env.example .env                 # fill APP_PASSWORD_HASH, SESSION_SECRET
+cp .env.example .env                 # fill OPERATOR_EMAIL, APP_PASSWORD_HASH, SESSION_SECRET, SECRETS_ENCRYPTION_KEY
 cat > .env.docker <<EOF              # Postgres credentials
 POSTGRES_USER=openstudy
 POSTGRES_PASSWORD=$(openssl rand -hex 24)
@@ -75,7 +74,7 @@ cd web && pnpm install && pnpm dev
 
 ## Testing
 
-The backend has a pytest suite (213 tests as of v0.6.0) that runs against a real Postgres testcontainer with per-test transaction rollback — every test gets a clean DB state without paying for container churn. Service-layer, MCP-tool, and end-to-end OAuth/login flows are all covered.
+The backend has a pytest suite (318 tests as of v0.7.0) that runs against a real Postgres testcontainer with per-test transaction rollback — every test gets a clean DB state without paying for container churn. Service-layer, MCP-tool, and end-to-end OAuth/login flows are all covered.
 
 ```bash
 uv run --no-sync pytest -q              # full suite

INSTALL.md

@@ -55,27 +55,47 @@ guide. Anywhere else works; just adjust the paths below.
 
 OpenStudy reads two env files, both kept out of git:
 
-- **`.env`** — application secrets used by the FastAPI container
-  (login password hash, session secret, optional integrations).
-- **`.env.docker`** — Postgres credentials only, used to spin up the
-  database container.
+- **`.env`** — application secrets and operator identity, read by the
+  FastAPI container at startup and at deploy time by
+  `scripts/seed_operator_password.py`.
+- **`.env.docker`** — Postgres credentials only, used by Docker Compose
+  to provision and reach the database container.
 
-Create them:
+### `.env` — required vars
+
+Copy the template, then fill in at minimum these five variables:
 
 ```bash
-# .env — copy the template, then fill in the placeholders
 cp .env.example .env
+```
+
+| Variable | How to generate / what to put |
+|---|---|
+| `OPERATOR_EMAIL` | Your login email address. This is the username you'll use at `/login`. |
+| `APP_PASSWORD_HASH` | Run `uv run python -m app.tools.hashpw` and paste the output (`$argon2id$...`). |
+| `SESSION_SECRET` | `python3 -c 'import secrets; print(secrets.token_urlsafe(48))'` |
+| `SECRETS_ENCRYPTION_KEY` | `python3 -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())'` |
+| `PUBLIC_URL` | The public origin of your deploy, e.g. `https://your-domain.tld`. Used in OAuth callbacks and email links. Leave blank for local dev (derived from the inbound request). |
 
-# Argon2id-hash a login password you'll use to sign in
-docker run --rm python:3.12-slim sh -c \
-  'pip install -q argon2-cffi && python -c "from argon2 import PasswordHasher; print(PasswordHasher().hash(input(\"password: \")))"'
-# → paste the resulting hash as APP_PASSWORD_HASH in .env
+`OPERATOR_DISPLAY_NAME` defaults to `"Operator"` — set it to your name if you like.
 
-# Generate a session-cookie signing secret
-python3 -c 'import secrets; print(secrets.token_urlsafe(48))'
-# → paste as SESSION_SECRET in .env
+`SIGNUPS_ENABLED` defaults to `false` (operator-only). Set to `true` to open public registration.
 
-# Generate a strong Postgres password and write the docker-only env file
+`EMAIL_BACKEND` defaults to `console` (emails print to stdout). For real email:
+
+```
+EMAIL_BACKEND=gmail_smtp
+GMAIL_SMTP_USER=you@gmail.com
+GMAIL_SMTP_APP_PASSWORD=<16-char app password from myaccount.google.com/apppasswords>
+EMAIL_FROM=you@gmail.com
+EMAIL_FROM_NAME=Your Name
+```
+
+Telegram credentials are per-user — each user configures their own bot token and chat ID via **Settings → Telegram** after logging in. No env vars needed.
+
+### `.env.docker` — Postgres credentials
+
+```bash
 cat > .env.docker <<EOF
 POSTGRES_USER=openstudy
 POSTGRES_PASSWORD=$(openssl rand -hex 24)
@@ -84,10 +104,13 @@ EOF
 chmod 600 .env .env.docker
 ```
 
-The other variables in `.env` are optional and document themselves —
-the internal API secret used by webhooks, the public URL the app
-advertises in OAuth flows. Telegram credentials are configured per-user
-via **Settings → Telegram** after first login (no env vars needed).
+Optionally bake your domain into the frontend image at build time (affects canonical tags, OG metadata, sitemap, and manifest):
+
+```
+PUBLIC_SITE_URL=https://your-domain.tld
+PUBLIC_SITE_NAME=Your Site Name
+PUBLIC_SHOW_LANDING=false
+```
 
 ---
 
@@ -123,20 +146,27 @@ You should also see the running containers (`openstudy`, `openstudy-postgres`,
 
 ### First-time operator login
 
-After running `./deploy.sh`:
+`./deploy.sh` automatically invokes `scripts/seed_operator_password.py`
+after migrations. That script reads your `.env` and reconciles the operator
+row in the `users` table:
+
+- If `OPERATOR_EMAIL` is set, it ensures a user row with that email exists.
+- If `APP_PASSWORD_HASH` is set **and** the row has no password yet, it
+  writes the hash — so re-running `./deploy.sh` never clobbers a password
+  you changed through the UI.
+- `OPERATOR_DISPLAY_NAME` is applied if provided.
+
+After the first `./deploy.sh`:
 
-1. Set `APP_PASSWORD_HASH` in `.env.docker` to your argon2id-hashed password
-   (use `uv run python -m app.tools.hashpw 'your-password'` to generate).
-2. Set `OPERATOR_EMAIL` to your email (or leave the default `operator@local`).
-3. Run `./deploy.sh` — it invokes `scripts/seed_operator_password.py` which
-   sets `users.password_hash` for the operator user from your env var.
-4. Log in at `https://your-domain/login` with `OPERATOR_EMAIL` + your password.
-5. Configure your Telegram bot in **Settings → Telegram** (per-user; no env
-   vars needed).
+1. Open `https://your-domain.tld/login`.
+2. Sign in with the email you set as `OPERATOR_EMAIL` and the password you
+   hashed into `APP_PASSWORD_HASH`.
+3. Go to **Settings → Telegram** to configure notifications (per-user, no
+   env vars required).
 
-`APP_PASSWORD_HASH` is bootstrap-only — the seed script reads it once at
-deploy time. Subsequent logins authenticate against `users.password_hash`
-in the database.
+If you need to reset the operator password later, update `APP_PASSWORD_HASH`
+in `.env` and delete the existing `password_hash` in the database, then
+redeploy — the seed script will write the new hash.
 
 ### Restoring data into a fresh box
 
@@ -323,13 +353,20 @@ and is readable by the container. `docker exec openstudy ls /opt/courses`
 should show your course tree.
 
 **Login returns 401 with the right password.**
-Re-hash the password, update `APP_PASSWORD_HASH` in `.env.docker`, then
-run `./deploy.sh` so `scripts/seed_operator_password.py` writes the new
-hash into `users.password_hash`. Common gotcha: the hash starts with
-`$argon2id$…` — those `$` characters are literal, not env interpolation.
-The compose `env_file: format: raw` directive prevents mangling, but if
-you've manually exported the variable in a shell, the `$` chars need to
-be single-quoted.
+Re-hash the password with `uv run python -m app.tools.hashpw`, update
+`APP_PASSWORD_HASH` in `.env` (not `.env.docker`), then manually clear the
+existing hash in the database so the seed script writes the new one:
+
+```bash
+docker exec -it openstudy-postgres psql -U openstudy -d openstudy \
+  -c "UPDATE users SET password_hash = NULL WHERE email = 'your-email@example.com';"
+./deploy.sh
+```
+
+Common gotcha: the hash starts with `$argon2id$…` — those `$` characters
+are literal, not env interpolation. The compose `env_file: format: raw`
+directive prevents mangling, but if you've manually exported the variable
+in a shell, the `$` chars need to be single-quoted.
 
 **MCP returns 401 from a Claude client.**
 The OAuth token cached by the client expired or was revoked. Reconnect:

README.md

@@ -14,7 +14,7 @@ A self-hostable personal study dashboard. Track your **courses, schedule, lectur
 ![Database: Postgres 16](https://img.shields.io/badge/db-Postgres%2016-336791)
 ![AI: MCP-native (44 tools)](https://img.shields.io/badge/AI-MCP--native%2044%20tools-7c3aed)
 ![Self-hosted](https://img.shields.io/badge/hosting-self--hosted-111)
-![Status: alpha](https://img.shields.io/badge/status-alpha-orange)
+![Version: v0.7.0](https://img.shields.io/badge/version-v0.7.0-green)
 
 ### Five themes — pick the one that fits your brain
 
@@ -114,7 +114,7 @@ The dashboard is where I see things. Claude is how I edit them. Same database be
 
 The MCP server ships with **44 tools — anything you can do in the UI, Claude can do too**. Create a study topic, mark something studied, upload a file, render a PDF as images, whatever.
 
-- **Multi-tenant SaaS-capable:** per-user data isolation enforced at both the service layer (WHERE filters) and the schema layer (composite FKs + RLS policies). Self-host as single-user or invite many users — same codebase.
+- **Multi-tenant:** every owned table carries a `user_id` FK. Data isolation is enforced at the service layer (WHERE filters) and the schema layer (composite FKs + RLS policies). Run it solo or flip `SIGNUPS_ENABLED=true` to open registration — same codebase, same deploy.
 
 Plug it into Claude.ai as a custom connector (full OAuth 2.1) and those tools are live in **Claude Code on your laptop, claude.ai in your browser, and the Claude iOS app on your phone**. Open Claude anywhere and it has the same view of your coursework that you do.
 
@@ -143,25 +143,36 @@ cd web && pnpm install && cd ..
 
 **2. Generate secrets and write `.env` files.**
 
+Open `.env` and fill in the required values:
+
 ```bash
 cp .env.example .env
 
-# Pick a login password, hash it with Argon2id, and paste the result as APP_PASSWORD_HASH:
-docker run --rm python:3.12-slim sh -c 'pip install -q argon2-cffi && python -c "from argon2 import PasswordHasher; print(PasswordHasher().hash(input(\"password: \")))"'
+# Set your login email (this becomes your username):
+#   OPERATOR_EMAIL=you@example.com
+
+# Hash a password for first login and paste as APP_PASSWORD_HASH:
+uv run python -m app.tools.hashpw
+# → paste the resulting $argon2id$... string as APP_PASSWORD_HASH
+
+# Generate a session-cookie signing secret:
+python3 -c 'import secrets; print(secrets.token_urlsafe(48))'
+# → paste as SESSION_SECRET
 
-# Generate a 48-byte session secret and paste as SESSION_SECRET:
-python -c 'import secrets; print(secrets.token_urlsafe(48))'
+# Generate the encryption key for per-user secrets (Telegram tokens, etc.):
+python3 -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())'
+# → paste as SECRETS_ENCRYPTION_KEY
 
 # Generate a Postgres password and write the Docker-only env file:
 cat > .env.docker <<EOF
 POSTGRES_USER=openstudy
 POSTGRES_PASSWORD=$(openssl rand -hex 24)
 POSTGRES_DB=openstudy
 EOF
-chmod 600 .env.docker
+chmod 600 .env .env.docker
 ```
 
-`.env` holds your application secrets (password hash, session secret, optional Telegram tokens). `.env.docker` holds the Postgres credentials that compose injects into the postgres container. Both are in `.gitignore`.
+`.env` holds your application secrets. `.env.docker` holds the Postgres credentials that compose injects into the postgres container. Both are in `.gitignore`.
 
 **3. Bring up the stack.**
 
@@ -417,25 +428,36 @@ cd web && pnpm install && cd ..
 
 **2. Secrets generieren und `.env`-Dateien schreiben.**
 
+`.env` öffnen und die Pflichtfelder ausfüllen:
+
 ```bash
 cp .env.example .env
 
-# Login-Passwort wählen, mit Argon2id hashen und als APP_PASSWORD_HASH einfügen:
-docker run --rm python:3.12-slim sh -c 'pip install -q argon2-cffi && python -c "from argon2 import PasswordHasher; print(PasswordHasher().hash(input(\"password: \")))"'
+# Login-E-Mail setzen (wird der Benutzername):
+#   OPERATOR_EMAIL=du@beispiel.de
+
+# Passwort hashen und als APP_PASSWORD_HASH einfügen:
+uv run python -m app.tools.hashpw
+# → den $argon2id$...-String als APP_PASSWORD_HASH einfügen
+
+# Session-Secret generieren:
+python3 -c 'import secrets; print(secrets.token_urlsafe(48))'
+# → als SESSION_SECRET einfügen
 
-# 48-Byte-Session-Secret generieren und als SESSION_SECRET einfügen:
-python -c 'import secrets; print(secrets.token_urlsafe(48))'
+# Verschlüsselungskey für Nutzer-Secrets generieren:
+python3 -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())'
+# → als SECRETS_ENCRYPTION_KEY einfügen
 
 # Postgres-Passwort generieren und die Docker-spezifische env-Datei schreiben:
 cat > .env.docker <<EOF
 POSTGRES_USER=openstudy
 POSTGRES_PASSWORD=$(openssl rand -hex 24)
 POSTGRES_DB=openstudy
 EOF
-chmod 600 .env.docker
+chmod 600 .env .env.docker
 ```
 
-`.env` enthält deine App-Secrets (Passwort-Hash, Session-Secret, optional Telegram-Tokens). `.env.docker` enthält die Postgres-Credentials, die Compose in den Postgres-Container injiziert. Beide sind in `.gitignore`.
+`.env` enthält deine App-Secrets. `.env.docker` enthält die Postgres-Credentials, die Compose in den Postgres-Container injiziert. Beide sind in `.gitignore`.
 
 **3. Stack starten.**