Mastermind/ADMIN_MANUAL.md

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)

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

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).