recess-cli 1.0.0

package/dist/config.js

@@ -0,0 +1,79 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+export const DEFAULT_OAUTH_CLIENT_ID = "c7e34138-18f9-45b1-a2fb-26a4e3a6d739";
+export function defaultConfigPath() {
+    return (process.env.RECESS_CLI_CONFIG ??
+        path.join(os.homedir(), ".recess-cli", "config.json"));
+}
+export async function readStoredConfig(configPath = defaultConfigPath()) {
+    try {
+        return JSON.parse(await fs.readFile(configPath, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return {};
+        throw error;
+    }
+}
+export async function resolveConfig() {
+    const configPath = defaultConfigPath();
+    const stored = await readStoredConfig(configPath);
+    const envCookie = process.env.RECESS_CLI_COOKIE;
+    const sessionCookie = envCookie ?? stored.sessionCookie;
+    return {
+        configPath,
+        apiOrigin: process.env.RECESS_CLI_API_ORIGIN ??
+            stored.apiOrigin ??
+            "https://api.recess.gg",
+        webOrigin: process.env.RECESS_CLI_WEB_ORIGIN ??
+            stored.webOrigin ??
+            "https://recess.gg",
+        oauthClientId: process.env.RECESS_CLI_OAUTH_CLIENT_ID ??
+            stored.oauthClientId ??
+            DEFAULT_OAUTH_CLIENT_ID,
+        sessionCookie,
+        sessionExpiresAt: stored.sessionExpiresAt,
+        user: stored.user,
+        authSource: envCookie ? "env" : sessionCookie ? "config" : "missing",
+        pendingDeviceCode: stored.pendingDeviceCode,
+        pendingUserCode: stored.pendingUserCode,
+        pendingApprovalUrl: stored.pendingApprovalUrl,
+        pendingExpiresAt: stored.pendingExpiresAt,
+    };
+}
+export async function writeStoredConfig(config, configPath = defaultConfigPath()) {
+    const directory = path.dirname(configPath);
+    await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+    const temporary = `${configPath}.${process.pid}.tmp`;
+    await fs.writeFile(temporary, `${JSON.stringify(config, null, 2)}\n`, {
+        mode: 0o600,
+    });
+    await fs.rename(temporary, configPath);
+    await fs.chmod(configPath, 0o600);
+}
+export async function updateStoredConfig(update) {
+    const configPath = defaultConfigPath();
+    const current = await readStoredConfig(configPath);
+    const next = { ...current, ...update };
+    await writeStoredConfig(next, configPath);
+    return next;
+}
+export async function clearStoredSession() {
+    const configPath = defaultConfigPath();
+    const current = await readStoredConfig(configPath);
+    delete current.sessionCookie;
+    delete current.sessionExpiresAt;
+    delete current.user;
+    await writeStoredConfig(current, configPath);
+}
+export async function clearPendingDeviceAuth() {
+    const configPath = defaultConfigPath();
+    const current = await readStoredConfig(configPath);
+    delete current.pendingDeviceCode;
+    delete current.pendingUserCode;
+    delete current.pendingApprovalUrl;
+    delete current.pendingExpiresAt;
+    await writeStoredConfig(current, configPath);
+}
+//# sourceMappingURL=config.js.map

package/dist/errors.js

@@ -0,0 +1,18 @@
+export class CliError extends Error {
+    code;
+    exitCode;
+    details;
+    constructor(code, message, exitCode = 1, details) {
+        super(message);
+        this.code = code;
+        this.exitCode = exitCode;
+        this.details = details;
+    }
+}
+export function apiError(status, body) {
+    const message = typeof body === "object" && body && "message" in body
+        ? String(body.message)
+        : `Recess API request failed with status ${status}`;
+    return new CliError("api_error", message, 1, { status, body });
+}
+//# sourceMappingURL=errors.js.map

package/dist/index.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import { runCommand } from "./cli.js";
+import { CliError } from "./errors.js";
+const json = process.argv.slice(2).includes("--json");
+try {
+    const data = await runCommand(process.argv.slice(2));
+    if (typeof data === "object" && data && "help" in data && !json) {
+        process.stdout.write(`${String(data.help)}\n`);
+    }
+    else if (json) {
+        process.stdout.write(`${JSON.stringify({ ok: true, data })}\n`);
+    }
+    else {
+        process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+    }
+}
+catch (error) {
+    const cliError = error instanceof CliError
+        ? error
+        : new CliError("unexpected_error", error instanceof Error ? error.message : String(error));
+    if (json) {
+        process.stdout.write(`${JSON.stringify({
+            ok: false,
+            error: {
+                code: cliError.code,
+                message: cliError.message,
+                ...(cliError.details === undefined
+                    ? {}
+                    : { details: cliError.details }),
+            },
+        })}\n`);
+    }
+    else {
+        process.stderr.write(`Error: ${cliError.message}\n`);
+        if (cliError.details) {
+            process.stderr.write(`${JSON.stringify(cliError.details, null, 2)}\n`);
+        }
+    }
+    process.exitCode = cliError.exitCode;
+}
+//# sourceMappingURL=index.js.map

package/dist/safety.js

@@ -0,0 +1,7 @@
+import { CliError } from "./errors.js";
+export function requireConfirmation(confirmed, preview) {
+    if (confirmed)
+        return;
+    throw new CliError("confirmation_required", "This admin action is a live write. Review the preview, obtain explicit human approval, then rerun with --confirm.", 2, { preview, requiredFlag: "--confirm" });
+}
+//# sourceMappingURL=safety.js.map

package/dist/setup.js

@@ -0,0 +1,43 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const here = path.dirname(fileURLToPath(import.meta.url));
+/** Bundled skill source: `<package>/skill/recess-cli`, from `dist/` or `src/`. */
+const skillSource = path.resolve(here, "..", "skill", "recess-cli");
+/**
+ * Skill directories from earlier names of this CLI. An agent that finds both
+ * would read two overlapping skills describing a command that no longer exists,
+ * so setup removes them.
+ */
+const SUPERSEDED_SKILL_DIRECTORIES = ["recess-admin"];
+export async function installSkill() {
+    const codexHome = process.env.CODEX_HOME ?? path.join(os.homedir(), ".codex");
+    const claudeHome = process.env.CLAUDE_CONFIG_DIR ?? path.join(os.homedir(), ".claude");
+    const destinations = [
+        { agent: "Codex", path: path.join(codexHome, "skills", "recess-cli") },
+        { agent: "Claude", path: path.join(claudeHome, "skills", "recess-cli") },
+    ];
+    for (const destination of destinations) {
+        const skillsRoot = path.dirname(destination.path);
+        await fs.mkdir(skillsRoot, { recursive: true });
+        await fs.rm(destination.path, { recursive: true, force: true });
+        await fs.cp(skillSource, destination.path, { recursive: true });
+        for (const superseded of SUPERSEDED_SKILL_DIRECTORIES) {
+            await fs.rm(path.join(skillsRoot, superseded), {
+                recursive: true,
+                force: true,
+            });
+        }
+    }
+    return destinations;
+}
+/**
+ * True when this process is running from a throwaway `npx` cache rather than a
+ * real install. The bundled skill tells the agent to run `recess ...`, so
+ * an npx-only setup leaves the skill pointing at a command that is not on PATH.
+ */
+export function isEphemeralInstall() {
+    return here.includes(`${path.sep}_npx${path.sep}`);
+}
+//# sourceMappingURL=setup.js.map

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "recess-cli",
+  "version": "1.0.0",
+  "description": "Safe Recess staff administration from the command line, for humans and coding agents.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": {
+    "recess": "dist/index.js"
+  },
+  "files": [
+    "dist/**/*.js",
+    "!dist/**/*.test.js",
+    "skill",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "openapi-fetch": "^0.14.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.0",
+    "@typescript/native-preview": "7.0.0-dev.20251015.1",
+    "openapi-typescript": "^7.8.0",
+    "oxlint": "^1.28.0",
+    "oxlint-tsgolint": "^0.6.0",
+    "typescript": "^5.9.2",
+    "vitest": "^1.6.0",
+    "@tryrecess/typescript-config": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "client:generate": "node scripts/generate-api-types.mjs",
+    "typecheck": "tsgo --noEmit",
+    "format": "oxfmt --ignore-path .oxfmtignore --check",
+    "format:fix": "oxfmt --ignore-path .oxfmtignore",
+    "lint": "oxlint --type-aware src/*.ts",
+    "lint:fix": "oxlint --type-aware --fix src/*.ts",
+    "test": "vitest run",
+    "install-local": "pnpm run build && make install-local",
+    "install-persistent": "pnpm run build && make install-persistent",
+    "install-skill": "pnpm run build && node scripts/install-skill.mjs"
+  }
+}

package/skill/recess-cli/SKILL.md

@@ -0,0 +1,290 @@
+---
+name: recess-cli
+description: Safely perform Recess staff administration through the recess CLI. Use when a Recess admin asks Codex to find a kid, parent, family, enrollment, subscription, invoice, or cohort; inspect or change a school kid's tier and capability gates; upload a kid's MAP Growth report; pause or resume billing; refund or credit an invoice item; extend a trial; cancel or restore a subscription; register or unregister a cohort against an enrollment; switch or move kids from one cohort to another; manage guide payout invoices (biweekly pay-cycle line-item changes, invoice status moves, payout recipient lookups); run class operations (take attendance, cancel or reschedule a class session, add a one-off session, end a cohort, pause cohort billing, email a cohort's families, approve or deny pending registrations); or process class-cancellation credits (the "Please credit these students accordingly" Slack message — credit every registered kid for a guide-canceled session).
+---
+
+# Recess CLI (`recess`)
+
+Use the installed `recess` command. Never bypass it with direct production database writes, Stripe calls, browser clicks, or hand-written API requests. Every command here operates on **live production data — real families, real kids, real money.**
+
+> **Maintain this skill.** Every time you discover a new failure mode, a working invocation, or a surprising behavior, add it to the "Gotchas" notebook at the bottom (append-only, dated). When a whole workflow changes, update the matching playbook in `reference/`. The skill's source of truth lives in the monolith at `apps/admin-cli/skill/recess-cli/` — fix it there, then reinstall (`pnpm --dir apps/admin-cli run install-skill`) — the published npm package ships the same bundle, so a skill change reaches non-checkout installs only on the next `recess-cli` release.
+
+## The safety model — non-negotiable
+
+Every mutating command is two-step. Run it **without** `--confirm` first: the CLI returns `confirmation_required` (exit code 2) plus the exact `action`, `target`, and `request` body it would send, and makes **no network write**.
+
+Some previews also carry a `details` object — server-resolved facts that cannot be known offline.
+Today those are `enrollments create` (real price, no-charge reuse, and capacity/slot violations) and
+`users tier set` (current/proposed capability locks and class-slot consequences); getting either
+costs read-only calls, never a write. **When `details` is present it is part of the preview — show it
+to the human too.** Approving from `action`/`request` alone while ignoring `details` is how an
+override gets rubber-stamped.
+
+1. Show that preview to the human, verbatim.
+2. Request explicit escalated approval for that exact action using the execution tool's approval mechanism.
+3. Only after the human approves, rerun the **unchanged** command with `--confirm`.
+
+Never infer approval from the original task, prior approval, urgency, or a successful read. Never add `--confirm` yourself before the approval arrives. If any ID, amount, refund method, payer, pause date, or target changes, discard the approval and preview again.
+
+**Exceptional actions** get named explicitly in the approval request, on top of the normal preview:
+
+| Flag / command | Why it is exceptional |
+|---|---|
+| `enrollments create` | **charges a real family real money.** Quote `details.billing.effectivePriceCents` (the discounted amount actually billed, NOT `listPriceCents`), the recurrence, and the first-charge date in the approval request |
+| `enrollments create --force` | overrides a cohort-capacity or school-class-slot violation; name the specific warning being overridden |
+| `users tier set --allow-strand` | lowers a kid's class allowance below active registrations; quote `slotsUsed`, the proposed allowance, and both capability-lock lists |
+| `billing cancel-subscription --immediate` | no period-end grace — access ends now |
+| `invoices refund … --who-pays recess` | Recess absorbs the cost instead of the guide |
+| `cohorts end --cancel-subscriptions` | sets EVERY active enrollment's Stripe subscription to cancel at period end |
+| `cohorts email` | real outward email blast to families (include the recipient count from `cohorts parent-emails`) |
+| `events cancel` | family-facing fan-out: chat messages, parent email blast, credit-owed notes, Slack |
+| `payout invoices set-status` to `OPEN`/`PAID`/`CANCELED` | moves real account balances; `--send-email` additionally emails the guide |
+
+## Setup, auth, and troubleshooting
+
+- Binary: `recess` (published on npm as `recess-cli`). The standard install needs no monolith checkout — `npm install -g recess-cli` then `recess setup` (installs this skill for Codex and Claude, then opens SSO). From a checkout, `pnpm --dir apps/admin-cli run install-persistent` builds a self-contained copy under `~/.recess-cli/cli/` linked from `~/.local/bin/recess`; `install-local` symlinks the checkout's live `dist/` instead — CLI-development only, and the link dies with its worktree.
+- Session: a **12-hour** signed admin cookie stored at `~/.recess-cli/config.json` (mode 0600). It is **not refreshable** — when it expires, a human must approve a fresh sign-in. On a headless agent, use `auth request` + `auth poll`; on a local workstation, `auth login` remains available.
+- Start every session with:
+
+  ```bash
+  command -v recess
+  recess --json doctor
+  ```
+
+  `doctor` reports the config paths/origins, the auth state (it validates the stored session against `GET /auth/admin-cli/session/`), and API reachability (`/health`). Interpret it before running anything else.
+- If auth is missing or expired on a headless agent, start a device-authorization request:
+
+  ```bash
+  recess --json auth request --label "<agent or VM name>"
+  ```
+
+  Show the returned `approvalUrl` and `userCode` to the human. The secret device code stays only in the mode-0600 config file and must never be copied into chat or logs. After the human approves the web page, collect the session:
+
+  ```bash
+  recess --json auth poll --timeout 300
+  ```
+
+  A timed-out poll preserves the pending request, so it is safe to rerun after approval. A denied, expired, or already-used request needs a fresh `auth request`.
+
+- On a workstation with a browser, the human can instead complete:
+
+  ```bash
+  recess --json auth login          # uses the built-in production OAuth client
+  ```
+
+  The login opens a browser to Recess SSO and listens on `127.0.0.1:8765` (5-minute timeout). A non-default `--callback-port` only works if that exact loopback URL is registered on the OAuth client — otherwise production rejects the redirect.
+- `auth status` shows the current session and whether it came from the env or the config file; `auth logout` clears the stored session.
+
+Environment overrides (all optional): `RECESS_CLI_API_ORIGIN` (default `https://api.recess.gg`), `RECESS_CLI_WEB_ORIGIN` (default `https://recess.gg`), `RECESS_CLI_OAUTH_CLIENT_ID` (overrides the built-in production client for local/staging), `RECESS_CLI_COOKIE` (session override, wins over the config file), `RECESS_CLI_CONFIG` (config path). Pointing `RECESS_CLI_API_ORIGIN` at a local server is how dev/testing works; if it is set, you are NOT talking to production — say so in previews.
+
+Auth failure modes:
+
+| Error code | Meaning | Fix |
+|---|---|---|
+| `auth_required` | no stored session | headless: `auth request` + human approval + `auth poll`; workstation: `auth login` |
+| `api_error` with 401 on any command | session expired or revoked | acquire a fresh session through the same headless or workstation flow |
+| `callback_unavailable` | port 8765 already in use | free the port or use a registered `--callback-port` |
+| `auth_timeout` / `auth_failed` | SSO not completed in 5 min / denied | retry the login in the browser |
+
+## The JSON contract
+
+Always pass `--json` (it may appear anywhere in the argv). Stdout then carries exactly one JSON object:
+
+- Success: `{"ok":true,"data":{…}}` — exit code 0.
+- Failure: `{"ok":false,"error":{"code":"…","message":"…","details":{…}}}` — exit code 1.
+- Write awaiting approval: code `confirmation_required`, `details.preview` = `{action,target,request}` (plus `details` on commands with server-resolved facts, e.g. `enrollments create`), `details.requiredFlag` = `--confirm` — **exit code 2**.
+
+Without `--json`, success pretty-prints to stdout but errors go to **stderr** as text — so agents use `--json` unconditionally. Error codes you will see: `invalid_arguments`, `auth_required`, `not_found`, `api_error` (carries `details.status` and the raw API `details.body`), `confirmation_required`, `unknown_command`, `unexpected_error`, plus the auth codes above.
+
+## Input conventions
+
+- **Money is integer cents**, always (`--amount-cents 28800` = $288.00). Parse dollar expressions yourself; never send fractional values.
+- **Three date shapes, not interchangeable:**
+  - `--until` / `--trial-end`: ISO date, must be in the future (`2026-09-01`).
+  - Payout item `--date`: bare `YYYY-MM-DD` (anchored to UTC noon so the calendar day survives timezone conversion) or a full ISO timestamp.
+  - Event `--starts-at`: **zoneless** cohort-local wall clock, `YYYY-MM-DDTHH:MM` — a timezone offset is rejected. "3pm" means `15:00` in the cohort's timezone.
+- **ID and status lists are comma-separated:** `--attended id1,id2` · `--status IN_REVIEW,DRAFT`.
+- Search queries are positional and may span words: `recess --json users search Morgan Rivera` works, quotes optional.
+- **Flag parser traps:** `--flag value` and `--flag=value` are both accepted, but a value that itself starts with `--` MUST use the `=` form (`--content="-- headline --"`), or it is parsed as another flag. Misspelled flags are not rejected — an unknown `--flag` silently swallows the next token, and the real flag then errors as "Missing required". On any confusing `invalid_arguments`, re-check flag spelling first.
+
+## The standard loop (reads resolve before writes)
+
+1. **Resolve names to IDs.** `users search` returns the matching people, their family, every family member, and each member's enrollments and cohort registrations. Never act on a guessed ID; stop on ambiguous matches and ask the human which family or user they mean.
+
+   ```bash
+   recess --json users search "parent or kid name"
+   recess --json enrollments list --user <kid-id>
+   ```
+
+2. **Read the exact current state** before proposing any write (playbooks list the reads per workflow).
+3. **Collect previews** by running every planned write WITHOUT `--confirm`.
+4. **Batch the escalation:** present the complete change plan — every preview, every side effect (emails, Stripe changes, notifications), every exceptional flag — as ONE approval request.
+5. **Execute confirmed:** rerun each command unchanged with `--confirm`.
+6. **Verify:** re-read the touched resources (`payout invoices get`, `events get`, `cohorts get`, `invoices list`, …) and check the new state matches the plan. Report the final API responses.
+
+## Command quick reference
+
+```bash
+# Health & auth
+recess --json doctor
+recess --json auth login|status|logout
+
+# People & enrollment context
+recess --json users search <name-or-id> [--limit 10]
+recess --json users get <user-id>
+recess --json users tier list-tiers
+recess --json users tier get <kid-id>
+recess --json users tier preview <kid-id> --tier <id> [--slots N]
+recess --json users tier set <kid-id> --tier <id> [--slots N] \
+  --expected-updated-at <iso> [--allow-strand] [--confirm]
+recess --json enrollments list --user <user-id>
+recess --json enrollments get-for-subscription --subscription <id>
+
+# Billing & subscriptions (reference/billing.md)
+recess --json subscriptions list --family <family-id> [--kid <kid-id>]
+recess --json invoices list --subscription <subscription-id>
+recess --json billing pause --subscription <id> [--until ISO_DATE] [--confirm]
+recess --json billing resume --subscription <id> [--confirm]
+recess --json billing extend-trial --subscription <id> --trial-end ISO_DATE [--confirm]
+recess --json billing cancel-subscription --subscription <id> [--immediate] [--reason TEXT] [--restore] [--confirm]
+recess --json invoices refund --invoice <id> --line-item <id> --method refund|credit|tokens \
+  [--full | --amount-cents N] [--who-pays guide|recess] [--reason TEXT] [--confirm]
+recess --json enrollments create --user <kid-id> --cohort <id> \
+  [--first-charge-at ISO_DATETIME] [--send-email] [--force] [--confirm]
+recess --json enrollments register-cohort --enrollment <id> --user <id> --cohort <id> [--confirm]
+recess --json enrollments unregister-cohort --user <id> --cohort <id> [--confirm]
+
+# MAP Growth reports (reference/map-scores.md)
+recess --json students upload-map-scores --student <kid-id> --file <report.pdf> [--confirm]
+
+# Guide payouts (reference/payout.md)
+recess --json payout payruns list [--status A,B] [--schedule <id>]
+recess --json payout recipients list [--search <name>] [--user <id>] [--id <id>]
+recess --json payout invoices list [--payrun <id>] [--recipient <account-id>] [--user <id>] [--status A,B]
+recess --json payout invoices get <invoice-id>
+recess --json payout invoices set-status <invoice-id> --status IN_REVIEW|OPEN|PAID|CANCELED [--send-email] [--confirm]
+recess --json payout items add --invoice <id> --amount-cents N --description TEXT [--date YYYY-MM-DD] [--confirm]
+recess --json payout items edit <item-id> [--amount-cents N] [--description TEXT] [--date YYYY-MM-DD] [--confirm]
+recess --json payout items delete <item-id> [--confirm]
+
+# Class ops (reference/class-ops.md)
+recess --json cohorts search <query>
+recess --json cohorts get <cohort-id> [--events-tab ACTIVE|ENDED|CANCELED|ARCHIVED]
+recess --json cohorts parent-emails <cohort-id>
+recess --json cohorts end <cohort-id> [--cancel-subscriptions] [--confirm]
+recess --json cohorts pause-billing <cohort-id> --weeks 1..6 [--confirm]
+recess --json cohorts resume-billing <cohort-id> [--confirm]
+recess --json cohorts email <cohort-id> --target ALL_PARENTS|ALL_PARENTS_GUIDES --content TEXT [--confirm]
+recess --json events get <event-id>
+recess --json events take-attendance <event-id> --attended <ids> [--absent <ids>] [--excused <ids>] [--confirm]
+recess --json events cancel <event-id> --reason TEXT [--confirm]
+recess --json events set-status <event-id> --status ACTIVE|ENDED|CANCELED [--confirm]
+recess --json events reschedule --cohort <id> --event <id> --starts-at "YYYY-MM-DDTHH:MM" [--timezone <iana>] [--length-mins N] [--confirm]
+recess --json events add --cohort <id> --starts-at "YYYY-MM-DDTHH:MM" [--timezone <iana>] [--length-mins N] [--confirm]
+recess --json registrations approve --registration <id> [--confirm]
+recess --json registrations deny --cohort <id> --user <id> [--confirm]
+
+# Onboarding (reference/onboarding.md) — all keyed on family-id
+recess --json onboarding status <family-id>
+recess --json onboarding kids [--time-period-days N] [--cohort <id>] [--limit N] [--stage-filter all|scheduled|oriented|course|converted|lost]
+recess --json onboarding intake-session <family-id>
+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]
+recess --json onboarding attest <family-id> --condition app_downloaded|tutor_met|goals_loaded|ma_diagnostic [--revoke] [--note TEXT] [--confirm]
+recess --json onboarding set-intake <family-id> --session <id> --data <json> [--expected-updated-at <iso>] [--confirm]
+recess --json onboarding extract <family-id> --session <id> (--transcript-file <path> | --granola <ref>) [--confirm]
+
+# Read-only escape hatch (GET only — no raw writes exist)
+recess --json request get /path?query=value
+```
+
+### School tier contract
+
+`users tier get` is the read-before-write source: copy its `updatedAt` into
+`--expected-updated-at`, then run `preview` (or the unconfirmed `set`) with the intended tier and
+slot override. Show the human `slotsUsed`, the proposed allowance,
+`capabilitiesLockedNow`/`capabilitiesLockedAfter`, `wouldStrandRegistrations`, and `enforcementOn`.
+Tier names are not a capability ladder: with enforcement on, `social` (and an unassigned tier)
+locks `todo`, `browser`, and `tutor_chat`; the other four canonical tiers lock none. With
+`enforcementOn:false`, the row still changes but the kid observes no capability change until the
+`school-onboarding-v1` flag turns on. Never infer lock consequences from the tier name.
+
+The CLI refuses `wouldStrandRegistrations:true` by default. `--allow-strand` is an exceptional
+override, not a retry hint: use it only after the human explicitly approves leaving more active
+registrations than class slots. A 409 `STALE_WRITE` means the kid changed after the read; fetch a new
+token, preview again, and discard the old approval.
+
+## Workflow playbooks
+
+Each domain has a full playbook in this skill's `reference/` directory. Read the matching one BEFORE running that domain's writes — they carry the semantics that make the writes correct (which command notifies families, how amounts are computed, which statuses permit which operations).
+
+| Task | Playbook |
+|---|---|
+| **Signing a kid up for a class / enrolling / "add them to this cohort" / "the parent wants to buy X"**, subscriptions, pauses, trials, cancellations, refunds/credits/token refunds, cohort register/unregister, moving kids between cohorts | [`reference/billing.md`](reference/billing.md) |
+| MAP Growth report uploads | [`reference/map-scores.md`](reference/map-scores.md) |
+| Guide payout invoices — the biweekly "CHANGES TO MAKE EVERY 2WKS" instruction | [`reference/payout.md`](reference/payout.md) |
+| Attendance, class cancellations, reschedules, one-off sessions, cohort lifecycle, cohort email, registration approvals | [`reference/class-ops.md`](reference/class-ops.md) |
+| Class-cancellation credits — the "Please credit these students accordingly" Slack workflow | [`reference/cancellation-credits.md`](reference/cancellation-credits.md) |
+| Non-flexible course one-off time shift when `events reschedule` 400s (`allowFlexibleScheduling: false`) | [`reference/class-ops-reschedule.md`](reference/class-ops-reschedule.md) |
+| Family onboarding — stage, account state, attestation checklist, parent intake session (fill / LLM-extract) | [`reference/onboarding.md`](reference/onboarding.md) |
+
+## Deliberately out of scope
+
+These are excluded from the CLI on purpose. If asked, direct the human to the web admin — do not improvise around the gap.
+
+- **Any raw write:** there is no `request post/put/patch/delete`. `request get` exists only for read-only endpoints missing a high-level command.
+- **Money movement:** initiating Mercury payouts, advancing whole pay runs, generating/regenerating payout invoices → `/admin/payout` in the web admin.
+- **Enrollment cancellation** as a standalone action (`unregister-cohort` deliberately preserves the enrollment; only `registrations deny` cancels one, because that is what the web Deny button does).
+- **Cohort creation and schedule editing:** create, start, full-edit/RRULE regeneration, generate-events, guides management → web admin cohort pages.
+
+## Guardrails
+
+- Use `--json` for analysis and preserve the CLI's stable JSON envelope.
+- Treat the exceptional actions table above as mandatory callouts in every approval request.
+- For `users tier set`, quote capability lock lists rather than describing one tier as "higher" or
+  "lower"; the mapping is binary and flag-gated. Never reuse an approval after a stale-write refresh.
+- `unregister-cohort` leaves the enrollment active; never substitute enrollment cancellation (or vice versa — see `registrations deny`).
+- **`enrollments create` vs `enrollments register-cohort` — pick wrong and you either double-charge a family or do nothing.** `create` sells a class: it makes a *new* Stripe subscription and charges the family. `register-cohort` only links a kid to a cohort against an enrollment they **already** hold, and moves no money. If the family is already paying for this course and you just need the kid in a cohort (a move, a swap, a slot they already bought), use `register-cohort`. Use `create` only when they are genuinely buying something new. When unsure, run `enrollments create` unconfirmed and read `details.reusedEnrollmentId`: if it is set, the kid already had a paid slot and `create` will correctly charge nothing — that is also your signal that `register-cohort` would have been the direct route.
+- `enrollments create` is the ONLY command that spends a family's money. Its unconfirmed run performs a server-side dry run and returns the real resolved price, so never quote a price from the course catalog or from memory — quote `details.billing.effectivePriceCents` — the post-discount amount, never `listPriceCents` — and mention `creditBalanceCents` when non-zero, since credits reduce the first invoice further. If `details.reusedEnrollmentId` is set, say plainly that nothing will be charged.
+- `enrollments create` replaces impersonating a guardian and walking their checkout. Never suggest impersonation to sign a kid up.
+- Never retry `enrollments create` after an `ENROLLMENT_PROVISION_FAILED` error. The Stripe subscription already exists; retrying sells a second one. Escalate to engineering with the subscription ID from the error message.
+- Stop on ambiguous search results and ask the human which family or user they mean.
+- Report the final API response and re-read the affected resource when a read command can verify the new state.
+
+## Gotchas (append-only lab notebook)
+
+Dated, newest last. Add an entry every time reality surprises you.
+
+- 2026-07-16 — Flag parser: an unknown/misspelled `--flag` is not rejected — it silently swallows the next token as its value, and the real flag then errors "Missing required --…". Check flag spelling first on weird `invalid_arguments`.
+- 2026-07-16 — Values starting with `--` (e.g. email content beginning with a dash run) must use `--flag=value` form; the space form parses the value as a new flag.
+- 2026-07-16 — `enrollments list --user <id>` is operations-search under the hood with the ID as the search term; an ID that search can't find returns `not_found` even if the user exists but is outside the search surface.
+- 2026-07-16 — `payout items add` without `--date` performs one READ before the confirmation gate (fetches the invoice to compute the default item date: endDate − 1 day). Expected; not a write.
+- 2026-07-16 — MAP uploads run the full AI extraction pipeline server-side and can take materially longer than other writes; don't treat a slow response as a hang. `kind:"learning_statements"` with zero inserted scores is a SUCCESS (narrative NWEA report → Mesa files), not a failure.
+- 2026-07-16 — The 12h session is not refreshable and login is browser-interactive; an agent can never self-heal auth. Hand `recess --json auth login` to the human and wait.
+- 2026-07-16 — `events reschedule` returning 409 means the target slot already has an event. Only flexible-scheduling courses and ACTIVE events can be rescheduled.
+- 2026-07-16 — `events take-attendance` stamps `attendanceTakenAt` with the current time automatically; there is no back-dating flag.
+- 2026-07-16 — `payout items edit --amount-cents` sets net = total (custom items carry no platform fee). Editing an auto-generated (non-custom) item with it would overwrite net semantics — only edit custom line items.
+- 2026-07-16 — `request get` requires a path starting with exactly one `/`; `//host` forms are rejected (SSRF guard).
+- 2026-07-16 — Payout guide emails on `set-status IN_REVIEW|OPEN` fire only with `--send-email` (server default false; suppressed on staging regardless). PAID and CANCELED invoices are terminal — the server 400s any later status change.
+- 2026-07-17 — `billing pause` always uses Stripe `pause_collection.behavior="void"`: invoices generated during the pause are VOIDED (family never charged), never deferred for later collection; access is unaffected. Weekly subscriptions bill on Sunday-00:00 (server/UTC) anchors, so `--until` (bare date → midnight UTC = the Stripe `resumes_at`) voids every Sunday tick strictly before it and charges the first tick at/after it. Pick a mid-week `--until` between the last Sunday to skip and the next one to charge. Full rules: `reference/billing.md` § Pause timing semantics.
+- 2026-07-17 — Per-subscription `billing pause` writes only to Stripe; `Enrollment.pausedAt`/`pauseResumesAt` stay null (only `cohorts pause-billing` stamps them). Verify via `subscriptions list`, never the enrollment row.
+- 2026-07-17 — `billing pause`/`resume --confirm` returns `api_error` with `details.status: 200` even on SUCCESS: the server route (`post.pause-collection.ts`) does the Stripe update but never sends its declared `{success:true}` body, so the CLI rejects the empty 200. The write has landed — verify with `subscriptions list` (`pause_collection` + `pause_collection_resume_at`) instead of retrying blind. (Route patched 2026-07-17 to send the body; the false error persists until that deploys.) **RESOLVED 2026-07-20** — the patch is live in prod; `billing pause --confirm` now returns a clean `{"ok":true,"data":{"success":true}}`. Verify-after-write still applies, but an `api_error` here is now a real failure, not the known false alarm.
+- 2026-07-17 — Before any refund/credit, read the invoice's payment composition from `invoices list` (`token_deduction_cents`, `applied_balance`, `amount` vs `subtotal`, `paymentIntent.status`) and state it in the approval request — token-paid portions go back as `--method tokens`, balance-covered portions mean a "full" cash refund over-refunds. Checklist in `reference/billing.md`.
+- 2026-07-17 — The cancellation Slack message's "Registered students" list is a cancel-time snapshot and can under-report: a kid registered since 2025 and invoiced for the canceled week was absent from it (Honey Squad, 7/16). Build the roster live from the cohort's REGISTERED registrations when processing credits (`reference/cancellation-credits.md`).
+- 2026-07-17 — Mixed-composition invoices (tokens + cash) need TWO refund commands, one per portion; observed a manual pass refund the $4 token portion of a $15 line and miss the $11 cash portion. Skip kids whose line already shows `credited_amount`/`token_refunded_cents` > 0 — the manual process runs days late and may race you.
+- 2026-07-17 — Stripe invoice IDs can share their first ~18 chars within the same week (`in_1TsAobBBeAjEgjlseDHTGOT1` vs `in_1TsAobBBeAjEgjlsHynCvkUi`) — never prefix-match invoice/line IDs; compare in full.
+- 2026-07-17 — `register-cohort` enforces cohort capacity server-side (400 `RA_REG_NOT_ALLOWED` "This cohort is at capacity") — the admin quiet-link path does NOT bypass it, and capacity editing is out of CLI scope (web admin). Before a batch cohort move, compare `cohorts get` `capacity` against incoming headcount; register-first/unregister-second per kid means a capacity failure leaves that kid safely in the old cohort.
+- 2026-07-17 — Signup billing shape: a new class signup creates an IMMEDIATE real invoice (backdated to the last Sunday anchor — line reads "Time on <course> from <Sun> until <Sun>", often with a first-week coupon) plus a $0 "Trial period" invoice; the "trial" is an anchor-reset bridge to Sunday billing (`apps/web-server/src/libs/stripe/create-subscription.ts`), NOT a free period. A recently signed-up kid can be `status: trialing` with `trial_end` a Sunday 1–2 weeks out, so a given session week may legitimately have NO invoice (family genuinely not charged) even though the kid paid the immediate invoice for an earlier week. Same-cohort same-week signups can differ (observed: one kid trial_end 7/12 and charged $25 for the 7/12 week; another trial_end 7/19, never charged for it). Before refunding a session for a new signup, read `subscriptions list` `trial_end` to learn which week each invoice actually covers — don't map "Trial period invoice" to "never paid" or the immediate invoice to the current week.
+- 2026-07-18 — An `install-local` symlink dies when its source worktree is deleted: every invocation exits 127 "no such file or directory". Fix by reinstalling with `pnpm --dir apps/admin-cli run install-persistent` (self-contained copy in `~/.recess-cli/cli/`), which no worktree deletion can break.
+- 2026-07-18 — Per-kid excused-absence credits (guide asks to credit specific absent kids; class still runs) follow the `cancellation-credits.md` mechanics minus the roster sweep: same Sunday-anchor invoice lookup, same composition check, `invoices refund --method credit --full`, reason "Excused absence - <cohort> <date>". Surface the `--who-pays` call explicitly — the guide default means the requesting guide absorbs the cost, which the human may want to override for a courtesy credit.
+- 2026-07-18 — A fully balance-paid invoice (`applied_balance` = -subtotal, `amount` 0, no tokens) takes `--method credit --full` cleanly: the credit note restores the consumed customer balance. The billing.md over-refund warning for `applied_balance < 0` is about CASH refunds (`--method refund`), not balance credits. Verified live on two CoLab invoices (cn_1Tufqt…, cn_1Tufqz…).
+- 2026-07-18 — Never call a Slack credit/absence request "unprocessed" from the thread alone — processed requests routinely get no Slack reply. The read-before-assert discipline applies to volunteered recommendations and status summaries, not just writes you're about to execute. Completion evidence lives in billing state and takes TWO reads per kid: `invoices list` (a past week handled by credit shows `credited_amount` + memo) AND `subscriptions list` (a future week can be pre-handled by a billing pause, which leaves NO invoice or enrollment trace — only Stripe `pause_collection`). Observed live: flagged two Brannock requests as open when both credits and a pre-emptive pause through 7/29 were already in place.
+- 2026-07-20 — "Skip next week" from a family is ambiguous mid-week and the two readings need OPPOSITE commands — resolve it with the human before previewing. The Sunday anchor means the week already in progress is ALREADY INVOICED AND PAID, so a pause does nothing for it (that week needs `invoices refund`); only the not-yet-issued Sunday tick can be voided by `billing pause`. Read `invoices list` for the latest `created_date` (a Sunday 00:00 UTC stamp) and the subscription's `period_end` to see exactly where the paid/unpaid boundary sits, then ask which session they mean. Observed live: Mon 7/20 request to skip "next week" on a Thursday 1-on-1 — Thu 7/23 was already paid, Thu 7/30 was not.
+- 2026-07-20 — A billing pause deliberately leaves the session ACTIVE on the calendar; skipping the charge and canceling the class are separate decisions with wildly different blast radii (pause = silent, `events cancel` = family email blast + chat + Slack). Ask which one the human wants rather than assuming a skipped week implies a canceled session.
+- 2026-07-20 — **A fully-credited MIXED invoice does NOT show `credited_amount` == the line's full amount** — the token half lands in the invoice-level `token_refunded_cents` while the line's `credited_amount` only ever reflects the CASH half. Foundations of Science 8-11, Natan Rocklin: a complete $30.00 credit verifies as `credited_amount: 2001` + `token_refunded_cents: 999` + `token_refundable_remaining_cents: 0` on a line whose `amount` is 3000. Read it as under-refunded and you will double-credit the family. The reliable "is this line fully made whole?" test is `credited_amount + token_refunded_cents == line amount` AND `token_refundable_remaining_cents == 0`. Note the two writes also return different envelopes: `--method credit` gives `{noteId: "cn_…"}`, `--method tokens` gives `{creditTransactionId, newBalance}` (no credit note exists for a token refund).
+- 2026-07-20 — Payment composition varies PER KID inside a single cohort week — never read one kid's invoice and apply that instrument to the roster. One 3-kid cancellation sweep hit all three shapes at once: fully cash-paid, fully balance-paid (`applied_balance` −3000, `amount` 0, no paymentIntent), and mixed tokens+cash. Same course, same $30 price, same Sunday invoice batch, three different correct commands (and four total writes for three kids).
+- 2026-07-20 — The invoice-ID prefix collision is not rare enough to ignore: within ONE kid-cohort sweep, Zayn Kacem's Foundations invoice `in_1TuiGeBBeAjEgjlsrwjle3Oz` and Andromeda Brand's Terraria invoice `in_1TuiGeBBeAjEgjlszZROm407` shared their first 18 chars (both minted in the same Sunday 00:07 UTC batch run). Scope every `invoices list` to the specific subscription and compare IDs in full — the same-second batch anchor is exactly what manufactures these near-twins.
+- 2026-07-21 — The earlier browser-only auth limitation is resolved for headless agents: run `auth request`, give the returned approval URL/code to a human admin, then run `auth poll`. The device secret remains in the mode-0600 config and must never be surfaced. The resulting session still expires after 12 hours and cannot refresh itself.
+- 2026-07-21 — **Never answer "was this cancellation refund handled?" from the DB alone.** `CreditTransactionLog` only shows `--method tokens` grants; Stripe cash/balance path (`--method credit` / `--method refund`) lands only as invoice `credited_amount` + credit-note memo via `invoices list`. Observed live: Foundations of Science 8-11 7/20 — Zayn (full cash credit $30) and Andromeda (full balance credit $30) looked "open" in DB/token logs while admin CLI invoices already showed `credited_amount: 3000` with memo `Guide cancellation - Foundations of Science (8-11) 2026-07-20`. Always verify completion with `recess --json invoices list --subscription <sub>` (and the mixed-invoice test `credited_amount + token_refunded_cents == line amount`).
+- 2026-07-21 — **Future canceled session = pause, not credit.** When the cancel lands before the Sunday that starts the canceled week, no invoice exists yet — `invoices refund` has nothing to target. Use `billing pause --until` mid-week after that Sunday to void only that tick (Scratch 'n Hack 2 Aug 4 cancel → pause until 2026-08-06 on `sub_1TlVBBB…`). Documented in `reference/cancellation-credits.md` §3b. Don't route these threads to Linear; load this skill + cancellation-credits playbook immediately on `#cohort-cancellations` / "Please credit these students accordingly".
+- 2026-07-23 — `events reschedule` on a non-flexible course 400s (`allowFlexibleScheduling: false`) even for a simple ±10 min move (Space Technology & Rocket Launches / Starship). Check `course.allowFlexibleScheduling` on `cohorts get` **before** promising a reschedule. Staff workaround already in use: `events add` at the new cohort-local time + `events set-status CANCELED` on the original (silent — not `events cancel`). Enabling flexible scheduling is web-admin-only. Details: `reference/class-ops-reschedule.md`.

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

@@ -0,0 +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."