deploy ProspectOS workspace final

README.md

@@ -225,3 +225,58 @@ This project is packaged for personal research. Public availability does not
 override a website's terms, robots controls, or applicable privacy law; keep
 searches small, use the worker only on data you are permitted to collect, and
 do not turn the review screen into unattended outreach.
+
+## Workspace accounts and operational controls
+
+Authentication is enabled by default. On a fresh database, open the app and
+complete the first-run owner setup. For unattended deployments, set
+`OWNER_EMAIL`, `OWNER_PASSWORD` (8+ characters), `OWNER_NAME`, and
+`WORKSPACE_NAME` in `.env`; the owner is created automatically only when no
+user exists. Sessions are server-side, cookies are HTTP-only, and mutating
+browser requests require a per-session CSRF token. Failed sign-ins are
+temporarily rate-limited after five consecutive failures.
+
+Roles are deliberately small:
+
+| Role | Capabilities |
+|---|---|
+| Viewer | Read catalogue and runs |
+| Reviewer | Viewer + review status, notes, and follow-up tasks |
+| Researcher | Reviewer + discovery runs, retries, cancellation, and assignments |
+| Admin | Researcher + users, workspace name, backups, and audit trail |
+| Owner | Admin, and cannot be removed as the last active owner |
+
+The **Users** page manages workspace members. A prospect drawer contains its
+assignee, notes, tasks, review status, and score/AI assessment history. Every
+workspace-scoped API query checks the signed-in organisation before returning
+data.
+
+## Backups and recovery
+
+The app keeps the existing SQLite catalogue and performs additive schema
+migrations; it does not delete or rewrite existing prospects. Use **Users →
+Verified backups → Create backup** or run this inside the app container:
+
+```bash
+python scripts/backup_sqlite.py
+```
+
+Backups use SQLite's online backup API, run `PRAGMA integrity_check`, and keep
+the newest `BACKUP_RETENTION` files in `BACKUP_DIR` (default `/data/backups`).
+The background scheduler creates one automatically every `BACKUP_INTERVAL_HOURS`
+(default 24; set it to `0` to disable automatic creation).
+Include the `prospect_data` volume in server backups. A scheduled or interrupted
+run is marked `recovery_required` after 30 minutes without a heartbeat. The
+Runs page can show its persisted event timeline and retry a failed/recoverable
+run as a new attempt, preserving the original run. Active jobs can be cancelled
+and the worker records the cancellation in the event stream.
+
+The audit trail records sign-ins, user and workspace changes, assignments,
+review decisions, notes, tasks, AI assessments, message generation, run
+retries/cancellations, settings, suppressions, and backup actions. Operational
+logs remain available under **Logs**; credentials and authorization values are
+redacted and retention is bounded by `LOG_RETENTION`.
+
+This release intentionally keeps SQLite for safety. PostgreSQL migration can
+be added later as a separate, tested data-migration project once the current
+workspace and backup workflow is stable.