recess-cli 1.3.3 → 1.6.0

package/dist/cli.js

@@ -1,4 +1,4 @@
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { RecessAdminApi, unwrap } from "./api.js";
@@ -10,7 +10,7 @@ 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 from the command line
+export const HELP = `recess — safe Recess administration and family AI tools
 
 Usage:
   recess [--json] --version
@@ -28,8 +28,18 @@ Usage:
     [--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>
@@ -120,8 +130,12 @@ Usage:
   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] skills list [--query TEXT] [--category TEXT]
-  recess [--json] skills get <skill-name> [--reference NAME | --all-references]
+  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]
@@ -142,19 +156,34 @@ Usage:
     (--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]
+    [--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] [--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>
+  recess [--json] goals edit <goal-id> --student <kid-id> --patch-file <path/patch.json>
+    --delta TEXT [--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] 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 <kid-id> --goal <goal-id>
+  recess [--json] goals files read --student <kid-id> --goal <goal-id> --path P
+  recess [--json] goals files write --student <kid-id>
     (--goal <goal-id> | --draft <draft-slug>)
     (--source-dir <local-dir> | --source-file <local-file> --path P)
-    [--message TEXT] [--confirm]
+    [--message TEXT] [--confirm --approval-token TOKEN]
+  recess [--json] goals pdf upload --student <kid-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 submodule) read-only over your admin session — they are never
@@ -194,8 +223,9 @@ Payout notes: amounts are integer cents. "payout items add" without --date
 defaults the item date to the penultimate day of the invoice's cycle (its
 endDate minus one day) and shows the computed date in the preview.
 
-Auth notes: "auth login" runs the browser loopback flow (local use). For a headless
-cloud agent, "auth request" prints an approval URL to hand a Recess admin; after they
+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.
 
@@ -232,7 +262,7 @@ async function sessionStatus(config) {
             authSource: config.authSource,
             status: result.response.status,
             expiresAt: config.sessionExpiresAt ?? null,
-            message: "The stored admin session is invalid or expired. Run `recess auth login`.",
+            message: "The stored Recess CLI session is invalid, expired, or revoked. Run `recess auth login`.",
         };
     }
     return { ...result.data, authSource: config.authSource };
@@ -276,7 +306,7 @@ async function skillStatus(config) {
         return { ...base, checked: false, reason: "no session" };
     }
     try {
-        const response = await fetch(new URL("/admin/cli-skill/", config.apiOrigin), {
+        const response = await fetch(new URL("/auth/admin-cli/skill/", config.apiOrigin), {
             headers: { cookie: config.sessionCookie },
             signal: AbortSignal.timeout(5000),
         });
@@ -315,9 +345,114 @@ 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 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;
+function approvalTokenFor(preview) {
+    return createHash("sha256").update(JSON.stringify(preview)).digest("hex");
+}
+function requirePreviewBoundConfirmation(parsed, preview) {
+    const approvalToken = approvalTokenFor(preview);
+    const boundPreview = {
+        ...preview,
+        details: { ...preview.details, approvalToken },
+    };
+    if (!hasFlag(parsed, "confirm")) {
+        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" });
+    }
+}
+async function cleanupPlannerUpload(api, conversationId, signed, includeDelete) {
+    if (signed.kind === "multipart") {
+        await api.client
+            .POST("/os-v2-mesa/planner/uploads/cleanup", {
+            body: {
+                action: "abort",
+                conversationId,
+                key: signed.key,
+                uploadId: signed.uploadId,
+            },
+        })
+            .catch(() => undefined);
+    }
+    if (includeDelete) {
+        await api.client
+            .POST("/os-v2-mesa/planner/uploads/cleanup", {
+            body: { action: "delete", conversationId, key: signed.key },
+        })
+            .catch(() => undefined);
+    }
+}
+function safeGoalUploadName(fileName) {
+    return fileName.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+async function sha256File(absolutePath) {
+    const handle = await fs.open(absolutePath, "r");
+    const hash = createHash("sha256");
+    const buffer = Buffer.allocUnsafe(4 * 1024 * 1024);
+    try {
+        let position = 0;
+        while (true) {
+            const { bytesRead } = await handle.read(buffer, 0, buffer.byteLength, position);
+            if (bytesRead === 0)
+                break;
+            hash.update(buffer.subarray(0, bytesRead));
+            position += bytesRead;
+        }
+    }
+    finally {
+        await handle.close();
+    }
+    return hash.digest("hex");
+}
+function uploadBody(bytes) {
+    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+}
+async function putSignedPart(uploadUrl, bytes, contentType) {
+    const response = await fetch(uploadUrl, {
+        method: "PUT",
+        headers: contentType ? { "content-type": contentType } : undefined,
+        body: uploadBody(bytes),
+    });
+    if (!response.ok) {
+        throw new CliError("upload_failed", `Textbook upload failed with HTTP ${response.status}. The goal workspace was not changed.`);
+    }
+}
+async function uploadPdfToSignedUrls(absolutePath, contentType, signed) {
+    if (signed.kind === "single") {
+        const bytes = await fs.readFile(absolutePath);
+        await putSignedPart(signed.uploadUrl, bytes, contentType);
+        return {
+            sha256: createHash("sha256").update(bytes).digest("hex"),
+            sizeBytes: bytes.byteLength,
+        };
+    }
+    const handle = await fs.open(absolutePath, "r");
+    const hash = createHash("sha256");
+    let sizeBytes = 0;
+    try {
+        for (const part of signed.parts) {
+            const position = (part.partNumber - 1) * signed.chunkSize;
+            const buffer = Buffer.allocUnsafe(signed.chunkSize);
+            const { bytesRead } = await handle.read(buffer, 0, signed.chunkSize, position);
+            if (bytesRead === 0) {
+                throw new CliError("upload_failed", `Textbook upload part ${part.partNumber} had no bytes. The goal workspace was not changed.`);
+            }
+            const bytes = buffer.subarray(0, bytesRead);
+            hash.update(bytes);
+            sizeBytes += bytesRead;
+            await putSignedPart(part.uploadUrl, bytes);
+        }
+    }
+    finally {
+        await handle.close();
+    }
+    return { sha256: hash.digest("hex"), sizeBytes };
+}
+async function readGoalWorkspaceWriteSource(parsed) {
     const sourceDirectory = flagString(parsed, "source-dir");
     const sourceFile = flagString(parsed, "source-file");
     if (Boolean(sourceDirectory) === Boolean(sourceFile)) {
@@ -328,12 +463,12 @@ async function readMesaWriteSource(parsed) {
     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.`);
+        if (files.length >= GOAL_WORKSPACE_WRITE_MAX_FILES) {
+            throw new CliError("invalid_arguments", `Goal workspace writes are limited to ${GOAL_WORKSPACE_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.`);
+        if (sizeBytes + fileStat.size > GOAL_WORKSPACE_WRITE_MAX_TOTAL_BYTES) {
+            throw new CliError("invalid_arguments", `Goal workspace writes are limited to ${GOAL_WORKSPACE_WRITE_MAX_TOTAL_BYTES} decoded bytes.`);
         }
         const bytes = await fs.readFile(absolutePath);
         sizeBytes += bytes.byteLength;
@@ -382,7 +517,7 @@ async function readMesaWriteSource(parsed) {
         await addFile(absolutePath, workspacePath);
     }
     if (files.length === 0) {
-        throw new CliError("invalid_arguments", "The Mesa write source contains no files.");
+        throw new CliError("invalid_arguments", "The goal workspace source contains no files.");
     }
     for (const file of files) {
         hash.update(file.path);
@@ -598,7 +733,7 @@ function parseGoalTemplateDocument(doc) {
     }
     const spec = doc.setupWorkflowSpec;
     if (spec === null || typeof spec !== "object" || Array.isArray(spec)) {
-        throw new CliError("invalid_arguments", 'Template file requires an object "setupWorkflowSpec" (the fixed wizard). Author it with the os-v2-goal-template-builder skill: `recess --json skills get os-v2-goal-template-builder --all-references`.');
+        throw new CliError("invalid_arguments", 'Template file requires an object "setupWorkflowSpec" (the fixed wizard). Load the guardian authoring guide first: `recess --json skills guardian get recess-goal-authoring --all-references`.');
     }
     const rawTags = doc.tags;
     let tags = [];
@@ -676,8 +811,8 @@ function parseGoalTemplateDocument(doc) {
 async function resolveGoalTemplateId(api, reference) {
     if (UUID_RE.test(reference))
         return reference;
-    const list = unwrap(await api.client.GET("/admin/goal-templates/", {
-        params: { query: { includeDeleted: "true" } },
+    const list = unwrap(await api.client.GET("/ai/goal-templates/", {
+        params: { query: { includeDeleted: "false" } },
     }));
     const match = list.items.find((item) => item.slug === reference);
     if (!match) {
@@ -1274,6 +1409,96 @@ export async function runCommand(argv) {
             params: { path: { userId } },
         }));
     }
+    if (noun === "guides" && verb === "create") {
+        const email = flagString(parsed, "email", { required: true })
+            .trim()
+            .toLowerCase();
+        if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+            throw new CliError("invalid_arguments", "--email does not look like a valid email address.");
+        }
+        const firstName = flagString(parsed, "first-name", { required: true });
+        const lastName = flagString(parsed, "last-name");
+        const sendInvite = !hasFlag(parsed, "no-invite");
+        const body = {
+            email,
+            firstName,
+            ...(lastName !== undefined ? { lastName } : {}),
+            sendInvite,
+        };
+        return writeCommand(parsed, {
+            action: sendInvite
+                ? "provision a GUIDE staff account and email its sign-in invite (outward email)"
+                : "provision a GUIDE staff account without sending the invite email",
+            target: { email },
+            request: body,
+        }, async () => unwrap(await api.client.POST("/admin/guides/", { body })));
+    }
+    if (noun === "guardians" && verb === "invite") {
+        const familyId = flagString(parsed, "family", { required: true });
+        const email = flagString(parsed, "email", { required: true })
+            .trim()
+            .toLowerCase();
+        if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+            throw new CliError("invalid_arguments", "--email does not look like a valid email address.");
+        }
+        const firstName = flagString(parsed, "first-name", { required: true });
+        const lastName = flagString(parsed, "last-name");
+        const sendInvite = !hasFlag(parsed, "no-invite");
+        // Read-only preflight: the approval preview must name the exact family
+        // this guardian is being granted over — a wrong family id hands a
+        // stranger full guardian access to someone's kids.
+        const family = unwrap(await api.client.GET("/admin/onboarding/families/{familyId}/status", {
+            params: { path: { familyId } },
+        }));
+        const body = {
+            email,
+            firstName,
+            ...(lastName !== undefined ? { lastName } : {}),
+            sendInvite,
+        };
+        return writeCommand(parsed, {
+            action: sendInvite
+                ? "invite a new GUARDIAN into an existing family and email the sign-in invite (outward email)"
+                : "add a new GUARDIAN to an existing family without sending the invite email",
+            target: { familyId, email },
+            request: body,
+            details: {
+                familyName: family.familyName,
+                kids: family.kids.map((kid) => kid.firstName),
+            },
+        }, async () => unwrap(await api.client.POST("/admin/users/family/{familyId}/guardians/", {
+            params: { path: { familyId } },
+            body,
+        })));
+    }
+    if (noun === "guides" && verb === "invite") {
+        const userId = flagString(parsed, "user", { required: true });
+        // Read-only preflight: the approval preview must name the exact person
+        // about to receive an outward email, and refuse a non-guide before the
+        // gate rather than after approval (the backend enforces the same rule).
+        const { user } = unwrap(await api.client.GET("/admin/users/{userId}", {
+            params: { path: { userId } },
+        }));
+        if (user.role !== "GUIDE") {
+            throw new CliError("invalid_arguments", `User ${userId} has role ${user.role}; only GUIDE accounts can be invited. Use guides create for a new guide.`);
+        }
+        if (!user.email) {
+            throw new CliError("invalid_arguments", `Guide ${userId} has no email address on file, so no invite can be sent.`);
+        }
+        return writeCommand(parsed, {
+            action: "send the guide sign-in invite email (outward email)",
+            target: { userId },
+            request: {},
+            details: {
+                to: user.email,
+                firstName: user.firstName,
+                lastName: user.lastName,
+                role: user.role,
+            },
+        }, async () => unwrap(await api.client.POST("/admin/guides/{userId}/invite/", {
+            params: { path: { userId } },
+        })));
+    }
     if (noun === "students" && verb === "upload-map-scores") {
         const studentId = flagString(parsed, "student", { required: true });
         const pdf = await readMapScorePdf(flagString(parsed, "file", { required: true }));
@@ -2146,21 +2371,23 @@ export async function runCommand(argv) {
         throw new CliError("invalid_arguments", "Use onboarding status|kids|intake-session|intake-session-create|set-stage|set-account-state|attest|set-intake|extract.");
     }
     if (noun === "skills") {
-        // Reads only — no gate. The value of this noun is that CLI agents author
-        // against the SAME documents the in-product tutor loads; nothing is copied
-        // into this package, so a skills-repo change reaches agents with no release.
+        // Reads only — no confirmation gate. Audience is explicit so an agent never
+        // infers whether `get` means guardian guidance or staff-only operations.
+        const audience = assertChoice(verb, ["admin", "guardian"], "skill audience");
+        const action = positional(parsed, 2, "skills action");
         const refresh = hasFlag(parsed, "refresh");
-        if (verb === "list") {
+        if (action === "list") {
             const query = flagString(parsed, "query");
             const category = flagString(parsed, "category");
-            const cacheKey = `list:${query ?? ""}:${category ?? ""}`;
+            const cacheKey = `${audience}:list:${query ?? ""}:${category ?? ""}`;
             if (!refresh) {
                 const cached = await readSkillCache(config.apiOrigin, cacheKey);
                 if (cached)
                     return { ...cached, cached: true };
             }
-            const data = unwrap(await api.client.GET("/admin/skills/", {
+            const data = unwrap(await api.client.GET("/auth/admin-cli/skills/{audience}", {
                 params: {
+                    path: { audience },
                     query: {
                         ...(query ? { query } : {}),
                         ...(category ? { category } : {}),
@@ -2170,22 +2397,22 @@ export async function runCommand(argv) {
             await writeSkillCache(config.apiOrigin, cacheKey, data);
             return { ...data, cached: false };
         }
-        if (verb === "get") {
-            const name = positional(parsed, 2, "skill name");
+        if (action === "get") {
+            const name = positional(parsed, 3, "skill name");
             const reference = flagString(parsed, "reference");
             const allReferences = hasFlag(parsed, "all-references");
             if (reference && allReferences) {
                 throw new CliError("invalid_arguments", "Pass --reference <name> for one reference or --all-references for the whole tree, not both.");
             }
-            const cacheKey = `get:${name}:${reference ?? ""}:${allReferences}`;
+            const cacheKey = `${audience}:get:${name}:${reference ?? ""}:${allReferences}`;
             if (!refresh) {
                 const cached = await readSkillCache(config.apiOrigin, cacheKey);
                 if (cached)
                     return { ...cached, cached: true };
             }
-            const data = unwrap(await api.client.GET("/admin/skills/{name}", {
+            const data = unwrap(await api.client.GET("/auth/admin-cli/skills/{audience}/{name}", {
                 params: {
-                    path: { name },
+                    path: { audience, name },
                     query: {
                         ...(reference ? { reference } : {}),
                         ...(allReferences ? { references: "all" } : {}),
@@ -2195,7 +2422,7 @@ export async function runCommand(argv) {
             await writeSkillCache(config.apiOrigin, cacheKey, data);
             return { ...data, cached: false };
         }
-        throw new CliError("invalid_arguments", "Use skills list|get.");
+        throw new CliError("invalid_arguments", "Use skills guardian list|get or skills admin list|get.");
     }
     if (noun === "content-library") {
         if (verb === "search") {
@@ -2204,7 +2431,7 @@ export async function runCommand(argv) {
             if (!Number.isInteger(limit) || limit < 1 || limit > 40) {
                 throw new CliError("invalid_arguments", "--limit must be an integer between 1 and 40.");
             }
-            return unwrap(await api.client.GET("/admin/content-library/search", {
+            return unwrap(await api.client.GET("/ai/content-library/search", {
                 params: { query: { q: query, limit } },
             }));
         }
@@ -2214,7 +2441,7 @@ export async function runCommand(argv) {
         if (verb === "list") {
             const query = flagString(parsed, "query")?.toLowerCase();
             const kind = flagString(parsed, "kind");
-            const data = unwrap(await api.client.GET("/admin/goal-templates/", {
+            const data = unwrap(await api.client.GET("/ai/goal-templates/", {
                 params: {
                     query: {
                         ...(flagString(parsed, "category")
@@ -2249,7 +2476,7 @@ export async function runCommand(argv) {
         }
         if (verb === "get") {
             const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
-            const template = unwrap(await api.client.GET("/admin/goal-templates/{id}", {
+            const template = unwrap(await api.client.GET("/ai/goal-templates/{id}", {
                 params: { path: { id } },
             }));
             // A full spec is large; `--spec-only` is what an agent pipes into a file
@@ -2266,7 +2493,7 @@ export async function runCommand(argv) {
         }
         if (verb === "versions") {
             const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
-            const data = unwrap(await api.client.GET("/admin/goal-templates/{id}/versions", {
+            const data = unwrap(await api.client.GET("/ai/goal-templates/{id}/versions", {
                 params: { path: { id } },
             }));
             const wanted = flagNumber(parsed, "version");
@@ -2293,7 +2520,7 @@ export async function runCommand(argv) {
             return {
                 slug: document.slug,
                 kind: document.kind,
-                ...unwrap(await api.client.POST("/admin/goal-templates/validate-spec", {
+                ...unwrap(await api.client.POST("/ai/goal-templates/validate-spec", {
                     body: {
                         setupWorkflowSpec: document.setupWorkflowSpec,
                         kind: document.kind,
@@ -2310,7 +2537,7 @@ export async function runCommand(argv) {
             // answer keys `apply` will demand all come out of the spec's own
             // validation — a locally guessed preview could name a different handler
             // than the one that lands. Validation writes nothing.
-            const validation = unwrap(await api.client.POST("/admin/goal-templates/validate-spec", {
+            const validation = unwrap(await api.client.POST("/ai/goal-templates/validate-spec", {
                 body: {
                     setupWorkflowSpec: document.setupWorkflowSpec,
                     kind: document.kind,
@@ -2338,7 +2565,7 @@ export async function runCommand(argv) {
                     specInventory: validation.totals,
                     note: "Setup mode is DETERMINISTIC_WORKFLOW and is one-way: this template can never be converted back to a chat-driven setup.",
                 },
-            }, async () => unwrap(await api.client.POST("/admin/goal-templates/", {
+            }, async () => unwrap(await api.client.POST("/ai/goal-templates/", {
                 body: document,
             })));
         }
@@ -2508,11 +2735,11 @@ export async function runCommand(argv) {
             const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
             const filePath = flagString(parsed, "path");
             if (filePath) {
-                return unwrap(await api.client.GET("/admin/goal-templates/{id}/snapshot/file", {
+                return unwrap(await api.client.GET("/ai/goal-templates/{id}/snapshot/file", {
                     params: { path: { id }, query: { path: filePath } },
                 }));
             }
-            return unwrap(await api.client.GET("/admin/goal-templates/{id}/snapshot/files", {
+            return unwrap(await api.client.GET("/ai/goal-templates/{id}/snapshot/files", {
                 params: { path: { id } },
             }));
         }
@@ -2532,7 +2759,7 @@ export async function runCommand(argv) {
                     sourceWorkspacePath: `drafts/${sourceDraft}/workspace`,
                     sourceStudentUserId,
                 };
-            const preflight = unwrap(await api.client.POST("/admin/goal-templates/{id}/snapshot/capture", {
+            const preflight = unwrap(await api.client.POST("/ai/goal-templates/{id}/snapshot/capture", {
                 params: { path: { id } },
                 body: { ...source, dryRun: true },
             }));
@@ -2542,7 +2769,7 @@ export async function runCommand(argv) {
             if (hasFlag(parsed, "dry-run"))
                 return preflight;
             const preview = {
-                action: "capture a validated Mesa workspace as this global template's instant-apply snapshot",
+                action: "capture a validated goal workspace as this global template's instant-apply snapshot",
                 target: {
                     templateId: preflight.template.id,
                     slug: preflight.template.slug,
@@ -2560,11 +2787,11 @@ export async function runCommand(argv) {
                     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.",
+                    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("/admin/goal-templates/{id}/snapshot/capture", {
+            return unwrap(await api.client.POST("/ai/goal-templates/{id}/snapshot/capture", {
                 params: { path: { id } },
                 body: {
                     ...source,
@@ -2597,7 +2824,7 @@ export async function runCommand(argv) {
                 ...totals,
                 [result.action]: (totals[result.action] ?? 0) + 1,
             }), {});
-            return writeCommand(parsed, {
+            const preview = {
                 action: "apply a goal template to students (creates goals and todos)",
                 target: { templateId: id, students: preflight.results.length },
                 request: { answers },
@@ -2612,12 +2839,19 @@ export async function runCommand(argv) {
                         warnings: result.warnings,
                     })),
                     missingCoverage: preflight.missingCoverage,
+                    templateVersion: preflight.templateVersion,
                     note: "Counts come from the backend's own dry run. `skipped_existing` items are idempotent — re-applying does not duplicate them.",
                 },
-            }, async () => unwrap(await api.client.POST("/ai/goal-templates/{id}/apply-workflow", {
+            };
+            requirePreviewBoundConfirmation(parsed, preview);
+            return unwrap(await api.client.POST("/ai/goal-templates/{id}/apply-workflow", {
                 params: { path: { id } },
-                body: { answers, dryRun: false },
-            })));
+                body: {
+                    answers,
+                    dryRun: false,
+                    expectedTemplateVersion: preflight.templateVersion,
+                },
+            }));
         }
         if (verb === "apply-starter") {
             const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
@@ -2643,10 +2877,10 @@ export async function runCommand(argv) {
         }
         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 (noun === "goals" && verb !== "files" && verb !== "pdf") {
         if (verb === "list") {
             const userId = flagString(parsed, "student", { required: true });
-            return unwrap(await api.client.GET("/admin/browser/students/{userId}/goals/", {
+            return unwrap(await api.client.GET("/tutor/browser/students/{userId}/goals/", {
                 params: { path: { userId } },
             }));
         }
@@ -2683,17 +2917,351 @@ export async function runCommand(argv) {
                     schedule: schedule ?? null,
                 },
                 details: {
-                    note: "Creates a description-only goal with no GoalModules and no Mesa workspace. For a module-backed course, apply a BLUEPRINT template instead. 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. For a module-backed course, apply a BLUEPRINT template instead. A 409 GOAL_LIMIT_REACHED means the kid is at capacity and nothing was created.",
                 },
-            }, async () => unwrap(await api.client.POST("/admin/browser/students/{userId}/goals/", {
+            }, async () => unwrap(await api.client.POST("/tutor/browser/students/{userId}/goals/", {
                 params: { path: { userId } },
                 body,
             })));
         }
-        throw new CliError("invalid_arguments", "Use goals list|create.");
+        if (verb === "edit") {
+            const goalId = positional(parsed, 2, "goal ID");
+            const studentId = flagString(parsed, "student", { required: true });
+            const patchFile = flagString(parsed, "patch-file", { required: true });
+            const patch = (await readJsonFile(patchFile, "Goal patch file"));
+            patch.delta = flagString(parsed, "delta", { 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}.`);
+            }
+            patch.expectedUpdatedAt = current.updatedAt;
+            const preview = {
+                action: "edit a goal for a managed student",
+                target: { goalId, studentUserId: studentId },
+                request: {
+                    patchFile: path.resolve(patchFile),
+                    expectedUpdatedAt: current.updatedAt,
+                    patch,
+                },
+            };
+            requirePreviewBoundConfirmation(parsed, preview);
+            return unwrap(await api.client.PATCH("/tutor/browser/students/goals/{goalId}/", {
+                params: { path: { goalId } },
+                body: patch,
+            }));
+        }
+        throw new CliError("invalid_arguments", "Use goals list|create|edit|files|pdf.");
+    }
+    if (noun === "students") {
+        if (verb === "list") {
+            return unwrap(await api.client.GET("/family/kids", {
+                params: { query: { includeSelf: "false" } },
+            }));
+        }
+        if (verb === "today") {
+            const kidId = flagString(parsed, "student", { required: true });
+            const date = flagString(parsed, "date");
+            return unwrap(await api.client.GET("/parent/kid/{kidId}/today/", {
+                params: { path: { kidId }, query: date ? { date } : {} },
+            }));
+        }
+        if (verb === "schedule") {
+            const studentId = flagString(parsed, "student", { required: true });
+            const days = flagNumber(parsed, "days");
+            if (days !== undefined &&
+                (!Number.isInteger(days) || days < 1 || days > 60)) {
+                throw new CliError("invalid_arguments", "--days must be an integer from 1 to 60.");
+            }
+            return unwrap(await api.client.GET("/tutor/students/{studentId}/schedule", {
+                params: {
+                    path: { studentId },
+                    query: days === undefined ? {} : { days },
+                },
+            }));
+        }
+        if (verb === "xp-history") {
+            const kidId = flagString(parsed, "student", { required: true });
+            const range = flagString(parsed, "range");
+            const parsedRange = range
+                ? assertChoice(range, ["week", "month", "quarter", "year"], "--range")
+                : undefined;
+            return unwrap(await api.client.GET("/parent/kid/{kidId}/xp-history/", {
+                params: {
+                    path: { kidId },
+                    query: parsedRange ? { range: parsedRange } : {},
+                },
+            }));
+        }
+        throw new CliError("invalid_arguments", "Use students list|today|schedule|xp-history|upload-map-scores.");
+    }
+    if (noun === "todos") {
+        if (verb === "create") {
+            const studentId = flagString(parsed, "student", { required: true });
+            const title = flagString(parsed, "title", { required: true });
+            const estimatedTimeInMins = flagNumber(parsed, "estimated-minutes");
+            const body = {
+                userId: studentId,
+                title,
+                ...(flagString(parsed, "due-date")
+                    ? { dueDate: flagString(parsed, "due-date") }
+                    : {}),
+                ...(flagString(parsed, "url")
+                    ? { url: flagString(parsed, "url") }
+                    : {}),
+                ...(estimatedTimeInMins !== undefined ? { estimatedTimeInMins } : {}),
+            };
+            return writeCommand(parsed, {
+                action: "create a todo for a managed student",
+                target: { studentUserId: studentId },
+                request: body,
+            }, async () => unwrap(await api.client.POST("/tutor/browser/todos/", { body })));
+        }
+        if (verb === "edit") {
+            const todoId = positional(parsed, 2, "todo ID");
+            const patchFile = flagString(parsed, "patch-file", { required: true });
+            const body = (await readJsonFile(patchFile, "Todo patch file"));
+            const current = unwrap(await api.client.GET("/tutor/browser/todos/{id}/", {
+                params: { path: { id: todoId } },
+            }));
+            body.expectedUpdatedAt = current.updatedAt;
+            const preview = {
+                action: "edit a todo for a managed student",
+                target: { todoId },
+                request: {
+                    patchFile: path.resolve(patchFile),
+                    expectedUpdatedAt: current.updatedAt,
+                    patch: body,
+                },
+            };
+            requirePreviewBoundConfirmation(parsed, preview);
+            return unwrap(await api.client.PATCH("/tutor/browser/todos/{id}", {
+                params: { path: { id: todoId } },
+                body,
+            }));
+        }
+        throw new CliError("invalid_arguments", "Use todos create|edit.");
+    }
+    if (noun === "memories") {
+        const studentId = flagString(parsed, "student", { required: true });
+        if (verb === "context") {
+            return unwrap(await api.client.GET("/tutor/students/{studentId}/prompt-memory", {
+                params: { path: { studentId } },
+            }));
+        }
+        if (verb === "log") {
+            const date = flagString(parsed, "date", { required: true });
+            return unwrap(await api.client.GET("/tutor/students/{studentId}/prompt-memory/log", {
+                params: { path: { studentId }, query: { date } },
+            }));
+        }
+        throw new CliError("invalid_arguments", "Use memories context|log.");
+    }
+    if (noun === "rocky") {
+        const studentId = flagString(parsed, "student", { required: true });
+        if (verb === "get") {
+            return unwrap(await api.client.GET("/tutor/students/{studentId}/rocky-config", {
+                params: { path: { studentId } },
+            }));
+        }
+        if (verb === "set") {
+            const patchFile = flagString(parsed, "patch-file", { required: true });
+            const patch = (await readJsonFile(patchFile, "Rocky config patch file"));
+            const expected = flagString(parsed, "expected-updated-at", {
+                required: true,
+            });
+            const expectedUpdatedAt = expected === "none" ? null : expected;
+            if (expectedUpdatedAt !== null &&
+                Number.isNaN(Date.parse(expectedUpdatedAt))) {
+                throw new CliError("invalid_arguments", "--expected-updated-at must be an ISO datetime from `rocky get`, or `none`.");
+            }
+            return writeCommand(parsed, {
+                action: "change Rocky's configuration for a managed student",
+                target: { studentUserId: studentId },
+                request: {
+                    patchFile: path.resolve(patchFile),
+                    expectedUpdatedAt,
+                    patch,
+                },
+            }, async () => unwrap(await api.client.PATCH("/tutor/students/{studentId}/rocky-config", {
+                params: { path: { studentId } },
+                body: { expectedUpdatedAt, patch },
+            })));
+        }
+        throw new CliError("invalid_arguments", "Use rocky get|set.");
+    }
+    if (noun === "goals" && verb === "pdf") {
+        const action = positional(parsed, 2, "goals pdf action");
+        if (action !== "upload") {
+            throw new CliError("invalid_arguments", "Use goals pdf upload.");
+        }
+        const studentId = flagString(parsed, "student", { required: true });
+        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 goals pdf upload.");
+        }
+        const sourceFile = flagString(parsed, "source-file", { required: true });
+        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}`);
+        }
+        if (!absolutePath.toLowerCase().endsWith(".pdf")) {
+            throw new CliError("invalid_arguments", "goals pdf upload accepts PDF files only.");
+        }
+        if (fileStat.size <= 0 || fileStat.size > GOAL_PDF_UPLOAD_MAX_BYTES) {
+            throw new CliError("invalid_arguments", `PDF size must be between 1 byte and ${GOAL_PDF_UPLOAD_MAX_BYTES} bytes.`);
+        }
+        const fileName = path.basename(absolutePath);
+        const workspacePath = flagString(parsed, "path") ?? `uploads/${safeGoalUploadName(fileName)}`;
+        if (!workspacePath.startsWith("uploads/")) {
+            throw new CliError("invalid_arguments", "Textbook PDFs must be attached under uploads/.");
+        }
+        const sourceSha256 = await sha256File(absolutePath);
+        const target = goalId
+            ? { kind: "goal", goalId }
+            : { kind: "draft", draftSlug: draftSlug };
+        const message = flagString(parsed, "message") ??
+            `recess-cli: attach textbook PDF ${fileName}`;
+        const placeholderManifest = JSON.stringify({
+            kind: "pending-pdf-upload",
+            fileName,
+            contentType: "application/pdf",
+            sizeBytes: fileStat.size,
+        });
+        const body = {
+            studentUserId: studentId,
+            target,
+            message,
+            files: [
+                {
+                    path: workspacePath,
+                    content: placeholderManifest,
+                    contentEncoding: "utf8",
+                },
+            ],
+        };
+        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 PDF upload did not return a preview; nothing was uploaded.");
+        }
+        requirePreviewBoundConfirmation(parsed, {
+            action: "upload a textbook PDF and attach it to a student's goal",
+            target: preflight.target,
+            request: {
+                sourceFile: absolutePath,
+                sourceSha256,
+                sizeBytes: fileStat.size,
+                workspacePath,
+                message,
+            },
+            details: {
+                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", {
+                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 === "mesa" && verb === "files") {
-        const action = positional(parsed, 2, "mesa files action");
+    if (noun === "goals" && verb === "files") {
+        const action = positional(parsed, 2, "goals files action");
         const studentId = flagString(parsed, "student", { required: true });
         if (action === "list") {
             const goalId = flagString(parsed, "goal", { required: true });
@@ -2712,9 +3280,9 @@ export async function runCommand(argv) {
             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.");
+                throw new CliError("invalid_arguments", "Pass exactly one of --goal or --draft for goals files write.");
             }
-            const input = await readMesaWriteSource(parsed);
+            const input = await readGoalWorkspaceWriteSource(parsed);
             const target = goalId
                 ? { kind: "goal", goalId }
                 : { kind: "draft", draftSlug: draftSlug };
@@ -2726,14 +3294,14 @@ export async function runCommand(argv) {
                 message,
                 files: input.files,
             };
-            const preflight = unwrap(await api.client.POST("/admin/mesa/workspace-files", {
+            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", "Mesa workspace write did not return a preview; nothing was written.");
+                throw new CliError("unexpected_response", "Goal workspace write did not return a preview; nothing was written.");
             }
             const preview = {
-                action: "batch-upsert files in a student's Mesa workspace",
+                action: "batch-upsert files in a student's goal workspace",
                 target: preflight.target,
                 request: {
                     source: input.source,
@@ -2750,8 +3318,8 @@ export async function runCommand(argv) {
                         : "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", {
+            requirePreviewBoundConfirmation(parsed, preview);
+            return unwrap(await api.client.POST("/tutor/browser/mesa/workspace-files", {
                 body: {
                     ...body,
                     dryRun: false,
@@ -2759,7 +3327,7 @@ export async function runCommand(argv) {
                 },
             }));
         }
-        throw new CliError("invalid_arguments", "Use mesa files list|read|write.");
+        throw new CliError("invalid_arguments", "Use goals files list|read|write.");
     }
     if (noun === "request" && verb === "get") {
         return api.rawGet(positional(parsed, 2, "request path"));