Add user/admin/install manuals

2026-04-21 10:29:56 -04:00
parent df7bc9ff71
commit 55e4f18509
4 changed files with 422 additions and 1 deletions
@@ -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).
@@ -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.
@@ -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
@@ -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://<your-host>/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/<id>`
 - 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/<emailId>`
 - 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/<id>`)
 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/<id>`
  - `/drafts/rfi/<id>`
 - Edit the title/body
 - Click **Save**
 ### Export a draft
 - Use the export links:
  - PCO: `/drafts/pco/<id>/export.md`
  - RFI: `/drafts/rfi/<id>/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).