recess-cli 1.9.2 → 2.1.0

package/dist/cli.js

@@ -1,274 +1,27 @@
 import { createHash, randomUUID } from "node:crypto";
+import { execFile } from "node:child_process";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { RecessAdminApi, unwrap } from "./api.js";
-import { flagList, flagNumber, flagString, hasFlag, parseArgs, } from "./args.js";
+import { RecessAdminApi, unwrap, withIdempotencyContext } 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 { 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";
-export const HELP = `recess — safe Recess administration and family AI tools
-
-Usage:
-  recess [--json] --version
-  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] 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]
-  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]
-  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 [--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]
-    [--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]
-  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]
-    [--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>)
-    [--dry-run] [--confirm]
-  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>
-      (--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 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 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 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 --draft" materializes that validated draft directly as a personal
-module-backed 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.
-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;
+import { appendJobEvent, getJob, listJobs, pruneJobs } from "./jobs.js";
+function requiredRequestReason(parsed) {
+    return requireCliRequestReason(flagString(parsed, "reason", { required: true }));
 }
 async function sessionStatus(config) {
     if (!config.sessionCookie) {
@@ -291,18 +44,20 @@ async function sessionStatus(config) {
     }
     return { ...result.data, authSource: config.authSource };
 }
-async function doctor(config) {
+async function doctor(config, reason) {
     const checks = {
         config: {
             path: config.configPath,
             apiOrigin: config.apiOrigin,
             webOrigin: config.webOrigin,
             oauthClientIdConfigured: Boolean(config.oauthClientId),
+            profile: config.profileName ?? null,
         },
         auth: await sessionStatus(config),
     };
     try {
         const response = await fetch(new URL("/health", config.apiOrigin), {
+            headers: cliRequestHeaders(undefined, reason),
             signal: AbortSignal.timeout(5000),
         });
         checks.api = { reachable: response.ok, status: response.status };
@@ -313,7 +68,7 @@ async function doctor(config) {
             message: error instanceof Error ? error.message : String(error),
         };
     }
-    checks.skill = await skillStatus(config);
+    checks.skill = await skillStatus(config, reason);
     return checks;
 }
 /**
@@ -322,7 +77,7 @@ async function doctor(config) {
  * silently rewrote `~/.claude/skills` mid-session would change what the agent is
  * reading out from under it. It names the command instead.
  */
-async function skillStatus(config) {
+async function skillStatus(config, reason) {
     const cliVersion = await readCliVersion();
     const installedVersion = await readBundledSkillVersion();
     const base = { cliVersion, bundledSkillVersion: installedVersion };
@@ -331,7 +86,7 @@ async function skillStatus(config) {
     }
     try {
         const response = await fetch(new URL("/auth/admin-cli/skill/", config.apiOrigin), {
-            headers: { cookie: config.sessionCookie },
+            headers: cliRequestHeaders({ cookie: config.sessionCookie }, reason),
             signal: AbortSignal.timeout(5000),
         });
         if (!response.ok) {
@@ -366,30 +121,433 @@ async function skillStatus(config) {
     }
 }
 async function writeCommand(parsed, preview, execute) {
-    requireConfirmation(hasFlag(parsed, "confirm"), preview);
-    return execute();
+    const fingerprint = approvalTokenFor(preview);
+    const suppliedOperationKey = flagString(parsed, "operation-key");
+    if (!hasFlag(parsed, "confirm")) {
+        const operationKey = operationKeyFor(fingerprint);
+        const boundPreview = {
+            ...preview,
+            details: {
+                ...preview.details,
+                operationKey,
+                retry: "Rerun the unchanged command with --confirm --operation-key <operationKey>. Reuse that same key after an interrupted invocation.",
+            },
+        };
+        await appendJobEvent({
+            jobId: operationKey,
+            status: "awaiting_confirmation",
+            timestamp: new Date().toISOString(),
+            action: preview.action,
+            fingerprint,
+            target: preview.target,
+        });
+        requireConfirmation(false, boundPreview);
+    }
+    if (!suppliedOperationKey) {
+        throw new CliError("confirmation_required", "A confirmed write requires the operation key from its approved preview.", 2, { preview, requiredFlag: "--operation-key" });
+    }
+    assertOperationKeyMatchesPreview(suppliedOperationKey, fingerprint, preview);
+    await appendJobEvent({
+        jobId: suppliedOperationKey,
+        status: "running",
+        timestamp: new Date().toISOString(),
+        action: preview.action,
+        fingerprint,
+        target: preview.target,
+    });
+    try {
+        const result = await withIdempotencyContext({ operationKey: suppliedOperationKey, fingerprint }, execute);
+        await appendJobEvent({
+            jobId: suppliedOperationKey,
+            status: "completed",
+            timestamp: new Date().toISOString(),
+            action: preview.action,
+            fingerprint,
+            target: preview.target,
+            result,
+        });
+        return result;
+    }
+    catch (error) {
+        await appendJobEvent({
+            jobId: suppliedOperationKey,
+            status: "unknown",
+            timestamp: new Date().toISOString(),
+            action: preview.action,
+            fingerprint,
+            target: preview.target,
+            message: error instanceof Error ? error.message : String(error),
+        });
+        throw error;
+    }
 }
 const GOAL_WORKSPACE_WRITE_MAX_FILES = 1_000;
 const GOAL_WORKSPACE_WRITE_MAX_TOTAL_BYTES = 20 * 1024 * 1024;
 const GOAL_PDF_UPLOAD_MAX_BYTES = 1024 * 1024 * 1024;
 const GOAL_QUEUE_MAX_ENTRIES = 500;
 const URL_QUEUE_DESCRIPTION_POINTER = "Skill queue managed by the system.";
+const RECESS_GIT_METADATA = "recess-workspace.json";
+async function runGit(cwd, args, options = {}) {
+    return new Promise((resolve, reject) => {
+        execFile("git", ["-C", cwd, ...args], {
+            encoding: "utf8",
+            maxBuffer: 32 * 1024 * 1024,
+            env: options.identity
+                ? {
+                    ...process.env,
+                    GIT_AUTHOR_NAME: "Recess CLI",
+                    GIT_AUTHOR_EMAIL: "cli@recess.gg",
+                    GIT_COMMITTER_NAME: "Recess CLI",
+                    GIT_COMMITTER_EMAIL: "cli@recess.gg",
+                }
+                : process.env,
+        }, (error, stdout, stderr) => {
+            if (error) {
+                reject(new CliError("git_failed", `Git command failed: git ${args.join(" ")} (${stderr.trim() || error.message})`));
+                return;
+            }
+            resolve(stdout);
+        });
+    });
+}
+async function ensureLocalGitIdentity(root) {
+    for (const [key, fallback] of [
+        ["user.name", "Recess CLI"],
+        ["user.email", "cli@recess.gg"],
+    ]) {
+        let configured = "";
+        try {
+            configured = (await runGit(root, ["config", "--get", key])).trim();
+        }
+        catch {
+            // A missing inherited value exits 1. Install a repo-local fallback so
+            // the checkout can be committed without changing the user's global Git.
+        }
+        if (!configured)
+            await runGit(root, ["config", key, fallback]);
+    }
+}
+function resolveWorkspaceCheckoutPath(root, workspacePath) {
+    const normalized = workspacePath.replaceAll("\\", "/");
+    const segments = normalized.split("/");
+    const isGitMetadataSegment = (segment) => {
+        // NTFS canonicalizes trailing dots/spaces, supports alternate data streams,
+        // and may expose .git through an 8.3 alias such as GIT~1. Reject those
+        // spellings too so a checkout cannot write Git metadata before `git init`.
+        const ntfsName = segment
+            .split(":", 1)[0]
+            .replace(/[ .]+$/g, "")
+            .toLowerCase();
+        return ntfsName === ".git" || /^git~\d+$/.test(ntfsName);
+    };
+    if (!normalized ||
+        path.posix.isAbsolute(normalized) ||
+        segments.some((segment) => !segment ||
+            segment === "." ||
+            segment === ".." ||
+            isGitMetadataSegment(segment))) {
+        throw new CliError("invalid_workspace", `Refusing unsafe workspace path from Mesa: ${workspacePath}`);
+    }
+    const target = path.resolve(root, ...segments);
+    if (!target.startsWith(`${root}${path.sep}`)) {
+        throw new CliError("invalid_workspace", `Refusing workspace path outside checkout: ${workspacePath}`);
+    }
+    return target;
+}
+function recessGitMetadataPath(root) {
+    return path.join(root, ".git", RECESS_GIT_METADATA);
+}
+async function writeRecessGitMetadata(root, metadata) {
+    const destination = recessGitMetadataPath(root);
+    const temporary = `${destination}.${process.pid}.tmp`;
+    await fs.writeFile(temporary, `${JSON.stringify(metadata, null, 2)}\n`, {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    await fs.rename(temporary, destination);
+}
+async function readRecessGitMetadata(sourceDirectory) {
+    const requestedRoot = path.resolve(sourceDirectory);
+    const requestedRealRoot = await fs.realpath(requestedRoot).catch(() => null);
+    if (!requestedRealRoot) {
+        throw new CliError("invalid_checkout", `Recess checkout does not exist: ${requestedRoot}`);
+    }
+    const root = (await runGit(requestedRoot, ["rev-parse", "--show-toplevel"])).trim();
+    const realRoot = await fs.realpath(root);
+    if (realRoot !== requestedRealRoot) {
+        throw new CliError("invalid_checkout", `--source-dir must be the Recess checkout root: ${root}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(await fs.readFile(recessGitMetadataPath(root), "utf8"));
+    }
+    catch {
+        throw new CliError("invalid_checkout", `${root} is not a Recess goal workspace checkout.`);
+    }
+    const value = parsed;
+    const candidateTarget = value.target;
+    const target = value.schemaVersion === 1 && typeof value.goalId === "string"
+        ? { kind: "goal", goalId: value.goalId }
+        : candidateTarget;
+    if (![1, 2].includes(typeof value.schemaVersion === "number" ? value.schemaVersion : 0) ||
+        typeof value.studentId !== "string" ||
+        !target ||
+        (target.kind !== "goal" && target.kind !== "draft") ||
+        (target.kind === "goal" && typeof target.goalId !== "string") ||
+        (target.kind === "draft" && typeof target.draftSlug !== "string") ||
+        typeof value.changeId !== "string" ||
+        typeof value.upstreamCommit !== "string") {
+        throw new CliError("invalid_checkout", `${root} has invalid Recess workspace metadata.`);
+    }
+    return {
+        root: realRoot,
+        metadata: {
+            schemaVersion: 2,
+            studentId: value.studentId,
+            target: target,
+            changeId: value.changeId,
+            upstreamCommit: value.upstreamCommit,
+        },
+    };
+}
+async function checkoutGoalWorkspace(input) {
+    const outputDirectory = path.resolve(input.outputDirectory);
+    if (await fs.lstat(outputDirectory).catch(() => null)) {
+        throw new CliError("destination_exists", `Checkout destination already exists: ${outputDirectory}`);
+    }
+    if (input.snapshot.files.length > GOAL_WORKSPACE_WRITE_MAX_FILES) {
+        throw new CliError("workspace_too_large", `Workspace has more than ${GOAL_WORKSPACE_WRITE_MAX_FILES} files.`);
+    }
+    const sizeBytes = input.snapshot.files.reduce((total, file) => total + file.sizeBytes, 0);
+    if (sizeBytes > GOAL_WORKSPACE_WRITE_MAX_TOTAL_BYTES) {
+        throw new CliError("workspace_too_large", `Workspace exceeds ${GOAL_WORKSPACE_WRITE_MAX_TOTAL_BYTES} decoded bytes.`);
+    }
+    const parent = path.dirname(outputDirectory);
+    await fs.mkdir(parent, { recursive: true });
+    const temporary = await fs.mkdtemp(path.join(parent, ".recess-checkout-"));
+    let moved = false;
+    try {
+        for (const file of input.snapshot.files) {
+            const destination = resolveWorkspaceCheckoutPath(temporary, file.path);
+            const bytes = Buffer.from(file.content, file.contentEncoding === "base64" ? "base64" : "utf8");
+            const sha256 = createHash("sha256").update(bytes).digest("hex");
+            if (bytes.byteLength !== file.sizeBytes || sha256 !== file.sha256) {
+                throw new CliError("invalid_workspace", `Mesa snapshot integrity check failed for ${file.path}.`);
+            }
+            await fs.mkdir(path.dirname(destination), { recursive: true });
+            await fs.writeFile(destination, bytes);
+        }
+        await runGit(temporary, ["init", "--quiet", "--initial-branch=main"]);
+        await ensureLocalGitIdentity(temporary);
+        await runGit(temporary, ["add", "-A"]);
+        await runGit(temporary, [
+            "commit",
+            "--quiet",
+            "--allow-empty",
+            "-m",
+            `Checkout Recess ${input.target.kind} workspace at ${input.snapshot.changeId}`,
+        ], { identity: true });
+        const upstreamCommit = (await runGit(temporary, ["rev-parse", "HEAD"])).trim();
+        await writeRecessGitMetadata(temporary, {
+            schemaVersion: 2,
+            studentId: input.studentId,
+            target: input.target,
+            changeId: input.snapshot.changeId,
+            upstreamCommit,
+        });
+        await fs.rename(temporary, outputDirectory);
+        moved = true;
+        return {
+            directory: outputDirectory,
+            studentId: input.studentId,
+            target: input.target,
+            changeId: input.snapshot.changeId,
+            upstreamCommit,
+            fileCount: input.snapshot.files.length,
+            sizeBytes,
+            next: `Edit with normal file tools, inspect with git -C ${JSON.stringify(outputDirectory)} diff, commit locally, then run recess --json goals files push --source-dir ${JSON.stringify(outputDirectory)} --reason <purpose>.`,
+        };
+    }
+    finally {
+        if (!moved)
+            await fs.rm(temporary, { recursive: true, force: true });
+    }
+}
+async function readRemoteWorkspaceSnapshot(api, studentId, target) {
+    return unwrap(await api.client.GET("/tutor/browser/mesa/workspace-files", {
+        params: {
+            query: {
+                studentUserId: studentId,
+                ...(target.kind === "goal"
+                    ? { goalId: target.goalId }
+                    : { draftSlug: target.draftSlug }),
+            },
+        },
+    }));
+}
+async function assertCheckoutReadyForMaterialization(checkout) {
+    const status = await runGit(checkout.root, ["status", "--porcelain=v1"]);
+    if (status.trim()) {
+        throw new CliError("uncommitted_changes", "Commit or discard all local workspace changes before creating or capturing.");
+    }
+    const head = (await runGit(checkout.root, ["rev-parse", "HEAD"])).trim();
+    if (head !== checkout.metadata.upstreamCommit) {
+        throw new CliError("unpushed_changes", "Push every local workspace commit before creating a goal or capturing a template.");
+    }
+    return head;
+}
+async function readGoalWorkspaceGitChanges(root, base) {
+    const status = await runGit(root, ["status", "--porcelain=v1"]);
+    if (status.trim()) {
+        throw new CliError("uncommitted_changes", "Commit or discard all local workspace changes before pushing.");
+    }
+    const head = (await runGit(root, ["rev-parse", "HEAD"])).trim();
+    if (head === base) {
+        throw new CliError("no_changes", "There are no local commits to push.");
+    }
+    await runGit(root, ["merge-base", "--is-ancestor", base, head]);
+    const commitLines = (await runGit(root, [
+        "log",
+        "--reverse",
+        "--format=%H%x09%s",
+        `${base}..${head}`,
+    ]))
+        .trim()
+        .split("\n")
+        .filter(Boolean);
+    const commits = commitLines.map((line) => {
+        const tab = line.indexOf("\t");
+        return { id: line.slice(0, tab), subject: line.slice(tab + 1) };
+    });
+    const raw = await runGit(root, [
+        "diff",
+        "--name-status",
+        "--no-renames",
+        "-z",
+        `${base}..${head}`,
+    ]);
+    const fields = raw.split("\0").filter((field) => field.length > 0);
+    if (fields.length % 2 !== 0) {
+        throw new CliError("git_failed", "Git returned an invalid workspace diff.");
+    }
+    const changes = [];
+    let sizeBytes = 0;
+    for (let index = 0; index < fields.length; index += 2) {
+        const statusCode = fields[index][0];
+        const workspacePath = fields[index + 1];
+        resolveWorkspaceCheckoutPath(root, workspacePath);
+        if (statusCode === "D") {
+            changes.push({ path: workspacePath, action: "delete" });
+            continue;
+        }
+        if (!["A", "M", "T"].includes(statusCode)) {
+            throw new CliError("unsupported_git_change", `Unsupported Git change ${fields[index]} for ${workspacePath}.`);
+        }
+        const absolutePath = resolveWorkspaceCheckoutPath(root, workspacePath);
+        const stat = await fs.lstat(absolutePath).catch(() => null);
+        if (!stat?.isFile() || stat.isSymbolicLink()) {
+            throw new CliError("invalid_workspace", `Refusing non-file workspace entry: ${workspacePath}`);
+        }
+        const bytes = await fs.readFile(absolutePath);
+        sizeBytes += bytes.byteLength;
+        changes.push({
+            path: workspacePath,
+            action: "upsert",
+            content: bytes.toString("base64"),
+            contentEncoding: "base64",
+            sizeBytes: bytes.byteLength,
+            sha256: createHash("sha256").update(bytes).digest("hex"),
+        });
+    }
+    if (changes.length === 0) {
+        throw new CliError("no_changes", "Local commits do not change workspace file contents.");
+    }
+    if (changes.length > GOAL_WORKSPACE_WRITE_MAX_FILES) {
+        throw new CliError("workspace_too_large", `Push changes more than ${GOAL_WORKSPACE_WRITE_MAX_FILES} files.`);
+    }
+    if (sizeBytes > GOAL_WORKSPACE_WRITE_MAX_TOTAL_BYTES) {
+        throw new CliError("workspace_too_large", `Push exceeds ${GOAL_WORKSPACE_WRITE_MAX_TOTAL_BYTES} decoded bytes.`);
+    }
+    return { head, commits, changes, sizeBytes };
+}
 function approvalTokenFor(preview) {
     return createHash("sha256").update(JSON.stringify(preview)).digest("hex");
 }
-function requirePreviewBoundConfirmation(parsed, preview) {
+function operationKeyFor(fingerprint) {
+    return `op_${randomUUID().replaceAll("-", "")}_${fingerprint}`;
+}
+function assertOperationKeyMatchesPreview(operationKey, fingerprint, preview) {
+    if (!operationKey.endsWith(`_${fingerprint}`)) {
+        throw new CliError("approval_mismatch", "The operation key does not belong to this preview. Start from a new preview and obtain approval again.", 2, { preview, requiredFlag: "--operation-key" });
+    }
+}
+async function requirePreviewBoundConfirmation(parsed, preview) {
     const approvalToken = approvalTokenFor(preview);
+    const suppliedOperationKey = flagString(parsed, "operation-key");
     const boundPreview = {
         ...preview,
-        details: { ...preview.details, approvalToken },
+        details: {
+            ...preview.details,
+            approvalToken,
+            operationKey: suppliedOperationKey ?? operationKeyFor(approvalToken),
+        },
     };
     if (!hasFlag(parsed, "confirm")) {
+        await appendJobEvent({
+            jobId: String(boundPreview.details.operationKey),
+            status: "awaiting_confirmation",
+            timestamp: new Date().toISOString(),
+            action: preview.action,
+            fingerprint: approvalToken,
+            target: preview.target,
+        });
         requireConfirmation(false, boundPreview);
     }
     const supplied = flagString(parsed, "approval-token");
     if (supplied !== approvalToken) {
         throw new CliError("approval_mismatch", "The approved preview no longer matches this request. Review the current preview and rerun with --confirm --approval-token <token>.", 2, { preview: boundPreview, requiredFlag: "--approval-token" });
     }
+    if (!suppliedOperationKey) {
+        throw new CliError("confirmation_required", "A confirmed write requires the operation key from its approved preview.", 2, { preview: boundPreview, requiredFlag: "--operation-key" });
+    }
+    assertOperationKeyMatchesPreview(suppliedOperationKey, approvalToken, boundPreview);
+    await appendJobEvent({
+        jobId: suppliedOperationKey,
+        status: "running",
+        timestamp: new Date().toISOString(),
+        action: preview.action,
+        fingerprint: approvalToken,
+        target: preview.target,
+    });
+    return { operationKey: suppliedOperationKey, fingerprint: approvalToken };
+}
+async function previewBoundWrite(parsed, preview, execute) {
+    const context = await requirePreviewBoundConfirmation(parsed, preview);
+    try {
+        const result = await withIdempotencyContext(context, execute);
+        await appendJobEvent({
+            jobId: context.operationKey,
+            status: "completed",
+            timestamp: new Date().toISOString(),
+            action: preview.action,
+            fingerprint: context.fingerprint,
+            target: preview.target,
+            result,
+        });
+        return result;
+    }
+    catch (error) {
+        await appendJobEvent({
+            jobId: context.operationKey,
+            status: "unknown",
+            timestamp: new Date().toISOString(),
+            action: preview.action,
+            fingerprint: context.fingerprint,
+            target: preview.target,
+            message: error instanceof Error ? error.message : String(error),
+        });
+        throw error;
+    }
 }
 async function cleanupPlannerUpload(api, conversationId, signed, includeDelete) {
     if (signed.kind === "multipart") {
@@ -553,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",
@@ -582,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 },
@@ -664,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.`);
@@ -1025,7 +1112,7 @@ function optionalDocString(doc, key) {
     return value;
 }
 /**
- * Coerce an authored template file into the exact `POST /admin/goal-templates/`
+ * Coerce an authored template file into the exact `POST /ai/goal-templates/`
  * body. Every unknown key is dropped rather than forwarded, so a stale field
  * copied from an old export cannot ride along into a create, and the shape
  * failures an agent actually makes (missing slug, spec as a string, tags as a
@@ -1184,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) {
@@ -1253,6 +1312,48 @@ function flagDateOnly(parsed, name) {
     return raw;
 }
 const DAY_MS = 24 * 60 * 60 * 1000;
+async function waitForContentLibraryLive(api, gems, timeoutSeconds) {
+    const pending = new Set(gems);
+    const latest = new Map();
+    const deadline = Date.now() + timeoutSeconds * 1000;
+    let delayMs = 2_000;
+    while (pending.size > 0) {
+        const targets = Array.from(pending);
+        for (let index = 0; index < targets.length; index += 3) {
+            const batch = targets.slice(index, index + 3);
+            await Promise.all(batch.map(async (gem) => {
+                const status = unwrap(await api.client.GET("/admin/content-library/status", {
+                    params: { query: { gem } },
+                }));
+                latest.set(gem, status);
+                if (status.stage === "live") {
+                    pending.delete(gem);
+                    return;
+                }
+                const errors = [
+                    status.progress.metadata,
+                    status.progress.cover,
+                    status.progress.searchIndex,
+                ].filter((step) => step.state === "error");
+                if (errors.length > 0) {
+                    throw new CliError("async_job_failed", `Content Library polishing failed for ${gem}.`, 1, { status });
+                }
+            }));
+        }
+        if (pending.size === 0)
+            break;
+        if (Date.now() + delayMs >= deadline) {
+            throw new CliError("async_timeout", `Timed out waiting for ${pending.size} Content Library resource(s) to become live. Retry the unchanged confirmed command with the same operation key to resume polling.`, 1, {
+                pending: Array.from(pending),
+                latest: Object.fromEntries(latest),
+            });
+        }
+        const jitter = Math.floor(Math.random() * Math.max(1, delayMs / 4));
+        await new Promise((resolve) => setTimeout(resolve, delayMs + jitter));
+        delayMs = Math.min(15_000, Math.round(delayMs * 1.7));
+    }
+    return { completed: true, resources: Array.from(latest.values()) };
+}
 // The cohort event routes take zoneless local wall-clock datetimes
 // (interpreted in the cohort's timezone server-side).
 function flagLocalDateTime(parsed, name, options = {}) {
@@ -1265,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)) {
@@ -1325,20 +1413,148 @@ function tierSlots(parsed) {
 export async function runCommand(argv) {
     const parsed = parseArgs(argv);
     const [noun, verb] = parsed.positionals;
+    const commands = buildCommandSchema(HELP);
     // Before the help branch: `--version` parses as a FLAG, so `noun` is
     // undefined and `!noun` would return help instead. (Found by running it.)
     if (noun === "version" || hasFlag(parsed, "version")) {
+        const unknown = Array.from(parsed.flags.keys()).filter((name) => !["deliver", "json", "version"].includes(name));
+        if (unknown.length > 0) {
+            throw new CliError("unknown_flag", `Unknown flag${unknown.length === 1 ? "" : "s"}: ${unknown
+                .map((name) => `--${name}`)
+                .join(", ")}.`, 1, { validFlags: ["--deliver", "--json", "--version"] });
+        }
         return {
             cliVersion: await readCliVersion(),
             skillVersion: await readBundledSkillVersion(),
         };
     }
-    if (!noun || noun === "help" || hasFlag(parsed, "help")) {
-        return { help: HELP };
+    if (!noun) {
+        const unknown = Array.from(parsed.flags.keys()).filter((name) => !["deliver", "help", "json", "profile"].includes(name));
+        if (unknown.length > 0) {
+            throw new CliError("unknown_flag", `Unknown flag${unknown.length === 1 ? "" : "s"}: ${unknown
+                .map((name) => `--${name}`)
+                .join(", ")}.`, 1, { validFlags: ["--deliver", "--help", "--json", "--profile"] });
+        }
+        return { help: scopedHelp(HELP, commands, []) };
+    }
+    if (noun === "help" || hasFlag(parsed, "help")) {
+        const scope = noun === "help" ? parsed.positionals.slice(1) : parsed.positionals;
+        return { help: scopedHelp(HELP, commands, scope) };
+    }
+    validateInvocation(parsed, commands);
+    if (noun === "agent-context") {
+        const profiles = await listProfiles();
+        return agentContext(commands, {
+            cliVersion: await readCliVersion(),
+            availableProfiles: profiles.profiles.map((profile) => profile.name),
+            feedbackUpstreamConfigured: Boolean(process.env.RECESS_CLI_FEEDBACK_ENDPOINT),
+        });
+    }
+    if (noun === "profile") {
+        const name = parsed.positionals[2];
+        if (verb === "list")
+            return listProfiles();
+        if (verb === "show") {
+            if (!name)
+                throw new CliError("invalid_arguments", "Missing profile name.");
+            const profiles = await listProfiles();
+            const profile = profiles.profiles.find((entry) => entry.name === name);
+            if (!profile)
+                throw new CliError("not_found", `Unknown profile ${name}.`);
+            return { ...profile, active: profiles.activeProfile === name };
+        }
+        if (verb === "save") {
+            if (!name)
+                throw new CliError("invalid_arguments", "Missing profile name.");
+            const current = await resolveConfig(flagString(parsed, "profile"));
+            const apiOrigin = flagString(parsed, "api-origin") ?? current.apiOrigin;
+            const webOrigin = flagString(parsed, "web-origin") ?? current.webOrigin;
+            const oauthClientId = flagString(parsed, "oauth-client-id") ?? current.oauthClientId;
+            for (const [label, value] of [
+                ["--api-origin", apiOrigin],
+                ["--web-origin", webOrigin],
+            ]) {
+                try {
+                    new URL(value);
+                }
+                catch {
+                    throw new CliError("invalid_arguments", `${label} must be a URL.`);
+                }
+            }
+            await saveProfile(name, { apiOrigin, webOrigin, oauthClientId });
+            return { saved: name, apiOrigin, webOrigin, oauthClientId };
+        }
+        if (verb === "use") {
+            if (!name)
+                throw new CliError("invalid_arguments", "Missing profile name.");
+            await useProfile(name);
+            return { activeProfile: name };
+        }
+        if (verb === "delete") {
+            if (!name)
+                throw new CliError("invalid_arguments", "Missing profile name.");
+            await deleteProfile(name);
+            return { deleted: name };
+        }
+    }
+    if (noun === "jobs") {
+        if (verb === "list") {
+            const limit = flagNumber(parsed, "limit") ?? 20;
+            if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+                throw new CliError("invalid_arguments", "--limit must be an integer from 1 through 100.");
+            }
+            return listJobs(limit);
+        }
+        if (verb === "get") {
+            const jobId = positional(parsed, 2, "operation key");
+            const result = await getJob(jobId);
+            if (!result.job)
+                throw new CliError("not_found", `Unknown job ${jobId}.`);
+            return result;
+        }
+        if (verb === "prune") {
+            const olderThanDays = flagNumber(parsed, "older-than-days") ?? 30;
+            if (!Number.isInteger(olderThanDays) ||
+                olderThanDays < 1 ||
+                olderThanDays > 3650) {
+                throw new CliError("invalid_arguments", "--older-than-days must be an integer from 1 through 3650.");
+            }
+            return pruneJobs(olderThanDays);
+        }
+    }
+    if (noun === "feedback") {
+        if (verb === "list") {
+            const limit = flagNumber(parsed, "limit") ?? 20;
+            if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+                throw new CliError("invalid_arguments", "--limit must be an integer from 1 through 100.");
+            }
+            return listFeedback(limit);
+        }
+        if (verb === "submit") {
+            const feedbackText = parsed.positionals.slice(2).join(" ").trim();
+            if (!feedbackText) {
+                throw new CliError("invalid_arguments", "Feedback text must not be empty.");
+            }
+            if (feedbackText.length > 4_000) {
+                throw new CliError("invalid_arguments", "Feedback text must be 4,000 characters or fewer.");
+            }
+            return writeCommand(parsed, {
+                action: "record Recess CLI feedback locally and send it upstream when configured",
+                target: {
+                    upstreamConfigured: Boolean(process.env.RECESS_CLI_FEEDBACK_ENDPOINT),
+                },
+                request: { text: feedbackText },
+            }, () => submitFeedback({
+                id: flagString(parsed, "operation-key", { required: true }),
+                text: feedbackText,
+                createdAt: new Date().toISOString(),
+            }));
+        }
     }
-    const config = await resolveConfig();
+    const config = await resolveConfig(flagString(parsed, "profile"));
+    const requestReason = noun === "auth" ? undefined : requiredRequestReason(parsed);
     if (noun === "doctor")
-        return doctor(config);
+        return doctor(config, requestReason);
     if (noun === "setup") {
         // Always lay down the bundled copy first: it is the floor, and it is the
         // only copy guaranteed to match this binary. The served upgrade below is
@@ -1348,6 +1564,7 @@ export async function runCommand(argv) {
             apiOrigin: config.apiOrigin,
             sessionCookie: config.sessionCookie,
             cliVersion: await readCliVersion(),
+            reason: requestReason,
         });
         const ephemeral = isEphemeralInstall();
         // Reuse a session that is still live; a missing or already-expired one is
@@ -1400,12 +1617,12 @@ export async function runCommand(argv) {
         if (verb === "status")
             return sessionStatus(config);
         if (verb === "logout") {
-            await clearStoredSession();
+            await clearStoredSession(config.profileName);
             return { loggedOut: true };
         }
         throw new CliError("invalid_arguments", "Use auth login, request, poll, status, or logout.");
     }
-    const api = new RecessAdminApi(config);
+    const api = new RecessAdminApi(config, requestReason);
     api.requireAuth();
     if (noun === "village") {
         const targetWorldId = flagString(parsed, "world") ?? "village-1";
@@ -1424,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") {
@@ -1865,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();
@@ -2001,52 +2342,47 @@ export async function runCommand(argv) {
                 ? { 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 },
+        // The backend owns the price/capacity plan. Recompute it on every run and
+        // bind the confirmation token to that exact plan before the mutation.
+        const preflight = unwrap(await api.client.POST("/admin/cohorts/enroll/", {
+            body: { ...body, dryRun: true },
         }));
+        const billing = preflight.plan.billing;
+        const usd = (cents) => `${(cents / 100).toFixed(2)} USD`;
+        const recurrence = billing.isRecurring
+            ? `, recurring per ${billing.interval}`
+            : "";
+        const amount = billing.discountKind || billing.creditBalanceCents > 0
+            ? `${usd(billing.effectivePriceCents)} (list ${usd(billing.listPriceCents)}${billing.discountKind ? `, ${billing.discountKind} discount applied` : ""}${billing.creditBalanceCents > 0 ? `; up to ${usd(billing.creditBalanceCents)} of Recess credits may reduce this further` : ""})`
+            : usd(billing.effectivePriceCents);
+        const preview = {
+            action: preflight.plan.reusedEnrollmentId
+                ? "enroll kid into cohort by reusing an existing enrollment (no charge)"
+                : billing.chargesImmediately
+                    ? `enroll kid into cohort and CHARGE ${amount} NOW${recurrence}`
+                    : `enroll kid into cohort with first charge of ${amount} on ${billing.firstChargeAt}${recurrence}`,
+            target: {
+                kid: `${preflight.plan.kid.firstName ?? ""} ${preflight.plan.kid.lastName ?? ""}`.trim(),
+                userId,
+                cohort: preflight.plan.cohort.name,
+                cohortId,
+                course: preflight.plan.cohort.courseName,
+            },
+            request: { ...body, dryRun: false },
+            details: {
+                billing,
+                reusedEnrollmentId: preflight.plan.reusedEnrollmentId,
+                warnings: preflight.warnings,
+                ...(preflight.warnings.length > 0 && !body.force
+                    ? {
+                        blocked: "These warnings will reject the write unless you also pass --force.",
+                    }
+                    : {}),
+            },
+        };
+        return previewBoundWrite(parsed, preview, async () => 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 });
@@ -2141,12 +2477,20 @@ export async function runCommand(argv) {
             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: {
+            const limit = flagNumber(parsed, "limit") ?? 20;
+            if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+                throw new CliError("invalid_arguments", "--limit must be an integer between 1 and 100.");
+            }
+            return unwrap(await api.client.GET("/admin/payout/recipient/", {
+                params: {
                     query: {
                         ...(search ? { search } : {}),
                         ...(userId ? { userId } : {}),
                         ...(id ? { id } : {}),
+                        limit,
+                        ...(flagString(parsed, "cursor")
+                            ? { cursor: flagString(parsed, "cursor") }
+                            : {}),
                     },
                 },
             }));
@@ -2483,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
@@ -2767,6 +2903,19 @@ export async function runCommand(argv) {
         if (verb === "set-stage") {
             const stage = assertChoice(flagString(parsed, "stage", { required: true }), CONTENT_LIBRARY_RESOURCE_STAGES, "--stage");
             const input = await readContentLibraryGemTargets(parsed);
+            const wait = hasFlag(parsed, "wait");
+            const timeoutSeconds = flagNumber(parsed, "timeout") ?? 900;
+            if (hasFlag(parsed, "timeout") && !wait) {
+                throw new CliError("invalid_arguments", "--timeout requires --wait.");
+            }
+            if (wait && stage !== "live") {
+                throw new CliError("invalid_arguments", "--wait is supported for content-library set-stage only when --stage live.");
+            }
+            if (!Number.isInteger(timeoutSeconds) ||
+                timeoutSeconds < 10 ||
+                timeoutSeconds > 7200) {
+                throw new CliError("invalid_arguments", "--timeout must be an integer number of seconds from 10 through 7200.");
+            }
             const preflightBody = {
                 gems: input.gems,
                 stage,
@@ -2783,16 +2932,39 @@ export async function runCommand(argv) {
                     resources: preflight.results,
                     lifecycle: "Uses the same lifecycle as Manage. Direct-to-Live never bypasses unfinished polishing; leaving Polishing cancels its bound run before moving.",
                     concurrency: 3,
+                    waitForLive: wait,
+                    ...(wait ? { timeoutSeconds } : {}),
                     ...(input.file ? { inputFile: input.file } : {}),
                 },
             };
-            return writeCommand(parsed, preview, async () => unwrap(await api.client.POST("/admin/content-library/transition", {
-                body: { gems: input.gems, stage, dryRun: false },
-            })));
+            return writeCommand(parsed, preview, async () => {
+                const result = unwrap(await api.client.POST("/admin/content-library/transition", {
+                    body: { gems: input.gems, stage, dryRun: false },
+                }));
+                if (!wait)
+                    return result;
+                return {
+                    ...result,
+                    wait: await waitForContentLibraryLive(api, input.gems, timeoutSeconds),
+                };
+            });
         }
         if (verb === "submit") {
             const stage = assertChoice(flagString(parsed, "stage") ?? "review", CONTENT_LIBRARY_STAGES, "--stage");
             const input = await readContentLibrarySubmitItems(parsed);
+            const wait = hasFlag(parsed, "wait");
+            const timeoutSeconds = flagNumber(parsed, "timeout") ?? 900;
+            if (hasFlag(parsed, "timeout") && !wait) {
+                throw new CliError("invalid_arguments", "--timeout requires --wait.");
+            }
+            if (wait && stage !== "polish") {
+                throw new CliError("invalid_arguments", "--wait is supported for content-library submit only when --stage polish.");
+            }
+            if (!Number.isInteger(timeoutSeconds) ||
+                timeoutSeconds < 10 ||
+                timeoutSeconds > 7200) {
+                throw new CliError("invalid_arguments", "--timeout must be an integer number of seconds from 10 through 7200.");
+            }
             const body = { stage, items: input.items };
             const preview = {
                 action: "content-library.submit",
@@ -2804,51 +2976,57 @@ export async function runCommand(argv) {
                         : "Holds each new resource in REVIEW until an admin approves it.",
                     duplicateBehavior: "Existing URLs are returned as duplicates and are not overwritten.",
                     deployOrderFence: "The server verifies the island's review/polish lifecycle capability before its first write.",
+                    waitForLive: wait,
+                    ...(wait ? { timeoutSeconds } : {}),
                     ...(input.file ? { inputFile: input.file } : {}),
                 },
             };
-            return writeCommand(parsed, preview, async () => unwrap(await api.client.POST("/admin/content-library/submit", {
-                body,
-            })));
+            return writeCommand(parsed, preview, async () => {
+                const result = unwrap(await api.client.POST("/admin/content-library/submit", {
+                    body,
+                }));
+                if (!wait)
+                    return result;
+                return {
+                    ...result,
+                    wait: await waitForContentLibraryLive(api, input.items.map((item) => item.url), timeoutSeconds),
+                };
+            });
         }
         throw new CliError("invalid_arguments", "Use content-library search, status, set-stage, or submit.");
     }
     if (noun === "goal-templates") {
         if (verb === "list") {
-            const query = flagString(parsed, "query")?.toLowerCase();
+            const query = flagString(parsed, "query");
             const kind = flagString(parsed, "kind");
-            const data = unwrap(await api.client.GET("/ai/goal-templates/", {
+            const wantedKind = kind
+                ? assertChoice(kind, GOAL_TEMPLATE_KINDS, "--kind")
+                : undefined;
+            const limit = flagNumber(parsed, "limit") ?? 20;
+            if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+                throw new CliError("invalid_arguments", "--limit must be an integer between 1 and 100.");
+            }
+            return unwrap(await api.client.GET("/ai/goal-templates/", {
                 params: {
                     query: {
                         ...(flagString(parsed, "category")
                             ? { category: flagString(parsed, "category") }
                             : {}),
+                        ...(query ? { query } : {}),
+                        ...(wantedKind ? { kind: wantedKind } : {}),
                         includeDeleted: hasFlag(parsed, "include-deleted")
                             ? "true"
                             : "false",
                         starterOnly: hasFlag(parsed, "starter-only")
                             ? "true"
                             : "false",
+                        limit,
+                        ...(flagString(parsed, "cursor")
+                            ? { cursor: flagString(parsed, "cursor") }
+                            : {}),
                     },
                 },
             }));
-            // The route filters by category/starter/deleted only; `--query` and
-            // `--kind` narrow the returned page here rather than pretending the
-            // backend supports them.
-            const wantedKind = kind
-                ? assertChoice(kind, GOAL_TEMPLATE_KINDS, "--kind")
-                : undefined;
-            const items = data.items.filter((item) => {
-                if (wantedKind && item.kind !== wantedKind)
-                    return false;
-                if (!query)
-                    return true;
-                return [item.title, item.slug, item.description, item.category ?? ""]
-                    .join("\n")
-                    .toLowerCase()
-                    .includes(query);
-            });
-            return { items, totalBeforeFilter: data.items.length };
         }
         if (verb === "get") {
             const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
@@ -2953,7 +3131,7 @@ export async function runCommand(argv) {
             // protected-inventory counting, and the token binding the approved loss
             // to this exact version + result hash. Always ask it for a fresh preview,
             // including on a confirmed run, before permitting the write request.
-            const preflight = unwrap(await api.client.POST("/admin/goal-templates/{id}/setup-workflow-spec/patch", {
+            const preflight = unwrap(await api.client.POST("/ai/goal-templates/{id}/setup-workflow-spec/patch", {
                 params: { path: { id } },
                 body: {
                     expectedVersion,
@@ -2991,7 +3169,9 @@ export async function runCommand(argv) {
                         : {}),
                 },
             };
-            requireConfirmation(hasFlag(parsed, "confirm"), preview);
+            if (!hasFlag(parsed, "confirm")) {
+                await requirePreviewBoundConfirmation(parsed, preview);
+            }
             const destructiveChangeToken = flagString(parsed, "destructive-change-token");
             if (preflight.preview.destructiveChanges &&
                 (!hasFlag(parsed, "confirm-destructive-changes") ||
@@ -3007,7 +3187,7 @@ export async function runCommand(argv) {
                     expectedDestructiveChangeToken: preflight.preview.destructiveChangeToken,
                 });
             }
-            return unwrap(await api.client.POST("/admin/goal-templates/{id}/setup-workflow-spec/patch", {
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.POST("/ai/goal-templates/{id}/setup-workflow-spec/patch", {
                 params: { path: { id } },
                 body: {
                     expectedVersion,
@@ -3016,7 +3196,7 @@ export async function runCommand(argv) {
                     confirmDestructiveChanges: preflight.preview.destructiveChanges,
                     ...(destructiveChangeToken ? { destructiveChangeToken } : {}),
                 },
-            }));
+            })));
         }
         if (verb === "set-metadata") {
             const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
@@ -3085,7 +3265,7 @@ export async function runCommand(argv) {
                 action: "update goal template metadata (never its setupWorkflowSpec)",
                 target: { templateId: id, expectedVersion },
                 request: body,
-            }, async () => unwrap(await api.client.PUT("/admin/goal-templates/{id}", {
+            }, async () => unwrap(await api.client.PUT("/ai/goal-templates/{id}", {
                 params: { path: { id } },
                 body,
             })));
@@ -3096,7 +3276,7 @@ export async function runCommand(argv) {
             // Read the current version so the gate refuses a stale delete locally,
             // and so the preview names the template a human is being asked to approve
             // rather than only its UUID.
-            const current = unwrap(await api.client.GET("/admin/goal-templates/{id}", {
+            const current = unwrap(await api.client.GET("/ai/goal-templates/{id}", {
                 params: { path: { id } },
             }));
             if (current.version !== expectedVersion) {
@@ -3114,7 +3294,7 @@ export async function runCommand(argv) {
                 details: {
                     note: "Soft delete: the row keeps its deletedAt and drops out of every list. Existing goals already applied from it are unaffected.",
                 },
-            }, async () => unwrap(await api.client.DELETE("/admin/goal-templates/{id}", {
+            }, async () => unwrap(await api.client.DELETE("/ai/goal-templates/{id}", {
                 params: { path: { id } },
             })));
         }
@@ -3134,18 +3314,43 @@ export async function runCommand(argv) {
             const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
             const sourceGoalId = flagString(parsed, "source-goal");
             const sourceDraft = flagString(parsed, "source-draft");
-            if (Boolean(sourceGoalId) === Boolean(sourceDraft)) {
-                throw new CliError("invalid_arguments", "Pass exactly one of --source-goal or --source-draft.");
+            const sourceDirectory = flagString(parsed, "source-dir");
+            if ([sourceGoalId, sourceDraft, sourceDirectory].filter(Boolean).length !==
+                1) {
+                throw new CliError("invalid_arguments", "Pass exactly one of --source-goal, --source-draft, or --source-dir.");
+            }
+            const checkout = sourceDirectory
+                ? await readRecessGitMetadata(sourceDirectory)
+                : null;
+            const checkoutHead = checkout
+                ? await assertCheckoutReadyForMaterialization(checkout)
+                : null;
+            const requestedSourceStudentId = flagString(parsed, "student");
+            if (checkout &&
+                requestedSourceStudentId &&
+                requestedSourceStudentId !== checkout.metadata.studentId) {
+                throw new CliError("invalid_arguments", `--student ${requestedSourceStudentId} does not match checkout owner ${checkout.metadata.studentId}.`);
             }
             const sourceStudentUserId = sourceDraft
                 ? flagString(parsed, "student", { required: true })
-                : undefined;
-            const source = sourceGoalId
-                ? { sourceGoalId }
-                : {
-                    sourceWorkspacePath: `drafts/${sourceDraft}/workspace`,
-                    sourceStudentUserId,
+                : checkout?.metadata.studentId;
+            let source;
+            if (sourceGoalId) {
+                source = { sourceGoalId };
+            }
+            else if (checkout?.metadata.target.kind === "goal") {
+                source = { sourceGoalId: checkout.metadata.target.goalId };
+            }
+            else {
+                const draftSlug = sourceDraft ??
+                    (checkout?.metadata.target.kind === "draft"
+                        ? checkout.metadata.target.draftSlug
+                        : undefined);
+                source = {
+                    sourceWorkspacePath: `drafts/${draftSlug}/workspace`,
+                    sourceStudentUserId: sourceStudentUserId,
                 };
+            }
             const preflight = unwrap(await api.client.POST("/ai/goal-templates/{id}/snapshot/capture", {
                 params: { path: { id } },
                 body: { ...source, dryRun: true },
@@ -3153,6 +3358,10 @@ export async function runCommand(argv) {
             if (preflight.action !== "preview_capture_snapshot") {
                 throw new CliError("unexpected_response", "Snapshot capture did not return a preview; nothing was captured.");
             }
+            if (checkout &&
+                preflight.source.changeId !== checkout.metadata.changeId) {
+                throw new CliError("stale_workspace", `Workspace changed from ${checkout.metadata.changeId} to ${preflight.source.changeId}. Check it out again before capturing; nothing was captured.`);
+            }
             if (hasFlag(parsed, "dry-run"))
                 return preflight;
             const preview = {
@@ -3169,6 +3378,13 @@ export async function runCommand(argv) {
                     fileCount: preflight.snapshot.fileCount,
                     sizeBytes: preflight.snapshot.sizeBytes,
                     sha256: preflight.snapshot.sha256,
+                    ...(checkout
+                        ? {
+                            sourceDirectory: checkout.root,
+                            localHeadCommit: checkoutHead,
+                            mesaChangeId: checkout.metadata.changeId,
+                        }
+                        : {}),
                 },
                 details: {
                     modules: preflight.snapshot.modules,
@@ -3177,8 +3393,7 @@ export async function runCommand(argv) {
                     note: "The confirmed request is fenced to both this template version and this exact source revision. Capturing bumps the template version unless the snapshot is unchanged.",
                 },
             };
-            requireConfirmation(hasFlag(parsed, "confirm"), preview);
-            return unwrap(await api.client.POST("/ai/goal-templates/{id}/snapshot/capture", {
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.POST("/ai/goal-templates/{id}/snapshot/capture", {
                 params: { path: { id } },
                 body: {
                     ...source,
@@ -3186,7 +3401,7 @@ export async function runCommand(argv) {
                     expectedTemplateVersion: preflight.template.version,
                     expectedSourceChangeId: preflight.source.changeId,
                 },
-            }));
+            })));
         }
         if (verb === "apply") {
             const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
@@ -3230,15 +3445,14 @@ export async function runCommand(argv) {
                     note: "Counts come from the backend's own dry run. `skipped_existing` items are idempotent — re-applying does not duplicate them.",
                 },
             };
-            requirePreviewBoundConfirmation(parsed, preview);
-            return unwrap(await api.client.POST("/ai/goal-templates/{id}/apply-workflow", {
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.POST("/ai/goal-templates/{id}/apply-workflow", {
                 params: { path: { id } },
                 body: {
                     answers,
                     dryRun: false,
                     expectedTemplateVersion: preflight.templateVersion,
                 },
-            }));
+            })));
         }
         if (verb === "apply-starter") {
             const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
@@ -3272,7 +3486,30 @@ export async function runCommand(argv) {
             }));
         }
         if (verb === "create") {
-            const userId = flagString(parsed, "student", { required: true });
+            const requestedStudentId = flagString(parsed, "student");
+            const sourceDirectory = flagString(parsed, "source-dir");
+            const explicitDraftSlug = flagString(parsed, "draft");
+            if (sourceDirectory && explicitDraftSlug) {
+                throw new CliError("invalid_arguments", "Pass either --source-dir or --draft, not both.");
+            }
+            const checkout = sourceDirectory
+                ? await readRecessGitMetadata(sourceDirectory)
+                : null;
+            if (checkout && checkout.metadata.target.kind !== "draft") {
+                throw new CliError("invalid_checkout", "A fresh module goal must be created from a draft checkout, not an existing goal checkout.");
+            }
+            const checkoutHead = checkout
+                ? await assertCheckoutReadyForMaterialization(checkout)
+                : null;
+            if (checkout &&
+                requestedStudentId &&
+                requestedStudentId !== checkout.metadata.studentId) {
+                throw new CliError("invalid_arguments", `--student ${requestedStudentId} does not match checkout owner ${checkout.metadata.studentId}.`);
+            }
+            const userId = requestedStudentId ?? checkout?.metadata.studentId;
+            if (!userId) {
+                throw new CliError("invalid_arguments", "Pass --student for a direct goal create, or use a Recess draft --source-dir.");
+            }
             const title = flagString(parsed, "title", { required: true });
             const descriptionFile = flagString(parsed, "description-file");
             const descriptionFlag = flagString(parsed, "description");
@@ -3288,14 +3525,17 @@ export async function runCommand(argv) {
                 throw new CliError("invalid_arguments", "--target-date must be an ISO 8601 datetime.");
             }
             const schedule = flagString(parsed, "schedule");
-            const draftSlug = flagString(parsed, "draft");
+            const draftSlug = explicitDraftSlug ??
+                (checkout?.metadata.target.kind === "draft"
+                    ? checkout.metadata.target.draftSlug
+                    : undefined);
             const enablesAppletFollowUps = hasFlag(parsed, "enable-applet-follow-ups");
             const disablesAppletFollowUps = hasFlag(parsed, "disable-applet-follow-ups");
             if (draftSlug && enablesAppletFollowUps === disablesAppletFollowUps) {
                 throw new CliError("invalid_arguments", "A module-backed goal requires exactly one of --enable-applet-follow-ups or --disable-applet-follow-ups.");
             }
             if (!draftSlug && (enablesAppletFollowUps || disablesAppletFollowUps)) {
-                throw new CliError("invalid_arguments", "Applet follow-up flags are used with --draft for direct module-backed goals.");
+                throw new CliError("invalid_arguments", "Applet follow-up flags are used with --draft or --source-dir for module-backed goals.");
             }
             if (draftSlug) {
                 const body = {
@@ -3313,6 +3553,10 @@ export async function runCommand(argv) {
                 if (preflight.action !== "preview_module_goal_create") {
                     throw new CliError("unexpected_response", "Direct module goal creation did not return a preview; no goal was created.");
                 }
+                if (checkout &&
+                    preflight.currentChangeId !== checkout.metadata.changeId) {
+                    throw new CliError("stale_workspace", `Draft changed from ${checkout.metadata.changeId} to ${preflight.currentChangeId}. Check it out again before creating the goal; nothing was created.`);
+                }
                 const preview = {
                     action: "create a module-backed goal directly from a validated draft workspace",
                     target: preflight.target,
@@ -3325,6 +3569,13 @@ export async function runCommand(argv) {
                         targetDate: targetDate ?? null,
                         schedule: schedule ?? null,
                         enableAppletFollowUps: enablesAppletFollowUps,
+                        ...(checkout
+                            ? {
+                                sourceDirectory: checkout.root,
+                                localHeadCommit: checkoutHead,
+                                mesaChangeId: checkout.metadata.changeId,
+                            }
+                            : {}),
                     },
                     details: {
                         currentChangeId: preflight.currentChangeId,
@@ -3338,14 +3589,35 @@ export async function runCommand(argv) {
                         note: "Creates a personal module-backed goal directly. It does not create, capture, or apply a reusable template. After success, Recess removes the draft only when no newer Mesa edit has landed; otherwise it preserves the draft.",
                     },
                 };
-                requirePreviewBoundConfirmation(parsed, preview);
-                return unwrap(await api.client.POST("/tutor/browser/mesa/goals", {
-                    body: {
-                        ...body,
-                        dryRun: false,
-                        expectedWorkspaceChangeId: preflight.currentChangeId,
-                    },
-                }));
+                return previewBoundWrite(parsed, preview, async () => {
+                    const result = unwrap(await api.client.POST("/tutor/browser/mesa/goals", {
+                        body: {
+                            ...body,
+                            dryRun: false,
+                            expectedWorkspaceChangeId: preflight.currentChangeId,
+                        },
+                    }));
+                    if (result.action !== "create_module_goal") {
+                        throw new CliError("unexpected_response", "Module goal creation returned a preview instead of creating the goal.");
+                    }
+                    if (checkout && result.mesaChangeId) {
+                        await writeRecessGitMetadata(checkout.root, {
+                            ...checkout.metadata,
+                            target: { kind: "goal", goalId: result.goalId },
+                            changeId: result.mesaChangeId,
+                            upstreamCommit: checkoutHead,
+                        });
+                        return {
+                            ...result,
+                            local: {
+                                directory: checkout.root,
+                                target: { kind: "goal", goalId: result.goalId },
+                                upstreamCommit: checkoutHead,
+                            },
+                        };
+                    }
+                    return result;
+                });
             }
             const body = {
                 title,
@@ -3363,7 +3635,7 @@ export async function runCommand(argv) {
                     schedule: schedule ?? null,
                 },
                 details: {
-                    note: "Creates a description-only goal with no modules or course workspace. Pass --draft to create a personal module-backed goal directly. A 409 GOAL_LIMIT_REACHED means the kid is at capacity and nothing was created.",
+                    note: "Creates a description-only goal with no modules or course workspace. Pass a draft checkout with --source-dir to create a personal module-backed goal. A 409 GOAL_LIMIT_REACHED means the kid is at capacity and nothing was created.",
                 },
             }, async () => unwrap(await api.client.POST("/tutor/browser/students/{userId}/goals/", {
                 params: { path: { userId } },
@@ -3392,11 +3664,39 @@ export async function runCommand(argv) {
                     patch,
                 },
             };
-            requirePreviewBoundConfirmation(parsed, preview);
-            return unwrap(await api.client.PATCH("/tutor/browser/students/goals/{goalId}/", {
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.PATCH("/tutor/browser/students/goals/{goalId}/", {
                 params: { path: { goalId } },
                 body: patch,
-            }));
+            })));
+        }
+        if (verb === "delete") {
+            const goalId = positional(parsed, 2, "goal ID");
+            const studentId = flagString(parsed, "student", { required: true });
+            const current = unwrap(await api.client.GET("/tutor/browser/students/{userId}/goals/", {
+                params: { path: { userId: studentId } },
+            })).goals.find((goal) => goal.id === goalId);
+            if (!current) {
+                throw new CliError("not_found", `Goal ${goalId} was not found for student ${studentId}.`);
+            }
+            const preview = {
+                action: "soft-delete a goal for a managed student",
+                target: {
+                    goalId,
+                    studentUserId: studentId,
+                    title: current.title,
+                    status: current.status,
+                },
+                request: { expectedUpdatedAt: current.updatedAt },
+                details: {
+                    note: "Soft-deletes the goal and its current/future dated todos. Historical todos and the deletion audit remain available.",
+                },
+            };
+            return previewBoundWrite(parsed, preview, async () => {
+                unwrap(await api.client.DELETE("/admin/browser/students/goals/{goalId}/", {
+                    params: { path: { goalId } },
+                }));
+                return { deleted: true, goalId, studentUserId: studentId };
+            });
         }
         if (verb === "queue") {
             const subverb = positional(parsed, 2, "queue action (get|set)");
@@ -3411,7 +3711,7 @@ export async function runCommand(argv) {
                 });
                 const delta = flagString(parsed, "delta", { required: true });
                 const replaceDescriptionPointer = hasFlag(parsed, "replace-description-pointer");
-                const { absolutePath, parsed: rawEntries } = await readJsonValue(entriesFile, "Queue entries file");
+                const { absolutePath, raw: rawEntriesText, parsed: rawEntries, } = await readJsonValue(entriesFile, "Queue entries file");
                 const entries = parseGoalQueueEntries(rawEntries, "Queue entries file");
                 const goal = unwrap(await api.client.GET("/tutor/browser/students/{userId}/goals/", {
                     params: { path: { userId: studentId } },
@@ -3422,15 +3722,36 @@ export async function runCommand(argv) {
                 const current = unwrap(await api.client.GET("/tutor/browser/students/goals/{goalId}/queue/", { params: { path: { goalId } } }));
                 const currentUrls = new Set(current.queue.map((item) => item.url));
                 const proposedUrls = new Set(entries.map((entry) => entry.url));
+                const currentByUrl = new Map(current.queue.map((item) => [item.url, item]));
+                const completionChanges = entries.flatMap((entry) => {
+                    if (entry.completed === undefined)
+                        return [];
+                    const existing = currentByUrl.get(entry.url);
+                    const currentlyCompleted = existing?.completedAt != null;
+                    if (currentlyCompleted === entry.completed)
+                        return [];
+                    return [
+                        {
+                            moduleRef: existing?.moduleRef ?? null,
+                            url: entry.url,
+                            fromCompletedAt: existing?.completedAt ?? null,
+                            toCompleted: entry.completed,
+                        },
+                    ];
+                });
                 const preview = {
                     action: "replace a goal's URL skill queue for a managed student",
                     target: { goalId, studentUserId: studentId },
                     request: {
                         entriesFile: absolutePath,
+                        entriesSha256: createHash("sha256")
+                            .update(rawEntriesText)
+                            .digest("hex"),
                         entryCount: entries.length,
                         delta,
                         replaceDescriptionPointer,
                         expectedUpdatedAt: goal.updatedAt,
+                        unchangedTitleForConcurrencyFence: goal.title,
                     },
                     details: {
                         currentQueue: current.queue.map((item) => ({
@@ -3444,26 +3765,31 @@ export async function runCommand(argv) {
                         removed: current.queue
                             .filter((item) => !proposedUrls.has(item.url))
                             .map((item) => item.url),
+                        completionChanges,
                         note: "Replaces the entire EXTERNAL_URL queue. Completion is preserved for unchanged URLs; WORKSPACE modules are untouched. Daily generation mints the head entry for a flag-on kid.",
                     },
                 };
-                requirePreviewBoundConfirmation(parsed, preview);
                 const body = {
                     delta,
                     expectedUpdatedAt: goal.updatedAt,
+                    // The deployed route's queue-only CAS reaches Prisma with an empty
+                    // scalar update, which reports zero rows and falsely trips the stale
+                    // write fence. Echoing the already-previewed title gives that CAS a
+                    // real update field without changing the title.
+                    title: goal.title,
                     queue: entries,
                     ...(replaceDescriptionPointer
                         ? { description: URL_QUEUE_DESCRIPTION_POINTER }
                         : {}),
                 };
-                return unwrap(await api.client.PATCH("/tutor/browser/students/goals/{goalId}/", {
+                return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.PATCH("/tutor/browser/students/goals/{goalId}/", {
                     params: { path: { goalId } },
                     body,
-                }));
+                })));
             }
             throw new CliError("invalid_arguments", "Use goals queue get|set.");
         }
-        throw new CliError("invalid_arguments", "Use goals list|create|edit|queue|files|pdf.");
+        throw new CliError("invalid_arguments", "Use goals list|create|edit|delete|queue|files|pdf.");
     }
     if (noun === "students") {
         if (verb === "list") {
@@ -3559,11 +3885,37 @@ export async function runCommand(argv) {
                     patch: body,
                 },
             };
-            requirePreviewBoundConfirmation(parsed, preview);
-            return unwrap(await api.client.PATCH("/tutor/browser/todos/{id}", {
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.PATCH("/tutor/browser/todos/{id}", {
                 params: { path: { id: todoId } },
                 body,
+            })));
+        }
+        if (verb === "delete") {
+            const todoId = positional(parsed, 2, "todo ID");
+            const current = unwrap(await api.client.GET("/tutor/browser/todos/{id}/", {
+                params: { path: { id: todoId } },
             }));
+            const preview = {
+                action: "permanently delete a todo for a managed student",
+                target: {
+                    todoId,
+                    studentUserId: current.userId,
+                    title: current.title,
+                    status: current.status,
+                    goalId: current.goal?.id ?? null,
+                },
+                request: { expectedUpdatedAt: current.updatedAt },
+                details: {
+                    dueDate: current.dueDate,
+                    creationSource: current.creationSource,
+                    creationSourceId: current.creationSourceId,
+                    url: "url" in current ? current.url : null,
+                    note: "Hard-deletes this todo without awarding XP or running todo-completion side effects. This is permanent; use it only when the preview identifies a disposable todo with no work to preserve.",
+                },
+            };
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.DELETE("/admin/todos/{id}/", {
+                params: { path: { id: todoId } },
+            })));
         }
         if (verb === "generate-applet") {
             const todoId = positional(parsed, 2, "todo ID");
@@ -3601,13 +3953,12 @@ export async function runCommand(argv) {
                     versionRouting: "The server evaluates applet-gen-v2 for this student and uses v1 when the flag is off or its evaluation fails.",
                 },
             };
-            requirePreviewBoundConfirmation(parsed, preview);
-            return unwrap(await api.client.POST("/admin/learning-pipeline/{analysisId}/generate-applet/", {
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.POST("/admin/learning-pipeline/{analysisId}/generate-applet/", {
                 params: { path: { analysisId: analysis.id } },
                 body: targetDueDateISO ? { targetDueDateISO } : {},
-            }));
+            })));
         }
-        throw new CliError("invalid_arguments", "Use todos create|edit|generate-applet.");
+        throw new CliError("invalid_arguments", "Use todos create|edit|delete|generate-applet.");
     }
     if (noun === "memories") {
         const studentId = flagString(parsed, "student", { required: true });
@@ -3715,7 +4066,7 @@ export async function runCommand(argv) {
         if (preflight.action !== "preview_workspace_files_write") {
             throw new CliError("unexpected_response", "Goal PDF upload did not return a preview; nothing was uploaded.");
         }
-        requirePreviewBoundConfirmation(parsed, {
+        const preview = {
             action: "upload a textbook PDF and attach it to a student's goal",
             target: preflight.target,
             request: {
@@ -3729,111 +4080,114 @@ export async function runCommand(argv) {
                 currentChangeId: preflight.currentChangeId,
                 note: "The PDF is stored separately and the goal workspace receives a small verified reference, matching planner-authored textbook goals.",
             },
-        });
-        const conversationId = randomUUID();
-        const signed = unwrap(await api.client.POST("/os-v2-mesa/planner/uploads/sign", {
-            body: {
-                conversationId,
-                studentUserId: studentId,
-                fileName,
-                contentType: "application/pdf",
-                sizeBytes: fileStat.size,
-            },
-        }));
-        let uploaded;
-        try {
-            const uploadedSource = await uploadPdfToSignedUrls(absolutePath, "application/pdf", signed);
-            if (uploadedSource.sha256 !== sourceSha256 ||
-                uploadedSource.sizeBytes !== fileStat.size) {
-                throw new CliError("source_changed", "The source PDF changed after approval. The upload was discarded; preview the current file again.");
-            }
-            uploaded =
-                signed.kind === "multipart"
-                    ? unwrap(await api.client.POST("/os-v2-mesa/planner/uploads/complete", {
-                        body: {
-                            conversationId,
-                            fileName,
-                            contentType: "application/pdf",
-                            key: signed.key,
-                            uploadId: signed.uploadId,
-                            sizeBytes: fileStat.size,
-                        },
-                    }))
-                    : unwrap(await api.client.POST("/os-v2-mesa/planner/uploads/verify", {
-                        body: {
-                            conversationId,
-                            fileName,
-                            contentType: "application/pdf",
-                            key: signed.key,
-                            sizeBytes: fileStat.size,
-                        },
-                    }));
-        }
-        catch (error) {
-            // A failed multipart complete may already have materialized the object,
-            // so attempt both abort and delete. These are compensation attempts; the
-            // original upload error remains authoritative.
-            await cleanupPlannerUpload(api, conversationId, signed, true);
-            throw error;
-        }
-        const manifest = JSON.stringify({
-            kind: "r2-pdf",
-            version: 2,
-            r2Key: uploaded.key,
-            signature: uploaded.manifestSignature,
-            fileName,
-            contentType: uploaded.contentType,
-            sizeBytes: uploaded.sizeBytes,
-        });
-        let workspace;
-        try {
-            workspace = unwrap(await api.client.POST("/tutor/browser/mesa/workspace-files", {
+        };
+        return previewBoundWrite(parsed, preview, async () => {
+            const conversationId = randomUUID();
+            const signed = unwrap(await api.client.POST("/os-v2-mesa/planner/uploads/sign", {
                 body: {
-                    ...body,
-                    files: [
-                        {
-                            path: workspacePath,
-                            content: manifest,
-                            contentEncoding: "utf8",
-                        },
-                    ],
-                    dryRun: false,
-                    expectedChangeId: preflight.currentChangeId,
+                    conversationId,
+                    studentUserId: studentId,
+                    fileName,
+                    contentType: "application/pdf",
+                    sizeBytes: fileStat.size,
                 },
             }));
-        }
-        catch (error) {
-            // Only a returned 4xx from this route is a definitive no-write response.
-            // A transport/5xx failure is ambiguous: the workspace commit may have landed,
-            // so keep the object rather than creating a dangling manifest.
-            const status = error instanceof CliError &&
-                error.details &&
-                typeof error.details === "object" &&
-                "status" in error.details
-                ? Number(error.details.status)
-                : 0;
-            if (status >= 400 && status < 500) {
+            let uploaded;
+            try {
+                const uploadedSource = await uploadPdfToSignedUrls(absolutePath, "application/pdf", signed);
+                if (uploadedSource.sha256 !== sourceSha256 ||
+                    uploadedSource.sizeBytes !== fileStat.size) {
+                    throw new CliError("source_changed", "The source PDF changed after approval. The upload was discarded; preview the current file again.");
+                }
+                uploaded =
+                    signed.kind === "multipart"
+                        ? unwrap(await api.client.POST("/os-v2-mesa/planner/uploads/complete", {
+                            body: {
+                                conversationId,
+                                fileName,
+                                contentType: "application/pdf",
+                                key: signed.key,
+                                uploadId: signed.uploadId,
+                                sizeBytes: fileStat.size,
+                            },
+                        }))
+                        : unwrap(await api.client.POST("/os-v2-mesa/planner/uploads/verify", {
+                            body: {
+                                conversationId,
+                                fileName,
+                                contentType: "application/pdf",
+                                key: signed.key,
+                                sizeBytes: fileStat.size,
+                            },
+                        }));
+            }
+            catch (error) {
+                // A failed multipart complete may already have materialized the object,
+                // so attempt both abort and delete. These are compensation attempts; the
+                // original upload error remains authoritative.
                 await cleanupPlannerUpload(api, conversationId, signed, true);
+                throw error;
             }
-            throw error;
-        }
-        return {
-            action: "upload_textbook_pdf",
-            sourceSha256,
-            fileName,
-            sizeBytes: uploaded.sizeBytes,
-            workspacePath,
-            workspace,
-        };
+            const manifest = JSON.stringify({
+                kind: "r2-pdf",
+                version: 2,
+                r2Key: uploaded.key,
+                signature: uploaded.manifestSignature,
+                fileName,
+                contentType: uploaded.contentType,
+                sizeBytes: uploaded.sizeBytes,
+            });
+            let workspace;
+            try {
+                workspace = unwrap(await api.client.POST("/tutor/browser/mesa/workspace-files", {
+                    body: {
+                        ...body,
+                        files: [
+                            {
+                                path: workspacePath,
+                                content: manifest,
+                                contentEncoding: "utf8",
+                            },
+                        ],
+                        dryRun: false,
+                        expectedChangeId: preflight.currentChangeId,
+                    },
+                }));
+            }
+            catch (error) {
+                // Only a returned 4xx from this route is a definitive no-write response.
+                // A transport/5xx failure is ambiguous: the workspace commit may have landed,
+                // so keep the object rather than creating a dangling manifest.
+                const status = error instanceof CliError &&
+                    error.details &&
+                    typeof error.details === "object" &&
+                    "status" in error.details
+                    ? Number(error.details.status)
+                    : 0;
+                if (status >= 400 && status < 500) {
+                    await cleanupPlannerUpload(api, conversationId, signed, true);
+                }
+                throw error;
+            }
+            return {
+                action: "upload_textbook_pdf",
+                sourceSha256,
+                fileName,
+                sizeBytes: uploaded.sizeBytes,
+                workspacePath,
+                workspace,
+            };
+        });
     }
     if (noun === "goals" && verb === "files") {
         const action = positional(parsed, 2, "goals files action");
-        const studentId = flagString(parsed, "student", { required: true });
         if (action === "list") {
+            const studentId = flagString(parsed, "student", { required: true });
             const goalId = flagString(parsed, "goal", { required: true });
             return unwrap(await api.client.GET("/tutor/students/{studentId}/goals/{goalId}/workspace/files", { params: { path: { studentId, goalId } } }));
         }
         if (action === "read") {
+            const studentId = flagString(parsed, "student", { required: true });
             const goalId = flagString(parsed, "goal", { required: true });
             return unwrap(await api.client.GET("/tutor/students/{studentId}/goals/{goalId}/workspace/file", {
                 params: {
@@ -3842,7 +4196,115 @@ export async function runCommand(argv) {
                 },
             }));
         }
+        if (action === "init" || action === "checkout") {
+            const studentId = flagString(parsed, "student", { required: true });
+            const goalId = flagString(parsed, "goal");
+            const draftSlug = flagString(parsed, "draft");
+            if (action === "init" && (goalId || !draftSlug)) {
+                throw new CliError("invalid_arguments", "goals files init requires --draft and does not accept --goal.");
+            }
+            if (Boolean(goalId) === Boolean(draftSlug)) {
+                throw new CliError("invalid_arguments", "Pass exactly one of --goal or --draft for goals files checkout.");
+            }
+            const outputDirectory = flagString(parsed, "output-dir", {
+                required: true,
+            });
+            const target = goalId
+                ? { kind: "goal", goalId }
+                : { kind: "draft", draftSlug: draftSlug };
+            const response = await readRemoteWorkspaceSnapshot(api, studentId, target);
+            if (action === "init" && response.snapshot.fileCount > 0) {
+                throw new CliError("draft_exists", `Draft ${draftSlug} already has files. Use goals files checkout --draft to preserve them.`);
+            }
+            return checkoutGoalWorkspace({
+                outputDirectory,
+                studentId,
+                target,
+                snapshot: response.snapshot,
+            });
+        }
+        if (action === "push") {
+            const sourceDirectory = flagString(parsed, "source-dir", {
+                required: true,
+            });
+            const checkout = await readRecessGitMetadata(sourceDirectory);
+            const local = await readGoalWorkspaceGitChanges(checkout.root, checkout.metadata.upstreamCommit);
+            const defaultMessage = local.commits.length === 1
+                ? local.commits[0].subject
+                : `recess-cli: push ${local.commits.length} commits (${local.commits.at(-1).subject})`;
+            const message = (flagString(parsed, "message") ?? defaultMessage).trim();
+            if (!message || message.length > 200) {
+                throw new CliError("invalid_arguments", "--message (or the derived local commit message) must be 1 to 200 characters.");
+            }
+            const files = local.changes.map((change) => change.action === "delete"
+                ? { path: change.path, action: "delete" }
+                : {
+                    path: change.path,
+                    action: "upsert",
+                    content: change.content,
+                    contentEncoding: change.contentEncoding,
+                });
+            const body = {
+                studentUserId: checkout.metadata.studentId,
+                target: checkout.metadata.target,
+                message,
+                files,
+                expectedChangeId: checkout.metadata.changeId,
+            };
+            const preflight = unwrap(await api.client.POST("/tutor/browser/mesa/workspace-files", {
+                body: { ...body, dryRun: true },
+            }));
+            if (preflight.action !== "preview_workspace_files_write") {
+                throw new CliError("unexpected_response", "Goal workspace push did not return a preview; nothing was written.");
+            }
+            const preview = {
+                action: `push committed Git changes to a student's Mesa ${checkout.metadata.target.kind} workspace`,
+                target: preflight.target,
+                request: {
+                    sourceDirectory: checkout.root,
+                    mesaBaseChangeId: checkout.metadata.changeId,
+                    localBaseCommit: checkout.metadata.upstreamCommit,
+                    localHeadCommit: local.head,
+                    commits: local.commits,
+                    message,
+                    changes: local.changes.map((change) => change.action === "delete"
+                        ? change
+                        : {
+                            path: change.path,
+                            action: change.action,
+                            sizeBytes: change.sizeBytes,
+                            sha256: change.sha256,
+                        }),
+                    sizeBytes: local.sizeBytes,
+                },
+                details: {
+                    currentChangeId: preflight.currentChangeId,
+                    note: "The committed local diff is published as one atomic Mesa change. Deletes and renames follow Git's diff. A changed Mesa tip refuses the push.",
+                },
+            };
+            return previewBoundWrite(parsed, preview, async () => {
+                const result = unwrap(await api.client.POST("/tutor/browser/mesa/workspace-files", {
+                    body: { ...body, dryRun: false },
+                }));
+                if (result.action !== "write_workspace_files") {
+                    throw new CliError("unexpected_response", "Goal workspace push returned an unexpected response.");
+                }
+                await writeRecessGitMetadata(checkout.root, {
+                    ...checkout.metadata,
+                    changeId: result.changeId,
+                    upstreamCommit: local.head,
+                });
+                return {
+                    ...result,
+                    local: {
+                        directory: checkout.root,
+                        upstreamCommit: local.head,
+                    },
+                };
+            });
+        }
         if (action === "write") {
+            const studentId = flagString(parsed, "student", { required: true });
             const goalId = flagString(parsed, "goal");
             const draftSlug = flagString(parsed, "draft");
             if (Boolean(goalId) === Boolean(draftSlug)) {
@@ -3881,19 +4343,18 @@ export async function runCommand(argv) {
                     files: preflight.files,
                     note: target.kind === "draft"
                         ? "This writes a complete authoring tree under drafts/<slug>/workspace. Capture it only after the server's goal-workspace validation passes."
-                        : "Live goal modules/ and state/ are blocked here because they have database projections; use a draft + template capture for structural course changes.",
+                        : "This directly edits the live goal workspace, including modules/ and state/. The write remains bound to the previewed workspace revision.",
                 },
             };
-            requirePreviewBoundConfirmation(parsed, preview);
-            return unwrap(await api.client.POST("/tutor/browser/mesa/workspace-files", {
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.POST("/tutor/browser/mesa/workspace-files", {
                 body: {
                     ...body,
                     dryRun: false,
                     expectedChangeId: preflight.currentChangeId,
                 },
-            }));
+            })));
         }
-        throw new CliError("invalid_arguments", "Use goals files list|read|write.");
+        throw new CliError("invalid_arguments", "Use goals files list|read|init|checkout|push|write.");
     }
     if (noun === "request" && verb === "get") {
         return api.rawGet(positional(parsed, 2, "request path"));