recess-cli 1.2.0 → 1.3.0

package/README.md

@@ -25,7 +25,7 @@ pnpm --dir apps/admin-cli run client:generate
 pnpm --dir apps/admin-cli run install-persistent
 ```
 
-`install-persistent` copies a self-contained build (non-test `dist/` JS + the `openapi-fetch` runtime dep) to `~/.recess-cli/cli/` and points `~/.local/bin/recess` at it — the install keeps working after the checkout or worktree it was built from is deleted. Use it on any machine that operates on production. `install-local` instead symlinks `~/.local/bin/recess` straight to this checkout's `dist/index.js` so rebuilds are picked up live — use it only while actively developing the CLI, and expect the link to die with the worktree. Both targets install the bundled skill for Codex at `${CODEX_HOME:-~/.codex}/skills/recess-cli` and Claude at `${CLAUDE_CONFIG_DIR:-~/.claude}/skills/recess-cli`. The skill is a multi-file bundle: `skill/recess-cli/SKILL.md` carries the safety model, auth troubleshooting, JSON contract, and command quick reference, and routes to the deep workflow playbooks in `skill/recess-cli/reference/` (billing, MAP scores, payouts, class ops).
+`install-persistent` copies a self-contained build (non-test `dist/` JS + the `openapi-fetch` runtime dep) to `~/.recess-cli/cli/` and points `~/.local/bin/recess` at it — the install keeps working after the checkout or worktree it was built from is deleted. Use it on any machine that operates on production. `install-local` instead symlinks `~/.local/bin/recess` straight to this checkout's `dist/index.js` so rebuilds are picked up live — use it only while actively developing the CLI, and expect the link to die with the worktree. Both targets install the bundled skill for Codex at `${CODEX_HOME:-~/.codex}/skills/recess-cli` and Claude at `${CLAUDE_CONFIG_DIR:-~/.claude}/skills/recess-cli`. The skill is a multi-file bundle: `skill/recess-cli/SKILL.md` carries the safety model, auth troubleshooting, JSON contract, and command quick reference, and routes to the deep workflow playbooks in `skill/recess-cli/reference/` (billing, MAP scores, payouts, class ops, onboarding, and goal authoring).
 
 ## One-time SSO setup
 
@@ -100,6 +100,8 @@ recess --json goal-templates validate-spec --file ./template.json   # iterate; w
 recess --json goal-templates create --file ./template.json          # preview, exit 2
 recess --json goal-templates create --file ./template.json --confirm
 recess --json goal-templates patch-spec <id-or-slug> --expected-version 7 --patches-file ./patches.json
+recess --json mesa files write --student <kid-id> --draft <draft-slug> --source-dir ./workspace
+recess --json goal-templates capture-snapshot <id-or-slug> --source-draft <draft-slug> --student <kid-id> --dry-run
 recess --json goal-templates apply <id-or-slug> --answers-file ./answers.json --dry-run
 recess --json goals create --student <kid-id> --title "..." --description-file ./goal.md
 recess --json mesa files list --student <kid-id> --goal <goal-id>
@@ -137,4 +139,10 @@ previews the per-student outcome. `set-metadata` and `delete` require `--expecte
 it always runs the backend's guarded preview first and requires the preview's exact loss token in
 addition to `--confirm` when protected template data would be removed.
 
+MODULE_BACKED BLUEPRINT content is authored as a local workspace tree, batch-upserted to a named
+Mesa draft, then attached with `capture-snapshot`. Both mutations run server previews before the
+confirmation gate. Mesa upserts are compare-and-set against the previewed repo change; capture is
+fenced to both that source change and the template version. Direct live-goal `modules/` and
+`state/` writes are blocked because those files have database projections.
+
 See `recess --help` for the complete command surface. The raw escape hatch is intentionally read-only: `recess --json request get /path`.

package/dist/args.js

@@ -1,4 +1,10 @@
 import { CliError } from "./errors.js";
+/**
+ * Flags that may legitimately appear more than once. Reading one through
+ * `flagString` still yields the LAST value, which is why every consumer of a
+ * repeatable flag must use `flagList` instead.
+ */
+export const REPEATABLE_FLAGS = new Set(["kid", "unassign"]);
 const BOOLEAN_FLAGS = new Set([
     "all-references",
     "allow-strand",
@@ -24,6 +30,16 @@ const BOOLEAN_FLAGS = new Set([
 export function parseArgs(args) {
     const positionals = [];
     const flags = new Map();
+    const repeated = new Map();
+    const record = (name, value) => {
+        if (!REPEATABLE_FLAGS.has(name))
+            return;
+        const existing = repeated.get(name);
+        if (existing)
+            existing.push(value);
+        else
+            repeated.set(name, [value]);
+    };
     for (let index = 0; index < args.length; index += 1) {
         const value = args[index];
         if (!value.startsWith("--")) {
@@ -32,7 +48,10 @@ export function parseArgs(args) {
         }
         const equalsAt = value.indexOf("=");
         if (equalsAt > 2) {
-            flags.set(value.slice(2, equalsAt), value.slice(equalsAt + 1));
+            const name = value.slice(2, equalsAt);
+            const flagValue = value.slice(equalsAt + 1);
+            flags.set(name, flagValue);
+            record(name, flagValue);
             continue;
         }
         const name = value.slice(2);
@@ -43,13 +62,29 @@ export function parseArgs(args) {
         const next = args[index + 1];
         if (next && !next.startsWith("--")) {
             flags.set(name, next);
+            record(name, next);
             index += 1;
         }
         else {
             flags.set(name, true);
         }
     }
-    return { positionals, flags };
+    return { positionals, flags, repeated };
+}
+/**
+ * Every value given for a repeatable flag, in order.
+ *
+ * Returns `[]` when the flag is absent, so a caller distinguishes "none given"
+ * from "given empty" by checking length rather than by a null dance.
+ */
+export function flagList(parsed, name) {
+    if (!REPEATABLE_FLAGS.has(name)) {
+        // A wiring defect, not a user error: reading a non-repeatable flag as a
+        // list would silently return [] however many times it was passed.
+        throw new CliError("invalid_arguments", `--${name} is not declared repeatable; add it to REPEATABLE_FLAGS.`);
+    }
+    const values = parsed.repeated.get(name) ?? [];
+    return values.map((value) => value.trim()).filter(Boolean);
 }
 export function flagString(parsed, name, options = {}) {
     const value = parsed.flags.get(name);

package/dist/cli.js

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { RecessAdminApi, unwrap } from "./api.js";
-import { flagNumber, flagString, hasFlag, parseArgs, } from "./args.js";
+import { flagList, flagNumber, flagString, hasFlag, parseArgs, } from "./args.js";
 import { login, pollDeviceAuth, requestDeviceAuth } from "./auth.js";
 import { clearStoredSession, resolveConfig, } from "./config.js";
 import { CliError } from "./errors.js";
@@ -38,6 +38,9 @@ Usage:
   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]
@@ -128,6 +131,9 @@ Usage:
     [--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 <kid-id>)
+    [--dry-run] [--confirm]
   recess [--json] goal-templates apply <template-id> --answers-file <path>
     [--dry-run] [--confirm]
   recess [--json] goal-templates apply-starter <template-id> --student <kid-id>
@@ -138,6 +144,10 @@ Usage:
     [--schedule TEXT] [--confirm]
   recess [--json] mesa files list --student <kid-id> --goal <goal-id>
   recess [--json] mesa files read --student <kid-id> --goal <goal-id> --path P
+  recess [--json] mesa files write --student <kid-id>
+    (--goal <goal-id> | --draft <draft-slug>)
+    (--source-dir <local-dir> | --source-file <local-file> --path P)
+    [--message TEXT] [--confirm]
 
 Authoring notes: "skills" serves the in-product tutor skills (the PRIVATE
 packages/skills submodule) read-only over your admin session — they are never
@@ -298,6 +308,83 @@ async function writeCommand(parsed, preview, execute) {
     requireConfirmation(hasFlag(parsed, "confirm"), preview);
     return execute();
 }
+const MESA_WRITE_MAX_FILES = 1_000;
+const MESA_WRITE_MAX_TOTAL_BYTES = 20 * 1024 * 1024;
+async function readMesaWriteSource(parsed) {
+    const sourceDirectory = flagString(parsed, "source-dir");
+    const sourceFile = flagString(parsed, "source-file");
+    if (Boolean(sourceDirectory) === Boolean(sourceFile)) {
+        throw new CliError("invalid_arguments", "Pass exactly one of --source-dir or --source-file.");
+    }
+    const files = [];
+    const hash = createHash("sha256");
+    let sizeBytes = 0;
+    let source;
+    const addFile = async (absolutePath, workspacePath) => {
+        if (files.length >= MESA_WRITE_MAX_FILES) {
+            throw new CliError("invalid_arguments", `Mesa workspace writes are limited to ${MESA_WRITE_MAX_FILES} files.`);
+        }
+        const fileStat = await fs.stat(absolutePath);
+        if (sizeBytes + fileStat.size > MESA_WRITE_MAX_TOTAL_BYTES) {
+            throw new CliError("invalid_arguments", `Mesa workspace writes are limited to ${MESA_WRITE_MAX_TOTAL_BYTES} decoded bytes.`);
+        }
+        const bytes = await fs.readFile(absolutePath);
+        sizeBytes += bytes.byteLength;
+        files.push({
+            path: workspacePath.replaceAll(path.sep, "/"),
+            content: bytes.toString("base64"),
+            contentEncoding: "base64",
+        });
+    };
+    if (sourceDirectory) {
+        const root = path.resolve(sourceDirectory);
+        const rootStat = await fs.lstat(root).catch(() => null);
+        if (!rootStat?.isDirectory() || rootStat.isSymbolicLink()) {
+            throw new CliError("invalid_arguments", `--source-dir is not a directory: ${root}`);
+        }
+        source = { kind: "directory", absolutePath: root };
+        const walk = async (directory, relativeRoot = "") => {
+            const entries = await fs.readdir(directory, { withFileTypes: true });
+            entries.sort((a, b) => a.name.localeCompare(b.name));
+            for (const entry of entries) {
+                const relativePath = relativeRoot
+                    ? path.join(relativeRoot, entry.name)
+                    : entry.name;
+                const absolutePath = path.join(directory, entry.name);
+                if (entry.isSymbolicLink()) {
+                    throw new CliError("invalid_arguments", `Refusing symbolic link in --source-dir: ${absolutePath}`);
+                }
+                if (entry.isDirectory()) {
+                    await walk(absolutePath, relativePath);
+                }
+                else if (entry.isFile()) {
+                    await addFile(absolutePath, relativePath);
+                }
+            }
+        };
+        await walk(root);
+    }
+    else {
+        const absolutePath = path.resolve(sourceFile);
+        const fileStat = await fs.lstat(absolutePath).catch(() => null);
+        if (!fileStat?.isFile() || fileStat.isSymbolicLink()) {
+            throw new CliError("invalid_arguments", `--source-file is not a file: ${absolutePath}`);
+        }
+        const workspacePath = flagString(parsed, "path", { required: true });
+        source = { kind: "file", absolutePath };
+        await addFile(absolutePath, workspacePath);
+    }
+    if (files.length === 0) {
+        throw new CliError("invalid_arguments", "The Mesa write source contains no files.");
+    }
+    for (const file of files) {
+        hash.update(file.path);
+        hash.update("\0");
+        hash.update(file.content, "base64");
+        hash.update("\0");
+    }
+    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(", ")}.`);
@@ -625,6 +712,34 @@ 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) {
@@ -1077,6 +1192,48 @@ 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 === "cohorts" && verb === "search") {
         const search = parsed.positionals.slice(2).join(" ").trim();
         if (!search)
@@ -2215,6 +2372,64 @@ export async function runCommand(argv) {
                 params: { path: { id } },
             }));
         }
+        if (verb === "capture-snapshot") {
+            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 sourceStudentUserId = sourceDraft
+                ? flagString(parsed, "student", { required: true })
+                : undefined;
+            const source = sourceGoalId
+                ? { sourceGoalId }
+                : {
+                    sourceWorkspacePath: `drafts/${sourceDraft}/workspace`,
+                    sourceStudentUserId,
+                };
+            const preflight = unwrap(await api.client.POST("/admin/goal-templates/{id}/snapshot/capture", {
+                params: { path: { id } },
+                body: { ...source, dryRun: true },
+            }));
+            if (preflight.action !== "preview_capture_snapshot") {
+                throw new CliError("unexpected_response", "Snapshot capture did not return a preview; nothing was captured.");
+            }
+            if (hasFlag(parsed, "dry-run"))
+                return preflight;
+            const preview = {
+                action: "capture a validated Mesa workspace as this global template's instant-apply snapshot",
+                target: {
+                    templateId: preflight.template.id,
+                    slug: preflight.template.slug,
+                    title: preflight.template.title,
+                    version: preflight.template.version,
+                },
+                request: {
+                    source: preflight.source,
+                    moduleCount: preflight.snapshot.moduleCount,
+                    fileCount: preflight.snapshot.fileCount,
+                    sizeBytes: preflight.snapshot.sizeBytes,
+                    sha256: preflight.snapshot.sha256,
+                },
+                details: {
+                    modules: preflight.snapshot.modules,
+                    paths: preflight.snapshot.paths,
+                    warnings: preflight.warnings,
+                    note: "The confirmed request is fenced to both this template version and this exact Mesa source change. Capturing bumps the template version unless the snapshot is unchanged.",
+                },
+            };
+            requireConfirmation(hasFlag(parsed, "confirm"), preview);
+            return unwrap(await api.client.POST("/admin/goal-templates/{id}/snapshot/capture", {
+                params: { path: { id } },
+                body: {
+                    ...source,
+                    dryRun: false,
+                    expectedTemplateVersion: preflight.template.version,
+                    expectedSourceChangeId: preflight.source.changeId,
+                },
+            }));
+        }
         if (verb === "apply") {
             const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
             const answers = await readJsonFile(flagString(parsed, "answers-file", { required: true }), "Answers file");
@@ -2282,7 +2497,7 @@ export async function runCommand(argv) {
                 body: { studentUserId, answers },
             })));
         }
-        throw new CliError("invalid_arguments", "Use goal-templates list|get|versions|validate-spec|create|patch-spec|set-metadata|delete|snapshot-files|apply|apply-starter.");
+        throw new CliError("invalid_arguments", "Use goal-templates list|get|versions|validate-spec|create|patch-spec|set-metadata|delete|snapshot-files|capture-snapshot|apply|apply-starter.");
     }
     if (noun === "goals") {
         if (verb === "list") {
@@ -2336,11 +2551,12 @@ export async function runCommand(argv) {
     if (noun === "mesa" && verb === "files") {
         const action = positional(parsed, 2, "mesa files action");
         const studentId = flagString(parsed, "student", { required: true });
-        const goalId = flagString(parsed, "goal", { required: true });
         if (action === "list") {
+            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 goalId = flagString(parsed, "goal", { required: true });
             return unwrap(await api.client.GET("/tutor/students/{studentId}/goals/{goalId}/workspace/file", {
                 params: {
                     path: { studentId, goalId },
@@ -2348,7 +2564,58 @@ export async function runCommand(argv) {
                 },
             }));
         }
-        throw new CliError("invalid_arguments", "Use mesa files list|read.");
+        if (action === "write") {
+            const goalId = flagString(parsed, "goal");
+            const draftSlug = flagString(parsed, "draft");
+            if (Boolean(goalId) === Boolean(draftSlug)) {
+                throw new CliError("invalid_arguments", "Pass exactly one of --goal or --draft for mesa files write.");
+            }
+            const input = await readMesaWriteSource(parsed);
+            const target = goalId
+                ? { kind: "goal", goalId }
+                : { kind: "draft", draftSlug: draftSlug };
+            const message = flagString(parsed, "message") ??
+                `recess-cli: write ${input.files.length} workspace file${input.files.length === 1 ? "" : "s"}`;
+            const body = {
+                studentUserId: studentId,
+                target,
+                message,
+                files: input.files,
+            };
+            const preflight = unwrap(await api.client.POST("/admin/mesa/workspace-files", {
+                body: { ...body, dryRun: true },
+            }));
+            if (preflight.action !== "preview_workspace_files_write") {
+                throw new CliError("unexpected_response", "Mesa workspace write did not return a preview; nothing was written.");
+            }
+            const preview = {
+                action: "batch-upsert files in a student's Mesa workspace",
+                target: preflight.target,
+                request: {
+                    source: input.source,
+                    sourceSha256: input.sha256,
+                    fileCount: input.files.length,
+                    sizeBytes: input.sizeBytes,
+                    message,
+                },
+                details: {
+                    currentChangeId: preflight.currentChangeId,
+                    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.",
+                },
+            };
+            requireConfirmation(hasFlag(parsed, "confirm"), preview);
+            return unwrap(await api.client.POST("/admin/mesa/workspace-files", {
+                body: {
+                    ...body,
+                    dryRun: false,
+                    expectedChangeId: preflight.currentChangeId,
+                },
+            }));
+        }
+        throw new CliError("invalid_arguments", "Use mesa files list|read|write.");
     }
     if (noun === "request" && verb === "get") {
         return api.rawGet(positional(parsed, 2, "request path"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "recess-cli",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Safe Recess staff administration from the command line, for humans and coding agents.",
   "license": "UNLICENSED",
   "repository": {

package/skill/recess-cli/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: recess-cli
-description: Safely perform Recess staff administration through the recess CLI. Use when a Recess admin asks Codex to find a kid, parent, family, enrollment, subscription, invoice, or cohort; inspect or change a school kid's tier and capability gates; upload a kid's MAP Growth report; pause or resume billing; refund or credit an invoice item; extend a trial; cancel or restore a subscription; register or unregister a cohort against an enrollment; switch or move kids from one cohort to another; manage guide payout invoices (biweekly pay-cycle line-item changes, invoice status moves, payout recipient lookups); run class operations (take attendance, cancel or reschedule a class session, add a one-off session, end a cohort, pause cohort billing, email a cohort's families, approve or deny pending registrations); process class-cancellation credits (the "Please credit these students accordingly" Slack message — credit every registered kid for a guide-canceled session); or author learning content — build, validate, publish, and loss-safely patch a deterministic GoalTemplate, apply a template to a kid or a roster, create a goal directly on a kid, and read the Mesa workspace files behind a goal or a template snapshot.
+description: Safely perform Recess staff administration through the recess CLI. Use when a Recess admin asks Codex to find a kid, parent, family, enrollment, subscription, invoice, or cohort; inspect or change a school kid's tier and capability gates; upload a kid's MAP Growth report; pause or resume billing; refund or credit an invoice item; extend a trial; cancel or restore a subscription; register or unregister a cohort against an enrollment; switch or move kids from one cohort to another; manage guide payout invoices (biweekly pay-cycle line-item changes, invoice status moves, payout recipient lookups); run class operations (take attendance, cancel or reschedule a class session, add a one-off session, end a cohort, pause cohort billing, email a cohort's families, approve or deny pending registrations); process class-cancellation credits (the "Please credit these students accordingly" Slack message — credit every registered kid for a guide-canceled session); or author learning content — build, validate, publish, and loss-safely patch a deterministic GoalTemplate, apply a template to a kid or a roster, create a goal directly on a kid, write a Mesa draft or goal workspace, capture a template snapshot, and read Mesa workspace or snapshot files.
 # Bundle version. Bump on every substantive edit; the CLI reports it and `doctor`
 # compares it against the served copy to tell an operator a refresh is available.
-version: 1.3.0
+version: 1.4.0
 # The lowest `recess` version this bundle is safe to install onto. Raise it ONLY
 # when the bundle documents a command, flag, or changed semantic that an older
 # binary does not have — an older CLI keeps its bundled copy instead of taking
 # this one. Prose, formatting, and Gotcha edits must NOT raise it; that is the
 # whole point of serving the bundle.
-minCliVersion: 1.2.0
+minCliVersion: 1.3.0
 ---
 
 # Recess CLI (`recess`)
@@ -27,10 +27,12 @@ Every mutating command is two-step. Run it **without** `--confirm` first: the CL
 Some previews also carry a `details` object — server-resolved facts that cannot be known offline.
 Today those include `enrollments create` (real price, no-charge reuse, and capacity/slot
 violations), `users tier set` (current/proposed capability locks and class-slot consequences), and
-`goal-templates patch-spec` (validated before/after hashes and protected-inventory loss); getting one
-costs read-only calls, never a write. **When `details` is present it is part of the preview — show it
-to the human too.** Approving from `action`/`request` alone while ignoring `details` is how an
-override gets rubber-stamped.
+`goal-templates patch-spec` (validated before/after hashes and protected-inventory loss),
+`mesa files write` (resolved workspace root, Mesa change fence, and file hashes), and
+`goal-templates capture-snapshot` (validated modules/files plus template/source fences); getting
+one costs read-only calls, never a write. **When `details` is present it is part of the preview —
+show it to the human too.** Approving from `action`/`request` alone while ignoring `details` is how
+an override gets rubber-stamped.
 
 1. Show that preview to the human, verbatim.
 2. Request explicit escalated approval for that exact action using the execution tool's approval mechanism.
@@ -221,12 +223,14 @@ recess --json goal-templates patch-spec <id-or-slug> --expected-version N --patc
 recess --json goal-templates set-metadata <id-or-slug> --expected-version N [--title …] [--confirm]
 recess --json goal-templates delete <id-or-slug> --expected-version N [--confirm]
 recess --json goal-templates snapshot-files <id-or-slug> [--path P]
+recess --json goal-templates capture-snapshot <id-or-slug> (--source-goal <goal-id> | --source-draft <draft-slug> --student <kid-id>) [--dry-run] [--confirm]
 recess --json goal-templates apply <id-or-slug> --answers-file <path> [--dry-run] [--confirm]
 recess --json goal-templates apply-starter <id-or-slug> --student <kid-id> [--confirm]
 recess --json goals list --student <kid-id>
 recess --json goals create --student <kid-id> --title TEXT --description TEXT [--confirm]
 recess --json mesa files list --student <kid-id> --goal <goal-id>
 recess --json mesa files read --student <kid-id> --goal <goal-id> --path P
+recess --json mesa files write --student <kid-id> (--goal <goal-id> | --draft <draft-slug>) (--source-dir <local-dir> | --source-file <local-file> --path P) [--message TEXT] [--confirm]
 
 # Read-only escape hatch (GET only — no raw writes exist)
 recess --json request get /path?query=value
@@ -294,10 +298,12 @@ Translate as you read:
 | `manage_goal_template action:"preview_setup_workflow_spec_patch"` / `"patch_setup_workflow_spec"` | `goal-templates patch-spec <id-or-slug> --expected-version N --patches-file …` (omit `--confirm` for the required server preview; destructive changes also require its exact token) |
 | `manage_goal_template action:"update"` (metadata) | `goal-templates set-metadata <id> --expected-version N … --confirm` |
 | `manage_goal_template action:"delete"` | `goal-templates delete <id> --expected-version N --confirm` |
+| `manage_goal_template action:"capture_snapshot"` | `goal-templates capture-snapshot <id-or-slug> --source-goal <goal-id>` or `--source-draft <slug> --student <kid-id>` |
 | `create_goal` | `goals create --student <kid-id> … --confirm`, or `goal-templates apply` when a template exists |
 | `mesa_list_files` / `mesa_read_file` | `mesa files list` / `mesa files read` |
+| `mesa_write_file` (batch upserts) | `mesa files write --student … (--goal … | --draft …) (--source-dir … | --source-file … --path …)` |
 | `load_skill` / `load_skill_reference` | `skills get <name>` / `skills get <name> --reference <ref>` |
-| `restore_version`, `capture_snapshot`, `clear_snapshot`, `mesa_write_file`, `mesa_edit_file`, `mesa_manage_module` | **No CLI command.** Restoring a version, capturing/clearing a snapshot, and writing workspace files stay in `recess.gg/ai`. Say so and hand the human the web tool. |
+| `restore_version`, `clear_snapshot`, `mesa_edit_file`, `mesa_manage_module` | **No CLI command.** Version restore, snapshot clearing, string edits/deletes, and projected live-goal module/state mutations stay in `recess.gg/ai`. |
 
 #### Research tools → your own harness
 
@@ -347,10 +353,10 @@ rather than pretend:
 - **The skill treats create as one step.** Here it is two: the unconfirmed run returns the
   SERVER-resolved `details` (`resolvedSetupHandler`, `resolvedGoalShape`, `wizardStepKeys`,
   `specInventory`). Put those in the approval request — they are what the template will actually do.
-- **Prebuilt templates are half-reachable.** You can create the BLUEPRINT and read a snapshot
-  (`snapshot-files`), but `capture_snapshot` has no command, so a template only becomes Prebuilt
-  through `recess.gg/ai`. Applying a MODULE_BACKED template with no snapshot 400s — that is the
-  server refusing correctly, not a bug to route around.
+- **Prebuilt templates are a draft → validate → capture flow.** Write the complete OS-V2 tree to a
+  named Mesa draft, preview `capture-snapshot`, then confirm it. Capture rejects an incomplete
+  draft and filters student `state/`, conversations, and `.recess/` bookkeeping from the frozen
+  snapshot. Applying a MODULE_BACKED template with no snapshot still 400s correctly.
 
 #### The one-way rules
 
@@ -377,7 +383,7 @@ Each domain has a full playbook in this skill's `reference/` directory. Read the
 | Class-cancellation credits — the "Please credit these students accordingly" Slack workflow | [`reference/cancellation-credits.md`](reference/cancellation-credits.md) |
 | Non-flexible course one-off time shift when `events reschedule` 400s (`allowFlexibleScheduling: false`) | [`reference/class-ops-reschedule.md`](reference/class-ops-reschedule.md) |
 | Family onboarding — stage, account state, attestation checklist, parent intake session (fill / LLM-extract) | [`reference/onboarding.md`](reference/onboarding.md) |
-| **Authoring learning content** — deterministic GoalTemplates, applying a template to a kid or roster, creating a goal on a kid, reading Mesa workspace files | [`reference/goal-authoring.md`](reference/goal-authoring.md) |
+| **Authoring learning content** — deterministic GoalTemplates, Mesa draft/goal workspace writes, snapshot capture, applying a template to a kid or roster, creating a goal on a kid | [`reference/goal-authoring.md`](reference/goal-authoring.md) |
 
 ## Deliberately out of scope
 
@@ -387,7 +393,7 @@ These are excluded from the CLI on purpose. If asked, direct the human to the we
 - **Money movement:** initiating Mercury payouts, advancing whole pay runs, generating/regenerating payout invoices → `/admin/payout` in the web admin.
 - **Enrollment cancellation** as a standalone action (`unregister-cohort` deliberately preserves the enrollment; only `registrations deny` cancels one, because that is what the web Deny button does).
 - **Cohort creation and schedule editing:** create, start, full-edit/RRULE regeneration, generate-events, guides management → web admin cohort pages.
-- **Restoring a template version, capturing/clearing a snapshot, and writing Mesa workspace files.** Reads exist; these writes do not. Existing-spec edits are the exception: use only `goal-templates patch-spec`, never `set-metadata` or a raw request.
+- **Restoring a template version or clearing a snapshot; deleting/editing Mesa files; direct live-goal `modules/` or `state/` writes.** Use `recess.gg/ai` for these projected mutations. The CLI intentionally supports upserts only and routes structural course authoring through a draft + capture.
 
 ## Guardrails
 
@@ -472,3 +478,4 @@ Dated, newest last. Add an entry every time reality surprises you.
 - 2026-08-04 — **`--version` is a flag, not a noun.** Anything the arg parser sees starting with `--` lands in `flags`, leaving `positionals` empty — so a `noun`-based check for it sits behind the `!noun → print help` branch and is unreachable. Same trap for any future `--foo` top-level command: check the flag before the help branch. Observed live: `recess --json --version` printed the whole help text.
 - 2026-08-04 — A `Makefile install-persistent` copy is NOT the npm package: it synthesizes its own `package.json`. If that manifest lacks `version`, or `skill/` is not copied alongside `dist/`, then `--version` reports `0.0.0` and the `minCliVersion` fence **fails closed** — every served skill upgrade is silently refused with `cli_too_old`. Both are now copied; if you add another packaged artifact the CLI reads at runtime, add it to that target too.
 - 2026-08-04 — **`goal-templates patch-spec` performs a server preview even on a confirmed run.** The first POST is `dryRun:true`, never a write; it binds the current template version, before/after hashes, and protected removals. A destructive second POST is impossible without `--confirm-destructive-changes` and that fresh preview token. If the template or patch file changes, preview again and obtain new approval.
+- 2026-08-05 — **A deterministic MODULE_BACKED spec is not the course content.** `goal-templates create` can create a valid BLUEPRINT while `snapshot` remains null; Goal Preview stays empty and apply correctly says there is no valid snapshot. Build the complete tree locally, `mesa files write --draft … --source-dir …`, then `goal-templates capture-snapshot --source-draft … --student …`. Both writes server-preview first. Mesa writes are fenced to the previewed repo change; capture is fenced to that source change and the template version. Direct live-goal `modules/`/`state/` writes are deliberately blocked because those paths have DB projections.

package/skill/recess-cli/reference/goal-authoring.md

@@ -66,8 +66,8 @@ the human directly, in the skill's language, and wait. Do not say "materialize",
 "module-backed", or "snapshot" to a tutor.
 
 A MODULE_BACKED spec **requires** `BLUEPRINT`; the server enforces it, and it additionally refuses to
-apply a MODULE_BACKED template that has no snapshot. Capturing a snapshot has no CLI command — that
-step is `recess.gg/ai` only.
+apply a MODULE_BACKED template that has no snapshot. Build a complete Mesa draft and capture it with
+the CLI workflow in §8 before applying the template.
 
 ## 2. Write one template file
 
@@ -194,7 +194,41 @@ the human which goal to retire.
 Load `goal-creation` (and `student-research` to read the kid first) before writing the description.
 An unresearched goal is the failure mode this whole surface exists to prevent.
 
-## 8. Read the workspaces
+## 8. Author, capture, and read workspaces
+
+For a new Prebuilt/instant-apply course, author the complete OS-V2 tree locally and upsert it into a
+named draft. The directory root becomes `drafts/<slug>/workspace` in the student's Mesa repo:
+
+```bash
+recess --json mesa files write --student <kid-id> --draft <draft-slug> --source-dir ./workspace
+# show the preview, obtain approval, then rerun unchanged:
+recess --json mesa files write --student <kid-id> --draft <draft-slug> --source-dir ./workspace --confirm
+
+recess --json goal-templates capture-snapshot <id-or-slug> --source-draft <draft-slug> --student <kid-id> --dry-run
+recess --json goal-templates capture-snapshot <id-or-slug> --source-draft <draft-slug> --student <kid-id>
+# show the preview, obtain approval, then rerun unchanged:
+recess --json goal-templates capture-snapshot <id-or-slug> --source-draft <draft-slug> --student <kid-id> --confirm
+```
+
+The draft must pass the full goal-builder contract: required top-level instructions, required fresh
+`state/` files, directory content, and at least one parseable runtime module. Capture validates that
+tree, then excludes `state/`, `conversations/`, and `.recess/` from the reusable snapshot. Its
+preview carries the template version, Mesa change id, module/file inventory, size, and SHA-256; the
+confirmed request is compare-and-set against both fences. If either changed, preview again and get
+fresh approval.
+
+Use `--source-file <local-file> --path <workspace-relative-path>` for one-file upserts. A live goal
+may be targeted with `--goal <goal-id>`, but the CLI rejects direct `modules/` and `state/` writes
+because those paths have database projections. Structural course changes belong in a draft, then a
+captured/applied template.
+
+An already-built OS-V2 goal can be captured directly:
+
+```bash
+recess --json goal-templates capture-snapshot <id-or-slug> --source-goal <goal-id> --dry-run
+```
+
+Read the resulting workspaces and snapshot with:
 
 ```bash
 recess --json mesa files list --student <kid-id> --goal <goal-id>
@@ -203,9 +237,6 @@ recess --json goal-templates snapshot-files <id-or-slug>
 recess --json goal-templates snapshot-files <id-or-slug> --path modules/01/index.md
 ```
 
-Reads only — there is no `mesa files write`. Writing workspace files stays in `recess.gg/ai`, which
-validates a workspace before it lands in a live kid's session.
-
 `mesa files list` returning `{"files":[]}` means the goal has no Mesa workspace at all — expected for
 a SIMPLE goal, and the signal that a BLUEPRINT goal has not been built yet.