# Feature: Account Registration

## Overview
People register for a student account through a front-end page, accepting any
signup-scoped policies at that time. Registration is **invite-only** by default: a
studio admin sends an invite, and the invitee completes signup via a tokenised
link. A settings seam (`us_registration_mode`) allows switching to open
self-registration with approval later.

## Registration Modes
Stored in the `us_registration_mode` option (default `invite`):
- `invite` — only a valid, pending invite token grants access to the registration form. *(implemented)*
- `self_approval` — anyone may register; the account is created in a pending state until a studio admin approves it. *(reserved for a later iteration)*

## Data Model — `{prefix}us_invites`

| Column             | Type             | Notes                                                  |
|--------------------|------------------|--------------------------------------------------------|
| `id`               | BIGINT UNSIGNED  | Primary key                                            |
| `email`            | VARCHAR(191)     | Invited email address                                  |
| `token`            | VARCHAR(64)      | SHA-256 hash of the token embedded in the registration link (raw token is never stored) |
| `role`             | VARCHAR(32)      | Role granted on acceptance (default `us_student`)       |
| `status`           | VARCHAR(20)      | `pending` / `accepted` / `revoked`                     |
| `invited_by`       | BIGINT UNSIGNED  | WordPress user ID of the studio admin who invited       |
| `accepted_user_id` | BIGINT UNSIGNED  | The created user's ID once accepted; NULL while pending  |
| `created_at`       | DATETIME         | Insertion time                                         |
| `accepted_at`      | DATETIME         | When accepted; NULL while pending                      |

## Policy Acceptance Scope
Policies declare **when** they must be accepted via `us_policies.acceptance_scope`:
`signup`, `booking`, or `both` (see `policies.md`). The registration form requires
acceptance of every published policy scoped `signup` or `both`. Acceptances are
recorded in `us_policy_acceptances` with `registration_type = account` and
`registration_id = <new user ID>`.

## Flow (invite mode)
1. Studio admin opens **Invites** (`manage_students`) and invites an email; an invite row is created storing the token's SHA-256 hash, and the registration link (with the raw token) is shown **once** in a notice. To re-send a lost link, revoke and re-invite.
2. The invitee opens `[us_student_register]` with the token (`?us_invite=<token>`); the lookup hashes the submitted token and matches it against the stored hash.
3. The form pre-fills the email and collects a display name and password, and renders the signup-scoped published policies, each with a required acceptance checkbox.
4. On submit, the token is re-validated (hashed lookup); a `us_student` user is created, the policy acceptances are recorded (`account` type), the invite is marked `accepted`, and the user is logged in.

## Admin Interface
**Invites** in wp-admin (`manage_students`, studio admin only):
- Select the **registration page** (the page hosting `[us_student_register]`), stored in the `us_registration_page_id` option; invitation links point there (falling back to the home page if unset)
- Invite an email (creates a pending invite; the link is displayed once, at creation only)
- List pending invites (email + invited date); revoke an invite

## Frontend Shortcode
- `[us_student_register]` — the registration page. Shows the form for a valid pending invite; otherwise shows an "by invitation only" message (in `invite` mode).

## Token Redirect
A `template_redirect` handler (`RegistrationPage::maybeRedirectToRegistrationPage()`)
sends any front-end request carrying a `us_invite` token to the configured
registration page (preserving the token), unless it is already on that page. This
covers invitation links generated/shared before a registration page was selected.
No-op when no registration page is set.

## Capabilities
- `manage_students` — manage invites (studio admin; administrators inherit it via the `user_has_cap` filter). Added to `RoleManager::STUDIO_ADMIN_CAPS`.

## Implementation
- Models: `Unsupervised\Schedular\Auth\Invite`
- Repository: `Unsupervised\Schedular\Auth\InviteRepository`
- Admin controller: `Unsupervised\Schedular\Auth\RegistrationController`
- Frontend: `Unsupervised\Schedular\Auth\RegistrationPage`
- Reuses `Policy\PolicyRepository`, `Policy\PolicyVersionRepository`, `Policy\AcceptanceRepository`
- Schema: `us_invites`; `us_policies.acceptance_scope`

## Tests
- `tests/Unit/Auth/InviteTest.php`
- `tests/Unit/Auth/InviteRepositoryTest.php`