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

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

@@ -0,0 +1,151 @@
+---
+name: api-timelines
+description: "Call nodetool.timelines from a code action: create, read, edit or write a whole timeline, study the shipped example timelines, validate at the showcase tier, preview composited frames and contact sheets, compare versions, render the cut, manage versions and insert reusable compositions. Load before the first call into nodetool.timelines."
+---
+
+# nodetool.timelines
+
+A timeline is a sequence: tracks of clips — media, text, shapes, groups, 3D
+models and MIDI — with animations, transitions, masks, mattes, effects and
+markers. This skill is the call reference. The `edit` op contract, the
+animation roles and the preset catalog are `timeline-edit-ops`. The build
+loop and the choice between the code pack and edit ops are `motion-graphics`.
+The craft is in `motion-direction`, `motion-principles`, `motion-curves`,
+`frame-composition`, `color-motion` and `beat-sync-editing`.
+
+## Calls
+
+| Call | Does | Answers |
+| :--- | :--- | :--- |
+| `list({query, limit})` | Lists sequences, newest first. | `{timelines}` |
+| `create(name, {fps, width, height, project_id})` | Creates an empty sequence. The defaults are 30 fps and 1920×1080. Vertical is 1080×1920. | `{timeline_id, …}` |
+| `get(id)` | Reads the stored document: fps, size, duration, tracks, clips, markers. | The document with its metadata |
+| `edit(id, ops)` | Applies up to 60 ops in order and saves. | `{applied, failed, ops, tracks, clips}`. Each entry of `ops` has its own `ok`. |
+| `setDocument(id, document, {fps, width, height, expected_updated_at, snapshot_name})` | Writes a whole document. It is validated first and snapshotted before the write. | The validation of what landed |
+| `validate(idOrDocument, {tier, normalize, fps, width, height})` | Checks the structure without a render. | `{ok, errors, warnings, summary}` |
+| `preview(idOrDocument, opts)` | Composites real frames. | Frames with image handles and layer reports, or one contact sheet |
+| `compare(a, b, {times_ms, range, width})` | Differences the pixels of two sides — each an id, `{timeline_id, version}` or a document; never a shipped-example slug. | A difference from 0 to 1 per frame, and a side-by-side sheet |
+| `render(id, opts)` | Renders the cut to a video file as a job. | `{job_id}`, or the asset with `wait: true` |
+| `versions(id, {save_type, limit})`, `getVersion(id, n)` | Lists and reads snapshots. | Version rows, newest first |
+| `snapshot(id, {name})` (also `createVersion`) | Saves a manual version. Manual versions are never pruned. | The version number |
+| `restore(id, n)` | Rolls back. The state it replaces is snapshotted first, and the result is validated. | The findings |
+| `deleteVersion(id, n)` | Deletes one snapshot. This cannot be undone. | — |
+| `examples.list({query})` | Lists the shipped example timelines. | Slugs, stats, poster and video locators |
+| `examples.get(slug, {scene_id, clip_offset, clip_limit})` | Reads one example scene. | Metadata, a scene catalog and a bounded excerpt |
+| `examples.source(slug)` | Reads the builder script that made an example. | Full JavaScript, imports included |
+| `compositions.list({source, query, limit})`, `compositions.get(id)` | Lists and reads templates: title card, lower third, caption bar, callout, CTA end card, logo sting, and the user's own. | Rows with their parameters |
+| `compositions.save(timelineId, groupTarget, name, params, {description})` | Saves a group as a template. | The composition id |
+| `compositions.remove(id)` | Deletes a saved template. | — |
+| `code.get(id)` | Reads the timeline's authoring code, when it has any. | `{code, baked_at, scenes: [{name, group_id, edited}]}` — `code` is `null` for a timeline with none |
+| `code.set(id, code, {force, require_match})` | Bakes `code` and merges it into the document, scene by scene: an untouched scene is replaced, a hand-edited one is kept and reported in `conflicts` unless `force` overwrites it (`true` for every scene, or an array of names). The bake runs no capability, so `code` must build the timeline from values alone. `require_match: true` attaches the code only if it bakes to exactly the saved document, which is what `v.save()` does. | `{timeline_id, errors, warnings, conflicts, scenes}`, plus `embedded` with `require_match` |
+| `code.edit(id, edits, {force})` | Exact-match string replacements against the stored code (each `old` must match exactly once), then bakes and merges the same way as `set`. The small-diff path for one change. | Same as `set` |
+| `code.rebake(id, {force})` | Reruns the stored code unchanged and merges again — for picking up a shipped example's own current script, or re-applying `force` to a scene left conflicted. | Same as `set` |
+| `code.detach(id, scenes)` | Stops tracking scenes (`scenes` is `"all"` or an array of names) — a later rebake never touches them again. | `{timeline_id, scenes}` |
+
+### Changing a code-backed timeline
+
+For any timeline that already has `code` (`code.get(id).code` is not null),
+the path is: `code.get(id)` → `code.edit(id, edits)` with a few small exact
+replacements → read the `conflicts`/`warnings` it answers → `preview(id,
+{sheet: true})` and look. `edit_timeline` ops still apply, for a timeline with
+no code and for a fine hand tweak on a code-backed one — but a hand edit
+inside a scene the code tracks makes that scene "edited": the next
+`code.set`/`code.edit`/`code.rebake` reports it in `conflicts` and keeps the
+hand-edited version rather than silently overwriting it. Pass `force` (`true`,
+or the scene's name in an array) to overwrite it with the code's own version
+instead of keeping the edit. A new timeline: build it and call `save()` — it
+attaches the retained program, the scene code with every research or
+generation result as a literal, so the timeline is already code-backed and a
+rebake repeats no call. Read `saved.code.warnings` when `embedded` is false.
+Otherwise, or to attach code after the fact, `create`, then `code.set`.
+
+## Coordinates and units
+
+- `transform.position.x/y` is in sequence pixels from the frame **centre**.
+  Positive x moves right and positive y moves down. This holds for every
+  clip, text and shapes included.
+- Shape geometry `shape.x/y/width/height` is in 0..1 fractions of the frame
+  from the **top-left**. It is not the transform position.
+- Masks use the 0..1 space of the clip itself.
+- Track order is z-order: index 0 draws on top. `add_track` appends to the
+  bottom, so add the overlays last or fix the order with `move_track`.
+- Times are in milliseconds. Custom-curve keyframes use `t` from 0 to 1 over
+  the window of the animation.
+
+## Three ways to build
+
+1. **In code, for motion graphics.** Import `@nodetool-ai/sandbox-timeline`:
+   `const v = video({...})` builds scenes of shapes, text and images,
+   keyframed in frames, and `v.save(nodetool.timelines)` saves them in one
+   call. Read `nodetool.packs.docs("@nodetool-ai/sandbox-timeline")`
+   first. This is the path for a dense, layered piece.
+2. **`setDocument`**, for a whole document you already hold. It replaces the
+   stored document field for field, so read `get(id)` and send it back
+   changed. Missing bookkeeping is filled in: track `index`, `visible`,
+   `locked`; clip `sourceType`, `status`, `locked`, `versions`; animation and
+   effect ids; `markers`. Pass `expected_updated_at` to refuse the write when
+   someone changed the timeline after you read it.
+3. **`edit(id, ops)`**, for targeted changes. Start with `{op: "get_state"}` to
+   read the ids. Check `failed` and the `ok` of each entry in `ops` before a
+   dependent edit. A batch
+   can save its good ops even when a later one fails.
+
+```js
+await nodetool.timelines.edit(id, [
+  { op: "add_track", type: "audio", name: "Music" },
+  { op: "add_text_clip", text: "Hi", startMs: 0, durationMs: 2000 },
+  { op: "animate_clip", target: "Hi", animations: [{ role: "in", preset: "fade" }] },
+  { op: "set_effects", target: "Hi", effects: [{ type: "blur", radius: 8 }] }
+]);
+```
+
+Existing media goes on with `{op: "add_media_clip", asset: "asset://<id>.mp4"}`,
+which appends after the last clip on the track. One call for each asset lays
+them end to end. `set_effects` replaces the whole chain, and an unknown effect
+parameter is refused.
+
+## The loop: validate, look, fix
+
+1. **Study an example** before a showcase piece. `examples.list()`, then
+   `examples.get(slug)` for the scene catalog, then
+   `examples.get(slug, {scene_id})` for one scene. Page long scenes with
+   `clip_offset: next_clip_offset` until `truncated` is false. Return only
+   the fields you study; the excerpts are large.
+2. **Validate.** `validate(id, {tier: "showcase"})` adds warnings about the
+   count of scene groups, custom animations per visible second, effect
+   variety, clip density, fast motion without blur, the finish, camera depth
+   and concurrent layers. Each warning names an example. Warnings do not
+   change `ok`. For an inline document, pass `normalize: true` to fill in the
+   bookkeeping as `setDocument` does.
+3. **Look.** Validation cannot judge the picture. Preview real frames:
+   - `times_ms` (up to 8) or `count` (default 3) for single frames.
+   - `range: {from_ms, to_ms, count}` (up to 24) to sweep a move, with
+     `sheet: true` for one labelled contact sheet.
+   - `width` (default 640, max 1280) and `motion_blur_samples` with
+     `shutter_angle`.
+   - The sheet comes back as `sheet.image`. Pass its `asset_id` to
+     `view_image`. Without a sheet, each frame has its own `image`.
+   - Sample the middle of an animation, not its ends.
+   - A frame's `degraded` list names where the preview draws differently from
+     the export, and `effects_not_applied` names effects it cannot draw.
+4. **Fix and compare.** After a change nobody asked for, run
+   `compare({timeline_id: id, version: n}, id)` to prove which frames it
+   touched. A difference of 0 everywhere means the edit was cosmetic.
+5. **Render** before you call the cut done. `render(id, {preview_scale: 0.5})`
+   is a fast draft. `wait: true` blocks up to `timeout_ms` (default 180000,
+   clamped to 300000). On a timeout the job keeps going; wait on it with
+   `nodetool.jobs.wait(job_id)`.
+
+## Render options
+
+`format` is `mp4` (default), `webm`, `mov` or `png_sequence`. Only `webm`,
+`mov` and `png_sequence` carry `alpha`. Also `video_codec`, `bitrate` (a
+number or `"8M"`), `motion_blur_samples` with `shutter_angle`,
+`include_audio` (default true) and `preview_scale`.
+
+## Documents from other surfaces
+
+A storyboard or a script assembles into a timeline of its own media
+(`nodetool.storyboards.assembleTimeline`, `nodetool.scripts.assembleTimeline`).
+For anything else, create your own timeline instead of editing one the user
+has open.

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

@@ -0,0 +1,57 @@
+---
+name: api-web
+description: "Call nodetool.web or nodetool.email from a code action: search the web, news or images, read a page's text, make an HTTP request, download a file into the workspace, screenshot a page, or search, archive and label Gmail messages. Load before the first call into these namespaces."
+---
+
+# nodetool.web and nodetool.email
+
+## nodetool.web
+
+| Call | Does | Answers |
+| :--- | :--- | :--- |
+| `search(query, opts)` | Web search. | Pages with a title, URL and snippet |
+| `news(query, opts)` | News search. | Articles with dates and sources |
+| `images(query, opts)` | Image search. `num_results` defaults to 20. | Title, page link, original image URL and thumbnail URL for each result |
+| `browse(url)` | Fetches a page and strips the HTML. | The readable text |
+| `fetch(url, {method, headers, body})` | One raw HTTP request. `method` defaults to GET. | The response body as text |
+| `download(url, outputFile)` | Saves the bytes of a URL into the workspace. `url` may also be an `asset://` URI, a `/api/storage/` key or a `data:` URI. | The workspace path, an `asset_url`, and for media a `display_markdown` snippet |
+| `screenshot(url, outputFile, {full_page})` | Renders the page in headless Chrome and saves a PNG. `outputFile` defaults to `screenshot.png`. `full_page: true` captures the whole scrollable page. | The workspace path |
+
+Options for `search`, `news` and `images`:
+
+- `provider` pins one backend: `"serpapi"`, `"dataforseo"`, `"brave"`,
+  `"apify"`, `"openai"` or `"google"` (Gemini grounded search, or SerpAPI for
+  `news`). Without it the call uses the first configured backend.
+- `images` cannot use `"openai"` or `"google"`, because they answer with prose
+  instead of results.
+- `allowed_domains` and `blocked_domains` scope the results.
+- `num_results` sets how many come back (10 by default for web and news).
+
+Rules:
+
+- Search result pages are blocked in `browse`. Use `search` to search, and
+  `browse` to read a page it found.
+- `download` is how an asset reaches the workspace, for ffmpeg or a document
+  conversion. To keep a downloaded file in the library, pass its `asset_url`
+  to `nodetool.assets.save(name, {source})`.
+- When you show a downloaded image to the user, paste `display_markdown` as it
+  is. Do not build a link from the workspace path.
+- Fan out independent lookups with `Promise.all`. Ten searches take one round
+  trip:
+
+```js
+const hits = await Promise.all(topics.map((t) => nodetool.web.search(t)));
+```
+
+## nodetool.email
+
+Gmail, when the account is connected.
+
+| Call | Does |
+| :--- | :--- |
+| `search({subject, text, since_hours_ago, max_results})` | Finds messages. `since_hours_ago` defaults to 6 and `max_results` to 50. Each result has `message_id`, `subject`, `sender` and `body`. |
+| `archive(messageIds)` | Archives one id or an array of ids. |
+| `label(messageId, label)` | Adds a label to one message. |
+
+Archiving and labelling change the user's mailbox. Declare the action as
+high risk unless the user asked for exactly that change.

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

@@ -0,0 +1,123 @@
+---
+name: api-workflows
+description: "Call nodetool.workflows, nodetool.jobs or nodetool.nodes from a code action: list, validate, save, run, debug and version workflow graphs, wait on background jobs, and look up or probe node types. Load before the first call into these namespaces."
+---
+
+# nodetool.workflows, nodetool.jobs, nodetool.nodes
+
+These three namespaces cover saved graphs, the runs they start, and the node
+catalog a graph is built from. How to design a graph is
+`nodetool-workflow-builder`. This skill is the call reference.
+
+Every method takes an id as the full id or its 12-character prefix, and every
+method throws when its backing tool is not on this belt.
+
+## nodetool.workflows
+
+| Call | Does | Answers |
+| :--- | :--- | :--- |
+| `list({workflow_type, query, limit})` | Lists workflows. `workflow_type` is `"user"` (default), `"example"` or `"all"`. | `{workflows: [{id, name, description, tags}]}` — an envelope, not an array |
+| `get(id)` | Reads one workflow with its graph. | The workflow record |
+| `create(name, graph, {description, tags, access, project_id})` | Saves a new workflow. `graph` is a DSL result, `{nodes, edges}`, or a workflow record. `create({name, graph})` also works. | The saved workflow with its `id` |
+| `validate(idOrGraph)` | Checks a graph against the node registry without a run. | `{ok, issues}`. Throws when the graph has errors, so a broken graph cannot reach a paid run. |
+| `run(id, params, {interactive, node_ids, reuse_results})` | Runs and blocks until the run settles. | The run result. With `interactive: true`, a failed node returns `status: "escalated"`. |
+| `start(id, params, {node_ids, reuse_results})` | Starts a run and returns at once. | A receipt `{job_id, id, status: "running"}` |
+| `debug(id, params, {interactive, node_ids, reuse_results, include_graph, log_limit})` | Runs and reports. | `{workflow_id, run, job, workflow}`. An escalated debug answers `{workflow_id, run}` with the escalation under `run`. |
+| `resolve(sessionId, escalationId, action, {outputs, reason, apply_to})` | Answers an escalation. | The next escalation, or the final report |
+| `example("<package>/<name>")` | Loads a shipped example with its graph. A bare name reads from `nodetool-base`. | The example workflow |
+| `versions(id, {limit})`, `getVersion(id, n)` | Lists and reads snapshots. | Version rows, newest first |
+| `snapshot(id, {name, description})` | Saves the current graph as a manual version. | The new version number |
+| `restore(id, n)` | Rolls the graph back. The graph it replaces is snapshotted first, so a restore can be undone. | — |
+| `deleteVersion(id, n)` | Deletes one snapshot. This cannot be undone. | — |
+| `open(id?)` | Opens the editable object model of a graph that is open in the editor. Throws when no editor tools are on the belt. | A workflow object: `addNode`, `connect`, `commit()` |
+
+`node_ids` runs only those nodes and what they need upstream. Unrelated
+branches and downstream nodes are not executed or billed. An upstream
+generator that already produced output in this workflow is fed that output
+instead of running again, unless `reuse_results: false`. This is the cheapest
+way to re-run one repaired node.
+
+### The debug report
+
+`debug` answers `{workflow_id, run, job, workflow}`:
+
+- `run.status` is the verdict of the run, and `run.error` names the failure.
+- `run.outputs` is keyed by output name. Each name holds an **array** of the
+  values it emitted, so read `run.outputs.summary[0]`, not `run.outputs.summary`.
+- `run.verdict.issues` lists what went wrong, node by node.
+- `job` carries the status, the cost and the logs.
+
+### Escalations
+
+An interactive run parks on a failed node and answers `status: "escalated"`
+with a `session_id`, an `escalation_id` and `escalation.allowedActions`. The actions
+are `retry`, `substitute` (with `{outputs}`, only when the escalation has a
+`candidateOutput`), `skip`, `end_stream` and `fail` (with `{reason}`).
+`apply_to: "signature"` also answers later failures with the same signature.
+`run` answers the escalation at the top level. `debug` nests it under `run`,
+so drive the loop with `run`. `resolve` answers the next escalation or the
+final report, both at the top level. Write the whole loop in one action:
+
+```js
+let report = await nodetool.workflows.run(id, params, { interactive: true });
+while (report.status === "escalated") {
+  report = await nodetool.workflows.resolve(report.session_id, report.escalation_id, "skip");
+}
+return { status: report.status, error: report.error, issues: report.verdict?.issues };
+```
+
+An unanswered escalation fails the run when its decision timeout expires.
+
+### Rules
+
+- A saved graph is not a run. When the user asked for results, call `run`.
+- Validate before `create` and before a paid run. `validate` throws on errors,
+  and its message lists the errors only.
+- A `*_model` property left unset fails validation. Assign
+  `(await nodetool.models.pick(capability)).ref`.
+- `create` checks model properties. An unknown provider or model id is refused
+  and not saved.
+
+## nodetool.jobs
+
+A job is one execution of a workflow, and a render of a timeline is a job too.
+
+| Call | Answers |
+| :--- | :--- |
+| `list({workflow_id, limit})` | Job rows with status, timing, error and the names of the outputs. The values are not in the list. |
+| `get(idOrReceipt)` | One job, with the outputs once it has settled |
+| `logs(idOrReceipt, {limit})` | The log tail. It answers for a failed job too, with the failure under `job_error`. |
+| `wait(idOrReceipt, {timeoutMs, pollMs})` | Polls until the status is `completed`, `failed`, `cancelled` or `error`, then answers the job. On a timeout it throws with the last status. |
+
+Every call takes the id string or the receipt that `start()` answered.
+Start, do other work, then wait, all in one action:
+
+```js
+const receipt = await nodetool.workflows.start(id, { prompt: "a fox" });
+// … other work in the same action …
+const settled = await nodetool.jobs.wait(receipt, { timeoutMs: 300000 });
+return { status: settled.status, outputs: settled.outputs };
+```
+
+Do not write one `get()` per action. `wait` is the polling loop. A code
+action stops after 600 s, so keep `timeoutMs` well under 600000 and call
+`wait` again in the next action when the job is still running.
+
+## nodetool.nodes
+
+| Call | Does | Answers |
+| :--- | :--- | :--- |
+| `search(query, {n_results, namespace, input_type, output_type, include_provider_nodes})` | Searches the catalog. `query` is a string or an array of terms. | `{total, results}`. The node type of a result is on `type`, not `node_type`. |
+| `info(type)` | Reads one node type: properties, inputs, outputs, defaults. | The node metadata |
+| `list({namespace, limit})` | Browses a namespace. An unknown namespace answers with the namespaces that exist. | Node rows |
+| `run(type, inputs)` | Runs ONE node with a property bag, with no workflow. | The outputs, keyed by slot |
+
+- Never guess a node type. Search, then read `info` for the exact property
+  names before you wire the node.
+- Provider nodes (`openai.*`, `fal.*` and others) are hidden unless you pass
+  `include_provider_nodes: true`. Pass it only when the user named a provider.
+- `run` is the cheapest probe of what a node does. Try one node before you
+  put it in a graph.
+- To call nodes as functions inside an action, import them from
+  `@nodetool-ai/sandbox-flow`. To author a graph, import them from
+  `@nodetool-ai/sandbox-dsl`. `nodetool-js-scripting` covers both packs.

package/dist/_skills/beat-sync-editing/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: beat-sync-editing
+description: Cut a NodeTool timeline to music and shape its pacing — detect the beat grid, place cuts on phrases, pick a cut type, build speed ramps with time remap, and give the piece an arc. Use when clips should land on the music, when pacing drags or feels choppy, when a hit needs impact, or when transitions feel arbitrary. Not for what each shot contains.
+---
+
+# Beat-Sync Editing → cuts, rhythm and retiming
+
+Where a cut lands matters as much as what is on screen. This turns a track and a
+brief into millisecond cut points on the timeline.
+
+`motion-direction` sets the energy; this turns it into a grid and an arc.
+`timeline-edit-ops` carries the op contract for the calls named here.
+`video-audio-continuity` decides where the bed comes from before there is a
+grid to read: a track you add yourself, or one generated clip carrying every
+scene.
+
+## Get the grid from the audio, not from arithmetic
+
+When the bed does not exist yet, generate it with the grid in mind: a Stable
+Audio prompt states its BPM (`stable-audio-prompting`), and an ElevenLabs
+`composition_plan` pins each section's length in milliseconds
+(`elevenlabs-audio-prompting`), so the drop lands where the plan says instead
+of where the model felt like putting it. Then measure it anyway — the
+generated file, not the prompt, is the grid.
+
+`detect_audio_events` on the music clip reports onsets and a tempo.
+
+- `onsets.times` are in **seconds**. Every timeline op takes milliseconds, so
+  multiply by 1000. This is the single most common mistake here.
+- Read `tempo.reliable` before you build anything off `bpm`. Speech and room
+  tone produce a confident-looking number from nothing. Unreliable means use the
+  onsets directly.
+- The first onset is the grid's offset. A grid anchored at 0 instead of beat one
+  puts every cut a few frames early — the edit that feels "almost right".
+
+With a reliable tempo:
+
+```
+ms_per_beat = 60000 / bpm
+frames_per_beat = (60 / bpm) × fps          # fps comes from get_timeline
+```
+
+At 120 BPM: 500ms a beat, 15 frames at 30fps, a 2000ms bar. Round each
+**cumulative** beat, never the step, or the grid drifts over a long edit.
+
+Lay the grid down so you can see it, then pull edges onto it:
+
+```json
+{"op": "set_markers_from_beats", "bpm": 120, "offset_ms": 0, "count": 32}
+{"op": "snap_to_beats", "targets": "all", "tolerance_ms": 60,
+ "mode": "start", "action": "move"}
+```
+
+Either takes `onsets_ms`, or a `bpm` with an `offset_ms`. With `bpm`,
+`set_markers_from_beats` also needs `count`, the number of beats to mark. An
+`onsets_ms` grid lays one marker per onset and ignores `count`. The 60ms default
+tolerance is about two frames at 30fps — close enough to read as on the beat,
+tight enough not to drag an edge onto a beat it was never near. `snap_to_beats`
+reports every target including the ones nothing was in reach of, with the reason.
+`action: "move"` keeps the clip's length and shifts what follows; `action:
+"trim"` changes the length and leaves the neighbours alone. Move a title that has
+to land on a hit; trim a picture clip whose out point has to meet the next shot.
+
+For an animation that should follow tempo changes, store a `beat` anchor on the
+animation: `{index: 3, scope: "clip", offsetMs: -20}` counts from the clip's
+start; `scope: "sequence"` counts from the document tempo's `offsetMs`.
+`index` is one-based, and `delayMs` adds another offset. This is distinct from
+snapping a clip edge or baking a measured audio curve. `animate_clip` does not
+accept `beat` in its tool input; write the animation's `beat` through the full
+document with `set_timeline_document`. A stored animation needs its `id`,
+`role`, `preset`, and `durationMs`; keep those and the rest of the animation
+when adding `beat`. Keep the document's tempo, setup, media tracks, template
+identity, clips, tracks, and markers in the write.
+
+## Cut on phrases, not on beats
+
+A cut on every beat is relentless and the viewer fatigues by beat eight. Cut on
+2, 4 or 8 beats, and accent on the eighth grid sparingly.
+
+| Personality | Cut every | Transition family | Retime |
+|---|---|---|---|
+| Playful | 4 beats, syncopated accents | Hard cut, occasional `push` | Light ramps |
+| Premium | 8–16 beats, long holds | Hard cut, occasional `crossfade` | Slow, smooth |
+| Corporate | 8 beats, steady | Hard cut only | None |
+| Energetic | 1–2 beats at the peak | Hard cut, `zoom`, `push` | Aggressive, on the beat |
+
+Put the single biggest visual on the drop. One piece, one peak.
+
+## Shape an arc
+
+Uniform pacing reads as flat regardless of content.
+
+| Phase | Cut every | Shot length | Note |
+|---|---|---|---|
+| Establish | 8–16 beats | Longest | Set the place, let it breathe |
+| Develop | 8 → 4 beats | Shortening | Accelerate to build |
+| Climax | 1–2 beats | Shortest | The drop, the biggest visual, the ramp |
+| Resolve | One long hold | Longest | The end card breathes after the peak |
+
+## Hide the seam
+
+A cut is invisible when motion carries the eye across it. Cut during a movement,
+and match its direction and speed across the cut. For graphics, cut at a
+transform peak — mid-travel, not at rest.
+
+Default to the hard cut: two clips on the same track, meeting exactly. Reach for
+anything else only when it is motivated.
+
+| Cut | How, on the timeline | Reach for it when |
+|---|---|---|
+| Hard cut | Adjacent clips, no overlap, no `set_transition` | Nine cuts in ten |
+| Match cut | Hard cut where both frames share a shape, position or motion vector | Two shots rhyme; the strongest move in motion design |
+| Crossfade | `set_transition` `crossfade` on the incoming clip, clips overlapped by at least its `durationMs` | Two shots of the same scene |
+| Dip | `dipToColor` with your own `color` | A chapter break |
+| Wipe / push / slide | Those types with a `direction` naming the edge the incoming clip arrives from | A graphic feel, or lateral energy |
+| Zoom | `zoom` | Pushing into the next beat |
+| J-cut | The next clip's audio clip starts 4–12 frames before its picture, on its own audio track | Dialogue, reveals: it pulls the viewer forward |
+| L-cut | The current clip's audio runs 12–24 frames under the next picture | Scene changes, ambience |
+| Whip | A short `offsetX` move plus a `blur` effect either side of a hard cut | Hype, a scene jump |
+
+Two things the engine does whether you asked or not:
+
+- Two clips on one track whose times overlap dissolve across the overlap with no
+  call at all. **An accidental overlap is an accidental dissolve.** When a cut
+  looks soft where you wanted it hard, check `startMs` and `durationMs` first.
+- A transition plays over the incoming clip's head against whatever is beneath
+  it. With no overlap there is nothing under it and it reads as a fade from
+  black.
+
+J and L cuts are built by splitting picture and sound onto separate clips, not
+by a transition: the shot's audio twin already sits on its own audio track after
+an assemble, so move that clip rather than the picture.
+
+## Speed ramps
+
+`set_time_remap` maps timeline time onto source time. `t` runs 0..1 over the
+clip's own window, must start at 0, end at 1 and ascend; `sourceMs` says which
+millisecond of the source plays there. Descending `sourceMs` is a reverse, a flat
+pair is a freeze.
+
+Ramp into a hit and snap out, with the slowest frame on the beat. On a 2000ms
+clip whose impact sits at 1200ms:
+
+```json
+{"op": "set_time_remap", "target": "Shot 3", "timeRemap": {"keyframes": [
+  {"t": 0, "sourceMs": 0},
+  {"t": 0.5, "sourceMs": 900, "easing": "easeIn"},
+  {"t": 0.6, "sourceMs": 1000, "easing": "easeOut"},
+  {"t": 1, "sourceMs": 2400}]}}
+```
+
+Between 0.5 and 0.6 the source advances 100ms across 200ms of timeline: half
+speed on the hit. `t` that repeats or goes backwards is
+`time_remap_not_monotonic`, an error. `split_clip` and `trim_clip` refuse a
+remapped clip, because re-deriving the curve silently is how a ramp becomes a
+different move — clear the remap, cut, re-apply.
+
+`speedMultiplier` on `set_clip_params` is the flat alternative: one rate for the
+whole clip, no curve. Use it when nothing needs to ramp.
+
+For rhythmic texture, `steppedTime: {fps}` quantizes one clip's sampling
+clock. `temporalEcho: {copies, intervalMs, opacityDecay}` draws delayed copies,
+which can trail a hit without duplicating clips by hand. A clip's `motionBlur`
+sets `samplesPerFrame` and `shutterAngle` for its own shutter window. Values
+above one request a minimum scene sample count; the scene uses the highest
+request, capped at 32, and samples each layer evenly over its own shutter.
+Set these fields in the full timeline document. `set_clip_params` refuses them.
+
+If motion must follow the actual audio envelope or detected onsets, use
+`bake_audio_animation`. It writes a source-anchored curve with `bakedFrom`
+provenance through `set_baked_animation`; re-baking replaces that measured
+curve. A beat anchor instead recomputes timing from the document tempo, while
+markers and `snap_to_beats` move edit points.
+
+## The plan, before the calls
+
+Write the cut down before editing, in the units the ops take:
+
+- Track spec: `bpm`, `fps`, the first onset in ms, the drop in ms, ms per beat.
+- The four phases with their ms ranges and target shot length.
+- Every cut as an absolute ms, its clip, and its cut type.
+- Audio offsets in ms for each J and L cut.
+- Each ramp as its `t` / `sourceMs` keyframes.
+- The marker list you will pass to `set_markers_from_beats`.
+
+## Check it
+
+`validate_timeline` after every batch: it catches overlapping clips, a
+transition longer than the clip carrying it, and clips shorter than a frame.
+
+Then look and listen. `preview_timeline_frame` at the ms either side of a cut
+says whether the seam is where you think it is; `analyze_audio` on the music
+confirms the grid you built matches the file. Before calling the cut done,
+`render_timeline` — a preview answers what one timecode looks like, a render
+answers whether it plays.
+
+## Common mistakes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Frantic | A cut on every beat | Cut on 2, 4 or 8 beat phrases |
+| Almost on beat | Grid anchored at 0, ignoring the first onset | Anchor to the onset, in ms |
+| Drift over a long edit | Rounding each step | Round each cumulative beat |
+| Jarring cut | Placed at rest, between motions | Cut mid-motion, match direction |
+| Soft where it should be hard | Overlapping clips on one track | Fix `startMs` and `durationMs` |
+| Transition fades from black | Nothing beneath the incoming head | Overlap the clips by the transition's `durationMs` |
+| Flat | Uniform pacing | Establish, develop, climax, resolve |
+| Nothing lands | No single peak | One biggest visual, on the drop, then a hold |

package/dist/_skills/caption-titles/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: caption-titles
+description: Add and animate a consistent text layer on an existing NodeTool timeline. Use for titles, lower-thirds, captions, callouts, end cards, number tickers, deterministic scrambles, and text on a path.
+featured: true
+---
+
+# Caption & Titles → Timeline Agent
+
+Work directly with timeline capabilities and open-timeline tools. Do not build a workflow or fabricate a cut.
+
+`timeline-edit-ops` carries the op contract for every call named here. `motion-principles` gives the entry and exit durations and easing behind each tier's presets, `frame-composition` fixes the safe inset and where a tier sits, `color-motion` the scrim and contrast fixes when type does not read, and `logo-reveal` owns the brand mark at the head or tail.
+
+## Type is post, never a render prompt
+
+Every board skill and every video prompting skill sends its on-screen copy here. A title card, a super, a lyric or a CTA is a text clip on the timeline, not words in a `generate_video` or `generate_image` prompt: generators letter unreliably, and copy baked into pixels cannot be corrected, translated or re-timed. When a board's shot `action` carries `Text: …`, that is the caption map's input, and the render prompt should not have asked for it.
+
+## Hard gate
+
+List and read the selected timeline first. When the job is to caption or title footage, the timeline must contain picture clips. If it is missing or has none, stop and ask for a real cut; route users to storyboard or script-to-timeline work instead. A typographic piece built from type and shapes alone, such as a title sequence, kinetic text or a standalone end card, needs no picture clips: build it through `motion-graphics` and use the tiers below for its type. Snapshot the timeline before editing with `create_timeline_version`.
+
+Read `fps`, `width` and `height` off `get_timeline` before setting a size: `fontSizePx` is authored against the sequence resolution, and the tiers below are fractions of `height`.
+
+## Lock one type system before adding text
+
+Resolve type family and tier weights, five size tiers as fractions of frame height, text/accent/scrim palette, safe inset and maximum width, and per-tier motion presets. Prefer a supplied brand kit, then existing text on the timeline, then a platform-safe system. Keep these tiers consistent: T1 title/end card, T2 lower-third, T3 captions, T4 callouts, T5 CTA.
+
+The family is one NodeTool ships — `Inter`, `Space Grotesk`, `Bebas Neue`, `Playfair Display`, `Lora`, `JetBrains Mono` — or every host resolves it against its own installed fonts, the editor and the render disagree on line widths, and `validate_timeline` reports `font_not_portable`. Sizes below 2.5% of frame height report `text_illegible`; body copy sits at 2.5–4%. `motion-direction` holds the same rule for the whole piece, so when a motion language already exists, take its type family rather than picking a second one.
+
+Motion per tier follows `motion-principles`: `fade` or `slide` in at 300–500ms, out at 200–300ms, role-default easing. Stagger only on a T1 or a kinetic T3 line of five words or fewer, and work out the span (`durationMs + offsetMs × (words − 1)`) against the clip — a span that does not fit is compressed silently and only `stagger_compressed` says so.
+
+Each tier has a shipped composition. Insert it with `{"op": "insert_composition", "composition_id": "<id>", ...}` and override its `params` rather than building the rig from bare clips — the timing and motion inside it are already balanced.
+
+| Tier | Composition id |
+|---|---|
+| T1 title | `title-card` |
+| T2 lower-third | `lower-third` |
+| T3 captions | `caption-bar` |
+| T4 callouts | `callout` |
+| T5 CTA / end card | `cta-end-card` |
+
+A brand mark at the head or tail is `logo-sting`.
+
+Every live-picture T2–T4 element gets a matching scrim unless the plate is demonstrably controlled.
+
+## Caption map
+
+Write the timed map before editing: tier, exact text, start/end, position, and scrim. Caption duration is at least `max(1200ms, words × 350ms)`. Titles/end cards stay on screen at least 2000ms, which leaves the read hold `motion-principles` § Holds sets between their in and out. Lower-thirds arrive about 500ms after a person appears and hold 2500–4000ms. One text idea per frame. Unknown facts use `[INPUT NEEDED: …]`.
+
+## Animate the letters and their content
+
+For a number that changes during a text clip, store `textAnimator` on an
+animation with `kind: "ticker"`, `from`, and `to`. It also accepts `decimals`,
+`padTo`, `prefix`, and `suffix`. Set `groupSeparator` to `","` to show
+thousands as `2,847`; omitting it keeps existing tickers ungrouped. For a
+deterministic decode into the clip's
+authored text, use `kind: "scramble"` with a fixed `seed` and optional
+`charset`. These operate over the animation window, so a held final frame
+shows the finished value.
+
+```json
+{"id": "count-in", "role": "in", "preset": "fade", "durationMs": 900,
+ "textAnimator": {"kind": "ticker", "from": 1, "to": 7,
+  "padTo": 2, "suffix": " / 07"}}
+```
+
+For unit-by-unit motion, set `stagger.unit` to `character`, `word`, or `line`
+and give it `offsetMs`. With a text stagger, `styleTracks` can target
+`glyph.color`, `glyph.blurPx`, or `glyph.trackingPx`. The colour uses CSS
+colour values; blur and tracking use sequence pixels. Use `text.color` or
+`text.fill.stops.0.color` for a whole line. A text fill gradient also exposes
+`text.fill.angle` and stop offsets. The target must refer to an existing
+style field; `text.color` is hidden while a gradient fill is set.
+
+To lay a title along a curve, set `textStyle.path` to an SVG path in
+normalized canvas coordinates. This places the baseline on the path. It does
+not make each character travel along it. Shape and mask paths can morph through
+`shape.d` and `mask.d` style tracks when both paths have matching commands and
+point counts. Use `followPath` when the whole clip should move along a path.
+
+`edit_timeline`'s `animate_clip` input accepts presets and custom numeric
+curves, but does not accept `textAnimator` or `styleTracks`; those fields are
+dropped from that call. To author them, read the current document and use
+`set_timeline_document` with the animation fields in the clip. That call
+validates the complete document and snapshots the previous state. Preserve
+the other tracks and clips from the document. `timeline-edit-ops` owns the full
+tool contract.
+
+## Build and verify
+
+Add separate overlay and subtitle tracks. For each map item, add scrim before text, apply the locked tier style, then animate it with that tier’s entry and exit preset. No hard cut-on. Use stagger only for tone-appropriate kinetic captions. Keep all text within safe margins and clear of faces and product moments.
+
+Two facts about stacking decide whether the text is seen at all. The lowest track `index` draws on top, so the scrim's track index sits between the picture's and the text's — picture, scrim, text, in descending index. And word-level captions generated from a voiceover clip composite above every real track regardless of where that clip sits, so no title can cover them: time a T1 around the narration rather than over it.
+
+Verify in two passes, and they answer different questions. `validate_timeline` reads the document: `text_illegible` (size, or under 3:1 contrast against the text's own `background` plate or a full-frame shape behind it), `font_not_portable`, `stagger_compressed`, `animation_exceeds_clip`, overlaps, and clips shorter than a frame. Its contrast check refuses to guess — a translucent scrim, gradient type or a plate it cannot prove is behind the text produces no finding — so a silent pass is not a pass. Then `preview_timeline_frame` at each item's entry midpoint, a held moment, and its exit: that is where text over a busy plate, a scrim covering a face, or a caption still finishing when its clip ends shows up. Re-read the map against the frames: timing, reading floors, scrim ordering, one CTA at the end. Then render with `render_timeline` before calling the layer done, as `timeline-edit-ops` § The render loop describes: the frames show one timecode, the render shows the timing at speed.