recess-cli 1.3.3 → 1.4.0

package/dist/cli.js

@@ -28,6 +28,11 @@ Usage:
     [--slots N]
   recess [--json] users tier set <kid-id> --tier social|academics|lite|complete|platform
     [--slots N] --expected-updated-at <iso> [--allow-strand] [--confirm]
+  recess [--json] guides create --email <email> --first-name TEXT
+    [--last-name TEXT] [--no-invite] [--confirm]
+  recess [--json] guides invite --user <user-id> [--confirm]
+  recess [--json] guardians invite --family <family-id> --email <email>
+    --first-name TEXT [--last-name TEXT] [--no-invite] [--confirm]
   recess [--json] students upload-map-scores --student <kid-id>
     --file </path/to/map-report.pdf> [--confirm]
   recess [--json] enrollments list --user <user-id>
@@ -1274,6 +1279,96 @@ export async function runCommand(argv) {
             params: { path: { userId } },
         }));
     }
+    if (noun === "guides" && verb === "create") {
+        const email = flagString(parsed, "email", { required: true })
+            .trim()
+            .toLowerCase();
+        if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+            throw new CliError("invalid_arguments", "--email does not look like a valid email address.");
+        }
+        const firstName = flagString(parsed, "first-name", { required: true });
+        const lastName = flagString(parsed, "last-name");
+        const sendInvite = !hasFlag(parsed, "no-invite");
+        const body = {
+            email,
+            firstName,
+            ...(lastName !== undefined ? { lastName } : {}),
+            sendInvite,
+        };
+        return writeCommand(parsed, {
+            action: sendInvite
+                ? "provision a GUIDE staff account and email its sign-in invite (outward email)"
+                : "provision a GUIDE staff account without sending the invite email",
+            target: { email },
+            request: body,
+        }, async () => unwrap(await api.client.POST("/admin/guides/", { body })));
+    }
+    if (noun === "guardians" && verb === "invite") {
+        const familyId = flagString(parsed, "family", { required: true });
+        const email = flagString(parsed, "email", { required: true })
+            .trim()
+            .toLowerCase();
+        if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+            throw new CliError("invalid_arguments", "--email does not look like a valid email address.");
+        }
+        const firstName = flagString(parsed, "first-name", { required: true });
+        const lastName = flagString(parsed, "last-name");
+        const sendInvite = !hasFlag(parsed, "no-invite");
+        // Read-only preflight: the approval preview must name the exact family
+        // this guardian is being granted over — a wrong family id hands a
+        // stranger full guardian access to someone's kids.
+        const family = unwrap(await api.client.GET("/admin/onboarding/families/{familyId}/status", {
+            params: { path: { familyId } },
+        }));
+        const body = {
+            email,
+            firstName,
+            ...(lastName !== undefined ? { lastName } : {}),
+            sendInvite,
+        };
+        return writeCommand(parsed, {
+            action: sendInvite
+                ? "invite a new GUARDIAN into an existing family and email the sign-in invite (outward email)"
+                : "add a new GUARDIAN to an existing family without sending the invite email",
+            target: { familyId, email },
+            request: body,
+            details: {
+                familyName: family.familyName,
+                kids: family.kids.map((kid) => kid.firstName),
+            },
+        }, async () => unwrap(await api.client.POST("/admin/users/family/{familyId}/guardians/", {
+            params: { path: { familyId } },
+            body,
+        })));
+    }
+    if (noun === "guides" && verb === "invite") {
+        const userId = flagString(parsed, "user", { required: true });
+        // Read-only preflight: the approval preview must name the exact person
+        // about to receive an outward email, and refuse a non-guide before the
+        // gate rather than after approval (the backend enforces the same rule).
+        const { user } = unwrap(await api.client.GET("/admin/users/{userId}", {
+            params: { path: { userId } },
+        }));
+        if (user.role !== "GUIDE") {
+            throw new CliError("invalid_arguments", `User ${userId} has role ${user.role}; only GUIDE accounts can be invited. Use guides create for a new guide.`);
+        }
+        if (!user.email) {
+            throw new CliError("invalid_arguments", `Guide ${userId} has no email address on file, so no invite can be sent.`);
+        }
+        return writeCommand(parsed, {
+            action: "send the guide sign-in invite email (outward email)",
+            target: { userId },
+            request: {},
+            details: {
+                to: user.email,
+                firstName: user.firstName,
+                lastName: user.lastName,
+                role: user.role,
+            },
+        }, async () => unwrap(await api.client.POST("/admin/guides/{userId}/invite/", {
+            params: { path: { userId } },
+        })));
+    }
     if (noun === "students" && verb === "upload-map-scores") {
         const studentId = flagString(parsed, "student", { required: true });
         const pdf = await readMapScorePdf(flagString(parsed, "file", { required: true }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "recess-cli",
-  "version": "1.3.3",
+  "version": "1.4.0",
   "description": "Safe Recess staff administration from the command line, for humans and coding agents.",
   "license": "UNLICENSED",
   "repository": {

package/skill/recess-cli/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: recess-cli
-description: Safely perform Recess staff administration through the recess CLI. Use when a Recess admin asks Codex to find a kid, parent, family, enrollment, subscription, invoice, or cohort; edit the Recess Village map or manage store-catalog availability; search the curated Content Library; inspect or change a school kid's tier and capability gates; upload a kid's MAP Growth report; pause or resume billing; refund or credit an invoice item; extend a trial; cancel or restore a subscription; register or unregister a cohort against an enrollment; switch or move kids from one cohort to another; manage guide payout invoices (biweekly pay-cycle line-item changes, invoice status moves, payout recipient lookups); run class operations (take attendance, cancel or reschedule a class session, add a one-off session, end a cohort, pause cohort billing, email a cohort's families, approve or deny pending registrations); process class-cancellation credits (the "Please credit these students accordingly" Slack message — credit every registered kid for a guide-canceled session); or author learning content — build, validate, publish, and loss-safely patch a deterministic GoalTemplate, apply a template to a kid or a roster, create a goal directly on a kid, write a Mesa draft or goal workspace, capture a template snapshot, and read Mesa workspace or snapshot files.
+description: Safely perform Recess staff administration through the recess CLI. Use when a Recess admin asks Codex to find a kid, parent, family, enrollment, subscription, invoice, or cohort; provision a new GUIDE staff account and email its sign-in invite (or resend one); edit the Recess Village map or manage store-catalog availability; search the curated Content Library; inspect or change a school kid's tier and capability gates; upload a kid's MAP Growth report; pause or resume billing; refund or credit an invoice item; extend a trial; cancel or restore a subscription; register or unregister a cohort against an enrollment; switch or move kids from one cohort to another; manage guide payout invoices (biweekly pay-cycle line-item changes, invoice status moves, payout recipient lookups); run class operations (take attendance, cancel or reschedule a class session, add a one-off session, end a cohort, pause cohort billing, email a cohort's families, approve or deny pending registrations); process class-cancellation credits (the "Please credit these students accordingly" Slack message — credit every registered kid for a guide-canceled session); or author learning content — build, validate, publish, and loss-safely patch a deterministic GoalTemplate, apply a template to a kid or a roster, create a goal directly on a kid, write a Mesa draft or goal workspace, capture a template snapshot, and read Mesa workspace or snapshot files.
 # Bundle version. Bump on every substantive edit; the CLI reports it and `doctor`
 # compares it against the served copy to tell an operator a refresh is available.
-version: 1.4.4
+version: 1.5.0
 # The lowest `recess` version this bundle is safe to install onto. Raise it ONLY
 # when the bundle documents a command, flag, or changed semantic that an older
 # binary does not have — an older CLI keeps its bundled copy instead of taking
 # this one. Prose, formatting, and Gotcha edits must NOT raise it; that is the
 # whole point of serving the bundle.
-minCliVersion: 1.3.3
+minCliVersion: 1.4.0
 ---
 
 # Recess CLI (`recess`)
@@ -51,6 +51,9 @@ Never infer approval from the original task, prior approval, urgency, or a succe
 | `invoices refund … --who-pays recess` | Recess absorbs the cost instead of the guide |
 | `cohorts end --cancel-subscriptions` | sets EVERY active enrollment's Stripe subscription to cancel at period end |
 | `cohorts email` | real outward email blast to families (include the recipient count from `cohorts parent-emails`) |
+| `guides create` | mints a staff-privileged GUIDE account (the `/admin` gate admits GUIDE) and by default emails the sign-in invite; quote the exact email address — the address IS the credential handle for passwordless login |
+| `guides invite` | real outward email to the previewed recipient telling them their account is live; quote `details.to` |
+| `guardians invite` | grants a new email address FULL guardian access over an existing family's kids and by default emails the sign-in invite; quote the previewed `details.familyName` + kid list and the exact email address |
 | `events cancel` | family-facing fan-out: chat messages, parent email blast, credit-owed notes, Slack |
 | `payout invoices set-status` to `OPEN`/`PAID`/`CANCELED` | moves real account balances; `--send-email` additionally emails the guide |
 | destructive `goal-templates patch-spec` | removes subjects, recipes, plans, queue items, source URLs, or missing-coverage records from a global template; quote the exact `details.safety.removed` inventory and hashes, then use the fresh token only after approval |
@@ -155,6 +158,14 @@ recess --json users tier set <kid-id> --tier <id> [--slots N] \
 recess --json enrollments list --user <user-id>
 recess --json enrollments get-for-subscription --subscription <id>
 
+# Guide staff accounts (ADMIN-only; both send outward email by default)
+recess --json guides create --email <email> --first-name TEXT [--last-name TEXT] [--no-invite] [--confirm]
+recess --json guides invite --user <user-id> [--confirm]
+
+# Invite a guardian into an EXISTING family (ADMIN-only; outward email by default;
+# the preview names the family + kids — verify them before requesting approval)
+recess --json guardians invite --family <family-id> --email <email> --first-name TEXT [--last-name TEXT] [--no-invite] [--confirm]
+
 # Billing & subscriptions (reference/billing.md)
 recess --json subscriptions list --family <family-id> [--kid <kid-id>]
 recess --json invoices list --subscription <subscription-id>
@@ -500,3 +511,4 @@ Dated, newest last. Add an entry every time reality surprises you.
 - 2026-08-05 — **`set-metadata --output-template-file` edits an AI_CHAT template's `outputTemplate`** (the goal-description payload DailyTodoGeneration consumes for description-only goals). Like `--agent-instructions-file`, it reads a local file and the server bumps the version + freezes a `GoalTemplateVersion` row. Editing a template never rewrites goals already created from it — the description was copied at goal-creation time; re-apply or edit live goals separately.
 - 2026-08-05 — **Content Library search now has a content/Pipeline-read-only CLI command.** `content-library search <query> [--limit 8]` calls the same hybrid/vector + rerank `/agent/search` funnel as Rocky's `search_gem_library`, returns the full fit/gist/coverage payload, and attributes the funnel's standard `offered` telemetry to `admin-cli`. It cannot inspect, ingest, file requests, curate, or edit the Pipeline; the permanent library token stays on the web server.
 - 2026-08-07 — **Village store goods do not live in the Village database.** They are ordinary main-Recess `StoreItem` rows with `itemType=VILLAGE_ITEM`; use `store-items list --item-type VILLAGE_ITEM` and the confirmation-gated `store-items set-status`, while `village models …` remains the separate Village-island map/model boundary. `set-status` refuses non-Village IDs and its live preflight names the item, current status, purchase count, and feed consequence before approval. A checked-in seed still owns fresh-database defaults, so an operational status edit does not replace updating that seed when the product default itself changes.
+- 2026-08-11 — **An external bundle leaf does not infer its grade answer from `availableWhen`.** When an `EXTERNAL_SKILL_QUEUE_SETUP` recipe has grade-specific plans and the shared wizard step is not named `grade`, set `handler.config.gradeLevelStepKey` to that exact step key. The server preview can validate without this optional binding, but apply dry-run then returns `No plan matched subject="…"`. Compare the new leaf with a working grade-bound sibling and dry-run the exact answers before calling the template finished.