recess-cli 1.4.0 → 1.6.0

package/skill/recess-cli/reference/map-scores.md

@@ -1,28 +0,0 @@
-# MAP Growth report uploads
-
-Read [`../SKILL.md`](../SKILL.md) first — the safety model and escalation discipline there govern everything below.
-
-Resolve the kid with `users search`, then preview the exact local PDF before uploading it:
-
-```bash
-recess --json students upload-map-scores --student <kid-id> --file /path/to/map-report.pdf
-```
-
-The command accepts one non-empty PDF up to 15 MB (validated locally — wrong extension, missing file, empty file, and oversize all fail before any network call). Its no-write preview includes the resolved absolute path, filename, byte count, content type, and SHA-256; show all of that to the human so approval identifies the exact student and file. Only after explicit approval, rerun the unchanged command with `--confirm`.
-
-## Two valid outcomes
-
-The confirmed upload runs the existing tutor-dashboard AI extraction pipeline, so it can take **materially longer** than other admin writes — do not treat a slow response as a hang. The response distinguishes:
-
-- `kind: "scores"` — the route inserted measured MAP rows; report `inserted` and `scoreIds`.
-- `kind: "learning_statements"` — the PDF was a narrative NWEA Learning Statements/Continuum report with no measured RIT rows; **zero inserted scores is expected and is a success**, and `learningStatementFiles` names the Mesa files created for the tutor.
-
-## Verify
-
-For a score upload, verify the resulting rows through the allowed read-only escape hatch:
-
-```bash
-recess --json request get /tutor/students/<kid-id>/map-test-scores
-```
-
-Do not call the multipart route by hand, and do not treat a narrative report's zero inserted rows as failure.

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

@@ -1,79 +0,0 @@
-# Onboarding (family stage, account state, attestations, parent intake)
-
-Read [`../SKILL.md`](../SKILL.md) first — the safety model, escalation discipline, and input conventions there govern everything below.
-
-Onboarding tracks a family from provisioned kid accounts to a fully set-up, cohort-ready household. Each family carries an `onboardingStage`, an `accountState`, a four-condition attestation checklist, and a parent intake session that structured setup data is collected into. All nine commands are keyed on the **familyId** (not a kid or user id) — resolve it with `users search` first.
-
-## Resolve the family and read its state
-
-```bash
-recess --json users search "parent or kid name"
-recess --json onboarding status <family-id>
-```
-
-`onboarding status` is a read (no confirmation gate). It returns the current `onboardingStage`, `accountState`, `stageUpdatedAt`, the attestation `checklist` (each of `app_downloaded` / `tutor_met` / `goals_loaded` / `ma_diagnostic` with who attested and when), and per-kid setup signals (`activeGoalCount`, `appOpened`). Read it before any onboarding write so approvals name the exact starting state.
-
-```bash
-recess --json onboarding kids [--time-period-days N] [--cohort <id>] [--limit N] \
-  [--stage-filter all|scheduled|oriented|course|converted|lost]
-```
-
-`onboarding kids` is the legacy funnel list — recently-onboarding kids with their parent, engagement counts, membership/enrollment status, and highest funnel stage. It is a read; the flags map one-to-one onto the endpoint's query (`timePeriodDays`, `cohortId`, `limit`, `stageFilter`). The `stageFilter` funnel values (`scheduled`/`oriented`/`course`/`converted`/`lost`) are the legacy per-kid funnel, distinct from the family `onboardingStage` enum below.
-
-## The end-to-end order
-
-A family moves through setup roughly in this order; the attestation checklist mirrors it:
-
-1. **App downloaded** on the kid's device → `attest --condition app_downloaded`.
-2. **Tutor + guide met** the family (intro call / orientation) → `attest --condition tutor_met`, and the parent-intake session is where that call's notes get captured (`intake-session`, then `intake-session-create` if absent → `set-intake` / `extract`).
-3. **Goals loaded** for each kid → `attest --condition goals_loaded`.
-4. **Math Academy diagnostic** taken → `attest --condition ma_diagnostic`.
-
-The family `onboardingStage` is the coarse gate that advances alongside this:
-`LEGACY → PROVISIONED → PARENT_CONFIRMED → CLEARED_FOR_COHORT → COMPLETE`. `CLEARED_FOR_COHORT` is the one with a live capability effect — it unlocks cohort registration for school-partner families (`apps/web-server/src/libs/capabilities.ts`). `PARENT_CONFIRMED` reflects the parent confirming setup in-app.
-
-## Parent intake session (read/create → fill → confirm)
-
-```bash
-recess --json onboarding intake-session <family-id>
-recess --json onboarding intake-session-create <family-id> [--confirm]
-recess --json onboarding set-intake <family-id> --session <session-id> --data '<json>' [--expected-updated-at <iso>] [--confirm]
-recess --json onboarding extract <family-id> --session <session-id> \
-  (--transcript-file <path> | --granola <ref>) [--confirm]
-```
-
-- `intake-session` is a **read-only GET**: it returns the family's existing IN_PROGRESS session, or a clean "none yet" result when the route returns 404. It never creates a session (`get.family-intake-session.ts`).
-- `intake-session-create` is the explicit **confirmed write**: its POST returns the current IN_PROGRESS session or creates a fresh one when none exists (`post.family-intake-session.ts`). Run it only when the read reports no session, then use its `sessionId` for the fill commands.
-- `set-intake` **writes** the structured `collectedData` object for the session (PUT). `--data` is raw JSON — this is an agent-driven path (`--json`); a human rarely hand-writes the object. Invalid JSON fails locally as `invalid_arguments` before any network call; the preview shows the parsed object and does **zero** network I/O. The optimistic-concurrency token resolves only on `--confirm`, in two modes: pass `--expected-updated-at <iso>` (the `updatedAt` from an `intake-session` read) for **strict CAS** — a stale token 409s (surfaced as a non-zero-exit error) if a parent's confirm-flow autosave bumped the session since; **omit it** and the CLI fetches the current token at confirm time and prints a stderr warning that edits made since your preview are not protected. Use strict mode whenever you previewed against a specific read.
-- `extract` **writes** by running the intake transcript through Claude and merging the result into the session. Pass **exactly one** source — `--transcript-file <path>` (read locally into `transcript`) or `--granola <ref>` — both or neither fails as `invalid_arguments` before any network call. It is LLM-bound and can take ~30s; do not treat a slow response as a hang. A `503` means Granola is not configured server-side.
-
-The relationship: `intake-session` (read) → `intake-session-create` when absent → `set-intake` or `extract` (populate it) → the parent confirms setup in-app (which moves the stage toward `PARENT_CONFIRMED`).
-
-## Stage and account-state writes
-
-```bash
-recess --json onboarding set-stage <family-id> \
-  --stage LEGACY|PROVISIONED|PARENT_CONFIRMED|CLEARED_FOR_COHORT|COMPLETE [--confirm]
-recess --json onboarding set-account-state <family-id> \
-  --state ACTIVE|PENDING_PAYMENT|PAUSED|BOOTED [--note TEXT] [--confirm]
-```
-
-- `set-stage` reads the current stage first (one GET before the confirmation gate) so the preview names the transition (`target.from`) and warns when the move goes **backward** — a lower stage re-locks progress the family already passed, and the action string is prefixed `MOVE BACKWARD — re-locks progress`. Confirm backward moves deliberately; `CLEARED_FOR_COHORT` gating cohort registration means dropping below it removes that access.
-- `set-account-state` sets the family's billing/access posture. `PAUSED` and `BOOTED` **lock the family out of paid capabilities** — the preview spells this out; call it out in the approval request. `--note` is analytics-only (recorded, not shown to the family).
-
-## Attestations
-
-```bash
-recess --json onboarding attest <family-id> \
-  --condition app_downloaded|tutor_met|goals_loaded|ma_diagnostic [--revoke] [--note TEXT] [--confirm]
-```
-
-Marks (or, with `--revoke`, clears) one checklist condition. The preview action reads `attest <condition>` or `REVOKE attestation <condition>`. `--note` is passed through. Read `onboarding status` first to see which conditions are already attested and by whom.
-
-## Batch and verify
-
-Same discipline as the other domains: collect every planned write's preview without `--confirm`, present one batched approval that names the side effects (stage backward moves, PAUSED/BOOTED lockout, the ~30s LLM extract), rerun unchanged with `--confirm`, then re-read `onboarding status` to confirm the new stage / checklist / account state.
-
-## Out of scope
-
-There is no `mcp serve` mode and no server-side PAT path for these endpoints yet — the CLI drives them over the normal admin cookie session only. Kid provisioning, device pairing, and the in-app parent-confirmation UI stay in the product surfaces that own them.

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

@@ -1,74 +0,0 @@
-# Guide payout ops (biweekly changes)
-
-Read [`../SKILL.md`](../SKILL.md) first — the safety model, escalation discipline, and input conventions there govern everything below.
-
-Guides and program partners are paid through payout invoices: a biweekly pay run spawns one invoice per payout recipient account, most line items are generated automatically from Stripe payments or taught sessions, and the operations team applies a short instruction of manual changes each cycle ("CHANGES TO MAKE EVERY 2WKS: Add for X … Delete Y …"). Your job is to translate that instruction into exact CLI writes.
-
-## 1. Identify the pay cycle
-
-```bash
-recess --json payout payruns list --status IN_REVIEW,DRAFT,UPCOMING
-```
-
-Pay runs are named like "Biweekly: Jun 28, 2026 - Jul 12, 2026". Valid `--status` values: `UPCOMING, DRAFT, IN_REVIEW, APPROVED, PAID, CANCELED`. A recurring-changes instruction targets the run currently being prepared (usually IN_REVIEW or DRAFT) unless it names dates. If more than one run is plausible, ask the human which cycle they mean.
-
-## 2. Resolve each recipient
-
-```bash
-recess --json payout recipients list --search "Tom Bickmore"
-```
-
-- Instructions name people or programs. A person maps to an account like "Tom B.'s Payout Account"; a program ("Guild of Imagination") maps to a program account with no linked user.
-- A guide can have TWO accounts (a TAKE_RATE account and an HOURLY account), which means two invoices in the same run. When a search returns more than one account, inspect both invoices' line items to determine which one the instruction targets, and state which account you chose in the approval request.
-- Zero matches: stop and ask the human; never guess a similar name.
-
-## 3. Find and inspect the invoice before writing
-
-```bash
-recess --json payout invoices list --payrun <payrun-id> --recipient <account-id>
-recess --json payout invoices get <invoice-id>
-```
-
-`payout invoices list` requires at least one filter (`--payrun`, `--recipient`, `--user`, or `--status`). Check before every write:
-
-- The invoice status permits the operation: adding items requires DRAFT or IN_REVIEW; editing allows DRAFT, IN_REVIEW, or OPEN; deleting items requires DRAFT or IN_REVIEW.
-- `mayHaveDuplicates: true` means a Stripe payment already appears on another invoice — flag it to the human instead of ignoring it.
-
-## 4. Apply the changes
-
-```bash
-recess --json payout items add --invoice <id> --amount-cents 28800 \
-  --description "Recess+ for 8 kids at $18 2wks 2x$144" --confirm
-recess --json payout items edit <item-id> --amount-cents 4000 --confirm
-recess --json payout items delete <item-id> --confirm
-recess --json payout invoices set-status <invoice-id> --status CANCELED --confirm
-```
-
-Conventions that make the changes correct:
-
-- **Amounts are integer cents.** Parse dollar expressions yourself and cross-check any stated total: "2x$144 = $288" is one line item of 28800 cents unless the instruction clearly means separate items. If your arithmetic disagrees with a stated "= $X", surface the discrepancy instead of picking one.
-- **Descriptions**: reuse the instruction's wording, minus trailing arithmetic ("… 2x$53.20 = $106.40" → "… 2x$53.20"). The same items recur every cycle, and stable wording lets the next cycle's operator match them.
-- **Item date**: when the instruction gives no date, omit `--date`; the CLI defaults to the penultimate day of the invoice cycle (endDate minus one day) and shows the computed date in the preview (this default requires one read of the invoice before the confirmation gate — expected). Confirm it looks right. An explicit `--date` takes bare `YYYY-MM-DD` (anchored to UTC noon) or a full ISO timestamp.
-- **Edits only touch custom items.** `payout items edit` sets net = total (custom line items carry no platform fee); auto-generated Stripe/session items have different net semantics — don't edit them, flag them to the human.
-- **Recurring instructions**: "EVERY 2WKS" items are re-added fresh each cycle; there is no copy-forward mechanism. When an instruction is terse, read the previous run's invoice for the same recipient and mirror its amounts and descriptions.
-- **"Delete <person>"** means take the person off this cycle's payroll: cancel their invoice with `set-status --status CANCELED` (for example, a guide who moved to Deel). **"Delete <line item>"** means soft-delete one item with `payout items delete`. "Delete the first one" is ambiguous — list the invoice's items in order and confirm the target with the human before deleting.
-
-## 5. Status changes carry side effects
-
-`payout invoices set-status` previews spell these out; repeat them in the approval request:
-
-- `IN_REVIEW` moves the invoice into review.
-- `OPEN` finalizes: adds the invoice total to the recipient's running account balance.
-- `PAID` marks paid and deducts the total from the account balance.
-- `CANCELED` cancels the invoice and reverses balance items carried on it.
-- The guide email on `IN_REVIEW`/`OPEN` fires **only with `--send-email`** (default: no email). Follow the instruction: "finalize and notify" needs the flag; a quiet finalize omits it.
-- A `PAID` or `CANCELED` invoice is terminal — the server rejects any further status change (400).
-- Never finalize, mark paid, or cancel without an explicit instruction to do so.
-
-## 6. Batch the escalation, verify after
-
-For a multi-recipient instruction, first run every read, then run every write WITHOUT `--confirm` to collect previews, and present the complete per-recipient change plan (every add, edit, delete, and cancel with its preview) as ONE approval request. After approval, run each command unchanged with `--confirm`, then re-read each touched invoice with `payout invoices get` and verify the new `totalAmountCents` matches your arithmetic.
-
-## Out of scope
-
-Money movement and bulk pay-run lifecycle are deliberately not in the CLI: initiating Mercury payouts, advancing whole pay runs, and generating or regenerating invoices happen in the web admin at `/admin/payout`. If asked, direct the human there.