@tutorflow/cli 0.3.1 → 0.4.0

package/README.md

@@ -1,67 +1,274 @@
 # @tutorflow/cli
 
-TutorFlow CLI for creating AI-powered educational content (slides, videos, courses) and evaluating student responses from the terminal or from AI agents. Wraps the TutorFlow Platform API (`/v1/platform/*`).
+The TutorFlow command line for developers, CI jobs and AI agents. It creates courses, slide decks, tests, interactive modules, videos, games and simulations, grades learner answers, and manages learners and webhooks through the **TutorFlow Content API** (`/v1/content/*`). Account, billing and discovery commands use the **Agent Platform** account routes (`/v1/platform/agent/*`).
 
 - **Binary:** `tutorflow`
 - **Package:** [`@tutorflow/cli`](https://www.npmjs.com/package/@tutorflow/cli) (current version in [`package.json`](package.json))
 - **Source:** [tutorflow-io/cli](https://github.com/tutorflow-io/cli) (private)
-- **Node:** `>= 18` for runtime, `>= 20` for development (Vitest 4 requirement)
-- **Agent-friendly:** every command supports `--json` output, env-var auth (`TUTORFLOW_API_KEY`), and proper exit codes — see [Non-interactive / agent usage](#non-interactive--agent-usage)
+- **Node:** `>= 18` at runtime, `>= 20` for development (Vitest 4)
+- **Agent-friendly:** `--json` output, env-var auth, no prompts without a TTY, stable error codes and exit codes. See [Agent usage](#agent-usage).
 
-## Installation
+> **Upgrading from 0.3.x?** Content commands now need a `tf_content_` key and call the Content API; `tf_platform_` keys are refused there with `EPLATFORMKEY`. Generation is asynchronous: add `--wait` to get the finished resource. See [Migrating from 0.3](#migrating-from-03).
 
-### A. End users (recommended)
-
-Install globally with any package manager:
+## Quick start
 
 ```bash
-npm  install -g @tutorflow/cli
-pnpm add    -g @tutorflow/cli
-yarn global add @tutorflow/cli
-```
+npm install -g @tutorflow/cli        # or: npx @tutorflow/cli <command>
 
-Then anywhere on the system:
+# 1. Create an agent account. The tf_content_ key is saved to ~/.tutorflow/config.json.
+tutorflow agent register --name "My Agent" --slug my-agent --email me@example.com
 
-```bash
-tutorflow --version
-tutorflow auth login
-tutorflow agent register --name "My Agent Workspace" --slug my-agent-workspace --email me@example.com
-tutorflow --json platform manifest
-tutorflow slide create "My first deck"
-```
+# 2. Generate content into the account's default classroom and wait for it.
+tutorflow course generate "Beginner Python for analysts" --lessons 3 --wait
+tutorflow slide generate "Photosynthesis" --count 8 --wait
+tutorflow test generate "Algebra basics" --items 5 --wait
 
-**One-shot use without installing**:
+# 3. Grade an answer and read the learner model it builds.
+tutorflow evaluate --type open-ended --question "Why is the sky blue?" \
+  --student-answer "Air scatters blue light more." --learner-id student-7 --concept-tags light,atmosphere
+tutorflow evaluation mastery student-7
 
-```bash
-npx @tutorflow/cli slide create "My first deck"
+# 4. Check what it cost.
+tutorflow credits balance
 ```
 
-This is the recommended path for AI agents and CI environments — no install step, always pulls the latest published version.
+## Keys and classrooms
+
+| Key prefix | Works with | Notes |
+| --- | --- | --- |
+| `tf_content_…` | every command | Returned by `agent register` as `contentApiKey`, or created in the Agent Platform dashboard. |
+| `tf_content_test_…` | content commands | Reaches only the sandbox classroom, returns canned results and spends nothing. Learner routes refuse test keys. |
+| `tf_platform_…` (deprecated) | `agent`, `platform` | Refused by content commands with `EPLATFORMKEY`. The Platform content routes it served are being removed. |
+
+Every content command acts in one classroom, chosen in this order:
+
+1. `--classroom <id>` (a global flag; works before or after the subcommand)
+2. `TUTORFLOW_CLASSROOM_ID`
+3. `classroomId` in `~/.tutorflow/config.json` (`tutorflow config set classroomId <id>`)
+4. `GET /v1/platform/agent/account`: `sandboxClassroomId` for a test key, `defaultClassroomId` otherwise
+5. `GET /v1/content/classrooms` when the account route refuses the key (a classroom Settings key): the only classroom, or the sandbox one for a test key; with several, the command exits 2 (`ECLASSROOM`) and lists them
+
+`tutorflow classroom list` shows the classrooms the key can reach.
+
+## Commands
+
+All ids are UUIDs. Every command accepts `--json`.
+
+### Account and discovery (`/v1/platform`)
+
+| Command | Route |
+| --- | --- |
+| `agent register --name --slug [--email] [--agent-identity] [--no-save]` | `POST /v1/platform/agent/register` (public). Saves `contentApiKey`. Pass `--email`: verification is required before buying credits. |
+| `agent account` | `GET /v1/platform/agent/account`: balance, `defaultClassroomId`, `sandboxClassroomId`, Content API URLs |
+| `agent billing status` | `GET /v1/platform/agent/billing/status` |
+| `agent billing session` | `POST /v1/platform/agent/billing/session`: hosted checkout URL for a human (verified email) |
+| `agent billing x402-deposit --amount-usd <n>` | `POST /v1/platform/agent/billing/x402/deposit`: USDC deposit address on Base (verified email) |
+| `agent checkout info --token` / `agent checkout create --token --amount-usd` | `GET` / `POST /v1/platform/agent/checkout` (public) |
+| `agent verify-email resend` | `POST /v1/platform/agent/verify-email/resend` |
+| `platform manifest` / `platform pricing` | `GET /v1/platform/.well-known/agent.json` / `GET /v1/platform/pricing-catalog` (public) |
+| `platform health` | `GET /v1/platform/health` |
+| `platform share-redirect <shareToken>` | `GET /v1/platform/share-redirects/{token}` (public): where an old Platform share link moved |
+
+### Generated content (`/v1/content/classrooms/{classroomId}/…`)
+
+| Command | Route | Credits |
+| --- | --- | --- |
+| `course generate [prompt] [--lessons] [--language] [--level] [--title] [--description]` | `POST …/courses/generate` | 3 + 3 per lesson |
+| `slide generate [topic] [--count 5-20] [--theme] [--instructions] [--text-length concise\|detailed]` | `POST …/slides/generate` | per page |
+| `test generate [topic] [--items] [--item-types select,blank,…] [--level] [--total-score]` | `POST …/tests/generate` | 3 |
+| `module generate [topic] [--type markdown\|ai-tutor\|flashcard\|…] [--reference]` | `POST …/modules/generate` | 3 |
 
-### B. Local development (this repo)
+`generate` (alias `create`) answers `202` with a run. Add `--wait [--timeout <seconds>]` to poll the run and print `{ run, resource }` with the resource's `editorUrl` and `publicUrl`. Every generate accepts `--idempotency-key`.
+
+Each of `course`, `slide`, `test`, `module`, `video`, `game` and `simulation` also has:
+
+| Subcommand | Route |
+| --- | --- |
+| `list [--limit] [--page] [--search]` | `GET …/{resource}` (JSON mode prints the raw `{ data, meta }` page) |
+| `get <id>` | `GET …/{resource}/{id}` |
+| `open <id> [--editor]` | prints `editorUrl` and `publicUrl`; opens one in a browser on a TTY |
+| `delete <id> --yes` | `DELETE …/{resource}/{id}` (`--yes` required without a TTY) |
+
+`test results <testId>` lists learners' results (`GET …/tests/{id}/results`).
+
+### Runs
+
+| Command | Route |
+| --- | --- |
+| `run list [--kind course\|slide\|test\|module] [--status] [--limit] [--cursor]` | `GET …/runs` |
+| `run get <runId>` | `GET …/runs/{runId}` |
+| `run wait <runId> [--timeout]` | polls `GET …/runs/{runId}`; prints `{ run, resource }` |
+| `run resume <runId>` | `POST …/runs/{runId}/resume` (course runs only) |
+
+A failed run exits 1 with `ERUNFAILED`; a timeout exits 1 with `ETIMEOUT` and names the `run wait` command to continue. Polling rides out up to five transient 5xx, 429 or network failures in a row.
+
+### Videos
+
+The Content API builds videos from scenes you script; it does not write the script from a prompt.
+
+| Command | Route |
+| --- | --- |
+| `video create --title [--description] [--visibility] [--scene "<script>"]…` | `POST …/videos`, then one scene per `--scene` in order |
+| `video scene add <videoId> [--script] [--display-text] [--duration] [--after <sceneId>]` | `POST …/videos/{id}/scenes`, then `PATCH` the new scene |
+| `video scene update <videoId> <sceneId> [--script] [--display-text] [--duration]` | `PATCH …/scenes/{sceneId}` |
+| `video scene delete <videoId> <sceneId> --yes` | `DELETE …/scenes/{sceneId}` |
+| `video narrate <videoId> [--scene <sceneId>]` | `POST …/narration` (1 credit per scene) |
+| `video render <videoId> [--generate-missing-narration] [--wait]` | `POST …/videos/{id}/render` (5 credits; `--wait` polls until `COMPLETED` and prints the mp4 URL) |
+| `video render-status <videoId>` / `video render-cancel <videoId>` | `GET …/render` / `POST …/render/cancel` |
+
+```bash
+tutorflow video create --title "Why the sky is blue" \
+  --scene "Sunlight is made of many colors." \
+  --scene "Air scatters blue light the most, so the sky looks blue."
+tutorflow video render <videoId> --generate-missing-narration --wait
+```
+
+### Games and simulations
+
+`game` and `simulation` share one lifecycle. The CLI always asks for the asynchronous answer (`Prefer: respond-async`), so `--wait` polls the resource's run route.
+
+| Command | Route | Credits |
+| --- | --- | --- |
+| `create --title [--description] [--visibility PRIVATE\|PUBLIC]` | `POST …/{games\|simulations}` | 0 |
+| `brief <id> [--reference <markdown>] [--wait]` | `POST …/{id}/brief` | 1 |
+| `build <id> [--wait]` | `POST …/{id}/build` | game 40, simulation 20 (2D) or 30 (3D) |
+| `revise <id> --feedback <text> [--wait]` | `POST …/{id}/revise` | as build |
+| `status <id>` | `GET …/{id}/run` | |
+
+### Evaluations and learners
+
+| Command | Route |
+| --- | --- |
+| `evaluate --type --question --student-answer [--expected-answer] [--rubric-json] [--max-score] [--learner-id] [--concept-tags a,b] [--subject] [--idempotency-key]` | `POST …/evaluations` (1 credit, synchronous) |
+| `evaluation list [--learner-id] [--status] [--type] [--limit] [--cursor]` / `evaluation get <id>` | `GET …/evaluations` |
+| `evaluation concepts` / `evaluation mastery <learnerId>` | `GET …/concepts` / `GET …/mastery/{learner}` |
+| `learner list` / `get <id>` / `progress <id>` | `GET …/learners…` (live keys only) |
+| `learner invite --email [--name] [--locale] [--course <id>]… [--test <id>]…` | `POST …/learners/invitations` |
+| `learner remove <id> --yes` | `DELETE …/learners/{id}` |
+
+`--type` takes `exact`, `rubric_short_answer` or `open_ended` (aliases `rubric`, `open-ended`). `exact` needs `--expected-answer`; `rubric_short_answer` needs `--rubric-json`.
+
+### Webhooks and credits (`/v1/content`)
+
+| Command | Route |
+| --- | --- |
+| `webhook list` / `get <id>` | `GET /v1/content/webhooks[/{id}]` |
+| `webhook create --url --event <event>… [--mode live\|test]` | `POST /v1/content/webhooks` (the signing secret is shown once) |
+| `webhook test <id>` / `deliveries <id>` / `rotate-secret <id>` / `delete <id> --yes` | the matching `/v1/content/webhooks/{id}/…` routes |
+| `credits balance` | `GET /v1/content/credits` |
+| `credits history [--limit] [--cursor] [--from] [--to] [--type]` | `GET /v1/content/credits/history` |
+
+Webhook management needs the `webhooks:manage` scope, which the key from `agent register` has. Events include `course.generation.completed`, `slide.generation.completed`, `test.generation.completed`, `module.generation.completed`, `video.render.completed`, `game.build.completed`, `simulation.build.completed` and their `.failed` twins.
+
+### Auth and config
+
+| Command | Effect |
+| --- | --- |
+| `auth login --api-key <key>` | Save a key (prompts on a TTY when omitted) |
+| `auth whoami` | Masked key, `keyKind` (`content_live`, `content_test`, `platform`, `unknown`), base URL, `source` (`env` or `config`). No network call. |
+| `auth logout --force` | Delete `~/.tutorflow/config.json` |
+| `config get [key]` / `config set <key> <value>` | Keys: `apiKey`, `baseUrl`, `classroomId` |
+
+The config file is written with mode `0600`.
+
+## Agent usage
+
+```bash
+export TUTORFLOW_API_KEY=tf_content_xxx
+export TUTORFLOW_JSON=1
+
+run=$(tutorflow course generate "Fractions for 5th grade" --lessons 2)
+tutorflow run wait "$(echo "$run" | jq -r .runId)" | jq -r .resource.publicUrl
+```
+
+- **Output:** with `--json` or `TUTORFLOW_JSON=1`, success is one JSON document on stdout and errors are JSON on stderr. Progress lines (text mode only) go to stderr.
+- **No prompts without a TTY:** a missing required input exits 2 with `ENOINTERACTIVE` and names the flag to pass. Destructive commands need `--yes`.
+- **Retries:** create and generate commands accept `--idempotency-key`.
+- **Errors:** `{"error":{"message","code",…}}`. API errors add `status`, `apiCode` (the Content API's code, e.g. `content_payment_required`), `requestId`, and when useful `hint`, `retryAfterSeconds`, `requiredScope`, `validation`, `billingSessionUrl`, `x402`.
+
+| Exit | Meaning |
+| --- | --- |
+| `0` | Success |
+| `1` | Failure: auth, network, API error, failed run, timeout |
+| `2` | Bad input: invalid flag, missing input without a TTY, ambiguous classroom |
+| `130` | Cancelled at a prompt |
+
+| Code | When |
+| --- | --- |
+| `EAUTH` | No API key |
+| `EPLATFORMKEY` | A `tf_platform_` key on a content command |
+| `ECLASSROOM` | No classroom could be chosen; pass `--classroom` |
+| `EINVAL` | Invalid flag value |
+| `ENOINTERACTIVE` | Missing input or confirmation without a TTY |
+| `EHTTP_<status>` | API error; see `apiCode` |
+| `ENETWORK` | The API could not be reached |
+| `ERUNFAILED` | A waited run, build or render failed |
+| `ETIMEOUT` | `--wait` gave up; the work continues on the server |
+| `ENOPREVIEW` | `open` found no URL |
+| `ENOTFOUND` | `config get` of an unset key |
+| `ECANCELLED` | Prompt cancelled |
+
+| Environment variable | Effect |
+| --- | --- |
+| `TUTORFLOW_API_KEY` | API key (wins over the config file) |
+| `TUTORFLOW_BASE_URL` | API origin, e.g. `https://dev-api.tutorflow.io` for staging |
+| `TUTORFLOW_CLASSROOM_ID` | Classroom for content commands |
+| `TUTORFLOW_JSON=1` | JSON mode |
+| `TUTORFLOW_DEBUG=1` / `DEBUG=1` | Stack traces on errors |
+| `TUTORFLOW_POLL_INTERVAL_MS` | `--wait` poll interval (default 3000) |
+
+Empty environment variables are ignored.
+
+## Migrating from 0.3
+
+| 0.3 | Now |
+| --- | --- |
+| `tf_platform_` key on every command | `tf_content_` key; `agent register` saves it. Platform keys still work on `agent` and `platform`. |
+| `/v1/platform/{courses,slides,tests,modules,videos,evaluations}` | `/v1/content/classrooms/{classroomId}/…` |
+| `course create` returned the finished course (`mode: sync`) | `course generate` (alias `create`) returns a run; add `--wait` |
+| `course create -l 10 -lang ko` | `course generate --lessons 10 --language ko` |
+| `slide create -t <theme>` | `slide generate --theme <themeId>` (5 to 20 pages) |
+| `video create "<prompt>" -s 6 -r 16:9 -d 90` | `video create --title … --scene "<script>"…`, then `video render --generate-missing-narration --wait` |
+| `module create --title --target --locale --private --no-quiz` | `module generate [--type] [--reference]`; edit the rest in the classroom editor |
+| `test create --classroom-id --tier --mode --time-limit` | `test generate` with the global `--classroom`; generation is always asynchronous |
+| `test edit-token`, `previewUrl` | `editorUrl` and `publicUrl` on every resource; `open <id>` |
+| list `--offset` | `--page` |
+| `evaluate` → `/v1/platform/evaluations` | `evaluate` → `…/evaluations`, plus `--learner-id` and `--concept-tags` |
+
+New in this version: `classroom`, `run`, `game`, `simulation`, `evaluation`, `learner`, `webhook`, `credits`, `video scene|narrate|render`, `agent billing x402-deposit`, `platform share-redirect`, `delete` on every resource, and the global `--classroom`.
+
+## Development
 
 ```bash
-git clone https://github.com/tutorflow-io/cli.git
-cd cli
+git clone https://github.com/tutorflow-io/cli.git && cd cli
 pnpm install
-pnpm build
-pnpm link              # exposes the `tutorflow` binary globally
+pnpm build && pnpm test       # the e2e suites spawn dist/index.js
+pnpm dev -- course list       # run from source
+pnpm link                     # expose `tutorflow` globally
 ```
 
-Verify:
+Try it against staging with a throwaway account:
 
 ```bash
-tutorflow --version       # matches package.json
-tutorflow --help
+export HOME=$(mktemp -d) TUTORFLOW_BASE_URL=https://dev-api.tutorflow.io
+node dist/index.js agent register --name "CLI test" --slug cli-test-$(date +%s)
+node dist/index.js course generate "Water cycle" --lessons 1 --wait
 ```
 
-To unlink later: `npm unlink -g @tutorflow/cli`.
+### Layout
 
-Run from source without building:
-
-```bash
-pnpm dev -- <command> [options]
-# e.g. pnpm dev -- slide list --limit 5
+```
+src/
+├── index.ts               # commander entrypoint and global flags (--json, --debug, --classroom)
+├── client.ts              # ApiClient: config resolution, HTTP, error envelope → CliError
+├── config.ts              # ~/.tutorflow/config.json (mode 0600)
+├── content/
+│   ├── context.ts         # tf_content_ key check and classroom resolution
+│   ├── resource.ts        # shared list/get/open/delete/generate subcommands
+│   └── runs.ts            # waiting on runs, game/simulation builds and renders
+├── commands/              # one file per top-level command
+├── utils/                 # runtime (JSON mode, CliError), output, args, keys
+└── testing/harness.ts     # test-only: fake API server and CLI spawner
 ```
 
 ## Releasing
@@ -128,7 +335,7 @@ These tripped us up during initial setup. Read before changing release infrastru
 
 ### Tarball hygiene
 
-- `tsconfig.json` excludes `**/*.test.ts` so test files don't end up in `dist/` (and therefore not in the published tarball).
+- `tsconfig.json` excludes `**/*.test.ts` and `src/testing/` so test code doesn't end up in `dist/` (and therefore not in the published tarball).
 - `package.json#files` is an allowlist (`dist`, `README.md`, `LICENSE`). Anything not listed is excluded.
 - Run `npm pack --dry-run` to inspect the tarball before publish.
 
@@ -136,631 +343,6 @@ These tripped us up during initial setup. Read before changing release infrastru
 
 The published tarball currently includes `.js.map` and `.d.ts.map` files which embed paths from the build environment. While the source itself isn't shipped, this leaks file structure. If that matters, set `sourceMap: false` and `declarationMap: false` in [tsconfig.json](tsconfig.json) before going public.
 
-## Development
-
-Run with `tsx` (no build step):
-
-```bash
-pnpm dev -- <command> [options]
-# e.g. pnpm dev -- slide list --limit 5
-```
-
-Build artifacts land in `dist/` (entry: `dist/index.js`, declared in `package.json#bin`).
-
-## Non-interactive / agent usage
-
-Every command supports the contract below so AI agents and CI scripts can use the CLI without a TTY.
-
-### Auth without prompts
-
-```bash
-# Option 1: env var (preferred for one-shot calls)
-TUTORFLOW_API_KEY=tf_xxx tutorflow --json slide list
-
-# Option 2: persist to ~/.tutorflow/config.json once
-tutorflow auth login --api-key tf_xxx
-tutorflow --json slide create "Photosynthesis for 5th graders" -n 12
-```
-
-`TUTORFLOW_API_KEY` always wins over the config file. `tutorflow auth whoami --json` reports `source: "env" | "config"` so an agent can verify which credential is active.
-
-### Machine-readable output
-
-`--json` (or `TUTORFLOW_JSON=1`) makes every command emit a single JSON line on stdout. Errors emit JSON to stderr.
-
-```bash
-$ tutorflow --json auth whoami
-{"authenticated":true,"apiKeyPreview":"tf_xxxxxxx...","baseUrl":"https://api.tutorflow.io","source":"env"}
-
-$ tutorflow --json auth whoami    # without auth
-# stdout: (empty)
-# stderr: {"error":{"message":"Not authenticated","code":"EAUTH"}}
-# exit:   1
-```
-
-List commands return raw arrays:
-
-```bash
-$ tutorflow --json slide list --limit 3
-[{"id":"...","title":"...","status":"ready","createdAt":"..."},...]
-```
-
-Pipe into `jq` for downstream automation:
-
-```bash
-tutorflow --json slide list --status ready | jq -r '.[].id' | xargs -I{} tutorflow --json slide get {}
-```
-
-### Exit codes
-
-| Code  | Meaning                                                           |
-| ----- | ----------------------------------------------------------------- |
-| `0`   | Success                                                           |
-| `1`   | Generic failure (auth, network, API error, etc.)                  |
-| `2`   | Bad input (invalid flag value, missing required input in non-TTY) |
-| `130` | User cancelled an interactive prompt (Ctrl+C)                     |
-
-The error JSON includes a stable `code`: `EAUTH`, `EINVAL`, `ENOINTERACTIVE`, `ENETWORK`, `EHTTP_<status>`, `ENOPREVIEW`, `ENOTFOUND`, `ECANCELLED`.
-
-### Required-input flags (no prompts)
-
-Commands that have required input expose every prompt as a flag:
-
-```bash
-# self-register a platform workspace and save the returned API key
-tutorflow --json agent register \
-  --name "Agent Workspace" \
-  --slug agent-workspace \
-  --email agent@example.com \
-  --agent-identity "codex"
-
-# slide / video / course create — accept positional [prompt]
-tutorflow --json slide create "Photosynthesis" -n 12 -l en
-tutorflow --json video create "Newton's laws" -s 6 -r 16:9 -d 90
-tutorflow --json course create "Beginner Python" -l 10 -lang en
-
-# evaluate — every input is a flag
-tutorflow --json evaluate \
-  --type exact \
-  --question "What is 2+2?" \
-  --student-answer "4" \
-  --expected-answer "4"
-
-# logout (skip confirmation)
-tutorflow auth logout --force
-```
-
-If a required input is missing **and** stdin is not a TTY, the command exits 2 with `ENOINTERACTIVE` and an error message naming the flag(s) to use. It never hangs waiting for input.
-
-### Globals
-
-| Flag                              | Env var                          | Effect                                          |
-| --------------------------------- | -------------------------------- | ----------------------------------------------- |
-| `--json`                          | `TUTORFLOW_JSON=1`               | JSON output to stdout, JSON errors to stderr    |
-| `--debug`                         | `DEBUG=1` or `TUTORFLOW_DEBUG=1` | Print stack traces on errors                    |
-| `--api-key <k>` (auth login only) | `TUTORFLOW_API_KEY`              | API key                                         |
-| (n/a)                             | `TUTORFLOW_BASE_URL`             | Override API base URL (staging, self-hosted)    |
-
-### MCP server
-
-A native MCP server (so agents can call tools directly without shelling out) is on the roadmap. For now, the `--json` shell contract is the recommended integration path.
-
-## Authentication
-
-Generate an API key in your TutorFlow workspace, then:
-
-```bash
-tutorflow auth login      # interactive password prompt for API key
-tutorflow auth whoami     # prints masked API key + base URL
-tutorflow auth logout     # confirms then deletes ~/.tutorflow/config.json
-```
-
-Credentials are persisted to `~/.tutorflow/config.json`:
-
-```json
-{
-  "apiKey": "tf_xxxxxxxxxxxxxxxxxxxx",
-  "baseUrl": "https://api.tutorflow.io",
-  "workspace": "optional-workspace-slug"
-}
-```
-
-The API key is sent as the `Authorization: Bearer <apiKey>` header on authenticated requests.
-
-### Config schema
-
-```ts
-interface IConfig {
-  apiKey?: string;     // required for all non-auth/config commands
-  baseUrl?: string;    // default: https://api.tutorflow.io
-  workspace?: string;  // optional workspace slug
-}
-```
-
-## Configuration commands
-
-```bash
-tutorflow config get                      # print full config (apiKey is masked)
-tutorflow config get <key>                # print one key as KEY=VALUE
-tutorflow config set <key> <value>        # update one key
-```
-
-| Key         | Type     | Default                    | Notes                                  |
-| ----------- | -------- | -------------------------- | -------------------------------------- |
-| `apiKey`    | `string` | none                       | Set via `auth login` or `config set`   |
-| `baseUrl`   | `string` | `https://api.tutorflow.io` | Override for staging / self-hosted     |
-| `workspace` | `string` | none                       | Reserved for future scoping            |
-
-`config set` rejects unknown keys.
-
-## Commands
-
-All resource commands require authentication. Without an API key they print:
-`✗ Not authenticated. Run "tutorflow auth login" first.`
-
-### `tutorflow agent`
-
-Manage the agent-facing TutorFlow Platform account flow.
-
-#### `agent register`
-
-Public self-service registration. Creates a platform workspace through
-`POST /v1/platform/agent/register`, returns the one-time API key, and saves it
-to `~/.tutorflow/config.json` by default so the next CLI command can run
-without a separate `auth login`.
-
-| Option                         | Type     | Default | Description                                  |
-| ------------------------------ | -------- | ------- | -------------------------------------------- |
-| `--name <name>`                | `string` | —       | Workspace display name                       |
-| `--slug <slug>`                | `string` | —       | Unique lowercase slug                        |
-| `--email <email>`              | `string` | none    | Contact email for verification and billing   |
-| `--agent-identity <identity>`  | `string` | none    | Optional agent identity string               |
-| `--no-save`                    | boolean  | false   | Print the API key but do not persist it      |
-
-```bash
-tutorflow --json agent register \
-  --name "Agent Workspace" \
-  --slug agent-workspace \
-  --email agent@example.com \
-  --agent-identity "codex"
-```
-
-#### `agent account`
-
-GET `/v1/platform/agent/account`. Shows workspace status, credit balance,
-email verification state, rate limits, and `restrictedActions`.
-
-```bash
-tutorflow --json agent account
-```
-
-#### `agent billing status`
-
-GET `/v1/platform/agent/billing/status`. Shows payment-method state, credit
-balance, billing mode, email verification state, and `restrictedActions`.
-
-```bash
-tutorflow --json agent billing status
-```
-
-#### `agent billing session`
-
-POST `/v1/platform/agent/billing/session`. Returns a TutorFlow-hosted checkout
-URL that an agent should forward to a human operator.
-
-```bash
-tutorflow --json agent billing session
-```
-
-#### `agent verify-email resend`
-
-POST `/v1/platform/agent/verify-email/resend`. Resends the workspace email
-verification message using the active API key.
-
-```bash
-tutorflow --json agent verify-email resend
-```
-
-#### `agent checkout info`
-
-GET `/v1/platform/agent/checkout?token=<token>`. Reads workspace info for a
-TutorFlow checkout token returned through the hosted billing-session flow.
-
-```bash
-tutorflow --json agent checkout info --token checkout_123
-```
-
-#### `agent checkout create`
-
-POST `/v1/platform/agent/checkout`. Creates a Stripe Checkout URL from a
-TutorFlow checkout token and amount. This is normally called by the hosted
-checkout page; CLI support exists for complete automation and testing.
-
-```bash
-tutorflow --json agent checkout create --token checkout_123 --amount-usd 25
-```
-
-### `tutorflow platform`
-
-Inspect public discovery metadata and validate the active Platform API key.
-
-| Subcommand | Endpoint | Auth |
-| ---------- | -------- | ---- |
-| `manifest` | `GET /v1/platform/.well-known/agent.json` | none |
-| `pricing` | `GET /v1/platform/pricing-catalog` | none |
-| `health` | `GET /v1/platform/health` | Platform API key |
-
-```bash
-tutorflow --json platform manifest
-tutorflow --json platform pricing
-tutorflow --json platform health
-```
-
-### `tutorflow slide`
-
-Create and manage slide decks.
-
-#### `slide create [prompt]`
-
-Creates a slide deck synchronously (`mode: 'sync'`).
-
-| Argument / Option       | Type                  | Default | Description                          |
-| ----------------------- | --------------------- | ------- | ------------------------------------ |
-| `[prompt]`              | `string` (positional) | —       | Prompted interactively if omitted    |
-| `-n, --count <number>`  | `string → int`        | `10`    | Slide count (parsed via `parseInt`)  |
-| `-l, --language <lang>` | `string`              | `en`    | ISO 639-1 language code              |
-| `-t, --theme <theme>`   | `string`              | none    | Theme identifier                     |
-
-POST `/v1/platform/slides` body:
-
-```json
-{
-  "prompt": "...",
-  "slideCount": 10,
-  "language": "en",
-  "theme": "...",
-  "mode": "sync"
-}
-```
-
-Output: `id`, `status`, `previewUrl` (if returned). After creation, prompts to open the preview URL in the browser.
-
-```bash
-tutorflow slide create "Photosynthesis for 5th graders" -n 12 -l en -t classic
-```
-
-#### `slide list`
-
-| Option                  | Type     | Default | Description                |
-| ----------------------- | -------- | ------- | -------------------------- |
-| `-l, --limit <number>`  | `string` | `10`    | Max rows to fetch          |
-| `-s, --status <status>` | `string` | none    | Server-side status filter  |
-
-GET `/v1/platform/slides?limit=<n>[&status=<s>]`. Renders an ASCII table with `ID` (8-char prefix), `Title`, `Status`, `Created`.
-
-#### `slide open <id>`
-
-Fetches `/v1/platform/slides/:id` and opens `previewUrl` in the default browser via [`open`](https://github.com/sindresorhus/open).
-
----
-
-### `tutorflow video`
-
-Create and manage AI-generated videos.
-
-#### `video create [prompt]`
-
-Creates a video synchronously (`mode: 'sync'`).
-
-| Argument / Option          | Type                  | Default | Description                              |
-| -------------------------- | --------------------- | ------- | ---------------------------------------- |
-| `[prompt]`                 | `string` (positional) | —       | Prompted interactively if omitted        |
-| `-s, --scenes <number>`    | `string → int`        | `5`     | Scene count                              |
-| `-r, --ratio <ratio>`      | `string`              | `16:9`  | Aspect ratio (`16:9`, `9:16`, `1:1`, …)  |
-| `-d, --duration <seconds>` | `string → int`        | `60`    | Target duration in seconds               |
-| `-l, --language <lang>`    | `string`              | `en`    | ISO 639-1 language code                  |
-
-POST `/v1/platform/videos` body:
-
-```json
-{
-  "prompt": "...",
-  "sceneCount": 5,
-  "aspectRatio": "16:9",
-  "targetDurationSeconds": 60,
-  "language": "en",
-  "mode": "sync"
-}
-```
-
-Output: `id`, `status`, `sceneCount`, `previewUrl` (if returned). Prompts to open in browser.
-
-```bash
-tutorflow video create "Intro to Newton's laws" -s 6 -r 16:9 -d 90 -l en
-```
-
-#### `video list`
-
-| Option                  | Type     | Default | Description                |
-| ----------------------- | -------- | ------- | -------------------------- |
-| `-l, --limit <number>`  | `string` | `10`    | Max rows                   |
-| `-s, --status <status>` | `string` | none    | Server-side status filter  |
-
-GET `/v1/platform/videos?limit=<n>[&status=<s>]`. Table columns: `ID`, `Title`, `Status`, `Scenes`, `Created`.
-
-#### `video open <id>`
-
-Opens the video preview URL in the browser.
-
----
-
-### `tutorflow course`
-
-Create and manage multi-lesson courses.
-
-#### `course create [prompt]`
-
-| Argument / Option          | Type                  | Default | Description                       |
-| -------------------------- | --------------------- | ------- | --------------------------------- |
-| `[prompt]`                 | `string` (positional) | —       | Prompted interactively if omitted |
-| `-l, --lessons <number>`   | `string → int`        | `8`     | Lesson count                      |
-| `-lang, --language <lang>` | `string`              | `en`    | ISO 639-1 language code           |
-
-> Note: `--language` uses the short flag `-lang` (not `-L`), because `-l` is already taken by `--lessons`.
-
-POST `/v1/platform/courses` body:
-
-```json
-{
-  "prompt": "...",
-  "lessonCount": 8,
-  "language": "en",
-  "mode": "sync"
-}
-```
-
-```bash
-tutorflow course create "Beginner Python in Korean" -l 10 -lang ko
-```
-
-#### `course list`
-
-| Option                 | Type     | Default | Description |
-| ---------------------- | -------- | ------- | ----------- |
-| `-l, --limit <number>` | `string` | `10`    | Max rows    |
-
-GET `/v1/platform/courses?limit=<n>`. Table columns: `ID`, `Title`, `Status`, `Created`.
-
-#### `course open <id>`
-
-Opens the course preview URL in the browser.
-
----
-
-### `tutorflow module`
-
-Create and manage standalone lesson modules.
-
-#### `module create [prompt]`
-
-POST `/v1/platform/modules`. Generates one classroom-compatible standalone
-lesson. `--idempotency-key` is sent as the `Idempotency-Key` header so agents
-can safely retry a create call.
-
-| Argument / Option              | Type                  | Default  | Description                      |
-| ------------------------------ | --------------------- | -------- | -------------------------------- |
-| `[prompt]`                     | `string` (positional) | —        | Lesson/module prompt             |
-| `--title <title>`              | `string`              | none     | Override generated title         |
-| `--description <description>`  | `string`              | none     | Override generated description   |
-| `--target <target>`            | `string`              | none     | Target learner audience          |
-| `--type <type>`                | `string`              | `lesson` | Module type                      |
-| `--locale <locale>`            | `string`              | `en`     | Locale code                      |
-| `--language <language>`        | `string`              | `en`     | Language code                    |
-| `--slug <slug>`                | `string`              | none     | Optional slug                    |
-| `--private`                    | boolean               | false    | Set `isPublic: false`            |
-| `--no-quiz`                    | boolean               | false    | Set `hasQuiz: false`             |
-| `--idempotency-key <key>`      | `string`              | none     | Safe retry key                   |
-
-```bash
-tutorflow --json module create "Fractions for 5th grade" \
-  --title "Fractions" \
-  --target "5th grade" \
-  --no-quiz \
-  --idempotency-key lesson-001
-```
-
-#### `module list`
-
-GET `/v1/platform/modules?limit=<n>&offset=<n>[&search=<q>]`.
-
-```bash
-tutorflow --json module list --limit 20 --offset 0 --search fractions
-```
-
-#### `module get <id>` / `module open <id>`
-
-Fetch a module by ID or open its `publicUrl`.
-
----
-
-### `tutorflow test`
-
-Create and manage generated assessments.
-
-#### `test create [prompt]`
-
-POST `/v1/platform/tests`. Generates a test/assessment. `--idempotency-key` is
-sent as the `Idempotency-Key` header.
-
-| Argument / Option         | Type                  | Default    | Description                    |
-| ------------------------- | --------------------- | ---------- | ------------------------------ |
-| `[prompt]`                | `string` (positional) | —          | Test generation prompt         |
-| `--title <title>`         | `string`              | none       | Override generated title       |
-| `--description <text>`    | `string`              | none       | Override generated description |
-| `-l, --language <lang>`   | `string`              | `en`       | Language code                  |
-| `--level <level>`         | `string`              | none       | Difficulty level               |
-| `--subject <subject>`     | `string`              | none       | Subject area                   |
-| `-n, --items <number>`    | `string -> int`       | none       | Target item count              |
-| `--time-limit <minutes>`  | `string -> int`       | none       | Time limit in minutes          |
-| `--classroom-id <id>`     | `string`              | none       | Classroom ID                   |
-| `--tier <tier>`           | `string`              | `standard` | Pricing tier                   |
-| `--mode <mode>`           | `string`              | `sync`     | `sync` or `async`              |
-| `--idempotency-key <key>` | `string`              | none       | Safe retry key                 |
-
-```bash
-tutorflow --json test create "Algebra quiz" \
-  --title "Algebra Basics" \
-  --items 8 \
-  --time-limit 30 \
-  --idempotency-key test-001
-```
-
-#### `test list`
-
-GET `/v1/platform/tests?limit=<n>&offset=<n>[&status=<s>]`.
-
-```bash
-tutorflow --json test list --limit 20 --status READY
-```
-
-#### `test get <id>` / `test open <id>` / `test edit-token <id>`
-
-Fetch a test, open its preview URL, or generate a fresh edit token.
-
----
-
-### `tutorflow evaluate`
-
-Evaluates a single learner response through the Platform Evaluations API.
-
-| Option                    | Type     | Default    | Allowed values / notes |
-| ------------------------- | -------- | ---------- | ---------------------- |
-| `-t, --type <type>`       | `string` | (prompted) | `exact`, `rubric_short_answer`, `open_ended`. Aliases: `rubric`, `open-ended` |
-| `-q, --question <text>`   | `string` | (prompted) | Question text |
-| `-a, --student-answer <text>` | `string` | (prompted) | Learner answer |
-| `-e, --expected-answer <text>` | `string` | none | Required for `exact`; sent as `referenceAnswer` |
-| `--rubric-json <json>` | `string` | none | Required for `rubric_short_answer` |
-| `--max-score <number>` | `number` | backend default | Maximum score |
-| `-l, --language <lang>` | `string` | `en` | Feedback language |
-| `--idempotency-key <key>` | `string` | none | Safe retry key |
-
-Interactive flow:
-
-1. Type (if not supplied)
-2. Question
-3. Student answer
-4. Expected answer — required only when type is `exact`
-
-POST `/v1/platform/evaluations` body:
-
-```json
-{
-  "evaluationType": "exact",
-  "questionText": "What is 2+2?",
-  "learnerAnswer": "4",
-  "referenceAnswer": "4",
-  "language": "en",
-  "mode": "sync"
-}
-```
-
-`referenceAnswer` is omitted when `evaluationType` is `open_ended`.
-`rubric_short_answer` requires `--rubric-json`, for example:
-
-```bash
-tutorflow --json evaluate \
-  --type rubric_short_answer \
-  --question "Explain the water cycle" \
-  --student-answer "Water evaporates and condenses." \
-  --rubric-json '{"criteria":[{"name":"Accuracy","description":"Scientific correctness","maxScore":10}]}'
-```
-
----
-
-### `tutorflow auth`
-
-| Subcommand | Description                                          |
-| ---------- | ---------------------------------------------------- |
-| `login`    | Interactive prompt for API key, writes to config     |
-| `logout`   | Prompts to confirm, then deletes config file         |
-| `whoami`   | Prints masked API key (first 10 chars) and `baseUrl` |
-
-## Exit behavior & errors
-
-- All commands wrap their action in `try/catch`. Failures print `✗ <message>` in red and the raw error, but the process exit code is **not** set explicitly — it's whatever Node returns (typically `0`). Don't rely on exit codes for scripting yet.
-- `await prompt(...)` from `@clack/prompts` returns a `symbol` when the user cancels (Ctrl+C); commands check for this and print `Cancelled` instead of throwing.
-- HTTP errors from the API are surfaced as `Error: API Error: <status> <body-json>`.
-
-## API client
-
-Internal HTTP client lives in [src/client.ts](src/client.ts):
-
-```ts
-class ApiClient {
-  static async create(): Promise<ApiClient>;        // loads from ~/.tutorflow/config.json
-  request<T>(method: string, endpoint: string, body?: object): Promise<T>;
-  setApiKey(apiKey: string): void;
-  setBaseUrl(baseUrl: string): void;
-}
-```
-
-- Uses [`undici.fetch`](https://github.com/nodejs/undici).
-- Headers always include `Content-Type: application/json`. Authenticated requests also include `Authorization: Bearer <apiKey>`.
-- Throws `Error('API Error: <status> <body>')` on non-2xx.
-
-## Project layout
-
-```
-.
-├── package.json              # bin: { tutorflow: ./dist/index.js }
-├── tsconfig.json
-├── vitest.config.ts
-├── .github/workflows/
-│   ├── ci.yml                # typecheck + build + test on PRs and master
-│   └── release.yml           # OIDC publish on master/main pushes when version is new
-├── RELEASING.md              # full release procedure + Trusted Publisher setup
-└── src/
-    ├── index.ts              # commander entrypoint, registers all commands
-    ├── client.ts             # undici-based ApiClient
-    ├── client.test.ts
-    ├── config.ts             # ~/.tutorflow/config.json read/write/update/delete
-    ├── config.test.ts
-    ├── types.ts              # API response interfaces (SlideResource, etc.)
-    ├── commands/
-    │   ├── agent.ts          # register / account / billing / email verification
-    │   ├── auth.ts           # login / logout / whoami
-    │   ├── config.ts         # get / set
-    │   ├── course.ts         # create / list / open
-    │   ├── evaluate.ts       # interactive evaluation
-    │   ├── module.ts         # standalone lesson modules
-    │   ├── platform.ts       # discovery / pricing / health
-    │   ├── slide.ts          # create / list / open
-    │   ├── test.ts           # generated assessments
-    │   └── video.ts          # create / list / open
-    └── utils/
-        ├── output.ts         # formatTable, formatJson
-        └── spinner.ts
-```
-
-## npm scripts
-
-| Script           | Command                 | Purpose                                 |
-| ---------------- | ----------------------- | --------------------------------------- |
-| `dev`            | `tsx src/index.ts`      | Run from source                         |
-| `build`          | `tsc --outDir dist`     | Emit JS + `.d.ts` to `dist/`            |
-| `link`           | `npm link`              | Symlink `tutorflow` globally            |
-| `typecheck`      | `tsc --noEmit`          | Type-check without emitting             |
-| `test`           | `vitest run`            | Run all tests once                      |
-| `test:watch`     | `vitest`                | Watch-mode tests                        |
-| `test:coverage`  | `vitest run --coverage` | Generate coverage report                |
-| `prepublishOnly` | `rm -rf dist && build`  | Auto-runs before `npm publish`          |
-
 ## Stack
 
-- **CLI framework:** [commander](https://github.com/tj/commander.js) `^11.0.0`
-- **Prompts:** [@clack/prompts](https://github.com/natemoo-re/clack) `^0.7.0`
-- **HTTP:** [undici](https://github.com/nodejs/undici) `^5.27.0`
-- **Color:** [chalk](https://github.com/chalk/chalk) `^5.3.0`
-- **Browser open:** [open](https://github.com/sindresorhus/open) `^9.0.0`
-- **Tests:** [Vitest](https://vitest.dev) `^4.1.5`
-- **Dev:** TypeScript `^5.0.0`, tsx `^3.0.0`, `@types/node` `^20.0.0`
+[commander](https://github.com/tj/commander.js) 11, [@clack/prompts](https://github.com/natemoo-re/clack) 0.7, [undici](https://github.com/nodejs/undici) 5, [chalk](https://github.com/chalk/chalk) 5, [open](https://github.com/sindresorhus/open) 9; Vitest 4, TypeScript 5, tsx 3.