@wji.ai/cli 0.1.0

package/skill/wji/SKILL.md

@@ -0,0 +1,398 @@
+---
+name: wji
+description: Drive the WJI AI platform from the terminal with the `wji` CLI — sign in, manage workspaces and the fsnode/dataset tree, upload assets, generate images/video/audio and poll the results, and work on Infinite Canvas nodes (read the user's selected nodes, create generate nodes, connect references), and manage models, agents, prompt presets and your profile. Use whenever a task mentions WJI, wji-backend, a WJI workspace, canvas, fsnode, dataset node, or asks to generate media on WJI.
+---
+
+# WJI CLI
+
+`wji` is a thin, scriptable client over the WJI API. Every command accepts
+`--json`, so prefer `--json` piped through `jq` when you need to read a value,
+and the human table output when you are showing the user a result.
+
+## Before anything else
+
+```bash
+wji auth whoami --json      # confirms endpoint, credential, org context
+```
+
+- `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
+  PATH). `npm link` fails with `EACCES` when the global prefix is root-owned;
+  don't reach for `sudo`.
+
+- Exit code `77` means the credential is missing or rejected. Tell the user to
+  run `wji auth login` (interactive) or export `WJI_API_KEY`. **Never ask the
+  user to paste a password into the conversation and never type one into
+  `--password` yourself** — `wji auth login` prompts without echoing.
+- `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.
+- **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
+  is ever replayed. The CLI serializes refreshes across processes, but a key
+  never refreshes at all. A JWT profile that keeps returning 401 needs one
+  `wji auth login`.
+
+## The mental model
+
+```
+organization (X-Org-Id header, optional)
+└── workspace                       wji ws
+    ├── apps  (Dataset, Files, InfiniteCanvas, …)
+    └── fsnode tree                 wji fs
+        └── dataset nodes           wji dataset
+generation ─> history entry ─> assets    wji gen / wji history / wji asset
+```
+
+- A **workspace** scopes billing, quota and members.
+- The **fsnode tree** is the file system inside a workspace: folders and files,
+  each with a free-form `content` JSON object.
+- A **dataset node** is an fsnode with mimetype `workspace/dataset` whose
+  `content` carries `{ type, description }` — these are the "ideas"
+  (outline, screenplay, character, location, prop, outfit, scene, shot, other)
+  that feed generation. See *Character datasets* below.
+- **Generation is asynchronous.** Submitting returns a history entry; the
+  assets inside it start `pending` and become `ready`.
+
+## Set a working context first
+
+Most commands take `--workspace`, but setting a default is less error-prone:
+
+```bash
+wji ws list
+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`.
+
+## Reading and editing the tree
+
+```bash
+wji ws fs                                  # whole workspace tree
+wji ws fs --app <appId>                    # one app's tree
+wji fs tree <nodeId> --depth 2
+wji fs ls <folderId>
+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 --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.
+
+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
+`wji preset update` already bypass that cache; if you hand-roll a
+read-merge-write with `--json`, expect the read to lag briefly.
+
+## Generating media
+
+Always pick the model from the live list rather than guessing a name:
+
+```bash
+wji models list --feature image
+wji models get <model>            # ratios, max n, reference support, --set params
+wji gen cost -t image -m <model> -n 4
+```
+
+**Pass the value in the MODEL column to `-m`** — that is the model's `nickname`,
+which is unique. The `name` column is shown only when it differs, and names do
+collide across providers (two different `seedance-2.0` entries exist), so `-m`
+with a bare name resolves to whichever the server picks first.
+
+Then submit. Add `--wait` when the user is waiting on the result:
+
+```bash
+wji gen image -m <modelName> -p "a rainy alley at dusk" -n 4 --ratio 16:9 --wait
+wji gen video -m <modelName> -p "slow pan" -d 5 --start-image <assetId> --wait --timeout 1200
+wji gen audio -m <modelName> -p "rain on a tin roof" --wait
+```
+
+- 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.
+- 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
+  resubmitting, which would charge credits twice.
+- `wji models get` prints the model's own parameter list with defaults and
+  allowed values. Only `--set` keys listed there take effect; anything else is
+  ignored silently.
+- Billing inputs are server-owned and stripped from `--set` / `--values`:
+  `num_images`, `referenceImageCount`, `referenceVideoTotalDuration`,
+  `output_resolution` and every `*Info` field. Use `-n` for the count and the
+  real reference flags (`--ref`, `--ref-video`, …) for references.
+
+### Choosing a model (house guidance)
+
+Use this to pick a model when the user hasn't named one, and to explain the
+trade-off when they have. Exact nicknames differ between environments — always
+confirm with `wji models list --feature <image|video>` and `wji models get`.
+
+**Images:** prefer **GPT Image 2.5** (`gpt-image-2.5-sunburst` for new images
+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**.
+
+**Video — reference models over first/last-frame models.** A family usually
+has both:
+
+| Kind | Examples | Takes |
+| --- | --- | --- |
+| **Ref** (preferred) | `seedance-2.5-ref`, `seedance-2.0-ref`, `seedance-2.0-fast-ref`, `Wan 3.0 Ref`, `Wan 3.0 Prime Ref`, `minimax-h3-ref`, `minimax-h3-max-ref` | reference **images, videos and audio** together (e.g. a character sheet + a motion clip + a voice line) |
+| First/last frame | `seedance-2.5`, `seedance-2.0`, `Wan 3.0`, `minimax-h3-i2v`, `minimax-h3-max-i2v` | only a start and/or end image |
+
+Use a first/last-frame model only when the user explicitly wants a shot to
+start or end on an exact frame. With a Ref model, pass images with `--ref`,
+videos with `--ref-video` and audio with `--ref-audio` (or connect them on the
+canvas); `wji models get` shows each model's caps (e.g. Wan 3.0 Ref: 10 images,
+video/audio ≤ 15 s total).
+
+**Video trade-offs** (best first):
+
+| | Ranking |
+| --- | --- |
+| **Quality** | Seedance 2.5 › Seedance 2.0 ≈ Wan 3.0 › MiniMax H3 ≈ Seedance 2.0 Fast › MiniMax H3 Max |
+| **Speed** (fastest first) | MiniMax H3 Max › Seedance 2.0 Fast › Wan 3.0 Prime › Seedance 2.0 ≈ Wan 3.0 › Seedance 2.5 |
+| **Price** (cheapest first) | MiniMax H3 Max › Seedance 2.0 Fast › Wan 3.0 Prime › Seedance 2.0 ≈ Wan 3.0 › Seedance 2.5 |
+
+So: **Seedance 2.5** for final, hero shots; **Seedance 2.0 / Wan 3.0** as the
+balanced default; **Seedance 2.0 Fast / MiniMax H3 Max** for drafts, tests and
+large batches. The ranking is a guide — quote the real number from
+`wji gen cost` / `wji canvas gen` before spending.
+
+### Limits (per account)
+
+| Limit | Value | When exceeded |
+| --- | --- | --- |
+| Submissions per minute | image 30 · video 10 · audio 20 | HTTP 429 |
+| Queued + running jobs | FREE 3 · VIP 10 · SVIP 25 | HTTP 429 `排隊中的任務已達上限` |
+
+**Never fire more generations at once than the queue allows.** Submit up to the
+cap, wait for jobs to finish (`wji history get <id> --wait`), then submit the
+next batch. A 429 means the request was rejected before anything was charged —
+wait and resubmit; do not retry in a tight loop.
+
+```bash
+wji history list --mode video
+wji history download <historyId> -o ./out
+```
+
+## Character datasets
+
+A character is only reusable across shots when its dataset carries all three:
+
+1. **Headshot** — a clean front-facing portrait on a plain background (sets
+   the face). Make it the dataset's `icon`.
+2. **Character sheet** — full-body front/side/back turnaround plus a few
+   expressions and outfit details, in the same outfit (sets body, clothes and
+   consistency). Generate it from the headshot with GPT Image 2.5 Sunburst.
+3. **Voice** — a short, clean audio sample of the character speaking (sets the
+   voice for Ref video models that take `--ref-audio`). Set it as
+   `primaryAudio`.
+
+All three are assets attached to the dataset node (`images` holds images and
+audio alike). When creating or reviewing a character, check which are missing
+and offer to make them; when generating video of that character, pass the
+headshot and sheet as image references and the voice as an audio reference to
+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>
+```
+
+`--images` replaces the whole list — read the current list first and keep
+what is already there.
+
+## Assets
+
+```bash
+wji asset upload ./ref.png                 # returns an asset id
+wji asset import https://example.com/x.jpg
+wji asset status <id> <id>                 # pending | ready | cancelled
+wji asset download <id> [<id>…] -o ./out   # keeps the file extension, so you can view images
+```
+
+- Uploaded assets attach to the default workspace unless you pass `--workspace`.
+- `asset status` only returns assets you created or that sit in a workspace
+  you belong to; other ids are silently omitted (the CLI warns how many).
+- `asset import` refuses private and internal addresses (`不允許存取該主機`).
+  Some public hosts also block server-side downloads (`無法下載或處理該圖片 URL`)
+  — download the file yourself and `wji asset upload` it instead.
+- `.html`, `.svg` and script uploads are stored as `application/octet-stream`
+  and served as attachments, so they will not render inline.
+
+## Skills
+
+Skills are SKILL.md bundles. **System skills** are built-in and read-only;
+**user skills** are yours to author and attach to agents. Only `.md` files
+persist server-side — scripts belong to system skills.
+
+```bash
+wji skill system                      # built-in skills you can attach
+wji skill push ./my-skill             # zip a local folder (SKILL.md at root) and upload
+wji skill list
+wji skill pull <id> ./my-skill        # write a bundle back to disk to edit it
+wji skill get <id>                    # metadata + file list
+```
+
+Attach skills to an agent and manage its version history:
+
+```bash
+wji agent skill-add <agentId> system:image user:<skillId>
+wji agent skills <agentId>
+wji agent versions <agentId>          # every edit auto-snapshots a version
+wji agent restore <agentId> <versionId>
+```
+
+Skill refs are `system:<key>` or `user:<skillId>` (a bare id means `user:`).
+System keys currently include `image`, `document`, `workspace-dataset`,
+`canvas` and `seedance-25` — confirm with `wji skill system`.
+When authoring, edit a pulled folder and `skill push` it again, or
+`skill update <id> --dir ./my-skill` to replace its files.
+
+Bundle limits: at most 200 markdown files, 2MB per file, 20MB in total and a
+5MB zip; 50 user skills per account. `skill update --dir` sends files in the
+request body, where each file is capped far lower, at **200,000 characters** —
+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).
+
+**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
+they have selected** on their account for 5 minutes (the tab renews it while
+open). Every `wji canvas` command then targets that canvas; pass
+`--canvas <id>` to work on another one (`wji canvas list`).
+
+```bash
+wji canvas status                     # linked canvas + selected nodes (ids, asset URLs, settings)
+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 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 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>
+wji canvas gen <nodeId> --wait                 # costs credits — see Rules
+wji canvas rm <nodeId…>                        # destructive — see Rules
+```
+
+- **Match the CLI to the site the user is on before anything else.** The
+  link is stored on the backend the browser talks to, so the CLI must use the
+  same one. `Cannot GET /canvas-link` (404) means the active profile points at
+  a backend without this feature — typically profile `prod`
+  (`https://api.wji.ai`) while the user linked on `http://localhost:3000`
+  (API `http://localhost:3002`). Check `wji config show`, then tell the user
+  which profile to use (`wji config use <profile>`), or run the commands with
+  `WJI_ENDPOINT=… WJI_API_KEY=…` for that backend. Don't switch their
+  profile silently, and never run canvas commands against production when the
+  link URL is localhost.
+- If `status` says *Not linked*, ask the user to open the canvas and press the
+  link button (and to select the nodes they mean). Don't guess a canvas.
+- The selection is **what the user means by "these" / "the selected images"**.
+  Use those node ids for `--from`; use each node's `assetId` to download and
+  look at the picture before writing a prompt about it.
+- Prompts are literal: `-p "@image1 …"` is text, not a file. Use
+  `--prompt-file` for a file and `-p -` for stdin.
+- Pick the model from `wji models list --feature video` and read
+  `wji models get <model>` for its ratios, duration range and `--set` keys.
+  `add`/`set` validate against it, fill the model's defaults, and turn
+  auto-duration off when you pass `-d`.
+- **A model the user names may not accept references.** Check the REFS column
+  of `wji models list`: a family often has a text-only model and a `Ref`
+  variant (`Wan 3.0` has none, `Wan 3.0 Ref` takes up to 10). If the request
+  builds on selected images, use the variant with references and say so —
+  otherwise the selection is silently ignored and the person or object in the
+  video will not match.
+- Model nicknames can contain spaces (`"Wan 3.0 Ref"`) — quote them.
+  Parameter values are case-sensitive and differ per model (`480P` for Wan,
+  `480p` for Seedance); copy them from `wji models get`.
+- Defaults you did not ask about still shape the result: the ratio falls back
+  to the workspace's (often 16:9 — ask or pick 9:16 for a portrait-style clip),
+  `audio` may default on, and **auto-duration** lets the model choose the
+  length. With auto-duration the cost `canvas gen` shows is an estimate for
+  the node's configured seconds; the final charge follows the real length.
+  Mention these when you report the node, and pass `-d` if the user needs a
+  fixed length or a fixed price.
+- Take new ids from the command's own output (`wji --json canvas add … | jq
+  -r .id`), not by searching names — names repeat on a canvas. In zsh a
+  variable holding several ids is not word-split; pass the ids literally.
+- Changes show up live in the user's open canvas; there's no need to ask them
+  to reload.
+- `canvas gen` sends exactly what the canvas's own Generate button sends
+  (references in order, text-node references prefixed to the prompt). Nodes
+  referencing dataset, bundle, table or YouTube nodes must be generated from
+  the browser.
+
+See `reference/canvas-recipes.md` for end-to-end examples.
+
+## Everything else
+
+```bash
+wji preset list -k "hero"        # usable presets; also `mine`, `public`, `workspace`
+wji preset get <id> --json | jq -r .prompt
+wji agent list                   # marketplace; `wji agent mine` for yours
+wji profile show
+wji profile wallet               # credit balance before an expensive batch
+wji org list && wji org use <orgId>
+```
+
+## Rules
+
+- **Confirm before destroying — in the conversation, one target at a time.**
+  These commands delete, revoke or overwrite, and none can be undone from the
+  CLI: `ws rm`, `ws app rm`, `ws member rm`, `fs rm`, `dataset rm`,
+  `asset rm`, `history rm`, `preset rm`, `skill rm`, `skill update --dir`,
+  `agent rm`, `auth key rm`, `auth key revoke`, `config rm`, `canvas rm`.
+  They prompt `[y/N]` in a terminal, but when you run them there is no
+  terminal, so they refuse unless you pass `--yes`. **The user's reply in the
+  chat is the only confirmation there is.** Before running one:
+  1. Look the target up and tell the user exactly what will go — name and id,
+     plus what goes with it: a workspace's apps and files, a folder's whole
+     subtree, the files `skill update --dir` replaces, anything still using an
+     API key, the credentials stored in a profile, the connections a canvas
+     node takes with it.
+  2. Wait for an explicit yes to *those* targets. A broad instruction such as
+     "clean up" or "delete the old ones" is not approval: list what you found
+     and ask.
+  3. Only then pass `--yes`. The approval covers the targets you listed, not
+     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.
+- **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
+  and wait for completions rather than retrying 429s.
+- **Lists are paginated.** `--limit` is capped at 100; `--limit -1` returns at
+  most 500 on most endpoints. Page with `--page` instead of assuming you got
+  everything.
+- **Report failures honestly.** A failed generation surfaces as a non-zero exit
+  with the provider's message — pass it on rather than retrying silently.
+
+See `reference/commands.md` for the full command and flag inventory.

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

@@ -0,0 +1,179 @@
+# Canvas recipes
+
+Worked examples for `wji canvas`. Each starts from the same place: the user has
+the canvas open in the browser, has pressed the **link** button in its top bar,
+and has selected the nodes they are talking about.
+
+```bash
+wji canvas status          # confirms the link and lists the selected nodes
+```
+
+If it says *Not linked*, ask the user to press the link button (and select the
+nodes) instead of guessing. If it fails with `Cannot GET /canvas-link`, the CLI
+profile points at a different backend than the browser (e.g. `prod` while the
+link URL is `localhost:3000`) — fix the profile first (see SKILL.md, Canvas).
+The link lasts 5 minutes after the tab stops renewing it, so re-check `status`
+if the user comes back later.
+
+All ids below are placeholders — always take them from `status`, `nodes` or
+`get`.
+
+---
+
+## 1. Selected images → suggest a video prompt → create the video node
+
+> "Use the images I selected to make a video node. Suggest a prompt first."
+
+1. Read the selection and keep the image nodes, in the order the user
+   selected them (that becomes `@image1`, `@image2`):
+
+   ```bash
+   wji canvas status --json | jq '.selected[] | select(.kind=="image") | {id, name, assetId}'
+   ```
+
+2. Look at the pictures before writing about them:
+
+   ```bash
+   wji asset download <assetId1> <assetId2> -o /tmp/canvas-refs
+   ```
+
+   Open the downloaded files and describe what is actually there — subject,
+   setting, light, mood.
+
+3. Pick a model that takes image references and read its limits:
+
+   ```bash
+   wji models list --feature video -k <family>   # REFS column must be non-empty
+   wji models get "<model>"        # ratios, duration range, max references, --set keys (exact case)
+   ```
+
+   If the user asked for a model by family name ("wan 3.0", "seedance"), choose
+   the member that accepts references (`Wan 3.0 Ref`, `seedance-2.0-fast-ref`)
+   and tell them why.
+
+4. Settle the settings the user didn't mention: ratio (workspace default vs.
+   9:16 for a portrait subject), fixed duration or auto, audio. Then propose
+   2–3 prompts in the chat. Refer to the images as `@image1`,
+   `@image2`, matching the order you will connect them. Mention the model,
+   ratio and duration you would use. Wait for the user to pick or edit one.
+
+5. Create the node. Nothing is charged yet:
+
+   ```bash
+   wji canvas add video -n "Lake reunion" \
+     --from <imageNode1> <imageNode2> \
+     -m <model> -r 16:9 -d 8 --resolution 720p \
+     -p "@image1 paddles a canoe across a still turquoise lake at dawn; as she reaches the shore, @image2 trots down the forest path to greet her. Soft morning light, reflections, shallow depth of field."
+   ```
+
+   The node appears next to the images in the user's canvas, wired to both,
+   with the prompt and settings filled in. Tell the user its name and that it is
+   ready to generate from the canvas or from here (recipe 4).
+
+## 2. Write or rewrite the prompt of an existing generate node
+
+> "This video node has two references wired in — write a better prompt for it."
+
+```bash
+wji canvas get <videoNode>                  # prompt, model, settings, references with labels
+wji canvas get <referenceNode>              # for each reference: kind, assetId, text
+wji asset download <assetId…> -o /tmp/canvas-refs
+```
+
+Draft the prompt against the **labels `get` printed** (`@image1 ← <nodeId>`),
+not against the order the user happened to mention things. Then:
+
+```bash
+wji canvas set <videoNode> -p "…"           # only the prompt changes; model and settings stay
+```
+
+Text nodes connected into a generate node are sent ahead of the prompt as
+`[node name]` + text. Don't repeat their content in the prompt.
+
+## 3. Change generation settings
+
+> "Make it vertical, 10 seconds, 720p, and fix the seed."
+
+```bash
+wji models get <model>                      # check 9:16 exists, duration range, seed key
+wji canvas set <node> -r 9:16 -d 10 --resolution 720p --set seed=1234
+```
+
+`set` rejects values the model does not support and names the valid ones. It
+merges `--set` into the existing parameters. Passing `-d` switches the
+model's auto-duration off.
+
+To switch model, pass `-m`. Settings the new model does not support fall back to
+its defaults; check with `wji canvas get <node>` and tell the user what changed.
+
+## 4. Generate directly
+
+> "Go ahead and generate it."
+
+```bash
+wji canvas gen <node>                       # prints the cost and refuses (no terminal)
+```
+
+Tell the user the cost from that message. With auto-duration it is an
+estimate for the node's configured seconds; say so, or set `-d` first for a
+fixed price. Only after they agree:
+
+```bash
+wji canvas gen <node> --yes --wait
+```
+
+The result becomes the node's asset, so the user sees it on the canvas. Video
+can take minutes: with a long wait, prefer submitting without `--wait` and
+checking `wji canvas get <node>` (status `generating` → `done`/`failed`) later.
+Never resubmit a node whose status is `generating` — that charges twice.
+
+## 5. Storyboard fan-out
+
+> "Here are my two character images. Make one video node per shot for this
+> 4-shot scene."
+
+1. Write the shot list in the chat and agree on it.
+2. Optionally drop the script on the canvas:
+
+   ```bash
+   wji canvas add text -n "Scene 3 shots" -t - < shots.txt
+   ```
+
+3. One generate node per shot, all wired to the same character images. Each
+   node is placed beside the references and below the previous one:
+
+   ```bash
+   wji canvas add video -n "Shot 1" --from <char1> <char2> -m <model> -r 16:9 -d 5 -p "…shot 1…"
+   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.
+
+## 6. Fix which image is `@image1`
+
+References are numbered in connection order. To swap `@image1` and `@image2`,
+reconnect the first one so it moves to the end:
+
+```bash
+wji canvas get <node>                       # @image1 ← A, @image2 ← B
+wji canvas disconnect <A> <node>
+wji canvas connect <A> <node>               # now @image1 ← B, @image2 ← A
+wji canvas set <node> -p "…"                # update the prompt to the new labels
+```
+
+## 7. Image variation from a selected image
+
+> "Make a watercolor version of the selected photo."
+
+```bash
+wji canvas add image -n "Watercolor" --from <photoNode> -m <imageModel> -r 16:9 \
+  -p "Turn @image1 into a soft watercolor illustration, keep the composition"
+wji canvas gen <newNode>                    # cost → user agrees → --yes --wait
+```
+
+## Cleaning up
+
+`wji canvas rm` deletes nodes and every connection touching them. It is on the
+confirm list: name the nodes (and how many connections go with them) in the
+chat, wait for a yes, then pass `--yes`.