recess-cli 3.1.0 → 3.3.0

package/README.md

@@ -77,13 +77,19 @@ Create an approved `OAuthClient` row in each Recess environment. This remains a
 
 The production row ID (`c7e34138-18f9-45b1-a2fb-26a4e3a6d739`) is the CLI's built-in default, so production login needs no client-ID setup. `--client-id`, `RECESS_CLI_OAUTH_CLIENT_ID`, and a stored client ID remain overrides for local/staging clients. The web-server decodes the assertion audience, loads that exact `OAuthClient`, and requires both `approved` and `adminCliEnabled`; there is no separate server environment allowlist. Production redirect validation is exact, so a different callback port must also be explicitly registered.
 
-The browser SSO assertion is exchanged once and discarded. The CLI stores a separate 12-hour signed Recess session at `~/.recess-cli/config.json` with mode `0600`. A guardian must hold the live `access:ai` permission; removing it immediately invalidates session checks. Guardian sessions cannot call `/admin` routes and every target is independently restricted to their family. A KID session has `village_home` scope: application-level and shared-auth fences permit only session inspection and Village assertion minting, denying every other backend route.
+The browser SSO assertion is exchanged once and discarded. The CLI stores a separate signed Recess session (12 hours by default) at `~/.recess-cli/config.json` with mode `0600`. A guardian must hold the live `access:ai` permission; removing it immediately invalidates session checks. Guardian sessions cannot call `/admin` routes and every target is independently restricted to their family. A KID session has `village_home` scope: application-level and shared-auth fences permit only session inspection and Village assertion minting, denying every other backend route.
 
 ```bash
 recess --json auth login
 recess --json doctor --reason "Verify CLI connectivity, identity, and scope"
 ```
 
+Sessions default to 12 hours. Admins can request 30 days locally with
+`recess --json auth login --duration 30d`, or remotely with
+`recess --json auth request --duration 30d --label "remote agent"`, approve the link as an
+admin, then run `recess --json auth poll`. The approval page shows the requested duration;
+the link still expires after 10 minutes. Non-admins cannot authorize 30-day sessions.
+
 ## Testing against a local server
 
 `auth login` opens production SSO, so local iteration uses the env-cookie hatch instead:

package/dist/args.js

@@ -6,6 +6,7 @@ import { CliError } from "./errors.js";
  */
 export const REPEATABLE_FLAGS = new Set(["kid", "unassign"]);
 const BOOLEAN_FLAGS = new Set([
+    "allow-assigned-edits",
     "all-references",
     "allow-strand",
     "cancel-subscriptions",

package/dist/auth.js

@@ -77,7 +77,11 @@ export async function login(config, options) {
     const assertion = await callback;
     const response = await fetch(new URL("/auth/admin-cli/exchange/", config.apiOrigin), {
         method: "POST",
-        headers: cliRequestHeaders({ authorization: `Bearer ${assertion}` }),
+        headers: cliRequestHeaders({
+            authorization: `Bearer ${assertion}`,
+            "content-type": "application/json",
+        }),
+        body: JSON.stringify({ sessionDuration: options.sessionDuration }),
     });
     const body = (await response.json());
     if (!response.ok)
@@ -109,7 +113,7 @@ export async function requestDeviceAuth(config, options) {
     const response = await fetch(new URL("/auth/admin-cli/device/authorize/", config.apiOrigin), {
         method: "POST",
         headers: cliRequestHeaders({ "content-type": "application/json" }),
-        body: JSON.stringify(options.label ? { label: options.label } : {}),
+        body: JSON.stringify(options),
     });
     const body = (await response.json());
     if (!response.ok)
@@ -128,7 +132,8 @@ export async function requestDeviceAuth(config, options) {
         userCode: authorize.userCode,
         expiresAt: authorize.expiresAt,
         interval: authorize.interval,
-        instructions: `Open ${authorize.approvalUrl} in a browser and approve it while signed in to Recess as the person this agent should act as — the session takes on THAT account's scope, so a guardian grants family-only access. Then run \`recess auth poll\`.`,
+        sessionDuration: options.sessionDuration ?? "12h",
+        instructions: `Open ${authorize.approvalUrl} in a browser and approve it while signed in to Recess ${options.sessionDuration === "30d" ? "as an admin to authorize 30 days of access" : "as the person this agent should act as"} — the session takes on THAT account's scope, so a guardian grants family-only access. Then run \`recess auth poll\`.`,
     };
 }
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

package/dist/cli.js

@@ -659,6 +659,44 @@ async function requirePreviewBoundConfirmation(parsed, preview, persistPreview =
     });
     return { operationKey: suppliedOperationKey, fingerprint: approvalToken };
 }
+/**
+ * A tutor template's `body` is the `## Subjects` block markdown (no `###`
+ * heading — the server renders that from `title` + `cadence`).
+ */
+async function readTutorTemplateBody(filePath) {
+    const absolutePath = path.resolve(filePath);
+    const contents = await fs.readFile(absolutePath, "utf8").catch(() => null);
+    if (contents === null) {
+        throw new CliError("invalid_arguments", `--body-file is not readable: ${absolutePath}`);
+    }
+    if (contents.trim().length === 0) {
+        throw new CliError("invalid_arguments", "--body-file is empty.");
+    }
+    return contents;
+}
+/**
+ * Every `*.md` in the directory becomes one `lessons[name]` entry, referenced
+ * from a module line as `lesson:<slug>/<name>`.
+ */
+async function readTutorTemplateLessons(directory) {
+    const absolutePath = path.resolve(directory);
+    const entries = await fs
+        .readdir(absolutePath, { withFileTypes: true })
+        .catch(() => null);
+    if (entries === null) {
+        throw new CliError("invalid_arguments", `--lessons-dir is not a readable directory: ${absolutePath}`);
+    }
+    const lessons = {};
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+        if (!entry.isFile() || !entry.name.toLowerCase().endsWith(".md"))
+            continue;
+        lessons[entry.name] = await fs.readFile(path.join(absolutePath, entry.name), "utf8");
+    }
+    if (Object.keys(lessons).length === 0) {
+        throw new CliError("invalid_arguments", `--lessons-dir contains no .md files: ${absolutePath}`);
+    }
+    return lessons;
+}
 async function previewBoundWrite(parsed, preview, execute, persistPreview = false) {
     const context = await requirePreviewBoundConfirmation(parsed, preview, persistPreview);
     try {
@@ -848,6 +886,9 @@ async function readGoalWorkspaceWriteSource(parsed) {
             const entries = await fs.readdir(directory, { withFileTypes: true });
             entries.sort((a, b) => a.name.localeCompare(b.name));
             for (const entry of entries) {
+                // Git metadata is local checkout state, including worktree .git files.
+                if (entry.name === ".git")
+                    continue;
                 const relativePath = relativeRoot
                     ? path.join(relativeRoot, entry.name)
                     : entry.name;
@@ -1916,6 +1957,10 @@ export async function executeRecessCommand(argv, options = {}) {
         };
     }
     if (noun === "auth") {
+        const duration = flagString(parsed, "duration");
+        if (duration !== undefined && duration !== "12h" && duration !== "30d") {
+            throw new CliError("invalid_arguments", "--duration must be 12h or 30d (admins only).");
+        }
         if (verb === "login") {
             const oauthClientId = flagString(parsed, "client-id") ?? config.oauthClientId;
             const callbackPort = flagNumber(parsed, "callback-port") ?? 8765;
@@ -1924,11 +1969,15 @@ export async function executeRecessCommand(argv, options = {}) {
                 callbackPort > 65535) {
                 throw new CliError("invalid_arguments", "--callback-port must be an integer from 1024 through 65535.");
             }
-            return login(config, { callbackPort, oauthClientId });
+            return login(config, {
+                callbackPort,
+                oauthClientId,
+                sessionDuration: duration,
+            });
         }
         if (verb === "request") {
             const label = flagString(parsed, "label");
-            return requestDeviceAuth(config, label ? { label } : {});
+            return requestDeviceAuth(config, { label, sessionDuration: duration });
         }
         if (verb === "poll") {
             const timeoutSeconds = flagNumber(parsed, "timeout") ?? 300;
@@ -2973,6 +3022,9 @@ export async function executeRecessCommand(argv, options = {}) {
                         ...(userId ? { userId } : {}),
                         ...(id ? { id } : {}),
                         limit,
+                        ...(hasFlag(parsed, "include-archived")
+                            ? { includeArchived: "true" }
+                            : {}),
                         ...(flagString(parsed, "cursor")
                             ? { cursor: flagString(parsed, "cursor") }
                             : {}),
@@ -2980,6 +3032,53 @@ export async function executeRecessCommand(argv, options = {}) {
                 },
             }));
         }
+        if ((area === "recipients" &&
+            ["archive", "unarchive", "remove-schedule", "add-schedule"].includes(action)) ||
+            (area === "payruns" && action === "remove-account")) {
+            const accountId = area === "payruns"
+                ? flagString(parsed, "recipient", { required: true })
+                : positional(parsed, 3, "account ID");
+            const payRunId = area === "payruns" ? positional(parsed, 3, "payrun ID") : undefined;
+            const scheduleId = action.endsWith("schedule")
+                ? flagString(parsed, "schedule", { required: true })
+                : undefined;
+            const account = unwrap(await api.client.GET("/admin/payout/recipient/", {
+                params: { query: { id: accountId, includeArchived: "true" } },
+            })).recipients[0];
+            const effects = action === "archive"
+                ? "Archive payout account, end all schedules and cancel all draft/review invoices. Stops new Recess accruals; preserves payment history and the guide login."
+                : action === "unarchive"
+                    ? "Unarchive payout account. Does not restore schedules or canceled invoices; add a schedule separately to resume payroll."
+                    : action === "remove-schedule"
+                        ? "Remove account from recurring schedule and cancel its draft/review invoices for that schedule. Other schedules and payment history are preserved."
+                        : action === "add-schedule"
+                            ? "Add active payout account to recurring schedule. Future payroll cycles will accrue compensation in Recess."
+                            : "Remove account from this payroll cycle and cancel its draft/review invoices. Future cycles are unchanged; regeneration will not re-add this account.";
+            return writeCommand(parsed, {
+                action: effects,
+                target: {
+                    accountId,
+                    ...(payRunId ? { payRunId } : {}),
+                    ...(scheduleId ? { scheduleId } : {}),
+                },
+                request: { action },
+                details: { accountName: account.name, user: account.user },
+            }, async () => {
+                if (action === "archive")
+                    return unwrap(await api.client.DELETE("/admin/payout/recipient/{accountId}", {
+                        params: { path: { accountId } },
+                    }));
+                if (action === "unarchive")
+                    return unwrap(await api.client.POST("/admin/payout/recipient/{accountId}/unarchive", { params: { path: { accountId } } }));
+                if (action === "add-schedule")
+                    return unwrap(await api.client.POST("/admin/payout/payrun/add-account/", {
+                        body: { accountId, scheduleId: scheduleId },
+                    }));
+                if (action === "remove-schedule")
+                    return unwrap(await api.client.DELETE("/admin/payout/schedule/{targetId}/recipient/{accountId}", { params: { path: { accountId, targetId: scheduleId } } }));
+                return unwrap(await api.client.DELETE("/admin/payout/cycle/{targetId}/recipient/{accountId}", { params: { path: { accountId, targetId: payRunId } } }));
+            });
+        }
         if (area === "invoices" && action === "list") {
             const payRunId = flagString(parsed, "payrun");
             const accountId = flagString(parsed, "recipient");
@@ -4307,6 +4406,65 @@ export async function executeRecessCommand(argv, options = {}) {
                             .includes(query))),
             };
         }
+        // Moves ONE kid's lesson, not the template's. The daily queue serves
+        // modules by `ordinal ASC`, so pushing the one a kid is stuck on past the
+        // rest is what hands them the next lesson tomorrow — no template version,
+        // no retiring the work they have already done, nobody else's goal touched.
+        if (verb === "move-module") {
+            const moduleRef = positional(parsed, 2, "module ref (e.g. Q006)");
+            const studentId = flagString(parsed, "student", { required: true });
+            const goalId = flagString(parsed, "goal", { required: true });
+            const toEnd = hasFlag(parsed, "to-end");
+            const position = flagNumber(parsed, "position");
+            if (toEnd === (position !== undefined)) {
+                throw new CliError("invalid_arguments", "Pass exactly one of --to-end or --position <n>.");
+            }
+            const goal = unwrap(await api.client.GET("/tutor/browser/students/{userId}/goals/", {
+                params: { path: { userId: studentId } },
+            })).goals.find((candidate) => candidate.id === goalId);
+            const modules = goal?.osV2?.modules ?? [];
+            const target = modules.find((module) => module.moduleRef.toLocaleLowerCase() === moduleRef.toLocaleLowerCase());
+            if (!target) {
+                throw new CliError("not_found", `Module ${moduleRef} was not found on goal ${goalId}. Known refs: ${modules.map((m) => m.moduleRef).join(", ") || "none"}.`);
+            }
+            // Sparse past the current maximum, so no sibling has to be renumbered.
+            const last = modules.reduce((max, m) => Math.max(max, m.ordinal), 0);
+            const ordinal = toEnd ? last + 1 : position;
+            if (ordinal === target.ordinal) {
+                throw new CliError("already_positioned", `Module ${target.moduleRef} ("${target.title}") is already at position ${ordinal}.`);
+            }
+            const collision = modules.find((m) => m.id !== target.id && m.ordinal === ordinal);
+            const preview = {
+                action: toEnd
+                    ? "move a lesson to the end of this kid's curriculum"
+                    : "move a lesson to a specific position in this kid's curriculum",
+                target: {
+                    studentUserId: studentId,
+                    goalId,
+                    goalTitle: goal?.title ?? null,
+                    moduleRef: target.moduleRef,
+                    title: target.title,
+                    from: target.ordinal,
+                    to: ordinal,
+                    completed: target.completedAt !== null,
+                },
+                request: { moduleId: target.id, ordinal },
+                details: {
+                    note: "Affects only this student's copy of the curriculum — the goal template and every other kid on it are untouched. Completion state is preserved: an unfinished lesson stays unfinished and is simply served later.",
+                    ...(collision
+                        ? {
+                            warning: `Position ${ordinal} is already held by ${collision.moduleRef} ("${collision.title}"). Both will sit at the same position and the queue will order them by creation date — pass --to-end instead if you just want this one out of the way.`,
+                        }
+                        : {}),
+                },
+            };
+            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.PATCH("/tutor/students/{studentId}/goals/{goalId}/modules/{moduleId}", {
+                params: {
+                    path: { studentId, goalId, moduleId: target.id },
+                },
+                body: { ordinal },
+            })));
+        }
         if (verb === "create") {
             const requestedStudentId = flagString(parsed, "student");
             const sourceDirectory = flagString(parsed, "source-dir");
@@ -4654,7 +4812,7 @@ export async function executeRecessCommand(argv, options = {}) {
             }
             throw new CliError("invalid_arguments", "Use goals queue get|set.");
         }
-        throw new CliError("invalid_arguments", "Use goals list|create|edit|delete|restore|archive|unarchive|complete|undo-completion|queue|files|pdf.");
+        throw new CliError("invalid_arguments", "Use goals list|create|edit|delete|restore|archive|unarchive|complete|undo-completion|move-module|queue|files|pdf.");
     }
     if (noun === "chat-logs") {
         return runChatLogsCommand({ parsed, api, writeCommand });
@@ -5081,6 +5239,156 @@ export async function executeRecessCommand(argv, options = {}) {
         }
         throw new CliError("invalid_arguments", "Use rocky get|set.");
     }
+    if (noun === "tutor-templates") {
+        if (verb === "list") {
+            const grade = flagNumber(parsed, "grade");
+            return unwrap(await api.client.GET("/tutor-templates/", {
+                params: {
+                    query: {
+                        q: flagString(parsed, "q"),
+                        subject: flagString(parsed, "subject"),
+                        ...(grade === undefined ? {} : { grade }),
+                    },
+                },
+            }));
+        }
+        if (verb === "get") {
+            const slug = positional(parsed, 2, "template slug");
+            return unwrap(await api.client.GET("/tutor-templates/{slug}", {
+                params: { path: { slug } },
+            }));
+        }
+        if (verb === "assign" || verb === "unassign") {
+            const slug = positional(parsed, 2, "template slug");
+            const studentId = flagString(parsed, "student");
+            const body = studentId ? { studentId } : {};
+            const template = unwrap(await api.client.GET("/tutor-templates/{slug}", {
+                params: { path: { slug } },
+            }));
+            return writeCommand(parsed, {
+                action: verb === "assign"
+                    ? "add a tutor template's subject block to a kid's plan"
+                    : "remove a tutor template's subject block from a kid's plan",
+                target: { slug, studentUserId: studentId ?? "the signed-in kid" },
+                request: body,
+                details: {
+                    title: template.title,
+                    cadence: template.cadence,
+                    consequence: verb === "assign"
+                        ? "Appends `### <title> — <cadence>` to rocky-v3/plan.md, rebuilds Today, and writes an ACTIVE assignment row."
+                        : "Deletes that subject block from rocky-v3/plan.md and marks the assignment REMOVED.",
+                },
+            }, async () => verb === "assign"
+                ? unwrap(await api.client.POST("/tutor-templates/{slug}/assign", {
+                    params: { path: { slug } },
+                    body,
+                }))
+                : unwrap(await api.client.POST("/tutor-templates/{slug}/unassign", {
+                    params: { path: { slug } },
+                    body,
+                })));
+        }
+        if (verb === "create" || verb === "update") {
+            const bodyFile = flagString(parsed, "body-file", {
+                required: verb === "create",
+            });
+            const lessonsDir = flagString(parsed, "lessons-dir");
+            const visibility = flagString(parsed, "visibility");
+            const emoji = flagString(parsed, "emoji");
+            const gradeMin = flagNumber(parsed, "grade-min");
+            const gradeMax = flagNumber(parsed, "grade-max");
+            const shared = {
+                ...(flagString(parsed, "title") === undefined
+                    ? {}
+                    : { title: flagString(parsed, "title") }),
+                ...(flagString(parsed, "summary") === undefined
+                    ? {}
+                    : { summary: flagString(parsed, "summary") }),
+                ...(flagString(parsed, "subject") === undefined
+                    ? {}
+                    : { subject: flagString(parsed, "subject") }),
+                ...(flagString(parsed, "cadence") === undefined
+                    ? {}
+                    : { cadence: flagString(parsed, "cadence") }),
+                ...(emoji === undefined ? {} : { emoji }),
+                ...(gradeMin === undefined ? {} : { gradeMin }),
+                ...(gradeMax === undefined ? {} : { gradeMax }),
+                ...(visibility === undefined
+                    ? {}
+                    : {
+                        visibility: assertChoice(visibility, ["PUBLIC", "STAFF"], "--visibility"),
+                    }),
+                ...(bodyFile === undefined
+                    ? {}
+                    : { body: await readTutorTemplateBody(bodyFile) }),
+                ...(lessonsDir === undefined
+                    ? {}
+                    : { lessons: await readTutorTemplateLessons(lessonsDir) }),
+            };
+            if (verb === "create") {
+                const missing = ["title", "summary", "subject", "cadence"].filter((name) => !(name in shared));
+                if (missing.length > 0) {
+                    throw new CliError("invalid_arguments", `tutor-templates create requires ${missing
+                        .map((name) => `--${name}`)
+                        .join(", ")}.`);
+                }
+                const slug = flagString(parsed, "slug", { required: true });
+                const body = { slug, ...shared };
+                return writeCommand(parsed, {
+                    action: "create a tutor template in the subject catalog",
+                    target: { slug },
+                    request: {
+                        ...body,
+                        bodyFile: bodyFile ? path.resolve(bodyFile) : null,
+                        lessonsDir: lessonsDir ? path.resolve(lessonsDir) : null,
+                    },
+                    details: {
+                        lessonNames: Object.keys(shared.lessons ?? {}),
+                        renamingNote: "`title` is the `### <heading>` join key in every kid's plan.md — renaming later orphans existing plans.",
+                    },
+                }, async () => unwrap(await api.client.POST("/tutor-templates/", { body })));
+            }
+            const slug = positional(parsed, 2, "template slug");
+            const body = shared;
+            if (Object.keys(body).length === 0) {
+                throw new CliError("invalid_arguments", "tutor-templates update needs at least one field to change.");
+            }
+            return writeCommand(parsed, {
+                action: "update a tutor template in the subject catalog",
+                target: { slug },
+                request: {
+                    ...body,
+                    bodyFile: bodyFile ? path.resolve(bodyFile) : null,
+                    lessonsDir: lessonsDir ? path.resolve(lessonsDir) : null,
+                },
+                details: {
+                    fields: Object.keys(body),
+                    renamingNote: "Changing `title` orphans the `### <heading>` in every plan.md already carrying this template.",
+                },
+            }, async () => unwrap(await api.client.PATCH("/tutor-templates/{slug}", {
+                params: { path: { slug } },
+                body,
+            })));
+        }
+        if (verb === "delete") {
+            const slug = positional(parsed, 2, "template slug");
+            const template = unwrap(await api.client.GET("/tutor-templates/{slug}", {
+                params: { path: { slug } },
+            }));
+            return writeCommand(parsed, {
+                action: "soft-delete a tutor template from the subject catalog",
+                target: { slug },
+                request: {},
+                details: {
+                    title: template.title,
+                    consequence: "The row is soft-deleted; subject blocks already written into kids' plan.md stay where they are.",
+                },
+            }, async () => unwrap(await api.client.DELETE("/tutor-templates/{slug}", {
+                params: { path: { slug } },
+            })));
+        }
+        throw new CliError("invalid_arguments", "Use tutor-templates list|get|create|update|delete|assign|unassign.");
+    }
     if (noun === "goals" && verb === "pdf") {
         const action = positional(parsed, 2, "goals pdf action");
         if (action !== "upload") {
@@ -5351,7 +5659,15 @@ export async function executeRecessCommand(argv, options = {}) {
                     content: change.content,
                     contentEncoding: change.contentEncoding,
                 });
+            const assignedEdits = hasFlag(parsed, "allow-assigned-edits")
+                ? { allowAssignedEdits: true }
+                : {};
+            const stateModification = hasFlag(parsed, "allow-state-modification")
+                ? { allowStateModification: true }
+                : {};
             const body = {
+                ...stateModification,
+                ...assignedEdits,
                 studentUserId: checkout.metadata.studentId,
                 target: checkout.metadata.target,
                 message,
@@ -5367,6 +5683,8 @@ export async function executeRecessCommand(argv, options = {}) {
                 throw new CliError("unexpected_response", "Goal workspace push did not return a preview; nothing was written.");
             }
             const request = {
+                ...stateModification,
+                ...assignedEdits,
                 sourceDirectory: checkout.root,
                 mesaBaseChangeId,
                 localBaseCommit,
@@ -5392,6 +5710,8 @@ export async function executeRecessCommand(argv, options = {}) {
                 target: boundTarget ?? preflight.target,
                 request,
                 details: {
+                    stateModificationPaths: preflight.stateModificationPaths ?? [],
+                    warnings: preflight.warnings ?? [],
                     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.",
@@ -5436,7 +5756,15 @@ export async function executeRecessCommand(argv, options = {}) {
                 : { kind: "draft", draftSlug: draftSlug };
             const message = flagString(parsed, "message") ??
                 `recess-cli: write ${input.files.length} workspace file${input.files.length === 1 ? "" : "s"}`;
+            const assignedEdits = hasFlag(parsed, "allow-assigned-edits")
+                ? { allowAssignedEdits: true }
+                : {};
+            const stateModification = hasFlag(parsed, "allow-state-modification")
+                ? { allowStateModification: true }
+                : {};
             const body = {
+                ...stateModification,
+                ...assignedEdits,
                 studentUserId: studentId,
                 target,
                 message,
@@ -5446,6 +5774,8 @@ export async function executeRecessCommand(argv, options = {}) {
                 ? unwrap(await api.client.GET("/auth/admin-cli/session/"))
                 : null;
             const request = {
+                ...stateModification,
+                ...assignedEdits,
                 source: input.source,
                 sourceSha256: input.sha256,
                 fileCount: input.files.length,
@@ -5480,6 +5810,8 @@ export async function executeRecessCommand(argv, options = {}) {
                 target: boundTarget ?? preflight.target,
                 request,
                 details: {
+                    stateModificationPaths: preflight.stateModificationPaths ?? [],
+                    warnings: preflight.warnings ?? [],
                     currentChangeId: preflight.currentChangeId,
                     files: preflight.files,
                     resolvedTarget: preflight.target,

package/dist/command-schema.js

@@ -2,6 +2,8 @@ import { CliError } from "./errors.js";
 export const AGENT_CONTEXT_SCHEMA_VERSION = "4";
 const BOOLEAN_FLAGS = new Set([
     "allow-possible-duplicate",
+    "allow-state-modification",
+    "allow-assigned-edits",
     "all-references",
     "analyzed",
     "apply",
@@ -27,6 +29,7 @@ const BOOLEAN_FLAGS = new Set([
     "mirrored",
     "no-collision",
     "no-invite",
+    "open",
     "refresh",
     "resend",
     "restore",
@@ -139,6 +142,15 @@ const AUTHENTICATED_COMMAND_PREFIXES = [
     "village render",
 ];
 const FAMILY_AI_COMMANDS = new Set([
+    "apps assign",
+    "apps list",
+    "apps preview",
+    "apps publish",
+    "apps pull",
+    "apps scaffold",
+    "apps standards",
+    "apps status",
+    "apps validate",
     "chat-logs by-todo",
     "chat-logs get",
     "chat-logs list",
@@ -161,6 +173,7 @@ const FAMILY_AI_COMMANDS = new Set([
     "goals files read",
     "goals files write",
     "goals list",
+    "goals move-module",
     "goals pdf upload",
     "goals queue get",
     "goals queue set",
@@ -179,6 +192,10 @@ const FAMILY_AI_COMMANDS = new Set([
     "students xp-history",
     "todos create",
     "todos edit",
+    "tutor-templates assign",
+    "tutor-templates get",
+    "tutor-templates list",
+    "tutor-templates unassign",
 ]);
 const STAFF_COMMANDS = new Set([
     "cohorts schedule get",
@@ -191,15 +208,6 @@ const STAFF_COMMANDS = new Set([
     "memories history",
     "memories revision",
     "memories restore",
-    "apps assign",
-    "apps list",
-    "apps preview",
-    "apps publish",
-    "apps pull",
-    "apps scaffold",
-    "apps standards",
-    "apps status",
-    "apps validate",
     "cohorts email",
     "cohorts end",
     "cohorts get",
@@ -291,6 +299,9 @@ const STAFF_COMMANDS = new Set([
     "todos delete",
     "todos restore",
     "todos generate-applet",
+    "tutor-templates create",
+    "tutor-templates delete",
+    "tutor-templates update",
     "users get",
     "users tier list-tiers",
     "village events",

package/dist/commands/apps.js

@@ -358,13 +358,22 @@ async function submit(ctx, dir, dryRun) {
     const manifest = await readManifest(dir);
     const link = await readAppLink(dir);
     const name = flagString(ctx.parsed, "name") ?? manifest.title ?? path.basename(dir);
+    // --open ships the folder's frame as written: Studio skips the locked-scaffold check and the
+    // guide's own shell, styles and screens are what the kid gets. Plain apps already own every file.
+    const open = hasFlag(ctx.parsed, "open");
+    if (open && !manifest.template) {
+        throw new CliError("invalid_arguments", "--open is for template apps (manifest.template); a plain app already ships every file as written.");
+    }
+    const template = manifest.template
+        ? { ...manifest.template, ...(open ? { scaffold: false } : {}) }
+        : undefined;
     const body = {
         ...(link?.projectId ? { projectId: link.projectId } : {}),
         name,
         ...(manifest.description ? { description: manifest.description } : {}),
         files,
         contract,
-        ...(manifest.template ? { template: manifest.template } : {}),
+        ...(template ? { template } : {}),
         ...(manifest.primitives?.length ? { primitives: manifest.primitives } : {}),
         dryRun,
     };

package/dist/help.js

@@ -28,8 +28,8 @@ Usage:
   recess [--json] jobs prune [--older-than-days 30]
   recess [--json] feedback list [--limit 20]
   recess [--json] feedback submit <text> [--confirm]
-  recess [--json] auth login [--client-id ID] [--callback-port 8765]
-  recess [--json] auth request [--label TEXT]
+  recess [--json] auth login [--client-id ID] [--callback-port 8765] [--duration 12h|30d]
+  recess [--json] auth request [--label TEXT] [--duration 12h|30d]
   recess [--json] auth poll [--timeout 300]
   recess [--json] auth status|logout
   recess [--json] users search <name-or-id> [--limit 10]
@@ -78,8 +78,8 @@ Usage:
   recess [--json] apps standards <query>
   recess [--json] apps list
   recess [--json] apps pull <project-id> [dir]
-  recess [--json] apps validate [dir] [--name TEXT] [--no-wait]
-  recess [--json] apps publish [dir] [--name TEXT] [--assign <kid-id>] [--due YYYY-MM-DD] [--no-wait]
+  recess [--json] apps validate [dir] [--name TEXT] [--open] [--no-wait]
+  recess [--json] apps publish [dir] [--name TEXT] [--open] [--assign <kid-id>] [--due YYYY-MM-DD] [--no-wait]
   recess [--json] apps assign [dir] --student <kid-id> [--due YYYY-MM-DD]
   recess [--json] apps status <build-id>
   recess [--json] applications list [--status SUBMITTED|CLAIMED|ENROLLED|CLOSED]
@@ -130,10 +130,15 @@ Usage:
   recess [--json] billing cancel-subscription --subscription <id>
     [--immediate] [--reason TEXT] [--restore] [--confirm]
   recess [--json] payout payruns list [--status A,B] [--schedule <id>]
-  recess [--json] payout recipients list [--search <name>] [--user <id>] [--id <id>]
+  recess [--json] payout recipients list [--search <name>] [--user <id>] [--id <id>] [--include-archived]
     [--limit 20] [--cursor <id>]
   recess [--json] payout invoices list [--payrun <id>] [--recipient <account-id>]
     [--user <id>] [--status A,B]   (at least one filter)
+  recess [--json] payout recipients archive <account-id> [--confirm]
+  recess [--json] payout recipients unarchive <account-id> [--confirm]
+  recess [--json] payout recipients remove-schedule <account-id> --schedule <id> [--confirm]
+  recess [--json] payout recipients add-schedule <account-id> --schedule <id> [--confirm]
+  recess [--json] payout payruns remove-account <payrun-id> --recipient <account-id> [--confirm]
   recess [--json] payout invoices get <invoice-id>
   recess [--json] payout invoices set-status <invoice-id>
     --status IN_REVIEW|OPEN|PAID|CANCELED [--send-email] [--confirm]
@@ -405,6 +410,8 @@ Usage:
     [--confirm --approval-token TOKEN]
   recess [--json] goals unarchive <goal-id> --student <kid-id>
     [--confirm --approval-token TOKEN]
+  recess [--json] goals move-module <module-ref> --student <kid-id> --goal <goal-id>
+    (--to-end | --position <n>) [--confirm --approval-token TOKEN]
   recess [--json] goals queue get <goal-id> --student <kid-id>
   recess [--json] goals queue set <goal-id> --student <kid-id>
     --entries-file <path.json> --delta TEXT [--replace-description-pointer]
@@ -435,6 +442,19 @@ Usage:
   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] tutor-templates list [--q TEXT] [--subject TEXT] [--grade N]
+  recess [--json] tutor-templates get <slug>
+  recess [--json] tutor-templates assign <slug> [--student <kid-id>] [--confirm]
+  recess [--json] tutor-templates unassign <slug> [--student <kid-id>] [--confirm]
+  recess [--json] tutor-templates create --slug SLUG --title TEXT --summary TEXT
+    --subject TEXT --cadence TEXT --body-file <path.md> [--lessons-dir <dir>]
+    [--emoji TEXT] [--grade-min N] [--grade-max N]
+    [--visibility PUBLIC|STAFF] [--confirm]
+  recess [--json] tutor-templates update <slug> [--title TEXT] [--summary TEXT]
+    [--subject TEXT] [--cadence TEXT] [--body-file <path.md>]
+    [--lessons-dir <dir>] [--emoji TEXT] [--grade-min N] [--grade-max N]
+    [--visibility PUBLIC|STAFF] [--confirm]
+  recess [--json] tutor-templates delete <slug> [--confirm]
   recess [--json] goals files list --student <goal-owner-id> --goal <goal-id>
   recess [--json] goals files read --student <goal-owner-id> --goal <goal-id> --path P
   recess [--json] goals files init --student <goal-owner-id> --draft <draft-slug>
@@ -443,11 +463,13 @@ Usage:
     (--goal <goal-id> | --draft <draft-slug>)
     --output-dir <local-dir>
   recess [--json] goals files push --source-dir <local-checkout>
-    [--message TEXT] [--confirm --approval-token TOKEN]
+    [--message TEXT] [--allow-state-modification] [--allow-assigned-edits]
+    [--confirm --approval-token TOKEN]
   recess [--json] goals files write --student <goal-owner-id>
     (--goal <goal-id> | --draft <draft-slug>)
     (--source-dir <local-dir> | --source-file <local-file> --path P)
-    [--message TEXT] [--confirm --approval-token TOKEN]
+    [--message TEXT] [--allow-state-modification] [--allow-assigned-edits]
+    [--confirm --approval-token TOKEN]
   recess [--json] goals pdf upload --student <goal-owner-id>
     (--goal <goal-id> | --draft <draft-slug>) --source-file <local.pdf>
     [--path uploads/name.pdf] [--message TEXT]
@@ -459,6 +481,14 @@ bundled into this npm package. Load os-v2-goal-template-builder and its
 references/deterministic-workflow-setup.md BEFORE authoring a template; that is
 the same guidance the recess.gg/ai agent follows, so there is exactly one
 standard. Responses cache under ~/.recess-cli/skills-cache/ (--refresh re-fetches).
+Goal file writes/pushes warn and refuse curriculum edits with unfinished assignments
+unless --allow-assigned-edits is supplied. This can change lessons while a student
+is working; assignments are not retired/completed and student answers are not merged.
+The flag requires a fresh preview and confirmation; revision checks still apply.
+Goal file writes/pushes require --allow-state-modification to modify state or
+student-work folders, or replace/delete an existing resources/artifacts file.
+Review the protected paths in the warning; the flag does not preserve answers
+automatically or bypass assignment/revision checks. Adding it needs a new preview.
 For goal workspace and PDF commands, --student names the goal owner. A
 full_admin session may use a KID or ADMIN user id, including its own ADMIN id;
 family_ai sessions remain limited to managed KID profiles.
@@ -551,7 +581,8 @@ cannot call /admin; KID sessions cannot call any non-Village API command. For a
 cloud agent that has no local browser to open, "auth request" prints an approval URL; whoever
 opens it and approves in a signed-in web session grants THEIR OWN scope, so a guardian approving
 mints a family-scoped session and only an admin can mint a full-admin one. "auth poll" then
-collects the 12h session. Kids cannot approve. When it lapses, run "auth request" again for a
+collects the session. Sessions default to 12h; admins can request 30 days with --duration 30d
+on either login or request. Only admins can approve 30-day requests. Kids cannot approve. When it lapses, run "auth request" again for a
 fresh link. Both paths yield the same session.
 
 Skill notes: this CLI's own agent skill ships inside the npm package AND is served

package/package.json

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

package/skill/recess-cli/SKILL.md

@@ -41,7 +41,8 @@ For machine-readable discovery filtered to the current session's locally decoded
 - Headless (no browser): `auth request`, then a human approves the printed URL while signed in to
   Recess, then `auth poll`. The session takes on the **approver's** scope — a guardian approving
   grants family-only access, not staff access. Kids cannot approve.
-- Sessions last 12 hours. `auth status` and `doctor` recheck the live user role and permissions;
+- Sessions default to 12 hours. Admins can use `auth login --duration 30d` locally or
+  `auth request --duration 30d` remotely; only an admin can approve a 30-day request. `auth status` and `doctor` recheck the live user role and permissions;
   discovery stays local and may reflect the minted scope until the next login.
 - `auth logout` clears the stored session.
 - The default API is production. If `RECESS_CLI_API_ORIGIN` is set, state the non-default origin before acting.
@@ -90,7 +91,7 @@ bundles/authorized URLs. `/mcp/legacy` temporarily retains `recess_exec({command
 
 ## Building Studio apps (`recess apps`)
 
-Guides build Recess Studio apps in their own editor and publish them with the CLI; Studio never
+Guides and guardians build Recess Studio apps in their own editor and publish them with the CLI; Studio never
 prompts a model for them.
 
 - `recess --json apps init <dir> --reason "..."` writes the locked scaffold plus `AGENTS.md` (the

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

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