recess-cli 2.1.0 → 2.2.0

package/dist/cli.js

@@ -9,6 +9,7 @@ import { clearStoredSession, deleteProfile, listProfiles, resolveConfig, savePro
 import { agentContext, buildCommandSchema, scopedHelp, validateInvocation, } from "./command-schema.js";
 import { runApplicationsCommand } from "./commands/applications.js";
 import { runOnboardingCommand } from "./commands/onboarding.js";
+import { runSchoolCommand } from "./commands/school.js";
 import { assertChoice, flagIdList, positional, readJsonFile, readJsonValue, } from "./commands/shared.js";
 import { CliError } from "./errors.js";
 import { listFeedback, submitFeedback } from "./feedback.js";
@@ -1156,6 +1157,14 @@ function parseGoalTemplateDocument(doc) {
         (typeof rawSortOrder !== "number" || !Number.isInteger(rawSortOrder))) {
         throw new CliError("invalid_arguments", 'Template file field "sortOrder" must be an integer.');
     }
+    const rawCoinAmount = doc.coinAmount;
+    if (rawCoinAmount !== undefined &&
+        rawCoinAmount !== null &&
+        (typeof rawCoinAmount !== "number" ||
+            !Number.isInteger(rawCoinAmount) ||
+            rawCoinAmount < 1)) {
+        throw new CliError("invalid_arguments", 'Template file field "coinAmount" must be a positive integer.');
+    }
     const kind = assertChoice(optionalDocString(doc, "kind") ?? "SIMPLE", GOAL_TEMPLATE_KINDS, "kind");
     const setupAudience = assertChoice(optionalDocString(doc, "setupAudience") ?? "KID_FRIENDLY", GOAL_TEMPLATE_SETUP_AUDIENCES, "setupAudience");
     const starterTierRaw = optionalDocString(doc, "starterTier");
@@ -1175,6 +1184,9 @@ function parseGoalTemplateDocument(doc) {
         ...(optionalDocString(doc, "imageUrl") === undefined
             ? {}
             : { imageUrl: optionalDocString(doc, "imageUrl") }),
+        ...(rawCoinAmount === undefined || rawCoinAmount === null
+            ? {}
+            : { coinAmount: rawCoinAmount }),
         ...(optionalDocString(doc, "category") === undefined
             ? {}
             : { category: optionalDocString(doc, "category") }),
@@ -2248,6 +2260,9 @@ export async function runCommand(argv) {
     if (noun === "applications" || noun === "quotes") {
         return runApplicationsCommand({ parsed, api, writeCommand });
     }
+    if (noun === "school") {
+        return runSchoolCommand({ parsed, api, writeCommand });
+    }
     if (noun === "cohorts" && verb === "search") {
         const search = parsed.positionals.slice(2).join(" ").trim();
         if (!search)
@@ -3084,7 +3099,18 @@ export async function runCommand(argv) {
         }
         if (verb === "create") {
             const filePath = flagString(parsed, "file", { required: true });
-            const document = parseGoalTemplateDocument(await readJsonFile(filePath, "Template file"));
+            const authoredDocument = parseGoalTemplateDocument(await readJsonFile(filePath, "Template file"));
+            const coinAmountOverride = flagNumber(parsed, "coin-amount");
+            if (coinAmountOverride !== undefined &&
+                (!Number.isInteger(coinAmountOverride) || coinAmountOverride < 1)) {
+                throw new CliError("invalid_arguments", "--coin-amount must be a positive integer.");
+            }
+            const document = {
+                ...authoredDocument,
+                ...(coinAmountOverride === undefined
+                    ? {}
+                    : { coinAmount: coinAmountOverride }),
+            };
             // C3 read-only preflight, for the same reason `enrollments create` has
             // one: the consequences an approver must weigh are resolved SERVER-side.
             // Which setupHandler runs, what shape of goal students get, and which
@@ -3110,6 +3136,7 @@ export async function runCommand(argv) {
                     category: document.category ?? null,
                     tags: document.tags,
                     isStarter: document.isStarter ?? false,
+                    coinAmount: document.coinAmount ?? null,
                 },
                 details: {
                     resolvedSetupHandler: validation.setupHandler,
@@ -3206,6 +3233,11 @@ export async function runCommand(argv) {
             const tags = flagString(parsed, "tags");
             const kind = flagString(parsed, "kind");
             const sortOrder = flagNumber(parsed, "sort-order");
+            const coinAmount = flagNumber(parsed, "coin-amount");
+            if (coinAmount !== undefined &&
+                (!Number.isInteger(coinAmount) || coinAmount < 1)) {
+                throw new CliError("invalid_arguments", "--coin-amount must be a positive integer.");
+            }
             const isStarterRaw = flagString(parsed, "is-starter");
             const setupAudienceRaw = flagString(parsed, "setup-audience");
             const isStarter = isStarterRaw === undefined
@@ -3222,6 +3254,10 @@ export async function runCommand(argv) {
                 ...(flagString(parsed, "emoji")
                     ? { emoji: flagString(parsed, "emoji") }
                     : {}),
+                ...(flagString(parsed, "image-url")
+                    ? { imageUrl: flagString(parsed, "image-url") }
+                    : {}),
+                ...(coinAmount === undefined ? {} : { coinAmount }),
                 ...(flagString(parsed, "category")
                     ? { category: flagString(parsed, "category") }
                     : {}),
@@ -3259,7 +3295,7 @@ export async function runCommand(argv) {
             // shape that caused the template incident; editing an existing spec goes
             // through the guarded /ai patch path with its destructive-change token.
             if (Object.keys(body).length === 1) {
-                throw new CliError("invalid_arguments", "Pass at least one field to change (--title, --description, --emoji, --category, --tags, --sort-order, --is-starter, --setup-audience, --kind, --agent-instructions-file, --output-template-file).");
+                throw new CliError("invalid_arguments", "Pass at least one field to change (--title, --description, --emoji, --image-url, --coin-amount, --category, --tags, --sort-order, --is-starter, --setup-audience, --kind, --agent-instructions-file, --output-template-file).");
             }
             return writeCommand(parsed, {
                 action: "update goal template metadata (never its setupWorkflowSpec)",
@@ -3270,6 +3306,28 @@ export async function runCommand(argv) {
                 body,
             })));
         }
+        if (verb === "generate-image") {
+            const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
+            const current = unwrap(await api.client.GET("/ai/goal-templates/{id}", {
+                params: { path: { id } },
+            }));
+            const prompt = flagString(parsed, "prompt");
+            return writeCommand(parsed, {
+                action: "queue paid GPT-Image-2 art regeneration",
+                target: {
+                    templateId: id,
+                    slug: current.slug,
+                    title: current.title,
+                },
+                request: { prompt: prompt ?? null },
+                details: {
+                    costNote: "This queues one paid 1024×1024 GPT-Image-2 generation and replaces the template image when it finishes. New templates already generate art automatically.",
+                },
+            }, async () => unwrap(await api.client.POST("/ai/goal-templates/{id}/generate-image", {
+                params: { path: { id } },
+                body: prompt ? { prompt } : {},
+            })));
+        }
         if (verb === "delete") {
             const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
             const expectedVersion = requiredExpectedVersion(parsed);
@@ -3476,9 +3534,31 @@ export async function runCommand(argv) {
                 body: { studentUserId, answers },
             })));
         }
-        throw new CliError("invalid_arguments", "Use goal-templates list|get|versions|validate-spec|create|patch-spec|set-metadata|delete|snapshot-files|capture-snapshot|apply|apply-starter.");
+        throw new CliError("invalid_arguments", "Use goal-templates list|get|versions|validate-spec|create|patch-spec|set-metadata|generate-image|delete|snapshot-files|capture-snapshot|apply|apply-starter.");
     }
     if (noun === "goals" && verb !== "files" && verb !== "pdf") {
+        if (verb === "complete" || verb === "undo-completion") {
+            const goalId = positional(parsed, 2, "goal ID");
+            const undo = verb === "undo-completion";
+            return writeCommand(parsed, {
+                action: undo
+                    ? "undo goal completion and reverse its coin reward"
+                    : "complete a goal and grant its one-time coin reward",
+                target: { goalId },
+                request: { source: "STAFF" },
+                details: undo
+                    ? {
+                        note: "Undo is refused if the student has already spent enough coins that the reward cannot be reversed.",
+                    }
+                    : undefined,
+            }, async () => unwrap(undo
+                ? await api.client.POST("/ai/goals/{goalId}/undo-completion", {
+                    params: { path: { goalId } },
+                })
+                : await api.client.POST("/ai/goals/{goalId}/complete", {
+                    params: { path: { goalId } },
+                })));
+        }
         if (verb === "list") {
             const userId = flagString(parsed, "student", { required: true });
             return unwrap(await api.client.GET("/tutor/browser/students/{userId}/goals/", {
@@ -3789,7 +3869,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|queue|files|pdf.");
+        throw new CliError("invalid_arguments", "Use goals list|create|edit|delete|complete|undo-completion|queue|files|pdf.");
     }
     if (noun === "students") {
         if (verb === "list") {

package/dist/command-schema.js

@@ -15,6 +15,7 @@ const BOOLEAN_FLAGS = new Set([
     "full",
     "help",
     "immediate",
+    "keep-tokens",
     "include-deleted",
     "json",
     "mirrored",

package/dist/commands/onboarding.js

@@ -37,6 +37,17 @@ const LIFECYCLE_PROMPT_KINDS = [
     "TWO_WEEK_CHECK_IN",
     "TWO_MONTH_TESTIMONIAL",
 ];
+// device-pairing.ts PAIRING_TTL_MS — the code dies 5 minutes after it is
+// minted, so the confirm step is what starts the clock, not the preview.
+const PAIRING_CODE_TTL_MINUTES = 5;
+function personName(firstName, lastName, fallback) {
+    return [firstName, lastName].filter(Boolean).join(" ") || fallback;
+}
+function summaryPreview(text, max = 600) {
+    if (!text)
+        return null;
+    return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
+}
 export async function runOnboardingCommand({ parsed, api, writeCommand, }) {
     const noun = parsed.positionals[0] ?? "";
     const verb = parsed.positionals[1] ?? "";
@@ -156,6 +167,26 @@ export async function runOnboardingCommand({ parsed, api, writeCommand, }) {
                 throw error;
             }
         }
+        if (verb === "reviews") {
+            const familyId = positional(parsed, 2, "family ID");
+            // The family workspace's review card: the handoff session(s) for this
+            // family. get.reviews.ts binds the family scope to the canonical (oldest)
+            // guardian — the same one the intake commands operate on — so a
+            // two-guardian family never surfaces the other guardian's session.
+            // `guardianMissing: true` with an empty list means the family has no
+            // guardian at all, not that no session was ever started.
+            return unwrap(await api.client.GET("/ai/onboarding/reviews", {
+                params: { query: { familyId } },
+            }));
+        }
+        if (verb === "review") {
+            const sessionId = positional(parsed, 2, "onboarding session ID");
+            // The full handoff record behind the workspace's handoff page: summary,
+            // collected data, artifacts, progress. Read this before mark-reviewed.
+            return unwrap(await api.client.GET("/ai/onboarding/reviews/{id}", {
+                params: { path: { id: sessionId } },
+            }));
+        }
         if (verb === "intake-session-create") {
             const familyId = positional(parsed, 2, "family ID");
             // The explicit create: get-or-create the intake session. Mints a blank
@@ -616,6 +647,149 @@ export async function runOnboardingCommand({ parsed, api, writeCommand, }) {
                 request: previewRequest,
             }, async () => unwrap(await api.client.POST("/admin/onboarding/families/{familyId}/intake-extract", { params: { path: { familyId } }, body })));
         }
+        if (verb === "contracts") {
+            const kidUserId = flagString(parsed, "kid");
+            // The route takes no filter: it returns the newest 100 contracts across
+            // ALL families (get.contracts.ts), so --kid narrows client-side and a
+            // contract older than that window is simply not in the window.
+            const result = unwrap(await api.client.GET("/admin/enrollment-contracts/"));
+            if (!kidUserId)
+                return result;
+            return {
+                ...result,
+                contracts: result.contracts.filter((contract) => contract.studentUserId === kidUserId),
+                scope: "newest 100 contracts across all families, filtered by --kid",
+            };
+        }
+        if (verb === "send-contract") {
+            const kidUserId = positional(parsed, 2, "kid user ID");
+            const tuitionCents = flagInteger(parsed, "tuition-cents", { min: 0 });
+            const parentEmail = flagString(parsed, "parent-email");
+            const partnerName = flagString(parsed, "partner-name");
+            const partnerEmail = flagString(parsed, "partner-email");
+            // Read-only preflight. Three things the approver must see before a legal
+            // document goes out under someone's name: that this id is the intended
+            // KID, that a live contract is not already out with the parent (the
+            // workspace hides its button in that case — here --resend is the explicit
+            // override), and who the signature request will actually reach.
+            const { user } = unwrap(await api.client.GET("/admin/users/{userId}", {
+                params: { path: { userId: kidUserId } },
+            }));
+            if (user.role !== "KID") {
+                throw new CliError("invalid_arguments", `User ${kidUserId} has role ${user.role}; an enrollment contract is sent for a kid.`);
+            }
+            if (!user.familyId) {
+                throw new CliError("invalid_arguments", `Kid ${kidUserId} has no family, so there is no guardian to sign.`);
+            }
+            const familyId = user.familyId;
+            const [contracts, status] = await Promise.all([
+                unwrap(await api.client.GET("/admin/enrollment-contracts/")),
+                unwrap(await api.client.GET("/admin/onboarding/families/{familyId}/status", {
+                    params: { path: { familyId } },
+                })),
+            ]);
+            const live = contracts.contracts.find((contract) => contract.studentUserId === kidUserId &&
+                contract.status !== "DECLINED" &&
+                contract.status !== "VOIDED");
+            if (live && !hasFlag(parsed, "resend")) {
+                throw new CliError("invalid_arguments", `Contract ${live.id} for this kid is already ${live.status} (sent ${live.sentAt}). Sending again originates a SECOND Documenso document to the parent — pass --resend if that is what you mean.`);
+            }
+            const body = {
+                studentUserId: kidUserId,
+                ...(tuitionCents !== undefined ? { tuitionCents } : {}),
+                ...(parentEmail ? { parentEmail } : {}),
+                ...(partnerName ? { partnerName } : {}),
+                ...(partnerEmail ? { partnerEmail } : {}),
+            };
+            return writeCommand(parsed, {
+                action: "originate the two-signer WonderED enrollment contract (partner signs first, then the parent) and email the signature request",
+                target: { kidUserId, familyId, familyName: status.familyName },
+                request: body,
+                details: {
+                    student: personName(user.firstName, user.lastName, kidUserId),
+                    // The send resolves the family's OLDEST guardian; this is the
+                    // family's predicted parent email (the oldest EMAIL-BEARING
+                    // guardian), so the two can differ when the oldest guardian has no
+                    // email — which is the case the route 400s on. --parent-email pins
+                    // the signer either way.
+                    parentEmailPredicted: status.welcome.recipientEmail,
+                    ...(parentEmail ? { parentEmailOverride: parentEmail } : {}),
+                    tuition: tuitionCents === undefined
+                        ? "resolved server-side from the family's newest ACCEPTED quote (the send 400s when no accepted quote covers this kid) — pass --tuition-cents to pin the amount in this approval"
+                        : `$${(tuitionCents / 100).toFixed(2)}`,
+                    partnerSigner: partnerName || partnerEmail
+                        ? { partnerName, partnerEmail }
+                        : "the WONDERED_SIGNATORY_* env pair",
+                    ...(live
+                        ? {
+                            resend: `Overriding live contract ${live.id} (${live.status}); this creates a SECOND document, it does not replace the first.`,
+                        }
+                        : {}),
+                    note: "Contracts normally auto-send when onboarding finalizes (enrollment-contract-autosend.ts). This command is for families priced after the fact, or whose auto-send was skipped for want of an accepted quote.",
+                },
+            }, async () => unwrap(await api.client.POST("/admin/enrollment-contracts/send/", { body })));
+        }
+        if (verb === "mark-reviewed") {
+            const sessionId = positional(parsed, 2, "onboarding session ID");
+            // Read-only preflight: the human approving this signs their name to a
+            // specific family's handoff, so the preview must carry the summary they
+            // are attesting to — and post.review.ts accepts ONLY HANDED_OFF, so
+            // refuse the states it would reject before the gate, not after approval.
+            const session = unwrap(await api.client.GET("/ai/onboarding/reviews/{id}", {
+                params: { path: { id: sessionId } },
+            }));
+            if (session.status !== "HANDED_OFF" && session.status !== "REVIEWED") {
+                throw new CliError("invalid_arguments", `Onboarding session ${sessionId} is ${session.status}; only a HANDED_OFF session can be marked reviewed. A COMPLETED session still needs the parent confirmation that creates the kid accounts.`);
+            }
+            const reviewer = session.reviewer
+                ? personName(session.reviewer.firstName, session.reviewer.lastName, session.reviewer.id)
+                : null;
+            return writeCommand(parsed, {
+                action: "mark the parent onboarding handoff as reviewed by you",
+                target: { sessionId, familyId: session.familyId },
+                request: {},
+                details: {
+                    status: session.status,
+                    parent: personName(session.parent.firstName, session.parent.lastName, session.parent.email ?? session.parent.id),
+                    handoffSentAt: session.handoffSentAt,
+                    // The stamp attests to THIS text; show it with the approval ask.
+                    handoffSummary: summaryPreview(session.handoffSummary),
+                    fullRecord: `recess --json onboarding review ${sessionId}`,
+                    ...(session.status === "REVIEWED"
+                        ? {
+                            note: `Already reviewed by ${reviewer ?? "another admin"} at ${session.handoffReviewedAt ?? "an unrecorded time"}. Confirming is a first-reviewer-wins no-op that preserves that attribution.`,
+                        }
+                        : {}),
+                },
+            }, async () => unwrap(await api.client.POST("/ai/onboarding/reviews/{id}", {
+                params: { path: { id: sessionId } },
+            })));
+        }
+        if (verb === "pairing-code") {
+            const kidUserId = positional(parsed, 2, "kid user ID");
+            // Read-only preflight: name the exact kid whose account this code signs
+            // in, and refuse a non-KID before the gate (the backend enforces the
+            // same rule, and an admin can pair ANY kid — there is no family fence to
+            // catch a mistyped id).
+            const { user } = unwrap(await api.client.GET("/admin/users/{userId}", {
+                params: { path: { userId: kidUserId } },
+            }));
+            if (user.role !== "KID") {
+                throw new CliError("invalid_arguments", `User ${kidUserId} has role ${user.role}; pairing codes can only be issued for kids.`);
+            }
+            return writeCommand(parsed, {
+                action: "issue a single-use device-pairing code that signs this kid into a new device",
+                target: { kidUserId, familyId: user.familyId },
+                request: { kidUserId },
+                details: {
+                    kid: personName(user.firstName, user.lastName, kidUserId),
+                    expiresInMinutes: PAIRING_CODE_TTL_MINUTES,
+                    credential: "The result is a live sign-in credential (token, shortCode, pairingUrl). Read it to the family for the device in front of them; never paste it into a ticket, log, or shared channel.",
+                },
+            }, async () => unwrap(await api.client.POST("/auth/device-pairing/generate/", {
+                body: { kidUserId },
+            })));
+        }
         throw new CliError("invalid_arguments", "Unknown onboarding command. Run `recess onboarding --help` for the current command list.");
     }
     throw new CliError("invalid_arguments", "Unknown onboarding command.");

package/dist/commands/school.js

@@ -0,0 +1,465 @@
+import { unwrap } from "../api.js";
+import { flagList, flagString, hasFlag } from "../args.js";
+import { CliError } from "../errors.js";
+import { assertChoice, flagInteger, flagIsoInstant, positional, readJsonFile, } from "./shared.js";
+const SCHOOL_TIERS = [
+    "social",
+    "academics",
+    "lite",
+    "complete",
+    "platform",
+];
+const RESOLVE_ACTIONS = ["waive", "cancel"];
+const RECONCILIATION_OUTCOMES = ["refunded", "kept", "written_off"];
+/** post.start-memberships.ts caps the body at ten kids per call. */
+const MEMBERSHIP_KID_LIMIT = 10;
+function dollars(cents) {
+    return `$${(cents / 100).toFixed(2)}`;
+}
+function kidName(firstName, lastName, fallback) {
+    return [firstName, lastName].filter(Boolean).join(" ") || fallback;
+}
+/**
+ * `"<kid-id>:<tier>[:<slots>[:<enrollment-cents>]]"` — the same
+ * colon-delimited per-kid spec `applications enroll --kid` uses. The 4th field
+ * is the child's own first-month charge (":0" = free); OMITTING it inherits the
+ * family-level default, and when neither is given the server refuses the whole
+ * conversion as PRICE_UNDECIDED rather than guessing a price.
+ */
+function parseKidTierSpec(spec) {
+    const [kidId, tier, slots, cents, ...rest] = spec.split(":");
+    if (!kidId || !tier || rest.length > 0) {
+        throw new CliError("invalid_arguments", `--kid "${spec}" must be "<kid-id>:<tier>[:<slots>[:<enrollment-cents>]]".`);
+    }
+    const number = (value, label) => {
+        const parsed = Number(value);
+        if (!Number.isInteger(parsed) || parsed < 0) {
+            throw new CliError("invalid_arguments", `--kid "${spec}": ${label} must be a nonnegative integer.`);
+        }
+        return parsed;
+    };
+    return {
+        kidId,
+        tierId: assertChoice(tier, SCHOOL_TIERS, `--kid "${spec}" tier`),
+        ...(slots ? { slotsPerKid: number(slots, "slots") } : {}),
+        ...(cents
+            ? { enrollmentPaymentCents: number(cents, "enrollment cents") }
+            : {}),
+    };
+}
+export async function runSchoolCommand({ parsed, api, writeCommand, }) {
+    const verb = parsed.positionals[1] ?? "";
+    /**
+     * The school roster is the ONE read behind every command here: it carries the
+     * institution, each family's stage/account state and kids, the live
+     * enrollment payment, and the open reconciliation items. Every write below
+     * previews from this same response, so the approval names the same facts the
+     * dashboard shows rather than a second, differently-shaped guess.
+     */
+    const roster = async (slug) => unwrap(await api.client.GET("/admin/partner/{slug}/families", {
+        params: { path: { slug } },
+    }));
+    const requireSlug = () => flagString(parsed, "school", { required: true });
+    if (verb === "families") {
+        return roster(requireSlug());
+    }
+    if (verb === "list") {
+        return unwrap(await api.client.GET("/admin/partner/"));
+    }
+    if (verb === "family-search") {
+        const search = flagString(parsed, "query", { required: true });
+        const limit = flagInteger(parsed, "limit", { min: 1, max: 100 });
+        return unwrap(await api.client.GET("/admin/partner/{slug}/family-search", {
+            params: {
+                path: { slug: requireSlug() },
+                query: { search, ...(limit !== undefined ? { limit } : {}) },
+            },
+        }));
+    }
+    if (verb === "convert") {
+        const familyId = positional(parsed, 2, "family ID");
+        const slug = requireSlug();
+        const kids = flagList(parsed, "kid").map(parseKidTierSpec);
+        if (kids.length === 0) {
+            throw new CliError("invalid_arguments", '--kid is required, once per kid: "<kid-id>:<tier>[:<slots>[:<enrollment-cents>]]". Every kid in the family must be assigned a tier, same rule as enrollment.');
+        }
+        const creditAmountCents = flagInteger(parsed, "credit-cents", {
+            min: 0,
+            max: 1_000_000,
+        });
+        const enrollmentPaymentCentsPerKid = flagInteger(parsed, "enrollment-payment-cents", { min: 0 });
+        const note = flagString(parsed, "note");
+        const body = {
+            familyId,
+            kids,
+            ...(creditAmountCents !== undefined ? { creditAmountCents } : {}),
+            ...(enrollmentPaymentCentsPerKid !== undefined
+                ? { enrollmentPaymentCentsPerKid }
+                : {}),
+            ...(note ? { note } : {}),
+        };
+        const unpriced = kids.filter((kid) => kid.enrollmentPaymentCents === undefined &&
+            enrollmentPaymentCentsPerKid === undefined);
+        if (unpriced.length > 0) {
+            throw new CliError("invalid_arguments", `No first-month price decided for ${unpriced
+                .map((kid) => kid.kidId)
+                .join(", ")}. Give each kid a 4th spec field (":0" for free) or pass --enrollment-payment-cents for the family; the server refuses an undecided price (PRICE_UNDECIDED).`);
+        }
+        // Read-only preflight on the family's own state — the roster cannot help
+        // here, because a family being converted INTO the program is not on it yet.
+        const status = unwrap(await api.client.GET("/admin/onboarding/families/{familyId}/status", {
+            params: { path: { familyId } },
+        }));
+        const familyKidIds = new Set(status.kids.map((kid) => kid.id));
+        const foreign = kids
+            .map((kid) => kid.kidId)
+            .filter((id) => !familyKidIds.has(id));
+        if (foreign.length > 0) {
+            throw new CliError("invalid_arguments", `Not kids in this family: ${foreign.join(", ")}.`);
+        }
+        const missing = status.kids.filter((kid) => !kids.some((k) => k.kidId === kid.id));
+        return writeCommand(parsed, {
+            action: "convert this marketplace family INTO the school program (links the institution, funds tokens, cancels live memberships)",
+            target: { familyId, slug, familyName: status.familyName },
+            request: body,
+            details: {
+                kids: kids.map((kid) => ({
+                    kid: status.kids.find((row) => row.id === kid.kidId)?.firstName ??
+                        kid.kidId,
+                    tier: kid.tierId,
+                    slots: kid.slotsPerKid ?? "the tier default",
+                    firstMonth: kid.enrollmentPaymentCents === undefined
+                        ? enrollmentPaymentCentsPerKid === undefined
+                            ? "undecided"
+                            : `${dollars(enrollmentPaymentCentsPerKid)} (family default)`
+                        : dollars(kid.enrollmentPaymentCents),
+                })),
+                ...(missing.length > 0
+                    ? {
+                        unassignedKids: missing.map((kid) => kid.firstName ?? kid.id),
+                        unassignedWarning: "These kids of the family were NOT given a tier here. They come out unassigned with 0 slots until an admin picks one.",
+                    }
+                    : {}),
+                consequences: [
+                    "Cancels live membership subscriptions at period end and turns off membership credits.",
+                    "Funds each kid top-up-to-target for the month; a lower --credit-cents is NOT topped back up until the next UTC month (it shares the cron's idempotency key).",
+                    "Existing cohort-enrollment subscriptions are deliberately left running — they migrate to token rails at their next renewal.",
+                    "Any nonzero total holds the family at PENDING_PAYMENT and gates them out of the parent app until they pay at /school/pay.",
+                    "ADMIN-only (exact-admin): a GUIDE or PROGRAM session gets 403.",
+                ],
+                reverse: `The inverse is \`school revert ${familyId} --school ${slug}\`, which is fenced off in production.`,
+            },
+        }, async () => unwrap(await api.client.POST("/admin/partner/{slug}/convert-family", {
+            params: { path: { slug } },
+            body,
+        })));
+    }
+    if (verb === "revert") {
+        const familyId = positional(parsed, 2, "family ID");
+        const slug = requireSlug();
+        const revokeTokens = !hasFlag(parsed, "keep-tokens");
+        const note = flagString(parsed, "note");
+        const { institution, families } = await roster(slug);
+        const family = families.find((row) => row.id === familyId);
+        if (!family) {
+            throw new CliError("invalid_arguments", `Family ${familyId} is not in ${institution.name} (${slug}). Revert only applies to a family currently in that school program.`);
+        }
+        return writeCommand(parsed, {
+            action: "convert this family OUT of the school program and back to marketplace billing",
+            target: { familyId, slug, familyName: family.name },
+            request: { familyId, revokeTokens, ...(note ? { note } : {}) },
+            details: {
+                institution: institution.name,
+                accountState: family.accountState,
+                onboardingStage: family.onboardingStage,
+                kids: family.kids.map((kid) => ({
+                    id: kid.id,
+                    name: kidName(kid.firstName, kid.lastName, kid.id),
+                    creditBalance: kid.creditBalance,
+                })),
+                revokeTokens,
+                liveEnrollmentPayment: family.liveEnrollmentPayment
+                    ? {
+                        id: family.liveEnrollmentPayment.id,
+                        status: family.liveEnrollmentPayment.status,
+                        amountDue: dollars(family.liveEnrollmentPayment.amountDueCents),
+                    }
+                    : null,
+                consequences: [
+                    revokeTokens
+                        ? "Revokes each kid's remaining school token balance (shown above)."
+                        : "LEAVES each kid's school token balance in place (--keep-tokens).",
+                    "Cancels the family's program membership; kids come out with NO membership. The follow-up is `school start-memberships`, which charges their card.",
+                    "Class registrations keep running on purpose — they start billing the family's own card at renewal.",
+                    "ADMIN-only (exact-admin): a GUIDE or PROGRAM session gets 403.",
+                ],
+                fence: "Gated on SCHOOL_REVERT_ENABLED, which is fail-closed and unset in every deployed environment — production refuses until settlement ships. A 409 here is that door, not a bad request.",
+                retry: "A 409 `revert_in_flight` means an earlier attempt is still settling; rerun the unchanged command with the SAME operation key rather than minting a new one.",
+            },
+        }, async () => unwrap(await api.client.POST("/admin/partner/{slug}/revert-family", {
+            params: { path: { slug } },
+            // Announce that this client reads the two-phase union; without the
+            // header the server sends the pre-union façade, which reports a
+            // still-settling revert as finished (revert-wire.ts).
+            headers: { "x-recess-revert-union": "1" },
+            body: { familyId, revokeTokens, ...(note ? { note } : {}) },
+        })));
+    }
+    if (verb === "start-memberships") {
+        const familyId = positional(parsed, 2, "family ID");
+        // --kid is REPEATABLE: read every occurrence, not just the last one.
+        const kidIds = flagList(parsed, "kid");
+        if (kidIds.length === 0) {
+            throw new CliError("invalid_arguments", "--kid is required: name each kid whose membership should start.");
+        }
+        if (kidIds.length > MEMBERSHIP_KID_LIMIT) {
+            throw new CliError("invalid_arguments", `--kid accepts at most ${MEMBERSHIP_KID_LIMIT} kids per call.`);
+        }
+        // Family-scoped, not slug-scoped: by the time this runs the family is no
+        // longer linked to a partner institution, so the roster read above cannot
+        // see it. The onboarding status is the read that still resolves.
+        const status = unwrap(await api.client.GET("/admin/onboarding/families/{familyId}/status", {
+            params: { path: { familyId } },
+        }));
+        const known = new Map(status.kids.map((kid) => [kid.id, kid]));
+        const unknown = kidIds.filter((id) => !known.has(id));
+        if (unknown.length > 0) {
+            throw new CliError("invalid_arguments", `Not kids in this family: ${unknown.join(", ")}. The server refuses the whole call when one id is foreign.`);
+        }
+        return writeCommand(parsed, {
+            action: "start a paid membership subscription for these kids, CHARGING the family's card on file",
+            target: { familyId, familyName: status.familyName },
+            request: { familyId, kidIds },
+            details: {
+                kids: kidIds.map((id) => kidName(known.get(id)?.firstName ?? null, null, id)),
+                billing: "Default membership price unless the family is grandfathered onto one, with a 1-day trial, confirmed against the customer's saved default payment method.",
+                note: "A kid whose membership is already ACTIVE comes back `skipped_active` rather than being charged twice; per-kid failures are reported in `results`, not thrown.",
+            },
+        }, async () => unwrap(await api.client.POST("/admin/memberships/start", {
+            body: { familyId, kidIds },
+        })));
+    }
+    if (verb === "resolve-payment") {
+        const paymentId = positional(parsed, 2, "enrollment payment ID");
+        const slug = requireSlug();
+        const action = assertChoice(flagString(parsed, "action", { required: true }), RESOLVE_ACTIONS, "--action");
+        const note = flagString(parsed, "note");
+        const { institution, families } = await roster(slug);
+        const family = families.find((row) => row.liveEnrollmentPayment?.id === paymentId);
+        const payment = family?.liveEnrollmentPayment;
+        if (!family || !payment) {
+            throw new CliError("invalid_arguments", `No live enrollment payment ${paymentId} under ${institution.name} (${slug}). Run \`school families --school ${slug}\` and read \`liveEnrollmentPayment\`; a payment already resolved is not resolvable again.`);
+        }
+        return writeCommand(parsed, {
+            action: action === "waive"
+                ? "WAIVE this enrollment charge — record it as collected off-platform and lift the paywall"
+                : "CANCEL this enrollment charge — drop the requirement entirely and lift the paywall",
+            target: {
+                paymentId,
+                slug,
+                familyId: family.id,
+                familyName: family.name,
+            },
+            request: { action, ...(note ? { note } : {}) },
+            details: {
+                institution: institution.name,
+                status: payment.status,
+                amountDue: dollars(payment.amountDueCents),
+                lines: payment.lines.map((line) => ({
+                    kid: line.firstName ?? line.kidId ?? "unassigned",
+                    amount: dollars(line.amountCents),
+                })),
+                stripeInvoiceId: payment.stripeInvoiceId,
+                effect: "The family stops being redirected to /school/pay and class registration reopens — but ONLY if no other PENDING enrollment payment remains on the family.",
+                accountState: "PENDING_PAYMENT is walked back; a family separately set to PAUSED or BOOTED keeps that state.",
+                ...(action === "cancel"
+                    ? {
+                        cancelCaveat: "If a charge already landed, compensation is unproven and the wire status comes back CANCEL_REQUESTED — the row is still live and still blocking. That is not a failed call.",
+                    }
+                    : {}),
+            },
+        }, async () => unwrap(await api.client.POST("/admin/partner/{slug}/enrollment-payments/{paymentId}/resolve", {
+            params: { path: { slug, paymentId } },
+            body: { action, ...(note ? { note } : {}) },
+        })));
+    }
+    if (verb === "close-reconciliation") {
+        const paymentId = positional(parsed, 2, "enrollment payment ID");
+        const slug = requireSlug();
+        const outcome = assertChoice(flagString(parsed, "outcome", { required: true }), RECONCILIATION_OUTCOMES, "--outcome");
+        const note = flagString(parsed, "note");
+        const { institution, families } = await roster(slug);
+        const family = families.find((row) => row.reconciliationItems.some((item) => item.paymentId === paymentId));
+        const item = family?.reconciliationItems.find((row) => row.paymentId === paymentId);
+        if (!family || !item) {
+            throw new CliError("invalid_arguments", `No reconciliation item for payment ${paymentId} under ${institution.name} (${slug}). Run \`school families --school ${slug}\` and read \`reconciliationItems\`.`);
+        }
+        if (item.resolution) {
+            throw new CliError("invalid_arguments", `That reconciliation item was already closed as ${item.resolution.outcome} at ${item.resolution.resolvedAt}. The close is conditional and irreversible — a second one 409s.`);
+        }
+        return writeCommand(parsed, {
+            action: `close this reconciliation item as ${outcome} (a money decision, and irreversible)`,
+            target: {
+                paymentId,
+                slug,
+                familyId: family.id,
+                familyName: family.name,
+            },
+            request: { outcome, ...(note ? { note } : {}) },
+            details: {
+                institution: institution.name,
+                amountPaid: dollars(item.amountPaidCents),
+                openedBecause: item.reason,
+                openedAt: item.openedAt,
+                paymentStatus: item.status,
+                invoiceId: item.invoiceId,
+                meaning: {
+                    refunded: "the money was returned to the family",
+                    kept: "the family genuinely owed it, so the charge stands",
+                    written_off: "neither — the business absorbed it",
+                }[outcome],
+                scope: "Bookkeeping only: this annotates the item, never deletes it, and does NOT settle a debt, unblock a family, or move the payment's status.",
+                irreversible: "The write is conditional on the item still being open, so every later attempt 409s and the item drops out of triage.",
+            },
+        }, async () => unwrap(await api.client.POST("/admin/partner/{slug}/enrollment-payments/{paymentId}/close-reconciliation", {
+            params: { path: { slug, paymentId } },
+            body: { outcome, ...(note ? { note } : {}) },
+        })));
+    }
+    if (verb === "codes") {
+        const subverb = parsed.positionals[2] ?? "";
+        const slug = requireSlug();
+        const codeId = () => positional(parsed, 3, "invite code ID");
+        if (subverb === "list") {
+            return unwrap(await api.client.GET("/admin/partner/{slug}/codes", {
+                params: { path: { slug } },
+            }));
+        }
+        if (subverb === "get") {
+            return unwrap(await api.client.GET("/admin/partner/{slug}/codes/{id}", {
+                params: { path: { slug, id: codeId() } },
+            }));
+        }
+        if (subverb === "create") {
+            const count = flagInteger(parsed, "count", { min: 1 });
+            const expiresAt = flagIsoInstant(parsed, "expires-at");
+            const note = flagString(parsed, "note");
+            const creditAmountCents = flagInteger(parsed, "credit-cents", { min: 0 });
+            const tierRaw = flagString(parsed, "tier");
+            const slotsPerKid = flagInteger(parsed, "slots", { min: 0, max: 20 });
+            const enrollmentPaymentCentsPerKid = flagInteger(parsed, "enrollment-payment-cents", { min: 0 });
+            const dataFile = flagString(parsed, "data-file");
+            // The preconfigured-invite `family` block (parent identity + the kid
+            // roster with per-kid tier and price) is a nested object, so it arrives
+            // as JSON the way `quotes create` takes its body. Without it this mints
+            // blank codes; with it, one addressed invite that emails the parent.
+            const family = dataFile
+                ? (await readJsonFile(dataFile, "Preconfigured invite file"))
+                : undefined;
+            const body = {
+                ...(count !== undefined ? { count } : {}),
+                ...(expiresAt ? { expiresAt } : {}),
+                ...(note ? { note } : {}),
+                ...(creditAmountCents !== undefined ? { creditAmountCents } : {}),
+                ...(tierRaw
+                    ? { tierId: assertChoice(tierRaw, SCHOOL_TIERS, "--tier") }
+                    : {}),
+                ...(slotsPerKid !== undefined ? { slotsPerKid } : {}),
+                ...(enrollmentPaymentCentsPerKid !== undefined
+                    ? { enrollmentPaymentCentsPerKid }
+                    : {}),
+                ...(family ? { family } : {}),
+            };
+            return writeCommand(parsed, {
+                action: family
+                    ? "mint a preconfigured school invite for this family and EMAIL the parent their claim link"
+                    : `mint ${count ?? 1} blank school invite code(s)`,
+                target: { slug },
+                request: body,
+                details: {
+                    expiresAt: expiresAt ?? "the institution default",
+                    firstMonthPerKid: enrollmentPaymentCentsPerKid === undefined
+                        ? "not set at the family level — each kid in --data-file must carry its own price"
+                        : dollars(enrollmentPaymentCentsPerKid),
+                    ...(family
+                        ? {
+                            duplicateGuard: "The create 409s when the parent email already has a Recess account or another live invite. That is the guard, not a transient failure.",
+                        }
+                        : {
+                            blank: "No --data-file, so these are blank codes: nobody is emailed and no roster is preconfigured.",
+                        }),
+                },
+            }, async () => unwrap(await api.client.POST("/admin/partner/{slug}/codes", {
+                params: { path: { slug } },
+                body,
+            })));
+        }
+        if (subverb === "set-kids") {
+            const id = codeId();
+            const body = (await readJsonFile(flagString(parsed, "data-file", { required: true }), "Invite roster file"));
+            return writeCommand(parsed, {
+                action: "edit an UNREDEEMED invite's roster in place — the parent's existing link keeps working",
+                target: { slug, codeId: id },
+                request: body,
+                details: {
+                    semantics: "The body is the FULL roster, not a diff: a student absent from the list is removed. `enrollmentPaymentCents` is required per student (null or 0 = that student enrolls free) so the paywall cannot be dropped by omission.",
+                    outOfScope: "Parent identity, note, credit and expiry are not editable here — changing WHO the invite is for is `codes replace`.",
+                    refusal: "Editing after redemption is refused outright; the accounts and the charge already exist.",
+                },
+            }, async () => unwrap(await api.client.PATCH("/admin/partner/{slug}/codes/{id}", {
+                params: { path: { slug, id } },
+                body,
+            })));
+        }
+        if (subverb === "replace") {
+            const id = codeId();
+            const body = (await readJsonFile(flagString(parsed, "data-file", { required: true }), "Replacement invite file"));
+            return writeCommand(parsed, {
+                action: "REPLACE this unredeemed invite: delete the old code and mint a new one, emailing the parent a fresh link",
+                target: { slug, codeId: id },
+                request: body,
+                details: {
+                    atomicity: "Delete and create run in ONE transaction, so a failure rolls back and the OLD invite survives — a failed replace is plainly retryable and never leaves the family with no invite.",
+                    whenToUse: "Use replace when the parent's identity or email changes; use `codes set-kids` to edit the roster without invalidating the link the parent already holds.",
+                    inherits: "Fields omitted from the body (note, credit) inherit from the old row read inside the transaction.",
+                },
+            }, async () => unwrap(await api.client.POST("/admin/partner/{slug}/codes/{id}/replace", {
+                params: { path: { slug, id } },
+                body,
+            })));
+        }
+        if (subverb === "resend") {
+            const id = codeId();
+            return writeCommand(parsed, {
+                action: "re-email this invite's claim link to the parent on file",
+                target: { slug, codeId: id },
+                request: {},
+                details: {
+                    outwardEmail: "This sends mail to a real family. The code itself is unchanged — use `codes replace` to mint a new one.",
+                },
+            }, async () => unwrap(await api.client.POST("/admin/partner/{slug}/codes/{id}/resend", {
+                params: { path: { slug, id } },
+            })));
+        }
+        if (subverb === "revoke") {
+            const id = codeId();
+            const existing = unwrap(await api.client.GET("/admin/partner/{slug}/codes/{id}", {
+                params: { path: { slug, id } },
+            }));
+            return writeCommand(parsed, {
+                action: "HARD-DELETE this unredeemed invite code",
+                target: { slug, codeId: id },
+                request: {},
+                details: {
+                    code: existing,
+                    irreversible: "The row is REMOVED, not soft-deleted: there is no deletedAt on TalentSchoolInviteCode and no undo. The parent's link stops working immediately.",
+                },
+            }, async () => unwrap(await api.client.DELETE("/admin/partner/{slug}/codes/{id}", {
+                params: { path: { slug, id } },
+            })));
+        }
+        throw new CliError("invalid_arguments", "Use school codes list|get|create|set-kids|replace|resend|revoke.");
+    }
+    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

@@ -142,6 +142,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 +167,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 +194,35 @@ 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] 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 +274,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 +307,8 @@ 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 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]

package/package.json

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