@velven/cli 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,114 @@
 # Changelog
 
+## 0.4.0
+
+- `velven create send` lets Velven pick how much to do when you pass neither `--effort` nor `--plan`/`--no-plan`:
+  a quick change, a full build it playtests and fixes, or a plan when you ask for one. Its line before sending reads "Velven picks how much to do: about 20 credits for a small change, at most
+  1500 held. You have 3200 available.", or on a project that never built "about 51 credits for a first build (its
+  pictures are made before the first preview)". With `--effort` or a plan flag the turn is as before; a later
+  message with neither flag is Velven's pick again (the help no longer says the flags are kept for every message).
+- `--build` sends the message as Build it: no more questions, Velven fills in what the plan leaves open. Words beyond
+  a bare build (`--build "make it 2D"`) change the plan first, then it is built; `--build "Build it"` builds the plan as
+  it is, at once.
+- `--ref <file>` (up to 4) uploads a reference picture (up to 10 MB) to the project and attaches it to the message:
+  the picture goes straight to Velven's storage through a link, then Velven keeps it. `--ref ref-3` sends a picture
+  the project already keeps, with no upload. A refused picture stops the CLI with Velven's sentence and exit 4, before
+  anything is sent; one over 10 MB is refused before it is uploaded.
+- Following a turn Velven routes says "Started: Velven is choosing the work", then what it chose in words, with the
+  work and the reason on standard error. A question prints with its numbered choices and the commands that answer it.
+- `velven create refs` lists the project's reference pictures (id, when added, size, how many messages carried each),
+  and `velven create refs rm <ref-n>` deletes one. A send whose picture finds the project's 16 full names both.
+- A question Velven asks is printed once, with its choices: the turn's reply, the same question, is no longer printed
+  again at the end. `velven create watch <turn>` names the turn's own project in how to answer it, not the current one.
+- A picture refused because the project has given out all 999 picture numbers stops with its own sentence and
+  `reference_numbers_used`, without the hint about removing a picture.
+- `velven create stats` heads a routed group with its work ("quick fast first builds", "standard full later builds",
+  "quick interview turns", "quick routed plan turns"), and `velven create show --timeline` names a routed turn's work
+  and first build from its router step.
+- `velven create new` without `--genre` makes an open game: Velven follows your idea instead of arcade's rules
+  (`--genre arcade` holds a project to them). Without `--engine`, Velven picks 2D (`phaser`) or 3D (`three`) from your
+  idea, 3D unless it is clearly 2D. A project made with `--engine` keeps its engine.
+- A new game starts with a short conversation: Velven asks a question or two (2D or 3D, the style, at most four in
+  all), each with numbered choices and `Just build it: velven create send --build "Just build it"` (the style question
+  also offers `--ref <file>`), then sketches a short plan, printed as a card with `Build it: velven create send --build
+  "Build it"`. `velven create plan` prints the project's plan again (`--json` too).
+- Following a build prints its plain steps ("Designing your game", "Painting the art", "Building the world", "Trying it
+  out", "Polishing", "Finishing up"), a first build's design once it is settled ("Designing <title>: <pitch>" with its
+  style and palette), and each picture as it lands ("Painted sky (1024 by 512)" and a link to it). The plan and the
+  brief as they are written are printed only with `watch --json`.
+- A message sent while a turn runs on the project waits behind it instead of being refused (the CLI asks for that:
+  `queue=true` on the estimate, `queue: true` on the message; Velven still refuses a send that does not ask, as it
+  refused 0.3.0's): "Queued: it runs after the turn that is running. velven create queue lists what waits." (exit 0;
+  `--json` prints `{ ok, queued }`). It starts when that turn ends, and following that turn prints "Your next message
+  is running: velven create watch <turn>". `velven create queue` lists the waiting messages (and any Velven could not
+  start, with why); `velven create queue rm <id>` removes one.
+- `velven create stats` heads a new game's plan turns "quick draft turns", and `velven create show --timeline` names a
+  draft or interview turn from its interviewer step.
+- After a turn that ends with a playable game, following it prints "Where it could go next:" with two to four short
+  suggestions Velven wrote for this game, and the command that sends the first one; send any of them as an ordinary
+  message.
+- `velven create usage` lists what each of your turns held and used, newest first (`--project <id>` for one project,
+  `--before <turn>` for the page before, `--json`).
+- When Velven kept a turn quick because the day's credits would not cover more, its route line says so in words. A
+  reply may end "You're running low on credits for today." and, after a question, the CLI now prints what follows the
+  question in the reply.
+- `velven create stats` adds a line under each group saying how the next message reacted to its turns (moved on,
+  corrected it, asked for checks), when any was labelled.
+- On a project that never built, a message without `--build` is priced as what Velven answers it with first: "about 2
+  credits for a question or a short plan"; with `--build`, as a first build.
+- A message sent while a turn runs that starts at once (the turn ended as it was queued) is followed as a turn ("Turn
+  <id> is on its way.", or "Turn <id> waits for room on Velven and starts on its own." when Velven's daily room holds
+  it back); one Velven refused when it came to start prints why and exits 4, instead of "Queued".
+- "Your next message is running" names the project ("on project <id>") when the message that started waited on
+  another of your projects.
+- When a new game's first build stops before it made the game (nothing saved, or only its design), the CLI prints
+  `Try again: velven create send --build "Build it"` under the reply.
+
+## 0.3.0
+
+- `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.
+- 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

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,23 +27,25 @@ 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" }` |
+| `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 |
+| `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:
 
@@ -62,84 +65,249 @@ keeps what your space shows. That includes a clip you recorded again or uploaded
 Your thumbnail and clip follow the same content policy as your space. They must show your space itself, not something
 unrelated or misleading.
 
-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:
+### 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.
 
-`versions`, `rollback` and `reset` act on the space `velven.json` in the current folder names; `--space <slug>` picks another.
+## Making a game with velven create
+
+`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 "Petal Drift"
+velven create send "a cozy game where you grow a garden on a floating island"
+```
+
+| Command | What it does |
+| --- | --- |
+| `velven create new [title]` | Start a project. It becomes the current project. Without `--genre` it is an open game: Velven follows your idea (`--genre arcade` holds it to arcade's rules). Without `--engine`, Velven picks 2D (`phaser`) or 3D (`three`) from your idea: 3D unless it is clearly 2D |
+| `velven create send <text>` | Send the current project a message. Velven picks how much to do unless you pass `--effort` or a plan flag. The CLI prints the estimate, asks before sending in a terminal, then follows the turn to its end. `--build` builds now, `--ref <file>` attaches a picture (`--ref ref-3` one the project keeps). Sent while a turn runs on the project, the message waits and runs when that turn ends (followed at once when that turn ended as it was sent; exit 4 with why when Velven refused it) |
+| `velven create plan` | A new game's short plan: what the game is, how it plays, its look, what is in it, how it ends. `--project <id>` picks another project |
+| `velven create queue` | The messages waiting behind the running turn, in the order they run, and any Velven could not start with why. `--project <id>` picks another project |
+| `velven create queue rm <id>` | Remove a waiting message before it runs |
+| `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 refs` | The project's reference pictures: each id, when it was added, its size and how many messages carried it. `--project <id>` picks another project |
+| `velven create refs rm <ref-n>` | Delete a reference picture, sent or not. The messages that carried it keep its number, and the number is never given to another picture |
+| `velven create credits` | Your credits: today's allowance, your balance, what open turns hold, and the latest entries |
+| `velven create usage` | What each of your turns held and used, newest first. `--project <id>` keeps one project's, `--before <turn>` reads the page before (the last line names it), `--json` prints the page |
+| `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:
+
+- Without `--effort`, `--plan` or `--no-plan`, Velven picks the turn's work from your message: a quick change, a full
+  build that it also playtests and fixes, or a plan. The CLI prints "Velven picks how much to do: about 20 credits
+  for a small change, at most 1500 held." first (on a project that never built, the figure is a first build's, and
+  the line says so); what is not spent comes back when the turn ends. Effort and plan mode then stay as the project
+  had them.
+- A new game starts with a short conversation: Velven asks what matters most and is still open (2D or 3D, the style,
+  at most four questions in all, fewer for a specific idea), then sketches a short plan. A question comes with
+  numbered choices and how to answer it: send a choice, your own words, or `--build "Just build it"`; the style
+  question also takes a picture with `--ref <file>`. The line names the turn's own project, also when you follow it
+  with `velven create watch` from another. The plan prints as a card (the title, the pitch, 2D or 3D and the camera,
+  how it plays, the look and palette, what is in it, how it ends, a score or not); send a change in words to reshape
+  it, or `--build "Build it"` to build it. `velven create plan` prints it again.
+- `--build` builds now: no more questions, and Velven fills in what the plan leaves open (writing the plan first when
+  there is none). Words beyond a bare build change the plan first (`--build "make it 2D"`: the plan is written again
+  in 2D, then built); `--build "Build it"` builds the plan as it is. Velven still picks how much to do.
+- `--ref <file>` attaches a reference picture (PNG, JPEG or WebP, up to 10 MB, up to 4 on a message): the CLI uploads
+  each to the project first (straight to Velven's storage through a link Velven gives, then Velven keeps it), then
+  sends the message with them. `--ref ref-3` sends a picture the project already keeps, by the id Velven printed when
+  it was attached, with no upload. Velven's agents read a picture's style, a character or a game's screen from it. A
+  picture Velven refuses, or one over 10 MB, stops the CLI with its sentence and exit 4, before the message is sent.
+  A project keeps up to 16 pictures. One no message carried goes a day after it was last uploaded; a sent one stays
+  until you delete it. When a project is full, the CLI says so and names `velven create refs` and
+  `velven create refs rm <ref-n>`. A project that has given out all 999 picture numbers takes no new one (exit 4,
+  `reference_numbers_used`): start a new project.
+- `--effort quick|standard|deep` sets how much the turn may do, in place of Velven's pick. 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, in place of Velven's pick: the turn writes or updates the project's design document and
+  changes no game files. `--no-plan` turns it off.
+- The project keeps the effort and plan mode you last passed, for a later message that passes only one of them (with
+  `--effort` alone, a new standard or deep effort turns plan mode on, quick turns it off). A message with neither is
+  Velven's pick again, whatever you passed before; 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.
+- A message sent while a turn runs on the project waits behind it (at most five a project), holding no credits, and
+  starts on its own when that turn ends: the CLI prints "Queued: it runs after the turn that is running." and exits 0.
+  `velven create queue` lists what waits, `velven create queue rm <id>` removes one; cancelling the running turn
+  leaves the queue as it is. Following the turn that ends prints "Your next message is running: velven create watch
+  <turn>" (with "on project <id>" when the message that started waited on another of your projects; one waiting on
+  the same project starts first). A queued message that starts at once but waits for room on Velven says "Turn <id>
+  waits for room on Velven and starts on its own.", as any such send.
+
+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. When Velven picked the work, it says so in words first ("I'll make the change."; when the day's
+credits kept it from a fuller turn, "I'll make the change. I kept this one quick to save credits."), with the work it
+picked and why on standard error. On a build it prints the plain step it is at ("Designing your game", "Painting the art", "Building the world", "Trying it out", "Polishing", "Finishing up"), and on a first build the design as it is settled ("Designing Petal Drift: ..." with its style and palette) and each picture once it lands ("Painted sky (1024 by 512)" with a link to look at it). 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 (when the turn asked a question, which it already printed with its choices, only what follows it), then, after a turn that ended with a playable game, "Where it could go next:" with two to four short suggestions for this game and the command that sends the first (`velven create send "Add a boss at the end"`; each is an ordinary message), then the preview link and the credits used. A reply may end with one sentence on what the turn took from your pictures, and with "You're running low on credits for today." when what is left would not cover another small change. 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 a new game's
+first build stops before it made the game (it saved nothing, or only its design), the reply ends "Press Build it to try
+again." and the CLI prints `Try again: velven create send --build "Build it"`; "try again" typed after it builds too.
+
+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, engine and, for the turns Velven routed, the work it picked ("quick fast first builds", "standard full later
+builds", "quick interview turns", "quick draft turns" for a new game's short plan) 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. Under a group's heading, "the next message:" says how the message after its turns reacted to them, as Velven's router labelled it (moved on, corrected it, asked for checks), when any was labelled.
+
+With `--json`, `new`, `send`, `list`, `show`, `plan`, `queue`, `credits`, `usage` and `stats` print one JSON object, and `send` prints only the
+finished turn (or the waiting message, `queued`, when it was queued); `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 plan and the brief as they are written included, which text mode leaves out until the last).
+
+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 |
+| 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 | 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 |
+| 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