recess-cli 2.0.0 → 2.1.0

package/dist/cli.js

@@ -3,311 +3,23 @@ import { execFile } from "node:child_process";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { RecessAdminApi, unwrap, withIdempotencyContext } from "./api.js";
-import { flagList, flagNumber, flagString, hasFlag, parseArgs, } from "./args.js";
+import { flagNumber, flagString, hasFlag, parseArgs, } from "./args.js";
 import { login, pollDeviceAuth, requestDeviceAuth } from "./auth.js";
 import { clearStoredSession, deleteProfile, listProfiles, resolveConfig, saveProfile, useProfile, } from "./config.js";
 import { agentContext, buildCommandSchema, scopedHelp, validateInvocation, } from "./command-schema.js";
+import { runApplicationsCommand } from "./commands/applications.js";
+import { runOnboardingCommand } from "./commands/onboarding.js";
+import { assertChoice, flagIdList, positional, readJsonFile, readJsonValue, } from "./commands/shared.js";
 import { CliError } from "./errors.js";
 import { listFeedback, submitFeedback } from "./feedback.js";
+import { HELP } from "./help.js";
+export { HELP };
 import { cliRequestHeaders, requireCliRequestReason } from "./http.js";
 import { requireConfirmation } from "./safety.js";
 import { installSkill, isEphemeralInstall, readBundledSkillVersion, readCliVersion, } from "./setup.js";
 import { compareVersions, updateSkillFromServer } from "./skill-update.js";
 import { readSkillCache, writeSkillCache } from "./skills-cache.js";
 import { appendJobEvent, getJob, listJobs, pruneJobs } from "./jobs.js";
-export const HELP = `recess — safe Recess administration and family AI tools
-
-Usage:
-  recess [--json] --version
-  recess [--json] agent-context
-  recess [--json] setup [--skill-only]
-  recess [--json] doctor
-  recess [--json] profile list
-  recess [--json] profile show <name>
-  recess [--json] profile save <name> [--api-origin URL] [--web-origin URL]
-    [--oauth-client-id ID]
-  recess [--json] profile use <name>
-  recess [--json] profile delete <name>
-  recess [--json] jobs list [--limit 20]
-  recess [--json] jobs get <operation-key>
-  recess [--json] jobs prune [--older-than-days 30]
-  recess [--json] feedback list [--limit 20]
-  recess [--json] feedback submit <text> [--confirm]
-  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] guides create --email <email> --first-name TEXT
-    [--last-name TEXT] [--no-invite] [--confirm]
-  recess [--json] guides invite --user <user-id> [--confirm]
-  recess [--json] guardians invite --family <family-id> --email <email>
-    --first-name TEXT [--last-name TEXT] [--no-invite] [--confirm]
-  recess [--json] students upload-map-scores --student <kid-id>
-    --file </path/to/map-report.pdf> [--confirm]
-  recess [--json] students list
-  recess [--json] students today --student <kid-id> [--date YYYY-MM-DD]
-  recess [--json] students schedule --student <kid-id> [--days 14]
-  recess [--json] students xp-history --student <kid-id>
-    [--range week|month|quarter|year]
-  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] applications enroll <application-id> --quote <quote-id>
-    --school <institution-slug> --kid "<quoteLineId>:<firstName>[:<age>]" (repeat per line)
-    [--family <family-id>] [--unassign <kid-id>] (repeat) [--note 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 --approval-token TOKEN]
-  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>]
-    [--limit 20] [--cursor <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]
-  recess [--json] store-items list [--search TEXT]
-    [--status ACTIVE|INACTIVE|COMING_SOON] [--item-type TYPE]
-    [--page 0] [--limit 20] [--sort-by name|price|createdAt|updatedAt|order]
-    [--sort-order asc|desc]
-  recess [--json] store-items set-status <village-store-item-id>
-    --status ACTIVE|INACTIVE|COMING_SOON [--confirm]
-  recess [--json] content-library search <query> [--limit 8]
-  recess [--json] content-library status <gem-id-or-url>
-  recess [--json] content-library set-stage <gem-id-or-url...> [--file <path>]
-    --stage review|polishing|live|archived [--wait] [--timeout 900] [--confirm]
-  recess [--json] content-library submit <url...> [--file <path>]
-    [--stage review|polish] [--title TEXT] [--summary TEXT]
-    [--lane web-toys|mechanics|explorables|data-stories|sims|maps-scale|sound-art|puzzles|wonder|idea-games]
-    [--wait] [--timeout 900] [--confirm]
-  recess [--json] skills guardian list [--query TEXT] [--category TEXT]
-  recess [--json] skills guardian get <skill-name>
-    [--reference NAME | --all-references] [--refresh]
-  recess [--json] skills admin list [--query TEXT] [--category TEXT]
-  recess [--json] skills admin get <skill-name>
-    [--reference NAME | --all-references]
-    [--refresh]
-  recess [--json] goal-templates list [--query TEXT] [--category TEXT]
-    [--kind SIMPLE|BLUEPRINT] [--starter-only] [--include-deleted]
-    [--limit 20] [--cursor <id>]
-  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 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]
-    [--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 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>
-      | --source-dir <local-checkout>)
-    [--dry-run] [--confirm --approval-token TOKEN]
-  recess [--json] goal-templates apply <template-id> --answers-file <path>
-    [--dry-run] [--confirm --approval-token TOKEN]
-  recess [--json] goal-templates apply-starter <template-id> --student <kid-id>
-    [--answers-file <path>] [--confirm]
-  recess [--json] goals list --student <kid-id>
-  recess [--json] goals create [--student <kid-id>] --title TEXT
-    (--description TEXT | --description-file <path>) [--target-date <iso>]
-    [--schedule TEXT] [(--draft <draft-slug> | --source-dir <local-checkout>)
-      (--enable-applet-follow-ups | --disable-applet-follow-ups)]
-    [--confirm --approval-token TOKEN]
-  recess [--json] goals edit <goal-id> --student <kid-id> --patch-file <path/patch.json>
-    --delta TEXT [--confirm --approval-token TOKEN]
-  recess [--json] goals delete <goal-id> --student <kid-id>
-    [--confirm --approval-token TOKEN]
-  recess [--json] goals queue get <goal-id> --student <kid-id>
-  recess [--json] goals queue set <goal-id> --student <kid-id>
-    --entries-file <path.json> --delta TEXT [--replace-description-pointer]
-    [--confirm --approval-token TOKEN]
-  recess [--json] todos create --student <kid-id> --title TEXT
-    [--due-date YYYY-MM-DD] [--estimated-minutes N] [--url URL] [--confirm]
-  recess [--json] todos edit <todo-id> --patch-file <path/patch.json>
-    [--confirm --approval-token TOKEN]
-  recess [--json] todos delete <todo-id>
-    [--confirm --approval-token TOKEN]
-  recess [--json] todos generate-applet <todo-id> --student <kid-id>
-    [--due-date YYYY-MM-DD] [--confirm --approval-token TOKEN]
-  recess [--json] memories context --student <kid-id>
-  recess [--json] memories log --student <kid-id> --date YYYY-MM-DD
-  recess [--json] rocky get --student <kid-id>
-  recess [--json] rocky set --student <kid-id> --patch-file <path/patch.json>
-    --expected-updated-at ISO|none [--confirm]
-  recess [--json] goals files list --student <goal-owner-id> --goal <goal-id>
-  recess [--json] goals files read --student <goal-owner-id> --goal <goal-id> --path P
-  recess [--json] goals files init --student <goal-owner-id> --draft <draft-slug>
-    --output-dir <local-dir>
-  recess [--json] goals files checkout --student <goal-owner-id>
-    (--goal <goal-id> | --draft <draft-slug>)
-    --output-dir <local-dir>
-  recess [--json] goals files push --source-dir <local-checkout>
-    [--message TEXT] [--confirm --approval-token TOKEN]
-  recess [--json] goals files write --student <goal-owner-id>
-    (--goal <goal-id> | --draft <draft-slug>)
-    (--source-dir <local-dir> | --source-file <local-file> --path P)
-    [--message TEXT] [--confirm --approval-token TOKEN]
-  recess [--json] goals pdf upload --student <goal-owner-id>
-    (--goal <goal-id> | --draft <draft-slug>) --source-file <local.pdf>
-    [--path uploads/name.pdf] [--message TEXT]
-    [--confirm --approval-token TOKEN]
-
-Authoring notes: "skills" serves the in-product tutor skills (the private
-packages/skills workspace package) read-only over your admin session — they are never
-bundled into this npm package. Load os-v2-goal-template-builder and its
-references/deterministic-workflow-setup.md BEFORE authoring a template; that is
-the same guidance the recess.gg/ai agent follows, so there is exactly one
-standard. Responses cache under ~/.recess-cli/skills-cache/ (--refresh re-fetches).
-For goal workspace and PDF commands, --student names the goal owner. A
-full_admin session may use a KID or ADMIN user id, including its own ADMIN id;
-family_ai sessions remain limited to managed KID profiles.
-"goals create --source-dir" materializes a clean, fully pushed draft checkout as
-a personal module-backed goal and retargets that checkout to the resulting live
-goal. It does not create or apply a reusable template. Its preview is bound to
-the exact workspace revision, hash, module inventory, and applet follow-up choice.
-Every template created here is setupMode DETERMINISTIC_WORKFLOW and CANNOT be
-converted back, so "validate-spec" against the same file until it passes, then
-"create". "create" runs a real server-side validation before its gate, so the
-preview shows the handler/goalShape/step keys the SERVER resolved. "apply" runs
-the backend's own dryRun before the gate and previews the per-student outcome.
-"set-metadata" and "delete" require --expected-version (from "get"); a stale one
-409s STALE_WRITE and writes nothing. The spec is unreachable from "set-metadata"
-by design — an existing spec is edited only through the guarded /ai patch path.
-
-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 for ADMIN or a GUARDIAN with
-access:ai. Guardian sessions are family-scoped and cannot call /admin. For a headless
-cloud agent, the ADMIN-only "auth request" prints an approval URL to hand a Recess admin; after they
-approve it in a browser, "auth poll" collects the 12h session. When it lapses, run
-"auth request" again for a fresh link. Both paths yield the same session.
-
-Skill notes: this CLI's own agent skill ships inside the npm package AND is served
-by the server, so wording/Gotcha updates arrive without an npm release. "setup"
-(or "setup --skill-only") installs the bundled copy, then upgrades it from the
-server when the served bundle's minCliVersion allows — an older binary keeps the
-bundled copy, and an unreachable server is not an error. "doctor" reports whether
-a newer skill exists and names the command; it never writes.
-
-Writes preview and exit 2 unless --confirm is supplied after explicit human approval.
-Every preview includes an operationKey; confirmed writes must echo it with
---operation-key so an interrupted invocation can be retried without duplicating the write.
-Environment overrides: RECESS_CLI_API_ORIGIN, RECESS_CLI_WEB_ORIGIN,
-RECESS_CLI_OAUTH_CLIENT_ID, RECESS_CLI_COOKIE, RECESS_CLI_CONFIG,
-RECESS_CLI_PROFILE, RECESS_CLI_FEEDBACK_ENDPOINT.
-
-Every command that calls the Recess API, except auth commands, requires
---reason TEXT: a non-empty human-readable purpose of at most 1024 characters.`;
-function positional(parsed, index, label) {
-    const value = parsed.positionals[index];
-    if (!value) {
-        throw new CliError("invalid_arguments", `Missing ${label}.`);
-    }
-    return value;
-}
 function requiredRequestReason(parsed) {
     return requireCliRequestReason(flagString(parsed, "reason", { required: true }));
 }
@@ -999,12 +711,6 @@ async function readGoalWorkspaceWriteSource(parsed) {
     }
     return { files, source, sizeBytes, sha256: hash.digest("hex") };
 }
-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",
@@ -1028,36 +734,6 @@ const PAYOUT_STATUS_SIDE_EFFECTS = {
     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 },
@@ -1110,41 +786,6 @@ const CONTENT_LIBRARY_DISCOVERY_LANES = [
     "idea-games",
 ];
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-/**
- * Read and parse a JSON file supplied by an authoring agent. Large payloads —
- * a setupWorkflowSpec, an answers map, a goal description — go through files
- * rather than argv: a shell mangles embedded quotes and newlines, and a spec
- * that survived a round trip through `--json '<...>'` is not the spec that was
- * reviewed.
- */
-async function readJsonValue(filePath, label) {
-    const absolutePath = path.resolve(filePath);
-    let raw;
-    try {
-        raw = await fs.readFile(absolutePath, "utf8");
-    }
-    catch (error) {
-        if (error.code === "ENOENT") {
-            throw new CliError("invalid_arguments", `${label} does not exist: ${absolutePath}`);
-        }
-        throw error;
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch (error) {
-        throw new CliError("invalid_arguments", `${label} is not valid JSON (${absolutePath}): ${error instanceof Error ? error.message : String(error)}`);
-    }
-    return { absolutePath, raw, parsed };
-}
-async function readJsonFile(filePath, label) {
-    const { absolutePath, parsed } = await readJsonValue(filePath, label);
-    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-        throw new CliError("invalid_arguments", `${label} must be a JSON object (${absolutePath}).`);
-    }
-    return parsed;
-}
 function parseGoalQueueEntries(value, label) {
     if (!Array.isArray(value)) {
         throw new CliError("invalid_arguments", `${label} must be a JSON array of queue entries.`);
@@ -1630,34 +1271,6 @@ function flagStatusList(parsed, name, choices) {
     }
     return values.map((value) => assertChoice(value, choices, `--${name}`));
 }
-/**
- * Parse one `--kid` spec into an enroll roster entry.
- *
- * Shape: `<quoteLineId>:<firstName>[:<age>]` — the quote line FIRST, because
- * the line id is the identity the enrollment matches on and the name is only a
- * label. A staffer typing these reads them off the quote, in order.
- *
- * ⚠️ THE NAME MAY CONTAIN NOTHING SURPRISING, but an age must be a real number:
- * age decides `birthdate` at creation AND rides in the frozen payment snapshot
- * that a later takeover is compared against, so a silently-dropped or
- * mistyped age is a money-adjacent error, not a cosmetic one. Absent is fine
- * (the server treats it as "not stated"); unparseable is refused here.
- */
-function parseEnrollKidSpec(raw) {
-    const parts = raw.split(":").map((part) => part.trim());
-    const [quoteLineId, firstName, ageRaw, ...extra] = parts;
-    if (!quoteLineId || !firstName || extra.length > 0) {
-        throw new CliError("invalid_arguments", `--kid must be "<quoteLineId>:<firstName>[:<age>]"; got "${raw}".`);
-    }
-    if (ageRaw === undefined || ageRaw === "") {
-        return { quoteLineId, firstName };
-    }
-    const age = Number(ageRaw);
-    if (!Number.isInteger(age) || age < 1 || age > 25) {
-        throw new CliError("invalid_arguments", `--kid age must be a whole number from 1 to 25; got "${ageRaw}".`);
-    }
-    return { quoteLineId, firstName, age };
-}
 function flagCents(parsed, name, options = {}) {
     const value = flagNumber(parsed, name);
     if (value === undefined) {
@@ -1753,19 +1366,6 @@ function flagLocalDateTime(parsed, name, options = {}) {
     }
     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)) {
@@ -2041,17 +1641,180 @@ export async function runCommand(argv) {
             return value;
         };
         if (verb === "render") {
+            const renderWorldId = flagString(parsed, "world") ??
+                (config.user && config.user.role !== "ADMIN"
+                    ? `home-${config.user.id}`
+                    : targetWorldId);
             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}`);
+            return api.villageRead(`/api/cli/worlds/${encodeURIComponent(renderWorldId)}/render?${params}`);
+        }
+        const directWorldId = flagString(parsed, "world") ??
+            (config.user?.id ? `home-${config.user.id}` : targetWorldId);
+        if (verb === "library") {
+            const action = positional(parsed, 2, "Village library action");
+            const base = `/api/cli/worlds/${encodeURIComponent(directWorldId)}/library`;
+            if (action === "search") {
+                const limit = flagNumber(parsed, "limit") ?? 20;
+                if (!Number.isInteger(limit) || limit < 1 || limit > 50) {
+                    throw new CliError("invalid_arguments", "--limit must be an integer from 1 through 50.");
+                }
+                const query = flagString(parsed, "query") ??
+                    parsed.positionals.slice(3).join(" ").trim();
+                const params = new URLSearchParams({ limit: String(limit) });
+                if (query)
+                    params.set("q", query);
+                return api.villageRead(`${base}?${params}`);
+            }
+            if (action === "get") {
+                const modelId = positional(parsed, 3, "model ID");
+                return api.villageRead(`${base}/${encodeURIComponent(modelId)}`);
+            }
+            throw new CliError("invalid_arguments", "Use village library search|get.");
+        }
+        if (verb === "objects") {
+            const action = positional(parsed, 2, "Village objects action");
+            const base = `/api/cli/worlds/${encodeURIComponent(directWorldId)}/objects`;
+            if (action === "list") {
+                const region = {
+                    minX: numberFlag("min-x", -20),
+                    minZ: numberFlag("min-z", -20),
+                    maxX: numberFlag("max-x", 20),
+                    maxZ: numberFlag("max-z", 20),
+                };
+                if (region.minX > region.maxX ||
+                    region.minZ > region.maxZ ||
+                    region.maxX - region.minX > 128 ||
+                    region.maxZ - region.minZ > 128) {
+                    throw new CliError("invalid_arguments", "Object bounds must be ordered and no wider than 128m per side.");
+                }
+                const params = new URLSearchParams(Object.fromEntries(Object.entries(region).map(([key, value]) => [key, String(value)])));
+                return api.villageRead(`${base}?${params}`);
+            }
+            if (action === "get") {
+                const objectId = positional(parsed, 3, "object ID");
+                return api.villageRead(`${base}/${encodeURIComponent(objectId)}`);
+            }
+            throw new CliError("invalid_arguments", "Use village objects list|get.");
+        }
+        if (verb === "build") {
+            const action = positional(parsed, 2, "Village build action");
+            if (action !== "cmd") {
+                throw new CliError("invalid_arguments", "Use village build cmd '<command-json>' or --file <command.json>.");
+            }
+            const commandFile = flagString(parsed, "file");
+            const inlineCommand = parsed.positionals[3];
+            if (Boolean(commandFile) === Boolean(inlineCommand)) {
+                throw new CliError("invalid_arguments", "Pass exactly one command JSON argument or --file <command.json>.");
+            }
+            let command;
+            let source;
+            if (commandFile) {
+                const value = await readJsonValue(commandFile, "Village command file");
+                if (value.parsed === null ||
+                    typeof value.parsed !== "object" ||
+                    Array.isArray(value.parsed)) {
+                    throw new CliError("invalid_arguments", "Village command file must contain one JSON object.");
+                }
+                command = value.parsed;
+                source = {
+                    file: value.absolutePath,
+                    sha256: createHash("sha256").update(value.raw).digest("hex"),
+                };
+            }
+            else {
+                try {
+                    const value = JSON.parse(inlineCommand);
+                    if (value === null ||
+                        typeof value !== "object" ||
+                        Array.isArray(value)) {
+                        throw new Error("command must be an object");
+                    }
+                    command = value;
+                }
+                catch (error) {
+                    throw new CliError("invalid_arguments", `Village command is not a JSON object: ${error instanceof Error ? error.message : String(error)}`);
+                }
+                source = { inline: true };
+            }
+            const buildWorldId = flagString(parsed, "world") ??
+                (config.user?.id ? `home-${config.user.id}` : undefined);
+            if (!buildWorldId) {
+                throw new CliError("invalid_arguments", "Missing --world. Login normally to default to your home world, or pass the exact world ID.");
+            }
+            return writeCommand(parsed, {
+                action: "run one authenticated Village build command",
+                target: { worldId: buildWorldId },
+                request: { command, ...source },
+                details: {
+                    consequence: "The Village server applies the same ownership, block-limit, and broadcast rules as an in-world wrench edit.",
+                },
+            }, () => api.villageCommand(buildWorldId, command));
+        }
+        if (verb === "worlds") {
+            const action = positional(parsed, 2, "Village world action");
+            const worldId = positional(parsed, 3, "world ID");
+            const bridgePath = `/admin/village/worlds/${encodeURIComponent(worldId)}`;
+            if (action === "export") {
+                const output = flagString(parsed, "out");
+                if (!output) {
+                    return api.villageRequest(`${bridgePath}/export`);
+                }
+                const absolutePath = path.resolve(output);
+                return writeCommand(parsed, {
+                    action: "export a Village world bundle to a local file",
+                    target: { worldId, file: absolutePath },
+                    request: { overwrite: true },
+                }, async () => {
+                    const bundle = await api.villageRequest(`${bridgePath}/export`);
+                    const contents = `${JSON.stringify(bundle, null, 2)}\n`;
+                    await fs.writeFile(absolutePath, contents, "utf8");
+                    return {
+                        worldId,
+                        file: absolutePath,
+                        sizeBytes: Buffer.byteLength(contents),
+                    };
+                });
+            }
+            if (action === "import") {
+                const value = await readJsonValue(flagString(parsed, "file", { required: true }), "Village world bundle");
+                return writeCommand(parsed, {
+                    action: "replace a Village world from an imported bundle",
+                    target: { worldId },
+                    request: {
+                        file: value.absolutePath,
+                        sizeBytes: Buffer.byteLength(value.raw),
+                        sha256: createHash("sha256").update(value.raw).digest("hex"),
+                    },
+                    details: {
+                        consequence: "The imported rows replace this world's current data and broadcast a live world reset.",
+                    },
+                }, () => api.villageRequest(`${bridgePath}/import`, {
+                    method: "POST",
+                    body: { bundle: value.parsed, confirm: "import" },
+                }));
+            }
+            if (action === "promote") {
+                return writeCommand(parsed, {
+                    action: "promote a Village mirror or archive into the live hub",
+                    target: { worldId },
+                    request: { confirm: "promote" },
+                    details: {
+                        consequence: "The current hub is archived, this world replaces it atomically, and connected players receive a live world reset.",
+                    },
+                }, () => api.villageRequest(`${bridgePath}/promote`, {
+                    method: "POST",
+                    body: { confirm: "promote" },
+                }));
+            }
+            throw new CliError("invalid_arguments", "Use village worlds export|import|promote.");
         }
         if (verb !== "models") {
-            throw new CliError("invalid_arguments", "Use village models … or village render …");
+            throw new CliError("invalid_arguments", "Use village build …, village library …, village objects …, village worlds …, village models …, or village render …");
         }
         const action = positional(parsed, 2, "Village model action");
         if (action === "list") {
@@ -2482,47 +2245,8 @@ export async function runCommand(argv) {
             params: { query: { subscriptionId } },
         }));
     }
-    if (noun === "applications" && verb === "enroll") {
-        const applicationId = positional(parsed, 2, "application ID");
-        const quoteId = flagString(parsed, "quote", { required: true });
-        const institutionSlug = flagString(parsed, "school", { required: true });
-        const familyId = flagString(parsed, "family");
-        const note = flagString(parsed, "note");
-        // Repeatable --kid, one per PRICED LINE on the quote. The server refuses a
-        // partial roster (every priced student must be enrolled), so this is
-        // deliberately not a convenience list — it is the whole quote, echoed back.
-        const kidSpecs = flagList(parsed, "kid");
-        if (kidSpecs.length === 0) {
-            throw new CliError("invalid_arguments", 'Missing --kid. Pass one per quote line: --kid "<quoteLineId>:<firstName>[:<age>]".');
-        }
-        const kids = kidSpecs.map(parseEnrollKidSpec);
-        // Every OTHER live child in the family must be named explicitly. The server
-        // refuses the whole enrollment otherwise, listing who was unlisted — so the
-        // failure is legible either way, but naming them here is how a staffer says
-        // "yes, I know, they are not enrolling".
-        const dispositions = flagList(parsed, "unassign").map((kidUserId) => ({
-            kidUserId,
-            action: "unassigned",
-        }));
-        return writeCommand(parsed, {
-            // One short clause, like every other preview in this file. The
-            // consequences are enumerated in `request` below, which is what the
-            // confirmation prompt prints in full — restating them here would make
-            // this the only preview a staffer has to read twice.
-            action: "enroll an application from its accepted quote (creates children, charges the first month, cancels marketplace subscriptions)",
-            target: { applicationId, quoteId, institutionSlug, familyId },
-            request: { kids, dispositions, note },
-        }, async () => unwrap(await api.client.POST("/admin/applications/{applicationId}/enroll", {
-            params: { path: { applicationId } },
-            body: {
-                quoteId,
-                institutionSlug,
-                kids,
-                ...(familyId ? { familyId } : {}),
-                ...(dispositions.length > 0 ? { dispositions } : {}),
-                ...(note ? { note } : {}),
-            },
-        })));
+    if (noun === "applications" || noun === "quotes") {
+        return runApplicationsCommand({ parsed, api, writeCommand });
     }
     if (noun === "cohorts" && verb === "search") {
         const search = parsed.positionals.slice(2).join(" ").trim();
@@ -3103,215 +2827,7 @@ export async function runCommand(argv) {
         }, 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.");
+        return runOnboardingCommand({ parsed, api, writeCommand });
     }
     if (noun === "skills") {
         // Reads only — no confirmation gate. Audience is explicit so an agent never