recess-cli 1.0.1 → 1.2.0

package/dist/cli.js

@@ -7,10 +7,13 @@ import { login, pollDeviceAuth, requestDeviceAuth } from "./auth.js";
 import { clearStoredSession, resolveConfig, } from "./config.js";
 import { CliError } from "./errors.js";
 import { requireConfirmation } from "./safety.js";
-import { installSkill, isEphemeralInstall } from "./setup.js";
+import { installSkill, isEphemeralInstall, readBundledSkillVersion, readCliVersion, } from "./setup.js";
+import { compareVersions, updateSkillFromServer } from "./skill-update.js";
+import { readSkillCache, writeSkillCache } from "./skills-cache.js";
 export const HELP = `recess — safe Recess administration from the command line
 
 Usage:
+  recess [--json] --version
   recess [--json] setup [--skill-only]
   recess [--json] doctor
   recess [--json] auth login [--client-id ID] [--callback-port 8765]
@@ -107,6 +110,49 @@ Usage:
   recess [--json] village models remove <placement-id> [--world village-1] [--confirm]
   recess [--json] village render --min-x N --min-z N --max-x N --max-z N
     [--world village-1]
+  recess [--json] skills list [--query TEXT] [--category TEXT]
+  recess [--json] skills get <skill-name> [--reference NAME | --all-references]
+    [--refresh]
+  recess [--json] goal-templates list [--query TEXT] [--category TEXT]
+    [--kind SIMPLE|BLUEPRINT] [--starter-only] [--include-deleted]
+  recess [--json] goal-templates get <template-id|slug> [--spec-only]
+  recess [--json] goal-templates versions <template-id> [--version N]
+  recess [--json] goal-templates validate-spec --file <path/template.json>
+  recess [--json] goal-templates create --file <path/template.json> [--confirm]
+  recess [--json] goal-templates patch-spec <template-id|slug> --expected-version N
+    --patches-file <path/patches.json> [--confirm]
+    [--confirm-destructive-changes --destructive-change-token TOKEN]
+  recess [--json] goal-templates set-metadata <template-id> --expected-version N
+    [--title TEXT] [--description TEXT] [--emoji X] [--category TEXT] [--tags A,B]
+    [--sort-order N] [--kind SIMPLE|BLUEPRINT] [--agent-instructions-file <path>]
+    [--confirm]
+  recess [--json] goal-templates delete <template-id> --expected-version N [--confirm]
+  recess [--json] goal-templates snapshot-files <template-id> [--path P]
+  recess [--json] goal-templates apply <template-id> --answers-file <path>
+    [--dry-run] [--confirm]
+  recess [--json] goal-templates apply-starter <template-id> --student <kid-id>
+    [--answers-file <path>] [--confirm]
+  recess [--json] goals list --student <kid-id>
+  recess [--json] goals create --student <kid-id> --title TEXT
+    (--description TEXT | --description-file <path>) [--target-date <iso>]
+    [--schedule TEXT] [--confirm]
+  recess [--json] mesa files list --student <kid-id> --goal <goal-id>
+  recess [--json] mesa files read --student <kid-id> --goal <goal-id> --path P
+
+Authoring notes: "skills" serves the in-product tutor skills (the PRIVATE
+packages/skills submodule) read-only over your admin session — they are never
+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).
+Every template created here is setupMode DETERMINISTIC_WORKFLOW and CANNOT be
+converted back, so "validate-spec" against the same file until it passes, then
+"create". "create" runs a real server-side validation before its gate, so the
+preview shows the handler/goalShape/step keys the SERVER resolved. "apply" runs
+the backend's own dryRun before the gate and previews the per-student outcome.
+"set-metadata" and "delete" require --expected-version (from "get"); a stale one
+409s STALE_WRITE and writes nothing. The spec is unreachable from "set-metadata"
+by design — an existing spec is edited only through the guarded /ai patch path.
 
 Onboarding notes: "status" and "intake-session" are reads — "intake-session"
 looks up the current IN_PROGRESS session without creating one (prints a "none
@@ -136,6 +182,13 @@ cloud agent, "auth request" prints an approval URL to hand a Recess admin; after
 approve it in a browser, "auth poll" collects the 12h session. When it lapses, run
 "auth request" again for a fresh link. Both paths yield the same session.
 
+Skill notes: this CLI's own agent skill ships inside the npm package AND is served
+by the server, so wording/Gotcha updates arrive without an npm release. "setup"
+(or "setup --skill-only") installs the bundled copy, then upgrades it from the
+server when the served bundle's minCliVersion allows — an older binary keeps the
+bundled copy, and an unreachable server is not an error. "doctor" reports whether
+a newer skill exists and names the command; it never writes.
+
 Writes preview and exit 2 unless --confirm is supplied after explicit human approval.
 Environment overrides: RECESS_CLI_API_ORIGIN, RECESS_CLI_WEB_ORIGIN,
 RECESS_CLI_OAUTH_CLIENT_ID, RECESS_CLI_COOKIE, RECESS_CLI_CONFIG.`;
@@ -189,8 +242,58 @@ async function doctor(config) {
             message: error instanceof Error ? error.message : String(error),
         };
     }
+    checks.skill = await skillStatus(config);
     return checks;
 }
+/**
+ * Report whether a newer agent skill is available. Deliberately READ-ONLY:
+ * `doctor` is run reflexively at the start of a session, and a diagnostic that
+ * silently rewrote `~/.claude/skills` mid-session would change what the agent is
+ * reading out from under it. It names the command instead.
+ */
+async function skillStatus(config) {
+    const cliVersion = await readCliVersion();
+    const installedVersion = await readBundledSkillVersion();
+    const base = { cliVersion, bundledSkillVersion: installedVersion };
+    if (!config.sessionCookie) {
+        return { ...base, checked: false, reason: "no session" };
+    }
+    try {
+        const response = await fetch(new URL("/admin/cli-skill/", config.apiOrigin), {
+            headers: { cookie: config.sessionCookie },
+            signal: AbortSignal.timeout(5000),
+        });
+        if (!response.ok) {
+            return { ...base, checked: false, reason: `server ${response.status}` };
+        }
+        const bundle = (await response.json());
+        const serverVersion = bundle.version ?? "0.0.0";
+        const minCliVersion = bundle.minCliVersion ?? "0.0.0";
+        const cliTooOld = compareVersions(cliVersion, minCliVersion) < 0;
+        const upToDate = compareVersions(installedVersion, serverVersion) >= 0;
+        return {
+            ...base,
+            checked: true,
+            serverSkillVersion: serverVersion,
+            minCliVersion,
+            upToDate,
+            ...(upToDate
+                ? {}
+                : cliTooOld
+                    ? {
+                        action: `Server skill ${serverVersion} needs recess >= ${minCliVersion}; upgrade with \`npm install -g recess-cli\`.`,
+                    }
+                    : { action: "Run `recess setup --skill-only` to install it." }),
+        };
+    }
+    catch (error) {
+        return {
+            ...base,
+            checked: false,
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
 async function writeCommand(parsed, preview, execute) {
     requireConfirmation(hasFlag(parsed, "confirm"), preview);
     return execute();
@@ -263,6 +366,220 @@ const SCHOOL_TIER_OPTIONS = [
 ];
 const SCHOOL_TIER_IDS = SCHOOL_TIER_OPTIONS.map((tier) => tier.id);
 const MAX_MAP_PDF_BYTES = 15 * 1024 * 1024;
+const GOAL_TEMPLATE_KINDS = ["SIMPLE", "BLUEPRINT"];
+const GOAL_TEMPLATE_SETUP_AUDIENCES = ["KID_FRIENDLY", "PARENT_SETUP"];
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Read and parse a JSON file supplied by an authoring agent. Large payloads —
+ * a setupWorkflowSpec, an answers map, a goal description — go through files
+ * rather than argv: a shell mangles embedded quotes and newlines, and a spec
+ * that survived a round trip through `--json '<...>'` is not the spec that was
+ * reviewed.
+ */
+async function readJsonValue(filePath, label) {
+    const absolutePath = path.resolve(filePath);
+    let raw;
+    try {
+        raw = await fs.readFile(absolutePath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new CliError("invalid_arguments", `${label} does not exist: ${absolutePath}`);
+        }
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new CliError("invalid_arguments", `${label} is not valid JSON (${absolutePath}): ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return { absolutePath, raw, parsed };
+}
+async function readJsonFile(filePath, label) {
+    const { absolutePath, parsed } = await readJsonValue(filePath, label);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new CliError("invalid_arguments", `${label} must be a JSON object (${absolutePath}).`);
+    }
+    return parsed;
+}
+async function readGoalTemplateSpecPatches(filePath) {
+    const { absolutePath, raw, parsed } = await readJsonValue(filePath, "Goal-template patch file");
+    if (!Array.isArray(parsed) || parsed.length === 0) {
+        throw new CliError("invalid_arguments", `Goal-template patch file must be a non-empty JSON array (${absolutePath}).`);
+    }
+    if (parsed.length > 50) {
+        throw new CliError("invalid_arguments", "Goal-template patch files support at most 50 operations.");
+    }
+    const patches = parsed.map((entry, index) => {
+        if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+            throw new CliError("invalid_arguments", `Patch operation ${index} must be an object.`);
+        }
+        const patch = entry;
+        const op = patch.op;
+        if (op !== "add" && op !== "copy" && op !== "replace" && op !== "remove") {
+            throw new CliError("invalid_arguments", `Patch operation ${index}.op must be add, copy, replace, or remove.`);
+        }
+        if (typeof patch.path !== "string" || !patch.path.startsWith("/")) {
+            throw new CliError("invalid_arguments", `Patch operation ${index}.path must be a JSON Pointer starting with "/".`);
+        }
+        const hasValue = Object.prototype.hasOwnProperty.call(patch, "value");
+        if ((op === "add" || op === "replace") && !hasValue) {
+            throw new CliError("invalid_arguments", `Patch operation ${index}.value is required for ${op}.`);
+        }
+        if ((op === "copy" || op === "remove") && hasValue) {
+            throw new CliError("invalid_arguments", `Patch operation ${index}.value is not allowed for ${op}.`);
+        }
+        if (op === "copy" &&
+            (typeof patch.from !== "string" || !patch.from.startsWith("/"))) {
+            throw new CliError("invalid_arguments", `Patch operation ${index}.from must be a JSON Pointer starting with "/" for copy.`);
+        }
+        return {
+            op,
+            path: patch.path,
+            ...(op === "copy" ? { from: patch.from } : {}),
+            ...(hasValue ? { value: patch.value } : {}),
+        };
+    });
+    return {
+        absolutePath,
+        sizeBytes: Buffer.byteLength(raw),
+        sha256: createHash("sha256").update(raw).digest("hex"),
+        patches,
+    };
+}
+function requiredDocString(doc, key) {
+    const value = doc[key];
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new CliError("invalid_arguments", `Template file is missing required string "${key}".`);
+    }
+    return value;
+}
+function optionalDocString(doc, key) {
+    const value = doc[key];
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string") {
+        throw new CliError("invalid_arguments", `Template file field "${key}" must be a string.`);
+    }
+    return value;
+}
+/**
+ * Coerce an authored template file into the exact `POST /admin/goal-templates/`
+ * body. Every unknown key is dropped rather than forwarded, so a stale field
+ * copied from an old export cannot ride along into a create, and the shape
+ * failures an agent actually makes (missing slug, spec as a string, tags as a
+ * comma list) are named locally before any network call.
+ *
+ * `setupMode` is deliberately absent: the route accepts only
+ * DETERMINISTIC_WORKFLOW and a deterministic template can never be converted
+ * back, so there is no choice to express.
+ */
+function parseGoalTemplateDocument(doc) {
+    if (doc.setupMode !== undefined &&
+        doc.setupMode !== "DETERMINISTIC_WORKFLOW") {
+        throw new CliError("invalid_arguments", `Template file sets setupMode "${String(doc.setupMode)}". New templates are DETERMINISTIC_WORKFLOW only — omit the field.`);
+    }
+    const spec = doc.setupWorkflowSpec;
+    if (spec === null || typeof spec !== "object" || Array.isArray(spec)) {
+        throw new CliError("invalid_arguments", 'Template file requires an object "setupWorkflowSpec" (the fixed wizard). Author it with the os-v2-goal-template-builder skill: `recess --json skills get os-v2-goal-template-builder --all-references`.');
+    }
+    const rawTags = doc.tags;
+    let tags = [];
+    if (Array.isArray(rawTags)) {
+        if (!rawTags.every((tag) => typeof tag === "string")) {
+            throw new CliError("invalid_arguments", 'Template file field "tags" must be an array of strings.');
+        }
+        tags = rawTags;
+    }
+    else if (typeof rawTags === "string") {
+        // A comma list is what a human writes by hand; accept it rather than
+        // failing an otherwise-valid template on punctuation.
+        tags = rawTags
+            .split(",")
+            .map((tag) => tag.trim())
+            .filter(Boolean);
+    }
+    else if (rawTags !== undefined && rawTags !== null) {
+        throw new CliError("invalid_arguments", 'Template file field "tags" must be an array of strings.');
+    }
+    const rawSortOrder = doc.sortOrder;
+    if (rawSortOrder !== undefined &&
+        rawSortOrder !== null &&
+        (typeof rawSortOrder !== "number" || !Number.isInteger(rawSortOrder))) {
+        throw new CliError("invalid_arguments", 'Template file field "sortOrder" must be an integer.');
+    }
+    const kind = assertChoice(optionalDocString(doc, "kind") ?? "SIMPLE", GOAL_TEMPLATE_KINDS, "kind");
+    const setupAudience = assertChoice(optionalDocString(doc, "setupAudience") ?? "KID_FRIENDLY", GOAL_TEMPLATE_SETUP_AUDIENCES, "setupAudience");
+    const starterTierRaw = optionalDocString(doc, "starterTier");
+    const parentSetupSpec = doc.parentSetupSpec;
+    if (parentSetupSpec !== undefined &&
+        parentSetupSpec !== null &&
+        (typeof parentSetupSpec !== "object" || Array.isArray(parentSetupSpec))) {
+        throw new CliError("invalid_arguments", 'Template file field "parentSetupSpec" must be an object.');
+    }
+    return {
+        slug: requiredDocString(doc, "slug"),
+        title: requiredDocString(doc, "title"),
+        description: requiredDocString(doc, "description"),
+        ...(optionalDocString(doc, "emoji") === undefined
+            ? {}
+            : { emoji: optionalDocString(doc, "emoji") }),
+        ...(optionalDocString(doc, "imageUrl") === undefined
+            ? {}
+            : { imageUrl: optionalDocString(doc, "imageUrl") }),
+        ...(optionalDocString(doc, "category") === undefined
+            ? {}
+            : { category: optionalDocString(doc, "category") }),
+        tags,
+        sortOrder: rawSortOrder ?? 0,
+        ...(doc.isStarter === undefined
+            ? {}
+            : { isStarter: Boolean(doc.isStarter) }),
+        ...(starterTierRaw === undefined
+            ? {}
+            : {
+                starterTier: assertChoice(starterTierRaw, ["CORE", "EXTRA"], "starterTier"),
+            }),
+        kind,
+        setupAudience,
+        setupWorkflowSpec: spec,
+        ...(parentSetupSpec === undefined || parentSetupSpec === null
+            ? {}
+            : { parentSetupSpec: parentSetupSpec }),
+        agentInstructions: requiredDocString(doc, "agentInstructions"),
+        ...(optionalDocString(doc, "outputTemplate") === undefined
+            ? {}
+            : { outputTemplate: optionalDocString(doc, "outputTemplate") }),
+    };
+}
+/**
+ * Resolve a template reference that may be a UUID or a slug. Slugs are what an
+ * author types and what the skill's prose uses; the routes take a UUID only.
+ */
+async function resolveGoalTemplateId(api, reference) {
+    if (UUID_RE.test(reference))
+        return reference;
+    const list = unwrap(await api.client.GET("/admin/goal-templates/", {
+        params: { query: { includeDeleted: "true" } },
+    }));
+    const match = list.items.find((item) => item.slug === reference);
+    if (!match) {
+        throw new CliError("invalid_arguments", `No goal template with id or slug "${reference}".`);
+    }
+    return match.id;
+}
+function requiredExpectedVersion(parsed) {
+    const value = flagNumber(parsed, "expected-version");
+    if (value === undefined) {
+        throw new CliError("invalid_arguments", "Missing required --expected-version. Read it from `goal-templates get <id>` (the `version` field); a stale value 409s without writing.");
+    }
+    if (!Number.isInteger(value) || value < 1) {
+        throw new CliError("invalid_arguments", "--expected-version must be a positive integer.");
+    }
+    return value;
+}
 async function readMapScorePdf(filePath) {
     const absolutePath = path.resolve(filePath);
     if (path.extname(absolutePath).toLowerCase() !== ".pdf") {
@@ -407,6 +724,14 @@ function tierSlots(parsed) {
 export async function runCommand(argv) {
     const parsed = parseArgs(argv);
     const [noun, verb] = parsed.positionals;
+    // Before the help branch: `--version` parses as a FLAG, so `noun` is
+    // undefined and `!noun` would return help instead. (Found by running it.)
+    if (noun === "version" || hasFlag(parsed, "version")) {
+        return {
+            cliVersion: await readCliVersion(),
+            skillVersion: await readBundledSkillVersion(),
+        };
+    }
     if (!noun || noun === "help" || hasFlag(parsed, "help")) {
         return { help: HELP };
     }
@@ -414,7 +739,15 @@ export async function runCommand(argv) {
     if (noun === "doctor")
         return doctor(config);
     if (noun === "setup") {
+        // Always lay down the bundled copy first: it is the floor, and it is the
+        // only copy guaranteed to match this binary. The served upgrade below is
+        // strictly additive on top of it.
         const skills = await installSkill();
+        const skillUpdate = await updateSkillFromServer({
+            apiOrigin: config.apiOrigin,
+            sessionCookie: config.sessionCookie,
+            cliVersion: await readCliVersion(),
+        });
         const ephemeral = isEphemeralInstall();
         // Reuse a session that is still live; a missing or already-expired one is
         // worth spending the browser round trip on now rather than at first use.
@@ -430,6 +763,7 @@ export async function runCommand(argv) {
             });
         return {
             skills,
+            skillUpdate,
             session: loggedIn ?? (sessionIsLive ? "existing" : null),
             ...(ephemeral
                 ? {
@@ -1529,6 +1863,493 @@ export async function runCommand(argv) {
         }
         throw new CliError("invalid_arguments", "Use onboarding status|kids|intake-session|intake-session-create|set-stage|set-account-state|attest|set-intake|extract.");
     }
+    if (noun === "skills") {
+        // Reads only — no gate. The value of this noun is that CLI agents author
+        // against the SAME documents the in-product tutor loads; nothing is copied
+        // into this package, so a skills-repo change reaches agents with no release.
+        const refresh = hasFlag(parsed, "refresh");
+        if (verb === "list") {
+            const query = flagString(parsed, "query");
+            const category = flagString(parsed, "category");
+            const cacheKey = `list:${query ?? ""}:${category ?? ""}`;
+            if (!refresh) {
+                const cached = await readSkillCache(config.apiOrigin, cacheKey);
+                if (cached)
+                    return { ...cached, cached: true };
+            }
+            const data = unwrap(await api.client.GET("/admin/skills/", {
+                params: {
+                    query: {
+                        ...(query ? { query } : {}),
+                        ...(category ? { category } : {}),
+                    },
+                },
+            }));
+            await writeSkillCache(config.apiOrigin, cacheKey, data);
+            return { ...data, cached: false };
+        }
+        if (verb === "get") {
+            const name = positional(parsed, 2, "skill name");
+            const reference = flagString(parsed, "reference");
+            const allReferences = hasFlag(parsed, "all-references");
+            if (reference && allReferences) {
+                throw new CliError("invalid_arguments", "Pass --reference <name> for one reference or --all-references for the whole tree, not both.");
+            }
+            const cacheKey = `get:${name}:${reference ?? ""}:${allReferences}`;
+            if (!refresh) {
+                const cached = await readSkillCache(config.apiOrigin, cacheKey);
+                if (cached)
+                    return { ...cached, cached: true };
+            }
+            const data = unwrap(await api.client.GET("/admin/skills/{name}", {
+                params: {
+                    path: { name },
+                    query: {
+                        ...(reference ? { reference } : {}),
+                        ...(allReferences ? { references: "all" } : {}),
+                    },
+                },
+            }));
+            await writeSkillCache(config.apiOrigin, cacheKey, data);
+            return { ...data, cached: false };
+        }
+        throw new CliError("invalid_arguments", "Use skills list|get.");
+    }
+    if (noun === "goal-templates") {
+        if (verb === "list") {
+            const query = flagString(parsed, "query")?.toLowerCase();
+            const kind = flagString(parsed, "kind");
+            const data = unwrap(await api.client.GET("/admin/goal-templates/", {
+                params: {
+                    query: {
+                        ...(flagString(parsed, "category")
+                            ? { category: flagString(parsed, "category") }
+                            : {}),
+                        includeDeleted: hasFlag(parsed, "include-deleted")
+                            ? "true"
+                            : "false",
+                        starterOnly: hasFlag(parsed, "starter-only")
+                            ? "true"
+                            : "false",
+                    },
+                },
+            }));
+            // The route filters by category/starter/deleted only; `--query` and
+            // `--kind` narrow the returned page here rather than pretending the
+            // backend supports them.
+            const wantedKind = kind
+                ? assertChoice(kind, GOAL_TEMPLATE_KINDS, "--kind")
+                : undefined;
+            const items = data.items.filter((item) => {
+                if (wantedKind && item.kind !== wantedKind)
+                    return false;
+                if (!query)
+                    return true;
+                return [item.title, item.slug, item.description, item.category ?? ""]
+                    .join("\n")
+                    .toLowerCase()
+                    .includes(query);
+            });
+            return { items, totalBeforeFilter: data.items.length };
+        }
+        if (verb === "get") {
+            const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
+            const template = unwrap(await api.client.GET("/admin/goal-templates/{id}", {
+                params: { path: { id } },
+            }));
+            // A full spec is large; `--spec-only` is what an agent pipes into a file
+            // before editing, without the surrounding metadata noise.
+            if (hasFlag(parsed, "spec-only")) {
+                return {
+                    id: template.id,
+                    slug: template.slug,
+                    version: template.version,
+                    setupWorkflowSpec: template.setupWorkflowSpec,
+                };
+            }
+            return template;
+        }
+        if (verb === "versions") {
+            const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
+            const data = unwrap(await api.client.GET("/admin/goal-templates/{id}/versions", {
+                params: { path: { id } },
+            }));
+            const wanted = flagNumber(parsed, "version");
+            if (wanted === undefined) {
+                // Version bodies carry the whole frozen spec; the default listing is
+                // metadata so history stays readable, and `--version N` fetches one.
+                return {
+                    versions: data.versions.map(({ setupWorkflowSpec, agentInstructions, ...rest }) => ({
+                        ...rest,
+                        hasSetupWorkflowSpec: setupWorkflowSpec !== null,
+                        agentInstructionsChars: agentInstructions.length,
+                    })),
+                };
+            }
+            const version = data.versions.find((entry) => entry.version === wanted);
+            if (!version) {
+                throw new CliError("invalid_arguments", `Template has no version ${wanted}.`);
+            }
+            return version;
+        }
+        if (verb === "validate-spec") {
+            const document = parseGoalTemplateDocument(await readJsonFile(flagString(parsed, "file", { required: true }), "Template file"));
+            // A read-only validation: no gate, and iterating on it is the whole point.
+            return {
+                slug: document.slug,
+                kind: document.kind,
+                ...unwrap(await api.client.POST("/admin/goal-templates/validate-spec", {
+                    body: {
+                        setupWorkflowSpec: document.setupWorkflowSpec,
+                        kind: document.kind,
+                    },
+                })),
+            };
+        }
+        if (verb === "create") {
+            const filePath = flagString(parsed, "file", { required: true });
+            const document = parseGoalTemplateDocument(await readJsonFile(filePath, "Template file"));
+            // C3 read-only preflight, for the same reason `enrollments create` has
+            // one: the consequences an approver must weigh are resolved SERVER-side.
+            // Which setupHandler runs, what shape of goal students get, and which
+            // answer keys `apply` will demand all come out of the spec's own
+            // validation — a locally guessed preview could name a different handler
+            // than the one that lands. Validation writes nothing.
+            const validation = unwrap(await api.client.POST("/admin/goal-templates/validate-spec", {
+                body: {
+                    setupWorkflowSpec: document.setupWorkflowSpec,
+                    kind: document.kind,
+                },
+            }));
+            if (!validation.valid) {
+                throw new CliError("invalid_spec", `The setupWorkflowSpec is invalid, so nothing was created: ${validation.error}`, 1, { file: path.resolve(filePath) });
+            }
+            return writeCommand(parsed, {
+                action: "create a NEW global goal template (DETERMINISTIC_WORKFLOW — this cannot be converted back)",
+                target: { slug: document.slug, title: document.title },
+                request: {
+                    file: path.resolve(filePath),
+                    kind: document.kind,
+                    setupAudience: document.setupAudience,
+                    category: document.category ?? null,
+                    tags: document.tags,
+                    isStarter: document.isStarter ?? false,
+                },
+                details: {
+                    resolvedSetupHandler: validation.setupHandler,
+                    resolvedGoalShape: validation.goalShape,
+                    wizardStepKeys: validation.stepKeys,
+                    specSha256: validation.sha256,
+                    specInventory: validation.totals,
+                    note: "Setup mode is DETERMINISTIC_WORKFLOW and is one-way: this template can never be converted back to a chat-driven setup.",
+                },
+            }, async () => unwrap(await api.client.POST("/admin/goal-templates/", {
+                body: document,
+            })));
+        }
+        if (verb === "patch-spec") {
+            const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
+            const expectedVersion = requiredExpectedVersion(parsed);
+            const patchFile = await readGoalTemplateSpecPatches(flagString(parsed, "patches-file", { required: true }));
+            // The server owns JSON Pointer semantics, strict final-spec validation,
+            // protected-inventory counting, and the token binding the approved loss
+            // to this exact version + result hash. Always ask it for a fresh preview,
+            // including on a confirmed run, before permitting the write request.
+            const preflight = unwrap(await api.client.POST("/admin/goal-templates/{id}/setup-workflow-spec/patch", {
+                params: { path: { id } },
+                body: {
+                    expectedVersion,
+                    patches: patchFile.patches,
+                    dryRun: true,
+                },
+            }));
+            if (preflight.action !== "preview_setup_workflow_spec_patch") {
+                throw new CliError("unexpected_response", "The goal-template patch preflight did not return a preview; nothing was changed.");
+            }
+            const preview = {
+                action: preflight.preview.destructiveChanges
+                    ? "patch a global goal template setupWorkflowSpec (REMOVES protected template data)"
+                    : "patch a global goal template setupWorkflowSpec",
+                target: {
+                    templateId: preflight.template.id,
+                    slug: preflight.template.slug,
+                    title: preflight.template.title,
+                    version: preflight.template.version,
+                },
+                request: {
+                    expectedVersion,
+                    patchesFile: patchFile.absolutePath,
+                    patchesFileSizeBytes: patchFile.sizeBytes,
+                    patchesFileSha256: patchFile.sha256,
+                    patches: patchFile.patches,
+                },
+                details: {
+                    patchesApplied: preflight.patchesApplied,
+                    safety: preflight.preview,
+                    ...(preflight.preview.destructiveChanges
+                        ? {
+                            destructiveApproval: "After explicit approval of the exact removed inventory, rerun with --confirm --confirm-destructive-changes and --destructive-change-token set to this preview's token.",
+                        }
+                        : {}),
+                },
+            };
+            requireConfirmation(hasFlag(parsed, "confirm"), preview);
+            const destructiveChangeToken = flagString(parsed, "destructive-change-token");
+            if (preflight.preview.destructiveChanges &&
+                (!hasFlag(parsed, "confirm-destructive-changes") ||
+                    !destructiveChangeToken ||
+                    destructiveChangeToken !== preflight.preview.destructiveChangeToken)) {
+                throw new CliError("destructive_confirmation_required", "This patch removes protected template data. Review the fresh preview and rerun with --confirm-destructive-changes plus its exact --destructive-change-token; nothing was changed.", 2, {
+                    preview,
+                    requiredFlags: [
+                        "--confirm",
+                        "--confirm-destructive-changes",
+                        "--destructive-change-token",
+                    ],
+                    expectedDestructiveChangeToken: preflight.preview.destructiveChangeToken,
+                });
+            }
+            return unwrap(await api.client.POST("/admin/goal-templates/{id}/setup-workflow-spec/patch", {
+                params: { path: { id } },
+                body: {
+                    expectedVersion,
+                    patches: patchFile.patches,
+                    dryRun: false,
+                    confirmDestructiveChanges: preflight.preview.destructiveChanges,
+                    ...(destructiveChangeToken ? { destructiveChangeToken } : {}),
+                },
+            }));
+        }
+        if (verb === "set-metadata") {
+            const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
+            const expectedVersion = requiredExpectedVersion(parsed);
+            const agentInstructionsFile = flagString(parsed, "agent-instructions-file");
+            const tags = flagString(parsed, "tags");
+            const kind = flagString(parsed, "kind");
+            const sortOrder = flagNumber(parsed, "sort-order");
+            const body = {
+                expectedVersion,
+                ...(flagString(parsed, "title")
+                    ? { title: flagString(parsed, "title") }
+                    : {}),
+                ...(flagString(parsed, "description")
+                    ? { description: flagString(parsed, "description") }
+                    : {}),
+                ...(flagString(parsed, "emoji")
+                    ? { emoji: flagString(parsed, "emoji") }
+                    : {}),
+                ...(flagString(parsed, "category")
+                    ? { category: flagString(parsed, "category") }
+                    : {}),
+                ...(tags
+                    ? {
+                        tags: tags
+                            .split(",")
+                            .map((tag) => tag.trim())
+                            .filter(Boolean),
+                    }
+                    : {}),
+                ...(sortOrder === undefined ? {} : { sortOrder }),
+                ...(kind
+                    ? { kind: assertChoice(kind, GOAL_TEMPLATE_KINDS, "--kind") }
+                    : {}),
+                ...(agentInstructionsFile
+                    ? {
+                        agentInstructions: await fs.readFile(path.resolve(agentInstructionsFile), "utf8"),
+                    }
+                    : {}),
+            };
+            // `setupWorkflowSpec` is unreachable from this command by construction.
+            // The route still accepts one, but a wholesale spec replacement is the
+            // shape that caused the template incident; editing an existing spec goes
+            // through the guarded /ai patch path with its destructive-change token.
+            if (Object.keys(body).length === 1) {
+                throw new CliError("invalid_arguments", "Pass at least one field to change (--title, --description, --emoji, --category, --tags, --sort-order, --kind, --agent-instructions-file).");
+            }
+            return writeCommand(parsed, {
+                action: "update goal template metadata (never its setupWorkflowSpec)",
+                target: { templateId: id, expectedVersion },
+                request: body,
+            }, async () => unwrap(await api.client.PUT("/admin/goal-templates/{id}", {
+                params: { path: { id } },
+                body,
+            })));
+        }
+        if (verb === "delete") {
+            const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
+            const expectedVersion = requiredExpectedVersion(parsed);
+            // Read the current version so the gate refuses a stale delete locally,
+            // and so the preview names the template a human is being asked to approve
+            // rather than only its UUID.
+            const current = unwrap(await api.client.GET("/admin/goal-templates/{id}", {
+                params: { path: { id } },
+            }));
+            if (current.version !== expectedVersion) {
+                throw new CliError("stale_write", `Goal template is at version ${current.version}, not ${expectedVersion}. Re-read it before deleting; nothing was deleted.`, 1, { templateId: id, currentVersion: current.version });
+            }
+            return writeCommand(parsed, {
+                action: "soft-delete a global goal template",
+                target: {
+                    templateId: id,
+                    slug: current.slug,
+                    title: current.title,
+                    version: current.version,
+                },
+                request: { expectedVersion },
+                details: {
+                    note: "Soft delete: the row keeps its deletedAt and drops out of every list. Existing goals already applied from it are unaffected.",
+                },
+            }, async () => unwrap(await api.client.DELETE("/admin/goal-templates/{id}", {
+                params: { path: { id } },
+            })));
+        }
+        if (verb === "snapshot-files") {
+            const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
+            const filePath = flagString(parsed, "path");
+            if (filePath) {
+                return unwrap(await api.client.GET("/admin/goal-templates/{id}/snapshot/file", {
+                    params: { path: { id }, query: { path: filePath } },
+                }));
+            }
+            return unwrap(await api.client.GET("/admin/goal-templates/{id}/snapshot/files", {
+                params: { path: { id } },
+            }));
+        }
+        if (verb === "apply") {
+            const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
+            const answers = await readJsonFile(flagString(parsed, "answers-file", { required: true }), "Answers file");
+            // `--dry-run` is a read: it resolves the whole plan and writes nothing,
+            // so it does not gate. Run it, read the per-student results, then confirm.
+            if (hasFlag(parsed, "dry-run")) {
+                return unwrap(await api.client.POST("/ai/goal-templates/{id}/apply-workflow", {
+                    params: { path: { id } },
+                    body: { answers, dryRun: true },
+                }));
+            }
+            // The real consequence — which students get which goals, which are
+            // skipped as already-existing, and what coverage is missing — is only
+            // knowable from the backend's own planner. Run its dryRun before the gate
+            // (writes nothing) so the approver sees the actual roster.
+            const preflight = unwrap(await api.client.POST("/ai/goal-templates/{id}/apply-workflow", {
+                params: { path: { id } },
+                body: { answers, dryRun: true },
+            }));
+            const counts = preflight.results.reduce((totals, result) => ({
+                ...totals,
+                [result.action]: (totals[result.action] ?? 0) + 1,
+            }), {});
+            return writeCommand(parsed, {
+                action: "apply a goal template to students (creates goals and todos)",
+                target: { templateId: id, students: preflight.results.length },
+                request: { answers },
+                details: {
+                    counts,
+                    results: preflight.results.map((result) => ({
+                        student: result.studentName,
+                        studentUserId: result.studentUserId,
+                        action: result.action,
+                        goalTitle: result.goalTitle,
+                        todoTitle: result.todoTitle,
+                        warnings: result.warnings,
+                    })),
+                    missingCoverage: preflight.missingCoverage,
+                    note: "Counts come from the backend's own dry run. `skipped_existing` items are idempotent — re-applying does not duplicate them.",
+                },
+            }, async () => unwrap(await api.client.POST("/ai/goal-templates/{id}/apply-workflow", {
+                params: { path: { id } },
+                body: { answers, dryRun: false },
+            })));
+        }
+        if (verb === "apply-starter") {
+            const id = await resolveGoalTemplateId(api, positional(parsed, 2, "template ID or slug"));
+            const studentUserId = flagString(parsed, "student", { required: true });
+            const answersFile = flagString(parsed, "answers-file");
+            const answers = answersFile
+                ? await readJsonFile(answersFile, "Answers file")
+                : {};
+            // apply-starter has no dryRun — it is the one-tap starter path — so this
+            // preview is offline. It is also flag-gated per actor server-side
+            // (school-onboarding-v1); a flag-off admin gets a 404 rather than a write.
+            return writeCommand(parsed, {
+                action: "apply ONE starter goal template to ONE student (no dry run exists for this route)",
+                target: { templateId: id, studentUserId },
+                request: { answers },
+                details: {
+                    note: "Gated behind the school-onboarding-v1 flag for the acting admin; a 404 means the flag is off, not that the template is missing. Prefer `goal-templates apply --dry-run` when the template supports it.",
+                },
+            }, async () => unwrap(await api.client.POST("/ai/goal-templates/{id}/apply-starter", {
+                params: { path: { id } },
+                body: { studentUserId, answers },
+            })));
+        }
+        throw new CliError("invalid_arguments", "Use goal-templates list|get|versions|validate-spec|create|patch-spec|set-metadata|delete|snapshot-files|apply|apply-starter.");
+    }
+    if (noun === "goals") {
+        if (verb === "list") {
+            const userId = flagString(parsed, "student", { required: true });
+            return unwrap(await api.client.GET("/admin/browser/students/{userId}/goals/", {
+                params: { path: { userId } },
+            }));
+        }
+        if (verb === "create") {
+            const userId = flagString(parsed, "student", { required: true });
+            const title = flagString(parsed, "title", { required: true });
+            const descriptionFile = flagString(parsed, "description-file");
+            const descriptionFlag = flagString(parsed, "description");
+            if ((descriptionFile && descriptionFlag) ||
+                (!descriptionFile && !descriptionFlag)) {
+                throw new CliError("invalid_arguments", "Pass exactly one of --description <text> or --description-file <path>.");
+            }
+            const description = descriptionFile
+                ? await fs.readFile(path.resolve(descriptionFile), "utf8")
+                : descriptionFlag;
+            const targetDate = flagString(parsed, "target-date");
+            if (targetDate !== undefined && Number.isNaN(Date.parse(targetDate))) {
+                throw new CliError("invalid_arguments", "--target-date must be an ISO 8601 datetime.");
+            }
+            const schedule = flagString(parsed, "schedule");
+            const body = {
+                title,
+                description,
+                ...(targetDate ? { targetDate } : {}),
+                ...(schedule ? { schedule } : {}),
+            };
+            return writeCommand(parsed, {
+                action: "create a goal directly on a kid (visible to them immediately)",
+                target: { studentUserId: userId },
+                request: {
+                    title,
+                    descriptionChars: description.length,
+                    targetDate: targetDate ?? null,
+                    schedule: schedule ?? null,
+                },
+                details: {
+                    note: "Creates a description-only goal with no GoalModules and no Mesa workspace. For a module-backed course, apply a BLUEPRINT template instead. A 409 GOAL_LIMIT_REACHED means the kid is at capacity and nothing was created.",
+                },
+            }, async () => unwrap(await api.client.POST("/admin/browser/students/{userId}/goals/", {
+                params: { path: { userId } },
+                body,
+            })));
+        }
+        throw new CliError("invalid_arguments", "Use goals list|create.");
+    }
+    if (noun === "mesa" && verb === "files") {
+        const action = positional(parsed, 2, "mesa files action");
+        const studentId = flagString(parsed, "student", { required: true });
+        const goalId = flagString(parsed, "goal", { required: true });
+        if (action === "list") {
+            return unwrap(await api.client.GET("/tutor/students/{studentId}/goals/{goalId}/workspace/files", { params: { path: { studentId, goalId } } }));
+        }
+        if (action === "read") {
+            return unwrap(await api.client.GET("/tutor/students/{studentId}/goals/{goalId}/workspace/file", {
+                params: {
+                    path: { studentId, goalId },
+                    query: { path: flagString(parsed, "path", { required: true }) },
+                },
+            }));
+        }
+        throw new CliError("invalid_arguments", "Use mesa files list|read.");
+    }
     if (noun === "request" && verb === "get") {
         return api.rawGet(positional(parsed, 2, "request path"));
     }