@velven/cli 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,6 +1,135 @@
 # Changelog
 
-## Unreleased
+## 0.5.0
+
+Needs the Velven of the same release, which speaks only this version: update to 0.5.0. 0.3.0 and 0.4.0 can no longer
+send a message (every send now carries an id), and no earlier version can publish without an account (each sends the
+claim token in the finish's body too, which Velven now refuses: it takes the token only in the `x-velven-claim`
+header). Publishing with an account is unchanged.
+
+- A message sent while a turn runs joins that turn when the turn is writing code: "Sent to the running turn
+  (<turn>).", then the CLI follows the project until the turn ends, prints "Taken into account." once the running
+  agent has read it, the turn's reply (which says what it did with your words) and how the turn ended (exit 0 when it
+  ended done, 1 otherwise). `--detach` prints the watch command instead. A turn takes up to five such messages, within
+  its own credits and time; a message with a picture, an answer, `--effort`, a plan flag or `--build` never joins a
+  turn, so it waits and keeps them.
+- Otherwise it waits, and the CLI says why: "Queued: the turn is not writing code now, so it runs after the turn.",
+  "the turn is finishing, so it runs next", "five messages already joined this turn", or "it runs after the turn that
+  is running" for `--queue` (always wait), a picture, an answer, `--effort`, a plan flag or `--build`. A message that joined too late to be read is queued
+  the same way ("Could not be taken this turn; queued as the next message.", or, when the project's queue is paused,
+  "queued, but the queue is paused ... Start it: velven create resume").
+- `send` makes an id for each message and, when the send gets no answer (a dropped connection, or an error on Velven's
+  side other than a turn that could not start), sends it once more with the same id: Velven answers what it did with
+  the first, nothing is started or held twice, and the line starts with "(already sent)". The estimate and the message
+  no longer carry `queue`.
+- `--answer <n>` answers Velven's open question with its choice n: the chip's words, or yours when you give some. The CLI
+  keeps the last question it printed, following a turn or a project, in its state file, and forgets it once any
+  message is sent to the project or a stream shows it answered or superseded; with none for the project it stops
+  with exit 2. A question now says `Answer: velven create send --answer 1 (a choice's number), or in your own
+  words.`
+- A failed or stopped turn pauses the messages waiting on its project. `velven create resume` starts them again ("Resumed:
+  2 waiting. The first starts now: velven create watch <turn>", or "Nothing was paused."); `velven create queue` starts
+  with "Paused after a failed turn" (or "a stopped turn") and marks a message sent while a turn ran; `velven create
+  cancel` says when it paused messages, and says a running turn stopped at once (its run was gone) is stopped with
+  the credits it used, never that its credits are back. A send while the queue is paused and a turn runs says so.
+- `velven create queue edit <id> <text>` changes a waiting message (`--build` sends it as Build it), and `velven create
+  queue move <id> <place>` moves one in line (it sends the whole order, and reads the queue again once when it changed
+  meanwhile), paused or not.
+- `velven create versions` lists the project's versions newest first (each turn that saved the game, then 0, the
+  template), marking `head`, `rolled back` and `preview`. `velven create restore <version>` goes back or forward to one,
+  instantly and for no credits: "Went back to version 2 (commit 2222222).", "Already on version 2.", and "Its preview
+  expired; Velven is rebuilding it (no credits)." when it is. An unknown version, a restore while a turn runs and a
+  version whose files are gone exit 4.
+- `velven create watch <project>` follows a project's whole chat: its newest turns under their headers, then each
+  message, question, plan, design, run, tool call, picture, build, playtest, review, commit (once saved, or "Not saved"
+  when its turn failed before the history held it), preview and restore as it lands, each turn's phase and end, the queue and its pause, the newest failure, and "Up to date." once caught up. It
+  reconnects from its place; Ctrl+C ends it with exit 0; `--until-idle` ends it once nothing runs and no message waits to start; `--from <n>` reads
+  what came after event n; `--json` prints each event on its line. `watch <turn>` is as before.
+- `velven create show` says what the project is doing: "Running: coding (turn 4)", "A preview of version 2 is being
+  rebuilt.", a paused queue, and the newest turn's failure with "Try again." when sending it again may work; "Latest
+  commit" names its version. `show --json` carries the project's `summary`.
+- A failed turn's class decides what the CLI suggests: following it prints "Try again: velven create send ... with the
+  same words." when sending it again may work, and `--json` answers carry `failure: { class, retryable }`.
+- Pictures, screenshots and clips are printed as stable Velven links (`/api/v1/create/media/<id>`) that do not expire:
+  they open in the browser you approved the CLI from, signed in (signed out, Velven asks you to sign in first),
+  instead of signed links that lasted 15 minutes. `--json` output carries each picture, screenshot, clip and frame by
+  its media id (`media`, `frame`) only: the events and `show --json` no longer carry `url`, `frame_url`, `clip_url` or
+  `expires_at` for them.
+- `velven create refs` reads how many messages carried each picture from every answer ("sent" for an answer without
+  the count is gone).
+- While a turn runs on the project, `send` prints no estimate: the message joins the turn or waits, holding nothing.
+  A waiting message that was taken out of the queue, or refused as it came to start, prints "Taken out of the queue;
+  it will not run." (a send again of it says the same). A later small change's step is "Making the change".
+- `watch <project>` prints a tool call once it has its note or has ended, a finished run's end after its tool calls and
+  pictures in a chat it reloads, "Build it: ..." only under a plan that ends its turn (never one a Build it turn drafts
+  and builds), and a restore to a later version as "Went forward to version N". `show` prints "Next turn: ..." only
+  after a turn sent with `--effort` or a plan flag.
+
+## 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
@@ -17,9 +146,6 @@
   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

package/README.md

@@ -153,37 +153,118 @@ to pick another.
 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
+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. `--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 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 (none while a turn runs on the project: the message joins it or waits, holding nothing), 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), `--answer <n>` answers Velven's question with its choice n. Sent while a turn runs on the project, the message joins that turn when the turn is writing code, else waits and runs when it ends; `--queue` always waits, as does a message with `--effort`, a plan flag, `--build`, `--ref` or `--answer` |
+| `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 on the project, in the order they run, whether the queue is paused, and any Velven could not start with why. `--project <id>` picks another project |
+| `velven create queue edit <id> <text>` | Change a waiting message's words (`--build` sends it as Build it), paused or not |
+| `velven create queue move <id> <place>` | Move a waiting message to a place in line (1 runs next), paused or not |
+| `velven create queue rm <id>` | Remove a waiting message before it runs |
+| `velven create resume` | Start the waiting messages again after a failed or stopped turn paused them: the first starts at once when no turn 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 watch <project>` | Follow a project's whole chat: its turns, messages, questions, pictures, previews, queue and versions, as they come. `--from <n>` reads only what came after that event, `--until-idle` ends once nothing runs on the project and no message waits to start |
+| `velven create cancel [turn]` | Stop a turn. What it finished is saved, unused credits come back, and the messages waiting on the project pause until you resume them |
+| `velven create versions` | The project's versions, newest first: each turn that saved the game, then 0, the template. Marks the one the project is on (`head`), the ones a restore left (`rolled back`) and those with a ready preview |
+| `velven create restore <version>` | Go back, or forward, to a version: instant and free (no turn, no credits). When its preview has expired, Velven rebuilds it in the background, also for no credits |
 | `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 [project]` | A project, what it is doing (the running turn's phase, a preview being rebuilt, a paused queue, the newest turn's failure), its newest turn, the version it is on and a fresh preview link (it works for 24 hours); after a turn you sent with `--effort` or a plan flag, the effort and plan mode the next such send keeps |
 | `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:
 
-- `--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.
+- 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: `--answer <n>` sends choice n (its words, or yours when you give some:
+  `velven create send --answer 2 "painted, but darker"`), or send your own words, or `--build "Just build it"`; the
+  style question also takes a picture with `--ref <file>`. The CLI keeps the last question it printed (following a
+  turn or a project) in its state file, so `--answer` needs no id, and forgets it once you send the project any
+  message or a stream shows it answered or superseded; with no question kept for the project it stops with exit 2. 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 joins that turn when the turn is writing code: the CLI prints "Sent
+  to the running turn (<turn>).", then follows the project until the turn ends, printing "Taken into account." once
+  the running agent has read it (from its next step; it keeps to the turn's credits and time), the turn's reply, and
+  how the turn ended (exit 0 when it ended done, 1 otherwise). The reply says what it did with your words. A turn
+  takes up to five such messages, and a message with a picture, an answer, `--effort`, a plan flag or `--build` never
+  joins a turn: those are a turn's own, so it waits and keeps them.
+- Otherwise the message waits behind the turn (at most five a project), holding no credits, and starts on its own when
+  that turn ends; the CLI says why it did not join and exits 0: "Queued: the turn is not writing code now, so it runs
+  after the turn." (it is planning, building, playtesting, saving), "the turn is finishing, so it runs next" (it is
+  past its time or wrapping up), "five messages already joined this turn", or "it runs after the turn that is running"
+  for `--queue`, a picture, an answer, `--effort`, a plan flag or `--build`. A message that joined a turn too late to be read is queued the same way, and
+  following it prints "Could not be taken this turn; queued as the next message." A waiting message you take out of
+  the queue (or that is refused as it comes to start) shows "Taken out of the queue; it will not run." 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.
+- A turn that fails or that you stop pauses the messages waiting on its project: they stay in line and nothing starts
+  until you run `velven create resume` (the first starts at once when no turn runs; "Resumed: 2 waiting. The first
+  starts now: velven create watch <turn>"). A message you send while the queue is paused and no turn runs starts at
+  once; one sent while a turn runs joins the paused line ("Queued, but the queue is paused...", a message the running
+turn could not take included: "Could not be taken this turn; queued, but the queue is paused..."). `velven create queue`
+  starts with "Paused after a failed turn" (or "a stopped turn"), `queue edit` and `queue move` change the line paused
+  or not, and removing the last waiting message clears the pause. `velven create cancel` says when it paused messages.
+- Each send carries an id the CLI makes for it. When the send gets no answer (the connection dropped, or Velven
+  answered with an error on its side), the CLI sends it once more with the same id, and Velven answers what it did
+  with the first: nothing is started or held twice, and the CLI prints "(already sent)" before its line.
 
 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.
+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"; a later small change says "Making the change" for its work), 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.
+
+Links to pictures, screenshots and clips are stable Velven links (`https://velven.ai/api/v1/create/media/<id>`) that
+do not expire: open one in the browser you approved the CLI from, where you are signed in (signed out, Velven asks you
+to sign in first, then shows it). A preview link carries its own 24-hour view token, as before.
+
+A turn that fails says why in a sentence, and its class says what to do: a turn that failed for Velven's capacity, the
+model service, the workspace or something unexpected on Velven's side may work when you send the message again (the
+CLI prints `Try again`); one refused for credits or because its build was refused needs a change first. A failed turn
+costs nothing. `--json` answers carry the class as `failure: { class, retryable }` (classes `credits`, `capacity`,
+`model`, `sandbox`, `build`, `unknown`).
 
 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
@@ -192,6 +273,24 @@ 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.
 
+`velven create watch <project>` (any id that is not a turn number) follows the project's chat instead of one turn:
+the newest turns so far, each under its header ("Turn 3 (done, version 2)"), then every change as it comes, saying
+each thing once. A person's message prints as `> words` with what happened to it while a turn ran; Velven's replies,
+questions with their choices, plans, designs, pictures with their links, commits, previews, playtests, reviews and
+restores ("Went back to version 1") print as they land; the engine's runs, tool calls, changed files and builds go
+to standard error. It also says each turn's phase and end, how many messages wait and whether the queue is paused, the
+newest failure, and "Up to date." once it has caught up. It reconnects from where it left off. Ctrl+C stops watching
+with exit 0: nothing is lost, `watch` again picks up the project as it is. `--until-idle` ends once it has caught up
+and no turn runs, no preview is being rebuilt and no message waits to start (one waiting on a paused queue starts only
+on `velven create resume`, so it does not count).
+
+`velven create versions` lists the project's versions, and `velven create restore <version>` goes to one: "Went back
+to version 2 (commit 2222222).", or "Went forward to …" for a later one. It is instant and costs nothing; the turns after it are marked rolled back and stay
+listed, and restoring one of them goes forward again. The next message builds on the version you went to. A restore
+waits for a running turn to end (exit 4 while one runs), and an expired preview is rebuilt in the background ("Its
+preview expired; Velven is rebuilding it (no credits)."); a message you send meanwhile stops the rebuild and makes its
+own preview.
+
 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
@@ -207,17 +306,18 @@ More than 20 tool calls or screenshots under one line fold into one; `--all` lis
 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:
+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.
+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`, `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.
+With `--json`, `new`, `send`, `list`, `show`, `plan`, `queue`, `refs`, `versions`, `restore`, `resume`, `credits`, `usage` and `stats` print one JSON object, and `send` prints only the
+finished turn (or the waiting message and why, `queued` and `why`; or for a message that joined a turn, the message, `steer` and the turn as it ended), with `again: true` when Velven had the send already; `show --json` carries the project's `summary`, `show --timeline --json` the turn's id and its timeline (`started_at` and the spans). `watch --json`
+is different: it prints each event of the turn, or of the project, 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.
+The current project, the last turn and the last question are saved in `~/.config/velven/create.json`, one set for
+each Velven `VELVEN_API` points at.
 
 ## Without an account
 
@@ -262,7 +362,7 @@ settings.
 | 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 |
+| 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, too many turns open or messages waiting, a restore while a turn runs, an unknown version, or the effort is not available |
 | 5 | Rate limited: try again later |
 | 6 | Not published: Velven refused the version, or with `--wait`, couldn't judge it |