recess-cli 1.4.0 → 1.6.0

package/skill/recess-cli/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Recess CLI"
-  short_description: "Safely operate Recess admin workflows"
-  default_prompt: "Use $recess-cli to find a family and safely perform the requested Recess admin action."
+  short_description: "Route safe Recess CLI work by audience"
+  default_prompt: "Use $recess-cli to authenticate, select the correct guardian or admin skill catalog, and safely complete the requested Recess task."

package/skill/recess-cli/agents/version.json

@@ -0,0 +1,4 @@
+{
+  "version": "2.0.0",
+  "minCliVersion": "1.6.0"
+}

package/skill/recess-cli/reference/billing.md

@@ -1,146 +0,0 @@
-# Billing, subscriptions, refunds, and cohort registration links
-
-Read [`../SKILL.md`](../SKILL.md) first — the safety model, escalation discipline, and input conventions there govern everything below.
-
-## Resolve, then read
-
-Search returns the matching people, their family, every family member, and each member's enrollments and cohort registrations:
-
-```bash
-recess --json users search "parent or kid name"
-recess --json enrollments list --user <kid-id>
-```
-
-Read the exact billing state before proposing a write:
-
-```bash
-recess --json subscriptions list --family <family-id> --kid <kid-id>
-recess --json invoices list --subscription <subscription-id>
-recess --json enrollments get-for-subscription --subscription <subscription-id>
-recess --json cohorts search "cohort name"
-```
-
-## Pausing and resuming collection
-
-```bash
-recess --json billing pause --subscription sub_123 --until 2026-09-01 --confirm
-recess --json billing pause --subscription sub_123 --confirm          # indefinite
-recess --json billing resume --subscription sub_123 --confirm
-```
-
-- Without `--until`, the pause is **indefinite** — say so in the approval request; someone must remember to resume it.
-- `--until` must be a future ISO date; the CLI converts it to the Stripe resume timestamp.
-
-### Pause timing semantics (read before choosing `--until`)
-
-Verified in source 2026-07-17: `apps/web-server/src/routes/admin/stripe/post.pause-collection.ts` (the endpoint both pause forms hit) and `apps/web-server/src/libs/enrollment/dry-run-stripe-dates.ts` (how subscriptions get their billing anchor).
-
-- **Paused invoices are voided.** Both pause forms send Stripe `pause_collection` with `behavior: "void"`: every subscription invoice generated while the pause is active is voided outright — the family is never charged for those cycles, and nothing accrues for later collection. Access is unaffected (the subscription keeps cycling; only collection stops).
-- **Billing ticks are Sunday-anchored.** Weekly course subscriptions are created with `billing_cycle_anchor` = Sunday 00:00 server time (UTC in prod) via `nextSundayEpochTimeS`; monthly products anchor to the 1st of the month. A weekly invoice issued on Sunday S covers the week starting S — so to skip a given session, you void the invoice of the **Sunday that starts that session's week**.
-- **`--until` is the Stripe `resumes_at` timestamp.** A bare ISO date parses as midnight UTC of that date. Every billing tick strictly before it is voided; the first tick at or after it charges normally.
-- **Choosing the date:** identify the Sunday starting the last week to skip (`S_last`) and the following Sunday (`S_next`). Pick an `--until` strictly between them, away from both edges — mid-week is safest. Example: to skip sessions on Thu 7/23 and Thu 7/30, void the Sunday 7/19 and Sunday 7/26 invoices and resume before Sunday 8/2 → `--until 2026-07-29` (anything 7/27 through 8/1 works).
-- **The cohort-wide sibling encodes this SOP server-side:** `cohorts pause-billing --weeks N` computes `resumes_at` = upcoming Sunday + N weeks − 2 hours (`post.cohort-pause-billing.ts`) — skip exactly N Sunday invoices, then resume with a 2-hour safety margin before the next tick so the resume never collides with the billing moment. Mirror that margin thinking when hand-picking `--until`.
-- **DB caveat:** the per-subscription pause writes only to Stripe — it never stamps `Enrollment.pausedAt`/`pauseResumesAt` (the cohort route stamps both). Verify a per-subscription pause via Stripe state (`subscriptions list`), never via the enrollment row.
-- **Known false error on success:** the confirmed write can come back as `api_error` with `details.status: 200` because the route omitted its success body (patched 2026-07-17, false error persists until deployed — see the gotcha in SKILL.md). Treat it as "probably landed" and verify via `subscriptions list` before doing anything else.
-
-## Trials and cancellation
-
-```bash
-recess --json billing extend-trial --subscription sub_123 --trial-end 2026-09-01 --confirm
-recess --json billing cancel-subscription --subscription sub_123 --reason "Family moved off platform" --confirm
-recess --json billing cancel-subscription --subscription sub_123 --restore --confirm
-```
-
-- Default cancellation is **at period end** (the family keeps access until then). `--immediate` removes that grace — treat it as exceptional and call it out explicitly in the approval request, like `who-pays=recess`.
-- `--restore` un-cancels a previously scheduled cancellation. Read the subscription first and confirm it actually has a pending cancellation.
-- Always pass `--reason` on cancellations; it lands in the admin audit trail.
-
-## Refunds and credits
-
-```bash
-recess --json invoices refund --invoice in_123 --line-item il_123 \
-  --method refund --full --who-pays guide --reason "Canceled session" --confirm
-```
-
-Three methods, different rules:
-
-| `--method` | What happens | Amount rules |
-|---|---|---|
-| `refund` | money back to the payment method (Stripe credit note) | `--full` or `--amount-cents N` |
-| `credit` | credit against the customer's balance (Stripe credit note) | `--full` or `--amount-cents N` |
-| `tokens` | Recess token grant instead of money | requires explicit `--amount-cents`; `--full` is rejected |
-
-- `--who-pays` defaults to `guide`. `--who-pays recess` means Recess absorbs the cost — exceptional, name it explicitly in the approval request.
-- Amounts are integer cents. Cross-check any dollar figure the human states before previewing.
-- Target the **line item** (`--line-item`), not the whole invoice; run `invoices list` first to identify it.
-- **Check how the invoice was paid before choosing the method.** `invoices list` exposes the payment composition per invoice — verify it and state it in the approval request:
-  - `token_deduction_cents` > 0 → that portion was paid with Recess tokens; give it back as `--method tokens` against `token_refundable_remaining_cents`, never as cash/credit.
-  - `applied_balance` < 0 → that portion was covered by existing customer credit; `amount` (actually collected) is less than `subtotal`, so a "full" cash refund would over-refund.
-  - Only when `amount` = `subtotal`, `token_deduction_cents` = 0, `applied_balance` = 0, and `paymentIntent.status` = `succeeded` was the invoice fully cash-paid and a `--full` refund/credit clean.
-  - Also read `credited_amount`/`post_payment_credited_amount` — a line already credited (memo shows why) must not be credited twice.
-
-## Signing a kid up for a paid class (`enrollments create`)
-
-The staff equivalent of a guardian buying a class. **This replaces impersonating the parent and walking their checkout** — same backend path (`initiateStripePayment`), so course discounts, Recess credit deduction, per-kid payment methods, and one-time-vs-recurring bundles all behave exactly as they do for the family.
-
-```bash
-# Always run unconfirmed first — this performs the backend's own dry run.
-recess --json enrollments create --user <kid-id> --cohort <cohort-id>
-
-# Then, after explicit human approval of the quoted amount:
-recess --json enrollments create --user <kid-id> --cohort <cohort-id> --confirm
-```
-
-**It spends real money.** The unconfirmed run is not an offline guess — it calls the backend with `dryRun:true` (writes nothing) and returns the *resolved* price, so the approval request must quote `details.billing` verbatim: `effectivePriceCents` (what Stripe bills after any course discount — **not** `listPriceCents`), `interval`, `firstChargeAt`, `chargesImmediately`, and `creditBalanceCents` when non-zero. Never quote a price from the course catalog or from memory; discounts and credits change it.
-
-Read the preview before escalating:
-
-- **`details.reusedEnrollmentId` is set** → the kid already holds an active enrollment with a free slot for this course. Nothing is charged and no subscription is created; the command just links the registration. Say that plainly — an approver told "we're charging $X" when the answer is $0 has been misled.
-- **`details.warnings` non-empty** → the cohort is at capacity and/or the kid's school-program class slots are exhausted. The write is **rejected** unless you also pass `--force`. Name the specific warning in the escalation; do not reach for `--force` as a reflex.
-- **`chargesImmediately: true`** → the family's card is charged during the confirmed call.
-
-### Deferring the first charge (`--first-charge-at`)
-
-```bash
-recess --json enrollments create --user <kid> --cohort <coh> \
-  --first-charge-at 2026-08-02T00:00:00Z --confirm
-```
-
-Recurring bundles only (a one-time bundle always invoices now — the route 400s `FIRST_CHARGE_UNSUPPORTED`). The subscription is created `trialing` until that instant, so **nothing is charged now**, and the recurring cycle re-anchors to it. Weekly Recess subscriptions all bill Sunday 00:00 UTC, so that is almost always the date you want — an arbitrary weekday anchor puts this family permanently out of step with every other weekly sub.
-
-Use it for goodwill and remediation: a kid joining mid-week who shouldn't pay for the remainder, or restoring access after a Recess-caused cancellation. Because no invoice is paid, the `invoice.paid` webhook that normally provisions everything never fires — so the route provisions the enrollment and registration **inline**, and the kid has access immediately. `result.mode` is `subscription_deferred` and `provisionedInline` is `true`.
-
-With no `--first-charge-at`, the invoice is paid during the call and the webhook does the provisioning; `enrollmentId`/`registrationId` come back `null` and `provisionedInline` is `false`. That is expected, not a failure — verify with `enrollments list --user` a few seconds later rather than treating the nulls as an error.
-
-**If it fails with `ENROLLMENT_PROVISION_FAILED`, do not retry.** The Stripe subscription was created; a retry sells a second one. Escalate with the subscription ID from the error message.
-
-## Cohort registration against an enrollment
-
-```bash
-recess --json enrollments register-cohort --enrollment <enrollment-id> --user <kid-id> --cohort <cohort-id> --confirm
-recess --json enrollments unregister-cohort --user <kid-id> --cohort <cohort-id> --confirm
-```
-
-- `register-cohort` links the registration to the named enrollment and sends **no** email (`sendEmail:false`) — it is the quiet administrative link, unlike `registrations approve` which welcomes the family.
-- `unregister-cohort` removes the cohort registration but **leaves the enrollment active** (`cancelEnrollment:false`). Enrollment cancellation is a different workflow: the only CLI path that cancels an enrollment is `registrations deny` (see [`class-ops.md`](class-ops.md)). Never substitute one for the other.
-
-### Switching a kid's cohort (the move play)
-
-Composing the two commands moves a kid (or a whole roster) to another cohort **without ever breaking the enrollment link or touching billing**. Proven 2026-07-17 moving 10 kids across two source cohorts.
-
-1. **Read both cohorts first** (`cohorts get` each): confirm the destination belongs to the **same course** as the enrollments; compare destination `capacity` against current registered count + incoming headcount; collect each kid's `userId` + `enrollmentId` from the source roster; note schedule/timezone/guide differences for the escalation.
-2. **Order is register-first, unregister-second, per kid** — never the reverse. A register that fails (capacity, state) then leaves the kid safely registered in the old cohort; the reverse order would strand them registered nowhere.
-   ```bash
-   recess --json enrollments register-cohort --enrollment <enr> --user <kid> --cohort <new> --confirm
-   recess --json enrollments unregister-cohort --user <kid> --cohort <old> --confirm
-   ```
-3. **Batch shape:** preview everything → one escalation → run ALL registers → then only the unregisters whose register succeeded.
-4. **Capacity is enforced server-side even on this admin path** (400 `RA_REG_NOT_ALLOWED` "This cohort is at capacity"); capacity editing is web-admin-only, so check it in step 1 or expect safe mid-batch failures.
-5. **Registrations without an Enrollment** (guide's own kid, ops accounts) can't be moved this way — `register-cohort` requires `--enrollment`. List them for the human.
-6. **Verify:** both rosters via `cohorts get`, and each moved kid's enrollment still ACTIVE on the same `stripeSubscriptionId` (`enrollments list --user`).
-7. **Call out in the escalation:** zero family notification (both commands are quiet — offer a `cohorts email` to the destination cohort afterward for the schedule change), billing untouched, and the emptied source cohorts stay ACTIVE (`cohorts end` is a separate decision).
-8. **⚠️ Never run `cohorts end --cancel-subscriptions` on the source cohort afterward.** A move reuses the *same* enrollment and Stripe subscription, and leaves a `CANCELED_REFUNDED` registration row behind in the source cohort. `cohorts end` selects its victims by *any* registration in that cohort regardless of status, so it cancels the subscription that is now paying for the **destination** cohort — and about a week later, when Stripe fires `customer.subscription.deleted`, every registration on that enrollment is swept, including the new one. **This happened on 2026-07-19** and silently unenrolled 9 of 10 just-migrated kids; the only enrollments still ACTIVE on the old cohorts were the ones that had just been moved, so the blast radius was exactly the migrated roster. End the old cohort **without** the flag. Full mechanics: [`web-server.md`](https://github.com/tryrecess/monolith/blob/staging/docs/codebase/web-server.md) § "cohorts end --cancel-subscriptions after a cohort migration".
-
-## Verify
-
-After confirmed writes, re-read: `subscriptions list` for pause/trial/cancel state, `invoices list` for the credit note, `enrollments list` / `cohorts get` for registration changes. Report the final API responses.

package/skill/recess-cli/reference/cancellation-credits.md

@@ -1,53 +0,0 @@
-# Class-cancellation credits — the "Please credit these students accordingly" workflow
-
-Read [`../SKILL.md`](../SKILL.md) first — the safety model, escalation discipline, and input conventions there govern everything below. Pause/refund mechanics live in [`billing.md`](billing.md); read its "Pause timing semantics" and refund payment-composition checklist before running this.
-
-## Trigger and why this playbook exists
-
-When a guide cancels a class session (`events cancel`, or the same route from the web), the backend (`apps/web-server/src/routes/admin/events/post.cancel-event.ts`) fires the family-facing fan-out AND posts to Slack `#cohort-cancellations`:
-
-> 🚫 Class Canceled … *Registered students:* … _Please credit these students accordingly._
-
-It also stamps a `UserNote` ("Credit owed: {course} on {date} was canceled…") on each kid registered **at cancel time**. That is where automation stops: **nothing refunds the families.** The crediting is manual, per-kid, and error-prone — this playbook is that step, done agentically. Forensics from the 2026-07-16 "Honey Squad - Steam Games" cancellation (verified via Apitally request logs + live invoice reads) showed the manual process lagging 2 days, silently under-refunding a mixed-composition invoice, and working from a stale roster. Every rule below traces to an observed failure.
-
-## The procedure
-
-**1. Resolve the canceled event.**
-```bash
-recess --json cohorts search "<cohort name from the Slack message>"
-recess --json cohorts get <cohort-id>
-```
-Find the CANCELED event matching the stated date (cohort-local time — "1:30 PM PDT Thursday July 16" = `2026-07-16T20:30Z` for a `America/Los_Angeles` cohort). Note `course.eventsPerWeek` and the bundle's weekly price.
-
-**2. Build the roster LIVE — never from the Slack message.** The Slack roster is a cancel-time snapshot of `status: REGISTERED` registrations and has been observed to **under-report** (2026-07-16: a kid registered since 2025 was invoiced for the canceled week yet absent from the Slack list). Work from the cohort's current REGISTERED registrations, cross-checked both directions:
-- In Slack but no longer registered / enrollment gone → skip, note why in the escalation.
-- Registered + invoiced for the canceled week but absent from Slack → include.
-- Registration with **no Enrollment** (guide's own kid, ops/test accounts) → nothing to refund; list as "no billing".
-
-**3. For each kid, find the invoice that covers the canceled session.**
-```bash
-recess --json enrollments list --user <kid-id>     # → the enrollment registered to THIS cohort → stripeSubscriptionId
-recess --json invoices list --subscription <sub-id>
-```
-Weekly subscriptions bill on Sunday-00:00-UTC anchors ([`billing.md`](billing.md)): the invoice created on the **Sunday starting the session's week** is the one owed back (session Thu 7/16 → the Sunday 7/12 invoice). No such invoice (pause, trial, joined mid-week) → skip, say so. Match invoice IDs **in full** — two distinct same-week invoices have shared their first 18 characters, differing only in the final 8.
-
-**New-signup trap:** signups create an immediate backdated invoice + a $0 "Trial period" invoice, and the sub sits `trialing` until a Sunday anchor (see the SKILL.md 2026-07-17 signup-billing gotcha). The immediate invoice pays for the kid's FIRST class week, not necessarily the session's week; if `trial_end` (from `subscriptions list`) is at/after the Sunday ending the session's week, the family was never charged for that session → skip, and don't claw back the immediate invoice (it maps to an earlier session).
-
-**4. Compute what is owed.** The canceled session's share of that week's invoice line. With `eventsPerWeek: 1` that is the full line (`--full` / the full weekly price). Multi-session weeks: the per-session share — confirm the split with the human rather than guessing.
-
-**5. Choose the instrument(s) from the invoice's payment composition** (checklist in [`billing.md`](billing.md)):
-
-| Composition | Action |
-|---|---|
-| Fully cash-paid (`token_deduction_cents` 0) | `invoices refund --method credit --full` (or `--amount-cents` for a per-session share) |
-| Fully token-paid | `--method tokens --amount-cents <token portion>` |
-| **Mixed** (tokens + cash) | **BOTH commands**: `tokens` for `token_deduction_cents`, `credit` for the cash remainder (`amount`). Observed live 2026-07-17: ops refunded a $4 token portion and missed the $11 cash portion of a $15 line |
-| Already credited (`credited_amount` > 0 or `token_refunded_cents` > 0) | **skip** — someone processed it first. This workflow runs days late and sometimes concurrently with a human; always re-read before previewing |
-
-**6. Flags.** `--who-pays guide` (the default) for guide-initiated cancellations. Reason: `"Guide cancellation - <cohort> <session date>"` (the observed convention is bare "Guide cancellation"; include the session date so repeat cancellations stay distinguishable).
-
-**7. Batch escalate.** One approval request: a table of kid → invoice (full ID) → line item → method → amount → reason, plus every skip and why. Then `--confirm` each unchanged command, then verify by re-reading each invoice (`credited_amount` / `token_refunded_cents`) and report final state.
-
-## When the CLI itself cancels the class
-
-`events cancel` triggers this same Slack message and the credit-owed notes ([`class-ops.md`](class-ops.md)). After a confirmed `events cancel`, offer to run this playbook immediately — same-session processing beats the observed 2-day lag and roster drift.

package/skill/recess-cli/reference/class-ops-reschedule.md

@@ -1,41 +0,0 @@
-# Non-flexible course time shifts (`events reschedule` blocked)
-
-Companion to `reference/class-ops.md` § Reschedules and one-off sessions.
-
-## Gate
-
-`events reschedule` requires `course.allowFlexibleScheduling === true` on `cohorts get`.
-
-When false, confirmed write returns API 400:
-
-> This course does not allow editing individual event times. Enable flexible scheduling on the course first.
-
-CLI cannot toggle the flag — web admin course settings only. Do not stop at "enable flexible scheduling" if staff needs the move now; use the workaround below.
-
-## Worked example (2026-07-23)
-
-- Cohort: Space Technology & Rocket Launches (resolve its id with `cohorts search`)
-- Course: Current Events in Space Tech & Rockets — `allowFlexibleScheduling: false`
-- Ask: move today up 10 minutes (Starship)
-- Usual slot: Thu 15:45 America/Edmonton → UTC `21:45`
-- Target: 15:35 Edmonton
-- Prior week evidence: ENDED pair on 2026-07-16 at both `21:35` and `21:45` UTC — ops already used one-off add, not true reschedule
-
-## Workaround (batch one approval)
-
-```bash
-# 1) Preview both (no --confirm)
-recess --json events add --cohort <cohort-id> \
-  --starts-at YYYY-MM-DDTHH:MM --timezone <cohort-tz> --length-mins 60
-recess --json events set-status <original-event-id> --status CANCELED
-
-# 2) After human OK, same commands with --confirm
-# 3) Verify
-recess --json cohorts get <cohort-id> --events-tab ACTIVE
-```
-
-Rules:
-
-- Use `set-status CANCELED` (silent). Never `events cancel` unless staff asked to notify families.
-- Approval text must say: new one-off + silent cancel of original, no parent blast.
-- Prefer this path over asking staff to flip flexible scheduling mid-incident when history shows prior one-offs.

package/skill/recess-cli/reference/class-ops.md

@@ -1,89 +0,0 @@
-# Class ops (attendance, cancellations, schedule changes, cohort lifecycle, registration approvals)
-
-Read [`../SKILL.md`](../SKILL.md) first — the safety model, escalation discipline, and input conventions there govern everything below.
-
-Cohorts are recurring class groups; each session is an event. Staff instructions arrive in plain language ("cancel Thursday's KSP and let families know", "take attendance for yesterday's 2pm session", "approve the pending signups"). Resolve them to IDs before writing.
-
-## Resolve the cohort and event first
-
-```bash
-recess --json cohorts search "Kids Startup Program"
-recess --json cohorts get <cohort-id>
-recess --json events get <event-id>
-```
-
-`cohorts get` returns the cohort's events (IDs, dates, statuses; filter with `--events-tab ACTIVE|ENDED|CANCELED|ARCHIVED`), its registrations including PENDING_APPROVAL ones with their registrationIds, and the derived billing-pause state. `events get` returns the session's roster with each kid's current attendance mark and per-cohort attendance counts. Match a spoken time ("Thursday's class", "the 2pm session") against event dates in the cohort's timezone; if more than one event fits, ask the human which one.
-
-## Attendance
-
-```bash
-recess --json events take-attendance <event-id> \
-  --attended <kid-id,kid-id> --absent <kid-id> --excused <kid-id> --confirm
-```
-
-- Run `events get` first and account for every REGISTERED kid: each goes in exactly one of `--attended`, `--absent`, or `--excused`. The CLI rejects overlapping lists and requires at least one list.
-- The attendance timestamp is set to now automatically; there is no back-dating flag.
-- Non-excused absentees can trigger automatic "we missed you" emails to their parents (when the cohort has absence emails on), and two consecutive absences alert staff in Slack. Name this in the approval request — mis-marking a kid absent emails a real family.
-- "Everyone came except Matthew (excused)" → every other registered kid in `--attended`, Matthew in `--excused`.
-
-## Cancel vs silent status change
-
-Two different operations — choose deliberately:
-
-```bash
-recess --json events cancel <event-id> --reason "Guide is sick" --confirm
-recess --json events set-status <event-id> --status CANCELED --confirm
-```
-
-- "Cancel the class and tell families" → `events cancel`. It notifies kid and parent chat channels, emails every registered parent, files a credit-owed note per student, and posts to Slack. There is no quiet variant of this command; the reason text is shown to families.
-- Canceling does NOT refund anyone — the Slack message ends with "Please credit these students accordingly" and that step is on us. After a confirmed `events cancel`, offer to run [`cancellation-credits.md`](cancellation-credits.md) immediately.
-- Administrative bookkeeping (event created by mistake, duplicate, already communicated) → `events set-status --status CANCELED`, which sends nothing.
-- Reactivate or publish a session → `events set-status --status ACTIVE`; mark it finished → `--status ENDED`.
-- If the instruction is ambiguous about notifying, ask; never guess an outward blast.
-
-## Reschedules and one-off sessions
-
-```bash
-recess --json events reschedule --cohort <cohort-id> --event <event-id> \
-  --starts-at 2026-07-23T15:00 --timezone America/Los_Angeles --confirm
-recess --json events add --cohort <cohort-id> --starts-at 2026-07-23T15:00 \
-  --timezone America/Los_Angeles --length-mins 60 --confirm
-```
-
-- Always move a session with `events reschedule` — never by editing the event's status or date directly. The reschedule path leaves a tombstone so schedule regeneration doesn't re-create the old slot.
-- Times are zoneless cohort-local: "move to 3pm" means `15:00` in the cohort's timezone; a timezone offset in `--starts-at` is rejected. Pass `--timezone` using the value from `cohorts get` when unsure.
-- `--length-mins` overrides the session length; omit it to keep the cohort default.
-- Only flexible-scheduling courses and ACTIVE events can be rescheduled; a 409 means the target slot already has an event.
-
-## Cohort lifecycle and email
-
-```bash
-recess --json cohorts end <cohort-id> --confirm
-recess --json cohorts pause-billing <cohort-id> --weeks 2 --confirm
-recess --json cohorts resume-billing <cohort-id> --confirm
-recess --json cohorts email <cohort-id> --target ALL_PARENTS --content "..." --confirm
-```
-
-- `cohorts end` (no flag) archives the cohort's channels and future events and leaves subscriptions untouched. `--cancel-subscriptions` sets EVERY active enrollment's Stripe subscription to cancel at period end — treat the flag as exceptional and call it out explicitly in the approval request, like `who-pays=recess`.
-- `pause-billing` pauses Stripe collection for every subscription in the cohort for 1–6 weeks (invoices void while paused). The server computes the window itself: `resumes_at` = upcoming Sunday 00:00 (server time, UTC in prod) + N weeks − 2 hours, because weekly subscriptions bill on Sunday-midnight anchors — so `--weeks N` skips exactly N Sunday invoices and resumes just before the next one (`post.cohort-pause-billing.ts`; full timing semantics in [`billing.md`](billing.md)). It also stamps `Enrollment.pausedAt`/`pauseResumesAt`, which is where `cohorts get`'s derived billing-pause state comes from. Enrollments already paused (`behavior: "void"`) or with `expireAtPeriodEnd` are skipped. Both directions are Stripe writes affecting real payments. `resume-billing` takes no `--weeks` and clears the pause plus the enrollment stamps.
-- `cohorts email` sends a real outward email blast. Before requesting approval, run `cohorts parent-emails <cohort-id>` and include the recipient count in the escalation. `ALL_PARENTS_GUIDES` adds guides, owners, and support. Content starting with a dash run needs the `--content="…"` form (see the flag parser traps in SKILL.md).
-
-## Registration approvals
-
-`cohorts get` lists PENDING_APPROVAL registrations with their registrationIds.
-
-```bash
-recess --json registrations approve --registration <registration-id> --confirm
-recess --json registrations deny --cohort <cohort-id> --user <kid-id> --confirm
-```
-
-- Approve flips the registration to REGISTERED and sends the family a welcome email.
-- Deny removes the registration AND cancels the enrollment — that is what the web admin's Deny button does. Never substitute the enrollment-preserving `enrollments unregister-cohort` for a denial (or vice versa).
-
-## Batch and verify
-
-Same discipline as payout ops: collect all previews without `--confirm`, present one batched approval request that names every side effect (family notifications, absence emails, Stripe changes, welcome emails), then rerun unchanged with `--confirm` and re-read (`events get` / `cohorts get`) to verify the new state.
-
-## Out of scope
-
-Cohort creation, start, full schedule edit/RRULE regeneration, generate-events, and guides management stay in the web admin cohort pages. If asked, direct the human there.

package/skill/recess-cli/reference/goal-authoring.md

@@ -1,274 +0,0 @@
-# Authoring learning content from the CLI
-
-The workflow behind `skills`, `goal-templates`, `goals`, and `mesa files`. Read this before the
-first write; the tool→command mapping and the one-way rules live in `SKILL.md` under "Learning-content
-contract".
-
-The point of this surface is not that an agent *can* create a template — the API always allowed
-that. It is that an agent can create a template **as good as one authored through `recess.gg/ai`**,
-because it loads the same authoring skills the in-product tutor loads. Skipping step 0 gives you a
-structurally valid template that is pedagogically wrong, and nothing downstream will catch it.
-
----
-
-## 0. Load the authoring skills. Always. First.
-
-```bash
-recess --json skills get os-v2-goal-template-builder --all-references
-```
-
-`--all-references` pulls `references/deterministic-workflow-setup.md` in the same call — that
-document is the catalog of what the deterministic handlers can express, and you cannot author a
-correct spec without it. Without the flag you get SKILL.md plus a reference *index*, and each
-reference is a separate `--reference <name>` call (the same two-step the in-product agent uses).
-
-Responses cache for about an hour under `~/.recess-cli/skills-cache/`. Pass `--refresh` when someone
-has just edited a skill.
-
-These documents are proprietary and are served, never shipped. Do not copy their text anywhere.
-
-### Which research doc, for what
-
-"Deep research" is not one method here — pick by what you are researching. Every one of these assumes
-OSAgent research tools you do not have; SKILL.md's "Research tools → your own harness" says what to
-substitute, and names the one real gap (`fetch_page_structure`).
-
-| Researching | Load |
-|---|---|
-| An external platform's assignable content, to bake a queue into a template | `os-v2-goal-template-builder --all-references` → §"The research loop" + §"The validation loop" |
-| Content for a module-backed goal workspace | `os-v2-goal-builder --all-references` → `research-protocol.md` (wave dispatch, lookup order, verification rules, output file shape) |
-| A goal from an uploaded curriculum (PDF, scope-and-sequence) | `os-v2-goal-builder --reference curriculum-source` |
-| A goal for one kid, from scratch, in depth | `goal-creation --reference structured-plan` (S1–S6; S4 is the parallel deep research, S2 carries the depth cascade) + `--reference subagent-tasks` for the five researcher prompts |
-| The same, but the ask is small | `goal-creation --reference quick-discovery` — it names its own escalation trigger into the structured flow |
-| One platform, deeply (pedagogy, reviews) | `pipeline-platform-research --all-references` |
-| The kid, before any of the above | `student-research` |
-
-Research before you draft, not after. The spec's `handler.config` must arrive **fully materialized** —
-the apply endpoint never fetches anything, so whatever you did not bake in does not exist at apply
-time, and there is no later pass that fills it in.
-
-**If the request cannot be expressed by a supported handler, report that and stop.** The skill says
-this explicitly and it is the single most important instruction in it. A template that "sort of"
-does the job becomes a global record every future apply reads.
-
-## 1. Decide the kind before drafting
-
-`kind` is the real decision; `setupMode` is not a choice (see §5).
-
-| Kind | What a student gets | Use when |
-|---|---|---|
-| `SIMPLE` | a description-only goal plus linked todos — no modules, no Mesa workspace | ongoing habits, platform practice targets, score/streak goals, free-choice reading |
-| `BLUEPRINT` | a finishable learning path, built per student by the planner or copied from a snapshot | a course with a sequence and an end |
-
-The skill phrases this as a tutor-facing question with three options (the third, "Prebuilt", is a
-BLUEPRINT that also carries an instant-apply snapshot). You have no `ask_user_question` tool — ask
-the human directly, in the skill's language, and wait. Do not say "materialize",
-"module-backed", or "snapshot" to a tutor.
-
-A MODULE_BACKED spec **requires** `BLUEPRINT`; the server enforces it, and it additionally refuses to
-apply a MODULE_BACKED template that has no snapshot. Build a complete Mesa draft and capture it with
-the CLI workflow in §8 before applying the template.
-
-## 2. Write one template file
-
-`validate-spec` and `create` read the same document, so you iterate on one artifact:
-
-```jsonc
-{
-  "slug": "kebab-case-unique",          // required, immutable-ish: it is the human handle
-  "title": "Daily Reading Habit",       // required
-  "description": "One line a tutor reads in the library.",  // required
-  "kind": "SIMPLE",                     // SIMPLE | BLUEPRINT   (default SIMPLE)
-  "setupAudience": "KID_FRIENDLY",      // KID_FRIENDLY | PARENT_SETUP
-  "emoji": "📚",
-  "category": "reading",
-  "tags": ["reading", "ela"],           // an array, or a comma string
-  "sortOrder": 0,
-  "isStarter": false,
-  "agentInstructions": "…",             // required
-  "outputTemplate": "…",
-  "setupWorkflowSpec": { /* the fixed wizard — a real object, never a JSON string */ }
-}
-```
-
-Unknown keys are dropped, so a file made by editing `goal-templates get <id>` output works —
-`version`, `createdById`, `createdAt` are ignored rather than rejected. `setupMode` must be absent
-(or `DETERMINISTIC_WORKFLOW`); anything else is refused locally.
-
-## 3. Iterate on `validate-spec` — it writes nothing
-
-```bash
-recess --json goal-templates validate-spec --file ./template.json
-```
-
-Valid:
-
-```json
-{"ok":true,"data":{"slug":"…","kind":"SIMPLE","valid":true,
-  "setupHandler":"TOOL_GENERATED_TODO_SETUP","goalShape":"SIMPLE",
-  "stepKeys":["students"],"sha256":"…",
-  "totals":{"subjects":0,"recipes":0,"plans":0,"queueItems":0,"sourceUrls":0,"missingCoverage":0}}}
-```
-
-Invalid returns `"valid": false` with the backend's verbatim message — read it and fix the file.
-`ok` stays `true` because an invalid spec is an expected step in an authoring loop, not a failure of
-the command. Handler configs are `.strict()`, so a guessed config fails with both missing-field and
-`unrecognized_keys` errors at once; that is your cue to go back to
-`references/deterministic-workflow-setup.md` rather than guessing again.
-
-`stepKeys` is the contract for §6: those are exactly the keys your answers file must carry.
-
-## 4. Create — read the server-resolved preview
-
-```bash
-recess --json goal-templates create --file ./template.json          # preview, exit 2
-recess --json goal-templates create --file ./template.json --confirm
-```
-
-The unconfirmed run performs one read-only validation and puts its result in `preview.details`:
-
-| Field | Why it is in the approval request |
-|---|---|
-| `resolvedSetupHandler` | which handler actually runs — derived from the spec, not from what you wrote in the file |
-| `resolvedGoalShape` | `SIMPLE` vs `MODULE_BACKED`; decides whether a snapshot is required to apply |
-| `wizardStepKeys` | the questions a tutor will be asked, and the answer keys `apply` will demand |
-| `specInventory` | subjects / recipes / plans / queue items / source URLs the template starts with |
-
-Show all of it. `action` alone does not tell a human what the template does.
-
-If the spec is invalid at this point the command fails with `invalid_spec` and creates nothing —
-even with `--confirm`. That ordering is deliberate: an approved-but-broken template must not land.
-
-## 5. What is permanent
-
-**Every template created here is `setupMode: DETERMINISTIC_WORKFLOW` and cannot be converted back.**
-There is no AI_CHAT creation path and no downgrade — the server refuses the conversion outright.
-Legacy AI_CHAT templates remain readable and editable; you will never create one.
-
-So the confirmation gate carries more weight here than on a reversible write. What *is* recoverable:
-metadata (`set-metadata`) and the row itself (`delete` is a soft delete, and goals already applied
-from the template are unaffected).
-
-## 6. Apply to a kid or a roster
-
-Answers are a JSON file keyed by the spec's `stepKeys`:
-
-```jsonc
-{ "students": ["<kid-uuid>", "<kid-uuid>"], "grade": "5" }
-```
-
-```bash
-recess --json goal-templates apply <id-or-slug> --answers-file ./answers.json --dry-run
-recess --json goal-templates apply <id-or-slug> --answers-file ./answers.json            # preview
-recess --json goal-templates apply <id-or-slug> --answers-file ./answers.json --confirm
-```
-
-`--dry-run` is a read and does not gate. The unconfirmed form runs the same backend dry run to build
-its preview, so `details.counts` and `details.results` are the backend's own plan, per student:
-
-- `created` — a new goal + todo
-- `skipped_existing` — idempotent; re-applying does not duplicate
-- `error` — that student failed; the others still committed (failure is per item, never per batch)
-
-`details.missingCoverage` lists content the planner could not resolve. Surface it — an apply that
-"succeeded" with missing coverage produced a thinner goal than intended.
-
-`apply-starter` is the one-tap starter path: one template, one student, no dry run, so its preview is
-offline. It is gated per acting admin behind the `school-onboarding-v1` flag and **404s when the flag
-is off** — which reads like a missing template but is not.
-
-## 7. A goal directly on a kid
-
-```bash
-recess --json goals list --student <kid-id>
-recess --json goals create --student <kid-id> --title "…" --description-file ./goal.md --confirm
-```
-
-This creates a **description-only** goal: no GoalModules, no Mesa workspace. For a real course,
-apply a BLUEPRINT template instead. `--description-file` exists because a good goal description is
-long and prose-shaped; a shell mangles it.
-
-A 409 `GOAL_LIMIT_REACHED` means the kid is at capacity and nothing was created — do not retry, ask
-the human which goal to retire.
-
-Load `goal-creation` (and `student-research` to read the kid first) before writing the description.
-An unresearched goal is the failure mode this whole surface exists to prevent.
-
-## 8. Author, capture, and read workspaces
-
-For a new Prebuilt/instant-apply course, author the complete OS-V2 tree locally and upsert it into a
-named draft. The directory root becomes `drafts/<slug>/workspace` in the student's Mesa repo:
-
-```bash
-recess --json mesa files write --student <kid-id> --draft <draft-slug> --source-dir ./workspace
-# show the preview, obtain approval, then rerun unchanged:
-recess --json mesa files write --student <kid-id> --draft <draft-slug> --source-dir ./workspace --confirm
-
-recess --json goal-templates capture-snapshot <id-or-slug> --source-draft <draft-slug> --student <kid-id> --dry-run
-recess --json goal-templates capture-snapshot <id-or-slug> --source-draft <draft-slug> --student <kid-id>
-# show the preview, obtain approval, then rerun unchanged:
-recess --json goal-templates capture-snapshot <id-or-slug> --source-draft <draft-slug> --student <kid-id> --confirm
-```
-
-The draft must pass the full goal-builder contract: required top-level instructions, required fresh
-`state/` files, directory content, and at least one parseable runtime module. Capture validates that
-tree, then excludes `state/`, `conversations/`, and `.recess/` from the reusable snapshot. Its
-preview carries the template version, Mesa change id, module/file inventory, size, and SHA-256; the
-confirmed request is compare-and-set against both fences. If either changed, preview again and get
-fresh approval.
-
-Use `--source-file <local-file> --path <workspace-relative-path>` for one-file upserts. A live goal
-may be targeted with `--goal <goal-id>`, but the CLI rejects direct `modules/` and `state/` writes
-because those paths have database projections. Structural course changes belong in a draft, then a
-captured/applied template.
-
-An already-built OS-V2 goal can be captured directly:
-
-```bash
-recess --json goal-templates capture-snapshot <id-or-slug> --source-goal <goal-id> --dry-run
-```
-
-Read the resulting workspaces and snapshot with:
-
-```bash
-recess --json mesa files list --student <kid-id> --goal <goal-id>
-recess --json mesa files read --student <kid-id> --goal <goal-id> --path modules/01/index.md
-recess --json goal-templates snapshot-files <id-or-slug>
-recess --json goal-templates snapshot-files <id-or-slug> --path modules/01/index.md
-```
-
-`mesa files list` returning `{"files":[]}` means the goal has no Mesa workspace at all — expected for
-a SIMPLE goal, and the signal that a BLUEPRINT goal has not been built yet.
-
-## 9. Spec patches, metadata edits, and deletes are fenced
-
-```bash
-recess --json goal-templates get <id-or-slug>          # read `version`
-recess --json goal-templates patch-spec <id-or-slug> --expected-version 7 --patches-file ./patches.json
-recess --json goal-templates set-metadata <id> --expected-version 7 --title "…" --confirm
-recess --json goal-templates delete <id> --expected-version 7 --confirm
-```
-
-`--expected-version` is mandatory. A stale one returns 409 `STALE_WRITE` (server) or `stale_write`
-(the CLI's own pre-check) and **nothing is written** — re-read, rebuild the edit, and get a fresh
-approval. Never reuse an approval across a stale-write refresh.
-
-`patches.json` is a non-empty JSON array (maximum 50 operations) using `add`, `copy`, `replace`, and
-`remove` with RFC 6901 JSON Pointer paths. The unconfirmed command sends `dryRun:true` to the server,
-which applies the operations in memory, strict-validates the complete result, and returns
-`details.safety` with before/after hashes, inventory totals, removals, and (when destructive) a
-token. Show that exact preview to the human. After approval, rerun the same command with `--confirm`;
-if `destructiveChanges` is true, also pass `--confirm-destructive-changes` and the preview's exact
-`--destructive-change-token`. The confirmed run obtains a fresh preview before writing, and a stale
-version or token writes nothing.
-
-`set-metadata` cannot send a `setupWorkflowSpec` at all. Never replace a whole live spec through a
-generic update or raw request; `patch-spec` is the only CLI path for an existing spec.
-
-## Verify after every write
-
-```bash
-recess --json goal-templates get <id-or-slug>       # version bumped? metadata right?
-recess --json goal-templates versions <id-or-slug>  # a new frozen version row exists
-recess --json goals list --student <kid-id>         # the goal actually landed on the kid
-```