# Mastermind MVP — Admin Manual

This manual is for the **owner/admin** who runs Mastermind.

## Admin areas
- Users: `/admin/users`
- Audit log: `/admin/audit`
- Email connectors: `/admin/email`
- Email rules: `/admin/email-rules`

---

## 1) User management
Path: `/admin/users`

### Create a user
- Provide:
  - email
  - display name (optional)
  - role (owner/apm)
  - temporary password

Password rules (enforced):
- at least **12 characters**
- includes uppercase + lowercase + number

### Reset a password
- Use **Reset** on the user row.

### Disable / enable a user
- Use **Toggle**.

### Delete a user
- Use **Delete** (removes the user and their identities).

**Important security note:**
- Today, the database default for `users.role` is `owner`. If you enable Google/Microsoft OAuth, new OAuth sign-ins may end up as owners unless the code is adjusted. Treat OAuth enablement as a privileged action.

---

## 2) Audit log
Path: `/admin/audit`

The audit log captures:
- login successes/failures
- admin actions (user creation, reset, disable)
- project creation/updates
- inbox imports, assignments, auto-assignments

Use this to answer: “who did what, when.”

---

## 3) Email connectors (status + enable/disable)
Path: `/admin/email`

Connectors exist for:
- Gmail
- Microsoft

In the MVP, these are **status toggles/placeholders** until OAuth ingestion is implemented end-to-end.

### Configured vs Authorized
- **Configured** means OAuth client ID/secret exists in environment variables.
- **Authorized** will remain false until an OAuth flow stores tokens and the worker sync is implemented.

---

## 4) Email rules (auto-assign)
Path: `/admin/email-rules`

Rules are evaluated in priority order:
- lower `priority` number runs first

Match types:
- `from_domain` — match sender domain
- `from_contains` — match substring in From
- `subject_contains` — match substring in Subject
- `body_contains` — match substring in Body
- `thread_key` — exact match thread key

### Recommended rule patterns
- Create one `from_domain` rule per key vendor/GC domain.
- Add a `subject_contains` rule for job numbers.
- Keep priority tight:
  - job-number rules (priority 40)
  - domain rules (priority 50)
  - general keywords last (priority 100+)

---

## 5) Storage + backups
Mastermind stores data under `./data/`:
- `data/postgres/` — Postgres database
- `data/uploads/` — raw `.eml` uploads
- `data/attachments/` — extracted email attachments

### Backup (manual)
```bash
cd /root/clawd/mastermind-mvp
docker compose down

tar -czf mastermind_backup_$(date +%Y%m%d_%H%M%S).tar.gz data .env docker-compose.yml

docker compose up -d --build
```

### Restore
```bash
cd /root/clawd/mastermind-mvp
docker compose down
rm -rf data

tar -xzf mastermind_backup_YYYYMMDD_HHMMSS.tar.gz

docker compose up -d --build
```

---

## 6) Operational troubleshooting
### Web is up but login fails
- Check if the DB already contains identities; bootstrap only triggers when **no local identities exist**.
- Reset the password via `/admin/users`.

### Disk growth / uploads
- Inbox uploads and attachments will grow over time.
- If disk is tight, archive older projects or introduce retention.

### Reverse proxy / cookies
If serving behind HTTPS reverse proxy:
- set `BASE_URL=https://...`
- set `TRUST_PROXY=true`
- set `COOKIE_SECURE=true`

Otherwise you’ll see session/cookie weirdness.

---

## 7) Security checklist (minimum)
- Change bootstrap owner password immediately after first login.
- Use a long random `SESSION_SECRET`.
- Keep the app private to LAN/Tailscale until hardened.
- Consider enabling CSRF checks for production.
- Avoid enabling OAuth until role-default behavior is fixed (or restrict by allowlist).