recess-cli 1.4.0 → 1.7.0

package/README.md

@@ -1,8 +1,8 @@
 # Recess CLI
 
-`recess-cli` is the typed, agent-friendly command layer for Recess staff operations. It uses the web-server OpenAPI document, authenticates admins 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. 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 (staff — no checkout needed)
+## Install (no checkout needed)
 
 Published to npm as [`recess-cli`](https://www.npmjs.com/package/recess-cli). On any machine with Node 20+:
 
@@ -25,7 +25,7 @@ pnpm --dir apps/admin-cli run client:generate
 pnpm --dir apps/admin-cli run install-persistent
 ```
 
-`install-persistent` copies a self-contained build (non-test `dist/` JS + the `openapi-fetch` runtime dep) to `~/.recess-cli/cli/` and points `~/.local/bin/recess` at it — the install keeps working after the checkout or worktree it was built from is deleted. Use it on any machine that operates on production. `install-local` instead symlinks `~/.local/bin/recess` straight to this checkout's `dist/index.js` so rebuilds are picked up live — use it only while actively developing the CLI, and expect the link to die with the worktree. Both targets install the bundled skill for Codex at `${CODEX_HOME:-~/.codex}/skills/recess-cli` and Claude at `${CLAUDE_CONFIG_DIR:-~/.claude}/skills/recess-cli`. The skill is a multi-file bundle: `skill/recess-cli/SKILL.md` carries the safety model, auth troubleshooting, JSON contract, and command quick reference, and routes to the deep workflow playbooks in `skill/recess-cli/reference/` (billing, MAP scores, payouts, class ops, onboarding, and goal authoring).
+`install-persistent` copies a self-contained build (non-test `dist/` JS + the `openapi-fetch` runtime dep) to `~/.recess-cli/cli/` and points `~/.local/bin/recess` at it — the install keeps working after the checkout or worktree it was built from is deleted. Use it on any machine that operates on production. `install-local` instead symlinks `~/.local/bin/recess` straight to this checkout's `dist/index.js` so rebuilds are picked up live — use it only while actively developing the CLI, and expect the link to die with the worktree. Both targets install the small shared router at `${CODEX_HOME:-~/.codex}/skills/recess-cli` and `${CLAUDE_CONFIG_DIR:-~/.claude}/skills/recess-cli`. That public npm bundle contains only authentication, JSON, confirmation, and audience-routing guidance. Guardian learning skills and staff-only operational skills/gotchas are fetched after login from separate permission-checked catalogs; they are not shipped in the package.
 
 ## One-time SSO setup
 
@@ -40,7 +40,7 @@ Create an approved `OAuthClient` row in each Recess environment. This remains a
 
 The production row ID (`c7e34138-18f9-45b1-a2fb-26a4e3a6d739`) is the CLI's built-in default, so production login needs no client-ID setup. `--client-id`, `RECESS_CLI_OAUTH_CLIENT_ID`, and a stored client ID remain overrides for local/staging clients. The web-server decodes the assertion audience, loads that exact `OAuthClient`, and requires both `approved` and `adminCliEnabled`; there is no separate server environment allowlist. Production redirect validation is exact, so a different callback port must also be explicitly registered.
 
-The browser SSO assertion is exchanged once and discarded. The CLI stores a separate 12-hour signed Recess admin session at `~/.recess-cli/config.json` with mode `0600`.
+The browser SSO assertion is exchanged once and discarded. The CLI stores a separate 12-hour signed Recess session at `~/.recess-cli/config.json` with mode `0600`. A guardian must hold the live `access:ai` permission; removing it immediately invalidates session checks. Guardian sessions cannot call `/admin` routes and every target is independently restricted to their family.
 
 ```bash
 recess --json auth login
@@ -54,13 +54,20 @@ With `--json`, stdout contains only one JSON object.
 Success:
 
 ```json
-{"ok":true,"data":{"results":[]}}
+{ "ok": true, "data": { "results": [] } }
 ```
 
 Error or write preview:
 
 ```json
-{"ok":false,"error":{"code":"confirmation_required","message":"...","details":{"preview":{},"requiredFlag":"--confirm"}}}
+{
+  "ok": false,
+  "error": {
+    "code": "confirmation_required",
+    "message": "...",
+    "details": { "preview": {}, "requiredFlag": "--confirm" }
+  }
+}
 ```
 
 Exit code `0` means success, `1` means an input/auth/API failure, and `2` means a write is awaiting explicit human confirmation.
@@ -83,7 +90,7 @@ Preview a write by omitting `--confirm`:
 recess --json billing pause --subscription <subscription-id> --until 2026-09-01
 ```
 
-After a human approves that exact preview, rerun the unchanged command with `--confirm`.
+After a human approves that exact preview, rerun the unchanged command with `--confirm`. File-backed family edits, deterministic template apply, and goal-content writes also return `details.approvalToken`; echo it with `--approval-token TOKEN`. The token covers the local bytes plus the server preflight/CAS state, so a changed file or goal produces a new preview instead of consuming stale approval.
 
 School tier writes require the `updatedAt` token from `users tier get`. Their read-only preflight
 shows `capabilitiesLockedNow`/`capabilitiesLockedAfter`, the resolved class allowance, current
@@ -110,19 +117,43 @@ separate `village models` commands edit the Village island's reusable models and
 ## Authoring learning content
 
 ```bash
-recess --json skills get os-v2-goal-template-builder --all-references
+recess --json skills guardian get recess-goal-authoring --all-references
 recess --json content-library search "fractions through visual puzzles" --limit 8
 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
 recess --json goal-templates patch-spec <id-or-slug> --expected-version 7 --patches-file ./patches.json
-recess --json mesa files write --student <kid-id> --draft <draft-slug> --source-dir ./workspace
+recess --json goals files write --student <kid-id> --draft <draft-slug> --source-dir ./goal-content
+recess --json goals pdf upload --student <kid-id> --draft <draft-slug> --source-file ./textbook.pdf
 recess --json goal-templates capture-snapshot <id-or-slug> --source-draft <draft-slug> --student <kid-id> --dry-run
 recess --json goal-templates apply <id-or-slug> --answers-file ./answers.json --dry-run
 recess --json goals create --student <kid-id> --title "..." --description-file ./goal.md
-recess --json mesa files list --student <kid-id> --goal <goal-id>
+recess --json goals create --student <kid-id> --draft <draft-slug> --title "..." \
+  --description-file ./goal.md --enable-applet-follow-ups
+recess --json goals files list --student <kid-id> --goal <goal-id>
 ```
 
+## Family AI operations
+
+```bash
+recess --json students list
+recess --json students today --student <kid-id>
+recess --json students schedule --student <kid-id> --days 30
+recess --json students xp-history --student <kid-id> --range month
+recess --json goals list --student <kid-id>
+recess --json todos create --student <kid-id> --title "Read chapter 4"
+recess --json memories context --student <kid-id>
+recess --json memories log --student <kid-id> --date 2026-08-12
+recess --json rocky get --student <kid-id>
+```
+
+All family writes still preview first. Goal/todo/Rocky edits also carry the current server version
+into the confirmed request. A guardian cannot target another family, inspect frozen/deleted
+template history, choose todo rewards/completion/internal fields, or use the ADMIN-only
+device-authorization flow. `memories context` and `memories log` read only the tutor repository's
+spine, rules, reminders, and session logs; private guide remarks are never returned. The CLI does
+not expose Postgres `UserMemory`.
+
 ## Keeping the agent skill current
 
 ```bash
@@ -131,34 +162,34 @@ recess --json doctor             # .skill reports whether a newer bundle exists
 recess --json setup --skill-only # bundled copy, then the served upgrade
 ```
 
-The CLI's own agent skill is **both** bundled in this package and served from
-`GET /admin/cli-skill/`. The bundled copy is the floor — it works offline, before a session exists,
+The CLI's small shared router skill is **both** bundled in this package and served from
+`GET /auth/admin-cli/skill/`. The bundled copy is the floor — it works offline, before a session exists,
 and always matches the installed binary; `postinstall` refreshes it on every `npm install -g`. The
-served copy is the upgrade: wording and Gotcha edits reach installed CLIs on the next deploy instead
-of the next npm release, fenced by the bundle's `minCliVersion` so an older binary keeps its bundled
+served copy is the upgrade: shared wording changes reach installed CLIs on the next deploy instead
+of the next npm release, fenced by the bundle manifest's `minCliVersion` so an older binary keeps its bundled
 copy rather than reading a skill written for a newer one. An unreachable server is never an error.
 
-`skills` (plural, a different thing) serves the in-product tutor skills — the same documents the `recess.gg/ai` agent loads —
-read-only over your admin session from the **private** `packages/skills` submodule. They are
-deliberately **not** bundled into this package, which is published publicly on npm: one source of
-truth, and a skills-repo update reaches CLI agents with no CLI release. Load
-`os-v2-goal-template-builder` before authoring; a spec that passes `validate-spec` is structurally
-valid, not good. Responses cache under `~/.recess-cli/skills-cache/` (`--refresh` re-fetches).
+`skills guardian list|get` serves family and goal-authoring guidance to `family_ai` and
+`full_admin` sessions. `skills admin list|get` serves the staff operational skill plus the live
+private tutor-skill registry and requires `full_admin`. The explicit audience is part of the command
+contract; `skills get` by itself is not valid. Responses cache under
+`~/.recess-cli/skills-cache/` (`--refresh` re-fetches).
 
 Every template created here is `setupMode: DETERMINISTIC_WORKFLOW` and **cannot be converted back**,
 so the confirmation gate is load-bearing. `create` runs a real server-side validation before the
 gate, so `preview.details` carries the handler, goal shape, wizard step keys, and spec inventory the
-*server* resolved rather than a client-side guess; `apply` runs the backend's own `dryRun` and
+_server_ resolved rather than a client-side guess; `apply` runs the backend's own `dryRun` and
 previews the per-student outcome. `set-metadata` and `delete` require `--expected-version` from
 `get`; a stale value 409s `STALE_WRITE` without writing. `set-metadata` cannot send a
 `setupWorkflowSpec` at all. Use `patch-spec` with a JSON array of bounded JSON-Pointer operations;
 it always runs the backend's guarded preview first and requires the preview's exact loss token in
 addition to `--confirm` when protected template data would be removed.
 
-MODULE_BACKED BLUEPRINT content is authored as a local workspace tree, batch-upserted to a named
-Mesa draft, then attached with `capture-snapshot`. Both mutations run server previews before the
-confirmation gate. Mesa upserts are compare-and-set against the previewed repo change; capture is
-fenced to both that source change and the template version. Direct live-goal `modules/` and
-`state/` writes are blocked because those files have database projections.
+Module-backed content is authored as a local workspace tree and batch-upserted to a named goal
+draft. For a personal one-off goal, `goals create --draft` validates and materializes that draft
+directly. For reusable content, attach it to a BLUEPRINT with `capture-snapshot`. Every mutation
+runs a server preview before the confirmation gate and is compare-and-set against the previewed
+revision. Direct live-goal `modules/` and `state/` writes remain blocked because those files have
+database projections.
 
 See `recess --help` for the complete command surface. The raw escape hatch is intentionally read-only: `recess --json request get /path`.

package/dist/api.js

@@ -14,7 +14,7 @@ export class RecessAdminApi {
     }
     requireAuth() {
         if (!this.config.sessionCookie) {
-            throw new CliError("auth_required", "No admin session found. Run `recess auth login`.");
+            throw new CliError("auth_required", "No Recess CLI session found. Run `recess auth login`.");
         }
     }
     async rawGet(path) {

package/dist/args.js

@@ -12,6 +12,8 @@ const BOOLEAN_FLAGS = new Set([
     "archived",
     "confirm",
     "dry-run",
+    "disable-applet-follow-ups",
+    "enable-applet-follow-ups",
     "full",
     "help",
     "immediate",

package/dist/auth.js

@@ -79,7 +79,7 @@ export async function login(config, options) {
         throw apiError(response.status, body);
     const pair = response.headers.get("set-cookie")?.split(";", 1)[0];
     if (!pair?.includes("=")) {
-        throw new CliError("auth_failed", "The Recess API did not return an admin session cookie.");
+        throw new CliError("auth_failed", "The Recess API did not return a CLI session cookie.");
     }
     const exchange = body;
     await updateStoredConfig({