recess-cli 1.0.1 → 1.3.0

package/skill/recess-cli/reference/class-ops-reschedule.md

@@ -14,7 +14,7 @@ CLI cannot toggle the flag — web admin course settings only. Do not stop at "e
 
 ## Worked example (2026-07-23)
 
-- Cohort: Space Technology & Rocket Launches (`1be248c5-acb9-472e-91d7-7d1dc9f37dd0`)
+- Cohort: Space Technology & Rocket Launches (resolve its id with `cohorts search`)
 - Course: Current Events in Space Tech & Rockets — `allowFlexibleScheduling: false`
 - Ask: move today up 10 minutes (Starship)
 - Usual slot: Thu 15:45 America/Edmonton → UTC `21:45`

package/skill/recess-cli/reference/goal-authoring.md

@@ -0,0 +1,274 @@
+# Authoring learning content from the CLI
+
+The workflow behind `skills`, `goal-templates`, `goals`, and `mesa files`. Read this before the
+first write; the tool→command mapping and the one-way rules live in `SKILL.md` under "Learning-content
+contract".
+
+The point of this surface is not that an agent *can* create a template — the API always allowed
+that. It is that an agent can create a template **as good as one authored through `recess.gg/ai`**,
+because it loads the same authoring skills the in-product tutor loads. Skipping step 0 gives you a
+structurally valid template that is pedagogically wrong, and nothing downstream will catch it.
+
+---
+
+## 0. Load the authoring skills. Always. First.
+
+```bash
+recess --json skills get os-v2-goal-template-builder --all-references
+```
+
+`--all-references` pulls `references/deterministic-workflow-setup.md` in the same call — that
+document is the catalog of what the deterministic handlers can express, and you cannot author a
+correct spec without it. Without the flag you get SKILL.md plus a reference *index*, and each
+reference is a separate `--reference <name>` call (the same two-step the in-product agent uses).
+
+Responses cache for about an hour under `~/.recess-cli/skills-cache/`. Pass `--refresh` when someone
+has just edited a skill.
+
+These documents are proprietary and are served, never shipped. Do not copy their text anywhere.
+
+### Which research doc, for what
+
+"Deep research" is not one method here — pick by what you are researching. Every one of these assumes
+OSAgent research tools you do not have; SKILL.md's "Research tools → your own harness" says what to
+substitute, and names the one real gap (`fetch_page_structure`).
+
+| Researching | Load |
+|---|---|
+| An external platform's assignable content, to bake a queue into a template | `os-v2-goal-template-builder --all-references` → §"The research loop" + §"The validation loop" |
+| Content for a module-backed goal workspace | `os-v2-goal-builder --all-references` → `research-protocol.md` (wave dispatch, lookup order, verification rules, output file shape) |
+| A goal from an uploaded curriculum (PDF, scope-and-sequence) | `os-v2-goal-builder --reference curriculum-source` |
+| A goal for one kid, from scratch, in depth | `goal-creation --reference structured-plan` (S1–S6; S4 is the parallel deep research, S2 carries the depth cascade) + `--reference subagent-tasks` for the five researcher prompts |
+| The same, but the ask is small | `goal-creation --reference quick-discovery` — it names its own escalation trigger into the structured flow |
+| One platform, deeply (pedagogy, reviews) | `pipeline-platform-research --all-references` |
+| The kid, before any of the above | `student-research` |
+
+Research before you draft, not after. The spec's `handler.config` must arrive **fully materialized** —
+the apply endpoint never fetches anything, so whatever you did not bake in does not exist at apply
+time, and there is no later pass that fills it in.
+
+**If the request cannot be expressed by a supported handler, report that and stop.** The skill says
+this explicitly and it is the single most important instruction in it. A template that "sort of"
+does the job becomes a global record every future apply reads.
+
+## 1. Decide the kind before drafting
+
+`kind` is the real decision; `setupMode` is not a choice (see §5).
+
+| Kind | What a student gets | Use when |
+|---|---|---|
+| `SIMPLE` | a description-only goal plus linked todos — no modules, no Mesa workspace | ongoing habits, platform practice targets, score/streak goals, free-choice reading |
+| `BLUEPRINT` | a finishable learning path, built per student by the planner or copied from a snapshot | a course with a sequence and an end |
+
+The skill phrases this as a tutor-facing question with three options (the third, "Prebuilt", is a
+BLUEPRINT that also carries an instant-apply snapshot). You have no `ask_user_question` tool — ask
+the human directly, in the skill's language, and wait. Do not say "materialize",
+"module-backed", or "snapshot" to a tutor.
+
+A MODULE_BACKED spec **requires** `BLUEPRINT`; the server enforces it, and it additionally refuses to
+apply a MODULE_BACKED template that has no snapshot. Build a complete Mesa draft and capture it with
+the CLI workflow in §8 before applying the template.
+
+## 2. Write one template file
+
+`validate-spec` and `create` read the same document, so you iterate on one artifact:
+
+```jsonc
+{
+  "slug": "kebab-case-unique",          // required, immutable-ish: it is the human handle
+  "title": "Daily Reading Habit",       // required
+  "description": "One line a tutor reads in the library.",  // required
+  "kind": "SIMPLE",                     // SIMPLE | BLUEPRINT   (default SIMPLE)
+  "setupAudience": "KID_FRIENDLY",      // KID_FRIENDLY | PARENT_SETUP
+  "emoji": "📚",
+  "category": "reading",
+  "tags": ["reading", "ela"],           // an array, or a comma string
+  "sortOrder": 0,
+  "isStarter": false,
+  "agentInstructions": "…",             // required
+  "outputTemplate": "…",
+  "setupWorkflowSpec": { /* the fixed wizard — a real object, never a JSON string */ }
+}
+```
+
+Unknown keys are dropped, so a file made by editing `goal-templates get <id>` output works —
+`version`, `createdById`, `createdAt` are ignored rather than rejected. `setupMode` must be absent
+(or `DETERMINISTIC_WORKFLOW`); anything else is refused locally.
+
+## 3. Iterate on `validate-spec` — it writes nothing
+
+```bash
+recess --json goal-templates validate-spec --file ./template.json
+```
+
+Valid:
+
+```json
+{"ok":true,"data":{"slug":"…","kind":"SIMPLE","valid":true,
+  "setupHandler":"TOOL_GENERATED_TODO_SETUP","goalShape":"SIMPLE",
+  "stepKeys":["students"],"sha256":"…",
+  "totals":{"subjects":0,"recipes":0,"plans":0,"queueItems":0,"sourceUrls":0,"missingCoverage":0}}}
+```
+
+Invalid returns `"valid": false` with the backend's verbatim message — read it and fix the file.
+`ok` stays `true` because an invalid spec is an expected step in an authoring loop, not a failure of
+the command. Handler configs are `.strict()`, so a guessed config fails with both missing-field and
+`unrecognized_keys` errors at once; that is your cue to go back to
+`references/deterministic-workflow-setup.md` rather than guessing again.
+
+`stepKeys` is the contract for §6: those are exactly the keys your answers file must carry.
+
+## 4. Create — read the server-resolved preview
+
+```bash
+recess --json goal-templates create --file ./template.json          # preview, exit 2
+recess --json goal-templates create --file ./template.json --confirm
+```
+
+The unconfirmed run performs one read-only validation and puts its result in `preview.details`:
+
+| Field | Why it is in the approval request |
+|---|---|
+| `resolvedSetupHandler` | which handler actually runs — derived from the spec, not from what you wrote in the file |
+| `resolvedGoalShape` | `SIMPLE` vs `MODULE_BACKED`; decides whether a snapshot is required to apply |
+| `wizardStepKeys` | the questions a tutor will be asked, and the answer keys `apply` will demand |
+| `specInventory` | subjects / recipes / plans / queue items / source URLs the template starts with |
+
+Show all of it. `action` alone does not tell a human what the template does.
+
+If the spec is invalid at this point the command fails with `invalid_spec` and creates nothing —
+even with `--confirm`. That ordering is deliberate: an approved-but-broken template must not land.
+
+## 5. What is permanent
+
+**Every template created here is `setupMode: DETERMINISTIC_WORKFLOW` and cannot be converted back.**
+There is no AI_CHAT creation path and no downgrade — the server refuses the conversion outright.
+Legacy AI_CHAT templates remain readable and editable; you will never create one.
+
+So the confirmation gate carries more weight here than on a reversible write. What *is* recoverable:
+metadata (`set-metadata`) and the row itself (`delete` is a soft delete, and goals already applied
+from the template are unaffected).
+
+## 6. Apply to a kid or a roster
+
+Answers are a JSON file keyed by the spec's `stepKeys`:
+
+```jsonc
+{ "students": ["<kid-uuid>", "<kid-uuid>"], "grade": "5" }
+```
+
+```bash
+recess --json goal-templates apply <id-or-slug> --answers-file ./answers.json --dry-run
+recess --json goal-templates apply <id-or-slug> --answers-file ./answers.json            # preview
+recess --json goal-templates apply <id-or-slug> --answers-file ./answers.json --confirm
+```
+
+`--dry-run` is a read and does not gate. The unconfirmed form runs the same backend dry run to build
+its preview, so `details.counts` and `details.results` are the backend's own plan, per student:
+
+- `created` — a new goal + todo
+- `skipped_existing` — idempotent; re-applying does not duplicate
+- `error` — that student failed; the others still committed (failure is per item, never per batch)
+
+`details.missingCoverage` lists content the planner could not resolve. Surface it — an apply that
+"succeeded" with missing coverage produced a thinner goal than intended.
+
+`apply-starter` is the one-tap starter path: one template, one student, no dry run, so its preview is
+offline. It is gated per acting admin behind the `school-onboarding-v1` flag and **404s when the flag
+is off** — which reads like a missing template but is not.
+
+## 7. A goal directly on a kid
+
+```bash
+recess --json goals list --student <kid-id>
+recess --json goals create --student <kid-id> --title "…" --description-file ./goal.md --confirm
+```
+
+This creates a **description-only** goal: no GoalModules, no Mesa workspace. For a real course,
+apply a BLUEPRINT template instead. `--description-file` exists because a good goal description is
+long and prose-shaped; a shell mangles it.
+
+A 409 `GOAL_LIMIT_REACHED` means the kid is at capacity and nothing was created — do not retry, ask
+the human which goal to retire.
+
+Load `goal-creation` (and `student-research` to read the kid first) before writing the description.
+An unresearched goal is the failure mode this whole surface exists to prevent.
+
+## 8. Author, capture, and read workspaces
+
+For a new Prebuilt/instant-apply course, author the complete OS-V2 tree locally and upsert it into a
+named draft. The directory root becomes `drafts/<slug>/workspace` in the student's Mesa repo:
+
+```bash
+recess --json mesa files write --student <kid-id> --draft <draft-slug> --source-dir ./workspace
+# show the preview, obtain approval, then rerun unchanged:
+recess --json mesa files write --student <kid-id> --draft <draft-slug> --source-dir ./workspace --confirm
+
+recess --json goal-templates capture-snapshot <id-or-slug> --source-draft <draft-slug> --student <kid-id> --dry-run
+recess --json goal-templates capture-snapshot <id-or-slug> --source-draft <draft-slug> --student <kid-id>
+# show the preview, obtain approval, then rerun unchanged:
+recess --json goal-templates capture-snapshot <id-or-slug> --source-draft <draft-slug> --student <kid-id> --confirm
+```
+
+The draft must pass the full goal-builder contract: required top-level instructions, required fresh
+`state/` files, directory content, and at least one parseable runtime module. Capture validates that
+tree, then excludes `state/`, `conversations/`, and `.recess/` from the reusable snapshot. Its
+preview carries the template version, Mesa change id, module/file inventory, size, and SHA-256; the
+confirmed request is compare-and-set against both fences. If either changed, preview again and get
+fresh approval.
+
+Use `--source-file <local-file> --path <workspace-relative-path>` for one-file upserts. A live goal
+may be targeted with `--goal <goal-id>`, but the CLI rejects direct `modules/` and `state/` writes
+because those paths have database projections. Structural course changes belong in a draft, then a
+captured/applied template.
+
+An already-built OS-V2 goal can be captured directly:
+
+```bash
+recess --json goal-templates capture-snapshot <id-or-slug> --source-goal <goal-id> --dry-run
+```
+
+Read the resulting workspaces and snapshot with:
+
+```bash
+recess --json mesa files list --student <kid-id> --goal <goal-id>
+recess --json mesa files read --student <kid-id> --goal <goal-id> --path modules/01/index.md
+recess --json goal-templates snapshot-files <id-or-slug>
+recess --json goal-templates snapshot-files <id-or-slug> --path modules/01/index.md
+```
+
+`mesa files list` returning `{"files":[]}` means the goal has no Mesa workspace at all — expected for
+a SIMPLE goal, and the signal that a BLUEPRINT goal has not been built yet.
+
+## 9. Spec patches, metadata edits, and deletes are fenced
+
+```bash
+recess --json goal-templates get <id-or-slug>          # read `version`
+recess --json goal-templates patch-spec <id-or-slug> --expected-version 7 --patches-file ./patches.json
+recess --json goal-templates set-metadata <id> --expected-version 7 --title "…" --confirm
+recess --json goal-templates delete <id> --expected-version 7 --confirm
+```
+
+`--expected-version` is mandatory. A stale one returns 409 `STALE_WRITE` (server) or `stale_write`
+(the CLI's own pre-check) and **nothing is written** — re-read, rebuild the edit, and get a fresh
+approval. Never reuse an approval across a stale-write refresh.
+
+`patches.json` is a non-empty JSON array (maximum 50 operations) using `add`, `copy`, `replace`, and
+`remove` with RFC 6901 JSON Pointer paths. The unconfirmed command sends `dryRun:true` to the server,
+which applies the operations in memory, strict-validates the complete result, and returns
+`details.safety` with before/after hashes, inventory totals, removals, and (when destructive) a
+token. Show that exact preview to the human. After approval, rerun the same command with `--confirm`;
+if `destructiveChanges` is true, also pass `--confirm-destructive-changes` and the preview's exact
+`--destructive-change-token`. The confirmed run obtains a fresh preview before writing, and a stale
+version or token writes nothing.
+
+`set-metadata` cannot send a `setupWorkflowSpec` at all. Never replace a whole live spec through a
+generic update or raw request; `patch-spec` is the only CLI path for an existing spec.
+
+## Verify after every write
+
+```bash
+recess --json goal-templates get <id-or-slug>       # version bumped? metadata right?
+recess --json goal-templates versions <id-or-slug>  # a new frozen version row exists
+recess --json goals list --student <kid-id>         # the goal actually landed on the kid
+```