recess-cli 2.1.0 → 2.3.0

package/dist/help.js

@@ -133,6 +133,11 @@ Usage:
     [--limit N] [--stage-filter all|scheduled|oriented|course|converted|lost]
   recess [--json] onboarding timeline <family-id>
   recess [--json] onboarding readiness <family-id>
+  recess [--json] onboarding family <family-id>
+  recess [--json] onboarding next <family-id>
+  recess [--json] onboarding doctor [--family <family-id>]
+  recess [--json] onboarding starter-coverage
+  recess [--json] onboarding backfill-trackers [--apply] [--confirm]
   recess [--json] onboarding active-tutors <family-id>
   recess [--json] onboarding meetings <family-id>
   recess [--json] onboarding cohort-options <family-id> [--kid <kid-id>]
@@ -142,6 +147,8 @@ Usage:
   recess [--json] onboarding orientation-sessions
   recess [--json] onboarding ixl-preview <family-id> --kid <kid-id>
   recess [--json] onboarding intake-session <family-id>
+  recess [--json] onboarding reviews <family-id>
+  recess [--json] onboarding review <session-id>
   recess [--json] onboarding intake-session-create <family-id> [--confirm]
   recess [--json] onboarding set-stage <family-id>
     --stage LEGACY|PROVISIONED|PARENT_CONFIRMED|CLEARED_FOR_COHORT|COMPLETE [--confirm]
@@ -165,6 +172,9 @@ Usage:
     --kid <kid-id> [--credentials-file <credentials.json>] [--confirm]
   recess [--json] onboarding remove-ixl <family-id> --kid <kid-id> [--confirm]
   recess [--json] onboarding ixl-sync [--apply] [--confirm]
+  recess [--json] onboarding contracts [--kid <kid-id>]
+  recess [--json] onboarding send-contract <kid-id> [--tuition-cents N]
+    [--parent-email <email>] [--partner-name TEXT] [--partner-email <email>] [--confirm]
   recess [--json] onboarding send-comms --subject <family:id|invite:id>
     --kind <kind> [--confirm]
   recess [--json] onboarding send-welcome <family-id> [--resend] [--confirm]
@@ -189,6 +199,53 @@ Usage:
     --data <json> [--expected-updated-at <iso>] [--confirm]
   recess [--json] onboarding extract <family-id> --session <id>
     (--transcript-file <path> | --granola <ref>) [--confirm]
+  recess [--json] onboarding mark-reviewed <session-id> [--confirm]
+  recess [--json] onboarding pairing-code <kid-id> [--confirm]
+  recess [--json] school list
+  recess [--json] school families --school <institution-slug>
+  recess [--json] school family-search --school <institution-slug> --query TEXT
+    [--limit N]
+  recess [--json] school convert <family-id> --school <institution-slug>
+    --kid "<kid-id>:<tier>[:<slots>[:<enrollment-cents>]]" [--kid "..."]
+    [--credit-cents N] [--enrollment-payment-cents N] [--note TEXT] [--confirm]
+  recess [--json] school revert <family-id> --school <institution-slug>
+    [--keep-tokens] [--note TEXT] [--confirm]
+  recess [--json] school start-memberships <family-id> --kid <kid-id> [--kid <kid-id>]
+    [--confirm]
+  recess [--json] school resolve-payment <payment-id> --school <institution-slug>
+    --action waive|cancel [--note TEXT] [--confirm]
+  recess [--json] school close-reconciliation <payment-id> --school <institution-slug>
+    --outcome refunded|kept|written_off [--note TEXT] [--confirm]
+  recess [--json] school codes list --school <institution-slug>
+  recess [--json] school codes get <code-id> --school <institution-slug>
+  recess [--json] school codes create --school <institution-slug> [--count N]
+    [--expires-at <iso>] [--note TEXT] [--credit-cents N]
+    [--tier social|academics|lite|complete|platform] [--slots N]
+    [--enrollment-payment-cents N] [--data-file <preconfigured-family.json>] [--confirm]
+  recess [--json] school codes set-kids <code-id> --school <institution-slug>
+    --data-file <roster.json> [--confirm]
+  recess [--json] school codes replace <code-id> --school <institution-slug>
+    --data-file <invite.json> [--confirm]
+  recess [--json] school codes resend <code-id> --school <institution-slug> [--confirm]
+  recess [--json] school codes revoke <code-id> --school <institution-slug> [--confirm]
+  recess [--json] school create --slug <slug> --name TEXT --credit-grant N
+    [--logo-url URL] [--program-type PARTNER|SCHOOL] [--token-topup-cents N] [--confirm]
+  recess [--json] school update <institution-id> [--slug <slug>] [--name TEXT]
+    [--logo-url URL] [--credit-grant N] [--program-type PARTNER|SCHOOL]
+    [--token-topup-cents N] [--confirm]
+  recess [--json] school representatives list --school <institution-slug>
+  recess [--json] school representatives search --query TEXT
+  recess [--json] school representatives add --school <institution-slug>
+    --user <user-id> [--confirm]
+  recess [--json] school representatives remove --school <institution-slug>
+    --user <user-id> [--confirm]
+  recess [--json] school credit-transactions --school <institution-slug>
+    [--page 0] [--limit 50]
+  recess [--json] school kid-slots <kid-id> --school <institution-slug>
+    --slots N [--premium-slots N] [--confirm]
+  recess [--json] school partner-family <family-id> --school <institution-slug>
+    --enabled true|false [--confirm]
+  recess [--json] school logo-upload --file </path/logo.png> [--confirm]
   recess [--json] village models list [--world village-1] [--query TEXT] [--archived]
   recess [--json] village models upload --file </path/model.glb>
     [--world village-1] [--name TEXT] [--id ID] [--description TEXT] [--tags A,B]
@@ -240,17 +297,20 @@ Usage:
   recess [--json] goal-templates get <template-id|slug> [--spec-only]
   recess [--json] goal-templates versions <template-id> [--version N]
   recess [--json] goal-templates validate-spec --file <path/template.json>
-  recess [--json] goal-templates create --file <path/template.json> [--confirm]
+  recess [--json] goal-templates create --file <path/template.json>
+    [--coin-amount N] [--confirm]
   recess [--json] goal-templates patch-spec <template-id|slug> --expected-version N
     --patches-file <path/patches.json> [--confirm --approval-token TOKEN]
     [--confirm-destructive-changes --destructive-change-token TOKEN]
   recess [--json] goal-templates set-metadata <template-id> --expected-version N
     [--title TEXT] [--description TEXT] [--emoji X] [--category TEXT] [--tags A,B]
-    [--sort-order N] [--is-starter true|false]
+    [--image-url URL] [--coin-amount N] [--sort-order N] [--is-starter true|false]
     [--setup-audience KID_FRIENDLY|PARENT_SETUP] [--kind SIMPLE|BLUEPRINT]
     [--agent-instructions-file <path>]
     [--output-template-file <path>] [--confirm]
   recess [--json] goal-templates delete <template-id> --expected-version N [--confirm]
+  recess [--json] goal-templates generate-image <template-id|slug>
+    [--prompt TEXT] [--confirm]
   recess [--json] goal-templates snapshot-files <template-id> [--path P]
   recess [--json] goal-templates capture-snapshot <template-id|slug>
     (--source-goal <goal-id> | --source-draft <draft-slug> --student <goal-owner-id>
@@ -270,6 +330,12 @@ Usage:
     --delta TEXT [--confirm --approval-token TOKEN]
   recess [--json] goals delete <goal-id> --student <kid-id>
     [--confirm --approval-token TOKEN]
+  recess [--json] goals complete <goal-id> [--confirm]
+  recess [--json] goals undo-completion <goal-id> [--confirm]
+  recess [--json] goals archive <goal-id> --student <kid-id>
+    [--confirm --approval-token TOKEN]
+  recess [--json] goals unarchive <goal-id> --student <kid-id>
+    [--confirm --approval-token TOKEN]
   recess [--json] goals queue get <goal-id> --student <kid-id>
   recess [--json] goals queue set <goal-id> --student <kid-id>
     --entries-file <path.json> --delta TEXT [--replace-description-pointer]
@@ -327,6 +393,26 @@ the backend's own dryRun before the gate and previews the per-student outcome.
 409s STALE_WRITE and writes nothing. The spec is unreachable from "set-metadata"
 by design — an existing spec is edited only through the guarded /ai patch path.
 
+School-onboarding workflow notes: "onboarding family" is the one-screen view
+(status + readiness + next action + intake session + active tutors, in
+parallel; flag-gated pieces degrade to a labeled "unavailable"). "onboarding
+next" returns the mission-control queue's current action for the family PLUS
+suggestedCommands — the exact commands that perform it, ids substituted.
+"onboarding doctor" answers "who actually sees the school-onboarding surface
+and why": the env kill-switches (SCHOOL_ONBOARDING_V1_FORCE,
+SCHOOL_ONBOARDING_CUTOVER), comms master switch + mode, the acting staffer's
+flag evaluation, and per-guardian/per-kid flag, capability-lock, and
+cohort-gate state; env values are the answering service's only — the Worker
+can differ. "onboarding starter-coverage" is the read-only pre-flip gate
+(ok:false = do not flip the flag). "onboarding backfill-trackers" is the WS-H
+census (read-only); --apply re-takes the census as the preview and stamps only
+the arm-1 guardians, exact-ADMIN, re-derived under a per-guardian lock
+server-side. "school create/update" carry money levers
+(--credit-grant/--token-topup-cents/--program-type spend real money via the
+monthly top-up cron and are exact-ADMIN on update); descriptive edits
+(name/slug/logo) are ordinary staff writes. "school kid-slots" is the raw
+slot override; "users tier set" is the tier-driven path.
+
 Onboarding notes: "status" and "intake-session" are reads — "intake-session"
 looks up the current IN_PROGRESS session without creating one (prints a "none
 yet" result when absent). "intake-session-create" is the explicit write that
@@ -353,9 +439,11 @@ endDate minus one day) and shows the computed date in the preview.
 Auth notes: "auth login" runs the browser loopback flow for ADMIN, GUIDE, a GUARDIAN with
 access:ai, or a KID using only Village home building. Guardian sessions are family-scoped and
 cannot call /admin; KID sessions cannot call any non-Village API command. For a headless
-cloud agent, the ADMIN-only "auth request" prints an approval URL to hand a Recess admin; after they
-approve it in a browser, "auth poll" collects the 12h session. When it lapses, run
-"auth request" again for a fresh link. Both paths yield the same session.
+cloud agent that has no local browser to open, "auth request" prints an approval URL; whoever
+opens it and approves in a signed-in web session grants THEIR OWN scope, so a guardian approving
+mints a family-scoped session and only an admin can mint a full-admin one. "auth poll" then
+collects the 12h session. Kids cannot approve. When it lapses, run "auth request" again for a
+fresh link. Both paths yield the same session.
 
 Skill notes: this CLI's own agent skill ships inside the npm package AND is served
 by the server, so wording/Gotcha updates arrive without an npm release. "setup"

package/dist/http.js

@@ -3,6 +3,44 @@ export const RECESS_CLIENT_HEADER = "x-recess-client";
 export const RECESS_CLIENT_CLI = "cli";
 export const RECESS_CLIENT_CLI_UI = "cli-ui";
 export const RECESS_REASON_HEADER = "x-recess-reason";
+/**
+ * Set alongside the reason when it had to be percent-encoded to survive the
+ * header. The server decodes only when this is present, so a literal `%` in an
+ * all-ASCII reason is never mangled.
+ */
+export const RECESS_REASON_ENCODING_HEADER = "x-recess-reason-encoding";
+export const RECESS_REASON_ENCODING_UTF8 = "utf-8-percent";
+const ASCII_PRINTABLE = /^[\x20-\x7E]*$/;
+/**
+ * Make a human-written reason safe to put in an HTTP header.
+ *
+ * Headers are ByteStrings: any code point above U+00FF throws
+ * "Cannot convert argument to a ByteString because the character at index N
+ * has a value of 8212" — 8212 being an em dash. The error names no field, so
+ * the failure looks like a bug in whatever command you happened to run, and
+ * typing an em dash or a curly quote in `--reason` is completely ordinary.
+ *
+ * Common typography is folded to its ASCII equivalent so the audit log stays
+ * readable; anything still non-ASCII (accented names, CJK, emoji) is
+ * UTF-8 percent-encoded and flagged for the server to decode, which is lossless.
+ */
+export function encodeReasonHeader(reason) {
+    const folded = reason
+        // Typography first, so the audit log keeps a readable reason instead of a
+        // percent-escaped one. These are what people actually type.
+        .replace(/[\u2010-\u2015\u2212]/g, "-") // hyphens, en/em dashes, minus
+        .replace(/[\u2018\u2019\u201A\u201B]/g, "'")
+        .replace(/[\u201C\u201D\u201E\u201F]/g, '"')
+        .replace(/\u2026/g, "...")
+        .replace(/[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g, " ")
+        .replace(/[\u200B-\u200D\uFEFF]/g, "");
+    if (ASCII_PRINTABLE.test(folded))
+        return { value: folded };
+    return {
+        value: encodeURIComponent(folded),
+        encoding: RECESS_REASON_ENCODING_UTF8,
+    };
+}
 export function requireCliRequestReason(value) {
     const reason = value?.trim();
     if (!reason) {
@@ -15,8 +53,13 @@ export function requireCliRequestReason(value) {
 }
 export function markCliRequest(headers, reason, client = RECESS_CLIENT_CLI) {
     headers.set(RECESS_CLIENT_HEADER, client);
-    if (reason)
-        headers.set(RECESS_REASON_HEADER, reason);
+    if (reason) {
+        const encoded = encodeReasonHeader(reason);
+        headers.set(RECESS_REASON_HEADER, encoded.value);
+        if (encoded.encoding) {
+            headers.set(RECESS_REASON_ENCODING_HEADER, encoded.encoding);
+        }
+    }
     return headers;
 }
 export function cliRequestHeaders(init, reason, client = RECESS_CLIENT_CLI) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "recess-cli",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "Safe Recess administration and family AI tools from the command line.",
   "license": "UNLICENSED",
   "repository": {

package/skill/recess-cli/SKILL.md

@@ -38,7 +38,9 @@ For machine-readable discovery, use `recess --json agent-context`; for a smaller
 ## Authentication
 
 - Workstation: `recess --json auth login` opens Recess SSO.
-- Headless device authorization is staff-only: `auth request`, human approval, then `auth poll`.
+- Headless (no browser): `auth request`, then a human approves the printed URL while signed in to
+  Recess, then `auth poll`. The session takes on the **approver's** scope — a guardian approving
+  grants family-only access, not staff access. Kids cannot approve.
 - Sessions last 12 hours and are rechecked against the live user role and permissions.
 - `auth status` inspects the current session; `auth logout` clears the stored session.
 - The default API is production. If `RECESS_CLI_API_ORIGIN` is set, state the non-default origin before acting.

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

@@ -1,4 +1,4 @@
 {
-  "version": "2.3.0",
+  "version": "2.4.0",
   "minCliVersion": "2.1.0"
 }