Show price cadence and require a pay agreement at booking

Every price a student meets on the front end now carries the cadence it is
billed on — at booking, up front, weekly, monthly — so a bare amount can no
longer read as a one-off when it is a recurring charge.

Both registration forms then restate the price and require a second, separate
tick agreeing to pay it, distinct from the policy acceptances above it. The
agreed figure includes the studio HST so it matches Payment::total(), the amount
actually billed; the rate reaches the browser as a new localized `taxRate`.

A weekly reservation is charged per lesson for every week it claims, and a week
another student takes first is simply not claimed, so its total is quoted as a
ceiling ("up to 12 lessons") rather than a promise. Free offerings have nothing
to agree to and show no price block at all.

The formatting and the agreement live in one shared helper (`window.usPricing`,
registered as `us-scheduler-pricing`) so a price reads the same in the booking
form, the class catalogue and the editor preview.

Closes #124

Co-Authored-By: Claude Opus 5 <[email protected]>

docs/features/group-classes.md

@@ -38,12 +38,13 @@ shows "You are enrolled in this class." instead of the Enrol button (the
 server would reject the duplicate with `409 already_enrolled` regardless — a
 cancelled enrolment does not block re-enrolling).
 
-1. Student opens a group class from the offering catalog.
+1. Student opens a group class from the offering catalog. Each class card shows its price with the **cadence** it is billed on — `120.00 CAD up front`, `40.00 CAD monthly`, and so on.
 2. Student answers the offering's questions (`GET /offerings/{id}/questions`).
 3. Student accepts the current published policy versions (`GET /policies`) — required to continue.
-4. Full-term payment is taken per the student's billing method (card by default; `pending` for e-transfer; skipped for comp). See `payments.md`.
-5. `POST /enrollments` creates the enrolment (`status = active`), records answers and policy acceptances, and links the payment — but only if the offering's `capacity` has not been reached.
-6. On successful payment (or comp) a receipt is emailed.
+4. The enrolment form restates the price (with HST) and requires a second, separate agreement to pay that amount before it will submit. See **Price Display and the Pay Agreement** in `payments.md`.
+5. Full-term payment is taken per the student's billing method (card by default; `pending` for e-transfer; skipped for comp). See `payments.md`.
+6. `POST /enrollments` creates the enrolment (`status = active`), records answers and policy acceptances, and links the payment — but only if the offering's `capacity` has not been reached.
+7. On successful payment (or comp) a receipt is emailed.
 
 Capacity is enforced at enrolment time by counting `active` rows for the offering;
 a class at capacity rejects further enrolments.

docs/features/lesson-booking.md

@@ -25,11 +25,12 @@ Students register for a private lesson by choosing an offering, picking a time (
 3. For a `weekly` reservation, the same weekday/time is held for the rest of the offering's term.
 4. Student answers the offering's questions (`GET /offerings/{id}/questions`).
 5. Student accepts the current published policy versions (`GET /policies`) — required to continue.
-6. Payment is taken per the student's billing method (card by default; `pending` for e-transfer; skipped for comp). See `payments.md`.
-7. `POST /bookings` creates the lesson row(s) (`status = pending`), records answers and policy acceptances, marks `us_availability.is_booked = 1`, and links the payment. A booking with nothing owed (a free offering) creates no payment and is `confirmed` immediately.
-8. On successful payment (or comp) the lesson is `confirmed` and a receipt is emailed.
-9. Instructor sees the booking under **My Lessons** and may update status via `PATCH /bookings/{id}/status`.
-10. The booking page also shows the student their upcoming lessons (`GET /bookings`) — each with the booked offering's name and length, when it happens, a per-lesson status badge (pending payment / confirmed), and a **Cancel** button. Only the soonest five are shown; a **Show all** control reveals the rest. `GET /bookings` includes `offering_title` and `duration_minutes` for each lesson so the list needs no extra request.
+6. Student is shown what the booking costs — the offering's price with its **cadence** (at booking / up front / weekly / monthly), plus HST — and must tick a second, separate agreement to pay that amount before the form will submit. A weekly reservation quotes the per-lesson fee and the ceiling on the total it can claim. A free offering shows no price block. See **Price Display and the Pay Agreement** in `payments.md`.
+7. Payment is taken per the student's billing method (card by default; `pending` for e-transfer; skipped for comp). See `payments.md`.
+8. `POST /bookings` creates the lesson row(s) (`status = pending`), records answers and policy acceptances, marks `us_availability.is_booked = 1`, and links the payment. A booking with nothing owed (a free offering) creates no payment and is `confirmed` immediately.
+9. On successful payment (or comp) the lesson is `confirmed` and a receipt is emailed.
+10. Instructor sees the booking under **My Lessons** and may update status via `PATCH /bookings/{id}/status`.
+11. The booking page also shows the student their upcoming lessons (`GET /bookings`) — each with the booked offering's name and length, when it happens, a per-lesson status badge (pending payment / confirmed), and a **Cancel** button. Only the soonest five are shown; a **Show all** control reveals the rest. `GET /bookings` includes `offering_title` and `duration_minutes` for each lesson so the list needs no extra request.
 
 ## Lesson-Type Filter
 Not every open slot can be booked as every private-lesson type — a slot tied to

docs/features/offerings.md

@@ -35,6 +35,11 @@ An offering is anything a student can register for: a private-lesson type (30 or
 - `weekly` — **not** charged at registration; a pending payment for one lesson's fee is generated **24 hours before each lesson** by the daily billing scan.
 - `monthly` — **not** charged at registration; on the **1st of each month** a single pending payment is generated for every lesson that falls in that month (4 lessons ⇒ 4 × fee).
 
+Students see the mode as a **cadence** beside every price on the front end — *at
+booking*, *up front*, *weekly*, *monthly* — and confirm it explicitly before a
+booking or enrolment goes through. See **Price Display and the Pay Agreement** in
+`payments.md`.
+
 `weekly` and `monthly` are *scheduled* billing (`Offering::isScheduledBilling()`): the
 booking/enrolment succeeds with no payment step, and payments are created later by the
 daily `us_generate_due_payments` cron scan. See `scheduled-billing.md` and `payments.md`.

docs/features/payments.md

@@ -98,6 +98,47 @@ After booking, the destination on a payment can be corrected per booking:
 | `created_at`               | DATETIME         | Insertion time                                        |
 | `paid_at`                  | DATETIME         | When marked `paid`; NULL otherwise                    |
 
+## Price Display and the Pay Agreement
+Every price a student is shown on the front end carries its **cadence** — the
+offering's `billing_mode` in the words the student needs:
+
+| `billing_mode` | Shown as     | Explained beneath as                                       |
+|----------------|--------------|------------------------------------------------------------|
+| `one_time`     | `at booking` | Charged once, when you book.                               |
+| `full_term`    | `up front`   | Charged once, up front, for the whole term.                |
+| `weekly`       | `weekly`     | Charged for each lesson, 24 hours before it starts.        |
+| `monthly`      | `monthly`    | Charged on the 1st of each month, for that month's lessons.|
+
+So a lesson type reads `50.00 CAD at booking` in the booking form's type picker,
+and a group class card reads `120.00 CAD up front`. A free offering shows `Free`.
+
+Before a booking or enrolment can be submitted, the form shows the price again as
+a summary block with a **required agreement checkbox** — the second confirmation,
+distinct from the policy acceptances above it:
+
+> ☐ I agree to pay 56.50 CAD at booking.
+
+The agreed figure is the amount actually billed, so the studio **HST rate** is
+added to it (`usScheduler.taxRate`, localized from `us_hst_rate`) and broken out
+above the checkbox — matching the total `Payment::total()` charges. A comped
+student is not taxed and is not charged at all, so for them the quoted figure is
+an upper bound. A free offering has nothing to agree to and shows no block.
+
+Cadence-specific wording:
+
+- **Weekly reservation of a `one_time` lesson type** — the fee is charged once per
+  week claimed, so the agreement states the per-lesson amount and the total as a
+  ceiling ("up to 12 lessons, 678.00 CAD in total"). The occurrence count mirrors
+  `BookingEndpoint::MAX_WEEKLY_OCCURRENCES`; a slot another student takes first is
+  simply not claimed, so the real charge can come in under it.
+- **`weekly` / `monthly`** — nothing is taken at registration, so the agreement is
+  to the recurring charge: "I agree to pay 56.50 CAD per lesson, billed monthly."
+
+All of this lives in `assets/js/pricing.js` (`window.usPricing`), shared by the
+booking and group-class flows so a price reads the same wherever it is met. The
+script is registered as `us-scheduler-pricing` and is a dependency of both
+`us-scheduler` and `us-scheduler-group`.
+
 ## Payment Flow
 1. During registration the front-end calls `POST /payments/intent` — but only when the registration response carried a `payment` summary (unpriced registrations return `payment: null` and skip the payment step). The intent call creates a Stripe PaymentIntent for a `card` student and returns the client secret. (`etransfer` returns a `pending` payment; `comp` returns none.)
 2. The browser confirms the card payment with Stripe.
@@ -139,8 +180,10 @@ See `payment-reporting.md` for the monthly report and CSV export endpoints.
 - Receipts: `Unsupervised\Schedular\Payment\ReceiptMailer`
 - Settings page: `Unsupervised\Schedular\Payment\StudioSettings`
 - REST endpoint: `Unsupervised\Schedular\Payment\PaymentEndpoint`
+- Front-end price display + pay agreement: `assets/js/pricing.js` (`window.usPricing`), registered and localized with `taxRate` by `Unsupervised\Schedular\ShortcodeRegistrar`
 
 ## Tests
+- `tests/Unit/ShortcodeRegistrarTest.php` (pricing helper registration + localized `taxRate`)
 - `tests/Unit/Payment/PaymentRepositoryTest.php`
 - `tests/Unit/Payment/PaymentTest.php`
 - `tests/Unit/Payment/StripeGatewayTest.php`