# Feature: User Roles

## Overview
Three custom WordPress user roles control access to all scheduling features: a studio admin who runs the business, instructors who teach, and students who book.

## Roles

### Studio Admin (`us_studio_admin`)
Runs the studio. Logs in via standard wp-admin. Can:
- Create instructor accounts and set/revoke each instructor's capabilities
- Manage offerings, intake questions, and policies
- Configure Stripe credentials and per-student billing overrides (card / e-transfer / comp)
- View the all-instructor payments report and export it

**Capabilities:** `read`, `manage_instructors`, `manage_offerings`, `manage_questions`, `manage_policies`, `manage_billing`, `view_all_payments`, `export_payments`

### Instructor (`us_instructor`)
Created by the studio admin. Logs in via standard wp-admin. Can:
- Manage their own availability slots (add/delete), including weekly-recurring windows
- Manage their own offerings and intake questions
- View their upcoming confirmed/pending lessons and group enrolments
- View and export their own payments

**Capabilities:** `read`, `manage_availability`, `manage_offerings`, `manage_questions`, `view_own_lessons`, `view_own_payments`, `export_payments`

### Student (`us_student`)
Logs in via the front-end `[us_student_login]` shortcode. Can:
- Browse available lesson slots and offerings from all instructors
- Book a private lesson (single or weekly) and enrol in group classes

**Capabilities:** `read`, `book_lesson`, `view_own_lessons`

## Capability Matrix

| Capability            | Studio Admin | Instructor | Student | Used by                         |
|-----------------------|:------------:|:----------:|:-------:|---------------------------------|
| `manage_instructors`  | ✓            |            |         | Instructor management           |
| `manage_availability` |              | ✓          |         | Availability                    |
| `manage_offerings`    | ✓            | ✓ (own)    |         | Offerings                       |
| `manage_questions`    | ✓            | ✓ (own)    |         | Registration questions          |
| `manage_policies`     | ✓            |            |         | Policies                        |
| `manage_billing`      | ✓            |            |         | Payments (Stripe + overrides)   |
| `book_lesson`         |              |            | ✓       | Lesson booking / enrolment      |
| `view_own_lessons`    |              | ✓          | ✓       | Lesson + group views            |
| `view_own_payments`   |              | ✓          |         | Payment reporting               |
| `view_all_payments`   | ✓            |            |         | Payment reporting               |
| `export_payments`     | ✓            | ✓ (own)    |         | Payment reporting export        |

## Instructor Management
The studio admin gets an **Instructors** admin page (gated by `manage_instructors`)
to add an instructor — creating the WP user with the `us_instructor` role — and to
toggle that instructor's per-capability access (e.g. whether they may manage their
own offerings/questions or export payments). The studio admin cannot grant a
capability it does not itself hold.

## Implementation
- Class: `Unsupervised\Schedular\Auth\RoleManager`
- Instructor management controller: `Unsupervised\Schedular\Auth\InstructorController`
- Roles are created on `plugins_loaded → init` and on plugin activation via `Installer`.
- Permissions are checked with `current_user_can()` against the capability string, not the role name.

## Tests
- `tests/Unit/Auth/RoleManagerTest.php`
- `tests/Unit/Auth/InstructorControllerTest.php`