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

package/dist/.nodetool-build-stamp

@@ -1 +1 @@
-2026-10-16T18:28:40.528Z
+2026-10-17T23:28:01.323Z

package/dist/_skills/LICENSE-iart-motion-design-skills

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iart.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/_skills/README.md

@@ -0,0 +1,211 @@
+# System skills
+
+The instruction documents NodeTool ships. A user skill is a row somebody wrote
+and can rewrite; a system skill is a `SKILL.md` in the build — same shape in the
+prompt, immutable, and present on every install with no seeding migration to
+drift. Loader and discovery rules live in
+`packages/agents/src/system-skills.ts`.
+
+One directory per skill, holding a `SKILL.md` whose frontmatter `name` matches
+the directory. Nothing imports these files, so this is not a workspace:
+`stageSystemSkills` in `scripts/bundle-backend.mjs` copies every directory here
+into `_skills/` beside the bundled `server.mjs`, and
+`scripts/verify-backend-bundle.mjs` fails a build that misses one. A new
+directory ships with no other change.
+
+`SKILL.md` is the whole skill. Only that file is staged and only that file is
+read, so material that would have been a `references/` file goes in a `##`
+section of the body, which `load_skill` returns in one piece.
+
+A skill the repository's own coding agent also wants is symlinked, not copied:
+`.claude/skills/<name>` points here. `npm run check:agents-docs` fails on a
+second copy, a broken link, a frontmatter name that disagrees with its
+directory, and a file beside `SKILL.md` — the last two are mistakes the loader
+would otherwise absorb in silence, leaving the skill out of the catalog with no
+error anywhere.
+
+## What the prompt carries
+
+Every turn carries a catalog of the user's own skills and of the shipped
+skills whose frontmatter says `featured: true`. The others are named by count
+and found with `list_skills({query})`, which matches a query word by word. The
+catalog is rendered by `formatSkillCatalogForPrompt` in
+`packages/agents/src/skill-prompt.ts`. Feature the entry point of each
+surface. Of the motion skills, only `motion-graphics`, `caption-titles` and
+`video-audio-continuity` are featured: `motion-graphics` loads the craft skills
+it needs, so their catalog lines would buy no routing. The model guides are
+reached through `find_model`, and the brief shapes, `api-*` references and
+`native-game-reference` through the skills and prompt lines that point at them.
+
+## The object-model references
+
+One `api-*` skill for each area of the `nodetool` object model that code
+actions call. The prompt lists each namespace as a line of signatures and
+names its skill; the skill holds every option, return shape and example.
+`NAMESPACE_DOCS` in `packages/agents/src/codeact/nodetool-api.ts` maps a
+namespace to its skill.
+
+| Skill | Namespaces |
+| :--- | :--- |
+| `api-workflows` | `workflows`, `jobs`, `nodes` |
+| `api-models` | `models` |
+| `api-media` | `media`, `generations` |
+| `api-assets` | `assets`, `documents` |
+| `api-web` | `web`, `email` |
+| `api-memory` | `memory`, `shared`, `threads` |
+| `api-agents` | `agents` |
+| `api-settings` | `settings`, `secrets` |
+| `api-collections` | `collections` |
+| `api-apps` | `apps` |
+| `api-timelines` | `timelines` |
+| `api-sketches` | `sketches` |
+| `api-scripts` | `scripts` |
+| `api-storyboards` | `storyboards` |
+| `api-games` | `games` |
+| `nodetool-troubleshooter` | `runs` |
+
+## The surfaces
+
+One skill per NodeTool document kind, for the agent inside the product and the
+one working on this repository alike.
+
+| Skill | Surface |
+| :--- | :--- |
+| `nodetool-workflow-builder` | Workflow graphs, and the routing table for when a graph is the wrong document |
+| `nodetool-app-builder` | Mini apps: operations, widgets, bindings, variables, resources |
+| `nodetool-sketch` | Sketches (image documents): layers, blend modes, placed images, briefs, versions |
+| `nodetool-3d-scene` | glTF models: objects, transforms, lights, materials, headless Blender renders |
+| `manimgx` | ManimGX scenes: math and 3D animations in Python, inspected and rendered by the `nodetool.manimgx` nodes |
+| `nodetool-js-scripting` | The QuickJS sandbox: Code node bodies, JS script documents, packs, calling nodes from code |
+| `nodetool-video-post` | Repairs on delivered footage, and the candidate review protocol they return |
+| `nodetool-rag-indexing` | Ingestion, vector collections, retrieval, the RAG loop |
+| `nodetool-browser-agent` | Browser automation agents: navigation, extraction, forms |
+| `nodetool-custom-node-developer` | New TypeScript node types and node packages |
+| `nodetool-model-provider-config` | Providers, credentials, local models, model selection |
+| `nodetool-api-reference` | REST, tRPC, MsgPack WebSocket, MCP, the OpenAI-compatible chat API |
+| `nodetool-chat-cli` | Chat CLI sessions, provider selection, Global Chat |
+| `nodetool-deployment` | Servers and workers: Docker, SSH, Runpod, cloud |
+| `nodetool-troubleshooter` | A failing run, routed to the surface it belongs to, and stuck generations |
+| `nodetool-skill-author` | Writing a user skill row or a shipped one |
+| `storyboard-core` | Storyboards, entity casting, rendering, timeline assembly — the contract the job and board skills quote |
+| `native-game` | Built-in games, generated asset installation, and playtests |
+| `native-game-reference` | The game document in detail: schema versions, scripts, visuals, physics, audio, input, HUD |
+| `game-direction` | Game feel, teaching beats, layered art, and completion evidence |
+
+The job skills that sit on `storyboard-core`, each one a brief shape rather
+than a tool contract: `ugc-video`, `product-commercial`, `script-video`,
+`short-film`, `video-clone`, `launch-kit`, `video-workflow`, `motion-ad`.
+`motion-ad` is the one that renders nothing by default: its board holds the
+real product images as stills and its motion is built on the timeline. Each
+job skill pairs with a board skill for structure: `ugc-video` and
+`product-commercial` with `commercial-beat-sheet`, `script-video` with
+`explainer-storyboard`, `short-film` with `trailer-template`.
+
+## The craft and the model lines
+
+| Skill | Answers |
+| :--- | :--- |
+| `motion-graphics` | The build loop, choosing between the code pack and edit ops, and the review pass |
+| `timeline-edit-ops` | The `edit_timeline` op contract: roles, presets, transitions, groups, masks, mattes, effects, validate and preview |
+| `motion-curves` | Custom animations — curves by hand, or a JS body baked in the sandbox |
+| `motion-principles` | Durations, easing, stagger, weight, anticipation — the numbers before the call |
+| `motion-direction` | The motion language a whole piece obeys, and the audit against it |
+| `frame-composition` | Grids, focal placement, safe areas, depth and parallax, camera moves |
+| `beat-sync-editing` | The beat grid, cut types, pacing arc, speed ramps |
+| `color-motion` | Palettes, gradient fills, the grade chain, which colour channels move |
+| `logo-reveal` | Stings: draw-on, wipe, build, wordmark, sound-logo sync |
+| `motion-background` | Ambient beds that loop and stay behind |
+| `caption-titles` | What on-screen text says and when it appears |
+| `video-audio-continuity` | Sound across a multi-scene cut — one clip carrying every scene, or a track of your own |
+| `explainer-storyboard`, `commercial-beat-sheet`, `launch-commercial`, `music-video-treatment` | Board shapes for four brief types |
+| `trailer-template` | Trailers and teasers: eight audio-first beats on a runtime-scaled grid, event/reception pairs, the drop at ~65%, one unbroken music bed |
+| `nano-banana-pro-prompting` | Nano Banana Pro: the art-director brief, and lock/change/amount/constraints for edits |
+| `gpt-image-2-prompting` | GPT Image 2: five slots, change-versus-preserve edits, labelled multi-image compositing |
+| `flux-2-klein-prompting` | FLUX.2 [klein]: the subject-first hierarchy, guidance and step choices, the seed-locked loop |
+| `seedance-2-prompting` | Seedance 2: subject and motion first, quoted dialogue, the sound brief, cuts in one take |
+| `veo-3-prompting` | Veo 3: the five-element structure, cinematography vocabulary, duration and audio economics |
+| `minimax-h3-prompting` | MiniMax H3: which endpoint, a job per reference, timed shot lists, native audio direction |
+| `wan-2-6-prompting` | Wan 2.6: text-to-video and image-to-video, and the prompt shape each one wants |
+| `kling-video-prompting` | Kling 2.5-turbo and later: the shot list, tagged elements, the labelled dialogue format |
+| `hailuo-prompting` | MiniMax Hailuo: beats in order, the Director bracket commands, no negative prompt |
+| `seedream-prompting` | Seedream 4 and 5: the six-layer brief, quoted copy, pinning what an edit must not change |
+| `qwen-image-prompting` | Qwen-Image: typography — exact copy, relative layout, non-Latin scripts, expansion off |
+| `elevenlabs-audio-prompting` | ElevenLabs: audio tags and stability, the dialogue list, sound-effect briefs, composition plans |
+| `stable-audio-prompting` | Stable Audio: genre/instruments/mood/BPM, the TrackType tags, which dials the distilled checkpoints ignore |
+
+The `*-prompting` skills are the model-line guides. None is featured, so the
+catalog does not list them. `find_model` attaches `prompting_skill` to a
+matching route so the guide surfaces at the step before the prompt is written,
+and each description names the model ids across every provider that serves the
+line, so `list_skills` finds the guide by model id. The table behind
+`prompting_skill` is `MODEL_PROMPTING_SKILLS` in
+`packages/agents/src/model-prompting-skills.ts`, and
+`packages/agents/tests/model-prompting-skills.test.ts` checks it against the
+skills on disk, the model ids the shipped provider manifests actually name, and
+the capability registry. A new line means a directory here plus a row there.
+
+`motion-graphics` carries the mechanics and the other motion skills carry the
+craft. A skill quotes calls rather than teaching them, and a renamed tool leaves
+it teaching a spelling no model can use, so
+`packages/agents/tests/shipped-skill-names.test.ts` reads every snake_case call
+out of every skill in this directory and checks it against the registry. A new
+directory is covered with no entry to add.
+
+It checks at two strengths. The motion skills its `SKILL_NAMES` lists are
+matched exactly against the capability specs and `edit_timeline`'s op list, and
+`motion-graphics` together with `timeline-edit-ops` has to name every shipped
+preset and stagger unit. Every other skill is matched against the vocabulary
+the registry declares in structured form: tool names, schema keys and enums,
+the op lists that `edit_sketch`, `edit_model3d` and `edit_storyboard` write
+into their `ops` fields, and the WebSocket commands. Free prose in a spec does
+not count, so a stale name that a spec merely mentions still fails. A call that is neither is exempted by name in
+`NOT_A_BACKEND_CALL`, with the reason it is not a rename waiting to happen.
+
+## How the set routes
+
+One job crosses the whole set in a fixed order, and each skill hands off at
+the same seams:
+
+1. **Brief → board.** A board skill (`commercial-beat-sheet`,
+   `launch-commercial`, `explainer-storyboard`, `music-video-treatment`,
+   `trailer-template`) resolves entities, writes the beats and stores them
+   with `create_storyboard` / `edit_storyboard`. A job skill on
+   `storyboard-core` decides what the picture looks like over the same board,
+   and the two compose: structure from one, look from the other. The storyboard and entity call
+   shapes — return fields, all fifteen `edit_storyboard` ops, every key
+   `set_board` accepts, which fields and entities each shot's prompt receives —
+   live once, in `storyboard-core` § Tool contract. The job skills and the five
+   board skills point there, and `commercial-beat-sheet` § Tool contract is only
+   a pointer.
+2. **Board → model.** Before the shot text is written, `find_model` picks the
+   image and video lines, `set_board {image_model, video_model}` makes them the
+   render defaults, and the `prompting_skill` on each result names the
+   `*-prompting` guide that decides how `action` and `motion` are worded.
+3. **Sound, before the first render.** `video-audio-continuity` decides whether
+   a multi-scene piece is one native-audio generation or separate clips under
+   a track of your own; the audio guides (`elevenlabs-audio-prompting`,
+   `stable-audio-prompting`) write that track.
+4. **Render → cut.** `assemble_storyboard_timeline` turns the board into the
+   document `motion-graphics` edits; `beat-sync-editing` sits the cuts on the
+   bed, `caption-titles` adds every word on screen (never a render prompt),
+   `logo-reveal` the mark, `color-motion` the grade, `motion-direction` the one
+   motion language, and the rest of the craft skills the numbers.
+
+Every skill states where the rest of the set picks up along that path. A craft
+skill opens by pointing back at `motion-graphics` for the op contract and
+sideways at the neighbours that decide its numbers; a board skill points
+forward at the motion skills at the step where a board becomes a cut, so an
+agent asked to animate a finished board loads the craft file instead of
+improvising against the op list.
+
+## Credit
+
+The craft skills beside `motion-graphics` are adapted from
+[iart-ai/motion-design-skills](https://github.com/iart-ai/motion-design-skills)
+(MIT, commit `3c129f7`), rewritten against NodeTool's timeline: its animation
+roles and preset catalog, its easing grammar, the animatable channels and how
+they fold, and the validate-and-preview loop that closes each one. Upstream's
+After Effects and Remotion skills have no counterpart — `motion-graphics` holds
+the tool contract and `motion-curves` the sandbox bake, which is what those two
+answer for this engine. The licence is kept at
+`LICENSE-iart-motion-design-skills`.

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

@@ -0,0 +1,58 @@
+---
+name: api-agents
+description: "Call nodetool.agents from a code action: hand a self-contained task to a sub-agent, fan several out in parallel, or start background sub-agents and collect their results later. Load before the first call into nodetool.agents."
+---
+
+# nodetool.agents
+
+A sub-agent is a fresh agent loop with the same tools as you and **none of
+this conversation**. It answers with its final message as text.
+
+| Call | Does | Answers |
+| :--- | :--- | :--- |
+| `run(prompt, {description})` | Runs a sub-agent and blocks until it finishes. | The final message of the sub-agent, as text. Throws when the sub-agent fails. |
+| `start(prompt, {description})` | Starts a sub-agent and returns at once. | `{subtask_id, status: "running"}` |
+| `wait({ids, timeoutMs})` | Blocks until the named sub-agents finish. Omit `ids` to wait for every one this turn started. `timeoutMs` defaults to 300000. A code action stops after 600 s, so keep it under that. | Rows `{subtask_id, status, result \| error}`. `status` is `completed`, `failed`, `aborted`, or `running` after a timeout. |
+
+`description` is the 3–7 word label the user sees. Without it the first six
+words of the prompt are used.
+
+## Write the prompt for a stranger
+
+- Put everything the child needs in the prompt: the goal, the inputs (ids,
+  uris, the text), the constraints, and what to return.
+- Ask for the answer shape you want: "reply as JSON with fields title, url,
+  summary". Parse the text you get back.
+- Pass ids and `asset://` uris, not descriptions of them. The child can read
+  them with its own tools.
+
+## When to delegate
+
+Delegate work that gains from a fresh, focused context: research one question
+end to end, draft a self-contained section, review a result against a brief.
+Do not delegate a single tool call. A sub-agent costs real time and money.
+
+## Patterns
+
+Parallel, blocking — one settled entry per prompt, so a failed child becomes
+an entry instead of a throw:
+
+```js
+const answers = await nodetool.batch(prompts, (p) => nodetool.agents.run(p),
+  { concurrency: 4 });
+```
+
+Background — start, do other work, then collect in the same action:
+
+```js
+const a = await nodetool.agents.start(researchPrompt, { description: "Research competitors" });
+const draft = await draftOutline();          // your own work meanwhile
+const [row] = await nodetool.agents.wait({ ids: [a.subtask_id] });
+```
+
+Results of a sub-agent you never wait for are lost to the turn. Always wait
+for what you need before the action ends.
+
+Sub-agents can start sub-agents of their own, up to a depth limit. Results
+they publish with `nodetool.shared.publish` are readable by the parent in the
+same run (see `api-memory`).

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

@@ -0,0 +1,54 @@
+---
+name: api-apps
+description: "Call nodetool.apps from a code action: list, read, create and edit mini apps through the App Builder steps, and debug an app's wiring or run it. Load before the first call into nodetool.apps."
+---
+
+# nodetool.apps
+
+A mini app is a UI of widgets bound to workflow operations and variables, so
+someone can run a task without the graph. How to design one, and every App
+Builder tool, is `nodetool-app-builder`. This is the call reference.
+
+| Call | Does | Answers |
+| :--- | :--- | :--- |
+| `list({limit})` | Lists apps, newest first, with their operations. | App rows |
+| `get(id)` | Reads the app document: operations, variables and the widget tree. | The document |
+| `create(name, {description, project_id, from_workflow_id, document})` | Creates an app. `from_workflow_id` binds its first operation to a workflow. `document` starts from a whole app document. | `{application_id, …}` |
+| `edit(id, steps, {name, description, workflow_ids, base_updated_at})` | Applies App Builder steps in order to the saved document, then saves once. | The result of each step and the app state |
+| `debug(id, {params, interact, run, timeout_ms, poll})` | Checks every binding and simulates the app. | A pass/fail verdict with issues, and the final state of each widget |
+
+## edit
+
+Each step is `{tool, input}`. `tool` is an App Builder tool name, such as
+`ui_app_add_operation` or `ui_app_add_component`. The `ui_app_` prefix may be
+left out.
+
+- `edit(id, [])` answers the catalog of every tool with its schema, and the
+  current state of the app. Call it first.
+- `workflow_ids` loads the bindable surface of workflows the app does not use
+  yet, so a widget can bind to one.
+- `base_updated_at` refuses the save when the app changed after you read it.
+
+## debug
+
+- `{run: false}` checks the wiring only. It is free and takes milliseconds.
+  Run it after every wiring change.
+- A bare `debug(id)` is a full run: `run` defaults to true. A full run
+  executes the real workflows and spends real money. Run it to confirm that
+  the app works, not to explore.
+- `interact` scripts the user actions in order: `{set: {key, value}}`,
+  `{click: <widget>}`, `{change: {…}}`, `{run: <operationId>}`,
+  `{cancel: <operationId>}`, `{seedResource: {id, items}}`. A widget is named
+  by its component id, by a type only one widget has, or by a unique label.
+  Without `interact`, the natural run trigger of the app is clicked.
+- `poll: true` returns a session id at once for a long run.
+
+```js
+const { application_id } = await nodetool.apps.create("Caption maker",
+  { from_workflow_id: wfId });
+const catalog = await nodetool.apps.edit(application_id, []);
+await nodetool.apps.edit(application_id, [
+  { tool: "ui_app_add_component", input: { /* from the catalog schema */ } }
+]);
+const check = await nodetool.apps.debug(application_id, { run: false });
+```

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

@@ -0,0 +1,66 @@
+---
+name: api-assets
+description: "Call nodetool.assets or nodetool.documents from a code action: find, read and save files in the user's asset library, keep a file another tool downloaded, and convert documents or extract text and tables from a PDF. Load before the first call into these namespaces."
+---
+
+# nodetool.assets and nodetool.documents
+
+An asset is a stored file in the user's library: an image, a video, audio, a
+document, JSON. Its locator is `asset://<id>` (an extension is allowed:
+`asset://<id>.png`). Reuse an asset id instead of making the same file again.
+The workspace is a different store: it holds the files of this run, by
+workspace-relative path.
+
+## nodetool.assets
+
+| Call | Does | Answers |
+| :--- | :--- | :--- |
+| `list({source, query, content_type, limit})` | Lists assets. `source` is `"user"` (default) or `"package"`. `content_type` is `image`, `video`, `audio`, `text` or `folder`. | Asset rows |
+| `search(query, {content_type, limit})` | Finds assets by a name substring across every media type. `content_type` is a MIME prefix (`"image/"`). An empty query lists the newest. `limit` defaults to 25. | Handles with `asset://` uris |
+| `images({query, limit})` | Lists image assets as handles: id, name, size, dimensions. No pixels are loaded. | Handles. Pass an id to `view_image` to see one. |
+| `get(assetId)` | Reads one asset row. No bytes. | The row |
+| `read(nameOrUri)` | Reads the content. Takes an `asset://` URI, an id, a `/api/storage/` key or a stored file name. | `{content}` for text, `{content_base64}` for binary |
+| `save(name, {content \| content_base64 \| source, content_type})` | Saves a file to the library. | `{asset_id, asset_uri, url}` |
+
+### save
+
+Pass exactly one of these:
+
+- `content` — text, markdown or JSON.
+- `content_base64` — binary bytes you made yourself.
+- `source` — bytes that already exist: the `asset_url` or `/api/storage/` key
+  that another tool returned (`nodetool.web.download`, `run_apify_actor`, a
+  generation), an `asset://` URI to copy, or an http(s) URL. The host copies
+  them, so the bytes never pass through the guest.
+
+Never `read()` a stored file to base64 to save it again. Pass it as `source`.
+Without `content_type`, the extension of `name` decides it: name an SVG
+`logo.svg` and it is stored as `image/svg+xml`. Show a saved image, video or
+audio file in the reply as `![label](asset_uri)`.
+
+### Editing a stored image
+
+Pass the asset to `image.*` (a guest global), then save the handle:
+
+```js
+const handle = await image.resize("asset://<id>.png", { width: 1024 });
+const saved = await nodetool.media.toImage(handle);
+return saved.asset_uri;
+```
+
+## nodetool.documents
+
+File-to-file conversion with Pandoc and PDF tools. Every path is
+workspace-relative. Stage an asset into the workspace first with
+`nodetool.web.download("asset://<id>", "in.pdf")`.
+
+| Call | Does |
+| :--- | :--- |
+| `convert(inputFile, outputFile, {from_format, to_format, extra_args})` | Pandoc conversion. `from_format` defaults to `markdown`, `to_format` to `pdf`. It reads markdown, docx, rst, html and more. |
+| `extractText(pdfPath, {start_page, end_page})` | Plain text from a PDF, as `{text}`. Pages are 0-based, and `end_page: -1` is the last page. |
+| `extractTables(pdfPath, outputJsonFile, {start_page, end_page})` | Tables from a PDF into a JSON file |
+| `markdownToPdf(inputFile, outputFile)` | Markdown to PDF |
+| `pdfToMarkdown(inputFile, outputFile, {start_page, end_page})` | PDF to Markdown |
+
+The output of a conversion is a workspace file. Save it to the library with
+`nodetool.assets.save(name, {source: …})` when the user should keep it.

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

@@ -0,0 +1,33 @@
+---
+name: api-collections
+description: "Call nodetool.collections from a code action: list the user's knowledge collections and run a semantic search in one of them. Indexing is not available from code; build it with nodetool-rag-indexing. Load before the first call into nodetool.collections."
+---
+
+# nodetool.collections
+
+The vector store behind retrieval. A collection holds document chunks with
+embeddings for semantic search. It is not an asset folder. How to chunk, index
+and build a RAG workflow is `nodetool-rag-indexing`.
+
+| Call | Does |
+| :--- | :--- |
+| `list()` | Lists the collections the user has. |
+| `query(collection, query, {n_results})` | Semantic search in one named collection. `n_results` defaults to 5. |
+
+`index`, `indexBatch`, `search` and `hybridSearch` also exist on
+`nodetool.collections`, but their tools are on no tool belt this product
+ships, so each one throws "not in this toolbelt". Do not plan on them. To add
+documents to a collection, build an indexing workflow as `nodetool-rag-indexing`
+describes and run it with `nodetool.workflows.run`.
+
+## Rules
+
+- Call `list()` first when you do not know the collection name.
+- An empty result from a collection the user just made usually means nothing
+  was indexed yet. Say so instead of retrying the query.
+
+```js
+const { collections } = await nodetool.collections.list();
+const hits = await nodetool.collections.query("manuals", "reset the device",
+  { n_results: 8 });
+```

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

@@ -0,0 +1,81 @@
+---
+name: api-games
+description: "Call nodetool.games from a code action: create or install a built-in game, read and edit its draft, write a whole generated level, generate and install art and audio into asset slots, playtest and autoplay routes, capture frames, publish a revision and build a web player. Load before the first call into nodetool.games."
+---
+
+# nodetool.games
+
+A built-in game runs in NodeTool's native 2D or 3D engine. It has a mutable **draft**
+and immutable **revisions**. Play is deterministic, so a playtest with the same
+seed and inputs gives the same result. How to build one is `native-game`, and
+feel, pacing and art direction are `game-direction`. This is the call
+reference.
+
+Every `id` is the full game id or its exact 12-character prefix.
+
+| Call | Does |
+| :--- | :--- |
+| `create(name, {project_id, dimension, template})` | Creates a game in a project. `dimension` is `2d` (default, a playable top-down room) or `3d` (an exploration blockout). `template` is `topdown` or `exploration`. Answers the full id and the revision. |
+| `get(id, {source, revision, view, entity_id})` | Reads the draft (default) or a revision. `view` is `outline` (default), `entity` or `full`. |
+| `edit(id, ops, {base_updated_at})` | Applies ordered edits to the draft atomically. Issues come back with the op index and path. It does not publish. |
+| `setDocument(id, document, {base_updated_at})` | Writes a whole document as one `set_document` edit, validated atomically. |
+| `previewAuthoring(id, {program, base_updated_at, expected_document})` | Rebakes retained construction without writing. Returns a candidate, entity/dependency changes, conflicts and restart policy. Omit `program` to rebuild the saved construction. |
+| `applyAuthoring(id, candidate)` | Recomputes and applies the preview against its exact draft. Rejects stale or changed candidates and unresolved conflicts. |
+| `generateAsset(id, slot, kind, prompt, opts)` | Makes or imports an asset and binds it to the draft. |
+| `installAsset(id, slot, binding, {base_revision, base_updated_at, candidate_workspace_id})` | Installs one staged asset. The staged bytes must match `binding.digest`. |
+| `playtest(id, {source, revision, seed, inputs, assertions, capture_ticks})` | Runs up to 18,000 ticks with run-length inputs and assertions, and captures up to 8 frames. |
+| `autoplay(id, {win, target_prefix, seed, player_id, max_ticks, source, revision})` | Searches for a route to a win or to an entity prefix. Answers replayable inputs, the win tick and level statistics. An exhausted budget is inconclusive. |
+| `capture(id, {ticks, inputs, seed, camera, overlays, scale, sheet, source, revision})` | Renders up to 8 frames for a visual review. |
+| `publish(id, {base_revision, message})` | Saves the draft as an immutable revision, only when the user asks. `base_revision` is required, and a stale one is a conflict. |
+| `build(id, {revision})` | Builds a standalone web player of a revision under `game-builds/<game-id>/<revision>` in the project workspace. |
+| `listExamples({query, limit})`, `getExample(slug, {view, entity_id})` | Lists and reads the shipped benchmark games, such as `kindle`. |
+| `installExample(slug, {project_id, name})` | Copies an example with its media into a project as a new game you own. |
+
+## generateAsset
+
+`kind` is `image`, `audio` (speech), `music`, `sfx`, `font`, `model` or
+`collider`. Each generation is billed, so confirm the slot list with the user
+before you generate assets for many slots.
+
+- Images can be prepared as aligned sprite sheets, edge tilesets or grade LUTs
+  through `preparation`.
+- `sfx` needs a registered sound-effect `node_type` and its `params`.
+- `font` imports a TTF or OTF `input_file`.
+- `model` needs a provider `node_type` with `params`, or an owned glTF or GLB
+  `input_file`. `dependency_files` maps a glTF buffer or image URI to an owned
+  asset or workspace path. `collider` takes `preparation.shape`. 3D results
+  are candidates that `installAsset` must install.
+- `install: false` stages a 2D candidate and answers its binding without
+  binding it.
+- `reference_slot` keeps a new image in the style of an existing slot.
+- `provider` and `model` pick the model. `background: true` starts it and
+  answers a `generation_id`; call again with `generation_id` and the same
+  preparation to finish.
+
+## Build a level in code
+
+Author the whole document with `@nodetool-ai/sandbox-game` and save it with
+`saveGame({name, document}, {games: nodetool.games, project_id})`. Read
+`nodetool.packs.docs("@nodetool-ai/sandbox-game")` first.
+
+For retained construction, use `constructGame({inputs, seed}, (inputs, builder)
+=> { return document; })` and save the returned bundle with `saveGame`. Put
+accepted preparation results and pinned asset bindings in `inputs`. The callback
+cannot depend on outer variables. Rebuilds run without external capabilities.
+Ordinary `setDocument` cannot attach or replace retained source or its baseline.
+
+Manual property edits become overrides. Removing a generated entity suppresses
+its key on later rebuilds. `edit` supports `reset_override` with `entity_id`,
+optional `scene_id` and optional field `path`, and `detach_entity` with the same
+entity target. Resetting a suppressed target restores it from the baseline.
+Active retained-game sessions adopt the rebuilt definition and assets on restart.
+
+## The loop
+
+1. Read an example: `getExample("kindle")`, then `view: "entity"` for the
+   script and feel parameters of one entity.
+2. Build or edit the draft.
+3. Prove it can be finished: `autoplay(id, {win: true})`, then replay the
+   route with `playtest(id, {inputs, assertions})` and a win assertion.
+4. Look at it: `capture(id, {ticks, sheet: true})`.
+5. Publish and build only when the user asks.