docs: add Phase 4 — RBAC with 3-tier roles and invitation flow

Three roles: platform admin (full SaaS), customer admin (tenant-scoped),
customer operator (read-only). Email invitation flow for tenant user
onboarding. 6 new requirements (RBAC-01 through RBAC-06).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.planning/REQUIREMENTS.md

@@ -47,6 +47,15 @@ Requirements for beta-ready release. Each maps to roadmap phases.
 - [x] **PRTA-05**: Operator can manage subscription plans and billing via Stripe integration
 - [x] **PRTA-06**: Portal displays agent cost tracking and usage metrics per tenant
 
+### RBAC & User Management
+
+- [ ] **RBAC-01**: Platform admin role with full access to all tenants, agents, users, and platform settings
+- [ ] **RBAC-02**: Customer admin role scoped to a single tenant with full control over agents, channels, billing, API keys, and user management
+- [ ] **RBAC-03**: Customer operator role scoped to a single tenant with read-only access to agents, conversations, and usage dashboards
+- [ ] **RBAC-04**: Customer admin can invite users (admin or operator) by email — invitee receives activation link to set password and enable access
+- [ ] **RBAC-05**: Portal navigation, pages, and UI elements adapt based on user role (platform admin sees tenant picker, customer admin sees their tenant, operator sees read-only views)
+- [ ] **RBAC-06**: API endpoints enforce role-based authorization — unauthorized actions return 403 Forbidden, not just hidden UI
+
 ## v2 Requirements
 
 Deferred to future release. Tracked but not in current roadmap.
@@ -120,9 +129,16 @@ Which phases cover which requirements. Updated during roadmap creation.
 | PRTA-04 | Phase 3 | Complete |
 | PRTA-05 | Phase 3 | Complete |
 | PRTA-06 | Phase 3 | Complete |
+| RBAC-01 | Phase 4 | Pending |
+| RBAC-02 | Phase 4 | Pending |
+| RBAC-03 | Phase 4 | Pending |
+| RBAC-04 | Phase 4 | Pending |
+| RBAC-05 | Phase 4 | Pending |
+| RBAC-06 | Phase 4 | Pending |
 
 **Coverage:**
-- v1 requirements: 25 total
+- v1 requirements: 25 total (all complete)
+- RBAC requirements: 6 total (Phase 4)
 - Mapped to phases: 25
 - Unmapped: 0
 

.planning/ROADMAP.md

@@ -92,6 +92,21 @@ Phases execute in numeric order: 1 -> 2 -> 3
 
 **LLM-03 conflict resolved:** BYO API keys confirmed in v1 scope per user decision during Phase 3 context gathering. Implemented via Fernet encryption in Phase 3.
 
+### Phase 4: RBAC
+**Goal**: Three-tier role-based access control — platform admins manage the SaaS, customer admins manage their tenant, customer operators get read-only access — with email invitation flow for onboarding tenant users
+**Depends on**: Phase 3
+**Requirements**: RBAC-01, RBAC-02, RBAC-03, RBAC-04, RBAC-05, RBAC-06
+**Success Criteria** (what must be TRUE):
+  1. A platform admin can see all tenants, all agents, and all users across the entire platform
+  2. A customer admin can only see their own tenant's agents, users, billing, and settings — no cross-tenant visibility
+  3. A customer operator can view agents and usage dashboards but cannot create, edit, or delete anything
+  4. A customer admin can invite a new user (admin or operator) by email — the invitee receives a link, clicks to activate, and sets their password
+  5. Portal navigation and API endpoints enforce role-based access — unauthorized actions return 403, not just hidden UI elements
+**Plans**: 0 plans
+
+Plans:
+- [ ] TBD (run /gsd:plan-phase 4 to break down)
+
 ---
 *Roadmap created: 2026-03-23*
 *Coverage: 25/25 v1 requirements mapped*

.planning/STATE.md

@@ -137,6 +137,10 @@ Recent decisions affecting current work:
 - [Phase 03-operator-experience]: BudgetAlertBadge renders neutral 'No limit set' for null budget_limit_usd — prevents false alarms
 - [Phase 03-operator-experience]: All Phase 3 portal routers (portal, billing, channels, llm_keys, usage, webhook) mounted directly on gateway FastAPI app
 
+### Roadmap Evolution
+
+- Phase 4 added: RBAC — 3-tier role-based access control (platform admin, customer admin, customer operator) with invitation flow
+
 ### Pending Todos
 
 None yet.