@wji.ai/cli 0.1.0 → 0.2.0

package/skill/wji/SKILL.md

@@ -15,6 +15,18 @@ and the human table output when you are showing the user a result.
 wji auth whoami --json      # confirms endpoint, credential, org context
 ```
 
+- **Check for a CLI update first.** The skill documents the newest commands, so
+  an old binary fails in confusing ways:
+
+  ```bash
+  wji --version && npm view @wji.ai/cli version
+  ```
+
+  If the installed version is lower, tell the user to run
+  `npm i -g @wji.ai/cli@latest` (or `pnpm add -g` / `yarn global add`) before
+  continuing. A dev checkout linked into PATH updates with `pnpm build`
+  instead. If the registry check fails (offline, proxy), carry on — don't
+  block the task on it.
 - `wji: command not found`: the CLI is not on PATH. From the `wji-cli` repo,
   `npm run build`, then link it where the user can write without sudo —
   `ln -s "$PWD/dist/index.js" ~/.local/bin/wji` (if `~/.local/bin` is on
@@ -28,6 +40,9 @@ wji auth whoami --json      # confirms endpoint, credential, org context
 - `wji config show` reveals which endpoint and profile are active. A local
   backend is `wji config set endpoint http://localhost:3002` — `:3000` is the
   web frontend, not the API.
+- **Scan the user's message for `-auto`.** It is not a CLI flag — it is the
+  user telling you to generate everything this request needs without stopping
+  to confirm the spend. See *Rules* for what it does and does not waive.
 - **Running several `wji` commands in parallel? Prefer an API key**
   (`WJI_API_KEY`, or `wji auth key create <name> --save`). A JWT login rotates
   its refresh token, and the server revokes *every* session if a refresh token
@@ -68,6 +83,10 @@ wji ws use <workspaceId>
 After that, `wji ws get`, `wji fs`, `wji gen` and `wji preset list` all default
 to that workspace. Use `wji ws use` rather than repeating `--workspace`.
 
+`wji ws create <name>` seeds the default template — Dataset, DatasetImageGeneration and
+InfiniteCanvas — because the API creates no apps on its own; pass `-a` to choose apps or
+`--no-apps` for an empty workspace.
+
 ## Reading and editing the tree
 
 ```bash
@@ -80,12 +99,15 @@ wji fs get <nodeId> --json | jq .content
 wji fs mkdir <parentId> characters --nickname 角色
 wji dataset new <folderId> "Ada" -t character -d "a tired detective"
 wji fs describe <nodeId> @description.md
-wji fs set <nodeId> --images <assetId> <assetId>
+wji fs set <nodeId> --merge content=@body.md --merge viewMode=content   # merged into content
+wji fs set <nodeId> --add-images <assetId> <assetId>                    # appended
+wji fs set <nodeId> --images <assetId> <assetId>                        # replaced
 ```
 
-`wji fs set --content` **replaces** the whole content object. To change one
-field, read it first (`wji fs get <id> --json | jq .content`), merge, then
-write — or use `wji fs describe`, which merges `content.description` for you.
+`wji fs set --content` **replaces** the whole content object, and so does
+`--set content.x=…`. To change fields inside `content`, use `--merge key=value`
+(dotted keys, `@file` values) — it reads the node and deep-merges for you, like
+`wji fs describe` does for `content.description`.
 
 Several GET endpoints are cached server-side for 10 seconds, so a plain read
 immediately after a write can come back stale. `wji fs describe` and
@@ -115,11 +137,19 @@ wji gen video -m <modelName> -p "slow pan" -d 5 --start-image <assetId> --wait -
 wji gen audio -m <modelName> -p "rain on a tin roof" --wait
 ```
 
+- **Check the spending policy in *Rules* before you submit:** a single image
+  just runs; video, audio and anything with `-n` above 1 need a yes in the
+  chat first — unless the user's message carried `-auto`.
 - References are `assetId[:label[:weight]]`: `--ref 65f0…:hero:0.6`. Reference
   *assets*, not file paths — upload first with `wji asset upload`.
 - Model-specific parameters go through `--set` (`--set quality=high`); read the
   valid keys from `wji models get`.
-- `--fsnode <id>` files the result onto a node; `--tags` labels the history.
+- `--fsnode <id>` files the *history entry* under a node — it does **not** add
+  the asset to that node's `images`. Recover them later with
+  `wji history list --fsnode <id>`. To make a generated image part of a dataset
+  you must attach it yourself, and `fs set --images` replaces the whole array:
+  read the current ids first, then write old + new together.
+- `--tags` labels the history entry.
 - Video can take minutes. Without `--wait` you get a history id back:
   `wji history get <id> --wait` resumes polling, and `--timeout` is in seconds.
 - On timeout the task is usually still running — re-poll rather than
@@ -142,6 +172,18 @@ confirm with `wji models list --feature <image|video>` and `wji models get`.
 and big changes such as character sheets; `gpt-image-2.5-flare` for edits that
 keep the composition), **Nano Banana 2** or **Nano Banana Pro**.
 
+Two image jobs have one right model each:
+
+- **Transparent background** (logos, cut-outs, overlays, sprites) → GPT Image
+  2.5 with `--set background=transparent`; the result comes back as PNG with
+  alpha. `opaque` forces a filled background, `auto` lets the model decide.
+- **Split a picture into layers** (subject separated from background, for
+  compositing) → `bytedance-seedream-5-pro` with
+  `--set layer_decomposition=true`. It needs **exactly one** reference image,
+  a size tier (`--set size=1K|2K`, not pixel dimensions), and returns several
+  PNG layers as separate assets. On a canvas, run it in the browser's layer
+  editor instead — a CLI generate node keeps only one asset per node.
+
 **Video — reference models over first/last-frame models.** A family usually
 has both:
 
@@ -207,11 +249,11 @@ a Ref model.
 
 ```bash
 wji fs get <datasetId> --scope full --json | jq '{images: [.images[]? | {id, type}], icon, primaryAudio}'
-wji fs set <datasetId> --images <headshot> <sheet> <voice> --icon <headshot> --set primaryAudio=<voice>
+wji fs set <datasetId> --add-images <headshot> <sheet> <voice> --icon <headshot> --set primaryAudio=<voice>
 ```
 
-`--images` replaces the whole list — read the current list first and keep
-what is already there.
+`--add-images` appends; `--images` replaces the whole list — use it only when
+the user wants the list rewritten, after reading what is there.
 
 ## Assets
 
@@ -267,12 +309,19 @@ use `skill push` for large files.
 
 ## Canvas
 
-An Infinite Canvas holds **nodes** (text, title, comment, image, video, audio…)
-and **edges** between them. An edge into a media node makes the source one of
-its **references**, numbered per kind in edge order: `@image1`, `@image2`,
-`@video1`. A media node is either a **display** node (shows an existing asset)
-or a **generate** node (prompt + model + settings; generating fills in its
-asset).
+An Infinite Canvas holds **nodes** (text, title, comment, image, video, audio,
+dataset…) and **edges** between them. An edge into a media node makes the
+source one of its **references**, numbered per kind in edge order: `@image1`,
+`@image2`, `@video1`. A media node is either a **display** node (shows an
+existing asset) or a **generate** node (prompt + model + settings; generating
+fills in its asset). A **dataset** node is a card bound to a workspace dataset
+(`canvas add dataset --dataset <fsnodeId>`) — good for showing a character
+or scene next to its sheets, but `canvas gen` cannot take it as a reference:
+reference the image display node that shows the asset instead.
+
+A workspace's InfiniteCanvas app can hold several canvases (`wji canvas list`);
+`wji canvas create <name>` adds an empty one — e.g. one canvas per episode or
+per character set.
 
 **The link.** The user opens a canvas in the browser and presses the link
 button in its top bar. That stores the open workspace, canvas and **the nodes
@@ -286,8 +335,11 @@ wji canvas nodes                      # every node; * marks generate nodes
 wji canvas get <nodeId>               # full detail incl. references
 wji asset download <assetId…> -o <dir>   # then look at the images yourself
 
+wji canvas create E01 -w <workspaceId>  # new empty canvas; then --canvas <id>
 wji canvas add video --from <imgNode> <imgNode> -m <model> -r 16:9 -d 8 -p "@image1 … @image2 …"
 wji canvas add text -t "shot list…" --at 0,600
+wji canvas add image --asset <assetId> -n "Ada sheet"     # display node for an existing asset
+wji canvas add dataset --dataset <fsnodeId>                # card bound to a workspace dataset
 wji canvas set <nodeId> -p "new prompt"        # merges: other settings stay
 wji canvas set <nodeId> -m <model> --resolution 720p --set seed=42
 wji canvas connect <from> <to>  /  wji canvas disconnect <from> <to>
@@ -377,14 +429,37 @@ wji org list && wji org use <orgId>
      anything you find afterwards — new targets need a new question.
 - **Overwrites don't prompt at all.** `fs set --content`, `--images` and
   `--tags`, and the update commands' tag options, replace the whole value.
-  Read the current value first, and check with the user before replacing
-  anything they did not ask to change.
-- **Generation costs credits.** Run `wji gen cost` first for anything large
-  (high `-n`, long video), show the user the number, and get agreement before
-  submitting a batch. `wji canvas gen` prints its exact cost and refuses
-  without `--yes`: run it once without `--yes` to get the number, tell the
-  user, and pass `--yes` only after they agree. Creating or editing a generate
-  node (`canvas add` / `canvas set`) costs nothing.
+  Prefer the merging forms (`--merge`, `--add-images`, `fs describe`); when
+  you must replace, read the current value first and check with the user
+  before replacing anything they did not ask to change.
+- **Generation costs credits — one image just runs; video and batches ask
+  first.** This is the user's standing policy. Follow it without asking them
+  to restate it:
+
+  | About to run | Do this |
+  | --- | --- |
+  | **One image** — `gen image` with `-n 1`, or `canvas gen` on an image node | **Go ahead.** Pass `--yes`, then report the `credits` line from the result. |
+  | **Any video or audio** | **Ask first.** Get the number, tell the user, wait for a yes. |
+  | **More than one generation in one step** — `-n 2` or higher, several nodes, a storyboard fan-out, an A×B matrix | **Ask first, with the total** — not the per-item price. |
+
+  Splitting a batch does not make it single: what needs approval is the total
+  you are about to spend in this step, however many commands it takes.
+
+  To get the number before asking, both of these are free: `wji gen cost -t
+  video -m <model> -d 8`, or run `wji canvas gen <nodeId>` *without* `--yes` —
+  it refuses to run and the error names the exact credits.
+
+  **`-auto` in the user's message overrides the table.** Generate everything
+  that request needs without asking — video and batches included — and report
+  the total actually charged when you are done. It covers that request and the
+  follow-ups continuing it; when the user moves to a different task, the table
+  above applies again. `-auto` never waives the confirmations for *destructive*
+  commands above, only the spending ones.
+
+  Creating or editing a generate node (`canvas add` / `canvas set`) costs
+  nothing, and neither does `gen cost`. Actual spend is in the result's
+  `credits` field (`history.chargedCredits`), so quote that rather than the
+  estimate once a job has finished.
 - **Never invent ids.** Look up workspace, node, asset and model ids with the
   list commands; ids are Mongo ObjectIds, not names.
 - **Stay inside the generation queue.** See *Limits* above — batch to the cap

package/skill/wji/reference/canvas-recipes.md

@@ -110,6 +110,18 @@ its defaults; check with `wji canvas get <node>` and tell the user what changed.
 
 > "Go ahead and generate it."
 
+**An image node just runs** (see the spending policy in SKILL.md *Rules*):
+
+```bash
+wji canvas gen <node> --yes --wait
+```
+
+Report the `credits` line from the result so the user sees what it actually
+cost.
+
+**A video or audio node needs a yes first** — so does any batch of nodes, and
+`-auto` in the user's message waives both:
+
 ```bash
 wji canvas gen <node>                       # prints the cost and refuses (no terminal)
 ```
@@ -147,8 +159,10 @@ Never resubmit a node whose status is `generating` — that charges twice.
    wji canvas add video -n "Shot 2" --from <char1> <char2> -m <model> -r 16:9 -d 5 -p "…shot 2…"
    ```
 
-4. Total the cost (`wji canvas gen <node>` for each, without `--yes`) before
-   offering to generate them all.
+4. Total the cost (`wji canvas gen <node>` for each, without `--yes`) and get a
+   yes on that total before generating any of them. A fan-out is a batch, so
+   this applies even when every node is an image — unless the request carried
+   `-auto`, in which case generate them all and report the total charged.
 
 ## 6. Fix which image is `@image1`
 

package/skill/wji/reference/commands.md

@@ -67,7 +67,7 @@ switch endpoint.
 | `ws list [-k keyword] [-s all\|me\|shared\|favorite] [--page] [--limit]` | `GET /workspace/search` — `--limit` max 100, `-1` returns at most 500 |
 | `ws get [id]` | `GET /workspace/list/:id` |
 | `ws use <id>` | stores the default workspace locally |
-| `ws create <name> [-d] [-r ratio] [-l lang] [-t type] [-a app...]` | `POST /workspace/create` |
+| `ws create <name> [-d] [-r ratio] [-l lang] [-t type] [-a app...] [--no-apps]` | `POST /workspace/create` — without `-a` the workspace gets the default template `dataset datasetimagegeneration canvas`; `--no-apps` creates it empty (the API itself adds nothing) |
 | `ws update [id] [-n] [-d] [-r] [-l] [--set]` | `PUT /workspace/list/:id` |
 | `ws rm <id> [-y]` | `DELETE /workspace/list/:id` (owner only) |
 | `ws favorite <id> [--off]` | `PUT /workspace/list/:id/favorite` |
@@ -99,7 +99,7 @@ Restriction from the backend: `Dataset`, `Draw`, `DatasetImageGeneration` and
 | `fs path <id>` | `GET /fsnode/list/:id/path` |
 | `fs mkdir <parent> <name> [--nickname] [--content]` | `POST /fsnode/create` type=folder |
 | `fs touch <parent> <name> [--mimetype] [--asset] [--content]` | `POST /fsnode/create` type=file |
-| `fs set <id> [-n] [--nickname] [--content] [--tags] [--images] [--icon] [--asset] [--sort] [--set]` | `PATCH /fsnode/list/:id` |
+| `fs set <id> [-n] [--nickname] [--content] [--tags] [--images] [--add-images] [--icon] [--asset] [--sort] [--set] [--merge]` | `PATCH /fsnode/list/:id` — `--merge key=value` deep-merges into `content` (reads first; `@file` values), `--add-images` appends to `images`; `--content`, `--images`, `--set content.*` replace |
 | `fs describe <id> <text>` | merges `content.description` |
 | `fs rm <id> [-y]` | `DELETE /fsnode/list/:id` (soft delete, whole subtree) |
 | `fs sort <parent> <ids...>` | `PATCH /fsnode/list/:id/children/sort` |
@@ -142,6 +142,11 @@ Semantic dataset folders created with the Dataset app: `story`, `character`,
 
 Asset states: `0` pending, `1` ready, `-1` cancelled.
 
+Model parameters worth knowing (`--set`, see `wji models get`):
+`gpt-image-2.5-*` `background=transparent` returns a PNG with alpha;
+`bytedance-seedream-5-pro` `layer_decomposition=true` splits one reference
+image into separate PNG layer assets (exactly 1 reference, `size=1K|2K`).
+
 Uploads of `.html`, `.xhtml`, `.svg`, `.js` and `.xml` are stored as
 `application/octet-stream` with `Content-Disposition: attachment`.
 
@@ -156,10 +161,11 @@ updates live.
 | `canvas status` (`link`) | `GET /canvas-link`, then the selected nodes read fresh from the canvas |
 | `canvas unlink` | `DELETE /canvas-link`; the tab turns its button off at its next heartbeat (≤ 60s) |
 | `canvas list [-w]` | canvases under each InfiniteCanvas app: `GET /workspace/list/:id/fs/:appId` → `workspace-v2/canvases` children |
+| `canvas create <name> [-w] [--app]` | `POST /fsnode/create` a `workspace-v2/canvas` folder under that `canvases` folder with the web's initial content (`{data:{viewport, backgroundMode:'dots'}, metadata:{}}`) |
 | `canvas nodes [-c] [-k kind]` | `GET /fsnode/list/:canvasId/children?limit=-1` + `POST /assets/check-status` |
 | `canvas get <nodeId> [-c]` | same load; one node with references (`@image1 ← id`) and frame slots |
 | `canvas edges [-c] [--node]` | the `canvas/edge` children |
-| `canvas add <kind> [-c] [-n] [-t\|--text-file] [--asset] [-p\|--prompt-file] [-m] [-r] [--resolution] [-d] [--set] [--from ids…] [--at x,y]` | `POST /fsnode/create` (`canvas/node/<kind>`), then one `canvas/edge` per `--from`. Kinds: text, title, comment, image, video, audio |
+| `canvas add <kind> [-c] [-n] [-t\|--text-file] [--asset] [--dataset] [-p\|--prompt-file] [-m] [-r] [--resolution] [-d] [--set] [--from ids…] [--at x,y]` | `POST /fsnode/create` (`canvas/node/<kind>`), then one `canvas/edge` per `--from`. Kinds: text, title, comment, image, video, audio, dataset. `add dataset --dataset <fsnodeId>` writes `content {datasetId, datasetName, datasetType, datasetParentName, description}` from the dataset node (must be `workspace/dataset`); it takes no `--from` |
 | `canvas set <nodeId> [-c] [-n] [-t] [--move x,y] [-p] [-m] [-r] [--resolution] [-d] [--set]` | read → merge → `PATCH /fsnode/list/:id` |
 | `canvas connect <from> <to> [-c]` | `POST /fsnode/create` (`canvas/edge`); a first/last-frame video model gets `videoFrameSlot` start, then end |
 | `canvas disconnect <from> <to> [-c]` | `DELETE /fsnode/list/:edgeId` |
@@ -200,7 +206,7 @@ viewport, url}` on toggle (`takeover: true`), on selection change and every
 
 Shared flags: `-m/--model` (required), `-p/--prompt`, `-n/--n`, `-w/--workspace`,
 `--fsnode`, `--scope`, `--scope-id`, `-r/--ratio`, `--tags`, `--values`,
-`--set`, `--no-history`, `--wait`, `--timeout` (seconds, default 900),
+`--set`, `--wait`, `--timeout` (seconds, default 900),
 `--interval` (seconds, default 5).
 
 | Command | Extra flags | API |
@@ -210,8 +216,11 @@ Shared flags: `-m/--model` (required), `-p/--prompt`, `-n/--n`, `-w/--workspace`
 | `gen audio` | `-d/--duration`, `--ref-audio` | `POST /ai/assets/history/audio/generations` |
 | `gen cost -t <type> -m <model>` | `-n`, `-p`, `-d`, `-r`, `--refs`, `--values` | `POST /ai/assets/preComputeCost` |
 
-`--no-history` calls `/ai/assets/<type>/generations`, which returns assets
-directly and cannot be polled by history id.
+Every generation goes through the history endpoint — there is no raw mode. The
+backend also exposes `/ai/assets/<type>/generations`, which skips the history
+record, but the CLI never calls it: without a history there is no id to poll,
+and `fsnode`, `scope`, `scopeId` and `tags` are silently dropped (they are
+written only inside `if (toHistory)`).
 
 Admission limits, per user and API key (changing IP does not reset them):