@nodetool-ai/agents 0.8.4-a24.3 → 0.8.4

package/dist/_skills/api-media/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: api-media
+description: "Call nodetool.media or nodetool.generations from a code action: generate or edit images, video, speech and music with a picked model, transcribe and embed, judge images with a vision model, read a video, run ffmpeg or ffprobe, download a video, and read the status and cost of a generation. Load before the first call into these namespaces."
+---
+
+# nodetool.media and nodetool.generations
+
+`nodetool.media` makes one result with one picked model and saves it as an
+asset. No workflow is needed. `nodetool.generations` is the record of every
+media generation: status, cost, and the assets it made. The model comes from
+`nodetool.models.pick` (see `api-models`). How to word a prompt for one model
+line is the `*-prompting` skill that `find_model` names in `prompting_skill`.
+
+## Generation calls
+
+Each call takes `model` as a `pick`/`find` result, `{provider, model_id}`, or
+a `"provider/model_id"` string.
+
+| Call | Options | Capability to pick |
+| :--- | :--- | :--- |
+| `generateImage(prompt, model, opts)` | `width`, `height`, `quality`, `negative_prompt`, `output_file`, `background` | `text_to_image` |
+| `editImage(inputFile, prompt, model, opts)` | `reference_files`, `strength`, `target_width`, `target_height`, `negative_prompt`, `output_file`, `background` | `image_to_image` |
+| `generateVideo(prompt, model, opts)` | `duration_seconds`, `aspect_ratio`, `resolution`, `num_frames`, `negative_prompt`, `output_file`, `background` | `text_to_video` |
+| `animateImage(inputFile, model, opts)` | `prompt`, `duration_seconds`, `aspect_ratio`, `resolution`, `num_frames`, `output_file`, `background` | `image_to_video` |
+| `videoFromReferences(referenceFiles, model, opts)` | `prompt`, `use_reference_video_audio`, `negative_prompt`, `num_frames`, `duration_seconds`, `aspect_ratio`, `resolution`, `output_file`, `background` | `reference_to_video` |
+| `speak(text, model, opts)` | `voice`, `speed`, `output_file`, `background` | `text_to_speech` |
+| `generateMusic(prompt, model, opts)` | `lyrics`, `duration_seconds`, `output_file`, `background` | `text_to_music` |
+| `transcribe(inputFile, model, opts)` | `language`, `prompt` | `automatic_speech_recognition` |
+| `embed(text, model, opts)` | `dimensions`. `text` is a string or an array. | `generate_embedding` |
+
+A generation answers with `asset_id`, `asset_uri` (`asset://…`),
+`generation_id`, `mime_type` and `bytes`, plus `path` when you passed
+`output_file`. An input file (`inputFile`, `reference_files`) is an
+`asset://` URI or a workspace path.
+
+- `editImage` is the call for "make it like this". Pass the attached image or
+  an approved earlier result as `inputFile`, and further images to match in
+  `reference_files`.
+- `videoFromReferences` is for a shot that more than one reference defines: a
+  character plus a garment, a product plus a location. The prompt then says
+  the action and the camera, not the subjects.
+- Models honour `duration_seconds` loosely. Measure the result with
+  `ffprobe` before you cut to it.
+- To put words on a picture, draw them yourself with `createCanvas` and
+  `fillText`, or with `renderText` from
+  `@nodetool-ai/sandbox-flow/lib.image.draw`.
+
+### Background generations
+
+`background` is the async flag on every generation call, not a transparent
+background. `background: true` returns at once with
+`{generation_id, status: "running", background: true}`. Collect the result
+with `nodetool.generations.wait(receipt)`. A run can have 16 open at most.
+Each one is billed, so confirm the count and the cost with the user before
+you fan out paid video. Start several, then wait for all of them in the same
+action:
+
+```js
+const model = await nodetool.models.pick("text_to_video");
+const receipts = await Promise.all(prompts.map((p) =>
+  nodetool.media.generateVideo(p, model, { background: true })));
+const done = await Promise.all(receipts.map((r) =>
+  nodetool.generations.wait(r, { timeout_seconds: 480 })));
+```
+
+A code action stops after 600 s. Keep each wait under that budget. A wait
+that times out answers the current record, so wait again in the next action
+for any that are still `running`.
+
+## Handles and saving
+
+`image.*`, `audio.*` and `video.*` (guest globals, no `nodetool.` prefix) take
+a generation result, its `asset_uri` or an asset id, and answer run-local
+handles. `video.addAudio(videoHandle, audioHandle)` combines media, for
+example. Save a finished handle with `nodetool.media.toImage(handle)`,
+`toAudio(handle)` or `toVideo(handle)` before the action ends. A handle is dead
+in the next action. Do not pull bytes into the guest.
+
+Hold each result in a local variable and feed it straight into the next call.
+Record the uris a later action or turn will need with `nodetool.memory.save`,
+and never re-run generation for something already saved.
+
+## Judging
+
+The judge is a chat model that reads images (`pick("generate_message")` on a
+vision model), not the model that made the picture.
+
+| Call | Answers |
+| :--- | :--- |
+| `critique(image, brief, visionModel, {taste_profile})` | A pass/revise verdict and concrete defects with locations and fixes. Feed the fixes into the next prompt. When it names no defect, make fresh variations. |
+| `compare(images, brief, visionModel, {taste_profile})` | The winner of 2–8 candidates by a pairwise knockout, each match judged twice with the order swapped, plus every verdict |
+| `scoreAdherence(image, brief, visionModel, {questions})` | Yes/no answers to up to 12 checks made from the brief, and the fraction that passed |
+| `understandVideo(video, prompt, videoModel, {max_tokens})` | `{text, truncated}`. Gemini reads the whole clip with audio. Other models get still frames with no audio. A `truncated` answer is half an answer: raise `max_tokens` or use a model that does not reason. |
+
+## Host binaries
+
+| Call | Does |
+| :--- | :--- |
+| `ffmpeg(args, {inputs, output_file, timeout_seconds})` | Runs ffmpeg in the workspace with no shell. `args` is the argv after the binary. Paths are workspace-relative, and URLs are refused. `inputs` stages assets first as `{"a.mp4": "asset://…"}` (8 files at most). `output_file` is saved as an asset. The default timeout is 180 s, the maximum 600 s. |
+| `ffprobe(path, {inputs, timeout_seconds})` | Reads the format and streams. `path` may be an `asset://` URI. The answer has a `summary` with `duration_seconds`, `width`, `height` and `has_audio` as real numbers and booleans. The default timeout is 30 s, the maximum 120 s. |
+| `downloadVideo(url, outputFile, {format, timeout_seconds})` | Downloads a public video with yt-dlp, up to 2 GiB. The default timeout is 300 s. |
+
+```js
+// Concatenate two assets in one call.
+await nodetool.media.ffmpeg(
+  ["-i", "a.mp4", "-i", "b.mp4", "-filter_complex",
+   "[0:v][0:a][1:v][1:a]concat=n=2:v=1:a=1[v][a]", "-map", "[v]", "-map", "[a]",
+   "out.mp4"],
+  { inputs: { "a.mp4": uriA, "b.mp4": uriB }, output_file: "out.mp4" }
+);
+```
+
+## nodetool.generations
+
+Every generation result carries `generation_id`. Read the cost with `get`
+instead of guessing it.
+
+| Call | Answers |
+| :--- | :--- |
+| `list({status, provider, capability, thread_id, job_id, since, limit, start_key})` | Generations, newest first, with status, cost, errors and assets |
+| `get(idOrResult)` | One generation in full: request parameters, cost and how it was priced, the provider request id, the assets |
+| `wait(idOrResult, {timeout_seconds})` | Waits for a background generation. The default is 300 s. A timeout answers the current record; call again to keep waiting. |
+| `cancel(idOrResult)` | Stops a running generation. It answers `cancelled: false` when the generation already settled. |
+| `reconcile(idOrResult)` | Asks the provider what it billed and replaces the estimate |
+| `fromProvider(provider, {model, status, since, until, limit, cursor})` | The provider's own history, from any machine. `fal_ai` answers. |
+| `getFromProvider(provider, requestId, {model})` | One provider-side generation, with the output urls it still hosts. This recovers a lost asset. |
+
+Statuses are `pending`, `running`, `recovering`, `completed`, `failed`,
+`cancelled`, `needs_attention` and `interrupted`. `completed` means the
+output is durable. A failed, cancelled or interrupted generation can still be
+billed.

package/dist/_skills/api-memory/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: api-memory
+description: "Call nodetool.memory, nodetool.shared or nodetool.threads from a code action: save and recall durable notes and resources across conversations, pass results between steps and sub-agents in one run, and read past chat threads. Load before the first call into these namespaces."
+---
+
+# nodetool.memory, nodetool.shared, nodetool.threads
+
+Nothing carries over between code actions except what a tool saved. These
+three namespaces are where state lives, at three lifetimes:
+
+| Namespace | Lifetime | Use it for |
+| :--- | :--- | :--- |
+| `nodetool.memory` | Every conversation, until deleted | Facts, decisions, preferences, and the assets and documents you made |
+| `nodetool.shared` | This run only | Handing results between steps, tasks and sub-agents |
+| `nodetool.threads` | Read-only chat history | "What did we decide last time?" |
+
+## nodetool.memory
+
+| Call | Does |
+| :--- | :--- |
+| `save(content, {title, kind, resources})` | Saves a note. |
+| `search(query, {limit, thread, kinds})` | Finds notes by keyword. Every word must appear in the title or the content, so fewer words find more. `limit` defaults to 25. |
+| `list({limit, thread, kinds})` | Lists notes, newest first. `limit` defaults to 100, max 200. |
+| `update(memoryId, {content, title, kind, resources})` | Changes the fields you pass. `resources` replaces the list. |
+| `remove(memoryId)` | Deletes one note. |
+
+- `kind` is `note` (default), `fact`, `preference`, `decision` or `resource`.
+- `thread` is `"all"` (default) or `"current"`.
+- `resources` is a list of `{type, id, uri?, label?}`. `type` is `asset`,
+  `workflow`, `collection`, `node`, `job`, `timeline`, `script`, `storyboard`,
+  `image_document`, `thread`, `url` or `other`. Asset references are checked
+  and come back with a live `asset://` uri.
+- The notes of the current conversation are shown to you at the start of each
+  turn. Search for the rest.
+
+Record what you make in the same action that makes it:
+
+```js
+const shot = await nodetool.media.generateImage(prompt, model);
+await nodetool.memory.save("Hero still for the launch film", {
+  title: "Hero still",
+  kind: "resource",
+  resources: [{ type: "asset", id: shot.asset_id }]
+});
+```
+
+Before you generate, search memory for a result that already exists. Never
+generate again what a note already records.
+
+## nodetool.shared
+
+The scratchpad of this run. It is gone when the run ends.
+
+| Call | Does |
+| :--- | :--- |
+| `list({kind, key_prefix, sources})` | Metadata only: keys, titles, kinds, sizes. `kind` filters to `task_result`, `step_result`, `input` or `shared`. |
+| `read(keys)` | Full values for the keys you name. Misses come back in `missing`. A key with no `<namespace>:` prefix is also looked up under `shared:`. |
+| `publish(key, value, {title, description})` | Stores any JSON value under `shared:<key>`. |
+
+The results of earlier steps and tasks land here. Read them instead of asking
+for them again. List first, then read only the keys you need.
+
+## nodetool.threads
+
+| Call | Does |
+| :--- | :--- |
+| `list({limit, workflow_id, cursor, preview})` | Past conversations, newest first, each with its last message unless `preview: false`. `limit` defaults to 20. |
+| `get(threadId, {limit, newest_first, cursor, max_chars})` | A page of messages, oldest first. Text is cut at `max_chars` (default 2000, `0` for no cut). |
+| `last(threadId)` | The newest message, or `undefined` |
+| `message(messageId)` | One message in full: every tool call with its arguments, files, cost |
+
+Page with the `next` cursor of the previous answer.

package/dist/_skills/api-models/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: api-models
+description: "Call nodetool.models from a code action: pick the best configured model for a capability, search for a model the user named, browse a provider's catalog, set a node's model property, or make one language-model call. Load before the first call into nodetool.models."
+---
+
+# nodetool.models
+
+Model discovery for this install. It knows which providers have credentials
+and which local models are downloaded. Never guess a model id: pick one here,
+then pass it on. Credentials and provider setup are
+`nodetool-model-provider-config`.
+
+## Calls
+
+| Call | Does | Answers |
+| :--- | :--- | :--- |
+| `pick(capability, {query, provider_hint, model_hint, prefer_local})` | Resolves ONE model. | The top result: `{provider, model_id, ref, …}` |
+| `find(capability, {query, task, provider_hint, model_hint, prefer_local, limit})` | Ranks candidates. `limit` defaults to 5. | `{results, ref, note?, query_matched?}` |
+| `list({provider, model_type, downloaded_only, limit})` | Browses every configured model. | `{results}` |
+| `forProvider(provider)` | Lists one provider's language models. | The provider catalog |
+| `generate(prompt, model, {system, images, max_tokens, temperature})` | One language-model call, with optional images. No asset is made. | `{provider, model, text}` |
+
+`capability` is one of `text_to_image`, `image_to_image`, `segment_image`,
+`text_to_video`, `image_to_video`, `reference_to_video`, `text_to_speech`,
+`text_to_music`, `audio_to_audio`, `automatic_speech_recognition`,
+`generate_embedding` and `generate_message`.
+
+`model_type` for `list` is one of `language`, `image`, `video`, `tts`,
+`music`, `audio_to_audio`, `asr` and `embedding`.
+
+## What a result carries
+
+- `provider` and `model_id` — the route. Every `nodetool.media.*` call takes
+  the whole result, `{provider, model_id}`, or a `"provider/model_id"` string.
+- `ref` — the typed value `{type, provider, id, name}`. Assign it **verbatim**
+  to a node's `*_model` property. The flat `model_id` field does not fit that
+  property.
+- For ranked media models: `canonical`, `ranked_task`, `rank` and `of`, and
+  `alternate_routes` for other providers that serve the same model. One model
+  is one row, not one row for each route.
+- `prompting_skill` — the name of the shipped guide for that model line. Load
+  it with `load_skill` before you write the prompt.
+
+## Rules
+
+- `pick` with no options is the good default. For image, video, speech and
+  music, the order comes from a quality leaderboard for the task. Do not shop
+  around.
+- When the user named a model, search in the same call:
+  `pick("text_to_image", {query: "flux schnell"})`. `query` is free text over
+  the model id and name. All words must appear, and separators do not matter.
+- `pick` throws when no configured provider offers the capability, and when a
+  `query` matches nothing. It never answers with an unrelated model. Report
+  the miss or call `find` to see what is configured.
+- `task` is a hint against the supported tasks of a model. It is not a search
+  box. Use `query` to search by name.
+- A judge for `nodetool.media.critique`, `compare`, `scoreAdherence` and
+  `understandVideo` is a chat model that reads images or video:
+  `pick("generate_message", {query: "gemini"})`, for example. It is not the
+  model that made the picture.
+
+## Examples
+
+```js
+// The best image model, straight into a generation.
+const model = await nodetool.models.pick("text_to_image");
+const shot = await nodetool.media.generateImage("a red fox in snow", model);
+
+// A node property wants the typed ref. wf = await nodetool.workflows.open(id).
+const tts = await nodetool.models.pick("text_to_speech");
+wf.node("speech_1").set({ model: tts.ref });
+
+// One text call with an image.
+const llm = await nodetool.models.pick("generate_message");
+const { text } = await nodetool.models.generate(
+  "Name the dominant colour in one word.", llm, { images: [shot.asset_uri] }
+);
+```

package/dist/_skills/api-scripts/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: api-scripts
+description: "Call nodetool.scripts from a code action: create a voice script (spoken lines, not JavaScript), add speakers with voices and spoken lines, voice the lines as audio takes, and assemble the takes into a voiceover timeline with word timings. Load before the first call into nodetool.scripts."
+---
+
+# nodetool.scripts
+
+A script (a voice script) is a cast of speakers, each with a voice, and the
+lines they speak in reading order. Voicing a line makes an audio take.
+Assembling lays the takes into a timeline. A JavaScript script is a different
+document (`nodetool-js-scripting`). A video timed to a written voiceover is
+`script-video`.
+
+| Call | Does | Answers |
+| :--- | :--- | :--- |
+| `list({limit})` | Lists scripts, newest first, with cast size, line count, voiced count and the timeline it was assembled into. | Script rows |
+| `create(name, {project_id, id})` | Creates an empty script. An existing `id` is returned as it is, so a retry makes no copy. | `{script_id, …}` |
+| `get(id)` | Reads the cast and every line with its id, index, speaker, text, direction, pause, effective voice and voicing status. | The script |
+| `edit(id, ops)` | Applies ops in order and saves. An open editor picks the change up live. | The result of each op |
+| `voice(id, opts)` | Calls the TTS provider for the lines. | The takes it made |
+| `assembleTimeline(id, {name, fps})` | Lays the voiced takes end to end into a timeline. | The timeline id, and the lines it skipped |
+
+Line status is `draft` (never voiced), `stale` (the text or voice changed
+since the take), `voiced` or `no_voice` (the speaker has no voice).
+
+## Ops
+
+A line `target` is its id, its 0-based index in the whole script, or its exact
+text. A speaker `target` is its id or name. An argument an op does not take is
+refused.
+
+| Op | Arguments |
+| :--- | :--- |
+| `set_setup` | `stage?`, `brief?`, `format?`, `length_seconds?`, `pace?`, `language?` |
+| `add_speaker` | `name`, `color?`, `provider?`, `model?`, `voice?`, `entityId?` |
+| `set_speaker` | `target`, `name?`, `color?`, `entityId?` — renames or recolours a speaker |
+| `set_speaker_voice` | `target`, `provider`, `model`, `voice`, `settings?` |
+| `remove_speaker` | `target` |
+| `add_section` | `title?` |
+| `add_line` | `text`, `speaker?`, `section?`, `direction?`, `pause_after_ms?`, `index?` |
+| `set_line_text` | `target`, `text` |
+| `set_line_speaker` | `target`, `speaker` — the op that gives a line its speaker |
+| `remove_line` | `target` |
+
+- `format` is `voiceover`, `dialogue`, `interview`, `ad-read` or `tutorial`.
+- `entityId` makes the speaker a cast character from the entity library, so
+  storyboard renders can use it.
+- A rewritten line keeps its takes as `stale`, so the next `voice()` records
+  exactly those again.
+
+## voice
+
+- Omit `targets` to voice every line that is unvoiced or stale. A whole script
+  is one call. Each line is a paid TTS call plus a transcription call, so
+  confirm the scope with the user before you voice a long script.
+- `targets` takes line ids, indexes or exact texts.
+- Each line uses its own voice, else its speaker's. `provider`, `model` and
+  `voice` together override every line. Pick the model with
+  `nodetool.models.pick("text_to_speech")`.
+- `speed`, `concurrency` (default 3, max 8).
+- Word timings are transcribed for captions (`transcribe`, default true;
+  `asr_provider` and `asr_model` default to `openai` and `whisper-1`).
+- Earlier takes are kept, and the new take becomes current.
+
+```js
+const { script_id: id } = await nodetool.scripts.create("Launch VO");
+await nodetool.scripts.edit(id, [
+  { op: "add_speaker", name: "Narrator" },
+  { op: "set_speaker_voice", target: "Narrator", provider, model, voice },
+  { op: "add_line", text: "Meet the lamp that listens.", speaker: "Narrator" }
+]);
+await nodetool.scripts.voice(id);
+const cut = await nodetool.scripts.assembleTimeline(id);
+```
+
+Each assembled clip carries its word timings, the speaker label and a link to
+its line, so a re-voiced line can round-trip into the cut. Running the
+assembly again rebuilds the same timeline in place. Validate it with
+`nodetool.timelines.validate` before a render.

package/dist/_skills/api-settings/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: api-settings
+description: "Call nodetool.settings or nodetool.secrets from a code action: read or change a NodeTool setting, find out which credentials are configured, ask the user to enter a missing API key, or read a secret in a script. Load before the first call into these namespaces."
+---
+
+# nodetool.settings and nodetool.secrets
+
+`nodetool.settings` is the configuration of this install. `nodetool.secrets`
+reads credentials inside a run. A secret value never passes through the agent:
+the user types it in a dialog.
+
+## nodetool.settings
+
+| Call | Does | Answers |
+| :--- | :--- | :--- |
+| `list({group})` | Lists every setting, or one group (`"Folders"`, for example), with its description, allowed values and current value. Secrets are not in this list. | `{settings, groups}` |
+| `get(key)` | Reads one setting, from the user's saved settings and then the environment. Refuses a secret. | The setting with its `value` and `source` (`user`, `env` or `unset`) |
+| `set(key, value)` | Changes one setting for this user. Only a declared setting can be set, and a setting with allowed values takes only those. `value` is a string. | — |
+| `secrets()` | Lists the known credentials and whether each one is configured. | Names and a configured flag. Never values. |
+| `requestSecret(key, {reason, help_url})` | Opens a dialog in the user's client where they type the value. | Only whether they saved one |
+
+`key` is the environment-variable name: `"AUTOSAVE_INTERVAL_MINUTES"`,
+`"STRIPE_API_KEY"`.
+
+### Asking for a credential
+
+1. Call `secrets()` to see what is missing, and use the name the service is
+   registered under.
+2. Call `requestSecret(key, {reason, help_url})`. Write `reason` for the user,
+   in one sentence. `help_url` is where they get the key.
+3. Continue when the answer says it was saved.
+
+A run with no interactive client refuses the request. Then tell the user
+which credential is missing and where to add it (Settings > Secrets). Do not
+ask again in a loop, and never ask the user to paste a key into the chat.
+
+## nodetool.secrets
+
+For code that needs a credential value, such as a Code node or a script:
+
+| Call | Does |
+| :--- | :--- |
+| `get(name)` | The value. It throws and names the secret when it is not set. |
+| `tryGet(name)` | The value, or `undefined` for a credential that is optional |
+| `list()` | The names this node declared in its secret scope, or `null` when it declared none |
+
+A read works only for a name inside the secret scope of the run. A chat
+action has no secret store, so `nodetool.secrets.get` throws there. Use the
+tools that hold the credential on the host instead of reading it.

package/dist/_skills/api-sketches/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: api-sketches
+description: "Call nodetool.sketches from a code action: create a sketch (layered image document), read it, add, arrange and restyle layers, place images on layers, resize the canvas, validate it, and manage its versions. Load before the first call into nodetool.sketches."
+---
+
+# nodetool.sketches
+
+A sketch is an image document: a canvas, a stack of layers, and the bindings
+that say where the picture of a layer comes from. How to compose one is
+`nodetool-sketch`. This is the call reference. One finished image with no
+layers to keep is `nodetool.media.generateImage`, not a sketch.
+
+| Call | Does | Answers |
+| :--- | :--- | :--- |
+| `list({query, limit})` | Lists sketches, newest first. | Rows with id, name and canvas size |
+| `create(name, {width, height, background_color, project_id, id})` | Creates a blank canvas. The defaults are 1024×1024 on `#ffffff`. An existing `id` you own is returned instead of a copy. | `{image_document_id, …}` |
+| `get(id)` | Reads the document: canvas, background, layers, bindings. Layer bitmaps stay opaque. | The document |
+| `edit(id, ops)` | Applies layer ops in order and saves. An open editor picks the change up live. | The result of each op |
+| `validate(idOrDocument, {width, height, background_color})` | Checks the structure without a render. For an inline document, pass the canvas it is stored against so a mismatch is reported. | `{ok, issues}` |
+| `versions(id, {save_type, limit})`, `getVersion(id, n)` | Lists and reads whole-document snapshots. | Version rows, newest first |
+| `snapshot(id, {name})` | Saves a manual version. | The version number |
+| `restore(id, n)` | Rolls back. The state it replaces is snapshotted first. | The findings of the validation after the restore |
+| `deleteVersion(id, n)` | Deletes one snapshot. This cannot be undone. | — |
+
+## Ops
+
+`target` is a layer id, its name, or `"active"`. Layer index 0 is the
+**bottom** layer.
+
+| Op | Arguments |
+| :--- | :--- |
+| `add_layer` | `name?`, `type?` (`"raster"` or `"mask"`), `index?`, `image?`, `x?`, `y?`, `width?`, `height?` |
+| `remove_layer` | `target` |
+| `rename_layer` | `target`, `name` |
+| `set_layer_props` | `target`, `visible?`, `locked?`, `opacity?`, `blendMode?` |
+| `set_layer_image` | `target`, `image`, `x?`, `y?`, `width?`, `height?` |
+| `reorder_layer` | `target`, `index` |
+| `duplicate_layer` | `target` |
+| `select_layer` | `target` |
+| `resize_canvas` | `width`, `height` |
+| `set_setup` | `brief?`, `use_case?`, `variations?`, `stage?` — the state of the guided image flow. It renders nothing. |
+
+- `image` is an asset id, an `asset://` locator, a `data:` URL or an http(s)
+  URL. The layer points at it and the editor draws it at its natural size from
+  the top-left of `{x, y, width, height}`, which defaults to the whole canvas.
+  Pass the dimensions of the image when you know them.
+- `use_case` is `product`, `portrait`, `key-art`, `social`, `logo`, `concept`
+  or `texture`, and it also sets the canvas size.
+- Pixels are never read or written here. Painting and generation happen in an
+  open editor or a workflow run.
+
+```js
+const { image_document_id: id } = await nodetool.sketches.create("Poster",
+  { width: 1080, height: 1350 });
+await nodetool.sketches.edit(id, [
+  { op: "add_layer", name: "Backdrop", image: bgUri },
+  { op: "add_layer", name: "Product", image: productUri, x: 240, y: 300, width: 600, height: 600 },
+  { op: "set_layer_props", target: "Product", blendMode: "normal", opacity: 1 }
+]);
+const check = await nodetool.sketches.validate(id);
+```

package/dist/_skills/api-storyboards/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: api-storyboards
+description: "Call nodetool.storyboards from a code action: create a storyboard, write and reorder its shots, set the board's style, entities and models, render stills and clips, revise a clip, and assemble the board into a timeline. Load before the first call into nodetool.storyboards."
+---
+
+# nodetool.storyboards
+
+A storyboard turns a brief into shots: an action, a camera, a motion and a
+duration for each, with cast entities. Stills are the cheap step, clips the
+expensive one, and the board assembles into a timeline. The directing
+contract is `storyboard-core`. The brief shapes are the board skills
+(`commercial-beat-sheet`, `explainer-storyboard`, `music-video-treatment`,
+`trailer-template`, and the job skills such as `product-commercial` and
+`short-film`). Search for them with `list_skills`.
+
+| Call | Does | Answers |
+| :--- | :--- | :--- |
+| `list({limit})` | Lists boards, newest first, with shot, still and clip counts. | Board rows |
+| `create(name, {brief, style, aspect_ratio, project_id, id})` | Creates a blank board. `aspect_ratio` defaults to `"16:9"`. `style` is added to every shot prompt. | `{id, storyboard_id, …}` |
+| `get(id)` | Reads the brief, style, aspect ratio, models, `revision`, and every shot with its id, index, slug, action, camera, motion, duration, status, `has_still`, `has_clip` and `covered_by`. | The board |
+| `edit(id, ops, {expected_revision})` | Applies ops in order and saves. It spends nothing. `expected_revision` refuses the edit when the board changed after you read it. | The result of each op |
+| `renderStills(id, {targets, provider, model, style, stale_only, concurrency})` | Makes keyframe stills with the image model. | The stills it made |
+| `renderClips(id, {targets, provider, model, resolution, mode, stale_only, concurrency})` | Makes clips with the video model. This is the expensive step. | The clips it made, and the shots it skipped |
+| `reviseClip(id, target, instruction, {provider, model})` | Changes one clip with a video-to-video edit: "make it darker, add rain". | The new take |
+| `assembleTimeline(id, {name, fps})` | Lays the rendered clips end to end into a timeline. | The timeline id, and what it skipped |
+| `previewDesign({storyboardId, expectedStoryboardRevision})` | Reads the board's design as an inline editable timeline preview. No generation and no save. | The preview |
+| `finish({storyboardId, expectedStoryboardRevision, strategy, model, timelineId, expectedTimelineRevision})` | Turns the board's graphics into editable timeline layers with no media generation. `strategy` is `deterministic` (default, no provider, an unreviewed draft) or `agentic` (a model composes and reviews rendered frames). | The status, the timeline and the new revisions |
+
+`targets` and `target` take a shot id, a 0-based index or a slug. Omit
+`targets` to render every shot that needs the step. `previewDesign` and
+`finish` take one argument object with camelCase keys.
+
+## Ops
+
+| Op | Arguments |
+| :--- | :--- |
+| `add_shot` | `action`, `slug?`, `camera?`, `motion?`, `dialogue?`, `narration?`, `duration_seconds?`, `duration_source?`, `render_mode?`, `entity_ids?`, `location_id?`, `covered_by?`, `notes?`, `end_state?`, `sound?`, `index?` |
+| `update_shot` | `target` and the same fields |
+| `remove_shot`, `duplicate_shot` | `target` |
+| `reorder_shot` | `target`, `index` |
+| `move_shot` | `target`, `scene_id?`, `position` (0-based inside the scene) |
+| `set_board` | `brief?`, `style?`, `aspect_ratio?`, `entity_ids?`, `image_model?`, `video_model?`, `narration?`, `music_prompt?`, `motion_design?` |
+| `set_setup` | `brief?`, `genre?`, `stage?` |
+| `set_style` | `entity_id` (a style entity becomes the board preset) or `style` (the descriptor alone) |
+| `create_scene`, `update_scene`, `merge_scene` | `after_scene_id?`; `scene_id`, `slugline?`, `lighting?`; `scene_id` |
+| `select_version`, `delete_version` | `target`, `kind`, `version` (0-based, oldest first) |
+| `add_keyframe_version` | `target`, `asset_id`, `flip_of?` |
+
+- `image_model` and `video_model` take a model object from
+  `nodetool.models.pick` and become the render defaults of the board.
+- `covered_by: {shot_id, start_seconds?, end_seconds?}` says that this shot's
+  picture is a window into another shot's clip, for one generation whose
+  length covers several beats. The covered shot counts as rendered. Pass
+  `null` to undo it.
+- `set_board` `narration` and `music_prompt` are board-level voiceover and
+  score direction. An empty string clears one. `motion_design` is
+  `{direction?, transitions?, continuities?}`, and `null` clears it.
+
+## Render modes
+
+A shot renders the way its `render_mode` says, or the way `mode` says for one
+call:
+
+- `keyframe` (default) animates the selected still with `image_to_video`. A
+  shot with no still is reported, not rendered. Render its still first.
+- `direct` makes the clip from the prompt with `text_to_video`. No still is
+  needed.
+- `reference` uses the reference images of the cast entities with
+  `reference_to_video`.
+
+Earlier stills and clips are kept as versions. `stale_only: true` renders
+only shots whose current version was made against a style, model, aspect
+ratio or prompt they no longer have.
+
+## The loop
+
+```js
+const { id } = await nodetool.storyboards.create("Lamp launch", { brief, style });
+await nodetool.storyboards.edit(id, [
+  { op: "set_board", image_model: await nodetool.models.pick("text_to_image"),
+    video_model: await nodetool.models.pick("image_to_video") },
+  { op: "add_shot", action: "Wide of the lamp on a desk at dusk", duration_seconds: 4 },
+  { op: "add_shot", action: "Close on the switch as a hand reaches in", duration_seconds: 3 }
+]);
+await nodetool.storyboards.renderStills(id);   // cheap: look at them first
+// … view the stills, fix shots with update_shot, render again with stale_only …
+// Confirm the shot count and the clip cost with the user before this call.
+await nodetool.storyboards.renderClips(id);    // expensive: every shot that needs a clip
+const cut = await nodetool.storyboards.assembleTimeline(id);
+```
+
+When the board links a script, assembly times each shot to the takes it
+covers and adds a voiceover clip for each voiced line. Validate the timeline
+with `nodetool.timelines.validate` before a render.