docs: v0.7.0 stable — multi-tenant migration complete

Author: AmmarSaleh50

CHANGELOG.md

@@ -4,6 +4,52 @@ All notable changes to OpenStudy will be documented here.
 Format loosely follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 versions follow [SemVer](https://semver.org/spec/v2.0.0.html).
 
+## v0.7.0 — Multi-tenant ready
+
+The multi-tenant migration (Phases 0-7) is complete. OpenStudy can now be
+self-hosted as single-user OR run as a multi-user platform from the same
+codebase. All credentials are per-user; the operator's bot, password, and
+chat ID never serve as fallbacks for other users.
+
+### Highlights
+
+- **Schema**: every owned table has a `user_id` FK with composite PKs/FKs
+  enforcing per-user data integrity. Cross-user FK violations are
+  structurally impossible.
+- **RLS policies**: shipped on every owned table. Inert under the current
+  BYPASSRLS connection role; flip to a non-bypass role to activate
+  defense-in-depth (see `docs/RLS.md`).
+- **Services**: every public service function takes `user_id` and filters
+  by it. Storage paths resolve under `STUDY_ROOT/<user_id>/...`.
+- **Auth**: home-grown signup + email verification + password reset.
+  Login is `email + password` only — `APP_PASSWORD_HASH` is bootstrap-only.
+- **MCP**: bearer tokens bind to user_id; tools operate on the bearer's
+  data only.
+- **Per-user secrets**: Telegram credentials live in `user_secrets`
+  (Fernet-encrypted), configured via Settings UI. No env-var fallbacks
+  for `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`, `TELEGRAM_WEBHOOK_SECRET`.
+- **Tests**: 318 passing (was 213 pre-migration).
+
+### Migration notes
+
+- After upgrade, run `./deploy.sh` once — it applies all 6 phase migrations
+  in order, runs `scripts/migrate_study_root.sh` (FS layout), and
+  `scripts/seed_operator_password.py` (operator password).
+- Existing operators: log in with `OPERATOR_EMAIL` (default `operator@local`)
+  + the password whose hash was in `APP_PASSWORD_HASH`. Reconfigure your
+  Telegram bot via Settings → Telegram (the env vars no longer work).
+- Self-hosters running solo: nothing changes day-to-day. You ARE the
+  operator user. Multi-user signups are gated by `SIGNUPS_ENABLED=false`
+  by default; flip it on if you want to invite others.
+
+### Deferred
+
+- Stripe billing — separate batch after this lands.
+- n8n Moodle scraper multi-tenancy — operator-only today; per-user Moodle
+  is a follow-up when first hosted user requests it.
+- Connection role flip to non-BYPASSRLS — operational; documented in
+  `docs/RLS.md`; flip when ready.
+
 ## v0.7.0-pre.7 (unreleased) — Multi-tenant Phase 6
 
 ### Per-user secrets

INSTALL.md

@@ -85,8 +85,9 @@ chmod 600 .env .env.docker
 ```
 
 The other variables in `.env` are optional and document themselves —
-Telegram bot credentials, the internal API secret used by webhooks, the
-public URL the app advertises in OAuth flows.
+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).
 
 ---
 
@@ -120,6 +121,23 @@ curl http://127.0.0.1:8000/api/health
 You should also see the running containers (`openstudy`, `openstudy-postgres`,
 `openstudy-frontend`) when you run `./deploy.sh --status`.
 
+### First-time operator login
+
+After running `./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).
+
+`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.
+
 ### Restoring data into a fresh box
 
 If you're moving from another deployment (or restoring a backup), apply
@@ -305,11 +323,13 @@ 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 and update `APP_PASSWORD_HASH` in `.env`. 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, 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.
 
 **MCP returns 401 from a Claude client.**
 The OAuth token cached by the client expired or was revoked. Reconnect:

README.md

@@ -114,6 +114,8 @@ 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.
+
 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.
 
 ## You'll need

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openstudy-api"
-version = "0.6.0"
+version = "0.7.0"
 description = "FastAPI backend for the OpenStudy app"
 readme = "README.md"
 requires-python = ">=3.12"