recess-cli 2.10.0 → 3.1.0

package/README.md

@@ -9,6 +9,13 @@ authenticated Village home building. It uses the web-server OpenAPI document, au
 through Recess SSO, emits stable JSON, and refuses live writes until the exact command is rerun with
 `--confirm` plus the preview's operation key after human approval.
 
+## Version 3 changes
+
+`goals list` now shows ACTIVE and PAUSED goals by default. Add `--include-archived` to
+include COMPLETED goals (both archived and rewarded completions), and `--query` to search.
+Staff gain `cohorts schedule` and versioned `memories` file commands. Deploy their backend
+and database support before publishing this CLI; writes require a server preview.
+
 ## Install (no checkout needed)
 
 Published to npm as [`recess-cli`](https://www.npmjs.com/package/recess-cli). On any machine with Node 20+:

package/dist/args.js

@@ -19,6 +19,7 @@ const BOOLEAN_FLAGS = new Set([
     "help",
     "immediate",
     "include-deleted",
+    "include-archived",
     "mirrored",
     "no-invite",
     "no-collision",

package/dist/cli.js

@@ -9,9 +9,11 @@ import { clearStoredSession, deleteProfile, listProfiles, resolveConfig, savePro
 import { agentContext, buildCommandSchema, findCommandSchema, remoteCommands, scopedHelp, validateInvocation, } from "./command-schema.js";
 import { runApplicationsCommand } from "./commands/applications.js";
 import { runAppsCommand } from "./commands/apps.js";
+import { readAssignmentSelection, runGoalCurriculumCommand, } from "./commands/goal-curriculum.js";
 import { runChatLogsCommand } from "./commands/chat-logs.js";
 import { runMasteryCommand } from "./commands/mastery.js";
 import { runOnboardingCommand } from "./commands/onboarding.js";
+import { runScheduleCommand, runMemoryFilesCommand, } from "./commands/safe-staff-operations.js";
 import { runSchoolCommand } from "./commands/school.js";
 import { runVillageEventsCommand } from "./commands/village-events.js";
 import { assertChoice, flagIdList, positional, readJsonFile, readJsonValue, } from "./commands/shared.js";
@@ -252,7 +254,10 @@ async function localWriteCommand(parsed, preview, execute) {
             action: preview.action,
             fingerprint,
             target: preview.target,
-            ...(preview.action.startsWith("mastery.") ? { preview } : {}),
+            ...(preview.action.startsWith("mastery.") ||
+                preview.request.attendanceTakenAt
+                ? { preview }
+                : {}),
         });
         requireConfirmation(false, boundPreview);
     }
@@ -611,7 +616,7 @@ function assertOperationKeyMatchesPreview(operationKey, fingerprint, preview) {
         });
     }
 }
-async function requirePreviewBoundConfirmation(parsed, preview) {
+async function requirePreviewBoundConfirmation(parsed, preview, persistPreview = false) {
     const approvalToken = approvalTokenFor(preview);
     const suppliedOperationKey = flagString(parsed, "operation-key");
     const boundPreview = {
@@ -630,6 +635,9 @@ async function requirePreviewBoundConfirmation(parsed, preview) {
             action: preview.action,
             fingerprint: approvalToken,
             target: preview.target,
+            // Opted-in operations retain the approved receipt in the 0600 ledger so
+            // retries can reach server idempotency after their own write changed state.
+            ...(persistPreview ? { preview } : {}),
         });
         requireConfirmation(false, boundPreview);
     }
@@ -651,13 +659,18 @@ async function requirePreviewBoundConfirmation(parsed, preview) {
     });
     return { operationKey: suppliedOperationKey, fingerprint: approvalToken };
 }
-async function previewBoundWrite(parsed, preview, execute) {
-    const context = await requirePreviewBoundConfirmation(parsed, preview);
+async function previewBoundWrite(parsed, preview, execute, persistPreview = false) {
+    const context = await requirePreviewBoundConfirmation(parsed, preview, persistPreview);
     try {
         const result = await withIdempotencyContext(context, execute);
         await appendJobEvent({
             jobId: context.operationKey,
-            status: "completed",
+            status: typeof result === "object" &&
+                result !== null &&
+                "outcome" in result &&
+                result.outcome === "outcome_unknown"
+                ? "unknown"
+                : "completed",
             timestamp: new Date().toISOString(),
             action: preview.action,
             fingerprint: context.fingerprint,
@@ -679,6 +692,41 @@ async function previewBoundWrite(parsed, preview, execute) {
         throw error;
     }
 }
+async function readExecutedPreview(parsed) {
+    const key = flagString(parsed, "operation-key");
+    if (!hasFlag(parsed, "confirm") || !key)
+        return null;
+    const { history } = await getJob(key);
+    const receipt = [...history].reverse().find((event) => event.preview);
+    if (!receipt?.preview)
+        return null;
+    // First confirmation still refreshes server effects. A prior execution
+    // attempt is what makes a stale preflight an idempotent-recovery problem.
+    if (!history.some((event) => event.status !== "awaiting_confirmation" &&
+        event.fingerprint === receipt.fingerprint &&
+        event.action === receipt.action))
+        return null;
+    const saved = receipt.preview;
+    const fingerprint = approvalTokenFor(saved);
+    if (receipt.fingerprint !== fingerprint ||
+        flagString(parsed, "approval-token") !== fingerprint) {
+        throw new CliError("approval_mismatch", "This operation key does not match the approved command. Retry the original command unchanged, or review a new preview.");
+    }
+    assertOperationKeyMatchesPreview(key, fingerprint, saved);
+    return saved;
+}
+/** A retried write must retain its approved fence after changing its own source state. */
+async function recoverExecutedPreview(parsed, expected) {
+    const saved = await readExecutedPreview(parsed);
+    if (!saved)
+        return null;
+    if (saved.action !== expected.action ||
+        JSON.stringify(saved.target) !== JSON.stringify(expected.target) ||
+        JSON.stringify(saved.request) !== JSON.stringify(expected.request)) {
+        throw new CliError("approval_mismatch", "This operation key does not match the approved command. Retry the original command unchanged, or review a new preview.");
+    }
+    return saved;
+}
 async function cleanupPlannerUpload(api, conversationId, signed, includeDelete) {
     if (signed.kind === "multipart") {
         await api.client
@@ -2677,6 +2725,14 @@ export async function executeRecessCommand(argv, options = {}) {
     if (noun === "school") {
         return runSchoolCommand({ parsed, api, writeCommand });
     }
+    if (noun === "cohorts" && verb === "schedule")
+        return runScheduleCommand({ parsed, api, writeCommand: previewBoundWrite });
+    if (noun === "memories" && verb !== "context" && verb !== "log")
+        return runMemoryFilesCommand({
+            parsed,
+            api,
+            writeCommand: previewBoundWrite,
+        });
     if (noun === "cohorts" && verb === "search") {
         const search = parsed.positionals.slice(2).join(" ").trim();
         if (!search)
@@ -3159,7 +3215,16 @@ export async function executeRecessCommand(argv, options = {}) {
                 excused: true,
             })),
         ];
-        const body = { attendanceTakenAt: new Date().toISOString(), attendance };
+        const operationKey = flagString(parsed, "operation-key");
+        const stored = operationKey ? await getJob(operationKey) : undefined;
+        const preparedAt = stored?.history.find((event) => event.preview?.request.attendanceTakenAt)?.preview?.request.attendanceTakenAt;
+        if (hasFlag(parsed, "confirm") && typeof preparedAt !== "string") {
+            throw new CliError("confirmation_required", "The saved attendance preview is unavailable. Request a new preview before confirming.");
+        }
+        const body = {
+            attendanceTakenAt: typeof preparedAt === "string" ? preparedAt : new Date().toISOString(),
+            attendance,
+        };
         return writeCommand(parsed, {
             action: "take attendance (non-excused absentees may trigger automatic 'we missed you' emails to parents)",
             target: { eventId },
@@ -3434,6 +3499,16 @@ export async function executeRecessCommand(argv, options = {}) {
         throw new CliError("invalid_arguments", "Use content-library search, status, set-stage, or submit.");
     }
     if (noun === "goal-templates") {
+        if (verb === "curriculum") {
+            return runGoalCurriculumCommand({
+                parsed,
+                api,
+                writeCommand,
+                resolveTemplateId: (value) => resolveGoalTemplateId(api, value),
+                previewBoundWrite: (args, preview, execute) => previewBoundWrite(args, preview, execute, true),
+                recoverExecutedPreview: (expected) => recoverExecutedPreview(parsed, expected),
+            });
+        }
         const readTemplateDocument = async () => {
             if (!isRemote) {
                 return readJsonFile(flagString(parsed, "file", { required: true }), "Template file");
@@ -3592,6 +3667,174 @@ export async function executeRecessCommand(argv, options = {}) {
                 body: document,
             })));
         }
+        if (verb === "policy") {
+            const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
+            return unwrap(await api.client.GET("/ai/goal-templates/{id}/policy", {
+                params: { path: { id } },
+            }));
+        }
+        if (verb === "set-policy") {
+            const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
+            const target = flagString(parsed, "target-modules");
+            const minimum = flagString(parsed, "required-modules");
+            for (const [flag, value] of [
+                ["target-modules", target],
+                ["required-modules", minimum],
+            ]) {
+                if (value === undefined ||
+                    (flag === "required-modules" && value === "all"))
+                    continue;
+                const count = Number(value);
+                if (!Number.isInteger(count) || count < 1 || count > 20)
+                    throw new CliError("invalid_arguments", `--${flag} must be an integer from 1 through 20${flag === "required-modules" ? " or all" : ""}.`);
+            }
+            if (target === undefined && minimum === undefined)
+                throw new CliError("invalid_arguments", "Provide --target-modules or --required-modules N|all");
+            const body = {
+                recipeKey: flagString(parsed, "recipe", { required: true }),
+                ...(target === undefined ? {} : { targetModuleCount: Number(target) }),
+                ...(minimum === undefined
+                    ? {}
+                    : {
+                        requiredModuleCount: minimum === "all" ? null : Number(minimum),
+                    }),
+                expectedVersion: requiredExpectedVersion(parsed),
+            };
+            const requestPreview = {
+                action: "edit shared goal-template assigned target or completion minimum",
+                target: { templateId: id, apiOrigin: api.config.apiOrigin },
+                request: body,
+            };
+            const receipt = await recoverExecutedPreview(parsed, requestPreview);
+            const preview = receipt ?? {
+                ...requestPreview,
+                details: unwrap(await api.client.POST("/ai/goal-templates/{id}/policy", {
+                    params: { path: { id } },
+                    body: { ...body, dryRun: true },
+                })),
+            };
+            // A recovered receipt only skips the now-stale preview. The actual write
+            // still reaches server authorization, idempotency, and expectedVersion.
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.POST("/ai/goal-templates/{id}/policy", {
+                params: { path: { id } },
+                body: { ...body, dryRun: false },
+            })), true);
+        }
+        if (verb === "migrate-policy") {
+            const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
+            const studentIds = flagString(parsed, "students", { required: true })
+                .split(",")
+                .map((value) => value.trim());
+            const preflight = unwrap(await api.client.POST("/ai/goal-templates/{id}/policy-migration", {
+                params: { path: { id } },
+                body: { studentIds, dryRun: true },
+            }));
+            const preview = {
+                action: "backfill reviewed goal policy identities and migration holds",
+                target: { templateId: id, studentIds },
+                request: { studentIds, fingerprint: preflight.fingerprint },
+                details: preflight,
+            };
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.POST("/ai/goal-templates/{id}/policy-migration", {
+                params: { path: { id } },
+                body: {
+                    studentIds,
+                    fingerprint: preflight.fingerprint,
+                    dryRun: false,
+                },
+            })));
+        }
+        if (verb === "retire-assignments") {
+            const [id, session] = await Promise.all([
+                resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug")),
+                api.client.GET("/auth/admin-cli/session/").then(unwrap),
+            ]);
+            if (session.user.role !== "ADMIN" || session.cliScope !== "full_admin")
+                throw new CliError("forbidden", "Assignment retirement requires a full-admin session.");
+            const goalId = flagString(parsed, "goal", { required: true });
+            const rawIds = flagString(parsed, "todos");
+            const selectionPath = flagString(parsed, "todos-file");
+            if (Boolean(rawIds) === Boolean(selectionPath))
+                throw new CliError("invalid_arguments", "Choose exactly one of --todos or --todos-file with explicit assignment IDs.");
+            const selection = selectionPath
+                ? await readAssignmentSelection(selectionPath)
+                : null;
+            const todoIds = selection?.todoIds ?? rawIds.split(",").map((id) => id.trim());
+            if (!todoIds.length ||
+                todoIds.length > 500 ||
+                todoIds.some((id) => !id) ||
+                new Set(todoIds).size !== todoIds.length)
+                throw new CliError("invalid_arguments", "Choose 1–500 distinct assignment IDs explicitly.");
+            const reason = flagString(parsed, "retirement-reason", {
+                required: true,
+            });
+            const requestPreview = {
+                action: "retire the selected curriculum assignments without completing lessons",
+                target: {
+                    templateId: id,
+                    goalId,
+                    actorId: session.user.id,
+                    apiOrigin: api.config.apiOrigin,
+                },
+                request: { todoIds, reason, selectionFile: selection?.file ?? null },
+            };
+            const receipt = await recoverExecutedPreview(parsed, requestPreview);
+            const preflight = receipt
+                ? receipt.details
+                : unwrap(await api.client.POST("/ai/goal-templates/{id}/goals/{goalId}/assignments/retire", {
+                    params: { path: { id, goalId } },
+                    body: { todoIds, reason, dryRun: true },
+                }));
+            const preview = receipt ?? {
+                ...requestPreview,
+                details: preflight,
+            };
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.POST("/ai/goal-templates/{id}/goals/{goalId}/assignments/retire", {
+                params: { path: { id, goalId } },
+                body: {
+                    todoIds,
+                    reason,
+                    fingerprint: preflight.fingerprint,
+                    dryRun: false,
+                },
+            })));
+        }
+        if (verb === "student-policy") {
+            const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
+            const goalId = flagString(parsed, "goal", { required: true });
+            const filePath = path.resolve(flagString(parsed, "file", { required: true }));
+            const bytes = await fs.readFile(filePath);
+            let raw;
+            try {
+                raw = JSON.parse(bytes.toString("utf8"));
+            }
+            catch {
+                throw new CliError("invalid_arguments", "Student policy edit must contain valid JSON");
+            }
+            // Backend Zod is authoritative; preserve exact file bytes in the approval preview.
+            const body = raw;
+            const preflight = unwrap(await api.client.POST("/ai/goal-templates/{id}/goals/{goalId}/policy", {
+                params: { path: { id, goalId } },
+                body: { ...body, dryRun: true },
+            }));
+            const preview = {
+                action: "review a student policy override or migration hold",
+                target: { templateId: id, goalId },
+                request: body,
+                details: {
+                    ...preflight,
+                    file: {
+                        absolutePath: filePath,
+                        sizeBytes: bytes.byteLength,
+                        sha256: createHash("sha256").update(bytes).digest("hex"),
+                    },
+                },
+            };
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.POST("/ai/goal-templates/{id}/goals/{goalId}/policy", {
+                params: { path: { id, goalId } },
+                body: { ...body, dryRun: false },
+            })));
+        }
         if (verb === "patch-spec") {
             const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
             const expectedVersion = requiredExpectedVersion(parsed);
@@ -4048,9 +4291,21 @@ export async function executeRecessCommand(argv, options = {}) {
         }
         if (verb === "list") {
             const userId = flagString(parsed, "student", { required: true });
-            return unwrap(await api.client.GET("/tutor/browser/students/{userId}/goals/", {
+            const result = unwrap(await api.client.GET("/tutor/browser/students/{userId}/goals/", {
                 params: { path: { userId } },
             }));
+            const query = flagString(parsed, "query")?.toLocaleLowerCase();
+            return {
+                ...result,
+                goals: result.goals.filter((goal) => (goal.status === "ACTIVE" ||
+                    goal.status === "PAUSED" ||
+                    (hasFlag(parsed, "include-archived") &&
+                        goal.status === "COMPLETED")) &&
+                    (!query ||
+                        `${goal.title}\n${goal.description ?? ""}`
+                            .toLocaleLowerCase()
+                            .includes(query))),
+            };
         }
         if (verb === "create") {
             const requestedStudentId = flagString(parsed, "student");
@@ -5047,7 +5302,40 @@ export async function executeRecessCommand(argv, options = {}) {
                 required: true,
             });
             const checkout = await readRecessGitMetadata(sourceDirectory);
-            const local = await readGoalWorkspaceGitChanges(checkout.root, checkout.metadata.upstreamCommit);
+            const isGoal = checkout.metadata.target.kind === "goal";
+            const session = isGoal
+                ? unwrap(await api.client.GET("/auth/admin-cli/session/"))
+                : null;
+            const actionDescription = `push committed Git changes to a student's Mesa ${checkout.metadata.target.kind} workspace`;
+            const boundTarget = session
+                ? {
+                    studentId: checkout.metadata.studentId,
+                    workspace: checkout.metadata.target,
+                    actorId: session.user.id,
+                    apiOrigin: api.config.apiOrigin,
+                }
+                : null;
+            const receipt = isGoal ? await readExecutedPreview(parsed) : null;
+            if (receipt &&
+                (receipt.action !== actionDescription ||
+                    JSON.stringify(receipt.target) !== JSON.stringify(boundTarget) ||
+                    receipt.request.sourceDirectory !== checkout.root)) {
+                throw new CliError("approval_mismatch", "The approved push belongs to a different checkout, account, or API.");
+            }
+            const localBaseCommit = receipt
+                ? String(receipt.request.localBaseCommit)
+                : checkout.metadata.upstreamCommit;
+            const mesaBaseChangeId = receipt
+                ? String(receipt.request.mesaBaseChangeId)
+                : checkout.metadata.changeId;
+            const local = await readGoalWorkspaceGitChanges(checkout.root, localBaseCommit);
+            if (receipt &&
+                ((checkout.metadata.upstreamCommit !== localBaseCommit &&
+                    checkout.metadata.upstreamCommit !== local.head) ||
+                    (checkout.metadata.upstreamCommit === localBaseCommit &&
+                        checkout.metadata.changeId !== mesaBaseChangeId))) {
+                throw new CliError("approval_mismatch", "The checkout's upstream metadata moved outside the approved push.");
+            }
             const defaultMessage = local.commits.length === 1
                 ? local.commits[0].subject
                 : `recess-cli: push ${local.commits.length} commits (${local.commits.at(-1).subject})`;
@@ -5068,36 +5356,44 @@ export async function executeRecessCommand(argv, options = {}) {
                 target: checkout.metadata.target,
                 message,
                 files,
-                expectedChangeId: checkout.metadata.changeId,
+                expectedChangeId: mesaBaseChangeId,
             };
-            const preflight = unwrap(await api.client.POST("/tutor/browser/mesa/workspace-files", {
-                body: { ...body, dryRun: true },
-            }));
-            if (preflight.action !== "preview_workspace_files_write") {
+            const preflight = receipt
+                ? null
+                : unwrap(await api.client.POST("/tutor/browser/mesa/workspace-files", {
+                    body: { ...body, dryRun: true },
+                }));
+            if (preflight && preflight.action !== "preview_workspace_files_write") {
                 throw new CliError("unexpected_response", "Goal workspace push did not return a preview; nothing was written.");
             }
-            const preview = {
-                action: `push committed Git changes to a student's Mesa ${checkout.metadata.target.kind} workspace`,
-                target: preflight.target,
-                request: {
-                    sourceDirectory: checkout.root,
-                    mesaBaseChangeId: checkout.metadata.changeId,
-                    localBaseCommit: checkout.metadata.upstreamCommit,
-                    localHeadCommit: local.head,
-                    commits: local.commits,
-                    message,
-                    changes: local.changes.map((change) => change.action === "delete"
-                        ? change
-                        : {
-                            path: change.path,
-                            action: change.action,
-                            sizeBytes: change.sizeBytes,
-                            sha256: change.sha256,
-                        }),
-                    sizeBytes: local.sizeBytes,
-                },
+            const request = {
+                sourceDirectory: checkout.root,
+                mesaBaseChangeId,
+                localBaseCommit,
+                localHeadCommit: local.head,
+                commits: local.commits,
+                message,
+                changes: local.changes.map((change) => change.action === "delete"
+                    ? change
+                    : {
+                        path: change.path,
+                        action: change.action,
+                        sizeBytes: change.sizeBytes,
+                        sha256: change.sha256,
+                    }),
+                sizeBytes: local.sizeBytes,
+            };
+            if (receipt &&
+                JSON.stringify(receipt.request) !== JSON.stringify(request)) {
+                throw new CliError("approval_mismatch", "The command or committed file bytes differ from the approved push.");
+            }
+            const preview = receipt ?? {
+                action: actionDescription,
+                target: boundTarget ?? preflight.target,
+                request,
                 details: {
                     currentChangeId: preflight.currentChangeId,
+                    resolvedTarget: preflight.target,
                     note: "The committed local diff is published as one atomic Mesa change. Deletes and renames follow Git's diff. A changed Mesa tip refuses the push.",
                 },
             };
@@ -5108,6 +5404,11 @@ export async function executeRecessCommand(argv, options = {}) {
                 if (result.action !== "write_workspace_files") {
                     throw new CliError("unexpected_response", "Goal workspace push returned an unexpected response.");
                 }
+                if (receipt &&
+                    checkout.metadata.upstreamCommit === local.head &&
+                    checkout.metadata.changeId !== result.changeId) {
+                    throw new CliError("approval_mismatch", "The acknowledged checkout revision does not match this recovered push. Its local metadata was preserved.");
+                }
                 await writeRecessGitMetadata(checkout.root, {
                     ...checkout.metadata,
                     changeId: result.changeId,
@@ -5120,7 +5421,7 @@ export async function executeRecessCommand(argv, options = {}) {
                         upstreamCommit: local.head,
                     },
                 };
-            });
+            }, isGoal);
         }
         if (action === "write") {
             const studentId = flagString(parsed, "student", { required: true });
@@ -5141,25 +5442,47 @@ export async function executeRecessCommand(argv, options = {}) {
                 message,
                 files: input.files,
             };
-            const preflight = unwrap(await api.client.POST("/tutor/browser/mesa/workspace-files", {
-                body: { ...body, dryRun: true },
-            }));
-            if (preflight.action !== "preview_workspace_files_write") {
+            const session = goalId
+                ? unwrap(await api.client.GET("/auth/admin-cli/session/"))
+                : null;
+            const request = {
+                source: input.source,
+                sourceSha256: input.sha256,
+                fileCount: input.files.length,
+                sizeBytes: input.sizeBytes,
+                message,
+            };
+            const boundTarget = session
+                ? {
+                    studentId,
+                    goalId: goalId,
+                    actorId: session.user.id,
+                    apiOrigin: api.config.apiOrigin,
+                }
+                : null;
+            const receipt = boundTarget
+                ? await recoverExecutedPreview(parsed, {
+                    action: "batch-upsert files in a student's goal workspace",
+                    target: boundTarget,
+                    request,
+                })
+                : null;
+            const preflight = receipt
+                ? null
+                : unwrap(await api.client.POST("/tutor/browser/mesa/workspace-files", {
+                    body: { ...body, dryRun: true },
+                }));
+            if (preflight && preflight.action !== "preview_workspace_files_write") {
                 throw new CliError("unexpected_response", "Goal workspace write did not return a preview; nothing was written.");
             }
-            const preview = {
+            const preview = receipt ?? {
                 action: "batch-upsert files in a student's goal workspace",
-                target: preflight.target,
-                request: {
-                    source: input.source,
-                    sourceSha256: input.sha256,
-                    fileCount: input.files.length,
-                    sizeBytes: input.sizeBytes,
-                    message,
-                },
+                target: boundTarget ?? preflight.target,
+                request,
                 details: {
                     currentChangeId: preflight.currentChangeId,
                     files: preflight.files,
+                    resolvedTarget: preflight.target,
                     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."
                         : "This directly edits the live goal workspace, including modules/ and state/. The write remains bound to the previewed workspace revision.",
@@ -5169,9 +5492,9 @@ export async function executeRecessCommand(argv, options = {}) {
                 body: {
                     ...body,
                     dryRun: false,
-                    expectedChangeId: preflight.currentChangeId,
+                    expectedChangeId: String(preview.details.currentChangeId),
                 },
-            })));
+            })), Boolean(goalId));
         }
         throw new CliError("invalid_arguments", "Use goals files list|read|init|checkout|push|write.");
     }

package/dist/command-schema.js

@@ -22,6 +22,7 @@ const BOOLEAN_FLAGS = new Set([
     "immediate",
     "keep-tokens",
     "include-deleted",
+    "include-archived",
     "json",
     "mirrored",
     "no-collision",
@@ -180,6 +181,16 @@ const FAMILY_AI_COMMANDS = new Set([
     "todos edit",
 ]);
 const STAFF_COMMANDS = new Set([
+    "cohorts schedule get",
+    "cohorts schedule set",
+    "cohorts schedule changes",
+    "cohorts schedule change",
+    "memories files",
+    "memories read",
+    "memories edit",
+    "memories history",
+    "memories revision",
+    "memories restore",
     "apps assign",
     "apps list",
     "apps preview",

package/dist/commands/goal-curriculum.js

@@ -0,0 +1,187 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { unwrap } from "../api.js";
+import { flagString } from "../args.js";
+import { CliError } from "../errors.js";
+import { flagInteger, positional } from "./shared.js";
+/** Selection files only supply explicit IDs; they never expand a filter into a mutation. */
+export async function readAssignmentSelection(filePath) {
+    const absolutePath = path.resolve(filePath);
+    const stat = await fs.stat(absolutePath);
+    if (!stat.isFile() || stat.size > 1024 * 1024) {
+        throw new CliError("invalid_arguments", "The assignment selection must be a regular JSON file no larger than 1 MiB.");
+    }
+    const bytes = await fs.readFile(absolutePath);
+    let document;
+    try {
+        document = JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        throw new CliError("invalid_arguments", "The assignment selection must contain valid JSON.");
+    }
+    if (!document ||
+        typeof document !== "object" ||
+        Array.isArray(document) ||
+        Object.keys(document).length !== 1 ||
+        !("todoIds" in document) ||
+        !Array.isArray(document.todoIds) ||
+        !document.todoIds.every((id) => typeof id === "string")) {
+        throw new CliError("invalid_arguments", 'The selection file must contain exactly {"todoIds":["assignment-uuid", ...]}.');
+    }
+    return {
+        todoIds: document.todoIds,
+        file: {
+            absolutePath,
+            sizeBytes: bytes.byteLength,
+            sha256: createHash("sha256").update(bytes).digest("hex"),
+        },
+    };
+}
+async function readResolutions(filePath) {
+    const absolutePath = path.resolve(filePath);
+    let bytes;
+    try {
+        const stat = await fs.stat(absolutePath);
+        if (!stat.isFile() || stat.size > 1024 * 1024) {
+            throw new CliError("invalid_arguments", "The resolution file must be a regular JSON file no larger than 1 MiB.");
+        }
+        bytes = await fs.readFile(absolutePath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new CliError("invalid_arguments", `File not found: ${absolutePath}`);
+        }
+        throw error;
+    }
+    let document;
+    try {
+        document = JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        throw new CliError("invalid_arguments", "The resolution file must contain valid JSON.");
+    }
+    if (!document || typeof document !== "object" || Array.isArray(document)) {
+        throw new CliError("invalid_arguments", "The resolution file must contain a JSON object.");
+    }
+    // The backend validates document version, choices, conflict IDs, and whether
+    // each choice is supported by the current three-way comparison.
+    return {
+        document: document,
+        file: {
+            absolutePath,
+            sizeBytes: bytes.byteLength,
+            sha256: createHash("sha256").update(bytes).digest("hex"),
+        },
+    };
+}
+export async function runGoalCurriculumCommand({ parsed, api, resolveTemplateId, previewBoundWrite, recoverExecutedPreview, }) {
+    const verb = positional(parsed, 2, "curriculum operation");
+    const [id, session] = await Promise.all([
+        resolveTemplateId(positional(parsed, 3, "template ID or slug")),
+        api.client.GET("/auth/admin-cli/session/").then(unwrap),
+    ]);
+    if (session.user.role !== "ADMIN" || session.cliScope !== "full_admin") {
+        throw new CliError("forbidden", "Curriculum updates require a full-admin session.");
+    }
+    const environment = {
+        actorId: session.user.id,
+        apiOrigin: api.config.apiOrigin,
+    };
+    if (verb === "status" || verb === "retry") {
+        const jobId = flagString(parsed, "job", { required: true });
+        if (verb === "status") {
+            return unwrap(await api.client.GET("/ai/goal-templates/{id}/curriculum/jobs/{jobId}", {
+                params: { path: { id, jobId } },
+            }));
+        }
+        const requestPreview = {
+            action: "resume the previously approved curriculum job",
+            target: { templateId: id, jobId, ...environment },
+            request: {},
+        };
+        const receipt = await recoverExecutedPreview(requestPreview);
+        const preview = receipt ?? {
+            ...requestPreview,
+            details: {
+                job: unwrap(await api.client.GET("/ai/goal-templates/{id}/curriculum/jobs/{jobId}", {
+                    params: { path: { id, jobId } },
+                })),
+                note: "Resumes this job's stored scope and resolutions. Completed goals are not replayed; stale goals require a new preview.",
+            },
+        };
+        return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.POST("/ai/goal-templates/{id}/curriculum/jobs/{jobId}/retry", {
+            params: { path: { id, jobId } },
+            body: {},
+        })));
+    }
+    const goalIds = flagString(parsed, "goals", { required: true })
+        .split(",")
+        .map((value) => value.trim());
+    if (goalIds.some((value) => !value) ||
+        new Set(goalIds).size !== goalIds.length) {
+        throw new CliError("invalid_arguments", "--goals must list distinct, nonempty goal IDs.");
+    }
+    if (verb === "backlog") {
+        const dueBefore = flagString(parsed, "due-before");
+        return unwrap(await api.client.GET("/ai/goal-templates/{id}/curriculum/backlog", {
+            params: {
+                path: { id },
+                query: { goalIds: goalIds.join(","), dueBefore },
+            },
+        }));
+    }
+    const targetVersion = flagInteger(parsed, "version", {
+        required: true,
+        min: 1,
+    });
+    const filePath = flagString(parsed, "resolutions-file", {
+        required: verb === "validate-resolutions",
+    });
+    const resolutionFile = filePath ? await readResolutions(filePath) : undefined;
+    const body = {
+        goalIds,
+        targetVersion,
+        resolutions: resolutionFile?.document ?? { version: 1, resolutions: [] },
+    };
+    const requestPreview = {
+        action: verb === "reverse"
+            ? "merge a prior template curriculum version into the selected student goals"
+            : "merge the selected template curriculum version into the selected student goals",
+        target: { templateId: id, goalIds, ...environment },
+        request: { ...body, resolutionFile: resolutionFile?.file ?? null },
+    };
+    const receipt = verb === "apply" || verb === "reverse"
+        ? await recoverExecutedPreview(requestPreview)
+        : null;
+    const comparison = receipt
+        ? receipt.details?.comparison
+        : unwrap(await api.client.POST("/ai/goal-templates/{id}/curriculum/preview", {
+            params: { path: { id } },
+            body,
+        }));
+    if (verb === "preview" || verb === "validate-resolutions") {
+        return { ...comparison, resolutionFile: resolutionFile?.file ?? null };
+    }
+    if (verb !== "apply" && verb !== "reverse") {
+        throw new CliError("invalid_arguments", "Use curriculum backlog|preview|validate-resolutions|apply|status|retry|reverse.");
+    }
+    const preview = receipt ?? {
+        ...requestPreview,
+        details: {
+            comparison,
+            note: "Only the exact selected goals are included. Unresolved conflicts block their goal. Assignments and earned history remain protected; reverse updates preserve changes made since the earlier version.",
+        },
+    };
+    return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.POST("/ai/goal-templates/{id}/curriculum/apply", {
+        params: { path: { id } },
+        body: {
+            ...body,
+            fingerprint: comparison.fingerprint,
+            operationKey: flagString(parsed, "operation-key", {
+                required: true,
+            }),
+        },
+    })));
+}
+//# sourceMappingURL=goal-curriculum.js.map

package/dist/commands/safe-staff-operations.js

@@ -0,0 +1,183 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { unwrap } from "../api.js";
+import { flagString, hasFlag } from "../args.js";
+import { CliError } from "../errors.js";
+import { appendJobEvent } from "../jobs.js";
+import { assertChoice, positional } from "./shared.js";
+const hash = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+function recoveryKey(ctx) {
+    if (!hasFlag(ctx.parsed, "confirm"))
+        return undefined;
+    const key = flagString(ctx.parsed, "operation-key");
+    const token = flagString(ctx.parsed, "approval-token");
+    if (key && (!token || !key.endsWith(`_${token}`)))
+        throw new CliError("approval_mismatch", "Recovery requires the original operation key and approval token.");
+    return key;
+}
+async function recovered(ctx, row, expectedInputHash) {
+    if (row.inputHash !== expectedInputHash)
+        throw new CliError("approval_mismatch", "This operation key belongs to different input. No operation was retried.");
+    await appendJobEvent({
+        jobId: row.operationKey,
+        status: row.outcome === "outcome_unknown" ? "unknown" : "completed",
+        timestamp: new Date().toISOString(),
+        action: "recover staff operation",
+        fingerprint: flagString(ctx.parsed, "approval-token"),
+        target: { apiOrigin: ctx.api.config.apiOrigin },
+        result: row,
+    });
+    return row;
+}
+export async function runScheduleCommand(ctx) {
+    const { api, parsed, writeCommand } = ctx;
+    const action = positional(parsed, 2, "schedule action");
+    const id = positional(parsed, 3, "cohort or change ID");
+    if (action === "change")
+        return unwrap(await api.client.GET("/admin/cohorts/schedule-changes/{changeId}", {
+            params: { path: { changeId: id } },
+        }));
+    const params = { path: { id } };
+    if (action === "get")
+        return unwrap(await api.client.GET("/admin/cohorts/{id}/schedule/", { params }));
+    if (action === "changes")
+        return unwrap(await api.client.GET("/admin/cohorts/{id}/schedule/changes", {
+            params: { ...params, query: { cursor: flagString(parsed, "cursor") } },
+        }));
+    if (action !== "set")
+        throw new CliError("invalid_arguments", "Use cohorts schedule get|set|changes|change.");
+    const input = {
+        days: flagString(parsed, "days", { required: true })
+            .split(",")
+            .map((d) => assertChoice(d.trim().toUpperCase(), ["MO", "TU", "WE", "TH", "FR", "SA", "SU"], "weekday")),
+        time: flagString(parsed, "time", { required: true }),
+        timezone: flagString(parsed, "timezone"),
+        effectiveDate: flagString(parsed, "effective-date", { required: true }),
+        notify: assertChoice(flagString(parsed, "notify", { required: true }), ["none", "parents"], "notify"),
+        reason: flagString(parsed, "reason", { required: true }).trim(),
+    };
+    const key = recoveryKey(ctx);
+    if (key) {
+        const history = unwrap(await api.client.GET("/admin/cohorts/{id}/schedule/changes", {
+            params: { ...params, query: { operationKey: key } },
+        }));
+        if (history.changes[0])
+            return recovered(ctx, history.changes[0], hash({ id, input }));
+    }
+    const capability = unwrap(await api.client.GET("/admin/cohorts/{id}/schedule/", { params }));
+    if (capability.capabilityVersion !== 1 || !capability.supported)
+        throw new CliError("unsupported_backend", capability.unsupportedReason ??
+            "Backend does not support safe schedule changes.");
+    const preview = unwrap(await api.client.POST("/admin/cohorts/{id}/schedule/preview", {
+        params,
+        body: input,
+    }));
+    return writeCommand(parsed, {
+        action: "change recurring cohort schedule",
+        target: { cohortId: id, apiOrigin: api.config.apiOrigin },
+        request: input,
+        details: preview,
+    }, async () => {
+        const result = unwrap(await api.client.POST("/admin/cohorts/{id}/schedule/apply", {
+            params,
+            body: {
+                ...input,
+                operationKey: flagString(parsed, "operation-key", {
+                    required: true,
+                }),
+                fingerprint: preview.fingerprint,
+            },
+        }));
+        return unwrap(await api.client.GET("/admin/cohorts/schedule-changes/{changeId}", {
+            params: { path: { changeId: result.id } },
+        }));
+    });
+}
+export async function runMemoryFilesCommand(ctx) {
+    const { parsed, api, writeCommand } = ctx;
+    const action = positional(parsed, 1, "memory action");
+    const studentId = flagString(parsed, "student", { required: true });
+    const params = { path: { studentId } };
+    if (action === "files")
+        return unwrap(await api.client.GET("/tutor/students/{studentId}/memory-files", {
+            params,
+        }));
+    const memoryPath = flagString(parsed, "path", { required: true });
+    if (action === "read")
+        return unwrap(await api.client.GET("/tutor/students/{studentId}/memory-files/read", {
+            params: { ...params, query: { path: memoryPath } },
+        }));
+    if (action === "history")
+        return unwrap(await api.client.GET("/tutor/students/{studentId}/memory-files/history", {
+            params: {
+                ...params,
+                query: { path: memoryPath, cursor: flagString(parsed, "cursor") },
+            },
+        }));
+    if (action === "revision")
+        return unwrap(await api.client.GET("/tutor/students/{studentId}/memory-files/revision", {
+            params: {
+                ...params,
+                query: {
+                    path: memoryPath,
+                    revision: flagString(parsed, "revision", { required: true }),
+                },
+            },
+        }));
+    if (action !== "edit" && action !== "restore")
+        throw new CliError("invalid_arguments", "Use memories files|read|edit|history|revision|restore.");
+    let content;
+    let contentFile;
+    if (action === "edit") {
+        contentFile = path.resolve(flagString(parsed, "content-file", { required: true }));
+        const info = await fs.lstat(contentFile);
+        if (!info.isFile() ||
+            info.isSymbolicLink() ||
+            (await fs.realpath(contentFile)) !== contentFile)
+            throw new CliError("invalid_file", "Memory input must be a regular file without symlink components.");
+        content = new TextDecoder("utf-8", { fatal: true }).decode(await fs.readFile(contentFile));
+    }
+    const input = {
+        path: memoryPath,
+        content,
+        revision: action === "restore"
+            ? flagString(parsed, "revision", { required: true })
+            : undefined,
+        action,
+        reason: flagString(parsed, "reason", { required: true }).trim(),
+    };
+    const key = recoveryKey(ctx);
+    if (key) {
+        const result = unwrap(await api.client.GET("/tutor/students/{studentId}/memory-files/operation", { params: { ...params, query: { operationKey: key } } }));
+        if (result.operation)
+            return recovered(ctx, result.operation, hash({ studentId, input }));
+    }
+    const preview = unwrap(await api.client.POST("/tutor/students/{studentId}/memory-files/preview", {
+        params,
+        body: input,
+    }));
+    if (preview.capabilityVersion !== 1 || preview.writeSupported !== true)
+        throw new CliError("unsupported_backend", preview.writeUnsupportedReason ??
+            "Backend does not support safe staff memory edits and restores.");
+    return writeCommand(parsed, {
+        action: `${action} student memory file`,
+        target: { studentId, path: memoryPath, apiOrigin: api.config.apiOrigin },
+        request: { ...input, contentFile },
+        details: {
+            ...preview,
+            before: { ...preview.before, revision: undefined },
+        },
+    }, async () => unwrap(await api.client.POST("/tutor/students/{studentId}/memory-files/apply", {
+        params,
+        body: {
+            ...input,
+            expectedHash: preview.before.contentSha,
+            fingerprint: preview.fingerprint,
+            operationKey: flagString(parsed, "operation-key", {
+                required: true,
+            }),
+        },
+    })));
+}
+//# sourceMappingURL=safe-staff-operations.js.map

package/dist/help.js

@@ -143,6 +143,10 @@ Usage:
     [--description TEXT] [--date YYYY-MM-DD] [--confirm]
   recess [--json] payout items delete <item-id> [--confirm]
   recess [--json] cohorts get <cohort-id> [--events-tab ACTIVE|ENDED|CANCELED|ARCHIVED]
+  recess [--json] cohorts schedule get <cohort-id>
+  recess [--json] cohorts schedule set <cohort-id> --days <MO,WE> --time <09:30> [--timezone <zone>] --effective-date <YYYY-MM-DD> --notify none|parents [--confirm] [--approval-token <token>]
+  recess [--json] cohorts schedule changes <cohort-id> [--cursor <cursor>]
+  recess [--json] cohorts schedule change <change-id>
   recess [--json] cohorts parent-emails <cohort-id>
   recess [--json] cohorts end <cohort-id> [--cancel-subscriptions] [--confirm]
   recess [--json] cohorts pause-billing <cohort-id> --weeks 1..6 [--confirm]
@@ -335,6 +339,29 @@ Usage:
     [--kind SIMPLE|BLUEPRINT] [--starter-only] [--include-deleted]
     [--limit 20] [--cursor <id>]
   recess [--json] goal-templates get <template-id|slug> [--spec-only]
+  recess [--json] goal-templates policy <template-id|slug>
+  recess [--json] goal-templates set-policy <template-id|slug> --recipe KEY
+    [--target-modules N] [--required-modules N|all] --expected-version N
+    [--confirm --approval-token TOKEN]
+  recess [--json] goal-templates migrate-policy <template-id|slug> --students ID,ID
+    [--confirm --approval-token TOKEN]
+  recess [--json] goal-templates student-policy <template-id|slug> --goal ID
+    --file <path/edit.json> [--confirm --approval-token TOKEN]
+  recess [--json] goal-templates retire-assignments <template-id|slug> --goal ID
+    [--todos ID,ID | --todos-file <path/selection.json>]
+    --retirement-reason TEXT [--confirm --approval-token TOKEN]
+  recess [--json] goal-templates curriculum backlog <template-id|slug>
+    --goals ID,ID [--due-before YYYY-MM-DD]
+  recess [--json] goal-templates curriculum preview <template-id|slug>
+    --goals ID,ID --version N [--resolutions-file <path/resolutions.json>]
+  recess [--json] goal-templates curriculum validate-resolutions <template-id|slug>
+    --goals ID,ID --version N --resolutions-file <path/resolutions.json>
+  recess [--json] goal-templates curriculum apply|reverse <template-id|slug>
+    --goals ID,ID --version N [--resolutions-file <path/resolutions.json>]
+    [--confirm --approval-token TOKEN]
+  recess [--json] goal-templates curriculum status <template-id|slug> --job ID
+  recess [--json] goal-templates curriculum retry <template-id|slug> --job ID
+    [--confirm --approval-token TOKEN]
   recess [--json] goal-templates versions <template-id> [--version N]
   recess [--json] goal-templates validate-spec --file <path/template.json>
   recess [--json] goal-templates create --file <path/template.json>
@@ -360,7 +387,7 @@ Usage:
     [--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 list --student <kid-id> [--query <text>] [--include-archived]
   recess [--json] goals create [--student <kid-id>] --title TEXT
     (--description TEXT | --description-file <path>) [--target-date <iso>]
     [--schedule TEXT] [(--draft <draft-slug> | --source-dir <local-checkout>)
@@ -395,6 +422,14 @@ Usage:
   recess [--json] todos generate-learning-analysis <todo-id> [--confirm]
   recess [--json] todos generate-applet <todo-id> --student <kid-id>
     [--due-date YYYY-MM-DD] [--confirm --approval-token TOKEN]
+  recess [--json] memories files --student <kid-id>
+  recess [--json] memories read --student <kid-id> --path <path>
+  recess [--json] memories edit --student <kid-id> --path <path> --content-file <file> [--confirm] [--approval-token <token>]
+  recess [--json] memories history --student <kid-id> --path <path> [--cursor <cursor>]
+  recess [--json] memories revision --student <kid-id> --path <path> --revision <revision>
+  recess [--json] memories restore --student <kid-id> --path <path> --revision <revision> [--confirm] [--approval-token <token>]
+    Staff memory edit/restore publication is disabled pending recoverable immutable history.
+    Reads, history, and recovery of existing operations remain available.
   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>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "recess-cli",
-  "version": "2.10.0",
+  "version": "3.1.0",
   "description": "Safe Recess administration and family AI tools from the command line.",
   "license": "UNLICENSED",
   "repository": {

package/skill/recess-cli/SKILL.md

@@ -72,18 +72,21 @@ Any changed target, payload, local file, server revision, amount, recipient, or
 
 ### Hosted MCP transport
 
-When this skill is reached through the hosted Recess connector, use its only tool,
-`recess_exec({argv,input?})`. `argv` starts with the command noun, omits both `recess` and `--json`,
-and still carries `--reason`. The CLI envelope is returned in MCP `structuredContent`; a
-`confirmation_required` envelope is expected control flow, while other failures are tool errors.
-Start with `argv:["agent-context"]` or `argv:["help","apps"]` for the remote-only catalog. OAuth
-already supplies the live user and scopes: never ask for cookies, profiles, local paths, or
-`--deliver`.
-
-Hosted writes stage the exact argv and structured payload on the server. Preview without
-`--confirm`, show the human `error.details.preview`, then confirm with the same command path plus
-`--confirm --operation-key <key>` and **omit `input`**. The server executes the stored bytes; changed
-source, flags, project/version, or operation keys require a fresh preview.
+Use the connector's individually named tools and their discovered argument schemas, for example
+`recess_students_todos({student:"…",reason:"…"})`. Discovery replaces CLI help. OAuth supplies the
+live user and consented scopes; never ask for cookies, local paths or profiles.
+
+Preview writes with named arguments and `reason`, show `error.details.preview`, then confirm
+through the same tool with **only** `{confirm:true,operationKey:"…"}`. Stored arguments and source
+bytes are restored server-side. Changed input or consequences require a new preview. Retain the
+key on interruption and inspect `recess_jobs_get`; never start a replacement for an uncertain
+write. `confirmation_required` is normal control flow in the returned `structuredContent`.
+
+Supply JSON/text directly, workspaces as file bundles with `baseRevision`, and binaries as
+`{name,content,encoding}` or scoped `{uploadHandle}` references created by `recess_upload_create`.
+Upload bytes to its signed URL(s); size/hash verification happens before use. Download returned
+bundles/authorized URLs. `/mcp/legacy` temporarily retains `recess_exec({command,input?})` for
+30 days after rollout. Refresh connector metadata and consent for expanded capabilities.
 
 ## Building Studio apps (`recess apps`)
 
@@ -106,20 +109,16 @@ prompts a model for them.
 - `recess --json apps standards "<words or notation>"` finds the CCSS standard for `manifest.json`
   (`"grade 4 adding fractions"` → `4.NF.B.3a`…); guides rarely know the codes, look them up.
 
-Hosted authoring keeps those same contracts but carries no folder:
-
-- `apps scaffold [--for-todo <id>]` returns authoring instructions, the five editable starter
-  files, fork guidance, and an optional learner brief. It performs no write.
-- Generate `input.appBundle` with exactly `skill.js`, `model.js`, `model.css`,
-  `params.schema.json`, and `params.json`, plus `contract` and `manifest`. Preview and confirm
-  `apps validate`; keep the returned project/version/build IDs and poll `apps status <build-id>`.
-- Fix findings in the bundle. For an existing project, first `apps pull <project-id>` and preserve
-  its `baseVersion`; a stale version is a conflict, never an overwrite.
-- `apps preview <project-id> --version <n>` returns the short-lived capability URL.
-  Preview/confirm `apps publish <project-id> --version <n>`, then poll its build. Publication sends
-  no source and reviews exactly that validated version.
-- After publication, preview/confirm `apps assign <project-id> --student <id> [--due YYYY-MM-DD]`.
-  Assignment is intentionally separate from hosted publish.
+Hosted authoring keeps those same contracts with named tools:
+
+- `recess_apps_scaffold` returns instructions, editable files, and an optional `forTodo` brief.
+- Supply `appBundle` (files, contract, manifest) to `recess_apps_validate`; preview and confirm,
+  then keep its project/version/build IDs and poll `recess_apps_status`.
+- Before editing an existing project, call `recess_apps_pull` and preserve its `baseVersion`.
+- `recess_apps_preview` previews creation of a temporary capability URL. Preview and confirm
+  `recess_apps_publish` for the exact project/version; it reviews that validated version.
+- Use `assign` and optional `due` on publication for recoverable publish-and-assign, or use
+  `recess_apps_assign` separately. A pending build retains the same operation key for retry.
 
 Two ways in. If the guide names a kid or a todo, pull the analysis first and build against it;
 otherwise build from their description:

package/skill/recess-cli/agents/version.json

@@ -1,4 +1,4 @@
 {
-  "version": "2.6.0",
-  "minCliVersion": "2.6.1"
+  "version": "3.0.0",
+  "minCliVersion": "3.0.0"
 }