recess-cli 1.9.2 → 2.1.0

package/dist/help.js

@@ -0,0 +1,376 @@
+export const HELP = `recess — safe Recess administration and family AI tools
+
+Usage:
+  recess [--json] --version
+  recess [--json] agent-context
+  recess [--json] setup [--skill-only]
+  recess [--json] doctor
+  recess [--json] profile list
+  recess [--json] profile show <name>
+  recess [--json] profile save <name> [--api-origin URL] [--web-origin URL]
+    [--oauth-client-id ID]
+  recess [--json] profile use <name>
+  recess [--json] profile delete <name>
+  recess [--json] jobs list [--limit 20]
+  recess [--json] jobs get <operation-key>
+  recess [--json] jobs prune [--older-than-days 30]
+  recess [--json] feedback list [--limit 20]
+  recess [--json] feedback submit <text> [--confirm]
+  recess [--json] auth login [--client-id ID] [--callback-port 8765]
+  recess [--json] auth request [--label TEXT]
+  recess [--json] auth poll [--timeout 300]
+  recess [--json] auth status|logout
+  recess [--json] users search <name-or-id> [--limit 10]
+  recess [--json] users get <user-id>
+  recess [--json] users tier list-tiers
+  recess [--json] users tier get <kid-id>
+  recess [--json] users tier preview <kid-id> --tier social|academics|lite|complete|platform
+    [--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] students list
+  recess [--json] students today --student <kid-id> [--date YYYY-MM-DD]
+  recess [--json] students schedule --student <kid-id> [--days 14]
+  recess [--json] students xp-history --student <kid-id>
+    [--range week|month|quarter|year]
+  recess [--json] enrollments list --user <user-id>
+  recess [--json] subscriptions list --family <family-id> [--kid <kid-id>]
+  recess [--json] invoices list --subscription <subscription-id>
+  recess [--json] billing pause --subscription <id> [--until ISO_DATE] [--confirm]
+  recess [--json] billing resume --subscription <id> [--confirm]
+  recess [--json] invoices refund --invoice <id> --line-item <id>
+    --method refund|credit|tokens [--full | --amount-cents N]
+    [--who-pays guide|recess] [--reason TEXT] [--confirm]
+  recess [--json] applications list [--status SUBMITTED|CLAIMED|ENROLLED|CLOSED]
+    [--status-scope active|closed] [--disposition READY_TO_ENROLL|TRIAL|PENDING_FUNDING|NO]
+    [--dispositioned true|false] [--quality QUALIFIED|NEEDS_NURTURE|UNKNOWN]
+    [--source PUBLIC|STAFF] [--limit 100] [--cursor <id>]
+  recess [--json] applications get <application-id>
+  recess [--json] applications quotes <application-id>
+  recess [--json] applications meetings <application-id>
+  recess [--json] applications call-notes <application-id>
+  recess [--json] applications create --data-file <application.json> [--confirm]
+  recess [--json] applications disposition <application-id>
+    --data-file <disposition.json> [--confirm]
+  recess [--json] applications qualify <application-id>
+    --quality QUALIFIED|NEEDS_NURTURE|UNKNOWN --reason TEXT [--confirm]
+  recess [--json] applications update-contact <application-id>
+    --data-file <contact.json> [--confirm]
+  recess [--json] applications claim-email|claim-link <application-id>
+    --intent-key <uuid> [--supersede] [--confirm]
+  recess [--json] applications revoke-claim <application-id> [--confirm]
+  recess [--json] applications link-family <application-id> --family <family-id> [--confirm]
+  recess [--json] applications close <application-id> --reason TEXT [--confirm]
+  recess [--json] applications add-call-note <application-id>
+    --data-file <call-note.json> [--confirm]
+  recess [--json] applications edit-call-note <application-id>
+    --note-id <note-id> --data-file <comment.json> [--confirm]
+  recess [--json] applications enroll <application-id> --quote <quote-id>
+    --school <institution-slug> --kid "<quoteLineId>:<firstName>[:<age>]" (repeat per line)
+    [--family <family-id>] [--unassign <kid-id>] (repeat) [--note TEXT] [--confirm]
+  recess [--json] quotes get <quote-id>
+  recess [--json] quotes preview --data-file <quote.json>
+  recess [--json] quotes create --data-file <quote.json> [--confirm]
+  recess [--json] quotes update <quote-id> --data-file <quote.json> [--confirm]
+  recess [--json] quotes send <quote-id> [--expected-revision <sha>] [--confirm]
+  recess [--json] quotes accept <quote-id> [--confirm]
+  recess [--json] quotes decline <quote-id> [--note TEXT] [--confirm]
+  recess [--json] cohorts search <query>
+  recess [--json] enrollments create --user <kid-id> --cohort <id>
+    [--first-charge-at ISO_DATETIME] [--send-email] [--force]
+    [--confirm --approval-token TOKEN]
+  recess [--json] enrollments register-cohort --enrollment <id>
+    --user <id> --cohort <id> [--confirm]
+  recess [--json] enrollments unregister-cohort --user <id>
+    --cohort <id> [--confirm]
+  recess [--json] enrollments get-for-subscription --subscription <id>
+  recess [--json] billing extend-trial --subscription <id>
+    --trial-end ISO_DATE [--confirm]
+  recess [--json] billing cancel-subscription --subscription <id>
+    [--immediate] [--reason TEXT] [--restore] [--confirm]
+  recess [--json] payout payruns list [--status A,B] [--schedule <id>]
+  recess [--json] payout recipients list [--search <name>] [--user <id>] [--id <id>]
+    [--limit 20] [--cursor <id>]
+  recess [--json] payout invoices list [--payrun <id>] [--recipient <account-id>]
+    [--user <id>] [--status A,B]   (at least one filter)
+  recess [--json] payout invoices get <invoice-id>
+  recess [--json] payout invoices set-status <invoice-id>
+    --status IN_REVIEW|OPEN|PAID|CANCELED [--send-email] [--confirm]
+  recess [--json] payout items add --invoice <id> --amount-cents N
+    --description TEXT [--date YYYY-MM-DD] [--confirm]
+  recess [--json] payout items edit <item-id> [--amount-cents N]
+    [--description TEXT] [--date YYYY-MM-DD] [--confirm]
+  recess [--json] payout items delete <item-id> [--confirm]
+  recess [--json] cohorts get <cohort-id> [--events-tab ACTIVE|ENDED|CANCELED|ARCHIVED]
+  recess [--json] cohorts parent-emails <cohort-id>
+  recess [--json] cohorts end <cohort-id> [--cancel-subscriptions] [--confirm]
+  recess [--json] cohorts pause-billing <cohort-id> --weeks 1..6 [--confirm]
+  recess [--json] cohorts resume-billing <cohort-id> [--confirm]
+  recess [--json] cohorts email <cohort-id> --target ALL_PARENTS|ALL_PARENTS_GUIDES
+    --content TEXT [--confirm]
+  recess [--json] events get <event-id>
+  recess [--json] events take-attendance <event-id> --attended <id,id,...>
+    [--absent <id,id,...>] [--excused <id,id,...>] [--confirm]
+  recess [--json] events cancel <event-id> --reason TEXT [--confirm]
+  recess [--json] events set-status <event-id> --status ACTIVE|ENDED|CANCELED [--confirm]
+  recess [--json] events reschedule --cohort <id> --event <event-id>
+    --starts-at "YYYY-MM-DDTHH:MM" [--timezone <iana>] [--length-mins N] [--confirm]
+  recess [--json] events add --cohort <id> --starts-at "YYYY-MM-DDTHH:MM"
+    [--timezone <iana>] [--length-mins N] [--confirm]
+  recess [--json] registrations approve --registration <id> [--confirm]
+  recess [--json] registrations deny --cohort <id> --user <id> [--confirm]
+  recess [--json] request get </path?query=value>
+  recess [--json] onboarding status <family-id>
+  recess [--json] onboarding queue [--school <institution-slug>]
+  recess [--json] onboarding kids [--time-period-days N] [--cohort <id>]
+    [--limit N] [--stage-filter all|scheduled|oriented|course|converted|lost]
+  recess [--json] onboarding timeline <family-id>
+  recess [--json] onboarding readiness <family-id>
+  recess [--json] onboarding active-tutors <family-id>
+  recess [--json] onboarding meetings <family-id>
+  recess [--json] onboarding cohort-options <family-id> [--kid <kid-id>]
+  recess [--json] onboarding comms [--school <institution-slug>]
+    [--status RESERVED|SENT|FAILED] [--kind <kind>] [--limit 50] [--cursor <cursor>]
+  recess [--json] onboarding lifecycle-prompts
+  recess [--json] onboarding orientation-sessions
+  recess [--json] onboarding ixl-preview <family-id> --kid <kid-id>
+  recess [--json] onboarding intake-session <family-id>
+  recess [--json] onboarding intake-session-create <family-id> [--confirm]
+  recess [--json] onboarding set-stage <family-id>
+    --stage LEGACY|PROVISIONED|PARENT_CONFIRMED|CLEARED_FOR_COHORT|COMPLETE [--confirm]
+  recess [--json] onboarding set-account-state <family-id>
+    --state ACTIVE|PENDING_PAYMENT|PAUSED|BOOTED [--note TEXT] [--confirm]
+  recess [--json] onboarding set-primary-tutor <family-id>
+    [--tutor <user-id> | --clear] [--confirm]
+  recess [--json] onboarding attest <family-id>
+    --condition app_downloaded|tutor_met|goals_loaded|ma_diagnostic [--revoke]
+    [--note TEXT] [--confirm]
+  recess [--json] onboarding clear-for-cohort <family-id> [--confirm]
+  recess [--json] onboarding register-cohort <family-id>
+    --kid <kid-id> --cohort <event-series-id> [--confirm]
+  recess [--json] onboarding set-kid-grade <family-id>
+    --kid <kid-id> [--grade 1..12 | --clear] [--confirm]
+  recess [--json] onboarding seed-feed <family-id> --kid <kid-id> [--confirm]
+  recess [--json] onboarding generate-summaries <family-id> [--confirm]
+  recess [--json] onboarding provision-math-academy <family-id>
+    --kid <kid-id> [--grade 1..12] [--confirm]
+  recess [--json] onboarding provision-ixl <family-id>
+    --kid <kid-id> [--credentials-file <credentials.json>] [--confirm]
+  recess [--json] onboarding remove-ixl <family-id> --kid <kid-id> [--confirm]
+  recess [--json] onboarding ixl-sync [--apply] [--confirm]
+  recess [--json] onboarding send-comms --subject <family:id|invite:id>
+    --kind <kind> [--confirm]
+  recess [--json] onboarding send-welcome <family-id> [--resend] [--confirm]
+  recess [--json] onboarding send-payment-email <family-id> [--resend] [--confirm]
+  recess [--json] onboarding send-recommendations <family-id>
+    --courses <course-id,course-id> [--resend] [--confirm]
+  recess [--json] onboarding set-lifecycle-prompt <kind>
+    [--enabled true|false] [--delay-days N] [--window-days N]
+    [--snooze-days N] [--max-prompts N] [--confirm]
+  recess [--json] onboarding override-lifecycle-prompt <kind> <family-id>
+    --action delay|skip|clear [--days N] [--confirm]
+  recess [--json] onboarding orientation-create --starts-at <iso>
+    [--ends-at <iso>] [--capacity N] [--confirm]
+  recess [--json] onboarding orientation-set-status <session-id>
+    --status CANCELED|COMPLETED [--confirm]
+  recess [--json] onboarding orientation-attendance <session-id>
+    --family <family-id> --attended true|false [--confirm]
+  recess [--json] onboarding meeting-reschedule <meeting-id>
+    --starts-at <iso> [--note TEXT] [--confirm]
+  recess [--json] onboarding meeting-cancel <meeting-id> --reason TEXT [--confirm]
+  recess [--json] onboarding set-intake <family-id> --session <id>
+    --data <json> [--expected-updated-at <iso>] [--confirm]
+  recess [--json] onboarding extract <family-id> --session <id>
+    (--transcript-file <path> | --granola <ref>) [--confirm]
+  recess [--json] village models list [--world village-1] [--query TEXT] [--archived]
+  recess [--json] village models upload --file </path/model.glb>
+    [--world village-1] [--name TEXT] [--id ID] [--description TEXT] [--tags A,B]
+    [--visual-only] [--confirm]
+  recess [--json] village models publish|archive <model-id> [--world village-1] [--confirm]
+  recess [--json] village models place <model-id> --x N --z N
+    [--y N] [--rotation 0..3] [--mirrored] [--no-collision] [--batch ID]
+    [--world village-1] [--confirm]
+  recess [--json] village models move <placement-id> --x N --z N
+    [--y N] [--rotation 0..3] [--mirrored] [--world village-1] [--confirm]
+  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] village library search [query] [--query TEXT] [--limit 20]
+    [--world home-USER_ID]
+  recess [--json] village library get <model-id> [--world home-USER_ID]
+  recess [--json] village objects list [--min-x -20] [--min-z -20]
+    [--max-x 20] [--max-z 20] [--world home-USER_ID]
+  recess [--json] village objects get <object-id> [--world home-USER_ID]
+  recess [--json] village build cmd '<command-json>' [--world home-USER_ID] [--confirm]
+  recess [--json] village build cmd --file <command.json> [--world home-USER_ID] [--confirm]
+  recess [--json] village worlds export <world-id> [--out <bundle.json>] [--confirm]
+  recess [--json] village worlds import <world-id> --file <bundle.json> [--confirm]
+  recess [--json] village worlds promote <mirror-or-archive-id> [--confirm]
+  recess [--json] store-items list [--search TEXT]
+    [--status ACTIVE|INACTIVE|COMING_SOON] [--item-type TYPE]
+    [--page 0] [--limit 20] [--sort-by name|price|createdAt|updatedAt|order]
+    [--sort-order asc|desc]
+  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 [--wait] [--timeout 900] [--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]
+    [--wait] [--timeout 900] [--confirm]
+  recess [--json] skills guardian list [--query TEXT] [--category TEXT]
+  recess [--json] skills guardian get <skill-name>
+    [--reference NAME | --all-references] [--refresh]
+  recess [--json] skills admin list [--query TEXT] [--category TEXT]
+  recess [--json] skills admin get <skill-name>
+    [--reference NAME | --all-references]
+    [--refresh]
+  recess [--json] goal-templates list [--query TEXT] [--category TEXT]
+    [--kind SIMPLE|BLUEPRINT] [--starter-only] [--include-deleted]
+    [--limit 20] [--cursor <id>]
+  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 --approval-token TOKEN]
+    [--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] [--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]
+  recess [--json] goal-templates capture-snapshot <template-id|slug>
+    (--source-goal <goal-id> | --source-draft <draft-slug> --student <goal-owner-id>
+      | --source-dir <local-checkout>)
+    [--dry-run] [--confirm --approval-token TOKEN]
+  recess [--json] goal-templates apply <template-id> --answers-file <path>
+    [--dry-run] [--confirm --approval-token TOKEN]
+  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] [(--draft <draft-slug> | --source-dir <local-checkout>)
+      (--enable-applet-follow-ups | --disable-applet-follow-ups)]
+    [--confirm --approval-token TOKEN]
+  recess [--json] goals edit <goal-id> --student <kid-id> --patch-file <path/patch.json>
+    --delta TEXT [--confirm --approval-token TOKEN]
+  recess [--json] goals delete <goal-id> --student <kid-id>
+    [--confirm --approval-token TOKEN]
+  recess [--json] goals queue get <goal-id> --student <kid-id>
+  recess [--json] goals queue set <goal-id> --student <kid-id>
+    --entries-file <path.json> --delta TEXT [--replace-description-pointer]
+    [--confirm --approval-token TOKEN]
+  recess [--json] todos create --student <kid-id> --title TEXT
+    [--due-date YYYY-MM-DD] [--estimated-minutes N] [--url URL] [--confirm]
+  recess [--json] todos edit <todo-id> --patch-file <path/patch.json>
+    [--confirm --approval-token TOKEN]
+  recess [--json] todos delete <todo-id>
+    [--confirm --approval-token TOKEN]
+  recess [--json] todos generate-applet <todo-id> --student <kid-id>
+    [--due-date YYYY-MM-DD] [--confirm --approval-token TOKEN]
+  recess [--json] memories context --student <kid-id>
+  recess [--json] memories log --student <kid-id> --date YYYY-MM-DD
+  recess [--json] rocky get --student <kid-id>
+  recess [--json] rocky set --student <kid-id> --patch-file <path/patch.json>
+    --expected-updated-at ISO|none [--confirm]
+  recess [--json] goals files list --student <goal-owner-id> --goal <goal-id>
+  recess [--json] goals files read --student <goal-owner-id> --goal <goal-id> --path P
+  recess [--json] goals files init --student <goal-owner-id> --draft <draft-slug>
+    --output-dir <local-dir>
+  recess [--json] goals files checkout --student <goal-owner-id>
+    (--goal <goal-id> | --draft <draft-slug>)
+    --output-dir <local-dir>
+  recess [--json] goals files push --source-dir <local-checkout>
+    [--message TEXT] [--confirm --approval-token TOKEN]
+  recess [--json] goals files write --student <goal-owner-id>
+    (--goal <goal-id> | --draft <draft-slug>)
+    (--source-dir <local-dir> | --source-file <local-file> --path P)
+    [--message TEXT] [--confirm --approval-token TOKEN]
+  recess [--json] goals pdf upload --student <goal-owner-id>
+    (--goal <goal-id> | --draft <draft-slug>) --source-file <local.pdf>
+    [--path uploads/name.pdf] [--message TEXT]
+    [--confirm --approval-token TOKEN]
+
+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
+standard. Responses cache under ~/.recess-cli/skills-cache/ (--refresh re-fetches).
+For goal workspace and PDF commands, --student names the goal owner. A
+full_admin session may use a KID or ADMIN user id, including its own ADMIN id;
+family_ai sessions remain limited to managed KID profiles.
+"goals create --source-dir" materializes a clean, fully pushed draft checkout as
+a personal module-backed goal and retargets that checkout to the resulting live
+goal. It does not create or apply a reusable template. Its preview is bound to
+the exact workspace revision, hash, module inventory, and applet follow-up choice.
+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
+yet" result when absent). "intake-session-create" is the explicit write that
+mints a blank session, so it is gated behind --confirm. "set-stage" reads the
+current stage first and warns when a move re-locks progress; CLEARED_FOR_COHORT
+unlocks cohort registration. "set-account-state" PAUSED/BOOTED lock the family out of paid
+capabilities (--note is analytics-only). "set-intake --data" takes JSON (agents
+drive it with --json; humans rarely will); the preview is offline. Its
+optimistic-concurrency token resolves only on --confirm: pass
+--expected-updated-at <iso> (from an intake-session read's updatedAt) for strict
+CAS that 409s if a parent autosaved since; omit it and the CLI fetches the
+current token at confirm time and warns that post-preview edits are unprotected.
+"extract" is LLM-bound and can take ~30s; a 503 means Granola is not configured
+server-side.
+
+Class-ops notes: "events cancel" notifies families (chat + parent email blast +
+credit notes + Slack); "events set-status --status CANCELED" is a silent status
+change. Reschedule times are cohort-local wall-clock (zoneless).
+
+Payout notes: amounts are integer cents. "payout items add" without --date
+defaults the item date to the penultimate day of the invoice's cycle (its
+endDate minus one day) and shows the computed date in the preview.
+
+Auth notes: "auth login" runs the browser loopback flow for ADMIN, GUIDE, a GUARDIAN with
+access:ai, or a KID using only Village home building. Guardian sessions are family-scoped and
+cannot call /admin; KID sessions cannot call any non-Village API command. For a headless
+cloud agent, the ADMIN-only "auth request" prints an approval URL to hand a Recess admin; after they
+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.
+Every preview includes an operationKey; confirmed writes must echo it with
+--operation-key so an interrupted invocation can be retried without duplicating the write.
+Environment overrides: RECESS_CLI_API_ORIGIN, RECESS_CLI_WEB_ORIGIN,
+RECESS_CLI_OAUTH_CLIENT_ID, RECESS_CLI_COOKIE, RECESS_CLI_CONFIG,
+RECESS_CLI_PROFILE, RECESS_CLI_FEEDBACK_ENDPOINT.
+
+Every command that calls the Recess API, except auth commands, requires
+--reason TEXT: a non-empty human-readable purpose of at most 1024 characters.`;
+//# sourceMappingURL=help.js.map

package/dist/http.js

@@ -0,0 +1,25 @@
+import { CliError } from "./errors.js";
+export const RECESS_CLIENT_HEADER = "x-recess-client";
+export const RECESS_CLIENT_CLI = "cli";
+export const RECESS_CLIENT_CLI_UI = "cli-ui";
+export const RECESS_REASON_HEADER = "x-recess-reason";
+export function requireCliRequestReason(value) {
+    const reason = value?.trim();
+    if (!reason) {
+        throw new CliError("invalid_arguments", "Missing required --reason.");
+    }
+    if (reason.length > 1024) {
+        throw new CliError("invalid_arguments", "--reason must be 1024 characters or fewer.");
+    }
+    return reason;
+}
+export function markCliRequest(headers, reason, client = RECESS_CLIENT_CLI) {
+    headers.set(RECESS_CLIENT_HEADER, client);
+    if (reason)
+        headers.set(RECESS_REASON_HEADER, reason);
+    return headers;
+}
+export function cliRequestHeaders(init, reason, client = RECESS_CLIENT_CLI) {
+    return markCliRequest(new Headers(init), reason, client);
+}
+//# sourceMappingURL=http.js.map

package/dist/index.js

@@ -2,6 +2,7 @@
 import { createInterface } from "node:readline/promises";
 import { parseArgs } from "./args.js";
 import { runCommand } from "./cli.js";
+import { deliverJson } from "./delivery.js";
 import { CliError } from "./errors.js";
 async function withInteractiveAdmissionStage(args) {
     const parsed = parseArgs(args);
@@ -38,7 +39,8 @@ async function withInteractiveAdmissionStage(args) {
     }
 }
 const argv = await withInteractiveAdmissionStage(process.argv.slice(2));
-const json = argv.includes("--json");
+const parsedArgv = parseArgs(argv);
+const json = parsedArgv.flags.has("json");
 // The interactive console owns the terminal, so it runs before the JSON
 // envelope machinery rather than through it.
 if (argv[0] === "ui") {
@@ -57,11 +59,21 @@ if (argv[0] === "ui") {
 }
 try {
     const data = await runCommand(argv);
-    if (typeof data === "object" && data && "help" in data && !json) {
+    const destination = parsedArgv.flags.get("deliver");
+    if (destination === true) {
+        throw new CliError("invalid_delivery", "--deliver requires a value.");
+    }
+    const envelope = { ok: true, data };
+    const delivery = await deliverJson(destination, envelope);
+    if (delivery.delivered) {
+        const acknowledgement = { ok: true, data: delivery };
+        process.stdout.write(`${json ? JSON.stringify(acknowledgement) : JSON.stringify(acknowledgement.data, null, 2)}\n`);
+    }
+    else if (typeof data === "object" && data && "help" in data && !json) {
         process.stdout.write(`${String(data.help)}\n`);
     }
     else if (json) {
-        process.stdout.write(`${JSON.stringify({ ok: true, data })}\n`);
+        process.stdout.write(`${JSON.stringify(envelope)}\n`);
     }
     else {
         process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);

package/dist/jobs.js

@@ -0,0 +1,80 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+function jobsPath() {
+    return (process.env.RECESS_CLI_JOBS_PATH ??
+        path.join(os.homedir(), ".recess-cli", "jobs.jsonl"));
+}
+async function readEvents() {
+    try {
+        return (await fs.readFile(jobsPath(), "utf8"))
+            .split("\n")
+            .filter(Boolean)
+            .flatMap((line) => {
+            try {
+                return [JSON.parse(line)];
+            }
+            catch {
+                return [];
+            }
+        });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+}
+export async function appendJobEvent(event) {
+    const file = jobsPath();
+    await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+    let stored = event;
+    const serialized = JSON.stringify(stored);
+    if (serialized.length > 64 * 1024 && event.result !== undefined) {
+        stored = {
+            ...event,
+            result: {
+                omitted: true,
+                reason: "Result exceeded the 64 KiB local job-ledger limit.",
+                bytes: Buffer.byteLength(serialized),
+            },
+        };
+    }
+    await fs.appendFile(file, `${JSON.stringify(stored)}\n`, { mode: 0o600 });
+    await fs.chmod(file, 0o600);
+}
+function foldJobs(events) {
+    const jobs = new Map();
+    for (const event of events) {
+        const prior = jobs.get(event.jobId);
+        jobs.set(event.jobId, { ...event, events: (prior?.events ?? 0) + 1 });
+    }
+    return Array.from(jobs.values()).sort((left, right) => right.timestamp.localeCompare(left.timestamp));
+}
+export async function listJobs(limit = 20) {
+    const jobs = foldJobs(await readEvents());
+    return {
+        jobs: jobs.slice(0, limit),
+        truncated: jobs.length > limit,
+        total: jobs.length,
+    };
+}
+export async function getJob(jobId) {
+    const history = (await readEvents()).filter((event) => event.jobId === jobId);
+    return { job: foldJobs(history)[0] ?? null, history };
+}
+export async function pruneJobs(olderThanDays) {
+    const events = await readEvents();
+    const cutoff = Date.now() - olderThanDays * 24 * 60 * 60 * 1000;
+    const kept = events.filter((event) => Date.parse(event.timestamp) >= cutoff);
+    const file = jobsPath();
+    await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+    const temporary = `${file}.${process.pid}.tmp`;
+    await fs.writeFile(temporary, kept.length > 0
+        ? `${kept.map((event) => JSON.stringify(event)).join("\n")}\n`
+        : "", { mode: 0o600 });
+    await fs.rename(temporary, file);
+    await fs.chmod(file, 0o600);
+    return { removed: events.length - kept.length, remaining: kept.length };
+}
+//# sourceMappingURL=jobs.js.map

package/dist/skill-update.js

@@ -1,5 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { cliRequestHeaders } from "./http.js";
 import { skillDestinations } from "./setup.js";
 /**
  * Compare dotted numeric versions. Deliberately hand-rolled rather than adding a
@@ -88,7 +89,7 @@ export async function updateSkillFromServer(input) {
     let bundle;
     try {
         const response = await fetch(new URL("/auth/admin-cli/skill/", input.apiOrigin), {
-            headers: input.sessionCookie ? { cookie: input.sessionCookie } : {},
+            headers: cliRequestHeaders(input.sessionCookie ? { cookie: input.sessionCookie } : undefined, input.reason),
             signal: AbortSignal.timeout(10_000),
         });
         if (!response.ok) {

package/dist/ui/index.js

@@ -3,6 +3,7 @@ import { render } from "ink";
 import { RecessAdminApi } from "../api.js";
 import { resolveConfig } from "../config.js";
 import { CliError } from "../errors.js";
+import { RECESS_CLIENT_CLI_UI } from "../http.js";
 import { App } from "./app.js";
 /**
  * The interactive console. Kept off the JSON path on purpose: agents parse
@@ -14,7 +15,7 @@ export async function runUi() {
     if (!config.sessionCookie) {
         throw new CliError("auth_required", "No Recess CLI session found. Run `recess auth login`.");
     }
-    const api = new RecessAdminApi(config);
+    const api = new RecessAdminApi(config, undefined, RECESS_CLIENT_CLI_UI);
     const instance = render(_jsx(App, { api: api }));
     await instance.waitUntilExit();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "recess-cli",
-  "version": "1.9.2",
+  "version": "2.1.0",
   "description": "Safe Recess administration and family AI tools from the command line.",
   "license": "UNLICENSED",
   "repository": {
@@ -48,8 +48,8 @@
     "typecheck": "tsgo --noEmit",
     "format": "oxfmt --ignore-path .oxfmtignore --check",
     "format:fix": "oxfmt --ignore-path .oxfmtignore",
-    "lint": "oxlint --type-aware src/*.ts",
-    "lint:fix": "oxlint --type-aware --fix src/*.ts",
+    "lint": "oxlint --type-aware src/*.ts src/commands/*.ts",
+    "lint:fix": "oxlint --type-aware --fix src/*.ts src/commands/*.ts",
     "test": "vitest run",
     "install-local": "pnpm run build && make install-local",
     "install-persistent": "pnpm run build && make install-persistent",

package/skill/recess-cli/SKILL.md

@@ -11,26 +11,30 @@ Use the installed `recess` command for Recess work. This small skill is shared b
 
 ```bash
 command -v recess
-recess --json doctor
+recess --json doctor --reason "Verify CLI connectivity, identity, and scope"
 ```
 
 `doctor` reports the active API origin, authenticated user, and CLI scope. Do not assume a role from the request. Use the scope returned by the server.
 
+If the reported scope is `village_home`, use only `recess village build`, `village library`, `village objects`, and `village render`. That session is intentionally unable to fetch the guardian or admin skill catalogs or call ordinary Recess API routes; Village applies the user's own-home and object-ownership checks to every build or read.
+
 Then load the guidance for the purpose of the work:
 
 ```bash
 # Parent or guardian work: kids, schedules, goals, todos, progress, memory, Rocky
-recess --json skills guardian get recess-family --all-references
+recess --json skills guardian get recess-family --all-references --reason "Load family workflow guidance"
 
 # Research, author, validate, or apply a goal or reusable goal template
-recess --json skills guardian get recess-goal-authoring --all-references
+recess --json skills guardian get recess-goal-authoring --all-references --reason "Load goal authoring guidance"
 
 # Staff-only school operations
-recess --json skills admin get recess-admin --all-references
+recess --json skills admin get recess-admin --all-references --reason "Load staff operations guidance"
 ```
 
 Use `skills guardian list` or `skills admin list` when the needed skill is not obvious. Never substitute one audience for the other. A guardian session cannot fetch the admin catalog; an admin may fetch either catalog.
 
+For machine-readable discovery, use `recess --json agent-context`; for a smaller syntax surface, use `recess --json help <noun> [verb]`. Unknown commands, flags, duplicate non-repeatable flags, missing flag values, and extra positional arguments fail explicitly.
+
 ## Authentication
 
 - Workstation: `recess --json auth login` opens Recess SSO.
@@ -49,23 +53,31 @@ Always pass `--json`. Stdout contains one object:
 - Failure: `{"ok":false,"error":{"code":"...","message":"...","details":{...}}}`, exit 1.
 - Write awaiting approval: `confirmation_required`, exit 2, with `details.preview` and `details.requiredFlag`.
 
+Every command-driven Recess API call except `auth` requires `--reason "..."`: a specific,
+human-readable purpose from 1 to 1024 characters. The server records it in the CLI request audit
+ledger. Reuse the invocation's same reason across its preflight and execution requests. The
+human-only `recess ui` console is exempt.
+
 Every write is two-step:
 
 1. Run without `--confirm`.
 2. Show the human the complete preview, including `preview.details`.
 3. Ask for explicit approval of that exact action.
-4. Rerun the unchanged command with `--confirm`. If the preview includes an `approvalToken`, pass it unchanged.
+4. Rerun the unchanged command with `--confirm --operation-key <operationKey>`. If the preview includes an `approvalToken`, pass it unchanged too.
 
-Any changed target, payload, local file, server revision, amount, recipient, or consequence requires a new preview and new approval. Never infer approval from the original request.
+Any changed target, payload, local file, server revision, amount, recipient, or consequence requires a new preview and new approval. Never infer approval from the original request. If a confirmed invocation is interrupted, retry the unchanged command with the same operation key; never mint a new one for an uncertain write. Inspect recovery state with `recess --json jobs get <operation-key>`.
 
 ## Shared constraints
 
-- Use high-level CLI commands. The raw escape hatch is GET-only: `recess --json request get /path`.
+- Use high-level CLI commands. The raw escape hatch is GET-only:
+  `recess --json request get /path --reason "Inspect the exact API resource needed for this task"`.
 - Resolve names to exact IDs before writes. Stop on ambiguous matches.
 - Money uses integer cents.
 - Keep dates in the exact format required by command help.
 - Treat a 401 or `auth_required` as an authentication problem. A transport-level `fetch failed` is a network/sandbox problem, not proof that the session expired.
-- Run `recess --help` for syntax; load the audience skill for workflow meaning.
+- Use `profile list|save|use` or global `--profile` for named environments. `--deliver file:<path>` atomically stores one JSON envelope locally; authenticated webhook delivery is intentionally unavailable.
+- `feedback submit` records CLI friction under an operation key and optionally forwards it when an upstream endpoint is configured.
+- Run scoped help for syntax; load the audience skill for workflow meaning.
 
 ## Updating this shared skill