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

package/dist/_skills/nodetool-workflow-builder/SKILL.md

@@ -0,0 +1,295 @@
+---
+name: nodetool-workflow-builder
+description: "Create or edit NodeTool workflow graphs, connections, and properties using UI, headless tools, or requested workflow files."
+featured: true
+---
+
+# Build NodeTool workflows
+
+Create or edit a workflow that produces the requested outputs from the specified
+inputs. Preserve existing nodes and connections outside the requested change.
+
+## A graph is one surface among several
+
+NodeTool holds several document kinds, and most of them are not graphs. Build a
+graph when the user asked for one, when the job has to re-run on new inputs, or
+when the result must be callable over the API. Otherwise route the request.
+
+| The deliverable | Skill |
+|---|---|
+| A finished video, still set or campaign | `storyboard-core`, which picks the job skill |
+| A screen someone clicks | `nodetool-app-builder` |
+| A repair on footage already cut: cutout, upscale, lip sync, generated sound | `nodetool-video-post` |
+| A cut, titles, transitions or animation on a timeline | the `motion-graphics` system skill, via `load_skill` |
+| Logic in JavaScript rather than nodes | `nodetool-js-scripting` |
+| A layered image, mask or overlay | `nodetool-sketch` |
+| A 3D model or scene | `nodetool-3d-scene` |
+| A playable 2D or 3D game | `native-game` |
+| A math or explainer animation in Python | `manimgx` |
+| Document indexing, vector search, RAG | `nodetool-rag-indexing` |
+| Navigating, reading or filling in web pages | `nodetool-browser-agent` |
+| A reusable video template for batches | `video-workflow` |
+| A new node type | `nodetool-custom-node-developer` |
+
+A workflow can still be the right answer alongside one of these: a mini app runs
+workflows, and a timeline clip can be produced by one.
+
+Use the authoring surface the user requested: the graph tools for a saved or
+open workflow, and JSON or the TypeScript DSL when a workflow file is
+requested. Do not claim a missing tool is callable. Use the live schemas and
+registry as the source of identifiers.
+
+## Build and verify
+
+1. Inspect the existing graph for edits (`ui_get_graph` or `get_workflow`).
+   Identify required inputs, outputs, and behavior from the request.
+2. Find node types. On the canvas, `ui_search_nodes` with
+   `include_properties: true` and `include_outputs: true` returns property and
+   output names. Headlessly, `search_nodes {query: [...]}` finds the type and
+   `get_node_info {node_type}` returns its inputs, outputs, types and defaults.
+   Pick models with `find_model` (headless) or `ui_search_models` (canvas). Do
+   not invent node types, properties, handles, or model identifiers.
+3. Add or update nodes, set required properties, and connect compatible handles.
+   Keep existing layout and identifiers when editing.
+4. Validate with `ui_get_graph` (its `validation` field) or `validate_workflow`.
+   Fix errors and required-input warnings. Read back the saved graph before
+   claiming it was created or changed. Report any remaining limitation.
+5. Execute only when the request includes a run. A run of generation nodes
+   spends provider money, so confirm scope with the user first. Report the
+   workflow id, inputs, validation result, and actual run outcome.
+
+If a node is unavailable, broaden the search and inspect supported alternatives.
+Proceed with an equivalent composition when it preserves the requested behavior.
+Otherwise explain the missing capability and ask only for the decision needed to
+choose an alternative. Continue independent work on the rest of the graph.
+
+## Graph tools
+
+These edit one workflow. With the workflow open in the editor they act on the
+live canvas. With no editor open, the eight graph tools (`ui_get_graph`,
+`ui_add_node`, `ui_connect_nodes`, `ui_update_node_data`, `ui_delete_node`,
+`ui_delete_edge`, `ui_move_node`, `ui_set_node_title`) read and write the saved
+workflow named by `workflow_id`. Each mutation also accepts
+`based_on_revision` (from `ui_get_graph`), which refuses the edit if the graph
+changed.
+
+| Tool | Purpose | Key params |
+|------|---------|-----------|
+| `ui_search_nodes` | Find node types | `query`, `input_type`, `output_type`, `include_properties`, `include_outputs`, `limit` |
+| `ui_search_models` | Models for a generic AI node | `kind` (`text_to_image`, `image_to_image`, `text_to_video`, `image_to_video`, `reference_to_video`, `text_to_speech`, `text_to_music`, `audio_to_audio`, `speech_to_text`, `text_generation`, `embedding`), `limit` |
+| `ui_add_node` | Add one node | `id`, `type`, `position {x, y}`, `properties` |
+| `ui_connect_nodes` | Connect two nodes | `source_node_id`, `source_handle`, `target_node_id`, `target_handle` |
+| `ui_update_node_data` | Merge into a node's `data` | `node_id`, `data` (e.g. `{properties: {…}}`, `{dynamic_outputs: {…}}`, `{title}`) |
+| `ui_get_graph` | Read graph, revision and validation | `workflow_id` |
+| `ui_delete_node` / `ui_delete_edge` | Remove | `node_id` / `edge_id` |
+| `ui_move_node` | Reposition | `node_id`, `position {x, y}` |
+| `ui_set_node_title` | Rename a node | `node_id`, `title` |
+| `ui_open_workflow` | Open a workflow tab | `workflow_id` |
+| `ui_run_workflow` | Execute | `workflow_id`, `params` |
+
+`ui_add_node` takes `properties` only. Anything else on the node's `data`, such
+as `dynamic_outputs`, is set afterwards with `ui_update_node_data`.
+
+## Workflow tools
+
+These need no editor.
+
+| Tool | Purpose |
+|---|---|
+| `list_workflows`, `get_workflow` | Find and read a workflow |
+| `search_nodes`, `get_node_info`, `list_nodes` | Node discovery. `search_nodes` hides provider nodes (`openai.*`, `kie.*`, …) unless `include_provider_nodes: true`, which is for a provider the user named |
+| `find_model` | A `{provider, model}` ref for a generic AI node's `model` property |
+| `create_workflow {name, graph}` | Save a new graph. Nodes are `{id, type, properties}`. Edges are `{source, sourceHandle, target, targetHandle}` |
+| `validate_workflow {workflow_id \| graph}` | Static check: unknown types, missing properties, unselected models, bad edges |
+| `run_workflow`, `start_background_job`, `debug_workflow` | Execute, execute without waiting, or execute with a full debug report |
+| `run_node {node_type, inputs}` | Run one node to probe what it does (chat only) |
+
+For a brief rather than a graph, the planner builds one: `plan_workflow
+{workflow_id}` stores a plan whose steps map to registry node types,
+`update_workflow_plan_step` fixes a step the registry lacks, and
+`build_workflow_from_plan {workflow_id}` places and validates the nodes. On the
+canvas the same flow is `ui_workflow_plan`, `ui_workflow_update_plan_step` and
+`ui_workflow_build_from_plan`.
+
+## Node catalog
+
+Catalog entries are search leads. Confirm each type with `get_node_info` or
+`ui_search_nodes` before using it. From the CLI, inspect installed types with
+`nodetool node list` and `nodetool node info <type>`.
+
+`nodetool.output.Output` is supplied by the audio pack. If it is needed but
+not installed, run `nodetool packs add audio --yes`. CLI workflow runs also
+return terminal transform outputs: a core-only deterministic text graph can
+end at `nodetool.text.Template` without a dedicated sink. For example,
+`StringInput` → `Template` returns the template's values under `outputs.Template`.
+
+| Namespace | Common nodes |
+|---|---|
+| `nodetool.input` | `StringInput`, `IntegerInput`, `FloatInput`, `BooleanInput`, `ImageInput`, `AudioInput`, `VideoInput`, `DocumentInput`, `MessageInput`, `LanguageModelInput` |
+| `nodetool.output` | `Output`. `nodetool.workflows.base_node.Preview` shows an intermediate value |
+| `nodetool.constant` | `String`, `Integer`, `Float`, `Bool`, `List`, `Dict`, `Image`, `Audio`, `Video`, `JSON` |
+| `nodetool.agents` | `Agent`, `Summarizer`, `Extractor`, `Classifier`, `Decision`, `EnhancePrompt`, `CreateThread` |
+| `nodetool.generators` | `ListGenerator`, `DataGenerator`, `StructuredOutputGenerator`, `ChartGenerator`, `SVGGenerator` |
+| `nodetool.text` | `Template`, `Concat`, `Prompt`, `FilterString`, `FilterRegexString`, `Embedding`, `AutomaticSpeechRecognition`, `SaveText` |
+| `nodetool.code` | `Code`: a JavaScript body. See `nodetool-js-scripting` |
+| `nodetool.control` | `If`, `Switch`, `ForEach`, `Collect`, `Loop`, `Chunk`, `Take`, `Zip`, `RepeatCount`, `RepeatValue`, `TryCatch` |
+| `nodetool.data` | `ForEachRow`, `LoadCSVAssets` |
+| `nodetool.document` | `LoadDocumentFile`, `SaveDocumentFile`, `ListDocuments` |
+| `nodetool.image` | `TextToImage`, `ImageToImage`, `LoadImageFile`, `SaveImage`, `Resize`, `Crop`, `RotateAndFlip`, `Compositor`, `Upscale`, `RemoveBackground` |
+| `nodetool.audio` | `TextToSpeech`, `TextToMusic`, `LoadAudioFile`, `SaveAudio`, `AudioMixer`, `Concat`, `Trim`, `Normalize` |
+| `nodetool.video` | `TextToVideo`, `ImageToVideo`, `ReferenceToVideo`, `LoadVideoFile`, `SaveVideo`, `Concat`, `Trim`, `ExtractFrame`, `ExtractAudio`, `AddAudio`, `GetVideoInfo` |
+| `vector` | `Collection`, `IndexTextChunk`, `QueryText`, `HybridSearch`. See `nodetool-rag-indexing` |
+| `lib.*` | `lib.pdf` (text, tables, page images), `lib.image.*` (filters, color, draw), `lib.audio.*` (effects), `lib.svg`, `lib.charts.ChartRenderer`, `lib.browser.Screenshot`, `lib.sqlite.GetDatabasePath` |
+
+`lib.http`, `lib.os`, `lib.datetime`, `lib.json`, `lib.math`, `lib.uuid`,
+`nodetool.boolean`, `nodetool.dictionary`, `nodetool.list`, `nodetool.numbers`,
+the old `nodetool.text` helpers such as `Slugify` and `Chunk`, and all `skills.*`
+nodes have been removed. Use the Code node (`nodetool.code.Code`) and its
+snippet library instead. Its body is plain JavaScript with `fetch`,
+`workspace.*` and the other globals `nodetool-js-scripting` lists. Libraries
+such as `@nodetool-ai/sandbox-dates` are imported sandbox packages, not globals.
+
+### Generation nodes
+
+Use the generic nodes with a `model` property: `nodetool.image.TextToImage`,
+`ImageToImage`, `nodetool.video.TextToVideo`, `ImageToVideo`,
+`ReferenceToVideo`, `nodetool.audio.TextToSpeech`, `TextToMusic`. Set `model`
+from `find_model` or `ui_search_models`. A provider's own node (`kie.video.*`,
+`openai.*`, `gemini.*`, …) exposes that model's extra settings. Search for one
+only when the user named the provider or needs a setting the generic node does
+not carry, with `include_provider_nodes: true` on `search_nodes`.
+
+### Data types
+
+- **Primitives**: `str`, `int`, `float`, `bool`, `list`, `dict`, `any`
+- **Assets**: `{type: "image|audio|video|document", uri: "..."}`
+- **Models**: `language_model`, `image_model`, `video_model`, `embedding_model`, `tts_model`
+
+Edges enforce type compatibility. Use `any` for flexible connections. Search
+with `input_type` / `output_type` (`"str"`, `"image"`, `"list"`, …) to find a
+node that fits a handle.
+
+## Workflow patterns
+
+- **Pipeline.** Input → transforms → Output. For example `ImageInput` →
+  `lib.image.enhance.AutoContrast` → `SaveImage` → `Output`.
+- **Agent generation.** Input → `Agent` or `Summarizer` → post-process →
+  Output. `ListGenerator` streams one item per line for fan-out.
+- **Previews.** Put `Preview` nodes after intermediate stages of a multi-stage
+  generation so progress is visible.
+- **RAG.** Index: Code node (`workspace.list`) → `LoadDocumentFile` → Code node
+  ("Chunk Text" snippet) → `vector.IndexTextChunk`. Query: `StringInput` →
+  `vector.HybridSearch` → `Template` → `Agent` → `Output`. See
+  `nodetool-rag-indexing`.
+- **Realtime.** `RealtimeAudioInput` → `openai.agents.RealtimeAgent` or
+  `openai.agents.LiveAgent` → `Preview`. `LiveAgent` runs full-duplex speech;
+  feed it 24 kHz PCM16 microphone chunks.
+- **Multi-modal.** Chain modalities: `AutomaticSpeechRecognition` → `Agent` →
+  `TextToImage`, or `ExtractAudio` → `AutomaticSpeechRecognition` →
+  `Summarizer`.
+- **Generated media.** `StringInput` (prompt) → `TextToVideo` → `Output`, or
+  `ImageInput` + `StringInput` → `ImageToVideo` → `Output`. For lip sync,
+  upscaling or avatar work, search `"lip sync"`, `"upscale"` or `"avatar"`.
+
+### Agent outputs and tools
+
+- `dynamic_outputs` on an `Agent` (`{"title": {"type": "str"}}`) declares
+  structured result fields. The model fills them through a submit tool, and each
+  becomes an output handle.
+- To let an Agent call another node as a tool, connect it with a control edge
+  (`edge_type: "control"`, both handles `__control__`). The Agent's regular
+  outputs (`text`, `chunk`) still route to `Preview` or `Output`.
+
+### Streaming and control flow
+
+- Everything is a stream. A single value is a one-item stream.
+- `nodetool.control.Collect` gathers a stream into a list.
+  `nodetool.control.ForEach` emits each item of a list.
+- `nodetool.control.Loop` repeats part of the graph: wire `initial` into the
+  body, the body's result back into `next`, and a bool into `condition` (loop
+  again while true). `max_iterations` bounds it and `done` carries the final
+  value. It is the only way to close a cycle. The DSL cannot express the back
+  edge, so build loops with the graph tools or workflow JSON.
+- `nodetool.agents.Decision` lets a model make the call: `prompt` is a yes/no
+  question, `value` is what it judges (images are shown to the model),
+  `decision` is the bool and `if_true`/`if_false` route `value` like `If`. Wire
+  `decision` into `Loop.condition` to loop until a model is satisfied, and phrase
+  the question so yes means "loop again".
+
+## Debugging and validation
+
+`ui_get_graph` returns a `validation` field:
+
+- `errors`: blocking issues, such as invalid node types or a Code body that does
+  not parse.
+- `warnings`: disconnected required inputs and empty required properties.
+- `suggestions`: orphaned nodes.
+
+`validate_workflow` is the headless equivalent and also catches unselected
+models and model ids a provider does not offer. Fix blocking errors and the
+warnings that prevent the requested behavior. Explain any remaining warning
+without expanding the task.
+
+- **"Required property 'X' is not set"**: set it with `ui_update_node_data` or in
+  the graph's `properties`. Common ones are `model` and `prompt`.
+- **"Required input 'X' not connected"**: add an edge or set a value.
+- **Wrong handle name**: re-read the type with `get_node_info` or
+  `ui_search_nodes {include_outputs: true}`.
+- **Type mismatch**: compare the source output type with the target input type.
+- **Node not found**: broaden the query or search by namespace prefix
+  (`"nodetool.text"`).
+
+Do not retry a failing call unchanged. Agent and generator nodes need `model`,
+generation nodes need `prompt`, and `ForEach` needs a list input. Set them or ask
+the user which value to use.
+
+## Running workflows from a shell
+
+This section is for a person or agent with a shell. The in-product agent uses
+`run_workflow` instead.
+
+```bash
+nodetool workflows run ./workflow.json --params '{"input": "hello"}' --json
+nodetool workflows run ./workflow.ts --json    # a DSL file, built then run
+nodetool workflows run <workflow_id>
+nodetool workflows list
+nodetool workflows get <id>
+nodetool jobs list
+nodetool serve --port 7777
+
+# From a NodeTool checkout
+npm run workflow -- ./workflow.json --input text='hello' --show-messages
+```
+
+## TypeScript DSL
+
+Write workflows as TypeScript with `@nodetool-ai/dsl`. Namespaces mirror node
+namespaces: `nodetool.text` is `text`, `nodetool.control` is `control`,
+`lib.pdf` is `libPdf`, `vector` is `vector`.
+
+```typescript
+import { workflow, input, text, agents, output } from "@nodetool-ai/dsl";
+
+const topic = input.stringInput({ name: "topic", value: "tides" });
+const brief = text.template({
+  string: "Explain {{ topic }} to a ten-year-old.",
+  topic: topic.output()
+});
+const answer = agents.summarizer({ text: brief.output() });
+const result = output.output({ name: "answer", value: answer.output("text") });
+
+const wf = workflow(result);
+console.log(JSON.stringify(wf));
+```
+
+- **`node.output()`** is a function. It returns the default output handle and
+  only works on a node with one. Name the slot on a multi-output node:
+  `answer.output("text")`, `branch.output("if_true")`.
+- **Connectable**: every input accepts a literal value or an output handle.
+- **`workflow(...terminals)`** traces from the terminal nodes and returns
+  serializable `{nodes, edges}`. A node shared by two branches appears once.
+- **`run(wf, opts?)`** executes in-process. **`runGraph(...terminals)`** is
+  `run(workflow(...terminals))`.
+- Dynamic inputs are extra keys, as `topic` on `text.template` above.
+- There is no `libMath`, `libHttp` or `list` namespace. Use `code.code` for
+  arithmetic, JSON, list and HTTP logic.

package/dist/_skills/product-commercial/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: product-commercial
+description: "Direct the look of a polished product film or brand commercial in NodeTool. For the ad's beat structure pair with commercial-beat-sheet, for a finished spot from a product page use launch-commercial, and for phone-shot creator ads use ugc-video."
+---
+
+**Load `/storyboard-core` first.** It carries the loop, the tool contract,
+the entity rules and the gating this skill assumes. Everything below is what is
+different about a camera-grade product film. This skill sets the look; an ad's
+hook, beats and timecodes come from `/commercial-beat-sheet`, which composes with
+it on the same board.
+
+## What makes this job type its own
+
+There is no face to hold steady, so the thing that drifts is the **pack**: label
+geometry, cap, proportions, colour. That is what the product entity is for, and it is
+why the reference image matters more here than the descriptor.
+
+The other difference is that a product film's shots are mostly about **light**, and
+light lives in the board style, not in the shot.
+
+## Casting the pack
+
+The user's pack shot is the entity. Save the attached image as an asset, then
+`create_entity {asset_id, kind: "prop", name, descriptor}`. Write the descriptor as
+geometry and finish — `squat 200ml amber glass cylinder, brushed gold screw cap,
+single centred cream label, serif wordmark` — not as marketing copy.
+
+Never invent a logo, a tagline or a label layout. If the label has to be readable, say
+so in the shot's `action` and give that shot a macro framing. Inspect the still
+before rendering its clip. If the label remains unreadable, retry only within the
+user's retry and spending limits. With no retries authorized, report the defect
+and follow the remaining requested stages without claiming the label is readable.
+
+Given several angles (front, three-quarter, back, top), tag the best single hero angle
+as the entity and keep the rest as plain assets. An entity is one image asset, so it
+carries one reference into the prompt.
+
+## The look goes in the board style, once
+
+| Register | `style` |
+|---|---|
+| Luxury studio | `black cyclorama, one warm key, gold rim, volumetric mist, 85-100mm, 24fps, no grain` |
+| Clean e-comm | `white sweep, soft top light, even fill, 50mm, no shadow detail loss` |
+| Location / lifestyle | `90s print / 35mm commercial, hard noon sun, mild bloom, no other brand marks` |
+| Dark technical | `graphite surface, hard side key, specular edges, controlled falloff` |
+
+Add `no on-screen type` to the style. Video models letter badly, and titles belong on
+the timeline as text clips (`edit_timeline` → `add_text_clip`), where they stay
+editable.
+
+## Shot pattern
+
+Use the requested shot count. When the brief leaves it open, five to seven shots
+are a starting pattern. Give each cut a distinct purpose. A product film reads as expensive
+when the **light** moves and the pack does not — write that literally:
+`the light streak crosses the glass, the bottle stays still`.
+
+- Put the move in `motion` with a distance or a degree: `slow 8cm push-in`,
+  `low 30-degree orbit`, `rack focus from cap to liquid`.
+- Give the last shot a **hold**: `last 1.2s dead hold` — models drift on the tail, and
+  a hold is what makes an end card usable.
+- Count the physical events: `two condensation beads run`, `one ripple, then still`.
+- On a location spot with talent, cast the person as a character entity per
+  `/ugc-video`'s casting pass, but keep the pack's shots free of them with an
+  explicit `entity_ids`.
+
+## Where a still is the wrong unit
+
+Macro glass, mist and specular highlights are where `keyframe` mode pays — the still
+is cheap and you can judge the light before spending on motion. Keep the default.
+
+Switch a shot to `render_mode: "direct"` only for heavy motion the first frame would
+stiffen: a fast orbit, liquid pouring, an explosive reveal. The direct clip prompt
+carries the camera fields, the scene lighting and the board style itself.
+
+## Briefs
+
+Adapt these examples to the user's brief. Example deliverables, style choices,
+and approval checkpoints apply only when the user adopts them.
+
+**Briefs** below has two: a 10s luxury pack shot with no talent, and a 30s
+street CPG walk with a character. Replace the bracketed placeholders and hand one over
+after the standing orders.
+
+## Briefs — product film
+
+One per message, after the standing orders from `/storyboard-core`. Replace
+`[PRODUCT]` and `[CITY]`. `Nova` stands for the character entity's **plain name**.
+
+---
+
+### Luxury pack shot, 10s 16:9
+
+```
+Direct a 10s 16:9 luxury commercial. [PRODUCT] only, no talent, no type.
+
+Cast the pack from the attached shot: save it as an asset, then tag it as a prop
+entity. Descriptor is geometry and finish, not copy.
+
+Board style: black cyclorama, one warm key, gold rim, volumetric mist, 85-100mm,
+24fps, no grain, no on-screen type.
+
+1a 0-2  macro. A light streak crosses the glass, two condensation beads run.
+        The light moves, the pack does not.
+2a 2-4  the bottle rises onto black acrylic, key holds.
+3a 4-6  low 30-degree orbit, label readable at the midpoint.
+4a 6-8  rack focus from cap to liquid, one ripple, then still.
+5a 8-10 pull back to a centred hero, key lifts ten percent, last 1.2s dead hold.
+
+Stop after the board. Stills before clips.
+```
+
+### Street CPG walk, 30s 16:9
+
+```
+Direct a 30s 16:9 street commercial in [CITY] for [PRODUCT] with Nova.
+
+Cast both: the pack from the attached shot as a prop entity, Nova as a character
+entity from a generated reference you show me first.
+
+Board style: 90s print / 35mm commercial, hard noon sun, mild bloom, no other
+brand marks, no on-screen type.
+
+1a 0-4   fisheye on a boom, Nova walking cobbles, [PRODUCT] in hand, long shadow
+2a 4-8   shoulder track, one bite or sip
+3a 8-12  POV from inside the cup or wrapper, a building cornice behind
+4a 12-16 low wide at a crosswalk, one unbranded taxi crosses
+5a 16-22 she stops and turns once, the pack reads
+6a 22-27 she leans to the lens, a small late smile. One line, this shot only.
+7a 27-30 the pack alone on a cafe table, street bokeh, one-second push, dead
+         hold on the tail. entity_ids: the product only.
+```

package/dist/_skills/qwen-image-prompting/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: qwen-image-prompting
+description: Prompt Alibaba's Qwen-Image line for the typography work it is built for — quoting exact copy so the model stops inventing it, switching prompt expansion off before it rewrites your strings, describing layout in relative position and weight rather than point sizes, writing non-Latin scripts as characters, and addressing edit references as image 1/2/3. Use whenever the model id names Qwen-Image (alibaba/qwen-image-3/text-to-image, alibaba/qwen-image-3/edit, fal-ai/qwen-image-2/pro/text-to-image, fal-ai/qwen-image-edit-2511, fal-ai/qwen-image-2512, fal-ai/qwen-image-layered, qwen-image-3.0-pro/edit, qwen/qwen-image-edit-plus) on generate_image, edit_image or a TextToImage node.
+---
+
+# Qwen-Image → the model you reach for when the image has words in it
+
+Qwen-Image renders text other image models garble. Runware's guide claims
+twelve scripts natively, legible down to roughly 10 px, and long layout
+instructions honoured. That is the
+reason to pick it, and the prompt should spend its length on the copy and the
+layout rather than on adjectives.
+
+Reach it with `find_model` for `text_to_image` or `image_to_image`, then
+`generate_image` / `edit_image`. `generate_image` forwards only the prompt, a
+negative prompt, the size and a quality string, and `edit_image` only the
+images, the prompt, a negative prompt, a target size and a strength. The
+expansion flag, guidance and step count exist only on the route's own node:
+find it with `search_nodes`, read its fields with `get_node_info`, and run it
+with `run_node`.
+
+On Qwen-Image-3 (`alibaba/qwen-image-3/*`) prompts run to 5000 characters; the
+negative prompt caps at 500. `fal-ai/qwen-image-2/edit` and the
+`qwen-image-max` routes cap the prompt at 800.
+
+## Quote the copy
+
+Anything in quotation marks is treated as literal copy. Anything you describe
+instead, the model writes for you — usually plausibly and never what you meant.
+
+> A vertical science poster. Title "轨道力学" in large bold characters across the
+> upper third, subtitle "Orbital Mechanics" in small widely-spaced capitals
+> directly beneath. Three labelled diagram panels down the centre, captions
+> "近地点", "远地点", "转移轨道" under each. A thin rule separates the diagram block
+> from a footer reading "第三版 · 2026". Flat editorial illustration, two-colour
+> palette. No other text.
+
+Three habits that make it land:
+
+- **Write the characters, never describe them.** Paste the Chinese, Japanese,
+  Korean or Spanish string itself, with its diacritics. "The Chinese word for
+  orbit" produces something that is not that word.
+- **State the relationship between scripts** in a bilingual layout — "on the
+  same line", "stacked directly beneath" — and match their size and weight, or
+  one language reads as an afterthought.
+- **Close with "no other text".** Left to itself, the model fills empty margins
+  with invented lettering.
+
+This is the model for copy that is part of the image — a poster, a label, a
+sign in the scene. A title or a super on a still headed for a timeline is not:
+that goes on as a text clip afterwards (`caption-titles`), where it can be
+corrected and re-timed.
+
+## Turn prompt expansion off for typography
+
+On the hosted tiers — Qwen-Image-2, Max and 3 — `enable_prompt_expansion`
+defaults to true and runs an LLM over your prompt first. AtlasCloud's
+`qwen-image-3.0` and `qwen-image-3.0-pro` routes spell it `prompt_extend`, also
+true by default. It helps a three-word
+prompt and ruins a typographic one: it edits the strings you quoted and adds
+signage you did not ask for. Set it false whenever exact copy matters.
+
+The open-weight checkpoints (`fal-ai/qwen-image`, the `qwen-image-edit-*`
+releases) have no such flag and take your prompt as written. On fal they expose
+`guidance_scale` and `num_inference_steps` instead, and LoRA variants — raise
+guidance when the layout is being loosely interpreted, and leave the step
+count alone until the prompt is settled. Replicate's `qwen/qwen-image` and
+`qwen/qwen-image-2512` call the dial `guidance`, and `qwen/qwen-image` adds an
+`enhance_prompt` rewrite that is off by default. Several Replicate edit routes
+(`qwen/qwen-image-edit`, `qwen/qwen-image-edit-plus`,
+`qwen/qwen-image-edit-2511`) expose neither dial.
+
+## Layout is relative, not metric
+
+Point sizes and pixel coordinates mean nothing here. Vertical order, relative
+size and relative weight mean everything. "Large bold capitals across the top,
+small widely-spaced capitals directly beneath, body copy in two columns below
+the rule" is a layout the model can execute. "24pt heading at x=120" is not.
+
+For dense label sets, add structural marks — rules, borders, panels. Without
+them a block of labels renders as a list.
+
+## Size
+
+On Qwen-Image-3, text-to-image runs 512×512 to 2048×2048 total pixels and
+editing runs 512×512 to 1440×1440; the other checkpoints have their own
+ceilings, so read the endpoint. Small type needs the pixels: draft the
+composition small, then render the deliverable near the ceiling, and choose a
+taller canvas when the fine print has to survive.
+
+## Editing
+
+Qwen-Image-3 Edit takes one to three reference images and **order matters** —
+the prompt addresses them as "image 1", "image 2", "image 3". References run
+384–2048 px per side, 10 MB each, JPEG/PNG without alpha or WEBP. The earlier
+edit checkpoints take a list too, and the same "image N" convention applies.
+
+> Place the bottle from image 1 on the marble surface from image 2, keeping the
+> bottle's label, proportions and cap exactly as they are. Match the lighting
+> direction of image 2. Replace the label copy with "SERIES 04" in white
+> sans-serif capitals.
+
+Name what stays as explicitly as what changes. Recolouring a packshot, carrying
+a product into a new scene, and staging two products together are all the same
+instruction shape: what comes from which image, what must not move.
+
+## Symptoms
+
+| What went wrong | What to change |
+| :--- | :--- |
+| The text is close to yours but not yours | Quote it, and set `enable_prompt_expansion` (or `prompt_extend`) false |
+| Invented words in the margins | Add "no other text" |
+| Non-Latin script renders as garbage | Paste the characters instead of describing them |
+| Small type is illegible | Render nearer the pixel ceiling, or use a taller canvas |
+| The wrong reference supplied the subject | Say "image 1" / "image 2" explicitly and check the order you sent |
+| Hierarchy is flat | Give each line a relative size and weight, not a size in points |
+
+Grade the result with `critique_image` and `score_image_adherence`, which will
+tell you whether the copy rendered as written before you look at the picture.
+
+Adapted from Runware's Qwen-Image-3.0 text and typography guide:
+https://runware.ai/docs/models/alibaba-qwen-image-3-0/guides/text-and-typography

package/dist/_skills/script-video/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: script-video
+description: "Direct a NodeTool video whose timing follows written voiceover, such as a narrated explainer or narrated b-roll: script, voice, and shots timed to the takes. For an explainer's beat structure, pair with explainer-storyboard. For on-camera creators, use ugc-video."
+---
+
+**Load `/storyboard-core` first.** It carries the loop, the tool contract and
+the gating this skill assumes. This job type inverts the order of that loop, so read
+the sequence below before creating a board. For a product explainer, load
+`/explainer-storyboard` as well: it sets the teaching arc and the beats, and this
+skill turns their voiceover into a script that times the shots.
+
+## What makes this job type its own
+
+Everywhere else the picture comes first and the words ride along. Here the words are
+the spine: they set the running time, and each shot has to be exactly as long as the
+line it covers. That is a different tool path — a **script resource** the storyboard
+links to — not a storyboard with narration typed into it.
+
+The payoff is that `assemble_storyboard_timeline` on a linked board cuts words and
+picture together: each shot runs as long as the takes it covers, and every voiced line
+becomes its own voiceover clip.
+
+## The sequence
+
+1. **Research and write the voiceover.** 150–165 words is about 60 seconds. Write it
+   before anything visual exists.
+2. `create_script {name}`.
+3. `edit_script {script_id, ops}` — `{"op": "add_speaker", "name": "Narrator"}`, then
+   one `{"op": "add_line", "speaker": "Narrator", "text": "..."}` per sentence. A line
+   with no `speaker` has no voice to inherit and reads `no_voice` however the cast is
+   set. One sentence per line: a line is the unit that gets a take and times a shot,
+   so a paragraph in one line gives you a shot you cannot cut.
+4. **Give the narrator a voice:** `find_model` (`text_to_speech`) →
+   `{"op": "set_speaker_voice", "target": "Narrator", "provider", "model", "voice"}`.
+   Without it every line reads `no_voice`. `voice` is the provider's own voice name
+   (`Aoede`, `alloy`), not a model id.
+5. `derive_storyboard_from_script {script_id, provider, model}` — one shot per line, in
+   reading order, each carrying the line ids it covers. Pass a language provider and
+   model for a director pass that writes each shot's visuals over that scaffold; omit
+   **both** for the bare scaffold.
+6. **Rewrite the visuals.** The derived shots are a starting point. Go through with
+   `edit_storyboard` `update_shot`, giving each an `action` that is concrete b-roll and
+   a `motion` with a count. Set the board `style` and `entity_ids` with `set_board`.
+   Confirm the shot count and the models with the user before the first render.
+7. **Stills on every shot**, reviewed, before any clip.
+8. `voice_script_lines {script_id}` — defaults to every draft or stale line. Word
+   timings come from a transcription pass (`transcribe: true` by default) and ride into
+   the clips as captions.
+9. Clips, then `assemble_storyboard_timeline`, then `validate_timeline`.
+10. **Duck the pictures' own sound.** Assembly gives every shot clip an audio twin on a
+    "Shot Audio" track. `edit_timeline` → `get_state`, then `set_clip_params` with
+    `muted: true` on those clips so the voiceover carries.
+
+## Timing
+
+A shot on a linked board takes its length from its lines' takes — that is
+`duration_source: "audio"`, the default once linked. Leave it alone. Pin a shot with
+`duration_source: "manual"` plus `duration_seconds` only when it must hold past its
+narration, such as a final card.
+
+Voice **before** you cut. A line with no take leaves its shot on its own duration, and
+the assembly lists it as skipped.
+
+## Style registers
+
+Put one in the board `style`, and say `no on-screen type` — titles belong on the
+timeline as text clips, where they stay editable.
+
+| Register | `style` |
+|---|---|
+| Flat 2D | `flat vector illustration, three-colour palette, thick uniform strokes, white ground` |
+| Documentary macro | `macro photography, shallow depth, natural light, matte film grade` |
+| Dark UI | `dark interface on a black ground, single accent colour, crisp type-free panels` |
+| Paper-craft | `cut-paper layers, soft drop shadows, warm raking light` |
+
+## Music
+
+`edit_storyboard` → `{op: "set_board", music_prompt: "..."}` sets the score direction,
+headless, and assembly turns it into a draft music clip under the voiceover. For a bed
+you generate yourself instead: `generate_music`, then `edit_timeline` → `add_track` +
+`add_media_clip`, with its `volumeDb` low enough to sit under the voiceover.
+
+## Brief
+
+Adapt these examples to the user's brief. Example deliverables, style choices,
+and approval checkpoints apply only when the user adopts them.
+
+```
+Research [TOPIC], then direct a faceless 16:9 explainer. No on-camera talent.
+
+Write the voiceover first, 150-165 words, one sentence per line, as a script:
+create_script, then edit_script to add a Narrator speaker and the lines, each
+line with speaker Narrator. Give the narrator a voice with set_speaker_voice
+before anything else.
+
+Then derive_storyboard_from_script with a director pass, and rewrite each of the
+eight shots' action and motion as concrete b-roll to that voiceover.
+Board style: [flat 2D / documentary macro / dark UI / paper-craft], no on-screen
+type.
+
+Stills on every shot before any clip. Then voice_script_lines so the shots take
+their length from the takes, then clips, then assemble_storyboard_timeline and
+validate_timeline. Finish by muting the Shot Audio clips under the voiceover.
+
+Stop after the script and the board. Show me the words before you spend.
+```