Refactor Study Desk application structure

README.md

@@ -1,4 +1,77 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+Study Desk is a self-hosted, single-user study application.
+
+## Local development
+
+```powershell
+npm.cmd ci
+npx.cmd prisma generate
+npm.cmd run dev
+```
+
+The automated test harness always creates a uniquely named database under
+`.test-databases/`, applies committed migrations, and removes the database after
+the run. It refuses `dev.db`, `/app/data/study.db`, existing databases, and paths
+that are not explicitly test-named.
+
+## Production container
+
+Set a unique session secret of at least 32 characters. Production startup fails
+before migrations or the HTTP server when the secret is missing, short, or the
+published development fallback.
+
+```powershell
+$env:SESSION_SECRET = '<at-least-32-random-characters>'
+docker compose -f docker-compose.yml up --build
+```
+
+The host listens on `http://localhost:3000`; the container listens on port 3726.
+Development Compose is intentionally explicit and is never auto-merged:
+
+```powershell
+docker compose -f docker-compose.dev.yml up --build
+```
+
+For first-time production setup, either provide an Argon2 encoded
+`ADMIN_PASSWORD_HASH`, or temporarily set `ALLOW_INITIAL_SETUP=true` for the
+one-time setup request. Remove the flag after setup. Production HTTP password
+reset initiation is unavailable; run this on the server instead:
+
+```powershell
+npm.cmd run auth:reset
+```
+
+If TLS terminates at a trusted reverse proxy, forward requests only from that
+proxy and set `SECURE_COOKIES=true`. Leave it false for intentional plain HTTP;
+Secure cookies cannot be used over plain HTTP.
+
+## Database backup, migration adoption, and restore
+
+Never run migration tests against the only copy of a study database. Create a
+lock-safe SQLite backup through the backup API and verify it before deployment:
+
+```powershell
+$env:DATABASE_URL = 'file:./data/study.db'
+npm.cmd run db:backup -- --output ./backups/study-before-upgrade.db
+npm.cmd run db:preflight
+npx.cmd prisma migrate deploy
+```
+
+The material-group preflight reports one of four states:
+
+- `APPLY`: migration history is complete and the group schema is absent; run
+  `prisma migrate deploy` normally.
+- `ADOPT`: prior migrations are tracked and the database exactly matches the
+  intended group schema. After reviewing the verified backup, explicitly run
+  `npm run db:preflight -- --resolve --backup <backup-path>`.
+- `CURRENT`: migration and schema already agree.
+- `CONFLICT`: partial or unknown state. Stop and recover manually; do not use
+  `db push`, reset, edit applied migrations, or mark anything applied.
+
+Restore drill: stop Study Desk, keep the damaged database as evidence, restore
+the verified backup to a new path, run SQLite `integrity_check` plus
+`npm run db:preflight`, start the same prior application image against the
+restored path, and compare class/deck/quiz counts plus representative content.
+Only swap the production path after those checks pass.
 
 ## Getting Started