@velven/cli 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # Changelog
 
+## Unreleased
+
+- `velven create show --timeline` draws a turn's timeline as a text waterfall: every phase, step, model and tool call
+  with its bar, start and time, the critical path marked with `*`. `--turn <id>` picks the turn (the current project's
+  newest by default), `--all` lists every tool call and screenshot (past 20 under one line they fold into one), and
+  `--json` prints the timeline. Its first line names the turn's live link, first change (the engine programmer's first
+  write that landed) and first playable preview.
+- `velven create stats`, for Velven's admins: p50 and p90 over recent turns by effort, plan mode and engine (the first
+  live link, the first change, the first playable preview, the whole turn, each phase, each job's cost and time, the single steps worth
+  comparing). `--days <n>` and `--origin <origin>` choose the turns; `--json` prints them as they come.
+- Following a turn says how long things took: a step of a second or more gets a line with its parts, each tool call's
+  line ends with its time, and the engine programmer's done line says its run's time, model steps, tool calls and images.
+- A project's first build is priced and named apart. `velven create send` says "A quick first build (its pictures are
+  made before the first preview): about 51 credits, at most 400." when the estimate says the turn is the project's
+  first build, `velven create show --timeline` calls such a turn "a quick first build", and `velven create stats` heads
+  its groups "quick first builds", "quick later builds", "quick build turns" (turns from before first builds were told
+  apart) and "quick plan turns". An older Velven's answers, without these fields, read as before.
+
+## 0.3.0
+
+- A version holds up to 512 MB and 5,000 files when you're signed in, so a game engine's web export fits. Without an
+  account it's still 50 MB and 1,000 files.
+- A file over 32 MB is sent in parts of 32 MB, each through its own upload link. A dropped upload resumes where it
+  stopped: the next `velven publish` sends only the parts Velven doesn't have yet. After a failed upload, the parts
+  already on their way are let finish before the CLI stops.
+- `velven dev` gives the page cross-origin isolation by the rule publishing uses. When the folder has a WebAssembly
+  module with shared memory (a threaded export, found in `.wasm`, `.wasm.br`, `.wasm.gz` and `.wasm.unityweb` files)
+  or `velven.json` sets `"crossOriginIsolated": true`, every response carries
+  `Document-Isolation-Policy: isolate-and-credentialless` and the start lines say so. Otherwise nothing changes.
+- `velven.json` takes `crossOriginIsolated` (`true` or `false`), sent with the publish.
+- `velven dev` serves a `.unityweb` file the way Velven does: compressed with gzip or brotli (read from its first
+  bytes), it's served with the type of the name inside and its encoding; otherwise as plain bytes. `.mem` and `.basis`
+  files are served as bytes, `.wgsl` as text.
+- Following a turn of `velven create` prints more as it happens: what each step changed, the live link while the
+  game is being built, each playtest's preview link (the first playable one, minutes before the end), its screenshots,
+  its clip and whether its checks passed (the judge's verdict follows as its own line).
+- `velven create`, for Velven's game builder: `new` starts a project, `send` sends it a message and follows the turn
+  (the estimate first, then a question in a terminal unless `--yes`; `--effort`, `--plan` and `--no-plan` are sent only
+  when given; `--detach` returns at once), `watch` follows a turn again, `cancel` stops one, and `list`, `show` and
+  `credits` read your projects and credits. The current project and last turn are saved per Velven in
+  `~/.config/velven/create.json`.
+- Following a turn reconnects from the last event it saw, and gives up only after five failed attempts in a row, so a
+  turn that waits a long time for room on Velven is followed to its end. Ctrl+C stops following; the turn goes on.
+- `--json` prints one object for `new`, `send` (the finished turn), `list`, `show` and `credits`; `watch --json` prints
+  one event per line.
+- Exit codes: refusals from the builder (not enough credits, closed, busy, too many turns, effort not available) are 4;
+  a failed or cancelled turn is 1.
+
+## 0.2.1
+
+- A `clip` in `velven.json` must be 5 to 10 seconds long. The CLI reads the length from the file's header and stops with
+  exit 2 (`invalid_media`) when it's outside that range. A file that doesn't say its length still goes through.
+- A `thumbnail` must be 4096 pixels or less on each side. The CLI reads the size from the picture's header and stops
+  with exit 2 (`invalid_media`) when it's larger.
+
 ## 0.2.0
 
 - `velven publish --prod` is usually live when the command ends: Velven reads every file of the version, and a clean

package/README.md

@@ -1,20 +1,21 @@
 # @velven/cli
 
-Publish a folder to [Velven](https://velven.ai), the community marketplace for spaces built with AI. Velven hosts the files
-and gives you a private preview link; `--prod` puts the version live on its own Velven page with the SDK added, usually
-within seconds.
+Publish a folder to [Velven](https://velven.ai), the community marketplace for spaces built with AI. Velven hosts your
+files and gives you a private preview link. `--prod` puts the version live on its own Velven page, with the SDK added,
+usually within seconds.
 
 ```sh
 npx @velven/cli login
-npx @velven/cli publish ./dist          # a private preview, link printed
-npx @velven/cli publish ./dist --prod   # live on its Velven page
+npx @velven/cli publish ./dist          # makes a private preview and prints its link
+npx @velven/cli publish ./dist --prod   # puts it live on its Velven page
 ```
 
-Or install it: `npm install -g @velven/cli`, then run `velven`. Node 20 or later. No dependencies.
+Or install it with `npm install -g @velven/cli`, then run `velven`. You need Node 20 or later. It has no dependencies.
 
 ## velven.json
 
-The listing comes from `velven.json` in the folder you publish. It stays on your machine; it is never uploaded, and neither is a `velven.json` in any folder below, whatever its case.
+Your listing comes from `velven.json` in the folder you publish. The file stays on your machine. It's never uploaded,
+and neither is a `velven.json` in any folder below, whatever its letter case.
 
 ```json
 {
@@ -26,107 +27,243 @@ The listing comes from `velven.json` in the folder you publish. It stays on your
 }
 ```
 
-Required: `title`, `type` (`game`, `world`, `tool` or `wonder`) and `devices` (`desktop`, `mobile`, `vr`). When one is
-missing, `velven publish` asks for it in a terminal and saves your answer into `velven.json`; anywhere else it stops
-and names each missing field.
+Three fields are required: `title`, `type` (`game`, `world`, `tool` or `wonder`) and `devices` (`desktop`, `mobile`,
+`vr`). If one is missing and you're in a terminal, `velven publish` asks for it and saves your answer in `velven.json`.
+Anywhere else, it stops and lists each missing field.
 
-Optional: `description`, `engine`, `ai_tools`, `models`, `how_made`, `source_url`, and for hosting:
+The optional fields are `description`, `engine`, `ai_tools`, `models`, `how_made` and `source_url`, plus these for
+hosting:
 
 | Key | What it does |
 | --- | --- |
-| `entry` | The page to open, when it is not `index.html` |
-| `spa` | `true` serves the entry page for any path without a file (client-side routing) |
-| `sdk` | `false` stops Velven adding the SDK's script tag (set it when you bundle `@velven/sdk` yourself) |
-| `start` | How to get past a start screen, so Velven can look at the space and record its clip: `{ "click": "Play" }`, `{ "click": [x, y] }` or `{ "key": "Space" }` |
-| `thumbnail` | A picture in the folder for the space's tile: JPEG, PNG or WebP, up to 2 MB |
-| `clip` | A video in the folder the tile plays on hover: MP4 or WebM, up to 3 MB (five seconds at 480p); without a `thumbnail` its first frame is the picture |
+| `entry` | The page to open, if it isn't `index.html` |
+| `spa` | Set to `true` for client-side routing: Velven serves the entry page for any path without a file |
+| `sdk` | Set to `false` to stop Velven adding the SDK's script tag, for example when you bundle `@velven/sdk` yourself |
+| `crossOriginIsolated` | Set to `true` when your page's own JavaScript needs `SharedArrayBuffer`. Velven finds a threaded WebAssembly module by itself, so a threaded export from a game engine doesn't need it |
+| `start` | How to get past your start screen, so Velven can look at the space and record its clip: `{ "click": "Play" }`, `{ "click": [x, y] }` or `{ "key": "Space" }` |
+| `thumbnail` | A picture in the folder for your space's tile. JPEG, PNG or WebP, up to 2 MB and 4096 pixels on each side |
+| `clip` | A video in the folder that your tile plays on hover. MP4 or WebM, up to 3 MB and 5 to 10 seconds long. Without a `thumbnail`, its first frame is the picture |
 | `boards`, `achievements`, `stats`, `toasts` | Leaderboards, achievements and stats, declared as in the SDK docs |
-| `space` | Written by the first publish; later publishes update that space |
-| `claim` | Written by a publish without an account; it updates the unlisted page until you claim it |
-
-`thumbnail` and `clip` must be files the publish sends (not left out by `.velvenignore`), of their kind by name and by
-their first bytes, and within their size: `velven publish` checks them before uploading anything and stops with exit 2
-(`invalid_media`) naming what is wrong. Velven then records nothing for the tile; a later version that names neither, or
-the same files, keeps what the space shows, a clip recorded again or uploaded on the Clip tab included.
-
-A `.velvenignore` file leaves files out: one pattern a line, `*`, `**` and `?`, `folder/` for folders, `#` comments.
-Dotfiles, `node_modules` and every `velven.json` are always left out, in any case, as is a name that ends in a dot or a space or holds `:` or `~` (the CLI names each such file);
-`velven dev` serves by the same rule, `.velvenignore` included, and a path only in the letter case the folder spells it, as the live version
-looks paths up (`Assets/Hero.png` does not open `assets/hero.png`). A link to a file or folder inside the folder is followed (a folder link's files go up under the
-link's name); a link outside the folder, to one of those, or back up to a folder it sits in is left out, and the CLI names each
-link it leaves out. A version holds at most 100 MB and 2,000 files.
-
-Velven never serves a program, an installer or a coin miner. Before uploading anything, `velven publish` looks at the
-first bytes of every file (a Windows, Linux or Mac program is refused whatever its name), at every name (`.exe`, `.scr`,
-`.msi`, `.dmg`, `.pkg`, `.app`, `.apk`, `.deb`, `.rpm`, `.jar`, `.bat`, `.cmd`, `.ps1`, `.vbs`; a compressed
-`setup.exe.gz` or `setup.exe.br` by the name inside) and at the text of scripts, pages and WebAssembly for a coin
-miner (a compressed file's text is left to Velven, which reads it inflated), and stops naming the file, with exit 4:
+| `space` | The first publish writes it. Later publishes update that space |
+| `claim` | A publish without an account writes it. It updates the unlisted page until you claim it |
+
+`velven publish` checks `thumbnail` and `clip` before it uploads anything. Each one must be:
+
+- a file the publish sends, so `.velvenignore` can't leave it out
+- the kind of file its name says, inside as well as in the name
+- within its size: 2 MB for a thumbnail, 3 MB for a clip
+- 4096 pixels or less on each side, for a thumbnail
+- 5 to 10 seconds long, for a clip
+
+If one isn't, the CLI stops with exit 2 (`invalid_media`) and tells you what to fix. Some files don't say how long
+they are. The CLI lets those through, and Velven measures the clip once your space is live. It uses the first 10
+seconds of a longer clip. It drops a clip under 5 seconds and records its own, unless you named a `thumbnail`.
+
+Name either one and Velven records nothing for your tile. A later version that names neither, or names the same files,
+keeps what your space shows. That includes a clip you recorded again or uploaded on the Clip tab.
+
+Your thumbnail and clip follow the same content policy as your space. They must show your space itself, not something
+unrelated or misleading.
+
+### Leaving files out
+
+A `.velvenignore` file leaves files out. Write one pattern per line. You can use `*`, `**` and `?`, `folder/` for
+folders, and `#` for comments.
+
+Some files are always left out: dotfiles, `node_modules` and every `velven.json`, in any letter case. So is a name that
+ends in a dot or a space, or contains `:` or `~`. The CLI lists each one it leaves out.
+
+The CLI follows a link to a file or folder inside the folder. A linked folder's files go up under the link's name. A
+link is left out when it points outside the folder, at a file that is always left out, or back up to a folder it sits
+in. The CLI lists each link it leaves out.
+
+`velven dev` serves files by the same rules, `.velvenignore` included. Paths must match the letter case in the folder,
+the same as on the live version, so `Assets/Hero.png` doesn't open `assets/hero.png`.
+
+A version can hold up to 512 MB and 5,000 files. A file over 32 MB is sent in parts, and a dropped upload resumes
+where it stopped: publish again and only the parts Velven doesn't have are sent.
+
+### Threaded exports
+
+A threaded export (a WebAssembly module with shared memory, such as an engine's export with threads turned on) needs
+cross-origin isolation to run. Velven reads your modules when it stores a version and gives that version isolation by
+itself. `"crossOriginIsolated": true` in `velven.json` does the same for a page whose own JavaScript needs
+`SharedArrayBuffer`.
+
+`velven dev` follows the same rule. At start it reads every `.wasm`, `.wasm.br`, `.wasm.gz` and `.wasm.unityweb` file
+the publish would send, and `velven.json`. When either asks for isolation, every response carries
+`Document-Isolation-Policy: isolate-and-credentialless` and the CLI prints "Cross-origin isolated". Otherwise it sends
+no such header, so what runs in `velven dev` runs the same once published.
+
+A `.unityweb` file is served the way Velven serves it: when its first bytes show gzip or brotli, with the type of the
+name inside (`game.wasm.unityweb` as WebAssembly) and that encoding; otherwise as plain bytes.
+
+### Programs, installers and coin miners
+
+Velven never serves a program, an installer or a coin miner. Before it uploads anything, `velven publish` checks every
+file in three ways:
+
+- It reads the start of each file. A Windows, Linux or Mac program is refused, whatever its name.
+- It checks each name: `.exe`, `.scr`, `.msi`, `.dmg`, `.pkg`, `.app`, `.apk`, `.deb`, `.rpm`, `.jar`, `.bat`,
+  `.cmd`, `.ps1`, `.vbs`. For a compressed file such as `setup.exe.gz` or `setup.exe.br`, it checks the name inside.
+- It reads the text of scripts, pages and WebAssembly for a coin miner. It leaves a compressed file's text to Velven,
+  which reads it uncompressed.
+
+If it finds one, it stops with exit 4 (`refused_file`) and names the file:
 `dist/setup.exe is a Windows program; Velven does not serve programs. Remove it or add it to .velvenignore.`
-The upload on velven.ai checks the same way. Velven reads the whole version again once it is uploaded, and refuses it
-with exit 6 when it holds one of these.
+
+The upload on velven.ai checks the same way. Velven also reads the whole version again after the upload, and refuses it
+with exit 6 if it has one of these in it.
 
 ## Commands
 
 | Command | What it does |
 | --- | --- |
-| `velven login` | Sign in: shows a code and opens velven.ai to approve it |
-| `velven logout` | Forget this computer's sign-in |
-| `velven whoami` | Who you are signed in as |
-| `velven publish [dir]` | Upload the folder (only files Velven does not already have) as a private preview; with `--prod`, live on its Velven page |
-| `velven versions` | The space's versions; `*` marks the live one |
-| `velven rollback [version]` | Put an earlier version live again (asks which when you leave it out) |
-| `velven dev [dir]` | Serve the folder on `localhost` and play it on Velven, with scores and saves going to the sandbox |
-| `velven reset` | Delete the space's sandbox data: `--scores --saves --achievements --content --rooms` (default all), `--player <handle>` |
+| `velven login` | Sign in. It shows a code and opens velven.ai so you can approve it |
+| `velven logout` | Sign this computer out |
+| `velven whoami` | Show who you're signed in as |
+| `velven publish [dir]` | Upload the folder as a private preview, sending only files Velven doesn't already have. With `--prod`, put it live on its Velven page |
+| `velven versions` | List the space's versions. `*` marks the live one |
+| `velven rollback [version]` | Put an earlier version live again. Leave out the version and it asks which one |
+| `velven dev [dir]` | Serve the folder on `localhost` and play it on Velven. Scores and saves go to the sandbox |
+| `velven reset` | Delete the space's sandbox data: `--scores --saves --achievements --content --rooms` (all of them by default), `--player <handle>` |
 
 `velven publish` options:
 
-- Without `--prod`: a private preview. The link works for 24 hours; scores and saves made there go to the sandbox.
-- `--prod`: publish it live on the space's Velven page. Most versions are live when the command ends; a refused one
-  prints the reason, naming the file, and exits 6. Sometimes a version waits on
-  Velven to publish it, usually for less than a minute, and the CLI prints a link to follow it.
-- `--wait`: wait here for the preview link, or with `--prod` until a version that waits is live. A refused version
-  prints the reason; a version Velven could not judge prints what it saw, and a start hint usually fixes it. Either way
-  you can ask for a review from the link printed, except for a program or a miner, which is never served: remove the
-  file and publish again.
-- `--title`, `--type`, `--devices desktop,mobile`, `--description`, `--engine`: override `velven.json` for this run only.
-- `--yes`: never ask for missing fields; fail naming them instead.
-- `--json`: print one JSON object, for scripts and agents (also on `whoami` and `versions`).
+- Without `--prod`, you get a private preview. The link works for 24 hours, and scores and saves made there go to the
+  sandbox.
+- `--prod` publishes the version live on the space's Velven page. Most versions are live when the command ends. A
+  refused one prints the reason, naming the file, and exits 6. Sometimes a version waits on Velven, usually for less
+  than a minute, and the CLI prints a link to follow it.
+- `--wait` waits in the terminal for the preview link. With `--prod`, it waits until a version that's waiting goes
+  live. A refused version prints the reason. A version Velven couldn't judge prints what Velven saw, and a start hint
+  usually fixes it. Either way, you can ask for a review from the printed link. The exception is a program or a miner,
+  which is never served: remove the file and publish again.
+- `--title`, `--type`, `--devices desktop,mobile`, `--description` and `--engine` override `velven.json` for this run
+  only.
+- `--yes` never asks for missing fields. It fails and lists them instead.
+- `--json` prints one JSON object, for scripts and agents. It also works on `whoami` and `versions`.
+
+`versions`, `rollback` and `reset` act on the space named in `velven.json` in the current folder. Use `--space <slug>`
+to pick another.
+
+## Making a game with velven create
 
-`versions`, `rollback` and `reset` act on the space `velven.json` in the current folder names; `--space <slug>` picks another.
+`velven create` talks to Velven's game builder: you describe a game in a sentence, and Velven's agents write it, build
+it and give you a preview link to play. It needs an account, since every turn spends credits.
+
+```sh
+velven create new "Fox Jump"
+velven create send "a one-button game where a fox jumps over logs" --effort quick
+```
+
+| Command | What it does |
+| --- | --- |
+| `velven create new [title]` | Start a project. It becomes the current project. `--engine` and `--genre` pick the packs (`phaser` and `arcade` by default) |
+| `velven create send <text>` | Send the current project a message. The CLI prints the estimate, asks before sending in a terminal, then follows the turn to its end |
+| `velven create watch [turn]` | Follow a turn, by default the last one you sent or watched. `--from <n>` starts from that event |
+| `velven create cancel [turn]` | Stop a turn. What it finished is saved, and unused credits come back |
+| `velven create list` | Your projects. `*` marks the current one |
+| `velven create show [project]` | A project, its newest turn and a fresh preview link (it works for 24 hours) |
+| `velven create show --timeline` | The newest turn's timeline as a waterfall (see below). `--turn <id>` picks another turn, `--all` lists every tool call |
+| `velven create credits` | Your credits: today's allowance, your balance, what open turns hold, and the latest entries |
+| `velven create stats` | For Velven's admins: p50 and p90 over recent turns. `--days <n>` (1 to 90, 7 by default), `--origin <origin>` |
+
+`velven create send` options:
+
+- `--effort quick|standard|deep` sets how much the turn may do. A quick turn writes and builds the game. A standard
+  turn also plays it and has its code reviewed. Deep is not available yet.
+- `--plan` turns on plan mode: the turn writes or updates the project's design document and changes no game files.
+  `--no-plan` turns it off. Plan mode is on by default for standard turns and off for quick ones.
+- Effort and plan mode stay as you last set them for the project, so the CLI sends them only when you pass them.
+- `--yes` sends without asking. Outside a terminal, the CLI never asks.
+- `--detach` sends the message and returns at once. Follow the turn later with `velven create watch`.
+- `--project <id>` sends to a project other than the current one.
+
+The CLI says what the turn does as it goes. What the agents write goes to standard output, and their progress goes to
+standard error. You see what each step changed, the live link while the game is being built, each playtest's preview
+link (the first playable one, before the turn ends), its screenshots and its clip. When the turn ends, it prints the reply, the preview link and the credits used. A turn that stops at
+its credit cap or time limit saves what it finished and ends with exit 0. A failed turn costs nothing.
+
+When Velven is busy, a turn waits for room and starts on its own. The CLI prints "Still waiting for room on Velven."
+and keeps following it, however long it waits. If the connection drops, the CLI reconnects and carries on where it
+left off. After five failed attempts in a row it stops with exit 1, and the turn goes on: `velven create watch` follows
+it again.
+
+Ctrl+C stops following the turn, but the turn goes on. The CLI prints how to watch or cancel it, and exits 1.
+
+While it follows a turn, the CLI also says how long things took: a step of a second or more gets a line with its
+parts (`  openWorkspace 10.9 s: sandbox.get 4.1 s, setup 0.1 s, describe 0.4 s`), each tool call's line ends with its
+time, and the engine programmer's last line says how its run went (`Engine programmer done in 3 min 12 s: 14 model
+steps, 28 tool calls, 6 images`).
+
+`velven create show --timeline` draws a turn's timeline once the turn has ended: every phase, step, model call, tool
+call, Sandbox call, build, upload and playtest stage, one line each under the line it belongs to, with a 60-column bar
+on the turn's clock, when it started, how long it took and the figures that matter (tokens and time to first token for
+a model call, files and bytes for an upload). `*` marks the critical path: the spans that set when the turn ended.
+The first line names the turn's live link, its first change (the engine programmer's first write that landed, the
+moment the live link shows the game instead of the template) and its first playable preview, `-` for one it never had.
+More than 20 tool calls or screenshots under one line fold into one; `--all` lists each. Without `--turn` it reads the
+newest turn of the current project, or of the project you name.
+
+`velven create stats` is for Velven's admins (anyone else is told so, with exit 4). It prints one table for each effort,
+plan mode and engine over the turns created in the last `--days` days (`--origin` keeps the turns sent from one place:
+`web`, `api`, `cli`, `mcp` or `benchmark`): how many finished and failed, p50 and p90 of the first live link, the first
+change, the first playable preview and the whole turn, each phase, each job's cost in credits and USD cents and its model time, and the
+single steps worth comparing, longest first.
+
+With `--json`, `new`, `send`, `list`, `show`, `credits` and `stats` print one JSON object, and `send` prints only the
+finished turn; `show --timeline --json` prints the turn's id and its timeline (`started_at` and the spans). `watch --json`
+is different: it prints each event of the turn as it comes, one JSON object per line.
+
+The current project and the last turn are saved in `~/.config/velven/create.json`, one set for each Velven
+`VELVEN_API` points at.
 
 ## Without an account
 
-`velven publish` works before you sign in. It makes an **unlisted page** on Velven: live as soon as Velven publishes it,
-with every SDK feature, but not listed anywhere on Velven until you claim it. The CLI prints the page's address, a claim
-token and a claim link, and saves the token in `velven.json` as `"claim"`, so publishing again from the folder updates
-the same page. When `velven.json` cannot be written (read-only, or a folder you cannot write to), the CLI says so, prints
-what to put in it (the token, or signed in the slug as `"space"`) and goes on with the publish; `--json` carries that
-sentence as `notSaved`. An unclaimed page is deleted 7 days after its first publish.
+`velven publish` works before you sign in. It makes an **unlisted page** on Velven. The page is live as soon as Velven
+publishes it and has every SDK feature, but it isn't listed anywhere on Velven until you claim it. The CLI prints the
+page's address, a claim token and a claim link. It saves the token in `velven.json` as `"claim"`, so publishing again
+from the folder updates the same page.
+
+Sometimes the CLI can't write `velven.json`, because the file is read-only or you can't write to the folder. It tells
+you, prints what to put in the file, and carries on with the publish. That's the token, or the slug as `"space"` if
+you're signed in. With `--json`, the message is in `notSaved`.
+
+An unclaimed page is deleted 7 days after its first publish.
+
+To claim it, open the claim link, or run `velven login` and publish again from the folder. The page becomes yours and
+goes on Velven, and `"space"` replaces `"claim"` in `velven.json`.
+
+Claimed it in the browser? Run `velven login` before you publish again. Otherwise:
+
+- Signed out, publishing with the claimed page's token exits 3 (`claim_spent`).
+- If it was claimed while the CLI was uploading, the version was never finished. The CLI exits 3 and tells you to run
+  `velven login` and publish again.
+- If it was claimed while the CLI was waiting with `--wait`, it exits 3 with a link to the space's Files tab, where the
+  version carries on.
 
-To claim it, open the claim link, or run `velven login` and publish again from the folder: the page becomes yours, goes
-on Velven, and `"claim"` in `velven.json` is replaced by `"space"`. Claimed it in the browser? Run `velven login`
-before publishing again: signed out, the claimed page's token exits 3 (`claim_spent`); claimed while the CLI uploads,
-the version was never finished, so it exits 3 saying to run `velven login` and publish again; claimed while it waits
-with `--wait`, it exits 3 with the space's Files tab link, where the version goes on. Without an account a version
-holds at most 50 MB and 1,000 files, and `--prod` needs you to sign in. By publishing you agree to Velven's Terms: https://velven.ai/terms
+Without an account, a version can hold up to 50 MB and 1,000 files, and `--prod` needs you to sign in. By publishing,
+you agree to Velven's Terms: https://velven.ai/terms
 
 ## In CI
 
-Set `VELVEN_TOKEN` to a token from `velven login` (in `~/.config/velven/auth.json`) and run
-`velven publish --prod --yes --wait`. The token takes precedence over a saved sign-in. Revoke tokens in your Velven settings.
+Set `VELVEN_TOKEN` to a token from `velven login` (you'll find it in `~/.config/velven/auth.json`), then run
+`velven publish --prod --yes --wait`. The token wins over a saved sign-in. You can revoke tokens in your Velven
+settings.
 
-`VELVEN_API` points the CLI at another Velven, such as `http://localhost:3000` when running Velven itself locally.
+`VELVEN_API` points the CLI at another Velven, such as `http://localhost:3000` when you run Velven itself locally.
 
 ## Exit codes
 
 | Code | Meaning |
 | --- | --- |
 | 0 | Done |
-| 1 | Failed: the network, a server error, a failed upload, or cancelled |
-| 2 | A mistake in the command or in `velven.json`, such as a missing field, or a `thumbnail` or `clip` that is not right (`invalid_media`) |
-| 3 | Not signed in (or the token was refused) for something that needs an account, such as `--prod` |
-| 4 | Refused by Velven: not your space, too large, too many files, a program, installer or coin miner in the folder (`refused_file`, before anything is uploaded), not found |
+| 1 | Failed: the network, a server error, a failed upload, or you cancelled. For `velven create`: a turn that failed or was cancelled, or that you stopped following |
+| 2 | A mistake in the command or in `velven.json`, such as a missing field, or a `thumbnail` or `clip` that breaks one of the rules above (`invalid_media`) |
+| 3 | You're not signed in, or your token was refused, for something that needs an account, such as `--prod` |
+| 4 | Refused by Velven: not your space, too large, too many files, a program, installer or coin miner in the folder (`refused_file`, before anything is uploaded), or not found. For `velven create`: not enough credits, the builder is closed, a turn is already running or you have too many open, or the effort is not available |
 | 5 | Rate limited: try again later |
-| 6 | Not published: Velven refused the version, or with `--wait`, could not judge it |
+| 6 | Not published: Velven refused the version, or with `--wait`, couldn't judge it |
 
 Docs: https://velven.ai/docs