@tutorflow/cli 0.3.1 → 0.5.0

package/README.md

@@ -1,766 +1,368 @@
 # @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:
-
-```bash
-npm  install -g @tutorflow/cli
-pnpm add    -g @tutorflow/cli
-yarn global add @tutorflow/cli
-```
-
-Then anywhere on the system:
-
-```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"
-```
-
-**One-shot use without installing**:
-
-```bash
-npx @tutorflow/cli slide create "My first deck"
-```
-
-This is the recommended path for AI agents and CI environments — no install step, always pulls the latest published version.
-
-### B. Local development (this repo)
-
-```bash
-git clone https://github.com/tutorflow-io/cli.git
-cd cli
-pnpm install
-pnpm build
-pnpm link              # exposes the `tutorflow` binary globally
-```
-
-Verify:
+## Quick start
 
 ```bash
-tutorflow --version       # matches package.json
-tutorflow --help
-```
-
-To unlink later: `npm unlink -g @tutorflow/cli`.
-
-Run from source without building:
-
-```bash
-pnpm dev -- <command> [options]
-# e.g. pnpm dev -- slide list --limit 5
-```
-
-## Releasing
-
-Releases are automated by GitHub Actions on pushes to `master` / `main`.
-Auth uses **npm OIDC Trusted Publishing** — no `NPM_TOKEN` secret in CI.
-
-```bash
-git checkout master
-git pull
-
-npm version patch --no-git-tag-version  # 0.3.0 → 0.3.1 (or minor / major)
-git push origin master  # Release workflow publishes if that version is not on npm yet
-```
-
-The [`Release` workflow](.github/workflows/release.yml):
-
-1. Reads `package.json` name and version
-2. Skips npm publish if that exact version already exists
-3. Runs `pnpm typecheck` + `pnpm build` + `pnpm test`
-4. Publishes new versions with `npm publish --access public` (auth via OIDC)
-5. Creates a GitHub Release only for `v*.*.*` tag pushes
-
-For full setup (npm org, Trusted Publisher config) see [RELEASING.md](RELEASING.md).
-
-### Pre-release / beta
-
-```bash
-npm version prerelease --preid=beta --no-git-tag-version  # 0.3.1 → 0.3.2-beta.0
-git push origin master
-```
-
-Pre-release versions publish to a dist-tag derived from the prerelease id
-(`0.3.1-beta.0` publishes with `--tag beta`).
-
-## ⚠️ Caveats & gotchas
-
-These tripped us up during initial setup. Read before changing release infrastructure.
-
-### Versioning
-
-- **Don't hardcode the version in `src/index.ts`.** It reads `version` from [`package.json`](package.json) via `resolveJsonModule`. Hardcoding will silently lie to users via `--version` after every `npm version` bump.
-- The `prepublishOnly` script in `package.json` rebuilds `dist/` before publish. Don't skip it.
+npm install -g @tutorflow/cli        # or: npx @tutorflow/cli <command>
 
-### npm Trusted Publishing (OIDC)
-
-- **npm CLI must be 11.5.1+** for OIDC auth. npm also requires a modern Node 22 runtime for trusted publishing, so the workflow uses Node 22.x and invokes `pnpm dlx npm@latest ...` for registry checks and publish. Do not replace that with the runner's bundled npm unless you verify its version supports OIDC trusted publishing.
-- The Trusted Publisher binding at [npmjs.com/package/@tutorflow/cli/access](https://www.npmjs.com/package/@tutorflow/cli/access) hardcodes:
-  - GitHub org: `tutorflow-io`
-  - Repo: `cli`
-  - Workflow filename: `release.yml`
-  - Environment: (none)
-
-  Renaming the repo, moving the workflow file, or adding an `environment:` to the publish job will break OIDC auth until the binding is updated.
-- Local manual publishes still need a token (set `NPM_TOKEN` in `.env` or run `npm login`). Use a Granular Access Token with **"Bypass two-factor authentication (2FA)"** checked, otherwise CI/scripts get `EOTP` errors.
-
-### Provenance
-
-- `--provenance` is **disabled** in [release.yml](.github/workflows/release.yml). npm only accepts provenance attestations from **public** GitHub repos. Add `--provenance` back to the `npm publish` command when this repo goes public.
-
-### Node + tooling
+# 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
 
-- **Vitest 4.x requires Node 20+** (uses `node:util.styleText`). CI tests Node 20 and Node 22, while release publishing runs on Node 22 for npm OIDC. The runtime CLI itself still supports Node 18 (declared in `package.json#engines`).
-
-### Tarball hygiene
+# 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
 
-- `tsconfig.json` excludes `**/*.test.ts` so test files don'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.
-
-### Source maps and a private repo
-
-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.
+# 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
 
-## Development
-
-Run with `tsx` (no build step):
-
-```bash
-pnpm dev -- <command> [options]
-# e.g. pnpm dev -- slide list --limit 5
+# 4. Check what it cost.
+tutorflow credits balance
 ```
 
-Build artifacts land in `dist/` (entry: `dist/index.js`, declared in `package.json#bin`).
+## Keys and classrooms
 
-## Non-interactive / agent usage
+| 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 command supports the contract below so AI agents and CI scripts can use the CLI without a TTY.
+Every content command acts in one classroom, chosen in this order:
 
-### 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
-```
+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_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.
+`tutorflow classroom list` shows the classrooms the key can reach.
 
-### Machine-readable output
+## Commands
 
-`--json` (or `TUTORFLOW_JSON=1`) makes every command emit a single JSON line on stdout. Errors emit JSON to stderr.
+All ids are UUIDs. Every command accepts `--json`.
 
-```bash
-$ tutorflow --json auth whoami
-{"authenticated":true,"apiKeyPreview":"tf_xxxxxxx...","baseUrl":"https://api.tutorflow.io","source":"env"}
+### Account and discovery (`/v1/platform`)
 
-$ tutorflow --json auth whoami    # without auth
-# stdout: (empty)
-# stderr: {"error":{"message":"Not authenticated","code":"EAUTH"}}
-# exit:   1
-```
+| 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 |
 
-List commands return raw arrays:
+### Generated content (`/v1/content/classrooms/{classroomId}/…`)
 
-```bash
-$ tutorflow --json slide list --limit 3
-[{"id":"...","title":"...","status":"ready","createdAt":"..."},...]
-```
+| 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 |
 
-Pipe into `jq` for downstream automation:
+`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`.
 
-```bash
-tutorflow --json slide list --status ready | jq -r '.[].id' | xargs -I{} tutorflow --json slide get {}
-```
+Each of `course`, `slide`, `test`, `module`, `video`, `game` and `simulation` also has:
 
-### Exit codes
+| 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) |
+| `share <id> [--listed]` | `PATCH …/{resource}/{id}`: makes it open by link and prints `publicUrl` |
+| `visibility <id> <value>` | `PATCH …/{resource}/{id}` with that visibility |
 
-| 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)                     |
+`share` sets the least open value that still opens by link, and `visibility` takes the values below (case does not matter). The PATCH answer carries the new `publicUrl`; JSON mode prints the whole answer.
 
-The error JSON includes a stable `code`: `EAUTH`, `EINVAL`, `ENOINTERACTIVE`, `ENETWORK`, `EHTTP_<status>`, `ENOPREVIEW`, `ENOTFOUND`, `ECANCELLED`.
+| Resource | `share` sets | `visibility` values |
+| --- | --- | --- |
+| `video`, `test` | `UNLISTED` (opens by link, kept out of lists and search); `--listed` sets `PUBLIC` | `PUBLIC`, `UNLISTED`, `PRIVATE` |
+| `slide`, `game`, `simulation` | `PUBLIC` | `PUBLIC`, `PRIVATE` |
+| `course` | `PUBLIC` | `PUBLIC`, `PRIVATE`, `ORGANIZATION`, `CLASSROOM`, `COURSE` |
+| `module` | `isPublic: true` | `PUBLIC`, `PRIVATE` (written as `isPublic`) |
 
-### Required-input flags (no prompts)
-
-Commands that have required input expose every prompt as a flag:
+`publicUrl` can stay null after `share`: a video's watch page opens once it is rendered, a game or simulation's play page once it is built, a course page once the course is published, and the sandbox classroom of `tf_content_test_` keys has no public pages. A test's public page shows its cover; answering needs a learner sign-in. New tests start `PUBLIC`.
 
 ```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
+tutorflow --json video share <videoId> | jq -r .publicUrl
 ```
 
-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.
+`test results <testId>` lists learners' results (`GET …/tests/{id}/results`).
 
-### Globals
+### Runs
 
-| 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)    |
+| 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) |
 
-### MCP server
+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.
 
-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.
+### Videos
 
-## Authentication
+The Content API builds videos from scenes you script; it does not write the script from a prompt.
 
-Generate an API key in your TutorFlow workspace, then:
+| Command | Route |
+| --- | --- |
+| `video create --title [--description] [--visibility PUBLIC\|UNLISTED\|PRIVATE] [--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 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
+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
 ```
 
-Credentials are persisted to `~/.tutorflow/config.json`:
+### Games and simulations
 
-```json
-{
-  "apiKey": "tf_xxxxxxxxxxxxxxxxxxxx",
-  "baseUrl": "https://api.tutorflow.io",
-  "workspace": "optional-workspace-slug"
-}
-```
+`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.
 
-The API key is sent as the `Authorization: Bearer <apiKey>` header on authenticated requests.
+| 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}` |
 
-### Config schema
+`--type` takes `exact`, `rubric_short_answer` or `open_ended` (aliases `rubric`, `open-ended`). `exact` needs `--expected-answer`; `rubric_short_answer` needs `--rubric-json`.
 
-```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            |
+### Webhooks and credits (`/v1/content`)
 
-`config set` rejects unknown keys.
-
-## Commands
+| 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` |
 
-All resource commands require authentication. Without an API key they print:
-`✗ Not authenticated. Run "tutorflow auth login" first.`
+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.
 
-### `tutorflow agent`
+### Auth and config
 
-Manage the agent-facing TutorFlow Platform account flow.
+| 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` |
 
-#### `agent register`
+The config file is written with mode `0600`.
 
-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`.
+## Agent usage
 
 ```bash
-tutorflow --json agent account
-```
-
-#### `agent billing status`
+export TUTORFLOW_API_KEY=tf_content_xxx
+export TUTORFLOW_JSON=1
 
-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
+run=$(tutorflow course generate "Fractions for 5th grade" --lessons 2)
+tutorflow run wait "$(echo "$run" | jq -r .runId)" | jq -r .resource.publicUrl
 ```
 
-#### `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
-```
+To hand the work to a person, make it open by link and send them `publicUrl`: `tutorflow course share <courseId> | jq -r .publicUrl`.
 
-#### `agent verify-email resend`
+- **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`.
 
-POST `/v1/platform/agent/verify-email/resend`. Resends the workspace email
-verification message using the active API key.
+| 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`.
 
-```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.
+## Development
 
 ```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"
-}
+git clone https://github.com/tutorflow-io/cli.git && cd cli
+pnpm install
+pnpm build && pnpm test       # the e2e suites spawn dist/index.js
+pnpm dev -- course list       # run from source
+pnpm link                     # expose `tutorflow` globally
 ```
 
-Output: `id`, `status`, `sceneCount`, `previewUrl` (if returned). Prompts to open in browser.
+Try it against staging with a throwaway account:
 
 ```bash
-tutorflow video create "Intro to Newton's laws" -s 6 -r 16:9 -d 90 -l en
+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
 ```
 
-#### `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`.
+### Layout
 
-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
+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
+│   ├── sharing.ts         # shared share/visibility 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
 ```
 
-#### `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.
+## Releasing
 
-| 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                   |
+Releases are automated by GitHub Actions on pushes to `master` / `main`.
+Auth uses **npm OIDC Trusted Publishing** — no `NPM_TOKEN` secret in CI.
 
 ```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>]`.
+git checkout master
+git pull
 
-```bash
-tutorflow --json module list --limit 20 --offset 0 --search fractions
+npm version patch --no-git-tag-version  # 0.3.0 → 0.3.1 (or minor / major)
+git push origin master  # Release workflow publishes if that version is not on npm yet
 ```
 
-#### `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                 |
+The [`Release` workflow](.github/workflows/release.yml):
 
-```bash
-tutorflow --json test create "Algebra quiz" \
-  --title "Algebra Basics" \
-  --items 8 \
-  --time-limit 30 \
-  --idempotency-key test-001
-```
+1. Reads `package.json` name and version
+2. Skips npm publish if that exact version already exists
+3. Runs `pnpm typecheck` + `pnpm build` + `pnpm test`
+4. Publishes new versions with `npm publish --access public` (auth via OIDC)
+5. Creates a GitHub Release only for `v*.*.*` tag pushes
 
-#### `test list`
+For full setup (npm org, Trusted Publisher config) see [RELEASING.md](RELEASING.md).
 
-GET `/v1/platform/tests?limit=<n>&offset=<n>[&status=<s>]`.
+### Pre-release / beta
 
 ```bash
-tutorflow --json test list --limit 20 --status READY
+npm version prerelease --preid=beta --no-git-tag-version  # 0.3.1 → 0.3.2-beta.0
+git push origin master
 ```
 
-#### `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"
-}
-```
+Pre-release versions publish to a dist-tag derived from the prerelease id
+(`0.3.1-beta.0` publishes with `--tag beta`).
 
-`referenceAnswer` is omitted when `evaluationType` is `open_ended`.
-`rubric_short_answer` requires `--rubric-json`, for example:
+## ⚠️ Caveats & gotchas
 
-```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}]}'
-```
+These tripped us up during initial setup. Read before changing release infrastructure.
 
----
+### Versioning
 
-### `tutorflow auth`
+- **Don't hardcode the version in `src/index.ts`.** It reads `version` from [`package.json`](package.json) via `resolveJsonModule`. Hardcoding will silently lie to users via `--version` after every `npm version` bump.
+- The `prepublishOnly` script in `package.json` rebuilds `dist/` before publish. Don't skip it.
 
-| 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` |
+### npm Trusted Publishing (OIDC)
 
-## Exit behavior & errors
+- **npm CLI must be 11.5.1+** for OIDC auth. npm also requires a modern Node 22 runtime for trusted publishing, so the workflow uses Node 22.x and invokes `pnpm dlx npm@latest ...` for registry checks and publish. Do not replace that with the runner's bundled npm unless you verify its version supports OIDC trusted publishing.
+- The Trusted Publisher binding at [npmjs.com/package/@tutorflow/cli/access](https://www.npmjs.com/package/@tutorflow/cli/access) hardcodes:
+  - GitHub org: `tutorflow-io`
+  - Repo: `cli`
+  - Workflow filename: `release.yml`
+  - Environment: (none)
 
-- 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>`.
+  Renaming the repo, moving the workflow file, or adding an `environment:` to the publish job will break OIDC auth until the binding is updated.
+- Local manual publishes still need a token (set `NPM_TOKEN` in `.env` or run `npm login`). Use a Granular Access Token with **"Bypass two-factor authentication (2FA)"** checked, otherwise CI/scripts get `EOTP` errors.
 
-## API client
+### Provenance
 
-Internal HTTP client lives in [src/client.ts](src/client.ts):
+- `--provenance` is **disabled** in [release.yml](.github/workflows/release.yml). npm only accepts provenance attestations from **public** GitHub repos. Add `--provenance` back to the `npm publish` command when this repo goes public.
 
-```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;
-}
-```
+### Node + tooling
 
-- 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.
+- **Vitest 4.x requires Node 20+** (uses `node:util.styleText`). CI tests Node 20 and Node 22, while release publishing runs on Node 22 for npm OIDC. The runtime CLI itself still supports Node 18 (declared in `package.json#engines`).
 
-## Project layout
+### Tarball hygiene
 
-```
-.
-├── 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
-```
+- `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.
 
-## npm scripts
+### Source maps and a private repo
 
-| 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`          |
+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.
 
 ## 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.