From 55e4f1850952242e2028b0fd0fb3823c0eee429e Mon Sep 17 00:00:00 2001 From: pnannery Date: Tue, 21 Apr 2026 10:29:56 -0400 Subject: [PATCH] Add user/admin/install manuals --- ADMIN_MANUAL.md | 145 ++++++++++++++++++++++++++++++++++++++++++++++ INSTALL_MANUAL.md | 128 ++++++++++++++++++++++++++++++++++++++++ README.md | 7 ++- USER_MANUAL.md | 143 +++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 422 insertions(+), 1 deletion(-) create mode 100644 ADMIN_MANUAL.md create mode 100644 INSTALL_MANUAL.md create mode 100644 USER_MANUAL.md diff --git a/ADMIN_MANUAL.md b/ADMIN_MANUAL.md new file mode 100644 index 0000000..8e51e26 --- /dev/null +++ b/ADMIN_MANUAL.md @@ -0,0 +1,145 @@ +# 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). \ No newline at end of file diff --git a/INSTALL_MANUAL.md b/INSTALL_MANUAL.md new file mode 100644 index 0000000..b7dffdb --- /dev/null +++ b/INSTALL_MANUAL.md @@ -0,0 +1,128 @@ +# Mastermind MVP — Install Manual + +This is the **operator install guide** for a private deployment (LAN/Tailscale or behind your reverse proxy). + +## 0) Prerequisites +- Docker Engine + Docker Compose v2 +- A hostname you can reach (Tailscale IP or reverse-proxy hostname) + +Repository layout: +- `docker-compose.yml` +- `web/` (Express app) +- `worker/` (background worker) +- `data/` (persistent volume directory) + +--- + +## 1) Configure environment +```bash +cd /root/clawd/mastermind-mvp +cp .env.example .env +``` + +Edit `.env`: +- `DB_PASSWORD` — Postgres password (used in compose) +- `SESSION_SECRET` — **required in production** (>=24 chars). Generate: + ```bash + openssl rand -base64 48 + ``` +- `BASE_URL` — the public base URL users will hit + - e.g. `http://100.x.y.z:3005` for Tailscale + - or `https://mm.yourdomain.com` behind a reverse proxy +- `TRUST_PROXY=true` if behind a reverse proxy +- `COOKIE_SECURE=true` if users access via HTTPS + +Bootstrap owner (first run only): +- `BOOTSTRAP_OWNER_EMAIL` +- `BOOTSTRAP_OWNER_PASSWORD` + +Important: +- Bootstrap is only created if **no local identities exist** in the DB. + +--- + +## 2) Start the stack +```bash +docker compose up -d --build +``` + +Services: +- `db` (Postgres) +- `web` (Express on port 3005) +- `worker` (stub) + +--- + +## 3) Verify health +From the host: +```bash +curl -fsS http://localhost:3005/health +``` +Expected: +```json +{"ok":true} +``` + +Then open: +- `BASE_URL/login` + +--- + +## 4) First login +Use the bootstrap credentials you set. +Then immediately change the password: +- `/account/password` + +--- + +## 5) Reverse proxy notes (optional) +If you run behind Traefik/Nginx/Caddy: +- proxy to `http://127.0.0.1:3005` +- set `BASE_URL=https://mm.yourdomain.com` +- set `TRUST_PROXY=true` +- set `COOKIE_SECURE=true` + +--- + +## 6) Update +```bash +cd /root/clawd/mastermind-mvp +docker compose down +git pull +docker compose up -d --build +``` + +--- + +## 7) Backup +Data lives under `./data/`. + +Recommended quick snapshot: +```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 +``` + +--- + +## 8) Common troubleshooting +### Login fails after changing .env bootstrap +Bootstrap only applies on empty DB. If you already ran it once: +- reset password via `/admin/users` +- or wipe `data/postgres` if you truly want a fresh instance + +### Cookies / sessions don’t stick +Usually a BASE_URL / COOKIE_SECURE / TRUST_PROXY mismatch. +- HTTP access → `COOKIE_SECURE=false` +- HTTPS access → `COOKIE_SECURE=true` and correct `BASE_URL=https://...` + +### Port conflicts +Compose binds: +- web: `3005:3005` +- db: `5433:5432` + +Change host ports if needed. diff --git a/README.md b/README.md index ad89d99..fd87000 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,12 @@ A portable, self-hosted dashboard that supports an Assistant PM workflow (starti - `/admin/email-rules` ## Quick start -See **INSTALL.md**. +See **INSTALL.md** (quick) or **INSTALL_MANUAL.md** (detailed). + +## Manuals +- **USER_MANUAL.md** — day-to-day usage +- **ADMIN_MANUAL.md** — admin/owner operations +- **INSTALL_MANUAL.md** — install + deploy + backup Common local commands: - `npm test` — run the repo test suite diff --git a/USER_MANUAL.md b/USER_MANUAL.md new file mode 100644 index 0000000..6a9c6f9 --- /dev/null +++ b/USER_MANUAL.md @@ -0,0 +1,143 @@ +# Mastermind MVP — User Manual + +This manual is for day‑to‑day users of the Mastermind MVP dashboard. + +## What Mastermind is +Mastermind is a self‑hosted Assistant Project Manager (APM) dashboard that helps you: +- create and manage projects +- import emails into an **Inbox** +- automatically sort/assign emails using rules +- create **draft‑first** documents (PCO and RFI) from emails +- keep an **audit trail** of key actions + +It is designed to be private (LAN/Tailscale) and safe by default (no auto‑sending). + +--- + +## Login / Logout +### Login +1. Open the login page: + - `https:///login` +2. Sign in with your **local email + password**. + +If Google/Microsoft OAuth is enabled by the admin, you may also see those buttons. + +### Logout +- Click **Logout** in the UI (or go to `/logout`). + +--- + +## Home +After logging in, you land on **Home** (`/`). From here you can reach: +- Projects +- Inbox +- Drafts +- Docs + +--- + +## Projects +### View projects +- Go to `/projects` +- You’ll see projects you’re a member of. + +### Create a project +1. Go to `/projects` +2. Fill the **Create Project** form (name is required) +3. Submit + +Fields you may use: +- **Name** (required) +- **Job #** (optional) +- **Role mode** (defaults to EC) +- **GC name** (optional) +- **City/State** (optional) +- **Keywords** (important for auto-sorting) + +### Edit a project +- Open the project: `/projects/` +- Update fields and save + +### Project inbox +- From the project page, use **Project Inbox** to view emails already assigned to that project. + +--- + +## Inbox (manual import) +Mastermind currently supports manual email import via `.eml` upload. + +### Upload email(s) +1. Go to `/inbox` +2. Use **Upload .eml** +3. Select one or more `.eml` files +4. Submit + +Notes: +- The system stores the raw `.eml` and any attachments. +- Uploaded emails initially appear as **Unsorted**. + +### Assign an email to a project +1. Open an email from `/inbox` +2. Choose a project in the **Assign** dropdown +3. Submit + +### View email details + attachments +- Open `/inbox/` +- Attachments can be downloaded from the email page. + +--- + +## Drafts (PCO / RFI) +Drafts are **generated from an email** and then edited by you. + +### Create a PCO draft from an email +1. Open an email (`/inbox/`) +2. Click **Create PCO Draft** +3. You’ll be taken to the draft editor + +### Create an RFI draft from an email +Same flow, using **Create RFI Draft**. + +### Edit + save a draft +- Draft editor pages: + - `/drafts/pco/` + - `/drafts/rfi/` +- Edit the title/body +- Click **Save** + +### Export a draft +- Use the export links: + - PCO: `/drafts/pco//export.md` + - RFI: `/drafts/rfi//export.md` + +--- + +## Tips for better sorting +- Put meaningful **keywords** in each Project. +- Ask an admin to create rules (sender domain, subject contains job #, etc.). +- Start simple: one rule per project is often enough. + +--- + +## Troubleshooting +### “Login failed” +- Confirm email and password. +- If you recently changed password, log out and back in. +- Ask an admin to reset your password. + +### Upload fails +- Confirm files are `.eml`. +- Try fewer files at once. +- If it consistently fails, ask admin to check disk space. + +### I can’t see a project +- You must be added as a project member (admin/owner action). + +--- + +## Glossary +- **Inbox**: Imported emails awaiting sorting/assignment. +- **PCO**: Potential Change Order draft. +- **RFI**: Request For Information draft. +- **Rule**: An automatic matching condition that assigns an email to a project. +- **Audit log**: A record of important actions (imports, assignments, admin changes). \ No newline at end of file