Initial plugin scaffold: lesson scheduling WordPress plugin

- Custom DB tables for availability slots and lesson bookings
- Instructor (wp-admin) and student (front-end) roles with custom capabilities
- REST API under us-scheduler/v1 for availability CRUD and booking
- [us_booking] and [us_student_login] shortcodes for student front end
- PHPUnit + Brain\Monkey unit test suite (29 tests)
- Gitea Actions CI: lint, PHPStan, tests on PHP 8.1/8.2/8.3, no-debug check
- Feature docs under docs/features/

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/features/availability-management.md

@@ -0,0 +1,39 @@
+# Feature: Availability Management
+
+## Overview
+Instructors define date/time windows during which they are available for lessons. Students book from these windows.
+
+## Data Model — `{prefix}us_availability`
+
+| Column         | Type             | Notes                                        |
+|----------------|------------------|----------------------------------------------|
+| `id`           | BIGINT UNSIGNED  | Primary key                                  |
+| `instructor_id`| BIGINT UNSIGNED  | WordPress user ID                            |
+| `start_dt`     | DATETIME         | Slot start — stored as `Y-m-d H:i:s`        |
+| `end_dt`       | DATETIME         | Slot end — stored as `Y-m-d H:i:s`          |
+| `is_booked`    | TINYINT(1)       | 0 = available, 1 = booked                    |
+| `created_at`   | DATETIME         | Insertion time                               |
+
+## Admin Interface
+Instructors access **My Availability** in wp-admin (`?page=us-availability`).
+- Add a slot: provide start and end datetime
+- Delete a slot: only allowed if `is_booked = 0`
+
+## REST API
+| Method   | Endpoint                          | Permission              |
+|----------|-----------------------------------|-------------------------|
+| `GET`    | `/wp-json/us-scheduler/v1/availability`       | `book_lesson`           |
+| `POST`   | `/wp-json/us-scheduler/v1/availability`       | `manage_availability`   |
+| `DELETE` | `/wp-json/us-scheduler/v1/availability/{id}`  | `manage_availability` + slot owner |
+
+`GET` supports query params: `instructor_id`, `from` (datetime), `to` (datetime).
+
+## Implementation
+- Repository: `Unsupervised\Schedular\Data\AvailabilityRepository`
+- Model: `Unsupervised\Schedular\Model\AvailabilitySlot`
+- Admin controller: `Unsupervised\Schedular\Admin\AvailabilityController`
+- REST endpoint: `Unsupervised\Schedular\Api\AvailabilityEndpoint`
+
+## Tests
+- `tests/Unit/Data/AvailabilityRepositoryTest.php`
+- `tests/Unit/Model/AvailabilitySlotTest.php`

docs/features/lesson-booking.md

@@ -0,0 +1,52 @@
+# Feature: Lesson Booking
+
+## Overview
+Students browse available slots and submit a booking. Instructors then confirm or cancel from wp-admin or via the REST API.
+
+## Data Model — `{prefix}us_lessons`
+
+| Column         | Type             | Notes                                            |
+|----------------|------------------|--------------------------------------------------|
+| `id`           | BIGINT UNSIGNED  | Primary key                                      |
+| `slot_id`      | BIGINT UNSIGNED  | FK → `us_availability.id`                        |
+| `student_id`   | BIGINT UNSIGNED  | WordPress user ID                                |
+| `instructor_id`| BIGINT UNSIGNED  | WordPress user ID (denormalised for fast queries) |
+| `status`       | VARCHAR(20)      | `pending` / `confirmed` / `cancelled`            |
+| `notes`        | TEXT             | Optional student notes                           |
+| `created_at`   | DATETIME         | Insertion time                                   |
+
+## Booking Flow
+1. Student opens the page with `[us_booking]` shortcode.
+2. JS fetches `GET /availability` → renders available slots.
+3. Student clicks **Book** → `POST /bookings` with `slot_id`.
+4. Server creates the lesson row (`status = pending`) and sets `us_availability.is_booked = 1`.
+5. Instructor sees the booking under **My Lessons** in wp-admin.
+6. Instructor updates status via `PATCH /bookings/{id}/status`.
+
+## REST API
+| Method    | Endpoint                                       | Permission                    |
+|-----------|------------------------------------------------|-------------------------------|
+| `GET`     | `/wp-json/us-scheduler/v1/bookings`            | Any logged-in user            |
+| `POST`    | `/wp-json/us-scheduler/v1/bookings`            | `book_lesson`                 |
+| `PATCH`   | `/wp-json/us-scheduler/v1/bookings/{id}/status`| `manage_availability` or admin |
+
+`GET /bookings` returns the caller's own lessons (student view) or upcoming lessons for the instructor if the caller has `manage_availability`.
+
+## Admin Interface
+- **Scheduler** (`manage_options` only): all upcoming lessons across all instructors
+- **My Lessons** (`view_own_lessons`): upcoming lessons for the logged-in instructor
+
+## Frontend Shortcodes
+- `[us_booking]` — student booking form; requires `book_lesson` capability
+- `[us_student_login]` — front-end login form for students
+
+## Implementation
+- Repository: `Unsupervised\Schedular\Data\BookingRepository`
+- Model: `Unsupervised\Schedular\Model\Lesson`
+- Admin controller: `Unsupervised\Schedular\Admin\LessonController`
+- REST endpoint: `Unsupervised\Schedular\Api\BookingEndpoint`
+- Frontend: `Unsupervised\Schedular\Frontend\BookingPage`, `LoginPage`
+
+## Tests
+- `tests/Unit/Data/BookingRepositoryTest.php`
+- `tests/Unit/Model/LessonTest.php`

docs/features/user-roles.md

@@ -0,0 +1,28 @@
+# Feature: User Roles
+
+## Overview
+Two custom WordPress user roles control access to all scheduling features.
+
+## Roles
+
+### Instructor (`us_instructor`)
+Created on plugin activation. Logs in via standard wp-admin. Can:
+- Manage their own availability slots (add/delete)
+- View their upcoming confirmed/pending lessons in wp-admin
+
+**Capabilities:** `read`, `manage_availability`, `view_own_lessons`
+
+### Student (`us_student`)
+Logs in via the front-end `[us_student_login]` shortcode. Can:
+- Browse available lesson slots from all instructors
+- Book a lesson slot
+
+**Capabilities:** `read`, `book_lesson`, `view_own_lessons`
+
+## Implementation
+- Class: `Unsupervised\Schedular\Roles\RoleManager`
+- 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/Roles/RoleManagerTest.php`