recess-cli 2.4.0 → 2.5.0

package/README.md

@@ -22,6 +22,29 @@ recess setup --reason "Install and update the Recess agent skill"
 
 Publishing rides the production deploy (`.github/workflows/admin-cli-publish.yml`): bump `version` in `apps/admin-cli/package.json` in a normal PR to `staging`, and it publishes when `staging` promotes to `production`. A production deploy that did not bump the version is a no-op — a `gate` job checks the version against npm first. The same workflow is still dispatchable by hand for out-of-band releases. pnpm packs the CLI so the workspace `catalog:` dependency becomes a real range; npm then publishes that tarball through the workflow's OIDC trusted-publishing path. The registry-side publisher must be configured as described in `docs/codebase/admin-cli.md`.
 
+## Building Studio apps with your agent
+
+```bash
+recess apps init my-applet --reason "New applet"      # scaffold + AGENTS.md (the contract your agent follows)
+# build it in your editor with Claude Code / Codex / Cursor, then:
+recess --json apps validate my-applet --reason "Check it"   # Studio's validation, nothing published
+recess --json apps publish my-applet --reason "Ship it"     # validation + independent review → live at appUrl
+recess --json apps list --reason "See my apps"
+recess apps pull <project-id> my-applet --reason "Keep editing"
+```
+
+Guides and staff only. The app folder keeps its project id in `.recess/app.json`, so publishing again updates the same app.
+
+For a specific kid, start from their session instead of a blank description:
+
+```bash
+recess --json students todos --student <kid-id> --analyzed --reason "What did they struggle with"
+recess --json students analysis --todo <todo-id> --reason "Read the analysis"
+recess apps init fix-it --for-todo <todo-id> --reason "Build for this gap"   # scaffold + brief.md
+recess --json apps publish fix-it --assign <kid-id> --due 2026-09-01 --reason "Ship it to the kid"
+recess --json apps standards "grade 4 adding fractions" --reason "Find the code"
+```
+
 ## Install (from a checkout — CLI development)
 
 From the monolith root:

package/dist/args.js

@@ -30,6 +30,7 @@ const BOOLEAN_FLAGS = new Set([
     "skill-only",
     "spec-only",
     "starter-only",
+    "unlink",
     "visual-only",
     "version",
     "wait",

package/dist/cli.js

@@ -8,8 +8,10 @@ import { login, pollDeviceAuth, requestDeviceAuth } from "./auth.js";
 import { clearStoredSession, deleteProfile, listProfiles, resolveConfig, saveProfile, useProfile, } from "./config.js";
 import { agentContext, buildCommandSchema, scopedHelp, validateInvocation, } from "./command-schema.js";
 import { runApplicationsCommand } from "./commands/applications.js";
+import { runAppsCommand } from "./commands/apps.js";
 import { runOnboardingCommand } from "./commands/onboarding.js";
 import { runSchoolCommand } from "./commands/school.js";
+import { runVillageEventsCommand } from "./commands/village-events.js";
 import { assertChoice, flagIdList, positional, readJsonFile, readJsonValue, } from "./commands/shared.js";
 import { CliError } from "./errors.js";
 import { listFeedback, submitFeedback } from "./feedback.js";
@@ -869,6 +871,10 @@ const SCHOOL_TIER_OPTIONS = [
     { id: "platform", name: "Platform Only", defaultClassSlots: 0 },
 ];
 const SCHOOL_TIER_IDS = SCHOOL_TIER_OPTIONS.map((tier) => tier.id);
+// Roles `users restore` may hand back. ADMIN and MODERATOR are absent on
+// purpose — a CLI session must never be able to mint staff; promotion has its
+// own paths. The server's POST /admin/users/change-role/ enforces the same set.
+const RESTORABLE_ROLES = ["KID", "GUARDIAN", "GUIDE", "PROGRAM"];
 const MAX_MAP_PDF_BYTES = 15 * 1024 * 1024;
 const GOAL_TEMPLATE_KINDS = ["SIMPLE", "BLUEPRINT"];
 const GOAL_TEMPLATE_SETUP_AUDIENCES = ["KID_FRIENDLY", "PARENT_SETUP"];
@@ -1960,8 +1966,11 @@ export async function runCommand(argv) {
             }
             throw new CliError("invalid_arguments", "Use village worlds export|import|promote.");
         }
+        if (verb === "events" || verb === "link-event") {
+            return runVillageEventsCommand({ parsed, api, writeCommand }, verb);
+        }
         if (verb !== "models") {
-            throw new CliError("invalid_arguments", "Use village build …, village library …, village objects …, village worlds …, village models …, or village render …");
+            throw new CliError("invalid_arguments", "Use village build …, village library …, village objects …, village worlds …, village models …, village events, village link-event …, or village render …");
         }
         const action = positional(parsed, 2, "Village model action");
         if (action === "list") {
@@ -2259,6 +2268,140 @@ export async function runCommand(argv) {
             params: { path: { userId } },
         }));
     }
+    if (noun === "users" && (verb === "lock" || verb === "unlock")) {
+        const userId = positional(parsed, 2, "user ID");
+        const locking = verb === "lock";
+        const profile = unwrap(await api.client.GET("/admin/users/{userId}", {
+            params: { path: { userId } },
+        }));
+        const target = profile.user;
+        // Mirrors the recess.gg/ai admin Lock/Unlock buttons exactly: a KID is
+        // locked together with its GUARDIANs (an unlocked kid under a locked
+        // guardian is not actually unlocked), anyone else is treated as the
+        // guardian side alone.
+        const guardians = (target.family?.users ?? []).filter((member) => member.role === "GUARDIAN");
+        const kidIds = target.role === "KID" ? [target.id] : [];
+        const guardianIds = target.role === "KID"
+            ? guardians.map((member) => member.id)
+            : [target.id];
+        const isUnlocked = (attributes) => (attributes ?? []).some((attribute) => attribute.attribute === "FLAG_ACCOUNT_UNLOCKED");
+        const describe = (member) => ({
+            id: member.id,
+            name: [member.firstName, member.lastName].filter(Boolean).join(" "),
+            role: member.role,
+            unlockedNow: isUnlocked(member.attributes),
+        });
+        const affected = [
+            ...(target.role === "KID" ? [describe(target)] : []),
+            ...(target.role === "KID" ? guardians.map(describe) : [describe(target)]),
+        ];
+        const preview = {
+            userId: target.id,
+            name: [target.firstName, target.lastName].filter(Boolean).join(" "),
+            role: target.role,
+            familyId: target.familyId,
+            accountUnlockedNow: target.role === "KID"
+                ? isUnlocked(target.attributes) &&
+                    guardians.every((member) => isUnlocked(member.attributes))
+                : isUnlocked(target.attributes),
+            accountUnlockedAfter: !locking,
+            kidIds,
+            guardianIds,
+            affected,
+        };
+        if (target.role === "KID" && guardianIds.length === 0) {
+            throw new CliError("invalid_arguments", `${preview.name || target.id} has no GUARDIAN in their family, so ${verb}ing the kid alone would leave the account in a mixed state. Resolve the family's guardians first.`, 1, { preview });
+        }
+        const body = { kidIds, guardianIds };
+        return writeCommand(parsed, {
+            action: locking
+                ? "lock the account: revoke the kid and guardian access roles, drop the kid from their Recess channels, and clear FLAG_ACCOUNT_UNLOCKED"
+                : "unlock the account: grant the kid and guardian access roles, restore the kid's Recess channel memberships, and set FLAG_ACCOUNT_UNLOCKED (the kid's clients are notified live)",
+            target: { userId: target.id, kidIds, guardianIds },
+            request: body,
+            details: preview,
+        }, async () => unwrap(await api.client.POST(locking ? "/admin/users/lock/" : "/admin/users/unlock/", { body })));
+    }
+    if (noun === "users" && (verb === "disable" || verb === "restore")) {
+        const userId = positional(parsed, 2, "user ID");
+        const disabling = verb === "disable";
+        // Restoring is one person at a time on purpose: DISABLED does not record
+        // what the account used to be, so the caller must name the role. --family
+        // would have to guess one per member.
+        const wholeFamily = disabling && hasFlag(parsed, "whole-family");
+        const role = disabling
+            ? "DISABLED"
+            : assertChoice(flagString(parsed, "role", { required: true }).toUpperCase(), RESTORABLE_ROLES, "--role");
+        // Server-resolved preflight (admin-cli.md C3): who else is in the family,
+        // who is already DISABLED, and who still has billable enrollments. It reads
+        // through findUnique, so it also resolves an already-disabled target — that
+        // is what makes a rerun (and every restore) previewable.
+        const state = unwrap(await api.client.GET("/admin/users/{userId}/role-preflight/", {
+            params: { path: { userId } },
+        }));
+        const describe = (member) => ({
+            id: member.id,
+            name: [member.firstName, member.lastName].filter(Boolean).join(" "),
+            role: member.role,
+            email: member.email,
+            billableEnrollments: member.billableEnrollments,
+            // Informational: a role change does NOT revoke these. Stripping access
+            // roles is what `users lock` does — run it alongside a disable when the
+            // account should also lose its grants.
+            accessRoles: member.accessRoles,
+        });
+        const candidates = wholeFamily ? state.members : [state.target];
+        const skipped = [];
+        const acting = [];
+        for (const member of candidates) {
+            const entry = describe(member);
+            if (member.id === state.actorId) {
+                skipped.push({ ...entry, reason: "this is your own account" });
+                continue;
+            }
+            if (member.role === "ADMIN" || member.role === "MODERATOR") {
+                skipped.push({
+                    ...entry,
+                    reason: `${member.role} accounts are never role-changed from the CLI`,
+                });
+                continue;
+            }
+            if (disabling && member.disabled) {
+                skipped.push({ ...entry, reason: "already DISABLED" });
+                continue;
+            }
+            if (!disabling && !member.disabled) {
+                skipped.push({ ...entry, reason: `already ${member.role}` });
+                continue;
+            }
+            acting.push(entry);
+        }
+        const preview = {
+            userId,
+            family: state.family,
+            role,
+            [disabling ? "disabling" : "restoring"]: acting,
+            skipped,
+        };
+        if (acting.length === 0) {
+            throw new CliError("no_op", `Nothing to ${verb}: every candidate was skipped. See preview.skipped for why.`, 1, { preview });
+        }
+        const billing = acting.filter((member) => member.billableEnrollments > 0);
+        if (disabling && billing.length > 0 && !hasFlag(parsed, "allow-billing")) {
+            throw new CliError("billable_enrollments", `${billing
+                .map((member) => `${member.name} (${member.billableEnrollments})`)
+                .join(", ")} still hold ACTIVE or PAST_DUE enrollments. Cancel billing first, or rerun with --allow-billing to orphan those paid seats deliberately.`, 1, { preview });
+        }
+        const body = { userIds: acting.map((member) => member.id), role };
+        return writeCommand(parsed, {
+            action: disabling
+                ? `disable ${acting.length} account(s): set User.role to DISABLED, which hides them from every dashboard, search, chat, and todo query, and purges their coherent-feed personal data. Soft and reversible via users restore — this is NOT a GDPR erasure`
+                : `restore ${acting.length} account(s) from DISABLED to ${role}`,
+            target: { userId, userIds: body.userIds, family: state.family },
+            request: body,
+            details: preview,
+        }, async () => unwrap(await api.client.POST("/admin/users/change-role/", { body })));
+    }
     if (noun === "guides" && verb === "create") {
         const email = flagString(parsed, "email", { required: true })
             .trim()
@@ -2395,6 +2538,9 @@ export async function runCommand(argv) {
     if (noun === "applications" || noun === "quotes") {
         return runApplicationsCommand({ parsed, api, writeCommand });
     }
+    if (noun === "apps") {
+        return runAppsCommand({ parsed, api, writeCommand });
+    }
     if (noun === "school") {
         return runSchoolCommand({ parsed, api, writeCommand });
     }
@@ -4101,6 +4247,25 @@ export async function runCommand(argv) {
                 },
             }));
         }
+        if (verb === "todos") {
+            const studentId = flagString(parsed, "student", { required: true });
+            const limit = flagNumber(parsed, "limit");
+            return unwrap(await api.client.GET("/studio/students/{studentId}/todos", {
+                params: {
+                    path: { studentId },
+                    query: {
+                        ...(limit === undefined ? {} : { limit }),
+                        ...(hasFlag(parsed, "analyzed") ? { analyzed: true } : {}),
+                    },
+                },
+            }));
+        }
+        if (verb === "analysis") {
+            const todoId = flagString(parsed, "todo", { required: true });
+            return unwrap(await api.client.GET("/studio/todos/{todoId}/analysis", {
+                params: { path: { todoId } },
+            }));
+        }
         if (verb === "xp-history") {
             const kidId = flagString(parsed, "student", { required: true });
             const range = flagString(parsed, "range");
@@ -4114,7 +4279,7 @@ export async function runCommand(argv) {
                 },
             }));
         }
-        throw new CliError("invalid_arguments", "Use students list|today|schedule|xp-history|upload-map-scores.");
+        throw new CliError("invalid_arguments", "Use students list|today|schedule|todos|analysis|xp-history|upload-map-scores.");
     }
     if (noun === "todos") {
         if (verb === "create") {
@@ -4142,6 +4307,7 @@ export async function runCommand(argv) {
             const todoId = positional(parsed, 2, "todo ID");
             const patchFile = flagString(parsed, "patch-file", { required: true });
             const body = (await readJsonFile(patchFile, "Todo patch file"));
+            const sessionRole = await resolveSessionRole(api);
             const current = unwrap(await api.client.GET("/tutor/browser/todos/{id}/", {
                 params: { path: { id: todoId } },
             }));
@@ -4154,11 +4320,23 @@ export async function runCommand(argv) {
                     expectedUpdatedAt: current.updatedAt,
                     patch: body,
                 },
+                details: sessionRole === "ADMIN"
+                    ? {
+                        writeRoute: "/admin/todos/{id} (staff route; supports the full typed todo patch)",
+                    }
+                    : {
+                        writeRoute: "/tutor/browser/todos/{id} (family-scoped field allowlist)",
+                    },
             };
-            return previewBoundWrite(parsed, preview, async () => unwrap(await api.client.PATCH("/tutor/browser/todos/{id}", {
-                params: { path: { id: todoId } },
-                body,
-            })));
+            return previewBoundWrite(parsed, preview, async () => sessionRole === "ADMIN"
+                ? unwrap(await api.client.PATCH("/admin/todos/{id}", {
+                    params: { path: { id: todoId } },
+                    body: body,
+                }))
+                : unwrap(await api.client.PATCH("/tutor/browser/todos/{id}", {
+                    params: { path: { id: todoId } },
+                    body,
+                })));
         }
         if (verb === "complete") {
             const todoId = positional(parsed, 2, "todo ID");
@@ -4201,7 +4379,6 @@ export async function runCommand(argv) {
                 },
                 request: body,
                 details: {
-                    currentXpReward: current.xpReward,
                     alreadyAwardedXp: completionXpAwarded,
                     targetTotalXp: targetXp,
                     newlyAwardedXp: newXp,

package/dist/command-schema.js

@@ -2,7 +2,9 @@ import { CliError } from "./errors.js";
 export const AGENT_CONTEXT_SCHEMA_VERSION = "4";
 const BOOLEAN_FLAGS = new Set([
     "all-references",
+    "analyzed",
     "apply",
+    "allow-billing",
     "allow-strand",
     "archived",
     "cancel-subscriptions",
@@ -11,6 +13,8 @@ const BOOLEAN_FLAGS = new Set([
     "confirm-destructive-changes",
     "disable-applet-follow-ups",
     "dry-run",
+    "force",
+    "no-wait",
     "enable-applet-follow-ups",
     "full",
     "help",
@@ -30,7 +34,9 @@ const BOOLEAN_FLAGS = new Set([
     "spec-only",
     "starter-only",
     "supersede",
+    "unlink",
     "visual-only",
+    "whole-family",
     "wait",
 ]);
 const REPEATABLE_FLAGS = new Set(["kid", "unassign"]);
@@ -142,6 +148,7 @@ const STAFF_COMMANDS = new Set([
     "onboarding ixl-preview",
     "onboarding kids",
     "onboarding lifecycle-prompts",
+    "onboarding link-math-academy",
     "onboarding mark-reviewed",
     "onboarding next",
     "onboarding orientation-attendance",
@@ -195,6 +202,8 @@ const STAFF_COMMANDS = new Set([
     "todos generate-applet",
     "users get",
     "users tier list-tiers",
+    "village events",
+    "village link-event",
 ]);
 /**
  * Classify the command itself, not the target passed to it. Target-level
@@ -307,8 +316,13 @@ function positionalBounds(usage) {
     const rest = usage.replace(/^recess\s+(?:\[--json\]\s+)?/, "");
     const tokens = rest.split(/\s+/);
     let count = 0;
+    let optional = 0;
     let variadic = false;
     for (const token of tokens) {
+        if (/^\[[a-z][a-z0-9-]*\]$/.test(token)) {
+            optional += 1;
+            continue;
+        }
         if (token.startsWith("--") ||
             token.startsWith("[") ||
             token.startsWith("(")) {
@@ -318,7 +332,7 @@ function positionalBounds(usage) {
         if (/^<[^,>]+\.\.\.>$/.test(token))
             variadic = true;
     }
-    return { min: count, max: variadic ? null : count };
+    return { min: count, max: variadic ? null : count + optional };
 }
 export function buildCommandSchema(help) {
     return usageBlocks(help).flatMap((usage) => {

package/dist/commands/apps.js

@@ -0,0 +1,413 @@
+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 { positional } from "./shared.js";
+const PROJECT_FILE = ".recess/app.json";
+const CONTRACT_FILE = "contract.json";
+const MANIFEST_FILE = "manifest.json";
+const BRIEF_FILE = "brief.md";
+const SKIP_DIRS = new Set([".recess", ".git", "node_modules"]);
+const MAX_FILE_BYTES = 512 * 1024;
+const TERMINAL = new Set(["COMPLETE", "FAILED", "REJECTED"]);
+async function readAppLink(dir) {
+    try {
+        const raw = await fs.readFile(path.join(dir, PROJECT_FILE), "utf8");
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function writeAppLink(dir, link) {
+    await fs.mkdir(path.join(dir, ".recess"), { recursive: true });
+    await fs.writeFile(path.join(dir, PROJECT_FILE), JSON.stringify(link, null, 2) + "\n");
+}
+/** Every text file under dir (relative, forward-slash paths); the CLI's own state stays out. */
+async function collectFiles(dir) {
+    const files = {};
+    async function walk(current, prefix) {
+        const entries = await fs.readdir(current, { withFileTypes: true });
+        for (const entry of entries) {
+            if (SKIP_DIRS.has(entry.name))
+                continue;
+            const full = path.join(current, entry.name);
+            const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                await walk(full, rel);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const stat = await fs.stat(full);
+            if (stat.size > MAX_FILE_BYTES) {
+                throw new CliError("invalid_arguments", `${rel} is larger than ${MAX_FILE_BYTES / 1024} KB; Studio apps are small text files.`);
+            }
+            files[rel] = await fs.readFile(full, "utf8");
+        }
+    }
+    await walk(dir, "");
+    if (!files["index.html"]) {
+        throw new CliError("invalid_arguments", `${dir} has no index.html. Run \`recess apps init\` first, or point --dir at the app.`);
+    }
+    return files;
+}
+async function writeFiles(dir, files) {
+    let count = 0;
+    for (const [rel, content] of Object.entries(files)) {
+        if (rel.includes("..") || path.isAbsolute(rel))
+            continue;
+        const full = path.join(dir, rel);
+        await fs.mkdir(path.dirname(full), { recursive: true });
+        await fs.writeFile(full, content);
+        count += 1;
+    }
+    return count;
+}
+function resolveDir(ctx, positionalIndex) {
+    const flag = flagString(ctx.parsed, "dir");
+    const fromPositional = ctx.parsed.positionals[positionalIndex];
+    return path.resolve(flag ?? fromPositional ?? ".");
+}
+async function readContract(dir) {
+    const raw = await fs
+        .readFile(path.join(dir, CONTRACT_FILE), "utf8")
+        .catch(() => null);
+    if (!raw) {
+        throw new CliError("invalid_arguments", `${CONTRACT_FILE} is missing. Your agent writes the BuildContract there (see AGENTS.md in the app folder).`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new CliError("invalid_arguments", `${CONTRACT_FILE} is not valid JSON.`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new CliError("invalid_arguments", `${CONTRACT_FILE} must be a JSON object (the BuildContract).`);
+    }
+    return parsed;
+}
+async function readManifest(dir) {
+    const raw = await fs
+        .readFile(path.join(dir, MANIFEST_FILE), "utf8")
+        .catch(() => null);
+    if (!raw)
+        return {};
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new CliError("invalid_arguments", `${MANIFEST_FILE} is not valid JSON.`);
+    }
+}
+function slug(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 48);
+}
+function briefFor(data) {
+    const { todo, analysis } = data;
+    const misconceptions = analysis.patterns.map((p) => p.instanceKey ?? slug(p.name));
+    const lines = [
+        "# Build brief — remediation for a kid's todo",
+        "",
+        `Source todo: "${todo.title}" (${todo.id})${todo.completedAt ? `, completed ${todo.completedAt.slice(0, 10)}` : ""}`,
+        ...(todo.description ? [`Todo description: ${todo.description}`] : []),
+        ...(data.standards.length
+            ? [
+                "",
+                "## Standard(s)",
+                ...data.standards.map((s) => `- ${s.notation} — ${s.description}`),
+            ]
+            : [
+                "",
+                "## Standard(s)",
+                "- none mapped; pick one with `recess apps standards <words>`",
+            ]),
+        ...(data.gradeBand ? ["", `Grade band: ${data.gradeBand}`] : []),
+        ...(data.interests.length
+            ? [`Interests: ${data.interests.join(", ")}`]
+            : []),
+        "",
+        "## What went wrong (forensic analysis of the session)",
+        "",
+        ...(analysis.overallPerformance
+            ? [`Overall: ${analysis.overallPerformance}`, ""]
+            : []),
+        ...(analysis.rootCause ? [`Root cause: ${analysis.rootCause}`, ""] : []),
+        ...(analysis.summary ? [`Summary: ${analysis.summary}`, ""] : []),
+        "### Patterns",
+        ...(analysis.patterns.length
+            ? analysis.patterns.flatMap((p) => [
+                `- **${p.name}**${p.instanceKey ? ` (\`${p.instanceKey}\`)` : ""}: ${p.issue}`,
+                `  ${p.analysis}`,
+                ...(p.behavioralGap
+                    ? [
+                        `  Observed: ${p.behavioralGap.observed}`,
+                        `  Expected: ${p.behavioralGap.expected}`,
+                    ]
+                    : []),
+            ])
+            : ["- none recorded"]),
+        "",
+        "### Prescriptions",
+        ...(analysis.prescriptions.length
+            ? analysis.prescriptions.map((p) => `- ${p.type}: ${p.recommendation}`)
+            : ["- none recorded"]),
+        "",
+        "## Build against this",
+        "",
+        "- Mode: remediate. The app exists to close the gap above — every practice item must be one the kid",
+        "  would get wrong by the observed behaviour, and the fork must confront observed vs expected.",
+        `- In manifest.json declare template.misconceptions as ${JSON.stringify(misconceptions)} (match the`,
+        "  keys above; add more only if the model teaches them) and template.ccss as the standard.",
+        "- Theme items with the interests listed; never use the kid's name or anything from the session.",
+        "- The kid must never learn this app exists because of a mistake: no 'last time', 'you got',",
+        "  'let's fix your'. The confront intro shows a stranger's attempt ('Someone tried this'); the",
+        "  title and every line read like any other practice.",
+        "- Follow AGENTS.md for everything else (contract, no reveals, one reading per step).",
+        "",
+    ];
+    return lines.join("\n");
+}
+function agentsGuide(docs) {
+    return [
+        "# Building this Recess app",
+        "",
+        "If a brief.md sits next to this file, it is the assignment: build for that kid's gap first —",
+        "but the kid never hears about the gap: no copy that refers to their past work or a mistake.",
+        "",
+        "This folder is a Recess Studio app on the locked scaffold. Edit ONLY: skill.js, model.js,",
+        "model.css, params.schema.json, params.json. Never touch index.html, styles.css, shell.js,",
+        "widgets.js, engine.js, key.js — a modified locked file fails validation.",
+        "",
+        "Before publishing, write two files at the root:",
+        "- contract.json — the BuildContract described below (copy the shape in the template contract).",
+        '- manifest.json — { "title": "...", "description": "...", "template": { "ccss": "5.NF.A.1", "modes": ["prepare","remediate"], "misconceptions": ["..."] } }',
+        "",
+        'Then: `recess apps validate --reason "..."` (reports without publishing) and',
+        '`recess apps publish --reason "..."` (validation + independent review; on pass the app is live).',
+        "",
+        "---",
+        "",
+        docs.runtime ?? "",
+        "",
+        "---",
+        "",
+        docs.template ?? "",
+        "",
+        "---",
+        "",
+        docs.pedagogy ? `# Pedagogy\n\n${docs.pedagogy}` : "",
+        "",
+        "---",
+        "",
+        docs.design ? `# Design\n\n${docs.design}` : "",
+        "",
+    ].join("\n");
+}
+async function pollBuild(ctx, buildId, timeoutMs) {
+    const started = Date.now();
+    let delay = 3_000;
+    for (;;) {
+        const status = unwrap(await ctx.api.client.GET("/studio/builds/{buildId}", {
+            params: { path: { buildId } },
+        }));
+        if (TERMINAL.has(status.status))
+            return status;
+        if (Date.now() - started > timeoutMs) {
+            throw new CliError("timeout", `Build ${buildId} is still ${status.status} after ${Math.round(timeoutMs / 1000)}s; check later with \`recess apps status ${buildId}\`.`);
+        }
+        await new Promise((r) => setTimeout(r, delay));
+        delay = Math.min(delay * 1.5, 15_000);
+    }
+}
+async function submit(ctx, dir, dryRun) {
+    const files = await collectFiles(dir);
+    const contract = await readContract(dir);
+    const manifest = await readManifest(dir);
+    const link = await readAppLink(dir);
+    const name = flagString(ctx.parsed, "name") ?? manifest.title ?? path.basename(dir);
+    const body = {
+        ...(link?.projectId ? { projectId: link.projectId } : {}),
+        name,
+        ...(manifest.description ? { description: manifest.description } : {}),
+        files,
+        contract,
+        ...(manifest.template ? { template: manifest.template } : {}),
+        dryRun,
+    };
+    const assignTo = flagString(ctx.parsed, "assign");
+    const due = flagString(ctx.parsed, "due");
+    if (assignTo && dryRun) {
+        throw new CliError("invalid_arguments", "--assign publishes; use `recess apps publish --assign <student-id>`.");
+    }
+    if (due && !/^\d{4}-\d{2}-\d{2}$/.test(due)) {
+        throw new CliError("invalid_arguments", "--due must be YYYY-MM-DD.");
+    }
+    const created = unwrap(await ctx.api.client.POST("/studio/imports", { body }));
+    await writeAppLink(dir, {
+        ...link,
+        projectId: created.projectId,
+        appUrl: created.appUrl,
+    });
+    const wait = !hasFlag(ctx.parsed, "no-wait");
+    if (!wait) {
+        if (assignTo) {
+            throw new CliError("invalid_arguments", "--assign needs the build result; drop --no-wait.");
+        }
+        return { ...created, dryRun };
+    }
+    const status = await pollBuild(ctx, created.buildId, 30 * 60 * 1000);
+    const result = {
+        projectId: created.projectId,
+        buildId: created.buildId,
+        appUrl: created.appUrl,
+        dryRun,
+        status: status.status,
+        report: status.report ?? null,
+        error: status.error ?? null,
+    };
+    if (!assignTo)
+        return result;
+    if (status.status !== "COMPLETE") {
+        return {
+            ...result,
+            assigned: null,
+            assignError: `Not assigned: the build ended ${status.status}. Fix the report and publish again.`,
+        };
+    }
+    const assigned = await assign(ctx, created.projectId, {
+        studentId: assignTo,
+        ...(due ? { dueDate: due } : {}),
+        ...(link?.forTodoId ? { sourceTodoId: link.forTodoId } : {}),
+    });
+    return { ...result, assigned };
+}
+async function assign(ctx, projectId, body) {
+    return unwrap(await ctx.api.client.POST("/studio/projects/{projectId}/assign", {
+        params: { path: { projectId } },
+        body,
+    }));
+}
+export async function runAppsCommand(ctx) {
+    const { parsed, api } = ctx;
+    const verb = parsed.positionals[1];
+    if (verb === "init") {
+        const dir = path.resolve(positional(parsed, 2, "app folder"));
+        await fs.mkdir(dir, { recursive: true });
+        const existing = await fs.readdir(dir);
+        if (existing.length > 0 && !hasFlag(parsed, "force")) {
+            throw new CliError("invalid_arguments", `${dir} is not empty. Use --force to write the scaffold over it.`);
+        }
+        const forTodo = flagString(parsed, "for-todo");
+        const analysis = forTodo
+            ? unwrap(await api.client.GET("/studio/todos/{todoId}/analysis", {
+                params: { path: { todoId: forTodo } },
+            }))
+            : null;
+        const scaffold = unwrap(await api.client.GET("/studio/scaffold"));
+        const written = await writeFiles(dir, scaffold.files);
+        await fs.writeFile(path.join(dir, "AGENTS.md"), agentsGuide(scaffold.docs));
+        if (analysis) {
+            await fs.writeFile(path.join(dir, BRIEF_FILE), briefFor(analysis));
+            await writeAppLink(dir, {
+                forTodoId: analysis.todo.id,
+                studentId: analysis.todo.studentId,
+            });
+        }
+        return {
+            dir,
+            filesWritten: written + (analysis ? 2 : 1),
+            ...(analysis
+                ? {
+                    brief: BRIEF_FILE,
+                    studentId: analysis.todo.studentId,
+                    standards: analysis.standards.map((s) => s.notation),
+                    misconceptions: analysis.analysis.patterns.map((p) => p.instanceKey ?? slug(p.name)),
+                }
+                : {}),
+            next: [
+                `cd ${dir}`,
+                analysis
+                    ? "Open the folder with your agent: brief.md is the assignment, AGENTS.md the contract."
+                    : "Open the folder with your agent and describe what the app should teach (AGENTS.md has the contract).",
+                'recess apps validate --reason "Check my app"',
+                analysis
+                    ? `recess apps publish --assign ${analysis.todo.studentId} --reason "Ship it to the kid"`
+                    : 'recess apps publish --reason "Ship my app"',
+            ],
+        };
+    }
+    if (verb === "standards") {
+        const q = parsed.positionals.slice(2).join(" ").trim();
+        if (!q) {
+            throw new CliError("invalid_arguments", 'Give words or a notation: recess apps standards "grade 4 adding fractions".');
+        }
+        return unwrap(await api.client.GET("/studio/standards", {
+            params: { query: { q } },
+        }));
+    }
+    if (verb === "assign") {
+        const dir = resolveDir(ctx, 2);
+        const link = await readAppLink(dir);
+        const studentId = flagString(parsed, "student") ?? link?.studentId;
+        if (!link?.projectId) {
+            throw new CliError("invalid_arguments", `${dir} has no published app yet; run \`recess apps publish\` first.`);
+        }
+        if (!studentId) {
+            throw new CliError("invalid_arguments", "--student <student-id> is required (or init the app with --for-todo).");
+        }
+        const due = flagString(parsed, "due");
+        if (due && !/^\d{4}-\d{2}-\d{2}$/.test(due)) {
+            throw new CliError("invalid_arguments", "--due must be YYYY-MM-DD.");
+        }
+        return assign(ctx, link.projectId, {
+            studentId,
+            ...(due ? { dueDate: due } : {}),
+            ...(link.forTodoId ? { sourceTodoId: link.forTodoId } : {}),
+        });
+    }
+    if (verb === "list") {
+        return unwrap(await api.client.GET("/studio/projects"));
+    }
+    if (verb === "pull") {
+        const projectId = positional(parsed, 2, "project id");
+        const dir = resolveDir(ctx, 3);
+        const project = unwrap(await api.client.GET("/studio/projects/{projectId}/files", {
+            params: { path: { projectId } },
+        }));
+        await fs.mkdir(dir, { recursive: true });
+        const written = await writeFiles(dir, project.files);
+        if (project.contract)
+            await fs.writeFile(path.join(dir, CONTRACT_FILE), JSON.stringify(project.contract, null, 2) + "\n");
+        await fs.writeFile(path.join(dir, MANIFEST_FILE), JSON.stringify({ title: project.name }, null, 2) + "\n");
+        await writeAppLink(dir, { projectId });
+        return {
+            dir,
+            projectId,
+            name: project.name,
+            versionNumber: project.versionNumber,
+            filesWritten: written,
+        };
+    }
+    if (verb === "validate") {
+        return submit(ctx, resolveDir(ctx, 2), true);
+    }
+    if (verb === "publish") {
+        return submit(ctx, resolveDir(ctx, 2), false);
+    }
+    if (verb === "status") {
+        const buildId = positional(parsed, 2, "build id");
+        return unwrap(await api.client.GET("/studio/builds/{buildId}", {
+            params: { path: { buildId } },
+        }));
+    }
+    throw new CliError("invalid_arguments", "Unknown apps command. Use: apps init <dir> [--for-todo <todo-id>] | apps standards <words> | apps list | apps pull <project-id> [dir] | apps validate [dir] | apps publish [dir] [--assign <student-id>] | apps assign [dir] --student <id> | apps status <build-id>.");
+}
+//# sourceMappingURL=apps.js.map

package/dist/commands/onboarding.js

@@ -503,6 +503,21 @@ export async function runOnboardingCommand({ parsed, api, writeCommand, }) {
                 request: {},
             }, async () => unwrap(await api.client.POST("/admin/onboarding/families/{familyId}/intake/generate-summaries", { params: { path: { familyId } } })));
         }
+        if (verb === "link-math-academy") {
+            const familyId = positional(parsed, 2, "family ID");
+            const kidUserId = flagString(parsed, "kid", { required: true });
+            const mathAcademyStudentId = flagInteger(parsed, "student-id", {
+                min: 1,
+            });
+            const body = mathAcademyStudentId === undefined ? {} : { mathAcademyStudentId };
+            return writeCommand(parsed, {
+                action: mathAcademyStudentId === undefined
+                    ? "link the kid to an existing Math Academy account using the saved login or a unique name match"
+                    : `link the kid to existing Math Academy student ${mathAcademyStudentId} after verifying that student exists`,
+                target: { familyId, kidUserId },
+                request: body,
+            }, async () => unwrap(await api.client.POST("/admin/onboarding/families/{familyId}/kids/{kidUserId}/link/math-academy", { params: { path: { familyId, kidUserId } }, body })));
+        }
         if (verb === "provision-math-academy") {
             const familyId = positional(parsed, 2, "family ID");
             const kidUserId = flagString(parsed, "kid", { required: true });

package/dist/commands/village-events.js

@@ -0,0 +1,150 @@
+import { unwrap } from "../api.js";
+import { flagString, hasFlag } from "../args.js";
+import { apiError, CliError } from "../errors.js";
+const NONE = "—";
+async function fetchTemplatesAndRooms(ctx) {
+    const [templatesResponse, rooms] = await Promise.all([
+        ctx.api.client.GET("/recess/event-templates-editable/"),
+        ctx.api.client.GET("/recess/village-rooms/"),
+    ]);
+    return {
+        templates: unwrap(templatesResponse).eventTemplates,
+        rooms: unwrap(rooms),
+    };
+}
+function schedule(template) {
+    if (template.singleEventDate)
+        return template.singleEventDate.slice(0, 10);
+    return template.rrule || NONE;
+}
+function renderColumns(rows) {
+    const widths = rows[0].map((_, column) => Math.max(...rows.map((row) => row[column].length)));
+    return rows
+        .map((row) => row
+        .map((cell, column) => column === row.length - 1 ? cell : cell.padEnd(widths[column]))
+        .join("  ")
+        .trimEnd())
+        .join("\n");
+}
+/** `village events` — every editable Recess Hour template and its Town Center zone. */
+async function listEvents(ctx) {
+    const { templates, rooms } = await fetchTemplatesAndRooms(ctx);
+    const roomsById = new Map(rooms.map((room) => [room.id, room]));
+    const templateRows = templates.map((template) => {
+        const room = template.villageRoomId
+            ? roomsById.get(template.villageRoomId)
+            : undefined;
+        return {
+            id: template.id,
+            name: template.name,
+            status: template.status,
+            schedule: schedule(template),
+            villageRoomId: template.villageRoomId,
+            villageRoomName: room?.name ?? null,
+            joinUrl: template.joinUrl ?? null,
+        };
+    });
+    const unlinkedRooms = rooms
+        .filter((room) => !room.linkedTemplateId)
+        .map((room) => ({ id: room.id, name: room.name }));
+    if (hasFlag(ctx.parsed, "json")) {
+        return { templates: templateRows, unlinkedRooms };
+    }
+    const table = renderColumns([
+        ["TEMPLATE", "NAME", "STATUS", "SCHEDULE", "ZONE", "ZONE NAME", "URL"],
+        ...templateRows.map((row) => [
+            row.id,
+            row.name,
+            row.status,
+            row.schedule,
+            row.villageRoomId ?? NONE,
+            row.villageRoomName ?? (row.villageRoomId ? "(unknown zone)" : NONE),
+            row.joinUrl ?? NONE,
+        ]),
+    ]);
+    const unlinked = unlinkedRooms.length === 0
+        ? "  (none)"
+        : renderColumns(unlinkedRooms.map((room) => [`  ${room.id}`, room.name]));
+    return {
+        help: `${templates.length === 0 ? "No editable event templates." : table}\n\nUnlinked Town Center zones:\n${unlinked}`,
+    };
+}
+function isHttpUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === "http:" || url.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+/** `village link-event --template <id> (--room <zoneId> | --unlink) [--url <https://…>]` */
+async function linkEvent(ctx) {
+    const { parsed, api, writeCommand } = ctx;
+    const templateId = flagString(parsed, "template", { required: true });
+    const roomId = flagString(parsed, "room");
+    const unlink = hasFlag(parsed, "unlink");
+    const url = flagString(parsed, "url");
+    if (url !== undefined && !isHttpUrl(url)) {
+        throw new CliError("invalid_arguments", "--url must be an http(s) URL (e.g. https://example.com/event).");
+    }
+    if (unlink === Boolean(roomId)) {
+        throw new CliError("invalid_arguments", "Pass exactly one of --room <zoneId> or --unlink.");
+    }
+    const { templates, rooms } = await fetchTemplatesAndRooms(ctx);
+    const template = templates.find((row) => row.id === templateId);
+    if (!template) {
+        throw new CliError("not_found", `No editable event template found for ${templateId}. Run \`recess village events\` to list them.`);
+    }
+    let room;
+    if (roomId) {
+        room = rooms.find((row) => row.id === roomId);
+        if (!room) {
+            throw new CliError("not_found", `No Village Town Center zone found for ${roomId}. Run \`recess village events\` to list linkable zones.`);
+        }
+        if (room.linkedTemplateId && room.linkedTemplateId !== templateId) {
+            throw new CliError("invalid_arguments", `Zone ${room.id} (${room.name}) is already linked to template ${room.linkedTemplateId} (${room.linkedTemplateName ?? "unnamed"}). Unlink that template first.`);
+        }
+    }
+    const previousRoom = template.villageRoomId
+        ? rooms.find((row) => row.id === template.villageRoomId)
+        : undefined;
+    const body = {
+        villageRoomId: room ? room.id : null,
+        ...(url !== undefined ? { joinUrl: url } : {}),
+    };
+    return writeCommand(parsed, {
+        action: room
+            ? `Link template ${template.id} (${template.name}) → zone ${room.id} (${room.name}); zone will be renamed to the event title${url ? ` and its link set to ${url}` : ""}`
+            : `Unlink template ${template.id} (${template.name}) from zone ${template.villageRoomId ?? NONE}${previousRoom ? ` (${previousRoom.name})` : ""}`,
+        target: {
+            templateId: template.id,
+            templateName: template.name,
+            currentVillageRoomId: template.villageRoomId,
+        },
+        request: body,
+    }, async () => {
+        const result = await api.client.PATCH("/recess/event-templates/{id}/", {
+            params: { path: { id: template.id } },
+            body,
+        });
+        if (!result.response.ok) {
+            throw apiError(result.response.status, result.error);
+        }
+        return {
+            templateId: template.id,
+            templateName: template.name,
+            villageRoomId: body.villageRoomId,
+            villageRoomName: room?.name ?? null,
+            ...(url !== undefined ? { joinUrl: url } : {}),
+        };
+    });
+}
+export async function runVillageEventsCommand(ctx, verb) {
+    if (verb === "events")
+        return listEvents(ctx);
+    if (verb === "link-event")
+        return linkEvent(ctx);
+    throw new CliError("invalid_arguments", "Use village events or link-event.");
+}
+//# sourceMappingURL=village-events.js.map

package/dist/help.js

@@ -22,6 +22,10 @@ Usage:
   recess [--json] auth status|logout
   recess [--json] users search <name-or-id> [--limit 10]
   recess [--json] users get <user-id>
+  recess [--json] users lock <user-id> [--confirm]
+  recess [--json] users unlock <user-id> [--confirm]
+  recess [--json] users disable <user-id> [--whole-family] [--allow-billing] [--confirm]
+  recess [--json] users restore <user-id> --role kid|guardian|guide|program [--confirm]
   recess [--json] users tier list-tiers
   recess [--json] users tier get <kid-id>
   recess [--json] users tier preview <kid-id> --tier social|academics|lite|complete|platform
@@ -38,6 +42,8 @@ Usage:
   recess [--json] students list
   recess [--json] students today --student <kid-id> [--date YYYY-MM-DD]
   recess [--json] students schedule --student <kid-id> [--days 14]
+  recess [--json] students todos --student <kid-id> [--limit 30] [--analyzed]
+  recess [--json] students analysis --todo <todo-id>
   recess [--json] students xp-history --student <kid-id>
     [--range week|month|quarter|year]
   recess [--json] enrollments list --user <user-id>
@@ -48,6 +54,14 @@ Usage:
   recess [--json] invoices refund --invoice <id> --line-item <id>
     --method refund|credit|tokens [--full | --amount-cents N]
     [--who-pays guide|recess] [--reason TEXT] [--confirm]
+  recess [--json] apps init <dir> [--for-todo <todo-id>] [--force]
+  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 assign [dir] --student <kid-id> [--due YYYY-MM-DD]
+  recess [--json] apps status <build-id>
   recess [--json] applications list [--status SUBMITTED|CLAIMED|ENROLLED|CLOSED]
     [--status-scope active|closed] [--disposition READY_TO_ENROLL|TRIAL|PENDING_FUNDING|NO]
     [--dispositioned true|false] [--quality QUALIFIED|NEEDS_NURTURE|UNKNOWN]
@@ -168,6 +182,8 @@ Usage:
   recess [--json] onboarding generate-summaries <family-id> [--confirm]
   recess [--json] onboarding provision-math-academy <family-id>
     --kid <kid-id> [--grade 1..12] [--confirm]
+  recess [--json] onboarding link-math-academy <family-id>
+    --kid <kid-id> [--student-id <math-academy-student-id>] [--confirm]
   recess [--json] onboarding provision-ixl <family-id>
     --kid <kid-id> [--credentials-file <credentials.json>] [--confirm]
   recess [--json] onboarding remove-ixl <family-id> --kid <kid-id> [--confirm]
@@ -270,6 +286,9 @@ Usage:
   recess [--json] village worlds export <world-id> [--out <bundle.json>] [--confirm]
   recess [--json] village worlds import <world-id> --file <bundle.json> [--confirm]
   recess [--json] village worlds promote <mirror-or-archive-id> [--confirm]
+  recess [--json] village events
+  recess [--json] village link-event --template <template-id>
+    [--room <zone-id>] [--unlink] [--url <https://…>] [--confirm]
   recess [--json] store-items list [--search TEXT]
     [--status ACTIVE|INACTIVE|COMING_SOON] [--item-type TYPE]
     [--page 0] [--limit 20] [--sort-by name|price|createdAt|updatedAt|order]
@@ -415,6 +434,33 @@ monthly top-up cron and are exact-ADMIN on update); descriptive edits
 (name/slug/logo) are ordinary staff writes. "school kid-slots" is the raw
 slot override; "users tier set" is the tier-driven path.
 
+"users lock"/"users unlock" are the CLI twin of the Lock/Unlock buttons on
+recess.gg/ai/students/<kid-id>/admin. They act on the whole account, not one
+person: a KID target is locked or unlocked together with every GUARDIAN in
+their family, because an unlocked kid under a locked guardian is not actually
+unlocked. Unlock grants the kid and guardian access roles, restores the kid's
+Recess channel memberships, sets FLAG_ACCOUNT_UNLOCKED, and notifies the kid's
+live clients; lock is the exact inverse. Rerunning "unlock" on an already
+unlocked account is the "Refresh Unlock" button and is safe. The preview shows
+each affected person's current flag; "users get" is the read.
+
+"users disable" is the harder stop, and a different mechanism: it sets
+User.role to DISABLED, so the account stops resolving in every dashboard,
+search, chat, and todo query at the database layer, and its coherent-feed
+personal data is purged. "users lock" only strips access roles. Disabling is
+SOFT and reversible — "users restore <id> --role ..." puts the account back —
+and it is NOT a GDPR erasure; nothing is deleted. A read-only preflight resolves
+the whole family (including members already DISABLED, which ordinary reads hide)
+and each person's billable enrollments. "--whole-family" extends the disable to
+every member of the target's family; ADMIN/MODERATOR members, your own account,
+and anyone already in the destination role are listed under preview.skipped
+rather than silently dropped. A target holding an ACTIVE or PAST_DUE enrollment
+is refused until billing is cancelled or "--allow-billing" deliberately orphans
+the seat. Restore names the role explicitly because DISABLED does not record
+what the account was; ADMIN and MODERATOR are not restorable from the CLI.
+Note that after a disable "users get" and "users search" no longer resolve the
+account — the confirmed write's own response is the record of what changed.
+
 Onboarding notes: "status" and "intake-session" are reads — "intake-session"
 looks up the current IN_PROGRESS session without creating one (prints a "none
 yet" result when absent). "intake-session-create" is the explicit write that

package/package.json

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

package/skill/recess-cli/SKILL.md

@@ -70,6 +70,42 @@ Every write is two-step:
 
 Any changed target, payload, local file, server revision, amount, recipient, or consequence requires a new preview and new approval. Never infer approval from the original request. If a confirmed invocation is interrupted, retry the unchanged command with the same operation key; never mint a new one for an uncertain write. Inspect recovery state with `recess --json jobs get <operation-key>`.
 
+## Building Studio apps (`recess apps`)
+
+Guides 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
+  runtime + template contract, pedagogy, and design rules). Read `AGENTS.md` before editing.
+- Edit only `skill.js`, `model.js`, `model.css`, `params.schema.json`, `params.json`. Locked files
+  fail validation if changed.
+- Write `contract.json` (the BuildContract from `AGENTS.md`) and `manifest.json`
+  (`{title, description, template?}`) before validating.
+- `recess --json apps validate [dir] --reason "..."` runs Studio's deterministic validation on the
+  uploaded files and returns `report.failReasons`; fix every reason and rerun. Nothing is published.
+- `recess --json apps publish [dir] --reason "..."` validates, then the independent reviewer judges
+  the app; on pass it becomes the current version at `appUrl`. `REJECTED` carries the reviewer's
+  findings — fix them and publish again. Both commands wait for the result (`--no-wait` to return the
+  build id and poll with `apps status`).
+- `recess --json apps pull <project-id> [dir]` downloads a project you own to keep editing it.
+- `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.
+
+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:
+
+- `recess --json students todos --student <kid-id> [--analyzed]` lists the kid's recent todos with
+  CCSS tags and `analyzed` (a forensic analysis exists); `recess --json students analysis --todo <id>`
+  returns it pruned for building — patterns with `instanceKey`, root cause, prescriptions, the
+  standard, grade band, interests. No name, no frames.
+- `recess --json apps init <dir> --for-todo <todo-id>` writes the scaffold plus `brief.md` (that
+  analysis as an assignment) and remembers the kid. Build to the brief: remediate mode, items the
+  kid would miss the observed way, `template.misconceptions` = the pattern keys.
+- `recess --json apps publish --assign <kid-id> [--due YYYY-MM-DD]` publishes and, on `COMPLETE`,
+  creates the kid's todo (linked to the source todo when init used `--for-todo`). A rejected build
+  assigns nothing. `recess --json apps assign [dir] --student <kid-id>` assigns an already-published
+  app.
+
 ## Shared constraints
 
 - Use high-level CLI commands. The raw escape hatch is GET-only: