@velven/cli 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,6 +1,70 @@
 # Changelog
 
-## Unreleased
+## 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 +81,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,80 @@ 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, 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:
 
-- `--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: 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. 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"), 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
@@ -207,14 +250,15 @@ 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`, `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.

package/dist/velven.js

@@ -23,7 +23,7 @@ class CliError extends Error {
   }
 }
 // package.json
-var version = "0.3.0";
+var version = "0.4.0";
 
 // src/version.ts
 var VERSION = version;
@@ -76,16 +76,28 @@ function causeOf(e) {
   return e instanceof Error && e.cause instanceof Error ? e.cause.message : e instanceof Error ? e.message : String(e);
 }
 async function call(api, method, path, body) {
+  return answerOf(api, path, body === undefined ? undefined : { type: "application/json", data: JSON.stringify(body) }, method);
+}
+async function putBytes(url, bytes, type, tooLarge) {
+  let response;
+  try {
+    response = await fetch(url, { method: "PUT", headers: { "content-type": type, "user-agent": USER_AGENT }, body: bytes });
+  } catch (e) {
+    throw new CliError(`Could not upload the picture (${causeOf(e)}).`, EXIT.failed, "network");
+  }
+  await response.text().catch(() => "");
+  if (response.status === 413)
+    throw new CliError(tooLarge, EXIT.refused, "too_large");
+  if (!response.ok)
+    throw new CliError(`The picture's upload was refused (HTTP ${response.status}). Try again in a moment.`, response.status >= 500 ? EXIT.failed : EXIT.refused, `http_${response.status}`);
+}
+async function answerOf(api, path, body, method) {
   const headers = requestHeaders(api, "application/json");
   if (body !== undefined)
-    headers["content-type"] = "application/json";
+    headers["content-type"] = body.type;
   let response;
   try {
-    response = await fetch(`${api.base}${path}`, {
-      method,
-      headers,
-      body: body === undefined ? undefined : JSON.stringify(body)
-    });
+    response = await fetch(`${api.base}${path}`, { method, headers, body: body?.data });
   } catch (e) {
     throw new CliError(`Could not reach Velven at ${api.base} (${causeOf(e)}).`, EXIT.failed, "network");
   }
@@ -408,7 +420,11 @@ function parseArgs(argv, spec) {
     if (value === undefined || eq === -1 && value.startsWith("--")) {
       throw new CliError(`--${name} needs a value.`, EXIT.usage, "usage");
     }
-    flags[name] = value;
+    if (kind === "strings") {
+      const given = flags[name];
+      flags[name] = [...Array.isArray(given) ? given : [], value];
+    } else
+      flags[name] = value;
   }
   return { positionals, flags };
 }
@@ -416,6 +432,10 @@ function stringFlag(parsed, name) {
   const value = parsed.flags[name];
   return typeof value === "string" ? value : undefined;
 }
+function stringsFlag(parsed, name) {
+  const value = parsed.flags[name];
+  return Array.isArray(value) ? value : typeof value === "string" ? [value] : [];
+}
 
 // src/context.ts
 import { spawn } from "node:child_process";
@@ -467,6 +487,10 @@ function nodeContext() {
   };
 }
 
+// src/create.ts
+import { readFile as readFile3 } from "node:fs/promises";
+import { resolve } from "node:path";
+
 // src/create-state.ts
 import { chmod as chmod2, mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
 import { dirname as dirname2, join as join2 } from "node:path";
@@ -512,7 +536,7 @@ var BAR_WIDTH = 60;
 var FOLD_OVER = 20;
 var LABEL_MAX = 44;
 var CHAIN_SLACK_MS = 50;
-var PHASE_ORDER = ["workspace", "planning", "coding", "building", "playtesting", "reviewing", "fixing", "saving", "previewing", "replying", "settle"];
+var PHASE_ORDER = ["routing", "workspace", "planning", "coding", "building", "playtesting", "reviewing", "fixing", "saving", "previewing", "replying", "settle"];
 var plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
 function seconds(ms) {
   return `${(ms / 1000).toFixed(1)} s`;
@@ -569,7 +593,11 @@ function spanFacts(span) {
     fps_median: (v) => `${v} fps`,
     memory_mb: (v) => `${v} MB memory`,
     clocks: (v) => Number(v) > 1 ? "across two clocks" : null,
-    reasoning: (v) => Number(v) > 0 ? `reasoning ${count(Number(v))}` : null
+    reasoning: (v) => Number(v) > 0 ? `reasoning ${count(Number(v))}` : null,
+    route: (v) => `routed ${v}`,
+    route_by: (v) => v === "fallback" ? "the router did not answer" : null,
+    downgraded: (v) => v === true ? "full was over the hold" : null,
+    route_reason: (v) => `"${v}"`
   };
   if (span.kind === "model") {
     const input = (num(a.input) ?? 0) + (num(a.cached) ?? 0);
@@ -707,7 +735,7 @@ function bar(row, total) {
   return `|${" ".repeat(a)}${"#".repeat(b - a)}${" ".repeat(BAR_WIDTH - b)}|`;
 }
 function renderTimeline(turn, spans, options = {}) {
-  const kind = `${turn.effort} ${turn.plan ? "plan turn" : isFirstBuild(spans) ? "first build" : "build turn"}`;
+  const kind = turnKind(turn, spans);
   if (spans.length === 0) {
     const why = turn.status === "queued" || turn.status === "running" ? " A turn's timeline is written when it ends." : "";
     return [`Turn ${turn.id}, a ${kind}, ${turn.status}: no timeline.${why}`];
@@ -768,7 +796,23 @@ function renderTimeline(turn, spans, options = {}) {
   return lines;
 }
 function isFirstBuild(spans) {
-  return spans.some((s) => s.name === "beginTurn" && s.attrs?.first_build === true);
+  return spans.some((s) => (s.name === "beginTurn" || s.name === "askRouter") && s.attrs?.first_build === true);
+}
+function workOf(spans) {
+  const interview = spans.find((s) => s.name === "askInterviewer" && typeof s.attrs?.interview === "string")?.attrs?.interview;
+  if (interview === "ask")
+    return "interview";
+  if (interview === "draft")
+    return "draft";
+  const route = spans.find((s) => s.name === "askRouter" && typeof s.attrs?.route === "string")?.attrs?.route;
+  return typeof route === "string" ? route : null;
+}
+function turnKind(turn, spans) {
+  const work = workOf(spans);
+  if (work === "interview" || work === "draft")
+    return `${turn.effort} ${work} turn`;
+  const what = turn.plan ? "plan turn" : isFirstBuild(spans) ? "first build" : "build turn";
+  return `${turn.effort} ${work === "fast" || work === "full" ? `${work} ` : ""}${what}`;
 }
 function firsts(timing) {
   if (!timing || timing.first_dev_ms === undefined && timing.first_write_ms === undefined && timing.first_preview_ms === undefined)
@@ -824,8 +868,11 @@ function table(rows, indent) {
 var sec = (ms) => ms === null ? "-" : seconds(ms);
 var pair = (p, f) => `${f(p.p50)} / ${f(p.p90)}`;
 function groupTitle(g) {
+  if (g.work === "interview" || g.work === "draft")
+    return `${g.effort} ${g.work} turns, ${g.engine}`;
   const what = g.plan ? "plan turns" : g.first_build === true ? "first builds" : g.first_build === false ? "later builds" : "build turns";
-  return `${g.effort} ${what}, ${g.engine}`;
+  const work = g.work === "plan" ? "routed " : g.work ? `${g.work} ` : "";
+  return `${g.effort} ${work}${what}, ${g.engine}`;
 }
 function renderStats(groups, options) {
   const over = `the last ${plural(options.days, "day")}${options.origin ? `, from ${options.origin}` : ""}`;
@@ -837,6 +884,9 @@ function renderStats(groups, options) {
   const lines = [`Turns created in ${over}: p50 and p90 over the done turns.`];
   for (const g of groups) {
     lines.push("", `${groupTitle(g)}: ${plural(g.turns, "done turn")}, ${g.failed} failed`);
+    const reacted = REACTION_WORDS.filter(([key]) => (g.reactions?.[key] ?? 0) > 0).map(([key, words]) => `${words} ${g.reactions[key]}`);
+    if (reacted.length)
+      lines.push(`  the next message: ${reacted.join(", ")}`);
     const figures = [
       ["figure", "p50", "p90", "turns"],
       ["first live link", sec(g.first_dev_ms.p50), sec(g.first_dev_ms.p90), ""],
@@ -865,6 +915,12 @@ function renderStats(groups, options) {
   }
   return lines;
 }
+var REACTION_WORDS = [
+  ["moved_on", "moved on"],
+  ["corrected", "corrected it"],
+  ["asked_checks", "asked for checks"],
+  ["none", "no reaction"]
+];
 function rank(phase) {
   const i = PHASE_ORDER.indexOf(phase);
   return i === -1 ? PHASE_ORDER.length : i;
@@ -875,13 +931,24 @@ var CREATE_HELP = `velven create: describe a game, and Velven's agents build it.
 
 Usage:
   velven create new [title...]       Start a project; it becomes the current one
-      --engine <id>                  The engine pack (default phaser)
-      --genre <id>                   The genre pack (default arcade)
-  velven create send <text...>       Send the project a message: prints the estimate, asks, then follows the turn
+      --engine <id>                  The engine pack (default: Velven picks, 3D unless your idea is clearly 2D)
+      --genre <id>                   The genre pack (default none: an open game, Velven follows your idea;
+                                     --genre arcade holds it to arcade's rules)
+  velven create send <text...>       Send the project a message: prints the estimate, asks, then follows the turn.
+                                     Velven picks how much to do (a quick change, a full build with a playtest,
+                                     a plan; on a new game a question or two, then a short plan to shape) unless
+                                     you pass --effort or a plan flag. Sent while a turn runs, it waits its turn
       --project <id>                 A project other than the current one
-      --effort quick|standard|deep   How much the turn may do; kept for later messages until you change it
-      --plan, --no-plan              Plan mode: the turn updates the design document and changes no game files;
-                                     kept until you change it (on by default for standard, off for quick)
+      --effort quick|standard|deep   How much the turn may do, instead of Velven's pick. The project keeps it
+                                     for a later message that passes only a plan flag; a message with neither
+                                     flag is Velven's pick again
+      --plan, --no-plan              Plan mode, instead of Velven's pick: the turn updates the design document
+                                     and changes no game files. Kept as --effort is (with --effort alone, on for
+                                     a new standard or deep, off for quick)
+      --build                        Build it: no more questions, Velven fills in what the plan leaves open
+                                     (Velven still picks how much)
+      --ref <file|ref-n>             A reference picture (PNG, JPEG or WebP, up to 10 MB) sent with the message, or
+                                     one the project keeps by its id (ref-3); up to 4
       --yes, -y                      Do not ask before sending
       --detach                       Send it and return at once; follow it later with watch
   velven create watch [turn]         Follow a turn to its end (default: the last one)
@@ -894,19 +961,31 @@ Usage:
       --turn <id>                    With --timeline: this turn instead of the project's newest
       --all                          With --timeline: list every tool call and screenshot (past 20 under one
                                      step they fold into one line)
+  velven create refs                 The project's reference pictures: each id, when it was added and how many
+                                     messages carried it (a project keeps up to 16)
+      --project <id>                 A project other than the current one
+  velven create refs rm <ref-n>      Delete a picture, sent or not; the messages that carried it keep its number
+  velven create plan                 The project's short plan: what the game is, how it plays, its look
+      --project <id>                 A project other than the current one
+  velven create queue                The messages waiting behind the running turn, in the order they run
+      --project <id>                 A project other than the current one
+  velven create queue rm <id>        Remove a waiting message
   velven create credits              Your credits and the latest entries
+  velven create usage                What each of your turns held and used, newest first
+      --project <id>                 Only this project's turns
+      --before <turn>                The page before this turn (the line at the end names it)
   velven create stats                Admins: p50 and p90 over recent turns, by effort, plan mode and engine
       --days <n>                     Turns created in the last n days, 1 to 90 (default 7)
       --origin <origin>              Only turns sent from web, api, cli, mcp or benchmark
 
-  --json: new, send, list, show, credits and stats print one JSON object (send prints the finished turn,
+  --json: new, send, list, show, plan, queue, refs, credits, usage and stats print one JSON object (send prints the finished turn,
   show --timeline the timeline); watch prints one event per line.
   Ctrl+C stops following a turn; the turn goes on.
 
 Exit codes:
   0 done (also a turn that stopped at its credit cap or time limit)   1 failed, cancelled or no longer followed
   2 bad command   3 needs sign-in   4 refused (no credits, closed, busy, too many turns, effort unavailable,
-  not found)   5 rate limited, try later`;
+  a picture refused, not found)   5 rate limited, try later`;
 var CREATE_FLAGS = {
   engine: "string",
   genre: "string",
@@ -914,6 +993,8 @@ var CREATE_FLAGS = {
   effort: "string",
   plan: "boolean",
   "no-plan": "boolean",
+  build: "boolean",
+  ref: "strings",
   yes: "boolean",
   detach: "boolean",
   from: "string",
@@ -922,19 +1003,26 @@ var CREATE_FLAGS = {
   turn: "string",
   all: "boolean",
   days: "string",
-  origin: "string"
+  origin: "string",
+  before: "string"
 };
 var SUBCOMMANDS = {
   new: ["engine", "genre", "json"],
-  send: ["project", "effort", "plan", "no-plan", "yes", "detach", "json"],
+  send: ["project", "effort", "plan", "no-plan", "build", "ref", "yes", "detach", "json"],
   watch: ["from", "json"],
   cancel: [],
   list: ["json"],
   show: ["json", "timeline", "turn", "all"],
+  refs: ["project", "json"],
+  plan: ["project", "json"],
+  queue: ["project", "json"],
   credits: ["json"],
+  usage: ["project", "before", "json"],
   stats: ["days", "origin", "json"]
 };
 var EFFORTS = ["quick", "standard", "deep"];
+var REFS_PER_MESSAGE = 4;
+var REFS_PER_PROJECT = 16;
 var ORIGINS = ["web", "api", "cli", "mcp", "benchmark"];
 var ROOT = "/api/v1/create";
 async function create(ctx, parsed) {
@@ -974,6 +1062,14 @@ async function create(ctx, parsed) {
       return show(ctx, api, args[0], json);
     case "stats":
       return stats(ctx, api, stringFlag(parsed, "days"), stringFlag(parsed, "origin"), json);
+    case "refs":
+      return referencePictures(ctx, api, args, stringFlag(parsed, "project"), json);
+    case "usage":
+      return usage(ctx, api, stringFlag(parsed, "project"), stringFlag(parsed, "before"), json);
+    case "plan":
+      return showPlan(ctx, api, args, stringFlag(parsed, "project"), json);
+    case "queue":
+      return queue(ctx, api, args, stringFlag(parsed, "project"), json);
     default:
       return credits(ctx, api, json);
   }
@@ -993,7 +1089,11 @@ async function newProject(ctx, api, title, engine, genre, json) {
     return EXIT.ok;
   }
   ctx.out(`Started ${project.title ?? "a project"} (${project.id}): ${packs(project)}. It is now the current project.`);
-  ctx.out('Tell it what to build: velven create send "a one-button game where a fox jumps over logs"');
+  if (!project.genre)
+    ctx.out("An open game: Velven follows your idea. --genre arcade holds a project to arcade's rules.");
+  if (!engine)
+    ctx.out("Velven picks the engine from your idea: 3D unless it is clearly 2D.");
+  ctx.out('Tell it what to build: velven create send "a cozy game where you grow a garden on a floating island"');
   return EXIT.ok;
 }
 async function send(ctx, api, words, parsed, json) {
@@ -1008,17 +1108,32 @@ async function send(ctx, api, words, parsed, json) {
     throw new CliError("Pass --plan or --no-plan, not both.", EXIT.usage, "usage");
   }
   const plan = parsed.flags.plan === true ? true : parsed.flags["no-plan"] === true ? false : undefined;
+  const routed = effort === undefined && plan === undefined;
+  const refs = stringsFlag(parsed, "ref");
+  if (refs.length > REFS_PER_MESSAGE)
+    throw new CliError(`A message takes up to ${REFS_PER_MESSAGE} pictures; ${refs.length} were given with --ref.`, EXIT.usage, "usage");
+  const pictures = await Promise.all(refs.map((ref) => REF_ID.test(ref) ? ref : readPicture(ctx, ref)));
   const project = await currentProject(ctx, api.base, stringFlag(parsed, "project"));
   const say = json ? () => {} : (line) => ctx.out(line);
   const query = new URLSearchParams;
+  if (routed)
+    query.set("routed", "true");
+  if (routed && parsed.flags.build === true)
+    query.set("intent", "build");
   if (effort !== undefined)
     query.set("effort", effort);
   if (plan !== undefined)
     query.set("plan", String(plan));
+  query.set("queue", "true");
   const search = query.toString();
   const { estimate } = await call(api, "GET", `${ROOT}/projects/${seg(project)}/estimate${search ? `?${search}` : ""}`);
-  const kind = estimate.plan ? `${estimate.effort} plan turn` : estimate.first_build === true ? `${estimate.effort} first build (its pictures are made before the first preview)` : `${estimate.effort} build turn`;
-  say(`A ${kind}: about ${estimate.credits.typical} credits, at most ${estimate.credits.cap}. You have ${estimate.available} available.`);
+  if (routed) {
+    const what = estimate.shaping === true ? "a question or a short plan" : estimate.first_build === true ? "a first build (its pictures are made before the first preview)" : "a small change";
+    say(`Velven picks how much to do: about ${estimate.credits.typical} credits for ${what}, at most ${estimate.credits.cap} held. You have ${estimate.available} available.`);
+  } else {
+    const kind = estimate.plan ? `${estimate.effort} plan turn` : estimate.first_build === true ? `${estimate.effort} first build (its pictures are made before the first preview)` : `${estimate.effort} build turn`;
+    say(`A ${kind}: about ${estimate.credits.typical} credits, at most ${estimate.credits.cap}. You have ${estimate.available} available.`);
+  }
   if (!estimate.enough) {
     throw new CliError(estimate.reason ?? "Velven cannot start this turn now.", EXIT.refused, "not_enough");
   }
@@ -1029,13 +1144,39 @@ async function send(ctx, api, words, parsed, json) {
       return EXIT.failed;
     }
   }
-  const body = { text };
+  const body = { text, queue: true };
   if (effort !== undefined)
     body.effort = effort;
   if (plan !== undefined)
     body.plan = plan;
+  if (parsed.flags.build === true)
+    body.intent = "build";
+  if (pictures.length) {
+    const ids = [];
+    for (const picture of pictures)
+      ids.push(typeof picture === "string" ? picture : await uploadPicture(api, project, picture));
+    body.references = ids;
+    say(`Attached ${plural2(ids.length, "picture")}: ${ids.join(", ")}.`);
+  }
   const sent = await call(api, "POST", `${ROOT}/projects/${seg(project)}/messages`, body);
-  const turn = sent.turn;
+  let turn;
+  let stream2;
+  if ("queued" in sent) {
+    const queued = sent.queued;
+    if (queued.state === "refused")
+      throw new CliError(queued.refused ?? "Velven could not start this message.", EXIT.refused, "refused");
+    if (queued.state === "waiting" || queued.turn === null) {
+      if (json)
+        ctx.out(JSON.stringify({ ok: true, queued }));
+      else
+        say(queuedLine(queued));
+      return EXIT.ok;
+    }
+    turn = { id: queued.turn, ...queued.capped === true ? { queued: true } : {} };
+  } else {
+    turn = sent.turn;
+    stream2 = sent.stream;
+  }
   await saveCreateState(ctx, api.base, { project, turn: turn.id });
   if (turn.queued)
     say(`Turn ${turn.id} waits for room on Velven and starts on its own.`);
@@ -1048,8 +1189,46 @@ async function send(ctx, api, words, parsed, json) {
       say(`Follow it: velven create watch ${turn.id}; stop it: velven create cancel ${turn.id}`);
     return EXIT.ok;
   }
-  const path = sent.stream?.startsWith("/") ? sent.stream : `${ROOT}/turns/${seg(turn.id)}/stream`;
-  return follow(ctx, api, turn.id, path, undefined, json ? "final" : "text");
+  const path = stream2?.startsWith("/") ? stream2 : `${ROOT}/turns/${seg(turn.id)}/stream`;
+  return follow(ctx, api, turn.id, path, undefined, json ? "final" : "text", project);
+}
+var REF_ID = /^ref-[1-9][0-9]{0,2}$/;
+async function uploadPicture(api, project, picture) {
+  const { upload } = await call(api, "POST", `${ROOT}/projects/${seg(project)}/references/uploads`);
+  const tooLarge = `The picture ${picture.file} is larger than ${Math.floor(upload.max_bytes / (1024 * 1024))} MB. Send a smaller one.`;
+  if (picture.bytes.length > upload.max_bytes)
+    throw new CliError(tooLarge, EXIT.refused, "too_large");
+  await putBytes(upload.url, picture.bytes, picture.type, tooLarge);
+  try {
+    const { reference } = await call(api, "POST", `${ROOT}/projects/${seg(project)}/references`, { upload: upload.id });
+    return reference.id;
+  } catch (e) {
+    if (e instanceof CliError && e.code === "too_many_references") {
+      const named = `velven create refs --project ${project}`;
+      throw new CliError(`${e.message} See them: ${named}; remove one: velven create refs rm <ref-n> --project ${project}.`, e.exitCode, e.code);
+    }
+    throw e;
+  }
+}
+var PICTURE_TYPES = { png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", webp: "image/webp" };
+async function readPicture(ctx, file) {
+  let bytes;
+  try {
+    bytes = new Uint8Array(await readFile3(resolve(ctx.cwd, file)));
+  } catch {
+    throw new CliError(`Could not read the picture ${file}.`, EXIT.usage, "usage");
+  }
+  const ext = file.toLowerCase().split(".").pop() ?? "";
+  return { file, bytes, type: PICTURE_TYPES[ext] ?? "application/octet-stream" };
+}
+async function turnProject(ctx, api, turn) {
+  const { project: current } = await readCreateState(ctx, api.base);
+  try {
+    const { turn: view } = await call(api, "GET", `${ROOT}/turns/${seg(turn)}`);
+    return view.project ?? current ?? null;
+  } catch {
+    return current ?? null;
+  }
 }
 async function watch(ctx, api, arg, fromFlag, json) {
   let from;
@@ -1059,9 +1238,10 @@ async function watch(ctx, api, arg, fromFlag, json) {
     from = Number(fromFlag);
   }
   const turn = await turnId(ctx, api.base, arg, "watch");
+  const named = json ? null : await turnProject(ctx, api, turn);
   let code;
   try {
-    code = await follow(ctx, api, turn, `${ROOT}/turns/${seg(turn)}/stream`, from, json ? "events" : "text");
+    code = await follow(ctx, api, turn, `${ROOT}/turns/${seg(turn)}/stream`, from, json ? "events" : "text", named);
   } catch (e) {
     if (e instanceof CliError && e.code === "stream_lost")
       await saveCreateState(ctx, api.base, { turn });
@@ -1070,10 +1250,10 @@ async function watch(ctx, api, arg, fromFlag, json) {
   await saveCreateState(ctx, api.base, { turn });
   return code;
 }
-async function follow(ctx, api, turn, path, from, mode) {
+async function follow(ctx, api, turn, path, from, mode, project) {
   const controller = new AbortController;
   ctx.untilStopped().then(() => controller.abort());
-  const said = { held: null, engine: null };
+  const said = { held: null, engine: null, project, asked: false, next: [] };
   let final;
   try {
     final = await stream(api, path, { from, signal: controller.signal, sleep: ctx.sleep }, (event2) => {
@@ -1118,7 +1298,7 @@ async function follow(ctx, api, turn, path, from, mode) {
     }
     ctx.out(JSON.stringify({ ok: code === EXIT.ok, ...error, turn: view }));
   } else if (mode === "text") {
-    finish(ctx, turn, event);
+    finish(ctx, turn, event, said);
   }
   return code;
 }
@@ -1165,12 +1345,51 @@ function render(ctx, event, said) {
   release(ctx, said);
   switch (event.type) {
     case "turn.started":
-      ctx.err(`Started: ${event.effort}${event.plan ? ", plan mode" : ""}, ${plural2(event.credits_held, "credit")} held.`);
+      if (event.routed === true)
+        ctx.err(`Started: Velven is choosing the work, ${plural2(event.credits_held, "credit")} held.`);
+      else
+        ctx.err(`Started: ${event.effort}${event.plan ? ", plan mode" : ""}, ${plural2(event.credits_held, "credit")} held.`);
+      return;
+    case "route":
+      ctx.out(event.said);
+      ctx.err(`  (${event.work}, ${event.effort}${event.plan ? ", plan mode" : ""}, ${plural2(event.credits_held, "credit")} held: ${event.reason})`);
+      return;
+    case "ask": {
+      ctx.out(`${event.question} (question ${event.index} of ${event.of})`);
+      for (const [i, choice] of event.choices.entries())
+        ctx.out(`  ${i + 1}. ${choice}`);
+      const send2 = sendCommand(said);
+      ctx.out(`Answer: ${send2} "${event.choices[0]}", or in your own words.`);
+      if (event.picture || event.topic === "style")
+        ctx.out(`Or show the look: ${send2} --ref <file> "like this".`);
+      ctx.out(`Just build it: ${send2} --build "Just build it"`);
+      said.asked = true;
       return;
+    }
+    case "plan":
+      if (!event.done)
+        return;
+      for (const line of planCard(event.plan))
+        ctx.out(line);
+      ctx.out(`Build it: ${sendCommand(said)} --build "Build it"`);
+      return;
+    case "brief": {
+      if (!event.done)
+        return;
+      if (event.title || event.pitch)
+        ctx.out(`Designing ${event.title ?? "your game"}${event.pitch ? `: ${event.pitch}` : ""}`);
+      if (event.style)
+        ctx.out(`  Style: ${event.style}`);
+      if (event.palette.length)
+        ctx.out(`  Palette: ${event.palette.join(", ")}`);
+      return;
+    }
     case "turn.queued":
       ctx.err("Still waiting for room on Velven.");
       return;
     case "phase":
+      if (event.progress)
+        ctx.out(event.progress.label);
       ctx.err(`${capital(event.phase)}${event.detail ? `: ${event.detail}` : ""}`);
       return;
     case "job": {
@@ -1192,6 +1411,8 @@ function render(ctx, event, said) {
     }
     case "tool":
       ctx.err(`  ${event.name}: ${event.summary}${typeof event.ms === "number" ? ` (${duration(event.ms)})` : ""}`);
+      if (event.picture?.url)
+        ctx.out(`Painted ${event.picture.id} (${event.picture.width} by ${event.picture.height}) ${dim(ctx, event.picture.url)}`);
       return;
     case "text":
       ctx.out(event.text);
@@ -1245,18 +1466,32 @@ function render(ctx, event, said) {
     case "cost":
       ctx.err(`${event.credits_used} of ${plural2(event.credits_held, "credit")} used so far.`);
       return;
+    case "next":
+      said.next = event.choices;
+      return;
     default:
       return;
   }
 }
-function finish(ctx, turn, event) {
+function finish(ctx, turn, event, said) {
   if (event.type === "error") {
     const tail = event.code === "turn_stopped" || event.code === "not_found" ? " Check it again later: velven create show" : ` The turn may go on. Watch it: velven create watch ${turn}; check it: velven create show`;
     ctx.err(`${event.message || "The turn's stream answered with an error."}${tail}`);
     return;
   }
-  if (event.reply)
-    ctx.out(event.reply);
+  const reply = event.reply && said.asked ? event.reply.split(`
+
+`).slice(1).join(`
+
+`) : event.reply;
+  if (reply)
+    ctx.out(reply);
+  if (said.next.length) {
+    ctx.out("Where it could go next:");
+    for (const [i, choice] of said.next.entries())
+      ctx.out(`  ${i + 1}. ${choice}`);
+    ctx.out(`Send one: velven create send${said.project ? ` --project ${said.project}` : ""} "${said.next[0]}"`);
+  }
   if (event.preview)
     ctx.out(`Play it: ${event.preview.url}`);
   const back = event.refunded > 0 ? `; ${plural2(event.refunded, "credit")} came back` : "";
@@ -1266,13 +1501,56 @@ function finish(ctx, turn, event) {
       ctx.out("It stopped at its credit cap. What it finished is saved: send another message to go on.");
     if (event.stop_reason === "time")
       ctx.out("It stopped at its time limit. What it finished is saved: send another message to go on.");
-    return;
-  }
-  if (event.status === "cancelled") {
+  } else if (event.status === "cancelled") {
     ctx.err(`Turn ${turn} was cancelled: ${plural2(event.credits_charged, "credit")} used${back}. What it finished is saved.`);
-    return;
+  } else {
+    ctx.err(`Turn ${turn} failed: ${event.error ?? "Velven could not finish it."} A failed turn costs nothing.`);
   }
-  ctx.err(`Turn ${turn} failed: ${event.error ?? "Velven could not finish it."} A failed turn costs nothing.`);
+  if (reply?.includes(BUILD_AGAIN))
+    ctx.out(`Try again: ${sendCommand(said)} --build "Build it"`);
+  if (event.next_turn) {
+    const elsewhere = event.next_project && said.project && event.next_project !== said.project ? ` on project ${event.next_project}` : "";
+    ctx.out(`Your next message${elsewhere} is running: velven create watch ${event.next_turn}`);
+  }
+}
+var BUILD_AGAIN = "Press Build it to try again.";
+function sendCommand(said) {
+  return `velven create send${said.project ? ` --project ${said.project}` : ""}`;
+}
+function dim(ctx, text) {
+  return ctx.interactive && !ctx.env.NO_COLOR ? `\x1B[2m${text}\x1B[22m` : text;
+}
+function planCard(plan) {
+  const lines = [];
+  if (plan.title)
+    lines.push(plan.title);
+  if (plan.pitch)
+    lines.push(plan.pitch);
+  if (plan.dimension)
+    lines.push(`${plan.dimension === "3d" ? "3D" : "2D"}${plan.camera ? `, ${plan.camera}` : ""}`);
+  if (plan.play?.length) {
+    lines.push("How it plays:");
+    for (const [i, beat] of plan.play.entries())
+      lines.push(`  ${i + 1}. ${beat}`);
+  }
+  if (plan.look)
+    lines.push(`Look: ${plan.look}`);
+  if (plan.palette?.length)
+    lines.push(`Palette: ${plan.palette.join(", ")}`);
+  if (plan.contents?.length) {
+    lines.push("What is in it:");
+    for (const thing of plan.contents)
+      lines.push(`  - ${thing}`);
+  }
+  if (plan.ending)
+    lines.push(`How it ends: ${plan.ending}`);
+  if (plan.score !== undefined)
+    lines.push(plan.score ? "It keeps a score." : "No score.");
+  return lines;
+}
+function queuedLine(queued) {
+  const ahead = queued.position !== null && queued.position > 1 ? ` and ${plural2(queued.position - 1, "message")} ahead of it` : "";
+  return `Queued: it runs after the turn that is running${ahead}. velven create queue lists what waits.`;
 }
 async function cancel(ctx, api, arg) {
   const turn = await turnId(ctx, api.base, arg, "cancel");
@@ -1383,6 +1661,125 @@ async function stats(ctx, api, daysFlag, origin, json) {
     ctx.out(line);
   return EXIT.ok;
 }
+async function referencePictures(ctx, api, args, projectFlag, json) {
+  const [action, id, ...rest] = args;
+  if (action === "rm") {
+    if (id === undefined || !REF_ID.test(id) || rest.length) {
+      throw new CliError("Name one picture to remove by its id, like velven create refs rm ref-3.", EXIT.usage, "usage");
+    }
+    const project2 = await currentProject(ctx, api.base, projectFlag);
+    await call(api, "DELETE", `${ROOT}/projects/${seg(project2)}/references/${seg(id)}`);
+    if (json)
+      ctx.out(JSON.stringify({ ok: true, deleted: id }));
+    else
+      ctx.out(`Removed ${id}. The messages that carried it keep its number, shown as removed.`);
+    return EXIT.ok;
+  }
+  if (action !== undefined) {
+    throw new CliError(`Unknown command "create refs ${action}". List the pictures with velven create refs, remove one with velven create refs rm ref-3.`, EXIT.usage, "usage");
+  }
+  const project = await currentProject(ctx, api.base, projectFlag);
+  const { references } = await call(api, "GET", `${ROOT}/projects/${seg(project)}/references`);
+  if (json) {
+    ctx.out(JSON.stringify({ ok: true, references }));
+    return EXIT.ok;
+  }
+  if (!references.length) {
+    ctx.out('No reference pictures yet. Attach one: velven create send --ref <picture> "like this".');
+    return EXIT.ok;
+  }
+  for (const r of references) {
+    const carried = r.messages !== undefined ? r.messages ? `on ${plural2(r.messages, "message")}` : "not sent yet" : r.attached ? "sent" : "not sent yet";
+    ctx.out(`${r.id.padEnd(7)}  ${when(r.created_at).padEnd(20)}  ${`${r.width} by ${r.height}`.padEnd(12)}  ${carried}`);
+  }
+  ctx.out(`${references.length} of ${REFS_PER_PROJECT} kept. A picture no message carried goes a day after it was last uploaded.`);
+  return EXIT.ok;
+}
+async function usage(ctx, api, project, before, json) {
+  if (before !== undefined && (!/^\d+$/.test(before) || Number(before) === 0))
+    throw new CliError(`--before is a turn number, like 12, not "${before}".`, EXIT.usage, "usage");
+  const query = new URLSearchParams;
+  if (project)
+    query.set("project", project);
+  if (before)
+    query.set("before", before);
+  const search = query.toString();
+  const answer = await call(api, "GET", `${ROOT}/usage${search ? `?${search}` : ""}`);
+  if (json) {
+    ctx.out(JSON.stringify({ ok: true, ...answer }));
+    return EXIT.ok;
+  }
+  if (!answer.turns.length) {
+    ctx.out(before ? "No earlier turns." : "No turns yet.");
+    return EXIT.ok;
+  }
+  for (const t of answer.turns) {
+    const used = t.credits.charged !== null ? `${plural2(t.credits.charged, "credit")} used` : `${plural2(t.credits.held, "credit")} held`;
+    const kind = t.work ?? `${t.effort}${t.plan ? " plan" : ""}`;
+    ctx.out(`turn ${String(t.turn).padEnd(6)}  ${when(t.created_at).padEnd(20)}  ${(t.project.title ?? "Untitled").padEnd(24)}  ${kind.padEnd(10)}  ${t.status.padEnd(9)}  ${used}`.trimEnd());
+  }
+  if (answer.next !== null)
+    ctx.out(`More: velven create usage${project ? ` --project ${project}` : ""} --before ${answer.next}`);
+  return EXIT.ok;
+}
+async function showPlan(ctx, api, args, projectFlag, json) {
+  if (args.length)
+    throw new CliError("velven create plan takes no words: name another project with --project <id>.", EXIT.usage, "usage");
+  const id = await currentProject(ctx, api.base, projectFlag);
+  const { project } = await call(api, "GET", `${ROOT}/projects/${seg(id)}`);
+  const plan = project.game_plan ?? null;
+  if (json) {
+    ctx.out(JSON.stringify({ ok: true, plan }));
+    return EXIT.ok;
+  }
+  if (!plan) {
+    ctx.out('This project has no plan yet. Send your idea and Velven sketches one with you: velven create send "a cozy farming game".');
+    return EXIT.ok;
+  }
+  for (const line of planCard(plan))
+    ctx.out(line);
+  if (!project.head)
+    ctx.out(`Build it: velven create send${projectFlag ? ` --project ${id}` : ""} --build "Build it"`);
+  return EXIT.ok;
+}
+async function queue(ctx, api, args, projectFlag, json) {
+  const [action, id, ...rest] = args;
+  if (action === "rm") {
+    if (id === undefined || !/^\d+$/.test(id) || Number(id) === 0 || rest.length) {
+      throw new CliError("Name one waiting message by its number, like velven create queue rm 12.", EXIT.usage, "usage");
+    }
+    const project2 = await currentProject(ctx, api.base, projectFlag);
+    await call(api, "DELETE", `${ROOT}/projects/${seg(project2)}/queue/${seg(id)}`);
+    if (json)
+      ctx.out(JSON.stringify({ ok: true, removed: Number(id) }));
+    else
+      ctx.out(`Removed message ${id}: it will not run.`);
+    return EXIT.ok;
+  }
+  if (action !== undefined) {
+    throw new CliError(`Unknown command "create queue ${action}". List what waits with velven create queue, remove one with velven create queue rm 12.`, EXIT.usage, "usage");
+  }
+  const project = await currentProject(ctx, api.base, projectFlag);
+  const { queued } = await call(api, "GET", `${ROOT}/projects/${seg(project)}/queue`);
+  if (json) {
+    ctx.out(JSON.stringify({ ok: true, queued }));
+    return EXIT.ok;
+  }
+  if (!queued.length) {
+    ctx.out("Nothing is waiting on this project.");
+    return EXIT.ok;
+  }
+  for (const q of queued) {
+    const at = q.position !== null ? `${q.position}.` : q.state === "refused" ? "x" : "-";
+    const words = q.text.length > 60 ? `${q.text.slice(0, 59)}…` : q.text;
+    ctx.out(`${at.padStart(3)} ${String(q.id).padEnd(6)}  ${when(q.created_at).padEnd(20)}  ${q.intent === "build" ? "[build] " : ""}${words}`);
+    if (q.state === "refused" && q.refused)
+      ctx.out(`      Not sent: ${q.refused}`);
+  }
+  if (queued.some((q) => q.state === "waiting"))
+    ctx.out("They run in this order when the running turn ends. Remove one: velven create queue rm <number>");
+  return EXIT.ok;
+}
 async function credits(ctx, api, json) {
   const view = await call(api, "GET", `${ROOT}/credits`);
   if (json) {
@@ -1428,9 +1825,9 @@ async function turnId(ctx, base, arg, verb) {
 
 // src/dev.ts
 import { createReadStream as createReadStream2 } from "node:fs";
-import { open as open2, readdir as readdir3, readFile as readFile5, realpath as realpath2, stat as stat2 } from "node:fs/promises";
+import { open as open2, readdir as readdir3, readFile as readFile6, realpath as realpath2, stat as stat2 } from "node:fs/promises";
 import { createServer } from "node:http";
-import { extname, join as join5, relative as relative2, resolve, sep } from "node:path";
+import { extname, join as join5, relative as relative2, resolve as resolve2, sep } from "node:path";
 import { createBrotliDecompress, createGunzip } from "node:zlib";
 
 // ../scan-rules/src/each-limit.ts
@@ -1753,7 +2150,7 @@ function refusalSentence(findings) {
 // src/files.ts
 import { createHash } from "node:crypto";
 import { createReadStream } from "node:fs";
-import { open, readdir as readdir2, readFile as readFile4, realpath, stat } from "node:fs/promises";
+import { open, readdir as readdir2, readFile as readFile5, realpath, stat } from "node:fs/promises";
 import { join as join4, relative } from "node:path";
 
 // src/ignore.ts
@@ -2058,7 +2455,7 @@ function mediaProblem(kind, path, size2, bytes, missing = "is not among the file
 }
 
 // src/project.ts
-import { readdir, readFile as readFile3, writeFile as writeFile3 } from "node:fs/promises";
+import { readdir, readFile as readFile4, writeFile as writeFile3 } from "node:fs/promises";
 import { join as join3, win32 } from "node:path";
 var SPACE_TYPES = ["game", "world", "tool", "wonder"];
 var DEVICES = ["desktop", "mobile", "vr"];
@@ -2078,7 +2475,7 @@ async function readProject(dir) {
   const path = join3(dir, names.includes(PROJECT_FILE) ? PROJECT_FILE : names.find(isProjectName) ?? PROJECT_FILE);
   let text;
   try {
-    text = await readFile3(path, "utf8");
+    text = await readFile4(path, "utf8");
   } catch {
     return { path, exists: false, data: {} };
   }
@@ -2243,7 +2640,7 @@ async function walk(root, skipped = () => {}) {
   const realRoot = await realpath(root);
   let rules = [];
   try {
-    rules = parseIgnore(await readFile4(join4(root, ".velvenignore"), "utf8"));
+    rules = parseIgnore(await readFile5(join4(root, ".velvenignore"), "utf8"));
   } catch {
     rules = [];
   }
@@ -2364,7 +2761,7 @@ async function checkMedia(config, files) {
       continue;
     const path = mediaPath(raw);
     const file = files.find((f) => f.path === path);
-    const bytes = !file ? undefined : file.size <= MEDIA_RULES[kind].maxBytes ? new Uint8Array(await readFile4(file.abs)) : await readHead(file.abs);
+    const bytes = !file ? undefined : file.size <= MEDIA_RULES[kind].maxBytes ? new Uint8Array(await readFile5(file.abs)) : await readHead(file.abs);
     const problem = mediaProblem(kind, path, file?.size, bytes, "is not among the files this publish sends: check the path, and that .velvenignore does not leave it out");
     if (problem)
       problems.push(problem);
@@ -2376,9 +2773,9 @@ async function checkMedia(config, files) {
   return out;
 }
 function hashFile(abs) {
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     const hash = createHash("sha256");
-    createReadStream(abs).on("data", (chunk) => hash.update(chunk)).on("error", reject).on("end", () => resolve(hash.digest("hex")));
+    createReadStream(abs).on("data", (chunk) => hash.update(chunk)).on("error", reject).on("end", () => resolve2(hash.digest("hex")));
   });
 }
 var HASH_CHUNK = 4 * MB;
@@ -2551,7 +2948,7 @@ function injectSdk(html, src) {
   return tag + html;
 }
 async function ignoreRules(root) {
-  return parseIgnore(await readFile5(join5(root, ".velvenignore"), "utf8").catch(() => ""));
+  return parseIgnore(await readFile6(join5(root, ".velvenignore"), "utf8").catch(() => ""));
 }
 async function namedAsOnDisk(base, rel) {
   const parts = rel.split("/").filter(Boolean);
@@ -2567,7 +2964,7 @@ async function statExact(base, rel) {
   return info && await namedAsOnDisk(base, rel) ? info : null;
 }
 async function startDevServer(root, options) {
-  const base = resolve(root);
+  const base = resolve2(root);
   const realBase = await realpath2(base);
   const server = createServer(async (req, res) => {
     const send2 = (status, body2, headers2 = {}) => {
@@ -2586,7 +2983,7 @@ async function startDevServer(root, options) {
     if (!parts.every(servableSegment))
       return send2(404, "Not found", { "content-type": "text/plain; charset=utf-8" });
     let rel = parts.join("/");
-    let file = resolve(base, rel);
+    let file = resolve2(base, rel);
     if (file !== base && !file.startsWith(base + sep))
       return send2(404, "Not found");
     let info = await statExact(base, rel);
@@ -2615,7 +3012,7 @@ async function startDevServer(root, options) {
     if (!real || !servableRelative(relative2(realBase, real))) {
       return send2(404, "Not found", { "content-type": "text/plain; charset=utf-8" });
     }
-    let body = await readFile5(file);
+    let body = await readFile6(file);
     const { type, encoding } = contentType(file, body);
     if (rel === options.entry && options.sdkSrc && !encoding)
       body = injectSdk(body.toString("utf8"), options.sdkSrc);
@@ -2638,7 +3035,7 @@ async function startDevServer(root, options) {
   };
 }
 async function dev(ctx, dirArg, portFlag) {
-  const dir = resolve(ctx.cwd, dirArg ?? ".");
+  const dir = resolve2(ctx.cwd, dirArg ?? ".");
   const info = await stat2(dir).catch(() => null);
   if (!info?.isDirectory())
     throw new CliError(`There is no folder at ${dir}.`, EXIT.usage, "usage");
@@ -2689,7 +3086,7 @@ async function dev(ctx, dirArg, portFlag) {
 
 // src/publish.ts
 import { stat as stat3 } from "node:fs/promises";
-import { resolve as resolve2 } from "node:path";
+import { resolve as resolve3 } from "node:path";
 
 // src/upload.ts
 import { open as open3 } from "node:fs/promises";
@@ -2796,7 +3193,7 @@ function fileEntry(f) {
 }
 var hashesOf = (f) => f.pieces ?? (f.sha256 ? [f.sha256] : []);
 async function folderOf(ctx, arg) {
-  const dir = resolve2(ctx.cwd, arg ?? ".");
+  const dir = resolve3(ctx.cwd, arg ?? ".");
   const info = await stat3(dir).catch(() => null);
   if (!info)
     throw new CliError(`There is no folder at ${dir}.`, EXIT.usage, "usage");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velven/cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Publish a folder to Velven, the community marketplace for spaces built with AI: a private preview first, then hosted and live on its own page in seconds.",
   "license": "MIT",
   "homepage": "https://velven.ai/docs",