recess-cli 1.0.1 → 1.2.0

package/README.md

@@ -13,7 +13,7 @@ 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.
 
-Publishing is a manual GitHub Action (`.github/workflows/admin-cli-publish.yml`): bump `version` in `apps/admin-cli/package.json` in a normal PR, then run the workflow. It publishes with `pnpm`, not `npm`, because the manifest uses the workspace `catalog:` protocol for `openapi-fetch` and only pnpm rewrites it to a real range in the tarball.
+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 publishes that tarball through the `admin-cli-publish.yml` OIDC trusted publisher configured on npmjs.com.
 
 ## Install (from a checkout — CLI development)
 
@@ -92,4 +92,49 @@ human explicitly approves the exceptional `--allow-strand` override.
 
 MAP uploads accept one PDF up to 15 MB. The preview includes the resolved path, byte count, and SHA-256 without contacting the API; the confirmed command sends the report to the existing tutor-dashboard extraction route.
 
-See `recess --help` for the complete P0 command surface. The raw escape hatch is intentionally read-only: `recess --json request get /path`.
+## Authoring learning content
+
+```bash
+recess --json skills get os-v2-goal-template-builder --all-references
+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 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>
+```
+
+## Keeping the agent skill current
+
+```bash
+recess --json --version          # {cliVersion, skillVersion}
+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,
+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
+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).
+
+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
+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.
+
+See `recess --help` for the complete command surface. The raw escape hatch is intentionally read-only: `recess --json request get /path`.

package/dist/args.js

@@ -1,18 +1,24 @@
 import { CliError } from "./errors.js";
 const BOOLEAN_FLAGS = new Set([
+    "all-references",
     "allow-strand",
     "cancel-subscriptions",
     "archived",
     "confirm",
+    "dry-run",
     "full",
     "help",
     "immediate",
+    "include-deleted",
     "mirrored",
     "no-collision",
     "json",
+    "refresh",
     "restore",
     "revoke",
     "send-email",
+    "spec-only",
+    "starter-only",
     "visual-only",
 ]);
 export function parseArgs(args) {