From 69e93259272136510d8575fe1229caf56cc0350e Mon Sep 17 00:00:00 2001
From: Bobban Rydh <bobban@tooweb.se>
Date: Tue, 29 Sep 2026 20:41:26 +0200
Subject: [PATCH] Document role-based menu access in ROLES.md

Adds a reference table of which sidebar items each role (viewer,
operator, admin) can see, plus a summary of which in-page actions on
otherwise-visible pages are held back to operator/admin.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 ROLES.md | 80 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)
 create mode 100644 ROLES.md

diff --git a/ROLES.md b/ROLES.md
new file mode 100644
index 0000000..c13d062
--- /dev/null
+++ b/ROLES.md
@@ -0,0 +1,80 @@
+# Roles & menu access
+
+Homelab Manager has three roles, ranked lowest to highest: **viewer**,
+**operator**, **admin**. The first person to sign in becomes admin;
+everyone after that starts as viewer until an admin changes their role
+under **Administration → Users**.
+
+A role can do everything the roles below it can, plus what's listed for
+it — operator includes everything viewer has, admin includes everything
+operator has.
+
+## Sidebar menu, by role
+
+✅ = the menu item appears for that role · ❌ = it's hidden entirely (not
+just disabled) — a group that would end up with zero visible items
+disappears too, and a group left with exactly one just shows as that
+page's own top-level link.
+
+| Menu item | Path | Viewer | Operator | Admin |
+|---|---|:---:|:---:|:---:|
+| Dashboard | `/` | ✅ | ✅ | ✅ |
+| **Infrastructure** | | | | |
+| Servers | `/servers` | ✅ | ✅ | ✅ |
+| Proxmox | `/proxmox` | ✅ | ✅ | ✅ |
+| Synology | `/synology` | ✅ | ✅ | ✅ |
+| Proxmox Backup | `/pbs` | ✅ | ✅ | ✅ |
+| Docker | `/docker` | ✅ | ✅ | ✅ |
+| Tailscale | `/tailscale` | ✅ | ✅ | ✅ |
+| **Network** | | | | |
+| DNS | `/dns` | ✅ | ✅ | ✅ |
+| Domains | `/domains` | ✅ | ✅ | ✅ |
+| IP Addresses | `/ipam` | ✅ | ✅ | ✅ |
+| Consistency | `/consistency` | ✅ | ✅ | ✅ |
+| **Automation** | | | | |
+| Semaphore | `/semaphore` | ✅ | ✅ | ✅ |
+| Gitea | `/gitea` | ✅ | ✅ | ✅ |
+| Secrets | `/secrets` | ✅ | ✅ | ✅ |
+| **Operations** | | | | |
+| Maintenance | `/maintenance` | ✅ | ✅ | ✅ |
+| Uptime Kuma | `/uptime-kuma` | ✅ | ✅ | ✅ |
+| Generator | `/generator` | ✅ | ✅ | ✅ |
+| **Administration** | | | | |
+| Integrations | `/integrations` | ✅ | ✅ | ✅ |
+| Users | `/users` | ❌ | ❌ | ✅ |
+| Sessions | `/sessions` | ❌ | ❌ | ✅ |
+| Audit Log | `/audit-log` | ❌ | ✅ | ✅ |
+| Diagnostic Log | `/diag-log` | ❌ | ❌ | ✅ |
+| Settings | `/settings` | ❌ | ❌ | ✅ |
+| Privacy (footer link, not in a group) | `/privacy` | ✅ | ✅ | ✅ |
+
+So in practice: **every page is visible to every role except the five
+under Administration** — Users, Sessions, and Diagnostic Log need admin;
+Audit Log needs operator or admin; Settings needs admin.
+
+## Being able to see a page isn't the same as being able to change things
+
+Almost every page above is visible to viewers, but most of the buttons
+on them aren't — a viewer can look at everything but can't act on
+anything. Operators can use the page's normal working actions (starting
+a container, syncing DNS, adding a secret, opening a maintenance
+window…). Some actions on otherwise-viewer-visible pages are held back
+even further, to admin only:
+
+- **Integrations & DNS providers**: any operator can use an integration
+  once it's configured (start/stop a guest, run a template, sync DNS
+  records, etc.), but adding, editing, testing, or deleting an
+  integration or DNS provider is admin-only.
+- **Servers**: registering a new server, rotating its agent token, and
+  editing/deleting a server are admin-only; tagging a server and
+  linking/unlinking it to a Proxmox guest just need operator.
+- **Tags**: creating, renaming, recoloring, or deleting a tag is
+  admin-only (applying an existing tag to a server needs operator).
+- Everything under **Settings** (notification channels, badge colors,
+  display prefs, log retention, backup/restore) is admin-only, matching
+  the page itself being admin-only.
+
+If you need the exact role for one specific button rather than this
+summary, check the corresponding route in `server/src/routes/` — each
+one that needs more than "signed in" calls `requireRole("operator")` or
+`requireRole("admin")` right where that action is defined.