recess-cli 2.2.0 → 2.3.0

package/README.md

@@ -121,6 +121,24 @@ row per request. The human-only `recess ui` console is explicitly exempt and ide
 
 ## Common flow
 
+School-onboarding work is family-first: one composite view, then a loop of "what's
+next" → the suggested command → "what's next" again, with `doctor` as the
+gate-observability instrument when something is unexpectedly dark:
+
+```bash
+recess --json onboarding family <family-id> --reason "One-screen view of this school family"
+recess --json onboarding next <family-id> --reason "What should happen next for this family"
+recess --json onboarding doctor --family <family-id> --reason "Why is the school surface dark for them"
+recess --json onboarding starter-coverage --reason "Run the pre-flip coverage gate"
+recess --json onboarding backfill-trackers --reason "Census the WS-H guardian trackers"
+```
+
+`next` returns the mission-control queue's current action plus `suggestedCommands`
+with real ids substituted; every suggested write still previews and requires its
+own `--confirm`. `doctor` reports the env kill-switches, comms mode, and
+per-guardian/per-kid flag + capability-lock + cohort-gate state — its env values
+are the answering service's only (the Worker can differ).
+
 ```bash
 recess --json users search "Morgan Rivera" --reason "Find the exact student record"
 recess --json users tier get <kid-id> --reason "Inspect the student's current tier"

package/dist/api.js

@@ -142,6 +142,23 @@ export class RecessAdminApi {
             throw apiError(response.status, body);
         return body;
     }
+    async uploadPartnerLogo(image, fileName, mimeType) {
+        this.requireAuth();
+        const formData = new FormData();
+        const arrayBuffer = image.buffer.slice(image.byteOffset, image.byteOffset + image.byteLength);
+        formData.append("file", new Blob([arrayBuffer], { type: mimeType }), fileName);
+        const headers = cliRequestHeaders({ cookie: this.config.sessionCookie }, this.reason, this.clientTag);
+        applyIdempotencyHeaders(headers);
+        const response = await fetch(new URL("/admin/partner/logo-upload", this.config.apiOrigin), {
+            method: "POST",
+            headers,
+            body: formData,
+        });
+        const body = await readResponseBody(response);
+        if (!response.ok)
+            throw apiError(response.status, body);
+        return body;
+    }
     async uploadMapTestScores(studentId, pdf, fileName) {
         this.requireAuth();
         const formData = new FormData();

package/dist/auth.js

@@ -100,6 +100,11 @@ export async function login(config, options) {
 // Start the headless (device-authorization) sign-in. Non-blocking: it stores the secret
 // device code locally and returns the approval URL for the agent to surface to a human, who
 // approves it in a browser. The agent then calls `pollDeviceAuth` to collect the session.
+//
+// The approver grants their own scope: a guardian approving yields a family-scoped session
+// over their own kids, an admin a full-admin one. That is what lets an agent running
+// anywhere — a cloud box with no browser — hold a session at all, instead of a human having
+// to be the hands for every command.
 export async function requestDeviceAuth(config, options) {
     const response = await fetch(new URL("/auth/admin-cli/device/authorize/", config.apiOrigin), {
         method: "POST",
@@ -123,11 +128,11 @@ export async function requestDeviceAuth(config, options) {
         userCode: authorize.userCode,
         expiresAt: authorize.expiresAt,
         interval: authorize.interval,
-        instructions: `Open ${authorize.approvalUrl} in a browser, approve as a Recess admin, then run \`recess auth poll\`.`,
+        instructions: `Open ${authorize.approvalUrl} in a browser and approve it while signed in to Recess as the person this agent should act as — the session takes on THAT account's scope, so a guardian grants family-only access. Then run \`recess auth poll\`.`,
     };
 }
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-// Poll the device-authorization request until an admin approves it (then store the session),
+// Poll the device-authorization request until a human approves it (then store the session),
 // or it is denied / expires / the timeout elapses. On a plain timeout the pending request is
 // preserved so the agent can call `auth poll` again after the human approves.
 export async function pollDeviceAuth(config, options) {

package/dist/cli.js

@@ -24,6 +24,52 @@ import { appendJobEvent, getJob, listJobs, pruneJobs } from "./jobs.js";
 function requiredRequestReason(parsed) {
     return requireCliRequestReason(flagString(parsed, "reason", { required: true }));
 }
+/**
+ * Role of whoever this session belongs to.
+ *
+ * The stored identity only describes an `auth login` session; an env-cookie
+ * session may belong to someone else entirely, so ask the server rather than
+ * trusting a stale login. Used by commands that must refuse *before* their
+ * confirmation gate — an approval a human grants and the server then rejects is
+ * worse than no preview at all.
+ */
+async function resolveSessionRole(api) {
+    if (api.config.authSource === "config" && api.config.user?.role) {
+        return api.config.user.role;
+    }
+    const session = await api.client.GET("/auth/admin-cli/session/");
+    return session.data?.user.role;
+}
+/** Status values `goals edit` may send. Deliberately narrow: the backend patch
+ * route is pause/resume only, and reaching the terminal state is
+ * `goals archive`, which frees an open-goal slot and writes a different audit
+ * row. */
+const EDITABLE_GOAL_STATUSES = ["ACTIVE", "PAUSED"];
+/**
+ * Reject bad enum values in a goal patch file *before* the preview is built.
+ *
+ * A preview is what a human approves, so it must not describe a write the
+ * server will refuse. Sending `{"status":"COMPLETED"}` used to preview cleanly,
+ * resolve a compare-and-set token, mint an approval token, and only then fail
+ * at confirm — spending a human approval on an impossible request.
+ */
+function assertGoalPatchValues(patch, patchFile) {
+    const status = patch.status;
+    if (status === undefined)
+        return;
+    if (typeof status !== "string" ||
+        !EDITABLE_GOAL_STATUSES.includes(status)) {
+        const archiveHint = status === "COMPLETED"
+            ? " To close out a finished course and free an open-goal slot, use `recess goals archive <goal-id> --student <kid-id>` instead — `goals edit` cannot set a terminal status."
+            : "";
+        throw new CliError("invalid_arguments", `${path.resolve(patchFile)} sets status to ${JSON.stringify(status)}, which \`goals edit\` does not accept. Allowed: ${EDITABLE_GOAL_STATUSES.join(", ")}.${archiveHint}`, 1, {
+            field: "status",
+            value: status,
+            allowed: [...EDITABLE_GOAL_STATUSES],
+            patchFile: path.resolve(patchFile),
+        });
+    }
+}
 async function sessionStatus(config) {
     if (!config.sessionCookie) {
         return {
@@ -131,7 +177,7 @@ async function writeCommand(parsed, preview, execute) {
             details: {
                 ...preview.details,
                 operationKey,
-                retry: "Rerun the unchanged command with --confirm --operation-key <operationKey>. Reuse that same key after an interrupted invocation.",
+                retry: "Rerun the unchanged command with --confirm --operation-key <operationKey>. Reuse that same key after an interrupted invocation. Previewing again is harmless: it mints another key that is equally valid, because keys are bound to the payload rather than to one preview run.",
             },
         };
         await appendJobEvent({
@@ -145,7 +191,7 @@ async function writeCommand(parsed, preview, execute) {
         requireConfirmation(false, boundPreview);
     }
     if (!suppliedOperationKey) {
-        throw new CliError("confirmation_required", "A confirmed write requires the operation key from its approved preview.", 2, { preview, requiredFlag: "--operation-key" });
+        throw new CliError("confirmation_required", "A confirmed write requires --operation-key. Run this exact command without --confirm, then pass the operationKey from the preview details. Any preview of this same payload yields a usable key.", 2, { preview, requiredFlag: "--operation-key" });
     }
     assertOperationKeyMatchesPreview(suppliedOperationKey, fingerprint, preview);
     await appendJobEvent({
@@ -477,9 +523,26 @@ function approvalTokenFor(preview) {
 function operationKeyFor(fingerprint) {
     return `op_${randomUUID().replaceAll("-", "")}_${fingerprint}`;
 }
+/**
+ * An operation key is `op_<random>_<fingerprint>`, and the fingerprint is a
+ * hash of the whole preview. Only the suffix is checked, which means **any**
+ * key minted from a preview of this exact payload works — including one from an
+ * earlier preview of the same command. That matters: previewing twice mints two
+ * different keys, both valid, and reaching for the newer one is not a mistake.
+ *
+ * The suffix is also what makes the key safe. It cannot be transplanted onto a
+ * different write, because a payload that differs by one character hashes
+ * differently and no key from the old preview will match.
+ */
 function assertOperationKeyMatchesPreview(operationKey, fingerprint, preview) {
     if (!operationKey.endsWith(`_${fingerprint}`)) {
-        throw new CliError("approval_mismatch", "The operation key does not belong to this preview. Start from a new preview and obtain approval again.", 2, { preview, requiredFlag: "--operation-key" });
+        throw new CliError("approval_mismatch", `This operation key was minted for a different payload, so it cannot approve this one. The key must end in _${fingerprint} — copy the operationKey out of the preview for THIS exact command (any preview of the same payload will do, newest or oldest). If the payload really did change, that is the gate working: get approval on the current preview.`, 2, {
+            preview,
+            requiredFlag: "--operation-key",
+            expectedKeySuffix: `_${fingerprint}`,
+            suppliedKey: operationKey,
+            note: "Keys are bound to the payload, not to a particular preview run. Re-previewing an unchanged command mints a new key with the same suffix; every one of them is accepted.",
+        });
     }
 }
 async function requirePreviewBoundConfirmation(parsed, preview) {
@@ -509,7 +572,7 @@ async function requirePreviewBoundConfirmation(parsed, preview) {
         throw new CliError("approval_mismatch", "The approved preview no longer matches this request. Review the current preview and rerun with --confirm --approval-token <token>.", 2, { preview: boundPreview, requiredFlag: "--approval-token" });
     }
     if (!suppliedOperationKey) {
-        throw new CliError("confirmation_required", "A confirmed write requires the operation key from its approved preview.", 2, { preview: boundPreview, requiredFlag: "--operation-key" });
+        throw new CliError("confirmation_required", "A confirmed write requires --operation-key. Run this exact command without --confirm, then pass the operationKey from the preview details. Any preview of this same payload yields a usable key.", 2, { preview: boundPreview, requiredFlag: "--operation-key" });
     }
     assertOperationKeyMatchesPreview(suppliedOperationKey, approvalToken, boundPreview);
     await appendJobEvent({
@@ -3559,6 +3622,51 @@ export async function runCommand(argv) {
                     params: { path: { goalId } },
                 })));
         }
+        if (verb === "archive" || verb === "unarchive") {
+            const goalId = positional(parsed, 2, "goal ID");
+            const studentId = flagString(parsed, "student", { required: true });
+            const reopen = verb === "unarchive";
+            const current = unwrap(await api.client.GET("/tutor/browser/students/{userId}/goals/", {
+                params: { path: { userId: studentId } },
+            })).goals.find((goal) => goal.id === goalId);
+            if (!current) {
+                throw new CliError("not_found", `Goal ${goalId} was not found for student ${studentId}.`);
+            }
+            // Refuse the no-op before asking a human to approve it. Approving
+            // "archive a goal" only to be told it was already archived teaches an
+            // agent to re-approve noise.
+            if (!reopen && current.status === "COMPLETED") {
+                throw new CliError("already_archived", `Goal ${goalId} ("${current.title}") is already archived and is not holding an open-goal slot.`);
+            }
+            if (reopen && current.status !== "COMPLETED") {
+                throw new CliError("not_archived", `Goal ${goalId} ("${current.title}") is ${current.status}, not archived. There is nothing to reopen.`);
+            }
+            const preview = {
+                action: reopen
+                    ? "reopen an archived goal (consumes one of the kid's open-goal slots)"
+                    : "archive a finished goal (frees one of the kid's open-goal slots)",
+                target: {
+                    goalId,
+                    studentUserId: studentId,
+                    title: current.title,
+                    status: current.status,
+                    progress: current.progress,
+                },
+                request: { goalId },
+                details: {
+                    note: reopen
+                        ? "Returns the goal to ACTIVE so it generates daily todos again. Refused with GOAL_LIMIT_REACHED if the kid is already at the open-goal cap, and refused for goals completed through the staff reward path (those need `goals undo-completion`, which reverses the coins)."
+                        : "Sets the terminal COMPLETED status. Grants no coins and posts no activity — use `goals complete` (staff only) when the kid should receive the goal's reward. The goal, its history, and its past todos all stay; only the open-goal slot is released. Any already-scheduled future todos on this goal are left alone, matching `goals complete`.",
+                },
+            };
+            return previewBoundWrite(parsed, preview, async () => unwrap(reopen
+                ? await api.client.POST("/ai/goals/{goalId}/unarchive", {
+                    params: { path: { goalId } },
+                })
+                : await api.client.POST("/ai/goals/{goalId}/archive", {
+                    params: { path: { goalId } },
+                })));
+        }
         if (verb === "list") {
             const userId = flagString(parsed, "student", { required: true });
             return unwrap(await api.client.GET("/tutor/browser/students/{userId}/goals/", {
@@ -3727,6 +3835,7 @@ export async function runCommand(argv) {
             const studentId = flagString(parsed, "student", { required: true });
             const patchFile = flagString(parsed, "patch-file", { required: true });
             const patch = (await readJsonFile(patchFile, "Goal patch file"));
+            assertGoalPatchValues(patch, patchFile);
             patch.delta = flagString(parsed, "delta", { required: true });
             const current = unwrap(await api.client.GET("/tutor/browser/students/{userId}/goals/", {
                 params: { path: { userId: studentId } },
@@ -3752,6 +3861,15 @@ export async function runCommand(argv) {
         if (verb === "delete") {
             const goalId = positional(parsed, 2, "goal ID");
             const studentId = flagString(parsed, "student", { required: true });
+            // Deletion is an /admin/* route, so a guardian or guide session can never
+            // complete it. Refuse here, before the preview, rather than rendering a
+            // full and entirely plausible preview — resolved goal, named title,
+            // described soft-delete — that a human approves and the server then
+            // answers 401. A preview is a promise about what --confirm will do.
+            const sessionRole = await resolveSessionRole(api);
+            if (sessionRole && sessionRole !== "ADMIN") {
+                throw new CliError("forbidden", "Deleting a goal is staff-only. To free an open-goal slot for a finished course, use `recess goals archive <goal-id> --student <kid-id>` — it sets the terminal status, keeps the goal and its history, and needs no staff involvement.", 1, { sessionRole, requiredRole: "ADMIN", alternative: "goals archive" });
+            }
             const current = unwrap(await api.client.GET("/tutor/browser/students/{userId}/goals/", {
                 params: { path: { userId: studentId } },
             })).goals.find((goal) => goal.id === goalId);
@@ -3869,7 +3987,7 @@ export async function runCommand(argv) {
             }
             throw new CliError("invalid_arguments", "Use goals queue get|set.");
         }
-        throw new CliError("invalid_arguments", "Use goals list|create|edit|delete|complete|undo-completion|queue|files|pdf.");
+        throw new CliError("invalid_arguments", "Use goals list|create|edit|delete|archive|unarchive|complete|undo-completion|queue|files|pdf.");
     }
     if (noun === "students") {
         if (verb === "list") {

package/dist/commands/onboarding.js

@@ -48,6 +48,75 @@ function summaryPreview(text, max = 600) {
         return null;
     return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
 }
+/**
+ * The mission-control queue rule → the CLI command(s) that perform it, with
+ * real ids substituted where the action carries them. Placeholders stay in
+ * angle brackets where a human choice remains (a template, a cohort, a
+ * transcript). Suggestions only: every write below still previews and demands
+ * its own --confirm when actually run.
+ */
+function suggestedCommandsForQueueAction(action, familyId) {
+    const slug = action.partnerSlug ?? "<institution-slug>";
+    const invite = action.inviteId ?? "<code-id>";
+    const kid = (action.kids.find((row) => row.activeGoalCount === 0) ?? action.kids[0])
+        ?.id ?? "<kid-id>";
+    switch (action.key) {
+        case "invite_waiting":
+            return [
+                `recess school codes get ${invite} --school ${slug}`,
+                `recess school codes resend ${invite} --school ${slug}`,
+            ];
+        case "invite_expired":
+            return [
+                `recess school codes replace ${invite} --school ${slug} --data-file <invite.json>`,
+            ];
+        case "parked":
+            return [`recess onboarding set-account-state ${familyId} --state ACTIVE`];
+        case "start_intake":
+            return [`recess onboarding intake-session-create ${familyId}`];
+        case "fill_intake":
+            return [
+                `recess onboarding extract ${familyId} --session <session-id> --granola <ref>`,
+                `recess onboarding set-intake ${familyId} --session <session-id> --data <json>`,
+            ];
+        case "send_welcome":
+            return [`recess onboarding send-welcome ${familyId}`];
+        case "nudge_confirm":
+            return [
+                `recess onboarding send-comms --subject family:${familyId} --kind confirm_nudge_1`,
+            ];
+        case "load_goals":
+            return [
+                `recess goal-templates list --starter-only`,
+                `recess goal-templates apply-starter <template-id> --student ${kid}`,
+            ];
+        case "assign_tutor":
+            return [
+                `recess onboarding active-tutors ${familyId}`,
+                `recess onboarding set-primary-tutor ${familyId} --tutor <user-id>`,
+            ];
+        case "attest":
+            return [
+                `recess onboarding attest ${familyId} --condition <app_downloaded|tutor_met|goals_loaded|ma_diagnostic>`,
+            ];
+        case "clear_for_cohort":
+            return [`recess onboarding clear-for-cohort ${familyId}`];
+        case "register_cohort":
+            return [
+                `recess onboarding cohort-options ${familyId} --kid ${kid}`,
+                `recess onboarding register-cohort ${familyId} --kid ${kid} --cohort <event-series-id>`,
+            ];
+        case "at_risk":
+            return [
+                `recess onboarding readiness ${familyId}`,
+                `recess onboarding timeline ${familyId}`,
+            ];
+        case "mark_complete":
+            return [`recess onboarding set-stage ${familyId} --stage COMPLETE`];
+        default:
+            return [];
+    }
+}
 export async function runOnboardingCommand({ parsed, api, writeCommand, }) {
     const noun = parsed.positionals[0] ?? "";
     const verb = parsed.positionals[1] ?? "";
@@ -97,6 +166,123 @@ export async function runOnboardingCommand({ parsed, api, writeCommand, }) {
             const familyId = positional(parsed, 2, "family ID");
             return unwrap(await api.client.GET("/admin/onboarding/families/{familyId}/active-tutors", { params: { path: { familyId } } }));
         }
+        if (verb === "family") {
+            const familyId = positional(parsed, 2, "family ID");
+            // The whole family on one screen: status + readiness + the queue's next
+            // action + the current intake session + active tutors, in parallel.
+            // `status` is the required backbone (a missing family fails the command);
+            // the flag-gated reads degrade to a labeled `unavailable` instead of
+            // failing the view — the doctor command is the tool for "why".
+            const soft = async (read) => {
+                try {
+                    return await read();
+                }
+                catch (error) {
+                    return {
+                        unavailable: error instanceof CliError ? error.message : String(error),
+                    };
+                }
+            };
+            const [status, readiness, nextAction, intakeSession, activeTutors] = await Promise.all([
+                api.client
+                    .GET("/admin/onboarding/families/{familyId}/status", {
+                    params: { path: { familyId } },
+                })
+                    .then(unwrap),
+                soft(() => api.client
+                    .GET("/admin/onboarding/families/{familyId}/readiness", {
+                    params: { path: { familyId } },
+                })
+                    .then(unwrap)),
+                soft(() => api.client
+                    .GET("/admin/onboarding/families/{familyId}/next-action", {
+                    params: { path: { familyId } },
+                })
+                    .then(unwrap)),
+                soft(async () => {
+                    try {
+                        return await api.rawGet(`/admin/onboarding/families/${encodeURIComponent(familyId)}/intake-session`);
+                    }
+                    catch (error) {
+                        if (error instanceof CliError &&
+                            typeof error.details === "object" &&
+                            error.details !== null &&
+                            error.details.status === 404) {
+                            return { intakeSession: null };
+                        }
+                        throw error;
+                    }
+                }),
+                soft(() => api.client
+                    .GET("/admin/onboarding/families/{familyId}/active-tutors", {
+                    params: { path: { familyId } },
+                })
+                    .then(unwrap)),
+            ]);
+            return {
+                familyId,
+                status,
+                readiness,
+                nextAction,
+                intakeSession,
+                activeTutors,
+            };
+        }
+        if (verb === "next") {
+            const familyId = positional(parsed, 2, "family ID");
+            const result = unwrap(await api.client.GET("/admin/onboarding/families/{familyId}/next-action", { params: { path: { familyId } } }));
+            const action = result.action;
+            return {
+                ...result,
+                // The queue rule mapped to the command that performs it, with real ids
+                // substituted where the action carries them — so "what's next" arrives
+                // holding "and here is how", instead of making the agent re-derive the
+                // funnel from documentation. Every suggested write still previews and
+                // requires its own --confirm.
+                suggestedCommands: action === null
+                    ? []
+                    : suggestedCommandsForQueueAction(action, familyId),
+            };
+        }
+        if (verb === "doctor") {
+            // --family is a flag rather than an optional positional: the schema
+            // derives positional bounds from the usage line, which cannot express
+            // optionality.
+            const familyId = flagString(parsed, "family");
+            return unwrap(await api.client.GET("/admin/onboarding/doctor", {
+                params: { query: familyId ? { familyId } : {} },
+            }));
+        }
+        if (verb === "starter-coverage") {
+            // The read-only pre-flip gate (same evaluation as the runbook's
+            // check-starter-coverage script). `ok: false` = do not flip the flag.
+            return unwrap(await api.client.GET("/admin/onboarding/starter-coverage"));
+        }
+        if (verb === "backfill-trackers") {
+            // WS-H over the wire. Without --apply this is the read-only census
+            // (dry-run POST, same precedent as `goal-templates apply --dry-run`).
+            // With --apply, the census is re-taken as the preview — the runbook's
+            // "fresh dry run on the identical predicate immediately before
+            // applying" — and the confirmed write re-derives every conjunct under a
+            // per-guardian lock server-side anyway.
+            if (!hasFlag(parsed, "apply")) {
+                return unwrap(await api.client.POST("/admin/onboarding/backfill-guardian-trackers", {
+                    body: { apply: false },
+                }));
+            }
+            const census = unwrap(await api.client.POST("/admin/onboarding/backfill-guardian-trackers", {
+                body: { apply: false },
+            }));
+            return writeCommand(parsed, {
+                action: "apply the WS-H guardian-tracker backfill: stamp parentOnboardingCompletedAt for the arm-1 (crash-between-commits) school guardians below",
+                target: { repairableCount: census.repairable.length },
+                request: { apply: true },
+                details: {
+                    freshCensus: census,
+                    authority: "The census is a photograph; the server re-derives every conjunct under a per-guardian lock at write time and skips anyone who no longer qualifies. Exact-ADMIN only.",
+                },
+            }, async () => unwrap(await api.client.POST("/admin/onboarding/backfill-guardian-trackers", { body: { apply: true } })));
+        }
         if (verb === "meetings") {
             const familyId = positional(parsed, 2, "family ID");
             return unwrap(await api.client.GET("/admin/onboarding/families/{familyId}/meetings", {

package/dist/commands/school.js

@@ -1,3 +1,6 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
 import { unwrap } from "../api.js";
 import { flagList, flagString, hasFlag } from "../args.js";
 import { CliError } from "../errors.js";
@@ -9,6 +12,7 @@ const SCHOOL_TIERS = [
     "complete",
     "platform",
 ];
+const PROGRAM_TYPES = ["PARTNER", "SCHOOL"];
 const RESOLVE_ACTIONS = ["waive", "cancel"];
 const RECONCILIATION_OUTCOMES = ["refunded", "kept", "written_off"];
 /** post.start-memberships.ts caps the body at ten kids per call. */
@@ -16,6 +20,38 @@ const MEMBERSHIP_KID_LIMIT = 10;
 function dollars(cents) {
     return `$${(cents / 100).toFixed(2)}`;
 }
+/** The exact type set post.partner-logo-upload.ts accepts, keyed by extension. */
+const LOGO_MIME_BY_EXT = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+};
+async function readLogoFile(filePath) {
+    const absolutePath = path.resolve(filePath);
+    const mimeType = LOGO_MIME_BY_EXT[path.extname(absolutePath).toLowerCase()];
+    if (!mimeType) {
+        throw new CliError("invalid_arguments", "--file must be a .png, .jpg, .jpeg, .gif, .webp, or .svg image.");
+    }
+    let bytes;
+    try {
+        bytes = await fs.readFile(absolutePath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new CliError("invalid_arguments", `Logo file does not exist: ${absolutePath}`);
+        }
+        throw error;
+    }
+    return {
+        bytes,
+        fileName: path.basename(absolutePath),
+        mimeType,
+        sha256: createHash("sha256").update(bytes).digest("hex"),
+    };
+}
 function kidName(firstName, lastName, fallback) {
     return [firstName, lastName].filter(Boolean).join(" ") || fallback;
 }
@@ -460,6 +496,232 @@ export async function runSchoolCommand({ parsed, api, writeCommand, }) {
         }
         throw new CliError("invalid_arguments", "Use school codes list|get|create|set-kids|replace|resend|revoke.");
     }
+    if (verb === "create") {
+        const slug = flagString(parsed, "slug", { required: true });
+        const name = flagString(parsed, "name", { required: true });
+        const logoUrl = flagString(parsed, "logo-url");
+        const creditGrant = flagInteger(parsed, "credit-grant", {
+            required: true,
+            min: 0,
+        });
+        const programTypeRaw = flagString(parsed, "program-type");
+        const programType = programTypeRaw
+            ? assertChoice(programTypeRaw, PROGRAM_TYPES, "--program-type")
+            : undefined;
+        const tokenTopUpCents = flagInteger(parsed, "token-topup-cents", {
+            min: 0,
+            max: 10_000_000,
+        });
+        if (programType === "SCHOOL" && tokenTopUpCents !== creditGrant) {
+            throw new CliError("invalid_arguments", "SCHOOL programs require --token-topup-cents equal to --credit-grant (the server enforces the same rule).");
+        }
+        const body = {
+            slug,
+            name,
+            defaultInitialCreditGrant: creditGrant,
+            ...(logoUrl ? { logoUrl } : {}),
+            ...(programType ? { programType } : {}),
+            ...(tokenTopUpCents !== undefined
+                ? { monthlyTokenTopUpCents: tokenTopUpCents }
+                : {}),
+        };
+        return writeCommand(parsed, {
+            action: `create the ${programType ?? "PARTNER"}-program institution "${name}" (${slug})`,
+            target: { slug },
+            request: body,
+            details: {
+                moneyLevers: {
+                    defaultInitialCreditGrant: creditGrant,
+                    monthlyTokenTopUpCents: tokenTopUpCents ?? null,
+                    warning: "For SCHOOL programs the monthly target tops EVERY kid in the institution up to it on the next cron run — these numbers spend real money at scale.",
+                },
+                duplicateGuard: "A taken slug 409s; pick another rather than retrying.",
+            },
+        }, async () => unwrap(await api.client.POST("/admin/partner/", { body })));
+    }
+    if (verb === "update") {
+        const institutionId = positional(parsed, 2, "institution ID");
+        const slug = flagString(parsed, "slug");
+        const name = flagString(parsed, "name");
+        const logoUrl = flagString(parsed, "logo-url");
+        const creditGrant = flagInteger(parsed, "credit-grant", { min: 0 });
+        const programTypeRaw = flagString(parsed, "program-type");
+        const programType = programTypeRaw
+            ? assertChoice(programTypeRaw, PROGRAM_TYPES, "--program-type")
+            : undefined;
+        const tokenTopUpRaw = flagString(parsed, "token-topup-cents");
+        const tokenTopUpCents = tokenTopUpRaw === undefined
+            ? undefined
+            : tokenTopUpRaw === "none"
+                ? null
+                : flagInteger(parsed, "token-topup-cents", {
+                    min: 0,
+                    max: 10_000_000,
+                });
+        const body = {
+            ...(slug ? { slug } : {}),
+            ...(name ? { name } : {}),
+            ...(logoUrl ? { logoUrl } : {}),
+            ...(creditGrant !== undefined
+                ? { defaultInitialCreditGrant: creditGrant }
+                : {}),
+            ...(programType ? { programType } : {}),
+            ...(tokenTopUpCents !== undefined
+                ? { monthlyTokenTopUpCents: tokenTopUpCents }
+                : {}),
+        };
+        if (Object.keys(body).length === 0) {
+            throw new CliError("invalid_arguments", "Pass at least one field to change (--slug, --name, --logo-url, --credit-grant, --program-type, --token-topup-cents).");
+        }
+        const touchesMoney = creditGrant !== undefined ||
+            tokenTopUpCents !== undefined ||
+            programType !== undefined;
+        return writeCommand(parsed, {
+            action: touchesMoney
+                ? "edit this institution INCLUDING a money lever or the program type (exact-ADMIN only)"
+                : "edit this institution's descriptive metadata (name/slug/logo)",
+            target: { institutionId },
+            request: body,
+            details: {
+                ...(touchesMoney
+                    ? {
+                        moneyWarning: "defaultInitialCreditGrant / monthlyTokenTopUpCents / programType are money levers: the monthly target tops EVERY kid up to it on the next cron. A GUIDE or PROGRAM session gets 403 for these fields.",
+                    }
+                    : {}),
+                ...(programType
+                    ? {
+                        programTypeGuard: "A type flip is refused while families are attached or unused invite codes exist — resolve those first.",
+                    }
+                    : {}),
+            },
+        }, async () => unwrap(await api.client.PATCH("/admin/partner/{id}", {
+            params: { path: { id: institutionId } },
+            body,
+        })));
+    }
+    if (verb === "representatives") {
+        const subverb = parsed.positionals[2] ?? "";
+        if (subverb === "list") {
+            return unwrap(await api.client.GET("/admin/partner/{slug}/representatives", {
+                params: { path: { slug: requireSlug() } },
+            }));
+        }
+        if (subverb === "search") {
+            const q = flagString(parsed, "query", { required: true });
+            return unwrap(await api.client.GET("/admin/partner/representatives/search", {
+                params: { query: { q } },
+            }));
+        }
+        if (subverb === "add") {
+            const slug = requireSlug();
+            const userId = flagString(parsed, "user", { required: true });
+            // Resolve the exact person first so the approval names who gains the
+            // representative surface, not a bare id.
+            const { user } = unwrap(await api.client.GET("/admin/users/{userId}", {
+                params: { path: { userId } },
+            }));
+            return writeCommand(parsed, {
+                action: "add this GUIDE/ADMIN as a representative of the institution",
+                target: {
+                    slug,
+                    userId,
+                    name: kidName(user.firstName, user.lastName, userId),
+                    role: user.role,
+                },
+                request: { userId },
+                details: {
+                    refusal: "Non-GUIDE/ADMIN users are refused by the server.",
+                },
+            }, async () => unwrap(await api.client.POST("/admin/partner/{slug}/representatives", {
+                params: { path: { slug } },
+                body: { userId },
+            })));
+        }
+        if (subverb === "remove") {
+            const slug = requireSlug();
+            const userId = flagString(parsed, "user", { required: true });
+            return writeCommand(parsed, {
+                action: "remove this representative from the institution",
+                target: { slug, userId },
+                request: {},
+            }, async () => unwrap(await api.client.DELETE("/admin/partner/{slug}/representatives/{userId}", { params: { path: { slug, userId } } })));
+        }
+        throw new CliError("invalid_arguments", "Use school representatives list|search|add|remove.");
+    }
+    if (verb === "credit-transactions") {
+        const slug = requireSlug();
+        const page = flagInteger(parsed, "page", { min: 0 });
+        const limit = flagInteger(parsed, "limit", { min: 1, max: 100 });
+        return unwrap(await api.client.GET("/admin/partner/{slug}/credit-transactions", {
+            params: {
+                path: { slug },
+                query: {
+                    ...(page !== undefined ? { page } : {}),
+                    ...(limit !== undefined ? { limit } : {}),
+                },
+            },
+        }));
+    }
+    if (verb === "kid-slots") {
+        const kidId = positional(parsed, 2, "kid ID");
+        const slug = requireSlug();
+        const slotsRaw = flagString(parsed, "slots", { required: true });
+        const concurrentClassSlots = slotsRaw === "unlimited"
+            ? null
+            : flagInteger(parsed, "slots", { min: 0 });
+        const premiumClassSlots = flagInteger(parsed, "premium-slots", {
+            min: 0,
+            max: 20,
+        });
+        const body = {
+            concurrentClassSlots,
+            ...(premiumClassSlots !== undefined ? { premiumClassSlots } : {}),
+        };
+        return writeCommand(parsed, {
+            action: "set this school kid's concurrent class slots directly (the raw slot override — `users tier set` is the tier-driven path)",
+            target: { kidId, slug },
+            request: body,
+            details: {
+                slots: concurrentClassSlots ?? "unlimited",
+                ...(premiumClassSlots !== undefined
+                    ? { premiumSlots: premiumClassSlots }
+                    : {}),
+                note: "SCHOOL-program kids only; the write re-checks membership under the family lock so it cannot race a concurrent revert.",
+            },
+        }, async () => unwrap(await api.client.PATCH("/admin/partner/{slug}/kids/{kidId}/slots", {
+            params: { path: { slug, kidId } },
+            body,
+        })));
+    }
+    if (verb === "partner-family") {
+        const familyId = positional(parsed, 2, "family ID");
+        const slug = requireSlug();
+        const enabledRaw = flagString(parsed, "enabled", { required: true });
+        const enabled = assertChoice(enabledRaw, ["true", "false"], "--enabled") ===
+            "true";
+        return writeCommand(parsed, {
+            action: enabled
+                ? "attach this family to the PARTNER institution"
+                : "detach this family from the PARTNER institution",
+            target: { familyId, slug },
+            request: { enabled },
+            details: {
+                scope: "PARTNER programs only — the server refuses SCHOOL institutions here, because school families carry entitlements this generic toggle cannot safely provision or remove (use `school convert`/`school revert`).",
+            },
+        }, async () => unwrap(await api.client.PATCH("/admin/partner/{slug}/families/{familyId}", {
+            params: { path: { slug, familyId } },
+            body: { enabled },
+        })));
+    }
+    if (verb === "logo-upload") {
+        const filePath = flagString(parsed, "file", { required: true });
+        const { bytes, fileName, mimeType, sha256 } = await readLogoFile(filePath);
+        return writeCommand(parsed, {
+            action: "upload this image to the assets CDN as a partner-institution logo (returns a URL for `school create/update --logo-url`)",
+            target: { fileName },
+            request: { fileName, mimeType, bytes: bytes.byteLength, sha256 },
+        }, async () => api.uploadPartnerLogo(bytes, fileName, mimeType));
+    }
     throw new CliError("invalid_arguments", "Unknown school command. Run `recess school --help` for the current command list.");
 }
 //# sourceMappingURL=school.js.map

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>]
@@ -223,6 +228,24 @@ Usage:
     --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]
@@ -309,6 +332,10 @@ Usage:
     [--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]
@@ -366,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
@@ -392,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.2.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"
 }