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

package/dist/_skills/nodetool-rag-indexing/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: nodetool-rag-indexing
+description: "Build NodeTool document ingestion, vector indexing, retrieval, and RAG pipelines. Use when documents must be chunked into a vector collection and searched by meaning, or when an answer should come from the user's own documents. To find a stored image, video or file by name or tag, use asset_search instead."
+featured: true
+---
+
+# Index documents and answer from them
+
+A **collection** is a named vector store. Indexing splits documents into
+chunks, embeds each chunk with the collection's embedding model and stores it.
+Retrieval embeds the question with the same model and returns the closest
+chunks, which a language model answers from.
+
+```
+INDEX:  documents → text → chunks → vector.IndexTextChunk → collection
+QUERY:  question → vector.HybridSearch / QueryText → context → Agent → answer
+```
+
+## Search what is already indexed
+
+Two tools are on the agent's belt in every chat:
+
+- `list_collections` returns each collection the user can access, with its
+  metadata (including `embedding_model`).
+- `query_collection {collection, query, n_results?}` returns the closest chunks
+  as `{id, document, score}`. `n_results` defaults to 5.
+
+Answer from the returned chunks and say which chunk ids the answer used. An
+empty result means the collection holds nothing close, not that the topic is
+unknown.
+
+The `vector_index`, `vector_batch_index`, `vector_text_search`,
+`vector_hybrid_search`, `vector_recursive_split_and_index` and
+`vector_markdown_split_and_index` tools act only on a collection a host binds
+to the run. A chat binds none, so they return an error there. Index through the
+nodes below instead.
+
+## Index through nodes
+
+All vector nodes are in the `vector` namespace.
+
+| Node | Takes | Does |
+|---|---|---|
+| `vector.Collection` | `name`, `embedding_model` | Gets or creates the collection and outputs a `{type: "collection", name}` ref |
+| `vector.IndexTextChunk` | `collection`, `document_id`, `text`, `metadata` | Upserts one chunk. The same `document_id` overwrites |
+| `vector.IndexString` | `collection`, `text`, `document_id`, `metadata` | Upserts one string |
+| `vector.IndexImage`, `vector.IndexEmbedding` | | Index an image or a precomputed embedding |
+| `vector.QueryText` | `collection`, `text`, `n_results` | Vector search. Outputs `ids`, `documents`, `metadatas`, `distances` |
+| `vector.HybridSearch` | `collection`, `text`, `n_results`, `k_constant`, `min_keyword_length` | Vector plus keyword search, fused by reciprocal rank. Adds `scores` |
+| `vector.QueryImage` | `collection`, `image`, `n_results` | Image search |
+| `vector.GetDocuments`, `vector.Peek`, `vector.Count` | `collection` | Inspect what is stored |
+| `vector.RemoveOverlap` | `documents` | Removes text repeated between overlapping chunks |
+
+The embedding model is set once, on `vector.Collection`'s `embedding_model`,
+and stored in the collection's metadata. Index and query nodes take only the
+collection, so indexing and search always use the same model. The shipped
+example uses the Ollama model `nomic-embed-text`. Changing the model means a
+new collection.
+
+For a few chunks, `run_node` is enough: `run_node {node_type:
+"vector.Collection", inputs: {name, embedding_model}}` once, then
+`vector.IndexTextChunk` with `collection: {type: "collection", name}` per
+chunk. For a folder of documents, build a workflow and run it.
+
+### Index workflow
+
+1. **List files.** A Code node with `await workspace.list(dir)`, or
+   `nodetool.document.ListDocuments {folder, pattern, recursive}`.
+2. **Load text.** `nodetool.document.LoadDocumentFile {path}` for text and
+   Markdown. For PDFs use `lib.pdf.ExtractText` or `lib.pdf.ExtractMarkdown`.
+3. **Chunk.** There is no chunking node. Use a Code node, starting from the
+   "Chunk Text" snippet, and record the list with
+   `await output("chunks", chunks)`. Read a document input with
+   `await media.text(inputs.document)`.
+4. **Fan out.** `nodetool.control.ForEach` emits each chunk on `output` and its
+   position on `index`. Build a unique `document_id` from the file name and the
+   index, for example with `nodetool.text.Template`.
+5. **Index.** `vector.IndexTextChunk` with the collection ref, the chunk as
+   `text`, the id as `document_id`, and `{source: <file name>}` as `metadata`.
+
+Validate with `validate_workflow`, then run it. Indexing with a hosted
+embedding model is billed per token, so confirm the size of the corpus with the
+user before indexing a large folder.
+
+| Content | Chunk size | Overlap |
+|---|---|---|
+| Technical docs | 200–500 tokens | about 50 tokens |
+| Prose | 300–600 tokens | about 75 tokens |
+| Code | 100–300 tokens | about 25 tokens |
+
+### Query workflow
+
+`StringInput` (question) → `vector.HybridSearch {collection, n_results: 5}` →
+a Code node joining `documents` into one context string → `nodetool.text.Prompt`
+or `Template` with the context and the question → `nodetool.agents.Agent` with a
+system prompt that limits it to the context → `Output`.
+
+The shipped example **Chat With Your Documents** builds a collection, indexes
+three documents and answers from them. Load it with `get_example_workflow
+{package_name: "nodetool-base", example_name: "Chat With Your Documents"}` and
+adapt it rather than starting from nothing.
+
+## Storage backends
+
+The workflow nodes and tools are the same on every backend. The server picks
+one at start from `NODETOOL_VECTOR_PROVIDER`:
+
+| Value | Store | Configuration |
+|---|---|---|
+| `sqlite-vec` (default) | Local SQLite file | `VECTORSTORE_DB_PATH` to move it |
+| `pinecone` | Pinecone | `PINECONE_API_KEY`, optional `PINECONE_ENVIRONMENT`, `PINECONE_CONTROLLER_HOST` |
+| `supabase` | Postgres with pgvector | `SUPABASE_URL` and `SUPABASE_KEY` or `SUPABASE_SERVICE_ROLE_KEY`, plus `packages/vectorstore/sql/supabase-migration.sql` applied to the project |
+
+Any other value stops the server with an error. These are server environment
+variables, set by whoever runs the server, not by the agent.
+
+## From a shell or over HTTP
+
+For a person with a shell, the `nodetool collections` CLI manages collections
+on the local server:
+
+```bash
+nodetool collections create handbook --embedding-model nomic-embed-text --embedding-provider ollama
+nodetool collections index handbook ./docs/*.md
+nodetool collections query handbook "refund policy" -n 5
+nodetool collections list
+nodetool collections delete handbook --yes
+```
+
+`POST /api/collections/<name>/index` takes one text file as a
+`multipart/form-data` upload in the `file` field, chunks it and indexes it into
+an existing collection that has an embedding model. Plain text, Markdown, HTML,
+CSV and JSON are accepted. PDFs, Office files and images need an indexing
+workflow.
+
+```bash
+curl -X POST http://localhost:7777/api/collections/handbook/index \
+  -H "Authorization: Bearer $TOKEN" \
+  -F "file=@./docs/refunds.md"
+```
+
+## Pitfalls
+
+- **A collection with no embedding model** cannot be searched. Create it with
+  one.
+- **Chunks too large** dilute the context. **Chunks too small** split
+  sentences. Keep 10–20% overlap.
+- **Reused `document_id`s** overwrite each other. Include the file name in the
+  id.
+- **Querying before indexing** returns nothing.
+- **Node names**: `vector.IndexTextChunk`, `vector.QueryText`,
+  `vector.HybridSearch`. There is no `vector.chroma.*` or `vector.faiss.*`, and
+  no `nodetool.text.Chunk`.

package/dist/_skills/nodetool-sketch/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: nodetool-sketch
+description: "Build or edit a NodeTool sketch (image document): layers, blend modes, placed images, generation briefs, version history."
+featured: true
+---
+
+# Work a NodeTool sketch
+
+A sketch is an **image document**: a canvas, a stack of layers, and the bindings
+that say where a layer's picture comes from. It is the surface for composited
+stills, masks, overlays and the guided image brief. One finished image with no
+layers to keep is `generate_image`, not a sketch.
+
+The document is layers and references. **Headless tools never read or write
+pixels.** Painting happens in an open editor (the `ui_sketch_*` tools below),
+generation happens in a workflow run or through the image tools. An image lands
+on a layer by reference, so nothing inlines a bitmap.
+
+## The loop
+
+1. **Find it.** `list_sketches`, then `get_sketch`. New one:
+   `create_sketch {name, width?, height?, background_color?, project_id?}` gives a
+   blank canvas (1024×1024, `#ffffff` by default).
+2. **Edit the stack.** `edit_sketch {image_document_id, ops: [...]}`. Operations
+   run in order against the stored document and the result is saved. An open
+   editor picks the change up live.
+3. **Validate.** `validate_sketch {image_document_id}` or an inline `document`.
+4. **Snapshot** before a destructive pass with `create_sketch_version`.
+
+## `edit_sketch` ops
+
+| Op | Does |
+|---|---|
+| `add_layer` | `{name?, type?: "raster"\|"mask", index?, image?, x?, y?, width?, height?}`. An `image` field makes this one op instead of two |
+| `remove_layer`, `rename_layer`, `duplicate_layer`, `reorder_layer` | Stack management |
+| `select_layer` | Sets the active layer |
+| `set_layer_props` | `opacity`, `blendMode`, visibility, lock |
+| `set_layer_image` | Points a layer at an asset id, an `asset://` locator, a `data:` URL or an http(s) URL |
+| `resize_canvas` | Positive integer width and height |
+| `set_setup` | The generation brief: `brief`, `use_case`, `variations` (1..8), `stage`. Renders nothing |
+
+`target` is a layer id, a layer name, or `"active"`. Layer index 0 is the
+bottom of the stack. `use_case` is one of `product`, `portrait`, `key-art`,
+`social`, `logo`, `concept`, `texture`, and it also sets the canvas size.
+`stage` is where the guided flow resumes: `idea`, `useCase`, `review`, `look`,
+or `done` for the plain editor.
+
+An asset id that resolves to nothing is refused rather than stored, because a
+stored one shows up as an empty layer.
+
+With the sketch open in a browser, the `ui_sketch_*` tools act on the live
+canvas, and only they touch pixels: `ui_sketch_get_state`,
+`ui_sketch_place_image`, `ui_sketch_stroke`, `ui_sketch_fill`,
+`ui_sketch_gradient`, `ui_sketch_draw_shape`, `ui_sketch_adjust_layer`,
+`ui_sketch_transform`, `ui_sketch_crop`, `ui_sketch_merge_down`,
+`ui_sketch_flatten_visible`, `ui_sketch_get_layer_image`,
+`ui_sketch_generate` and `ui_sketch_render_to_asset`.
+
+## Vector layers
+
+The editor imports self-contained SVG files as vector layers. Each layer keeps
+its SVG source in the document. Use the vector inspector to edit SVG source,
+download it, or rasterize the layer for painting. Moving and transforming a
+vector layer preserves its source. Rasterization is undoable. Example sketches
+open with vector layers.
+
+SVG scripts, embedded HTML, animations, external images, and stylesheets are
+removed on import. Use presentation attributes for fills, strokes, and text.
+The headless stack operations can preserve existing vector layers. Creating or
+editing SVG source currently requires the editor.
+
+## The guided brief
+
+`set_setup` writes the one-line brief. `refine_image_brief {image_document_id,
+provider?, model?}` expands it into the five fields an image model needs
+(subject, composition, lighting, style words, and what to leave out) and stops
+at the review step. It creates no layer and starts no generation. It is the
+cheap text pass a person edits before anything is rendered.
+
+Once the fields read right, put pixels on a layer in two calls:
+`generate_image` saves the result as an asset and returns its `asset://` URI,
+then `edit_sketch` with `add_layer {image}` or `set_layer_image {target, image}`
+places it. Generation spends provider money, so confirm the count with the user
+before rendering several `variations`.
+
+To use the finished composite in a workflow, `nodetool.sketch.RenderSketch`
+takes a `sketch` and flattens it to an `image` and a `mask`.
+
+## What `validate_sketch` catches
+
+Duplicate layer ids, an active or mask layer the stack lacks, unknown blend
+modes, opacities and transforms that cannot render, generation bindings pointing
+at missing layers, unknown binding kinds and statuses, canvas settings that
+disagree with the stored ones, and fields a schema round trip would strip. Layer
+bitmaps stay opaque to it.
+
+## Versions
+
+`list_sketch_versions`, `get_sketch_version` (read a snapshot without restoring),
+`create_sketch_version`, `restore_sketch_version`, `delete_sketch_version`.
+A restore snapshots the pre-restore state first, so it is undoable, then
+re-validates against today's schema: an old document may fail what it used to
+pass.
+
+These snapshot the whole document. The per-layer generation takes are a
+different thing, and they record one generated image on one layer.
+
+## Verify from a shell
+
+These are the `nodetool` CLI. From a NodeTool checkout the same commands run
+as `npm run dev:nodetool -- <command>`.
+
+```bash
+nodetool sketch validate <image_document_id|sketch.json> --json
+nodetool sketch debug sketch.json \
+  --interact '[{"tool":"add_layer","input":{"name":"Shadow"}},
+               {"tool":"set_layer_props","input":{"target":"Shadow","opacity":0.4,"blendMode":"multiply"}}]'
+nodetool sketch versions list <id> --save-type manual --limit 10
+```
+
+A path on disk wins over an id. `debug` runs the static check, then each
+`--interact` step against the headless `ui_sketch_*` bridge, and validates what
+the session left behind. A failing step is recorded and the script continues.
+Pixels, painting, rendering, generation and asset I/O are not simulated.
+
+## Where a sketch is used
+
+- A mini app shows one with the **Sketch** widget, which takes a
+  `{type: "sketch", id}` reference, and collects one with the **Sketch Pad**
+  input. See `nodetool-app-builder`.
+- A mini app resource of `kind: "sketch"` lets the app read or edit it.
+
+## Reference
+
+In a NodeTool checkout, these repository sources go further:
+
+- `docs/harnesses.md` § nodetool sketch validate / debug
+- `docs/harnesses.md` § nodetool sketch versions

package/dist/_skills/nodetool-skill-author/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: nodetool-skill-author
+description: "Write or revise a NodeTool skill: a user skill row through create_skill, or a shipped system skill under packages/system-skills. Use when instructions should persist across sessions."
+featured: true
+---
+
+# Author a NodeTool skill
+
+A skill is a named set of instructions an agent loads when its description
+matches the task. Write one when the same direction would otherwise be repeated
+every session. Do not write one for a single job: do the job.
+
+## Which kind
+
+| | User skill | System skill |
+|---|---|---|
+| Lives in | A row in the user's account | `packages/system-skills/<name>/SKILL.md` in the build |
+| Written by | `create_skill`, `update_skill`, `delete_skill` | A file in a pull request |
+| Scope | That user | Every install, on day one, with no seeding migration |
+| Editable at runtime | Yes | No. Immutable, and `create_skill`, `update_skill` and renames refuse a shipped name. A user row that already held the name before the skill shipped still shadows it |
+
+A repository skill under `.claude/skills/` is a third thing: it directs the
+coding agent working on the NodeTool repository, not the agent inside the
+product — the engineering loop, not a product surface. Its maintenance rules
+are in a checkout's `.claude/README.md`, § Maintaining skills.
+
+A skill that teaches a product surface is a system skill even when the coding
+agent also wants it. `packages/system-skills/<name>` holds the one copy and
+`.claude/skills/<name>` is a symlink to it, so the product and the repository
+read the same document. Write a second copy under `.claude/skills/` and the
+two drift; `npm run check:agents-docs` fails on one.
+
+## The contract
+
+A system skill is one Markdown document with frontmatter:
+
+```markdown
+---
+name: my-skill
+description: When to use this
+---
+
+The instructions.
+```
+
+A user skill has the same three parts as separate `create_skill` fields:
+`{name, description, content}`. `content` is the body only. Do not put
+frontmatter in it.
+
+- `name` is a lowercase slug, `a-z0-9-` only, at most 64 characters. It cannot
+  contain `anthropic` or `claude`. A user's names must be unique per user.
+- `description` is one bounded line, at most 1024 characters, with no markup.
+  **It is the only part always in context**, so write it as *when to use this*,
+  not as what the skill contains. A description that does not name the trigger
+  means the skill never loads.
+- `featured: true` is for a shipped skill only. It puts the skill in the
+  catalog that every turn carries. Every other shipped skill is found with
+  `list_skills({query})`, so feature a skill only when a turn needs it before
+  its first call: the entry point of a product surface, or a craft skill that
+  work on that surface always reads.
+- The body must be non-empty. Frontmatter is parsed as scalar `key: value`
+  pairs, not full YAML, and the fence is the first `---` line after the opening
+  one, so a `---` rule inside the body survives.
+- `##` headings organize the body for the reader. `load_skill` returns the
+  whole document in one piece, so a section does not save context.
+
+Confirm the parse by listing it back: `list_skills` shows name and description,
+`load_skill {name}` returns the full instructions.
+
+## Write it so it fires and so it holds
+
+- **Lead with the result, then the loop.** The reader is mid-task and will act
+  on the first thing that looks like an instruction.
+- **Name tools exactly.** A renamed tool in a skill is a failure a model cannot
+  recover from. Check each call against the live schema or the capability
+  registry before writing it.
+- **State what a tool refuses**, not only what it accepts. Most skill failures
+  are a call made with a field the tool drops.
+- **Point at the neighbour** rather than restating it. A craft skill quotes a
+  call, the contract skill owns it.
+- **Do not add checkpoints or deliverables** the user did not ask for. An
+  example in a skill is an illustration, not a requirement on the next request.
+
+## Shipping a system skill
+
+One directory holding a `SKILL.md` whose frontmatter `name` matches the
+directory. Nothing imports these files, so `packages/system-skills` is not a
+workspace: `stageSystemSkills` in `scripts/bundle-backend.mjs` copies every
+directory 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.
+
+Discovery checks `NODETOOL_SYSTEM_SKILLS_DIR` first, and when it is set nothing
+else is searched. Otherwise it uses `_skills/` beside the bundle, else
+`packages/system-skills` on the way up. Only `SKILL.md` is read: a
+skill ships as one document, so material that would have been a `references/`
+file belongs in a `##` section of the body.
+
+Symlink the new directory into `.claude/skills/<name>` when the repository's
+coding agent should reach it too.
+
+Two follow-ups a new system skill usually needs:
+
+- Check the tool names yourself. `packages/agents/tests/shipped-skill-names.test.ts`
+  reads snake_case calls out of every shipped skill and checks them against the
+  registry, but only names with a known verb prefix (`add_`, `create_`, `get_`,
+  `list_` and so on). Names such as `web_search`, `request_secret` or
+  `find_model` pass unchecked, and so do node types. A skill
+  whose body names timeline calls can also go in that test's `SKILL_NAMES`,
+  which matches them exactly against the capability specs and `edit_timeline`'s
+  op list.
+- A skill that guides one model line goes in `MODEL_PROMPTING_SKILLS`
+  (`packages/agents/src/model-prompting-skills.ts`) so `find_model` attaches it
+  to a matching route. `packages/agents/tests/model-prompting-skills.test.ts`
+  checks that table against the skills on disk, the model ids the shipped
+  provider manifests name, and the capability registry.
+
+## Reference
+
+In a NodeTool checkout, these repository sources go further:
+
+- `packages/system-skills/README.md` — the shipped set, and how one job
+  routes across it.
+- `packages/agents/src/system-skills.ts` — loader and discovery rules.
+- `packages/protocol/src/skill-document.ts` — the parser and the validators.