recess-cli 1.7.0 → 1.9.0

package/README.md

@@ -1,6 +1,6 @@
 # Recess CLI
 
-`recess-cli` is the typed, agent-friendly command layer for Recess operations. ADMIN accounts receive the full staff surface; GUARDIAN accounts with `access:ai` receive family-scoped class schedules, progress, goals, todos, memories, Rocky configuration, learning research, GoalTemplate, and goal-content commands. It uses the web-server OpenAPI document, authenticates through Recess SSO, emits stable JSON, and refuses live writes until the exact command is rerun with `--confirm` after human approval.
+`recess-cli` is the typed, agent-friendly command layer for Recess operations. ADMIN accounts receive the full staff surface; GUARDIAN accounts with `access:ai` receive family-scoped class schedules, progress, goals, todos, memories, Rocky configuration, learning research, GoalTemplate, and goal-content commands; GUIDE accounts receive that same student surface for the students they hold an ACTIVE tutor assignment to — not their wider class roster. It uses the web-server OpenAPI document, authenticates through Recess SSO, emits stable JSON, and refuses live writes until the exact command is rerun with `--confirm` after human approval.
 
 ## Install (no checkout needed)
 
@@ -11,7 +11,7 @@ npm install -g recess-cli
 recess setup
 ```
 
-`setup` installs the bundled skill for both Codex and Claude and then opens Recess SSO in your browser (skip the browser step with `--skill-only`; it is also skipped when a live session already exists). Restart your agent afterwards so it discovers the skill. `npx -y recess-cli setup` works too, but leaves no `recess` on your PATH — which is the command the installed skill tells the agent to run — so `setup` warns when it detects it is running from an npx cache.
+`setup` installs the bundled skill in the Codex and Claude Code user directories, which Cursor also discovers for compatibility, and then opens Recess SSO in your browser (skip the browser step with `--skill-only`; it is also skipped when a live session already exists). Restart your agent afterwards so it discovers the skill. `npx -y recess-cli setup` works too, but leaves no `recess` on your PATH — which is the command the installed skill tells the agent to run — so `setup` warns when it detects it is running from an npx cache.
 
 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`.
 
@@ -47,6 +47,38 @@ recess --json auth login
 recess --json doctor
 ```
 
+## Testing against a local server
+
+`auth login` opens production SSO, so local iteration uses the env-cookie hatch instead:
+
+```bash
+export RECESS_CLI_API_ORIGIN=http://localhost:5068
+export RECESS_CLI_COOKIE='recess.auth-token=<signed-value>'
+recess --json doctor
+```
+
+To mint `<signed-value>`: sign `{sub, role, cliScope}` with the server's `JWT_SECRET` (audience = `CLIENT_ORIGIN`), then sign THAT string with `cookie.signerFactory(COOKIE_SECRET)` from `@fastify/cookie`. Two traps, both silent:
+
+- `@fastify/jwt` reads the auth cookie with `signed: true`, so a **bare JWT is rejected as "missing token"** before it is ever verified — the `@fastify/cookie` signature is not optional.
+- A **stored identity from a previous `auth login` does not describe an env-cookie session** (it may even be a different person on a different environment). Commands that branch on role ask the server whenever `authSource !== "config"`.
+
+Real SSO against a local server instead needs an `OAuthClient` row in the local database with `approved && adminCliEnabled` and redirect `http://127.0.0.1:8765/callback`, passed via `RECESS_CLI_OAUTH_CLIENT_ID`.
+
+## Interactive console (`recess ui`)
+
+```bash
+recess ui
+```
+
+A terminal console for the human half of the job: roster on the left (live-session dot, today's
+todo bar, XP, active goals), detail on the right (today's numbers, what they're working on right
+now, recent daily summaries). Refreshes every 30s. Keys: `↑↓`/`jk` move, `/` filter, `r` refresh,
+`q` quit. It is scope-aware — an ADMIN sees every student, a GUIDE sees the students they are
+actively assigned to.
+
+`ui` deliberately never touches the `--json` path: agents parse stdout, so the TUI runs before the
+JSON envelope and writes only to the terminal.
+
 ## JSON contract
 
 With `--json`, stdout contains only one JSON object.
@@ -119,6 +151,8 @@ separate `village models` commands edit the Village island's reusable models and
 ```bash
 recess --json skills guardian get recess-goal-authoring --all-references
 recess --json content-library search "fractions through visual puzzles" --limit 8
+recess --json content-library status <gem-id-or-url>
+recess --json content-library set-stage <gem-id-or-url...> --stage archived
 recess --json goal-templates validate-spec --file ./template.json   # iterate; writes nothing
 recess --json goal-templates create --file ./template.json          # preview, exit 2
 recess --json goal-templates create --file ./template.json --confirm
@@ -133,6 +167,27 @@ recess --json goals create --student <kid-id> --draft <draft-slug> --title "..."
 recess --json goals files list --student <kid-id> --goal <goal-id>
 ```
 
+ADMIN discovery batches use the same Content Library admission door as the dashboard. Omit
+`--confirm` to preview the exact payload first. An interactive run asks for Review or polish with
+Review preselected; JSON/non-interactive runs safely default to Review. Use `--stage polish` to
+start automatic decoration immediately:
+
+```bash
+recess --json content-library submit https://example.org/activity --stage review
+recess --json content-library submit --file ./gems.json
+recess --json content-library submit --file ./urls.txt --stage polish --confirm
+```
+
+JSON files are arrays of URL strings or `{ "url", "title"?, "summary"?, "lane"? }` objects;
+plain-text files contain one URL per line. The server checks that the deployed island understands
+the review/polish lifecycle before sending any item, and then writes with concurrency three.
+`content-library status` accepts an exact gem ID (including one returned by search) or URL and
+reports its Review/Polishing/Live/Archived stage plus metadata, cover, and search-index progress.
+`content-library set-stage` accepts one or many IDs/URLs (or a newline/JSON-string-array `--file`),
+previews every resolved current stage, and requires `--confirm`. It uses the same lifecycle as
+Manage: direct-to-Live routes unfinished gems through Polishing, and moving out of Polishing
+cancels that exact run first.
+
 ## Family AI operations
 
 ```bash

package/dist/cli.js

@@ -130,6 +130,13 @@ Usage:
   recess [--json] store-items set-status <village-store-item-id>
     --status ACTIVE|INACTIVE|COMING_SOON [--confirm]
   recess [--json] content-library search <query> [--limit 8]
+  recess [--json] content-library status <gem-id-or-url>
+  recess [--json] content-library set-stage <gem-id-or-url...> [--file <path>]
+    --stage review|polishing|live|archived [--confirm]
+  recess [--json] content-library submit <url...> [--file <path>]
+    [--stage review|polish] [--title TEXT] [--summary TEXT]
+    [--lane web-toys|mechanics|explorables|data-stories|sims|maps-scale|sound-art|puzzles|wonder|idea-games]
+    [--confirm]
   recess [--json] skills guardian list [--query TEXT] [--category TEXT]
   recess [--json] skills guardian get <skill-name>
     [--reference NAME | --all-references] [--refresh]
@@ -148,7 +155,9 @@ Usage:
     [--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>]
+    [--sort-order N] [--is-starter true|false]
+    [--setup-audience KID_FRIENDLY|PARENT_SETUP] [--kind SIMPLE|BLUEPRINT]
+    [--agent-instructions-file <path>]
     [--output-template-file <path>] [--confirm]
   recess [--json] goal-templates delete <template-id> --expected-version N [--confirm]
   recess [--json] goal-templates snapshot-files <template-id> [--path P]
@@ -187,8 +196,8 @@ Usage:
     [--path uploads/name.pdf] [--message TEXT]
     [--confirm --approval-token TOKEN]
 
-Authoring notes: "skills" serves the in-product tutor skills (the PRIVATE
-packages/skills submodule) read-only over your admin session — they are never
+Authoring notes: "skills" serves the in-product tutor skills (the private
+packages/skills workspace package) 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
@@ -627,6 +636,25 @@ const STORE_ITEM_SORT_FIELDS = [
     "updatedAt",
     "order",
 ];
+const CONTENT_LIBRARY_STAGES = ["review", "polish"];
+const CONTENT_LIBRARY_RESOURCE_STAGES = [
+    "review",
+    "polishing",
+    "live",
+    "archived",
+];
+const CONTENT_LIBRARY_DISCOVERY_LANES = [
+    "web-toys",
+    "mechanics",
+    "explorables",
+    "data-stories",
+    "sims",
+    "maps-scale",
+    "sound-art",
+    "puzzles",
+    "wonder",
+    "idea-games",
+];
 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 —
@@ -663,6 +691,215 @@ async function readJsonFile(filePath, label) {
     }
     return parsed;
 }
+function contentLibrarySubmitItem(value, label) {
+    const record = typeof value === "string"
+        ? { url: value }
+        : value && typeof value === "object" && !Array.isArray(value)
+            ? value
+            : null;
+    if (!record) {
+        throw new CliError("invalid_arguments", `${label} must be a URL string or an object with url and optional title, summary, and lane.`);
+    }
+    const allowed = new Set(["url", "title", "summary", "lane"]);
+    const unknown = Object.keys(record).filter((key) => !allowed.has(key));
+    if (unknown.length) {
+        throw new CliError("invalid_arguments", `${label} has unsupported fields: ${unknown.join(", ")}.`);
+    }
+    const text = (key) => {
+        const raw = record[key];
+        if (raw === undefined)
+            return undefined;
+        if (typeof raw !== "string" || !raw.trim()) {
+            throw new CliError("invalid_arguments", `${label}.${key} must be a non-empty string.`);
+        }
+        return raw.trim();
+    };
+    const rawUrl = text("url");
+    if (!rawUrl) {
+        throw new CliError("invalid_arguments", `${label}.url is required.`);
+    }
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw new CliError("invalid_arguments", `${label}.url must be a valid http(s) URL.`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new CliError("invalid_arguments", `${label}.url must be a valid http(s) URL.`);
+    }
+    if (url.toString().length > 2_000) {
+        throw new CliError("invalid_arguments", `${label}.url must be at most 2000 characters.`);
+    }
+    const title = text("title");
+    const summary = text("summary");
+    const laneRaw = text("lane");
+    const lane = laneRaw
+        ? assertChoice(laneRaw, CONTENT_LIBRARY_DISCOVERY_LANES, `${label}.lane`)
+        : undefined;
+    if (title && title.length > 500) {
+        throw new CliError("invalid_arguments", `${label}.title must be at most 500 characters.`);
+    }
+    if (summary && summary.length > 4_000) {
+        throw new CliError("invalid_arguments", `${label}.summary must be at most 4000 characters.`);
+    }
+    return {
+        url: url.toString(),
+        ...(title ? { title } : {}),
+        ...(summary ? { summary } : {}),
+        ...(lane ? { lane } : {}),
+    };
+}
+async function readContentLibrarySubmitItems(parsed) {
+    const items = parsed.positionals
+        .slice(2)
+        .map((url, index) => contentLibrarySubmitItem(url, `URL ${index + 1}`));
+    const filePath = flagString(parsed, "file");
+    let file;
+    if (filePath) {
+        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", `Content Library input file does not exist: ${absolutePath}`);
+            }
+            throw error;
+        }
+        const trimmed = raw.trim();
+        if (!trimmed) {
+            throw new CliError("invalid_arguments", `Content Library input file is empty: ${absolutePath}`);
+        }
+        let entries;
+        if (trimmed.startsWith("[")) {
+            let parsedFile;
+            try {
+                parsedFile = JSON.parse(trimmed);
+            }
+            catch (error) {
+                throw new CliError("invalid_arguments", `Content Library input file is not valid JSON (${absolutePath}): ${error instanceof Error ? error.message : String(error)}`);
+            }
+            if (!Array.isArray(parsedFile)) {
+                throw new CliError("invalid_arguments", `Content Library JSON input must be an array (${absolutePath}).`);
+            }
+            entries = parsedFile;
+        }
+        else {
+            entries = raw
+                .split(/\r?\n/)
+                .map((line) => line.trim())
+                .filter((line) => line && !line.startsWith("#"));
+        }
+        items.push(...entries.map((entry, index) => contentLibrarySubmitItem(entry, `File item ${index + 1}`)));
+        file = {
+            absolutePath,
+            sizeBytes: Buffer.byteLength(raw),
+            sha256: createHash("sha256").update(raw).digest("hex"),
+        };
+    }
+    if (items.length === 0) {
+        throw new CliError("invalid_arguments", "Pass at least one URL as an argument or through --file.");
+    }
+    if (items.length > 500) {
+        throw new CliError("invalid_arguments", "Content Library submit accepts at most 500 items per confirmed batch.");
+    }
+    const title = flagString(parsed, "title");
+    const summary = flagString(parsed, "summary");
+    const laneRaw = flagString(parsed, "lane");
+    if ((title || summary || laneRaw) && items.length !== 1) {
+        throw new CliError("invalid_arguments", "--title, --summary, and --lane apply to one URL only; use JSON objects in --file for per-item metadata.");
+    }
+    if (items.length === 1 && (title || summary || laneRaw)) {
+        items[0] = contentLibrarySubmitItem({
+            ...items[0],
+            ...(title ? { title } : {}),
+            ...(summary ? { summary } : {}),
+            ...(laneRaw ? { lane: laneRaw } : {}),
+        }, "Submitted item");
+    }
+    return { items, ...(file ? { file } : {}) };
+}
+function contentLibraryGemTarget(value, label) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new CliError("invalid_arguments", `${label} must be an exact resource ID or http(s) URL.`);
+    }
+    const target = value.trim();
+    if (UUID_RE.test(target))
+        return target;
+    let url;
+    try {
+        url = new URL(target);
+    }
+    catch {
+        throw new CliError("invalid_arguments", `${label} must be an exact resource ID or http(s) URL. Use content-library search to find a live gem's ID.`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new CliError("invalid_arguments", `${label} must be an exact resource ID or http(s) URL.`);
+    }
+    if (url.toString().length > 2_000) {
+        throw new CliError("invalid_arguments", `${label} must be at most 2000 characters.`);
+    }
+    return url.toString();
+}
+async function readContentLibraryGemTargets(parsed) {
+    const gems = parsed.positionals
+        .slice(2)
+        .map((value, index) => contentLibraryGemTarget(value, `Gem ${index + 1}`));
+    const filePath = flagString(parsed, "file");
+    let file;
+    if (filePath) {
+        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", `Content Library gem file does not exist: ${absolutePath}`);
+            }
+            throw error;
+        }
+        const trimmed = raw.trim();
+        if (!trimmed) {
+            throw new CliError("invalid_arguments", `Content Library gem file is empty: ${absolutePath}`);
+        }
+        let entries;
+        if (trimmed.startsWith("[")) {
+            let parsedFile;
+            try {
+                parsedFile = JSON.parse(trimmed);
+            }
+            catch (error) {
+                throw new CliError("invalid_arguments", `Content Library gem file is not valid JSON (${absolutePath}): ${error instanceof Error ? error.message : String(error)}`);
+            }
+            if (!Array.isArray(parsedFile)) {
+                throw new CliError("invalid_arguments", `Content Library gem JSON input must be an array (${absolutePath}).`);
+            }
+            entries = parsedFile;
+        }
+        else {
+            entries = raw
+                .split(/\r?\n/)
+                .map((line) => line.trim())
+                .filter((line) => line && !line.startsWith("#"));
+        }
+        gems.push(...entries.map((entry, index) => contentLibraryGemTarget(entry, `File gem ${index + 1}`)));
+        file = {
+            absolutePath,
+            sizeBytes: Buffer.byteLength(raw),
+            sha256: createHash("sha256").update(raw).digest("hex"),
+        };
+    }
+    if (gems.length === 0) {
+        throw new CliError("invalid_arguments", "Pass at least one gem ID or URL as an argument or through --file.");
+    }
+    if (gems.length > 500) {
+        throw new CliError("invalid_arguments", "Content Library set-stage accepts at most 500 gems per confirmed batch.");
+    }
+    return { gems, ...(file ? { file } : {}) };
+}
 async function readGoalTemplateSpecPatches(filePath) {
     const { absolutePath, raw, parsed } = await readJsonValue(filePath, "Goal-template patch file");
     if (!Array.isArray(parsed) || parsed.length === 0) {
@@ -2444,7 +2681,60 @@ export async function runCommand(argv) {
                 params: { query: { q: query, limit } },
             }));
         }
-        throw new CliError("invalid_arguments", "Use content-library search.");
+        if (verb === "status") {
+            const gem = contentLibraryGemTarget(positional(parsed, 2, "gem id or URL"), "Gem");
+            return unwrap(await api.client.GET("/admin/content-library/status", {
+                params: { query: { gem } },
+            }));
+        }
+        if (verb === "set-stage") {
+            const stage = assertChoice(flagString(parsed, "stage", { required: true }), CONTENT_LIBRARY_RESOURCE_STAGES, "--stage");
+            const input = await readContentLibraryGemTargets(parsed);
+            const preflightBody = {
+                gems: input.gems,
+                stage,
+                dryRun: true,
+            };
+            const preflight = unwrap(await api.client.POST("/admin/content-library/transition", {
+                body: preflightBody,
+            }));
+            const preview = {
+                action: "content-library.set-stage",
+                target: { stage, resourceCount: preflight.results.length },
+                request: { gems: input.gems, stage },
+                details: {
+                    resources: preflight.results,
+                    lifecycle: "Uses the same lifecycle as Manage. Direct-to-Live never bypasses unfinished polishing; leaving Polishing cancels its bound run before moving.",
+                    concurrency: 3,
+                    ...(input.file ? { inputFile: input.file } : {}),
+                },
+            };
+            return writeCommand(parsed, preview, async () => unwrap(await api.client.POST("/admin/content-library/transition", {
+                body: { gems: input.gems, stage, dryRun: false },
+            })));
+        }
+        if (verb === "submit") {
+            const stage = assertChoice(flagString(parsed, "stage") ?? "review", CONTENT_LIBRARY_STAGES, "--stage");
+            const input = await readContentLibrarySubmitItems(parsed);
+            const body = { stage, items: input.items };
+            const preview = {
+                action: "content-library.submit",
+                target: { stage, resourceCount: input.items.length },
+                request: body,
+                details: {
+                    admission: stage === "polish"
+                        ? "Starts automatic decoration; the island promotes each successful resource to LIVE after the polish and deterministic tail finish."
+                        : "Holds each new resource in REVIEW until an admin approves it.",
+                    duplicateBehavior: "Existing URLs are returned as duplicates and are not overwritten.",
+                    deployOrderFence: "The server verifies the island's review/polish lifecycle capability before its first write.",
+                    ...(input.file ? { inputFile: input.file } : {}),
+                },
+            };
+            return writeCommand(parsed, preview, async () => unwrap(await api.client.POST("/admin/content-library/submit", {
+                body,
+            })));
+        }
+        throw new CliError("invalid_arguments", "Use content-library search, status, set-stage, or submit.");
     }
     if (noun === "goal-templates") {
         if (verb === "list") {
@@ -2659,6 +2949,11 @@ export async function runCommand(argv) {
             const tags = flagString(parsed, "tags");
             const kind = flagString(parsed, "kind");
             const sortOrder = flagNumber(parsed, "sort-order");
+            const isStarterRaw = flagString(parsed, "is-starter");
+            const setupAudienceRaw = flagString(parsed, "setup-audience");
+            const isStarter = isStarterRaw === undefined
+                ? undefined
+                : assertChoice(isStarterRaw, ["true", "false"], "--is-starter") === "true";
             const body = {
                 expectedVersion,
                 ...(flagString(parsed, "title")
@@ -2682,6 +2977,12 @@ export async function runCommand(argv) {
                     }
                     : {}),
                 ...(sortOrder === undefined ? {} : { sortOrder }),
+                ...(isStarter === undefined ? {} : { isStarter }),
+                ...(setupAudienceRaw
+                    ? {
+                        setupAudience: assertChoice(setupAudienceRaw, GOAL_TEMPLATE_SETUP_AUDIENCES, "--setup-audience"),
+                    }
+                    : {}),
                 ...(kind
                     ? { kind: assertChoice(kind, GOAL_TEMPLATE_KINDS, "--kind") }
                     : {}),
@@ -2701,7 +3002,7 @@ export async function runCommand(argv) {
             // 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, --output-template-file).");
+                throw new CliError("invalid_arguments", "Pass at least one field to change (--title, --description, --emoji, --category, --tags, --sort-order, --is-starter, --setup-audience, --kind, --agent-instructions-file, --output-template-file).");
             }
             return writeCommand(parsed, {
                 action: "update goal template metadata (never its setupWorkflowSpec)",
@@ -3024,6 +3325,19 @@ export async function runCommand(argv) {
     }
     if (noun === "students") {
         if (verb === "list") {
+            // A guide has no family — their roster is the students they are
+            // actively assigned to, which the tutor surface already scopes. The
+            // stored identity is absent on an env-cookie session, so fall back to
+            // asking the server who this session belongs to.
+            // The stored identity only describes a `auth login` session; an
+            // env-cookie session may belong to someone else entirely, so ask the
+            // server rather than trusting a stale login.
+            const role = api.config.authSource === "config"
+                ? api.config.user?.role
+                : (await api.client.GET("/auth/admin-cli/session/")).data?.user.role;
+            if (role === "GUIDE") {
+                return unwrap(await api.client.GET("/tutor/students", {}));
+            }
             return unwrap(await api.client.GET("/family/kids", {
                 params: { query: { includeSelf: "false" } },
             }));

package/dist/index.js

@@ -1,9 +1,62 @@
 #!/usr/bin/env node
+import { createInterface } from "node:readline/promises";
+import { parseArgs } from "./args.js";
 import { runCommand } from "./cli.js";
 import { CliError } from "./errors.js";
-const json = process.argv.slice(2).includes("--json");
+async function withInteractiveAdmissionStage(args) {
+    const parsed = parseArgs(args);
+    if (parsed.flags.has("json") ||
+        parsed.flags.has("help") ||
+        parsed.flags.has("stage") ||
+        parsed.positionals[0] !== "content-library" ||
+        parsed.positionals[1] !== "submit" ||
+        !process.stdin.isTTY ||
+        !process.stderr.isTTY) {
+        return args;
+    }
+    const terminal = createInterface({
+        input: process.stdin,
+        output: process.stderr,
+        terminal: true,
+    });
+    try {
+        while (true) {
+            const answer = (await terminal.question("Admission stage [Review/polish] (Review): "))
+                .trim()
+                .toLowerCase();
+            if (!answer || answer === "r" || answer === "review") {
+                return [...args, "--stage", "review"];
+            }
+            if (answer === "p" || answer === "polish") {
+                return [...args, "--stage", "polish"];
+            }
+            process.stderr.write("Choose Review or polish.\n");
+        }
+    }
+    finally {
+        terminal.close();
+    }
+}
+const argv = await withInteractiveAdmissionStage(process.argv.slice(2));
+const json = argv.includes("--json");
+// The interactive console owns the terminal, so it runs before the JSON
+// envelope machinery rather than through it.
+if (argv[0] === "ui") {
+    const { runUi } = await import("./ui/index.js");
+    try {
+        await runUi();
+        process.exit(0);
+    }
+    catch (error) {
+        const cliError = error instanceof CliError
+            ? error
+            : new CliError("unexpected_error", error instanceof Error ? error.message : String(error));
+        process.stderr.write(`Error: ${cliError.message}\n`);
+        process.exit(cliError.exitCode);
+    }
+}
 try {
-    const data = await runCommand(process.argv.slice(2));
+    const data = await runCommand(argv);
     if (typeof data === "object" && data && "help" in data && !json) {
         process.stdout.write(`${String(data.help)}\n`);
     }

package/dist/ui/app.js

@@ -0,0 +1,127 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Box, Text, useApp, useInput } from "ink";
+import { useCallback, useEffect, useState } from "react";
+const REFRESH_MS = 30_000;
+function relative(iso) {
+    if (!iso)
+        return "never";
+    const deltaMin = Math.round((Date.now() - new Date(iso).getTime()) / 60_000);
+    if (deltaMin < 1)
+        return "just now";
+    if (deltaMin < 60)
+        return `${deltaMin}m ago`;
+    const hours = Math.round(deltaMin / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    return `${Math.round(hours / 24)}d ago`;
+}
+/** done/total as a compact bar — the fastest read on "is today on track". */
+function todoBar(done, total) {
+    if (total === 0)
+        return "·".repeat(5);
+    const filled = Math.round((done / total) * 5);
+    return "█".repeat(filled) + "░".repeat(5 - filled);
+}
+export function App({ api }) {
+    const { exit } = useApp();
+    const [session, setSession] = useState(null);
+    const [rows, setRows] = useState([]);
+    const [summaries, setSummaries] = useState(null);
+    const [cursor, setCursor] = useState(0);
+    const [filter, setFilter] = useState("");
+    const [filtering, setFiltering] = useState(false);
+    const [error, setError] = useState(null);
+    const [loadedAt, setLoadedAt] = useState(null);
+    const visible = rows.filter((r) => filter ? r.name.toLowerCase().includes(filter.toLowerCase()) : true);
+    const selected = visible[Math.min(cursor, visible.length - 1)];
+    const loadRoster = useCallback(async () => {
+        try {
+            const [sessionRes, rosterRes] = await Promise.all([
+                api.client.GET("/auth/admin-cli/session/"),
+                api.client.GET("/tutor/students", {}),
+            ]);
+            const s = sessionRes.data;
+            if (s) {
+                setSession({
+                    role: s.user.role,
+                    cliScope: s.cliScope,
+                    name: [s.user.firstName, s.user.lastName].filter(Boolean).join(" "),
+                });
+            }
+            const items = (rosterRes.data?.items ?? []);
+            setRows(items);
+            setLoadedAt(new Date());
+            setError(null);
+        }
+        catch (err) {
+            setError(err instanceof Error ? err.message : String(err));
+        }
+    }, [api]);
+    useEffect(() => {
+        void loadRoster();
+        const timer = setInterval(() => void loadRoster(), REFRESH_MS);
+        return () => clearInterval(timer);
+    }, [loadRoster]);
+    // Detail is fetched per selection rather than up front: a roster of 40
+    // students would otherwise fire 40 requests nobody asked for.
+    useEffect(() => {
+        let cancelled = false;
+        setSummaries(null);
+        if (!selected)
+            return;
+        void (async () => {
+            try {
+                const res = await api.client.GET("/tutor/students/{studentId}/daily-summaries", { params: { path: { studentId: selected.userId } } });
+                if (cancelled)
+                    return;
+                const data = res.data;
+                setSummaries(data?.items?.slice(0, 3) ?? []);
+            }
+            catch {
+                if (!cancelled)
+                    setSummaries([]);
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [api, selected?.userId]);
+    useInput((input, key) => {
+        if (filtering) {
+            if (key.return || key.escape) {
+                setFiltering(false);
+                return;
+            }
+            if (key.backspace || key.delete) {
+                setFilter((f) => f.slice(0, -1));
+                return;
+            }
+            if (input)
+                setFilter((f) => f + input);
+            return;
+        }
+        if (input === "q" || key.escape)
+            exit();
+        if (input === "r")
+            void loadRoster();
+        if (input === "/") {
+            setFilter("");
+            setFiltering(true);
+        }
+        if (key.downArrow || input === "j") {
+            setCursor((c) => Math.min(c + 1, Math.max(visible.length - 1, 0)));
+        }
+        if (key.upArrow || input === "k")
+            setCursor((c) => Math.max(c - 1, 0));
+    });
+    const liveCount = rows.filter((r) => r.liveSession).length;
+    return (_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsxs(Box, { justifyContent: "space-between", children: [_jsxs(Text, { children: [_jsx(Text, { bold: true, color: "cyan", children: "recess" }), _jsxs(Text, { dimColor: true, children: [" ", session
+                                        ? `${session.name} · ${session.role} · ${session.cliScope}`
+                                        : "connecting…"] })] }), _jsxs(Text, { dimColor: true, children: [rows.length, " students", liveCount > 0 ? ` · ${liveCount} live` : "", loadedAt ? ` · ${loadedAt.toLocaleTimeString()}` : ""] })] }), error ? (_jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "red", children: error }) })) : null, _jsxs(Box, { marginTop: 1, children: [_jsxs(Box, { flexDirection: "column", width: "55%", children: [_jsxs(Text, { dimColor: true, children: ["STUDENT".padEnd(22), "TODAY".padEnd(8), "XP".padEnd(6), "GOALS"] }), visible.length === 0 ? (_jsx(Text, { dimColor: true, children: rows.length === 0 ? "no students in scope" : "no match" })) : null, visible.map((row, index) => {
+                                const active = row.userId === selected?.userId;
+                                return (_jsxs(Text, { inverse: active, color: row.liveSession ? "green" : undefined, children: [`${row.liveSession ? "●" : " "} ${row.name}`
+                                            .slice(0, 21)
+                                            .padEnd(22), `${todoBar(row.todosToday.done, row.todosToday.total)}`.padEnd(8), `${row.todayXp}`.padEnd(6), `${row.activeGoalCount}`] }, row.userId));
+                            })] }), _jsx(Box, { flexDirection: "column", width: "45%", paddingLeft: 2, children: selected ? (_jsxs(_Fragment, { children: [_jsx(Text, { bold: true, children: selected.name }), _jsxs(Text, { dimColor: true, children: ["last active ", relative(selected.lastActiveAt)] }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsxs(Text, { children: ["todos today", " ", _jsxs(Text, { bold: true, children: [selected.todosToday.done, "/", selected.todosToday.total] }), "   ", "xp ", _jsx(Text, { bold: true, children: selected.todayXp })] }), _jsxs(Text, { children: ["active goals ", _jsx(Text, { bold: true, children: selected.activeGoalCount }), "   ", "modules done", " ", _jsx(Text, { bold: true, children: selected.modulesCompleted })] })] }), selected.liveSession ? (_jsx(Box, { marginTop: 1, children: _jsxs(Text, { color: "green", children: ["\u25CF working on ", selected.liveSession.todoTitle, " (", relative(selected.liveSession.startedAt), ")"] }) })) : null, _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { dimColor: true, children: "RECENT SUMMARIES" }), summaries === null ? _jsx(Text, { dimColor: true, children: "loading\u2026" }) : null, summaries?.length === 0 ? _jsx(Text, { dimColor: true, children: "none" }) : null, summaries?.map((s) => (_jsxs(Text, { children: [(s.summaryDate ?? "").slice(0, 10), " ", _jsx(Text, { dimColor: true, children: s.status ?? "" }), " ", (s.smsNotification ?? "").slice(0, 40)] }, s.id)))] })] })) : (_jsx(Text, { dimColor: true, children: "select a student" })) })] }), _jsx(Box, { marginTop: 1, children: filtering ? (_jsxs(Text, { children: ["filter: ", _jsx(Text, { bold: true, children: filter }), _jsx(Text, { dimColor: true, children: " (enter to apply, esc to stop)" })] })) : (_jsxs(Text, { dimColor: true, children: ["\u2191\u2193/jk move \u00B7 / filter", filter ? ` (${filter})` : "", " \u00B7 r refresh \u00B7 q quit"] })) })] }));
+}
+//# sourceMappingURL=app.js.map

package/dist/ui/index.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { render } from "ink";
+import { RecessAdminApi } from "../api.js";
+import { resolveConfig } from "../config.js";
+import { CliError } from "../errors.js";
+import { App } from "./app.js";
+/**
+ * The interactive console. Kept off the JSON path on purpose: agents parse
+ * stdout, so the TUI is only reachable through its own command and never
+ * writes an envelope.
+ */
+export async function runUi() {
+    const config = await resolveConfig();
+    if (!config.sessionCookie) {
+        throw new CliError("auth_required", "No Recess CLI session found. Run `recess auth login`.");
+    }
+    const api = new RecessAdminApi(config);
+    const instance = render(_jsx(App, { api: api }));
+    await instance.waitUntilExit();
+}
+//# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "recess-cli",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "Safe Recess administration and family AI tools from the command line.",
   "license": "UNLICENSED",
   "repository": {
@@ -26,11 +26,15 @@
     "access": "public"
   },
   "dependencies": {
-    "openapi-fetch": "^0.14.0"
+    "ink": "^7.1.1",
+    "openapi-fetch": "^0.14.0",
+    "react": "^19.2.8"
   },
   "devDependencies": {
     "@types/node": "^24.10.0",
+    "@types/react": "^19.2.18",
     "@typescript/native-preview": "7.0.0-dev.20251015.1",
+    "esbuild": "^0.28.2",
     "openapi-typescript": "^7.8.0",
     "oxlint": "^1.28.0",
     "oxlint-tsgolint": "^0.6.0",