recess-cli 1.0.0

package/dist/cli.js

@@ -0,0 +1,1537 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { RecessAdminApi, unwrap } from "./api.js";
+import { flagNumber, flagString, hasFlag, parseArgs, } from "./args.js";
+import { login, pollDeviceAuth, requestDeviceAuth } from "./auth.js";
+import { clearStoredSession, resolveConfig, } from "./config.js";
+import { CliError } from "./errors.js";
+import { requireConfirmation } from "./safety.js";
+import { installSkill, isEphemeralInstall } from "./setup.js";
+export const HELP = `recess — safe Recess administration from the command line
+
+Usage:
+  recess [--json] setup [--skill-only]
+  recess [--json] doctor
+  recess [--json] auth login [--client-id ID] [--callback-port 8765]
+  recess [--json] auth request [--label TEXT]
+  recess [--json] auth poll [--timeout 300]
+  recess [--json] auth status|logout
+  recess [--json] users search <name-or-id> [--limit 10]
+  recess [--json] users get <user-id>
+  recess [--json] users tier list-tiers
+  recess [--json] users tier get <kid-id>
+  recess [--json] users tier preview <kid-id> --tier social|academics|lite|complete|platform
+    [--slots N]
+  recess [--json] users tier set <kid-id> --tier social|academics|lite|complete|platform
+    [--slots N] --expected-updated-at <iso> [--allow-strand] [--confirm]
+  recess [--json] students upload-map-scores --student <kid-id>
+    --file </path/to/map-report.pdf> [--confirm]
+  recess [--json] enrollments list --user <user-id>
+  recess [--json] subscriptions list --family <family-id> [--kid <kid-id>]
+  recess [--json] invoices list --subscription <subscription-id>
+  recess [--json] billing pause --subscription <id> [--until ISO_DATE] [--confirm]
+  recess [--json] billing resume --subscription <id> [--confirm]
+  recess [--json] invoices refund --invoice <id> --line-item <id>
+    --method refund|credit|tokens [--full | --amount-cents N]
+    [--who-pays guide|recess] [--reason TEXT] [--confirm]
+  recess [--json] cohorts search <query>
+  recess [--json] enrollments create --user <kid-id> --cohort <id>
+    [--first-charge-at ISO_DATETIME] [--send-email] [--force] [--confirm]
+  recess [--json] enrollments register-cohort --enrollment <id>
+    --user <id> --cohort <id> [--confirm]
+  recess [--json] enrollments unregister-cohort --user <id>
+    --cohort <id> [--confirm]
+  recess [--json] enrollments get-for-subscription --subscription <id>
+  recess [--json] billing extend-trial --subscription <id>
+    --trial-end ISO_DATE [--confirm]
+  recess [--json] billing cancel-subscription --subscription <id>
+    [--immediate] [--reason TEXT] [--restore] [--confirm]
+  recess [--json] payout payruns list [--status A,B] [--schedule <id>]
+  recess [--json] payout recipients list [--search <name>] [--user <id>] [--id <id>]
+  recess [--json] payout invoices list [--payrun <id>] [--recipient <account-id>]
+    [--user <id>] [--status A,B]   (at least one filter)
+  recess [--json] payout invoices get <invoice-id>
+  recess [--json] payout invoices set-status <invoice-id>
+    --status IN_REVIEW|OPEN|PAID|CANCELED [--send-email] [--confirm]
+  recess [--json] payout items add --invoice <id> --amount-cents N
+    --description TEXT [--date YYYY-MM-DD] [--confirm]
+  recess [--json] payout items edit <item-id> [--amount-cents N]
+    [--description TEXT] [--date YYYY-MM-DD] [--confirm]
+  recess [--json] payout items delete <item-id> [--confirm]
+  recess [--json] cohorts get <cohort-id> [--events-tab ACTIVE|ENDED|CANCELED|ARCHIVED]
+  recess [--json] cohorts parent-emails <cohort-id>
+  recess [--json] cohorts end <cohort-id> [--cancel-subscriptions] [--confirm]
+  recess [--json] cohorts pause-billing <cohort-id> --weeks 1..6 [--confirm]
+  recess [--json] cohorts resume-billing <cohort-id> [--confirm]
+  recess [--json] cohorts email <cohort-id> --target ALL_PARENTS|ALL_PARENTS_GUIDES
+    --content TEXT [--confirm]
+  recess [--json] events get <event-id>
+  recess [--json] events take-attendance <event-id> --attended <id,id,...>
+    [--absent <id,id,...>] [--excused <id,id,...>] [--confirm]
+  recess [--json] events cancel <event-id> --reason TEXT [--confirm]
+  recess [--json] events set-status <event-id> --status ACTIVE|ENDED|CANCELED [--confirm]
+  recess [--json] events reschedule --cohort <id> --event <event-id>
+    --starts-at "YYYY-MM-DDTHH:MM" [--timezone <iana>] [--length-mins N] [--confirm]
+  recess [--json] events add --cohort <id> --starts-at "YYYY-MM-DDTHH:MM"
+    [--timezone <iana>] [--length-mins N] [--confirm]
+  recess [--json] registrations approve --registration <id> [--confirm]
+  recess [--json] registrations deny --cohort <id> --user <id> [--confirm]
+  recess [--json] request get </path?query=value>
+  recess [--json] onboarding status <family-id>
+  recess [--json] onboarding kids [--time-period-days N] [--cohort <id>]
+    [--limit N] [--stage-filter all|scheduled|oriented|course|converted|lost]
+  recess [--json] onboarding intake-session <family-id>
+  recess [--json] onboarding intake-session-create <family-id> [--confirm]
+  recess [--json] onboarding set-stage <family-id>
+    --stage LEGACY|PROVISIONED|PARENT_CONFIRMED|CLEARED_FOR_COHORT|COMPLETE [--confirm]
+  recess [--json] onboarding set-account-state <family-id>
+    --state ACTIVE|PENDING_PAYMENT|PAUSED|BOOTED [--note TEXT] [--confirm]
+  recess [--json] onboarding attest <family-id>
+    --condition app_downloaded|tutor_met|goals_loaded|ma_diagnostic [--revoke]
+    [--note TEXT] [--confirm]
+  recess [--json] onboarding set-intake <family-id> --session <id>
+    --data <json> [--expected-updated-at <iso>] [--confirm]
+  recess [--json] onboarding extract <family-id> --session <id>
+    (--transcript-file <path> | --granola <ref>) [--confirm]
+  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]
+    [--visual-only] [--confirm]
+  recess [--json] village models publish|archive <model-id> [--world village-1] [--confirm]
+  recess [--json] village models place <model-id> --x N --z N
+    [--y N] [--rotation 0..3] [--mirrored] [--no-collision] [--batch ID]
+    [--world village-1] [--confirm]
+  recess [--json] village models move <placement-id> --x N --z N
+    [--y N] [--rotation 0..3] [--mirrored] [--world village-1] [--confirm]
+  recess [--json] village models remove <placement-id> [--world village-1] [--confirm]
+  recess [--json] village render --min-x N --min-z N --max-x N --max-z N
+    [--world village-1]
+
+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
+mints a blank session, so it is gated behind --confirm. "set-stage" reads the
+current stage first and warns when a move re-locks progress; CLEARED_FOR_COHORT
+unlocks cohort registration. "set-account-state" PAUSED/BOOTED lock the family out of paid
+capabilities (--note is analytics-only). "set-intake --data" takes JSON (agents
+drive it with --json; humans rarely will); the preview is offline. Its
+optimistic-concurrency token resolves only on --confirm: pass
+--expected-updated-at <iso> (from an intake-session read's updatedAt) for strict
+CAS that 409s if a parent autosaved since; omit it and the CLI fetches the
+current token at confirm time and warns that post-preview edits are unprotected.
+"extract" is LLM-bound and can take ~30s; a 503 means Granola is not configured
+server-side.
+
+Class-ops notes: "events cancel" notifies families (chat + parent email blast +
+credit notes + Slack); "events set-status --status CANCELED" is a silent status
+change. Reschedule times are cohort-local wall-clock (zoneless).
+
+Payout notes: amounts are integer cents. "payout items add" without --date
+defaults the item date to the penultimate day of the invoice's cycle (its
+endDate minus one day) and shows the computed date in the preview.
+
+Auth notes: "auth login" runs the browser loopback flow (local use). For a headless
+cloud agent, "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.
+
+Writes preview and exit 2 unless --confirm is supplied after explicit human approval.
+Environment overrides: RECESS_CLI_API_ORIGIN, RECESS_CLI_WEB_ORIGIN,
+RECESS_CLI_OAUTH_CLIENT_ID, RECESS_CLI_COOKIE, RECESS_CLI_CONFIG.`;
+function positional(parsed, index, label) {
+    const value = parsed.positionals[index];
+    if (!value) {
+        throw new CliError("invalid_arguments", `Missing ${label}.`);
+    }
+    return value;
+}
+async function sessionStatus(config) {
+    if (!config.sessionCookie) {
+        return {
+            authenticated: false,
+            authSource: "missing",
+            message: "Run `recess auth login`.",
+        };
+    }
+    const api = new RecessAdminApi(config);
+    const result = await api.client.GET("/auth/admin-cli/session/");
+    if (!result.response.ok || !result.data) {
+        return {
+            authenticated: false,
+            authSource: config.authSource,
+            status: result.response.status,
+            expiresAt: config.sessionExpiresAt ?? null,
+            message: "The stored admin session is invalid or expired. Run `recess auth login`.",
+        };
+    }
+    return { ...result.data, authSource: config.authSource };
+}
+async function doctor(config) {
+    const checks = {
+        config: {
+            path: config.configPath,
+            apiOrigin: config.apiOrigin,
+            webOrigin: config.webOrigin,
+            oauthClientIdConfigured: Boolean(config.oauthClientId),
+        },
+        auth: await sessionStatus(config),
+    };
+    try {
+        const response = await fetch(new URL("/health", config.apiOrigin), {
+            signal: AbortSignal.timeout(5000),
+        });
+        checks.api = { reachable: response.ok, status: response.status };
+    }
+    catch (error) {
+        checks.api = {
+            reachable: false,
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+    return checks;
+}
+async function writeCommand(parsed, preview, execute) {
+    requireConfirmation(hasFlag(parsed, "confirm"), preview);
+    return execute();
+}
+function assertChoice(value, choices, label) {
+    if (!choices.includes(value)) {
+        throw new CliError("invalid_arguments", `${label} must be one of: ${choices.join(", ")}.`);
+    }
+    return value;
+}
+const PAYRUN_STATUSES = [
+    "UPCOMING",
+    "DRAFT",
+    "IN_REVIEW",
+    "APPROVED",
+    "PAID",
+    "CANCELED",
+];
+const PAYOUT_INVOICE_STATUSES = [
+    "DRAFT",
+    "IN_REVIEW",
+    "OPEN",
+    "PENDING_PAYMENT",
+    "PAID",
+    "CANCELED",
+];
+// The guide email on IN_REVIEW/OPEN only fires when sendEmail is true.
+const PAYOUT_STATUS_SIDE_EFFECTS = {
+    IN_REVIEW: "moves the invoice into review",
+    OPEN: "FINALIZES the invoice: adds its total to the recipient's account balance",
+    PAID: "marks the invoice paid and deducts its total from the recipient's account balance",
+    CANCELED: "cancels the invoice and reverses any balance items carried on it",
+};
+// Ascending onboarding stage order (mirrors STAGE_ORDER in
+// apps/web-server/src/libs/onboarding-stage.ts); a lower index is earlier
+// progress, so a target below the current stage is a backward move.
+const ONBOARDING_STAGES = [
+    "LEGACY",
+    "PROVISIONED",
+    "PARENT_CONFIRMED",
+    "CLEARED_FOR_COHORT",
+    "COMPLETE",
+];
+// What each stage unlocks/implies, surfaced in the set-stage preview.
+const ONBOARDING_STAGE_SIDE_EFFECTS = {
+    LEGACY: "the pre-onboarding baseline",
+    PROVISIONED: "kid accounts provisioned, awaiting parent confirmation",
+    PARENT_CONFIRMED: "parent has confirmed setup",
+    CLEARED_FOR_COHORT: "unlocks cohort registration for school families",
+    COMPLETE: "onboarding finished",
+};
+const ONBOARDING_ACCOUNT_STATES = [
+    "ACTIVE",
+    "PENDING_PAYMENT",
+    "PAUSED",
+    "BOOTED",
+];
+const ONBOARDING_CONDITIONS = [
+    "app_downloaded",
+    "tutor_met",
+    "goals_loaded",
+    "ma_diagnostic",
+];
+const SCHOOL_TIER_OPTIONS = [
+    { id: "social", name: "Social", defaultClassSlots: 2 },
+    { id: "academics", name: "Academics", defaultClassSlots: 0 },
+    { id: "lite", name: "Lite", defaultClassSlots: 1 },
+    { id: "complete", name: "Complete", defaultClassSlots: 3 },
+    { id: "platform", name: "Platform Only", defaultClassSlots: 0 },
+];
+const SCHOOL_TIER_IDS = SCHOOL_TIER_OPTIONS.map((tier) => tier.id);
+const MAX_MAP_PDF_BYTES = 15 * 1024 * 1024;
+async function readMapScorePdf(filePath) {
+    const absolutePath = path.resolve(filePath);
+    if (path.extname(absolutePath).toLowerCase() !== ".pdf") {
+        throw new CliError("invalid_arguments", "--file must point to a PDF report.");
+    }
+    let stat;
+    try {
+        stat = await fs.stat(absolutePath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new CliError("invalid_arguments", `MAP score PDF does not exist: ${absolutePath}`);
+        }
+        throw error;
+    }
+    if (!stat.isFile()) {
+        throw new CliError("invalid_arguments", `MAP score PDF is not a regular file: ${absolutePath}`);
+    }
+    if (stat.size === 0) {
+        throw new CliError("invalid_arguments", "MAP score PDF is empty.");
+    }
+    if (stat.size > MAX_MAP_PDF_BYTES) {
+        throw new CliError("invalid_arguments", "MAP score PDF exceeds the 15 MB upload limit.");
+    }
+    const bytes = await fs.readFile(absolutePath);
+    return {
+        absolutePath,
+        bytes,
+        fileName: path.basename(absolutePath),
+        sha256: createHash("sha256").update(bytes).digest("hex"),
+    };
+}
+function flagStatusList(parsed, name, choices) {
+    const raw = flagString(parsed, name);
+    if (raw === undefined)
+        return undefined;
+    const values = raw
+        .split(",")
+        .map((value) => value.trim())
+        .filter(Boolean);
+    if (values.length === 0) {
+        throw new CliError("invalid_arguments", `--${name} requires a value.`);
+    }
+    return values.map((value) => assertChoice(value, choices, `--${name}`));
+}
+function flagCents(parsed, name, options = {}) {
+    const value = flagNumber(parsed, name);
+    if (value === undefined) {
+        if (options.required) {
+            throw new CliError("invalid_arguments", `Missing required --${name}.`);
+        }
+        return undefined;
+    }
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new CliError("invalid_arguments", `--${name} must be a positive integer number of cents.`);
+    }
+    return value;
+}
+function flagItemDateMs(parsed) {
+    const raw = flagString(parsed, "date");
+    if (raw === undefined)
+        return undefined;
+    // A bare YYYY-MM-DD is anchored to UTC noon so the calendar day survives
+    // timezone conversion on the server.
+    const iso = /^\d{4}-\d{2}-\d{2}$/.test(raw) ? `${raw}T12:00:00.000Z` : raw;
+    const ms = Date.parse(iso);
+    if (!Number.isFinite(ms)) {
+        throw new CliError("invalid_arguments", "--date must be YYYY-MM-DD or a full ISO timestamp.");
+    }
+    return ms;
+}
+const DAY_MS = 24 * 60 * 60 * 1000;
+// The cohort event routes take zoneless local wall-clock datetimes
+// (interpreted in the cohort's timezone server-side).
+function flagLocalDateTime(parsed, name, options = {}) {
+    const raw = flagString(parsed, name, options);
+    if (raw === undefined)
+        return undefined;
+    const match = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2})(:\d{2})?$/.exec(raw);
+    if (!match) {
+        throw new CliError("invalid_arguments", `--${name} must be a zoneless local datetime like 2026-07-20T15:00 (no timezone offset).`);
+    }
+    return match[2] ? raw : `${raw}:00`;
+}
+function flagIdList(parsed, name) {
+    const raw = flagString(parsed, name);
+    if (raw === undefined)
+        return [];
+    const ids = raw
+        .split(",")
+        .map((value) => value.trim())
+        .filter(Boolean);
+    if (ids.length === 0) {
+        throw new CliError("invalid_arguments", `--${name} requires a value.`);
+    }
+    return ids;
+}
+export function penultimateCycleDayMs(cycleEndDate) {
+    const endMs = Date.parse(cycleEndDate);
+    if (!Number.isFinite(endMs)) {
+        throw new CliError("api_error", `Invoice endDate is not a valid date: ${cycleEndDate}`);
+    }
+    return endMs - DAY_MS;
+}
+async function resolveSchoolKidContext(api, kidId) {
+    const search = unwrap(await api.client.GET("/admin/users/operations-search", {
+        params: { query: { search: kidId, limit: 1 } },
+    }));
+    const result = search.results.find((candidate) => candidate.members.some((member) => member.id === kidId));
+    const kid = result?.members.find((member) => member.id === kidId);
+    if (!result || !kid) {
+        throw new CliError("not_found", `No user found for ${kidId}.`);
+    }
+    if (kid.role !== "KID") {
+        throw new CliError("invalid_arguments", `School tiers can only be read or set for KID users; ${kidId} is ${kid.role}.`);
+    }
+    if (!result.family) {
+        throw new CliError("not_found", `Kid ${kidId} does not belong to a family with a school institution.`);
+    }
+    const status = unwrap(await api.client.GET("/admin/onboarding/families/{familyId}/status", {
+        params: { path: { familyId: result.family.id } },
+    }));
+    if (!status.kids.some((candidate) => candidate.id === kidId)) {
+        throw new CliError("not_found", `Kid ${kidId} was not found in family ${result.family.id}.`);
+    }
+    if (status.programType !== "SCHOOL" || !status.partnerSlug) {
+        throw new CliError("invalid_arguments", `Kid ${kidId} is not assigned to an internal school program.`);
+    }
+    return {
+        familyId: result.family.id,
+        institutionSlug: status.partnerSlug,
+    };
+}
+function tierSlots(parsed) {
+    const slots = flagNumber(parsed, "slots");
+    if (slots !== undefined &&
+        (!Number.isInteger(slots) || slots < 0 || slots > 20)) {
+        throw new CliError("invalid_arguments", "--slots must be an integer from 0 through 20.");
+    }
+    return slots;
+}
+export async function runCommand(argv) {
+    const parsed = parseArgs(argv);
+    const [noun, verb] = parsed.positionals;
+    if (!noun || noun === "help" || hasFlag(parsed, "help")) {
+        return { help: HELP };
+    }
+    const config = await resolveConfig();
+    if (noun === "doctor")
+        return doctor(config);
+    if (noun === "setup") {
+        const skills = await installSkill();
+        const ephemeral = isEphemeralInstall();
+        // Reuse a session that is still live; a missing or already-expired one is
+        // worth spending the browser round trip on now rather than at first use.
+        const sessionIsLive = config.authSource !== "missing" &&
+            (config.authSource === "env" ||
+                (config.sessionExpiresAt !== undefined &&
+                    Date.parse(config.sessionExpiresAt) > Date.now()));
+        const loggedIn = hasFlag(parsed, "skill-only") || sessionIsLive
+            ? null
+            : await login(config, {
+                callbackPort: 8765,
+                oauthClientId: config.oauthClientId,
+            });
+        return {
+            skills,
+            session: loggedIn ?? (sessionIsLive ? "existing" : null),
+            ...(ephemeral
+                ? {
+                    warning: "Running from a temporary npx cache: the installed skill calls `recess-cli`, which is not on your PATH. Run `npm install -g recess-cli` for a persistent command.",
+                }
+                : {}),
+        };
+    }
+    if (noun === "auth") {
+        if (verb === "login") {
+            const oauthClientId = flagString(parsed, "client-id") ?? config.oauthClientId;
+            const callbackPort = flagNumber(parsed, "callback-port") ?? 8765;
+            if (!Number.isInteger(callbackPort) ||
+                callbackPort < 1024 ||
+                callbackPort > 65535) {
+                throw new CliError("invalid_arguments", "--callback-port must be an integer from 1024 through 65535.");
+            }
+            return login(config, { callbackPort, oauthClientId });
+        }
+        if (verb === "request") {
+            const label = flagString(parsed, "label");
+            return requestDeviceAuth(config, label ? { label } : {});
+        }
+        if (verb === "poll") {
+            const timeoutSeconds = flagNumber(parsed, "timeout") ?? 300;
+            if (!Number.isInteger(timeoutSeconds) ||
+                timeoutSeconds < 1 ||
+                timeoutSeconds > 3600) {
+                throw new CliError("invalid_arguments", "--timeout must be an integer number of seconds from 1 through 3600.");
+            }
+            return pollDeviceAuth(config, { timeoutMs: timeoutSeconds * 1000 });
+        }
+        if (verb === "status")
+            return sessionStatus(config);
+        if (verb === "logout") {
+            await clearStoredSession();
+            return { loggedOut: true };
+        }
+        throw new CliError("invalid_arguments", "Use auth login, request, poll, status, or logout.");
+    }
+    const api = new RecessAdminApi(config);
+    api.requireAuth();
+    if (noun === "village") {
+        const targetWorldId = flagString(parsed, "world") ?? "village-1";
+        const numberFlag = (name, fallback) => {
+            const value = flagNumber(parsed, name) ?? fallback;
+            if (value === undefined) {
+                throw new CliError("invalid_arguments", `Missing required --${name}.`);
+            }
+            return value;
+        };
+        const quarterRotation = () => {
+            const value = numberFlag("rotation", 0);
+            if (!Number.isInteger(value) || value < 0 || value > 3) {
+                throw new CliError("invalid_arguments", "--rotation must be 0, 1, 2, or 3.");
+            }
+            return value;
+        };
+        if (verb === "render") {
+            const params = new URLSearchParams({
+                worldId: targetWorldId,
+                minX: String(numberFlag("min-x")),
+                minZ: String(numberFlag("min-z")),
+                maxX: String(numberFlag("max-x")),
+                maxZ: String(numberFlag("max-z")),
+            });
+            return api.villageRequest(`/admin/village/render?${params}`);
+        }
+        if (verb !== "models") {
+            throw new CliError("invalid_arguments", "Use village models … or village render …");
+        }
+        const action = positional(parsed, 2, "Village model action");
+        if (action === "list") {
+            const params = new URLSearchParams({ worldId: targetWorldId });
+            const query = flagString(parsed, "query");
+            if (query)
+                params.set("q", query);
+            if (hasFlag(parsed, "archived"))
+                params.set("archived", "true");
+            return api.villageRequest(`/admin/village/models?${params}`);
+        }
+        if (action === "upload") {
+            const absolutePath = path.resolve(flagString(parsed, "file", { required: true }));
+            if (path.extname(absolutePath).toLowerCase() !== ".glb") {
+                throw new CliError("invalid_arguments", "--file must point to a .glb file.");
+            }
+            let bytes;
+            try {
+                bytes = await fs.readFile(absolutePath);
+            }
+            catch (error) {
+                throw new CliError("invalid_arguments", `Could not read GLB ${absolutePath}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            if (bytes.byteLength === 0 || bytes.byteLength > 5 * 1024 * 1024) {
+                throw new CliError("invalid_arguments", "GLB must be between 1 byte and 5 MB.");
+            }
+            const metadata = {
+                id: flagString(parsed, "id"),
+                name: flagString(parsed, "name"),
+                description: flagString(parsed, "description"),
+                tags: flagString(parsed, "tags"),
+                visualOnly: hasFlag(parsed, "visual-only") || undefined,
+            };
+            return writeCommand(parsed, {
+                action: "upload and validate a reusable Village GLB draft",
+                target: { worldId: targetWorldId },
+                request: {
+                    file: absolutePath,
+                    fileName: path.basename(absolutePath),
+                    sizeBytes: bytes.byteLength,
+                    sha256: createHash("sha256").update(bytes).digest("hex"),
+                    ...metadata,
+                },
+            }, () => api.uploadVillageModel(targetWorldId, bytes, path.basename(absolutePath), metadata));
+        }
+        if (action === "publish" || action === "archive") {
+            const modelId = positional(parsed, 3, "model ID");
+            return writeCommand(parsed, {
+                action: `${action} a reusable Village model`,
+                target: { worldId: targetWorldId, modelId },
+                request: { action },
+            }, () => api.villageRequest(`/admin/village/models/${encodeURIComponent(modelId)}/${action}`, { method: "POST", body: { worldId: targetWorldId } }));
+        }
+        if (action === "place") {
+            const modelId = positional(parsed, 3, "model ID");
+            const body = {
+                worldId: targetWorldId,
+                assetId: modelId,
+                position: {
+                    x: numberFlag("x"),
+                    y: numberFlag("y", 0),
+                    z: numberFlag("z"),
+                },
+                rotation: quarterRotation(),
+                mirrored: hasFlag(parsed, "mirrored"),
+                collides: !hasFlag(parsed, "no-collision"),
+                ...(flagString(parsed, "batch")
+                    ? { batchId: flagString(parsed, "batch") }
+                    : {}),
+            };
+            return writeCommand(parsed, {
+                action: "place a reusable Village model on the 0.5m grid",
+                target: { worldId: targetWorldId, modelId },
+                request: body,
+            }, () => api.villageRequest("/admin/village/models/place", {
+                method: "POST",
+                body,
+            }));
+        }
+        if (action === "move") {
+            const placementId = positional(parsed, 3, "placement ID");
+            const body = {
+                worldId: targetWorldId,
+                position: {
+                    x: numberFlag("x"),
+                    y: numberFlag("y", 0),
+                    z: numberFlag("z"),
+                },
+                rotation: quarterRotation(),
+                mirrored: hasFlag(parsed, "mirrored"),
+            };
+            return writeCommand(parsed, {
+                action: "move a Village model placement on the 0.5m grid",
+                target: { worldId: targetWorldId, placementId },
+                request: body,
+            }, () => api.villageRequest(`/admin/village/models/placements/${encodeURIComponent(placementId)}`, { method: "PUT", body }));
+        }
+        if (action === "remove") {
+            const placementId = positional(parsed, 3, "placement ID");
+            return writeCommand(parsed, {
+                action: "remove a Village model placement",
+                target: { worldId: targetWorldId, placementId },
+                request: {},
+            }, () => api.villageRequest(`/admin/village/models/placements/${encodeURIComponent(placementId)}?worldId=${encodeURIComponent(targetWorldId)}`, { method: "DELETE" }));
+        }
+        throw new CliError("invalid_arguments", "Use village models list|upload|publish|archive|place|move|remove.");
+    }
+    if (noun === "users" && verb === "search") {
+        const query = parsed.positionals.slice(2).join(" ").trim();
+        if (!query)
+            throw new CliError("invalid_arguments", "Missing search query.");
+        const limit = flagNumber(parsed, "limit") ?? 10;
+        return unwrap(await api.client.GET("/admin/users/operations-search", {
+            params: { query: { search: query, limit } },
+        }));
+    }
+    if (noun === "users" && verb === "tier") {
+        const action = positional(parsed, 2, "users tier action");
+        if (action === "list-tiers") {
+            return { tiers: SCHOOL_TIER_OPTIONS };
+        }
+        if (!["get", "preview", "set"].includes(action)) {
+            throw new CliError("invalid_arguments", "Use users tier list-tiers|get|preview|set.");
+        }
+        const kidId = positional(parsed, 3, "kid ID");
+        if (action === "get") {
+            const context = await resolveSchoolKidContext(api, kidId);
+            const state = unwrap(await api.client.GET("/admin/partner/{slug}/kids/{kidId}/tier", {
+                params: {
+                    path: { slug: context.institutionSlug, kidId },
+                    query: {},
+                },
+            }));
+            return { kidId, ...context, ...state };
+        }
+        const tierId = assertChoice(flagString(parsed, "tier", { required: true }), SCHOOL_TIER_IDS, "--tier");
+        const proposedSlots = tierSlots(parsed);
+        const expectedUpdatedAt = action === "set"
+            ? flagString(parsed, "expected-updated-at", { required: true })
+            : undefined;
+        if (expectedUpdatedAt !== undefined &&
+            Number.isNaN(Date.parse(expectedUpdatedAt))) {
+            throw new CliError("invalid_arguments", "--expected-updated-at must be an ISO-8601 timestamp from users tier get.");
+        }
+        const context = await resolveSchoolKidContext(api, kidId);
+        const state = unwrap(await api.client.GET("/admin/partner/{slug}/kids/{kidId}/tier", {
+            params: {
+                path: { slug: context.institutionSlug, kidId },
+                query: {
+                    proposedTierId: tierId,
+                    ...(proposedSlots === undefined ? {} : { proposedSlots }),
+                },
+            },
+        }));
+        const preview = {
+            kidId,
+            ...context,
+            tierId: state.tierId,
+            concurrentClassSlots: state.concurrentClassSlots,
+            slotsUsed: state.slotsUsed,
+            enforcementOn: state.enforcementOn,
+            updatedAt: state.updatedAt,
+            proposedTierId: state.proposedTierId,
+            proposedConcurrentClassSlots: state.proposedConcurrentClassSlots,
+            capabilitiesLockedNow: state.capabilitiesLocked,
+            capabilitiesLockedAfter: state.capabilitiesLockedAfter,
+            wouldStrandRegistrations: state.wouldStrandRegistrations,
+        };
+        if (action === "preview")
+            return preview;
+        const allowStrand = hasFlag(parsed, "allow-strand");
+        if (state.wouldStrandRegistrations && !allowStrand) {
+            throw new CliError("would_strand_registrations", `The proposed ${state.proposedConcurrentClassSlots} slots are below ${state.slotsUsed} active registrations. Rerun with --allow-strand only after explicitly approving the over-allocation.`, 1, { preview });
+        }
+        const body = {
+            tierId,
+            ...(proposedSlots === undefined ? {} : { slotsPerKid: proposedSlots }),
+            expectedUpdatedAt: expectedUpdatedAt,
+            allowStrand,
+        };
+        return writeCommand(parsed, {
+            action: state.enforcementOn
+                ? `set the kid's school tier to ${tierId} with the displayed capability and class-slot consequences`
+                : `set the kid's school tier to ${tierId}; enforcement is OFF, so capability locks will not be observable yet`,
+            target: { kidId, institutionSlug: context.institutionSlug },
+            request: body,
+            details: preview,
+        }, async () => unwrap(await api.client.PATCH("/admin/partner/{slug}/kids/{kidId}/tier", {
+            params: {
+                path: { slug: context.institutionSlug, kidId },
+            },
+            body,
+        })));
+    }
+    if (noun === "users" && verb === "get") {
+        const userId = positional(parsed, 2, "user ID");
+        return unwrap(await api.client.GET("/admin/users/{userId}", {
+            params: { path: { userId } },
+        }));
+    }
+    if (noun === "students" && verb === "upload-map-scores") {
+        const studentId = flagString(parsed, "student", { required: true });
+        const pdf = await readMapScorePdf(flagString(parsed, "file", { required: true }));
+        return writeCommand(parsed, {
+            action: "upload a MAP Growth PDF and extract scores into the tutor dashboard",
+            target: { studentId },
+            request: {
+                file: pdf.absolutePath,
+                fileName: pdf.fileName,
+                sizeBytes: pdf.bytes.byteLength,
+                sha256: pdf.sha256,
+                contentType: "application/pdf",
+            },
+        }, () => api.uploadMapTestScores(studentId, pdf.bytes, pdf.fileName));
+    }
+    if (noun === "enrollments" && verb === "list") {
+        const userId = flagString(parsed, "user", { required: true });
+        const data = unwrap(await api.client.GET("/admin/users/operations-search", {
+            params: { query: { search: userId, limit: 10 } },
+        }));
+        const member = data.results
+            .flatMap((result) => result.members)
+            .find((candidate) => candidate.id === userId);
+        if (!member) {
+            throw new CliError("not_found", `No user found for ${userId}.`);
+        }
+        return { user: member, enrollments: member.enrollments };
+    }
+    if (noun === "subscriptions" && verb === "list") {
+        const familyId = flagString(parsed, "family", { required: true });
+        const kidId = flagString(parsed, "kid");
+        return unwrap(await api.client.GET("/admin/stripe/family-subscriptions", {
+            params: { query: { familyId, ...(kidId ? { kidId } : {}) } },
+        }));
+    }
+    if (noun === "invoices" && verb === "list") {
+        const subscriptionId = flagString(parsed, "subscription", {
+            required: true,
+        });
+        return unwrap(await api.client.GET("/admin/stripe/subscription-invoices", {
+            params: { query: { subscriptionId } },
+        }));
+    }
+    if (noun === "cohorts" && verb === "search") {
+        const search = parsed.positionals.slice(2).join(" ").trim();
+        if (!search)
+            throw new CliError("invalid_arguments", "Missing cohort search query.");
+        return unwrap(await api.client.GET("/admin/cohorts/", {
+            params: { query: { search } },
+        }));
+    }
+    if (noun === "billing" && (verb === "pause" || verb === "resume")) {
+        const subscriptionId = flagString(parsed, "subscription", {
+            required: true,
+        });
+        const until = flagString(parsed, "until");
+        let pauseOption = verb === "resume" ? "resume" : until ? "fixed" : "indefinite";
+        let resumeAt;
+        if (until) {
+            resumeAt = Math.floor(new Date(until).getTime() / 1000);
+            if (!Number.isFinite(resumeAt) || resumeAt <= Date.now() / 1000) {
+                throw new CliError("invalid_arguments", "--until must be a valid future ISO date.");
+            }
+        }
+        const body = {
+            subscriptionId,
+            pauseOption,
+            ...(resumeAt ? { resumeAt } : {}),
+        };
+        return writeCommand(parsed, {
+            action: verb === "resume"
+                ? "resume billing collection"
+                : "pause billing collection",
+            target: { subscriptionId },
+            request: body,
+        }, async () => unwrap(await api.client.POST("/admin/stripe/pause-collection", { body })));
+    }
+    if (noun === "invoices" && verb === "refund") {
+        const invoiceId = flagString(parsed, "invoice", { required: true });
+        const lineItem = flagString(parsed, "line-item", { required: true });
+        const method = assertChoice(flagString(parsed, "method", { required: true }), ["refund", "credit", "tokens"], "--method");
+        const whoPays = assertChoice(flagString(parsed, "who-pays") ?? "guide", ["guide", "recess"], "--who-pays");
+        const reason = flagString(parsed, "reason");
+        const amount = flagNumber(parsed, "amount-cents");
+        const fullRefund = hasFlag(parsed, "full");
+        if (method === "tokens" && (!amount || fullRefund)) {
+            throw new CliError("invalid_arguments", "Token refunds require --amount-cents and do not accept --full.");
+        }
+        if (method !== "tokens" && !fullRefund && !amount) {
+            throw new CliError("invalid_arguments", "Pass --full or a positive --amount-cents.");
+        }
+        if (amount !== undefined && (!Number.isInteger(amount) || amount <= 0)) {
+            throw new CliError("invalid_arguments", "--amount-cents must be a positive integer.");
+        }
+        if (method === "tokens") {
+            const body = { invoiceId, lineItem, amount: amount, whoPays, reason };
+            return writeCommand(parsed, {
+                action: "refund invoice item as tokens",
+                target: { invoiceId, lineItem },
+                request: body,
+            }, async () => unwrap(await api.client.POST("/admin/stripe/refund-as-tokens", {
+                body,
+            })));
+        }
+        const body = {
+            invoiceId,
+            lineItem,
+            refundOrCredit: method,
+            fullRefund,
+            ...(amount ? { amount } : {}),
+            whoPays,
+            reason,
+        };
+        return writeCommand(parsed, {
+            action: `issue invoice ${method}`,
+            target: { invoiceId, lineItem },
+            request: body,
+        }, async () => unwrap(await api.client.POST("/admin/stripe/issue-credit-note", {
+            body,
+        })));
+    }
+    if (noun === "enrollments" && verb === "create") {
+        const userId = flagString(parsed, "user", { required: true });
+        const cohortId = flagString(parsed, "cohort", { required: true });
+        const firstChargeAt = flagString(parsed, "first-charge-at");
+        if (firstChargeAt && Number.isNaN(Date.parse(firstChargeAt))) {
+            throw new CliError("invalid_arguments", "--first-charge-at must be an ISO datetime, e.g. 2026-08-02T00:00:00Z.");
+        }
+        const body = {
+            userId,
+            cohortId,
+            sendEmail: hasFlag(parsed, "send-email"),
+            force: hasFlag(parsed, "force"),
+            ...(firstChargeAt
+                ? { firstChargeAt: new Date(firstChargeAt).toISOString() }
+                : {}),
+        };
+        // Unlike other writes, the offline preview here would hide the only facts
+        // that matter — the amount charged, whether anything is charged at all, and
+        // whether the kid is over capacity or out of school slots. Ask the backend
+        // for its own dry run (read-only, writes nothing) and put that in front of
+        // the human before the confirmation gate.
+        if (!hasFlag(parsed, "confirm")) {
+            const preview = unwrap(await api.client.POST("/admin/cohorts/enroll/", {
+                body: { ...body, dryRun: true },
+            }));
+            const b = preview.plan.billing;
+            const usd = (cents) => `${(cents / 100).toFixed(2)} USD`;
+            const recurrence = b.isRecurring ? `, recurring per ${b.interval}` : "";
+            // effectivePriceCents already has the course discount applied; credits are
+            // deducted later as an invoice line, so this is an upper bound.
+            const amount = b.discountKind || b.creditBalanceCents > 0
+                ? `${usd(b.effectivePriceCents)} (list ${usd(b.listPriceCents)}${b.discountKind ? `, ${b.discountKind} discount applied` : ""}${b.creditBalanceCents > 0 ? `; up to ${usd(b.creditBalanceCents)} of Recess credits may reduce this further` : ""})`
+                : usd(b.effectivePriceCents);
+            requireConfirmation(false, {
+                action: preview.plan.reusedEnrollmentId
+                    ? "enroll kid into cohort by reusing an existing enrollment (no charge)"
+                    : b.chargesImmediately
+                        ? `enroll kid into cohort and CHARGE ${amount} NOW${recurrence}`
+                        : `enroll kid into cohort with first charge of ${amount} on ${b.firstChargeAt}${recurrence}`,
+                target: {
+                    kid: `${preview.plan.kid.firstName ?? ""} ${preview.plan.kid.lastName ?? ""}`.trim(),
+                    userId,
+                    cohort: preview.plan.cohort.name,
+                    cohortId,
+                    course: preview.plan.cohort.courseName,
+                },
+                request: { ...body, dryRun: false },
+                details: {
+                    billing: b,
+                    reusedEnrollmentId: preview.plan.reusedEnrollmentId,
+                    warnings: preview.warnings,
+                    ...(preview.warnings.length > 0 && !body.force
+                        ? {
+                            blocked: "These warnings will reject the write unless you also pass --force.",
+                        }
+                        : {}),
+                },
+            });
+        }
+        return unwrap(await api.client.POST("/admin/cohorts/enroll/", {
+            body: { ...body, dryRun: false },
+        }));
+    }
+    if (noun === "enrollments" && verb === "register-cohort") {
+        const enrollmentId = flagString(parsed, "enrollment", { required: true });
+        const userId = flagString(parsed, "user", { required: true });
+        const cohortId = flagString(parsed, "cohort", { required: true });
+        const body = {
+            cohortId,
+            userIds: [userId],
+            sendEmail: false,
+            enforcePendingEnrollmentCheck: false,
+            enrollmentId,
+        };
+        return writeCommand(parsed, {
+            action: "register cohort against enrollment",
+            target: { enrollmentId, userId, cohortId },
+            request: body,
+        }, async () => unwrap(await api.client.POST("/admin/cohorts/register/", { body })));
+    }
+    if (noun === "enrollments" && verb === "unregister-cohort") {
+        const userId = flagString(parsed, "user", { required: true });
+        const cohortId = flagString(parsed, "cohort", { required: true });
+        const body = { cohortId, userIds: [userId], cancelEnrollment: false };
+        return writeCommand(parsed, {
+            action: "unregister cohort without canceling enrollment",
+            target: { userId, cohortId },
+            request: body,
+        }, async () => unwrap(await api.client.POST("/admin/cohorts/unregister/", { body })));
+    }
+    if (noun === "enrollments" && verb === "get-for-subscription") {
+        const subscriptionId = flagString(parsed, "subscription", {
+            required: true,
+        });
+        return unwrap(await api.client.GET("/admin/stripe/enrollment-for-subscription", {
+            params: { query: { subscriptionId } },
+        }));
+    }
+    if (noun === "billing" && verb === "extend-trial") {
+        const subscriptionId = flagString(parsed, "subscription", {
+            required: true,
+        });
+        const trialEndRaw = flagString(parsed, "trial-end", { required: true });
+        const trialEnd = Math.floor(new Date(trialEndRaw).getTime() / 1000);
+        if (!Number.isFinite(trialEnd) || trialEnd <= Date.now() / 1000) {
+            throw new CliError("invalid_arguments", "--trial-end must be a valid future ISO date.");
+        }
+        const body = { subscriptionId, trialEnd };
+        return writeCommand(parsed, {
+            action: `extend subscription trial to ${trialEndRaw}`,
+            target: { subscriptionId },
+            request: body,
+        }, async () => unwrap(await api.client.POST("/admin/stripe/extend-trial", { body })));
+    }
+    if (noun === "billing" && verb === "cancel-subscription") {
+        const subscriptionId = flagString(parsed, "subscription", {
+            required: true,
+        });
+        const immediate = hasFlag(parsed, "immediate");
+        const restore = hasFlag(parsed, "restore");
+        const reason = flagString(parsed, "reason");
+        const body = {
+            immediate,
+            subscriptionId,
+            restore,
+            ...(reason ? { reason } : {}),
+        };
+        return writeCommand(parsed, {
+            action: restore
+                ? "restore a previously canceled subscription"
+                : immediate
+                    ? "cancel subscription IMMEDIATELY (no period-end grace)"
+                    : "cancel subscription at period end",
+            target: { subscriptionId },
+            request: body,
+        }, async () => unwrap(await api.client.POST("/admin/stripe/cancel-subscription", { body })));
+    }
+    if (noun === "payout") {
+        const area = verb;
+        const action = parsed.positionals[2];
+        if (area === "payruns" && action === "list") {
+            const status = flagStatusList(parsed, "status", PAYRUN_STATUSES);
+            const scheduleId = flagString(parsed, "schedule");
+            return unwrap(await api.client.GET("/admin/payout/payrun/payrun/", {
+                params: {
+                    query: {
+                        ...(status ? { status } : {}),
+                        ...(scheduleId ? { scheduleId } : {}),
+                    },
+                },
+            }));
+        }
+        if (area === "recipients" && action === "list") {
+            const search = flagString(parsed, "search");
+            const userId = flagString(parsed, "user");
+            const id = flagString(parsed, "id");
+            return unwrap(await api.client.GET("/admin/payout/recipient/", {
+                params: {
+                    query: {
+                        ...(search ? { search } : {}),
+                        ...(userId ? { userId } : {}),
+                        ...(id ? { id } : {}),
+                    },
+                },
+            }));
+        }
+        if (area === "invoices" && action === "list") {
+            const payRunId = flagString(parsed, "payrun");
+            const accountId = flagString(parsed, "recipient");
+            const userId = flagString(parsed, "user");
+            const status = flagStatusList(parsed, "status", PAYOUT_INVOICE_STATUSES);
+            if (!payRunId && !accountId && !userId && !status) {
+                throw new CliError("invalid_arguments", "Pass at least one filter: --payrun, --recipient, --user, or --status.");
+            }
+            return unwrap(await api.client.GET("/admin/payout/invoices/", {
+                params: {
+                    query: {
+                        ...(payRunId ? { payRunId } : {}),
+                        ...(accountId ? { accountId } : {}),
+                        ...(userId ? { userId } : {}),
+                        ...(status ? { status } : {}),
+                    },
+                },
+            }));
+        }
+        if (area === "invoices" && action === "get") {
+            const invoiceId = positional(parsed, 3, "invoice ID");
+            return unwrap(await api.client.GET("/admin/payout/invoice/{id}", {
+                params: { path: { id: invoiceId } },
+            }));
+        }
+        if (area === "invoices" && action === "set-status") {
+            const invoiceId = positional(parsed, 3, "invoice ID");
+            const status = assertChoice(flagString(parsed, "status", { required: true }), ["IN_REVIEW", "OPEN", "PAID", "CANCELED"], "--status");
+            const sendEmail = hasFlag(parsed, "send-email");
+            const emailEffect = status === "IN_REVIEW" || status === "OPEN"
+                ? sendEmail
+                    ? " and emails the guide"
+                    : " WITHOUT emailing the guide (pass --send-email to notify)"
+                : "";
+            const body = { status, sendEmail };
+            return writeCommand(parsed, {
+                action: `set payout invoice status to ${status} — ${PAYOUT_STATUS_SIDE_EFFECTS[status]}${emailEffect}`,
+                target: { invoiceId },
+                request: body,
+            }, async () => unwrap(await api.client.PATCH("/admin/payout/invoice-status/{id}", {
+                params: { path: { id: invoiceId } },
+                body,
+            })));
+        }
+        if (area === "items" && action === "add") {
+            const invoiceId = flagString(parsed, "invoice", { required: true });
+            const totalAmountCents = flagCents(parsed, "amount-cents", {
+                required: true,
+            });
+            const description = flagString(parsed, "description", { required: true }).trim();
+            if (!description) {
+                throw new CliError("invalid_arguments", "--description must not be empty.");
+            }
+            let itemTimestampMs = flagItemDateMs(parsed);
+            let itemDateSource = "--date flag";
+            if (itemTimestampMs === undefined) {
+                const detail = unwrap(await api.client.GET("/admin/payout/invoice/{id}", {
+                    params: { path: { id: invoiceId } },
+                }));
+                itemTimestampMs = penultimateCycleDayMs(detail.invoice.endDate);
+                itemDateSource =
+                    "default: penultimate day of the invoice cycle (endDate - 1 day)";
+            }
+            const body = {
+                invoiceId,
+                totalAmountCents,
+                description,
+                itemTimestampMs,
+            };
+            return writeCommand(parsed, {
+                action: "add custom payout invoice line item",
+                target: { invoiceId },
+                request: {
+                    ...body,
+                    itemDate: new Date(itemTimestampMs).toISOString(),
+                    itemDateSource,
+                },
+            }, async () => unwrap(await api.client.POST("/admin/payout/custom-invoice-item/", {
+                body,
+            })));
+        }
+        if (area === "items" && action === "edit") {
+            const itemId = positional(parsed, 3, "line item ID");
+            const amountCents = flagCents(parsed, "amount-cents");
+            const description = flagString(parsed, "description");
+            const itemDateMs = flagItemDateMs(parsed);
+            if (amountCents === undefined &&
+                description === undefined &&
+                itemDateMs === undefined) {
+                throw new CliError("invalid_arguments", "Pass at least one of --amount-cents, --description, or --date.");
+            }
+            // Custom line items carry no platform fee, so net always equals total.
+            const body = {
+                ...(amountCents !== undefined
+                    ? { totalAmountCents: amountCents, netAmountCents: amountCents }
+                    : {}),
+                ...(description !== undefined ? { description } : {}),
+                ...(itemDateMs !== undefined
+                    ? { itemDate: new Date(itemDateMs).toISOString() }
+                    : {}),
+            };
+            return writeCommand(parsed, {
+                action: "edit payout invoice line item",
+                target: { itemId },
+                request: body,
+            }, async () => unwrap(await api.client.PATCH("/admin/payout/invoice-item/{id}", {
+                params: { path: { id: itemId } },
+                body,
+            })));
+        }
+        if (area === "items" && action === "delete") {
+            const itemId = positional(parsed, 3, "line item ID");
+            return writeCommand(parsed, {
+                action: "soft-delete payout invoice line item",
+                target: { itemId },
+                request: {},
+            }, async () => unwrap(await api.client.DELETE("/admin/payout/invoice-item/{id}", {
+                params: { path: { id: itemId } },
+            })));
+        }
+        throw new CliError("invalid_arguments", "Use payout payruns list, payout recipients list, payout invoices list|get|set-status, or payout items add|edit|delete.");
+    }
+    if (noun === "cohorts" && verb === "get") {
+        const cohortId = positional(parsed, 2, "cohort ID");
+        const eventsTab = flagString(parsed, "events-tab");
+        return unwrap(await api.client.GET("/admin/cohorts/{id}/details/", {
+            params: {
+                path: { id: cohortId },
+                query: eventsTab
+                    ? {
+                        eventsTab: assertChoice(eventsTab, ["ACTIVE", "ENDED", "CANCELED", "ARCHIVED"], "--events-tab"),
+                    }
+                    : {},
+            },
+        }));
+    }
+    if (noun === "cohorts" && verb === "parent-emails") {
+        const cohortId = positional(parsed, 2, "cohort ID");
+        return unwrap(await api.client.GET("/admin/cohorts/{id}/parent-emails/", {
+            params: { path: { id: cohortId } },
+        }));
+    }
+    if (noun === "cohorts" && verb === "end") {
+        const cohortId = positional(parsed, 2, "cohort ID");
+        const cancelSubscriptions = hasFlag(parsed, "cancel-subscriptions");
+        return writeCommand(parsed, {
+            action: cancelSubscriptions
+                ? "end cohort AND CANCEL EVERY ACTIVE STRIPE SUBSCRIPTION at period end (exceptional)"
+                : "end cohort (archives channels and future events; subscriptions untouched)",
+            target: { cohortId },
+            request: { cancelSubscriptions },
+        }, async () => unwrap(await api.client.POST("/admin/cohorts/{id}/end/", {
+            params: {
+                path: { id: cohortId },
+                query: cancelSubscriptions ? { cancelSubscriptions: "true" } : {},
+            },
+        })));
+    }
+    if (noun === "cohorts" &&
+        (verb === "pause-billing" || verb === "resume-billing")) {
+        const cohortId = positional(parsed, 2, "cohort ID");
+        const pausing = verb === "pause-billing";
+        const weeks = flagNumber(parsed, "weeks");
+        if (pausing) {
+            if (weeks === undefined ||
+                !Number.isInteger(weeks) ||
+                weeks < 1 ||
+                weeks > 6) {
+                throw new CliError("invalid_arguments", "--weeks must be an integer from 1 through 6.");
+            }
+        }
+        else if (weeks !== undefined) {
+            throw new CliError("invalid_arguments", "resume-billing does not accept --weeks.");
+        }
+        const body = pausing
+            ? { action: "pause", pauseWeeks: weeks }
+            : { action: "resume" };
+        return writeCommand(parsed, {
+            action: pausing
+                ? `pause Stripe collection for every active enrollment in the cohort for ${weeks} week(s)`
+                : "resume Stripe collection for the cohort's paused enrollments",
+            target: { cohortId },
+            request: body,
+        }, async () => unwrap(await api.client.POST("/admin/cohorts/{id}/pause-billing/", {
+            params: { path: { id: cohortId } },
+            body,
+        })));
+    }
+    if (noun === "cohorts" && verb === "email") {
+        const cohortId = positional(parsed, 2, "cohort ID");
+        const target = assertChoice(flagString(parsed, "target", { required: true }), ["ALL_PARENTS", "ALL_PARENTS_GUIDES"], "--target");
+        const content = flagString(parsed, "content", { required: true }).trim();
+        if (!content) {
+            throw new CliError("invalid_arguments", "--content must not be empty.");
+        }
+        const body = { target, content };
+        return writeCommand(parsed, {
+            action: `send an email blast to ${target === "ALL_PARENTS" ? "ALL PARENTS" : "ALL PARENTS AND GUIDES"} of the cohort (exceptional outward email)`,
+            target: { cohortId },
+            request: body,
+        }, async () => unwrap(await api.client.POST("/admin/cohorts/{id}/email/", {
+            params: { path: { id: cohortId } },
+            body,
+        })));
+    }
+    if (noun === "events" && verb === "get") {
+        const eventId = positional(parsed, 2, "event ID");
+        return unwrap(await api.client.GET("/admin/events/{eventId}/", {
+            params: { path: { eventId } },
+        }));
+    }
+    if (noun === "events" && verb === "take-attendance") {
+        const eventId = positional(parsed, 2, "event ID");
+        const attended = flagIdList(parsed, "attended");
+        const absent = flagIdList(parsed, "absent");
+        const excused = flagIdList(parsed, "excused");
+        if (attended.length === 0 && absent.length === 0 && excused.length === 0) {
+            throw new CliError("invalid_arguments", "Pass at least one of --attended, --absent, or --excused.");
+        }
+        const seen = new Set();
+        for (const id of [...attended, ...absent, ...excused]) {
+            if (seen.has(id)) {
+                throw new CliError("invalid_arguments", `User ${id} appears in more than one of --attended/--absent/--excused.`);
+            }
+            seen.add(id);
+        }
+        const attendance = [
+            ...attended.map((userId) => ({ userId, attended: true })),
+            ...absent.map((userId) => ({ userId, attended: false })),
+            ...excused.map((userId) => ({
+                userId,
+                attended: false,
+                excused: true,
+            })),
+        ];
+        const body = { attendanceTakenAt: new Date().toISOString(), attendance };
+        return writeCommand(parsed, {
+            action: "take attendance (non-excused absentees may trigger automatic 'we missed you' emails to parents)",
+            target: { eventId },
+            request: body,
+        }, async () => unwrap(await api.client.PATCH("/admin/events/{eventId}", {
+            params: { path: { eventId } },
+            body,
+        })));
+    }
+    if (noun === "events" && verb === "cancel") {
+        const eventId = positional(parsed, 2, "event ID");
+        const reason = flagString(parsed, "reason", { required: true }).trim();
+        if (!reason) {
+            throw new CliError("invalid_arguments", "--reason must not be empty.");
+        }
+        const body = { reason };
+        return writeCommand(parsed, {
+            action: "cancel event AND NOTIFY: messages kid + parent channels, emails every registered parent, files credit-owed notes, posts to Slack",
+            target: { eventId },
+            request: body,
+        }, async () => unwrap(await api.client.POST("/admin/events/{eventId}/cancel", {
+            params: { path: { eventId } },
+            body,
+        })));
+    }
+    if (noun === "events" && verb === "set-status") {
+        const eventId = positional(parsed, 2, "event ID");
+        const status = assertChoice(flagString(parsed, "status", { required: true }), ["ACTIVE", "ENDED", "CANCELED"], "--status");
+        const body = { status };
+        return writeCommand(parsed, {
+            action: `set event status to ${status} (silent administrative change — sends NO notifications; use "events cancel" to notify families)`,
+            target: { eventId },
+            request: body,
+        }, async () => unwrap(await api.client.PATCH("/admin/events/{eventId}", {
+            params: { path: { eventId } },
+            body,
+        })));
+    }
+    if (noun === "events" && (verb === "reschedule" || verb === "add")) {
+        const cohortId = flagString(parsed, "cohort", { required: true });
+        const startsAt = flagLocalDateTime(parsed, "starts-at", {
+            required: true,
+        });
+        const timezone = flagString(parsed, "timezone");
+        const lengthMins = flagNumber(parsed, "length-mins");
+        if (lengthMins !== undefined &&
+            (!Number.isInteger(lengthMins) || lengthMins <= 0)) {
+            throw new CliError("invalid_arguments", "--length-mins must be a positive integer.");
+        }
+        const body = {
+            startsAt,
+            ...(timezone ? { timezone } : {}),
+            ...(lengthMins !== undefined ? { eventLength: lengthMins } : {}),
+        };
+        if (verb === "reschedule") {
+            const eventId = flagString(parsed, "event", { required: true });
+            return writeCommand(parsed, {
+                action: "reschedule event (cohort-local wall-clock time; tombstone-safe move)",
+                target: { cohortId, eventId },
+                request: body,
+            }, async () => unwrap(await api.client.PATCH("/admin/cohorts/{id}/events/{eventId}", {
+                params: { path: { id: cohortId, eventId } },
+                body,
+            })));
+        }
+        return writeCommand(parsed, {
+            action: "add a one-off meeting (cohort-local wall-clock time)",
+            target: { cohortId },
+            request: body,
+        }, async () => unwrap(await api.client.POST("/admin/cohorts/{id}/events/", {
+            params: { path: { id: cohortId } },
+            body,
+        })));
+    }
+    if (noun === "registrations" && verb === "approve") {
+        const registrationId = flagString(parsed, "registration", {
+            required: true,
+        });
+        const body = { registrationId };
+        return writeCommand(parsed, {
+            action: "approve pending cohort registration (sends the welcome email)",
+            target: { registrationId },
+            request: body,
+        }, async () => unwrap(await api.client.POST("/admin/cohorts/register/approve/", { body })));
+    }
+    if (noun === "registrations" && verb === "deny") {
+        const cohortId = flagString(parsed, "cohort", { required: true });
+        const userId = flagString(parsed, "user", { required: true });
+        const body = { cohortId, userIds: [userId], cancelEnrollment: true };
+        return writeCommand(parsed, {
+            action: "deny registration: unregister from the cohort AND cancel the enrollment",
+            target: { cohortId, userId },
+            request: body,
+        }, async () => unwrap(await api.client.POST("/admin/cohorts/unregister/", { body })));
+    }
+    if (noun === "onboarding") {
+        if (verb === "status") {
+            const familyId = positional(parsed, 2, "family ID");
+            return unwrap(await api.client.GET("/admin/onboarding/families/{familyId}/status", {
+                params: { path: { familyId } },
+            }));
+        }
+        if (verb === "kids") {
+            const timePeriodDays = flagNumber(parsed, "time-period-days");
+            const cohortId = flagString(parsed, "cohort");
+            const limit = flagNumber(parsed, "limit");
+            const stageFilterRaw = flagString(parsed, "stage-filter");
+            const stageFilter = stageFilterRaw
+                ? assertChoice(stageFilterRaw, ["all", "scheduled", "oriented", "course", "converted", "lost"], "--stage-filter")
+                : undefined;
+            return unwrap(await api.client.GET("/admin/onboarding/kids/", {
+                params: {
+                    query: {
+                        ...(timePeriodDays !== undefined ? { timePeriodDays } : {}),
+                        ...(cohortId ? { cohortId } : {}),
+                        ...(limit !== undefined ? { limit } : {}),
+                        ...(stageFilter ? { stageFilter } : {}),
+                    },
+                },
+            }));
+        }
+        if (verb === "intake-session") {
+            const familyId = positional(parsed, 2, "family ID");
+            // A true read: look up the family's current IN_PROGRESS intake session
+            // WITHOUT minting one (get.family-intake-session.ts). Merely viewing a
+            // family must not create a blank session — use intake-session-create to
+            // mint one. A 404 means "none yet" and is a clean result, not an error.
+            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,
+                        familyId,
+                        message: "No intake session for this family yet.",
+                    };
+                }
+                throw error;
+            }
+        }
+        if (verb === "intake-session-create") {
+            const familyId = positional(parsed, 2, "family ID");
+            // The explicit create: get-or-create the intake session. Mints a blank
+            // IN_PROGRESS session when none exists (post.family-intake-session.ts,
+            // freshIfFinished), so it is a write and goes through the confirmation
+            // gate like every other mutating command.
+            return writeCommand(parsed, {
+                action: "create the family's parent intake session (mints a blank IN_PROGRESS session if none exists)",
+                target: { familyId },
+                request: {},
+            }, async () => unwrap(await api.client.POST("/admin/onboarding/families/{familyId}/intake-session", { params: { path: { familyId } } })));
+        }
+        if (verb === "set-stage") {
+            const familyId = positional(parsed, 2, "family ID");
+            const stage = assertChoice(flagString(parsed, "stage", { required: true }), ONBOARDING_STAGES, "--stage");
+            // Read the current stage first so the preview can name the transition and
+            // warn when it moves progress backward (re-locks capabilities).
+            const current = unwrap(await api.client.GET("/admin/onboarding/families/{familyId}/status", {
+                params: { path: { familyId } },
+            }));
+            const from = current.onboardingStage;
+            const backward = ONBOARDING_STAGES.indexOf(stage) < ONBOARDING_STAGES.indexOf(from);
+            const body = { stage };
+            return writeCommand(parsed, {
+                action: `${backward ? "MOVE BACKWARD — re-locks progress: " : ""}set onboarding stage to ${stage} — ${ONBOARDING_STAGE_SIDE_EFFECTS[stage]}`,
+                target: { familyId, from },
+                request: body,
+            }, async () => unwrap(await api.client.PATCH("/admin/onboarding/families/{familyId}/stage", { params: { path: { familyId } }, body })));
+        }
+        if (verb === "set-account-state") {
+            const familyId = positional(parsed, 2, "family ID");
+            const state = assertChoice(flagString(parsed, "state", { required: true }), ONBOARDING_ACCOUNT_STATES, "--state");
+            const note = flagString(parsed, "note");
+            const lockout = state === "PAUSED" || state === "BOOTED"
+                ? " — locks the family out of paid capabilities"
+                : "";
+            const body = { state, ...(note !== undefined ? { note } : {}) };
+            return writeCommand(parsed, {
+                action: `set account state to ${state}${lockout}`,
+                target: { familyId },
+                request: body,
+            }, async () => unwrap(await api.client.PATCH("/admin/onboarding/families/{familyId}/account-state", { params: { path: { familyId } }, body })));
+        }
+        if (verb === "attest") {
+            const familyId = positional(parsed, 2, "family ID");
+            const condition = assertChoice(flagString(parsed, "condition", { required: true }), ONBOARDING_CONDITIONS, "--condition");
+            const revoke = hasFlag(parsed, "revoke");
+            const note = flagString(parsed, "note");
+            const body = {
+                condition,
+                attested: !revoke,
+                ...(note !== undefined ? { note } : {}),
+            };
+            return writeCommand(parsed, {
+                action: revoke
+                    ? `REVOKE attestation ${condition}`
+                    : `attest ${condition}`,
+                target: { familyId },
+                request: body,
+            }, async () => unwrap(await api.client.POST("/admin/onboarding/families/{familyId}/attest", { params: { path: { familyId } }, body })));
+        }
+        if (verb === "set-intake") {
+            const familyId = positional(parsed, 2, "family ID");
+            const sessionId = flagString(parsed, "session", { required: true });
+            const dataRaw = flagString(parsed, "data", { required: true });
+            const expectedUpdatedAt = flagString(parsed, "expected-updated-at");
+            let collectedData;
+            try {
+                collectedData = JSON.parse(dataRaw);
+            }
+            catch {
+                throw new CliError("invalid_arguments", "--data must be valid JSON for the intake collectedData object.");
+            }
+            if (expectedUpdatedAt !== undefined &&
+                Number.isNaN(Date.parse(expectedUpdatedAt))) {
+                throw new CliError("invalid_arguments", "--expected-updated-at must be an ISO-8601 timestamp (the intake-session read's updatedAt).");
+            }
+            const collected = collectedData;
+            // The preview must do ZERO network so an offline preview stays honest
+            // (admin-cli offline-preview contract). The optimistic-concurrency token
+            // is resolved only on --confirm, inside the execute closure below — so a
+            // plain preview never reaches out. Strict mode (--expected-updated-at)
+            // shows the pinned token in the preview; the default fetches it at confirm.
+            const previewRequest = {
+                sessionId,
+                collectedData: collected,
+                ...(expectedUpdatedAt !== undefined ? { expectedUpdatedAt } : {}),
+            };
+            return writeCommand(parsed, {
+                action: "write structured parent intake data for the family",
+                target: { familyId, sessionId },
+                request: previewRequest,
+            }, async () => {
+                // Resolve the CAS token now (only reached on --confirm):
+                // - strict mode: pin the operator-supplied token. A stale one 409s
+                //   (unwrap → CliError → non-zero exit), protecting a parent's
+                //   concurrent confirm-flow autosave.
+                // - default: fetch the CURRENT token and warn that edits made since
+                //   the preview are unprotected. The CLI is a last-resort admin tool;
+                //   pragmatic default + honest warning + strict opt-in.
+                let token = expectedUpdatedAt;
+                if (token === undefined) {
+                    const current = unwrap(await api.client.GET("/admin/onboarding/families/{familyId}/intake-session", { params: { path: { familyId } } }));
+                    token = current.updatedAt;
+                    process.stderr.write("Warning: using current session token; edits made since your preview are not protected — pass --expected-updated-at for strict CAS.\n");
+                }
+                const body = {
+                    sessionId,
+                    collectedData: collected,
+                    expectedUpdatedAt: token,
+                };
+                return unwrap(await api.client.PUT("/admin/onboarding/families/{familyId}/intake", { params: { path: { familyId } }, body }));
+            });
+        }
+        if (verb === "extract") {
+            const familyId = positional(parsed, 2, "family ID");
+            const sessionId = flagString(parsed, "session", { required: true });
+            const transcriptFile = flagString(parsed, "transcript-file");
+            const granolaRef = flagString(parsed, "granola");
+            if ((transcriptFile && granolaRef) || (!transcriptFile && !granolaRef)) {
+                throw new CliError("invalid_arguments", "Pass exactly one source: --transcript-file <path> or --granola <ref>.");
+            }
+            let transcript;
+            if (transcriptFile) {
+                try {
+                    transcript = await fs.readFile(path.resolve(transcriptFile), "utf8");
+                }
+                catch (error) {
+                    throw new CliError("invalid_arguments", `Could not read transcript file ${transcriptFile}: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            const body = {
+                sessionId,
+                ...(transcript !== undefined ? { transcript } : {}),
+                ...(granolaRef ? { granolaRef } : {}),
+            };
+            // Keep raw transcript PII out of the confirmation preview (it prints to
+            // stderr, agent logs, and approval records); the full body still goes to
+            // the API on --confirm.
+            const previewRequest = transcript !== undefined && transcriptFile
+                ? {
+                    sessionId,
+                    path: path.resolve(transcriptFile),
+                    byteCount: Buffer.byteLength(transcript, "utf8"),
+                    sha256Prefix: createHash("sha256")
+                        .update(transcript)
+                        .digest("hex")
+                        .slice(0, 12),
+                }
+                : { sessionId, ...(granolaRef ? { granolaRef } : {}) };
+            return writeCommand(parsed, {
+                action: "extract intake from transcript via Claude and merge into session",
+                target: {
+                    familyId,
+                    sessionId,
+                    source: transcriptFile ? "transcript" : "granola",
+                },
+                request: previewRequest,
+            }, async () => unwrap(await api.client.POST("/admin/onboarding/families/{familyId}/intake-extract", { params: { path: { familyId } }, body })));
+        }
+        throw new CliError("invalid_arguments", "Use onboarding status|kids|intake-session|intake-session-create|set-stage|set-account-state|attest|set-intake|extract.");
+    }
+    if (noun === "request" && verb === "get") {
+        return api.rawGet(positional(parsed, 2, "request path"));
+    }
+    throw new CliError("unknown_command", `Unknown command: ${parsed.positionals.join(" ")}\n\n${HELP}`);
+}
+//# sourceMappingURL=cli.js.map