Add account registration with signup policy acceptance

Implements #16: invite-only student self-registration through a front-end
page, accepting signup-scoped policies at account creation.

Policy domain:
- us_policies.acceptance_scope (signup/booking/both); Policy::appliesTo();
  PolicyRepository::findForScope(); scope threaded through PolicyService,
  the REST create, the admin controller, and the Policies form.
- PolicyAcceptance::REG_ACCOUNT (registration_id = the new user's ID).

Auth:
- Invite value object + InviteRepository; us_invites table.
- RegistrationController + Invites admin page (manage_students): invite an
  email, share the registration link, revoke.
- RegistrationPage ([us_student_register] shortcode): validates the invite
  token, collects name/password, renders signup-scoped published policies
  with required acceptance, creates the us_student user, records account-type
  acceptances, marks the invite accepted, and logs the user in.
- RoleManager: manage_students cap added to STUDIO_ADMIN_CAPS.

Invite-only is implemented; the us_registration_mode self_approval path is a
documented future seam.

Docs: docs/features/account-registration.md; policies.md updated.
Tests: tests/Unit/Auth/ (Invite, InviteRepository) plus Policy scope
updates. composer test (104), cs, and PHPStan level 6 all pass.

Refs #16

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

tests/Unit/Auth/InviteRepositoryTest.php

@@ -0,0 +1,138 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Tests\Unit\Auth;
+
+use Brain\Monkey\Functions;
+use Mockery;
+use Unsupervised\Schedular\Auth\Invite;
+use Unsupervised\Schedular\Auth\InviteRepository;
+use Unsupervised\Schedular\Tests\Unit\TestCase;
+
+class InviteRepositoryTest extends TestCase
+{
+    private \wpdb $db;
+    private InviteRepository $repo;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $this->db         = Mockery::mock(\wpdb::class);
+        $this->db->prefix = 'wp_';
+        $this->repo       = new InviteRepository($this->db);
+    }
+
+    public function testInsertReturnsId(): void
+    {
+        Functions\expect('current_time')->with('mysql')->andReturn('2026-06-02 09:00:00');
+
+        $this->db->shouldReceive('insert')
+            ->once()
+            ->with(
+                'wp_us_invites',
+                Mockery::on(static function (array $d): bool {
+                    return $d['email'] === 'a@b.test'
+                        && $d['token'] === 'tok123'
+                        && $d['status'] === Invite::STATUS_PENDING
+                        && $d['invited_by'] === 2;
+                }),
+                ['%s', '%s', '%s', '%s', '%d', '%d', '%s', '%s']
+            );
+        $this->db->insert_id = 5;
+
+        self::assertSame(5, $this->repo->insert(new Invite('a@b.test', 'tok123', invitedBy: 2)));
+    }
+
+    public function testFindByTokenReturnsInvite(): void
+    {
+        $this->db->shouldReceive('prepare')
+            ->once()
+            ->with(Mockery::pattern('/token = %s/'), 'tok123')
+            ->andReturn('SELECT ...');
+
+        $this->db->shouldReceive('get_row')->andReturn($this->row());
+
+        $invite = $this->repo->findByToken('tok123');
+
+        self::assertInstanceOf(Invite::class, $invite);
+        self::assertSame('a@b.test', $invite->email);
+    }
+
+    public function testFindByTokenReturnsNullWhenMissing(): void
+    {
+        $this->db->shouldReceive('prepare')->andReturn('SELECT ...');
+        $this->db->shouldReceive('get_row')->andReturn(null);
+
+        self::assertNull($this->repo->findByToken('nope'));
+    }
+
+    public function testFindPendingByEmailFiltersStatus(): void
+    {
+        $this->db->shouldReceive('prepare')
+            ->once()
+            ->with(Mockery::pattern('/email = %s AND status = %s/'), 'a@b.test', Invite::STATUS_PENDING)
+            ->andReturn('SELECT ...');
+
+        $this->db->shouldReceive('get_row')->andReturn($this->row());
+
+        self::assertInstanceOf(Invite::class, $this->repo->findPendingByEmail('a@b.test'));
+    }
+
+    public function testFindPendingMapsRows(): void
+    {
+        $this->db->shouldReceive('prepare')
+            ->once()
+            ->with(Mockery::pattern('/status = %s/'), Invite::STATUS_PENDING)
+            ->andReturn('SELECT ...');
+
+        $this->db->shouldReceive('get_results')->andReturn([$this->row()]);
+
+        $pending = $this->repo->findPending();
+
+        self::assertCount(1, $pending);
+        self::assertInstanceOf(Invite::class, $pending[0]);
+    }
+
+    public function testMarkAcceptedUpdatesRow(): void
+    {
+        Functions\expect('current_time')->with('mysql')->andReturn('2026-06-02 10:00:00');
+
+        $this->db->shouldReceive('update')
+            ->once()
+            ->with(
+                'wp_us_invites',
+                Mockery::on(static fn (array $d): bool => $d['status'] === Invite::STATUS_ACCEPTED && $d['accepted_user_id'] === 9),
+                ['id' => 5],
+                ['%s', '%d', '%s'],
+                ['%d']
+            )
+            ->andReturn(1);
+
+        self::assertTrue($this->repo->markAccepted(5, 9));
+    }
+
+    public function testRevokeUpdatesStatus(): void
+    {
+        $this->db->shouldReceive('update')
+            ->once()
+            ->with('wp_us_invites', ['status' => Invite::STATUS_REVOKED], ['id' => 5], ['%s'], ['%d'])
+            ->andReturn(1);
+
+        self::assertTrue($this->repo->revoke(5));
+    }
+
+    private function row(): object
+    {
+        return (object) [
+            'id'               => '5',
+            'email'            => 'a@b.test',
+            'token'            => 'tok123',
+            'role'             => 'us_student',
+            'status'           => Invite::STATUS_PENDING,
+            'invited_by'       => '2',
+            'accepted_user_id' => null,
+            'accepted_at'      => null,
+        ];
+    }
+}

tests/Unit/Auth/InviteTest.php

@@ -0,0 +1,71 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Tests\Unit\Auth;
+
+use Unsupervised\Schedular\Auth\Invite;
+use Unsupervised\Schedular\Auth\RoleManager;
+use Unsupervised\Schedular\Tests\Unit\TestCase;
+
+class InviteTest extends TestCase
+{
+    public function testDefaults(): void
+    {
+        $invite = new Invite('a@b.test', 'tok123');
+
+        self::assertSame('a@b.test', $invite->email);
+        self::assertSame('tok123', $invite->token);
+        self::assertSame(RoleManager::STUDENT, $invite->role);
+        self::assertSame(Invite::STATUS_PENDING, $invite->status);
+        self::assertTrue($invite->isPending());
+        self::assertNull($invite->invitedBy);
+        self::assertNull($invite->acceptedUserId);
+        self::assertNull($invite->id);
+    }
+
+    public function testFromRowMapsCorrectly(): void
+    {
+        $invite = Invite::fromRow((object) [
+            'id'               => '5',
+            'email'            => 'a@b.test',
+            'token'            => 'tok123',
+            'role'             => RoleManager::STUDENT,
+            'status'           => Invite::STATUS_ACCEPTED,
+            'invited_by'       => '2',
+            'accepted_user_id' => '9',
+            'accepted_at'      => '2026-06-02 09:00:00',
+        ]);
+
+        self::assertSame(5, $invite->id);
+        self::assertSame(2, $invite->invitedBy);
+        self::assertSame(9, $invite->acceptedUserId);
+        self::assertFalse($invite->isPending());
+    }
+
+    public function testFromRowHandlesNullableIds(): void
+    {
+        $invite = Invite::fromRow((object) [
+            'id'               => '5',
+            'email'            => 'a@b.test',
+            'token'            => 'tok123',
+            'role'             => RoleManager::STUDENT,
+            'status'           => Invite::STATUS_PENDING,
+            'invited_by'       => null,
+            'accepted_user_id' => null,
+            'accepted_at'      => null,
+        ]);
+
+        self::assertNull($invite->invitedBy);
+        self::assertNull($invite->acceptedUserId);
+        self::assertTrue($invite->isPending());
+    }
+
+    public function testToArrayContainsExpectedKeys(): void
+    {
+        $arr = (new Invite('a@b.test', 'tok', id: 1))->toArray();
+
+        foreach (['id', 'email', 'token', 'role', 'status', 'invited_by', 'accepted_user_id', 'accepted_at'] as $key) {
+            self::assertArrayHasKey($key, $arr);
+        }
+    }
+}

tests/Unit/Policy/PolicyRepositoryTest.php

@@ -31,14 +31,35 @@ class PolicyRepositoryTest extends TestCase
             ->once()
             ->with(
                 'wp_us_policies',
-                Mockery::on(static fn (array $d): bool => $d['title'] === 'Cancellation' && $d['slug'] === 'cancellation' && $d['current_version_id'] === null),
-                ['%s', '%s', '%d', '%s']
+                Mockery::on(static fn (array $d): bool => $d['title'] === 'Cancellation' && $d['slug'] === 'cancellation' && $d['current_version_id'] === null && $d['acceptance_scope'] === Policy::SCOPE_BOOKING),
+                ['%s', '%s', '%d', '%s', '%s']
             );
         $this->db->insert_id = 7;
 
         self::assertSame(7, $this->repo->insert(new Policy('Cancellation', 'cancellation')));
     }
 
+    public function testFindForScopeMatchesScopeOrBoth(): void
+    {
+        $this->db->shouldReceive('prepare')
+            ->once()
+            ->with(
+                Mockery::pattern('/acceptance_scope = %s OR acceptance_scope = %s/'),
+                Policy::SCOPE_SIGNUP,
+                Policy::SCOPE_BOTH
+            )
+            ->andReturn('SELECT ...');
+
+        $this->db->shouldReceive('get_results')->andReturn([
+            (object) ['id' => '1', 'title' => 'Terms', 'slug' => 'terms', 'current_version_id' => '5', 'acceptance_scope' => Policy::SCOPE_SIGNUP],
+        ]);
+
+        $found = $this->repo->findForScope(Policy::SCOPE_SIGNUP);
+
+        self::assertCount(1, $found);
+        self::assertSame(Policy::SCOPE_SIGNUP, $found[0]->acceptanceScope);
+    }
+
     public function testUpdateCurrentVersion(): void
     {
         $this->db->shouldReceive('update')
@@ -57,6 +78,7 @@ class PolicyRepositoryTest extends TestCase
             'title'              => 'Cancellation',
             'slug'               => 'cancellation',
             'current_version_id' => null,
+            'acceptance_scope'   => Policy::SCOPE_BOOKING,
         ]);
 
         $policy = $this->repo->findBySlug('cancellation');
@@ -76,7 +98,7 @@ class PolicyRepositoryTest extends TestCase
     public function testFindAllMapsRows(): void
     {
         $this->db->shouldReceive('get_results')->andReturn([
-            (object) ['id' => '1', 'title' => 'A', 'slug' => 'a', 'current_version_id' => null],
+            (object) ['id' => '1', 'title' => 'A', 'slug' => 'a', 'current_version_id' => null, 'acceptance_scope' => Policy::SCOPE_BOOKING],
         ]);
 
         $all = $this->repo->findAll();

tests/Unit/Policy/PolicyServiceTest.php

@@ -56,7 +56,7 @@ class PolicyServiceTest extends TestCase
     {
         Functions\expect('current_time')->with('mysql')->andReturn('2026-06-01 12:00:00');
 
-        $this->policies->shouldReceive('findById')->once()->with(4)->andReturn(new Policy('T', 't', 8, 4));
+        $this->policies->shouldReceive('findById')->once()->with(4)->andReturn(new Policy('T', 't', 8, id: 4));
         $this->versions->shouldReceive('findById')->once()->with(9)->andReturn(new PolicyVersion(4, 2, '<p>x</p>', PolicyVersion::STATUS_DRAFT, null, 9));
 
         $this->versions->shouldReceive('updateStatus')->once()->with(8, PolicyVersion::STATUS_ARCHIVED);
@@ -70,7 +70,7 @@ class PolicyServiceTest extends TestCase
     {
         Functions\expect('current_time')->andReturn('2026-06-01 12:00:00');
 
-        $this->policies->shouldReceive('findById')->once()->with(4)->andReturn(new Policy('T', 't', null, 4));
+        $this->policies->shouldReceive('findById')->once()->with(4)->andReturn(new Policy('T', 't', null, id: 4));
         $this->versions->shouldReceive('findById')->once()->with(9)->andReturn(new PolicyVersion(4, 1, null, PolicyVersion::STATUS_DRAFT, null, 9));
 
         // No archive call expected (no prior current version).
@@ -82,7 +82,7 @@ class PolicyServiceTest extends TestCase
 
     public function testPublishRejectsVersionFromAnotherPolicy(): void
     {
-        $this->policies->shouldReceive('findById')->once()->with(4)->andReturn(new Policy('T', 't', null, 4));
+        $this->policies->shouldReceive('findById')->once()->with(4)->andReturn(new Policy('T', 't', null, id: 4));
         $this->versions->shouldReceive('findById')->once()->with(9)->andReturn(new PolicyVersion(99, 1, null, PolicyVersion::STATUS_DRAFT, null, 9));
 
         // No status/current-version writes when the version belongs elsewhere.

tests/Unit/Policy/PolicyValueObjectsTest.php

@@ -17,12 +17,14 @@ class PolicyValueObjectsTest extends TestCase
             'title'              => 'Cancellation',
             'slug'               => 'cancellation',
             'current_version_id' => '9',
+            'acceptance_scope'   => Policy::SCOPE_BOTH,
         ]);
 
         self::assertSame(4, $policy->id);
         self::assertSame('cancellation', $policy->slug);
         self::assertSame(9, $policy->currentVersionId);
-        self::assertArrayHasKey('current_version_id', $policy->toArray());
+        self::assertSame(Policy::SCOPE_BOTH, $policy->acceptanceScope);
+        self::assertArrayHasKey('acceptance_scope', $policy->toArray());
     }
 
     public function testPolicyHandlesNullCurrentVersion(): void
@@ -32,11 +34,23 @@ class PolicyValueObjectsTest extends TestCase
             'title'              => 'Cancellation',
             'slug'               => 'cancellation',
             'current_version_id' => null,
+            'acceptance_scope'   => Policy::SCOPE_BOOKING,
         ]);
 
         self::assertNull($policy->currentVersionId);
     }
 
+    public function testPolicyAppliesToScopeAndBoth(): void
+    {
+        $signup = new Policy('Terms', 'terms', acceptanceScope: Policy::SCOPE_SIGNUP);
+        self::assertTrue($signup->appliesTo(Policy::SCOPE_SIGNUP));
+        self::assertFalse($signup->appliesTo(Policy::SCOPE_BOOKING));
+
+        $both = new Policy('Both', 'both', acceptanceScope: Policy::SCOPE_BOTH);
+        self::assertTrue($both->appliesTo(Policy::SCOPE_SIGNUP));
+        self::assertTrue($both->appliesTo(Policy::SCOPE_BOOKING));
+    }
+
     public function testPolicyVersionFromRowAndStatusHelper(): void
     {
         $version = PolicyVersion::fromRow((object) [