@pixerate/editor 0.80.0 → 0.82.0

package/skills/pixerate-parameters/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: pixerate-parameters
+description: How to read and change a Pixerate parameters panel (the schema-driven sliders, toggles, choices, colour pickers, vectors, image pickers and text fields behind an effect, shader, generator or component props) through its commands - listing parameters with their types, ranges, steps and defaults, setting several values as one undo step, resetting, seeded randomize, applying and saving presets, and toggling keyframes for animation. Use when asked to tweak an effect or shader, change a slider or control value, try variations, save or apply a preset, or animate a parameter, or when parameters.list and parameters.set appear in list_commands.
+---
+
+# Parameters panel
+
+A parameters panel is a schema of fields, each with an `id`, a `type` and a `default`, plus the
+current values. Types: `number` and `int` (optional `min`, `max`, `step`, `unit`), `boolean`,
+`choice` (fixed options), `color` (`"#rrggbb"`, or `"#rrggbbaa"` when the field has alpha),
+`vector` (an array of 2..4 numbers), `image` (a URL) and `text`. Fields can sit in groups and
+can be hidden by `showIf` conditions on other values. The panel has built-in presets (from the
+schema, read-only) and user presets, an undo history, and optionally a playhead `time` (ms)
+with keyframes.
+
+There are no dedicated tools: the panel registers commands, which you run with `run_command`
+or `run_commands` (see `pixerate-agent-tools`). The ids below use the default `parameters.`
+prefix; a host with several panels registers each with its own prefix, so find the right one
+with `list_commands` (query "Parameters").
+
+## Working method
+
+1. **Read.** Run `parameters.list`. Note each field's `type`, `schema` (min, max, step,
+   `options` for choices, `size` for vectors), `value`, `default`, `visible`, and `keyframe`
+   state; and the `presets` and playhead `time`.
+2. **Plan** the values from the user's intent in the field's own units and ranges. Check
+   whether a preset already gives the look (`parameters.applyPreset`).
+3. **Write once.** Put every value of one change into one `parameters.set` call: it validates
+   all values first and applies them as one undo step, or changes nothing and says why.
+4. **Check** the returned `changed` ids and `values`. If a field you set is `visible: false`,
+   its value is stored but has no effect until its `showIf` condition holds; set the
+   controlling field too.
+5. **Verify visually** with the host's render or view tool when one exists (for example
+   `view_editor` or the editor's `render_*` tool); parameters themselves have no preview.
+
+## Best practices
+
+- **Respect the schema.** Stay within `min`/`max`; land on the `step` grid; give `int` fields
+  integers; give choices one of their listed option values (not labels); give vectors exactly
+  `size` numbers. Units (`unit`: x, px, %, degrees, ms) mean what they say; do not convert.
+- **Change little at a time.** Move the parameters that drive the user's request and leave the
+  rest. Large simultaneous changes make it hard to tell which one caused the result.
+- **Presets for reuse.** When the user likes a result, offer to save it with
+  `parameters.savePreset` and a descriptive name (and `description`). Apply presets with
+  `merge: true` to layer a look over the current values; without it, fields the preset leaves
+  out return to defaults.
+- **Randomize with care.** Randomize only for exploration and say so. Pass `ids` to limit it to
+  the fields that should vary, and a `seed` so the result can be reproduced and reported.
+  Save a preset first if the current values matter; undo restores them otherwise.
+- **Keyframes for animation:** set the value at a time, then toggle a key there. Use as few
+  keys as the motion needs; let the timeline's easing do the in-betweens.
+- **Defaults are the baseline.** `parameters.reset` with specific `ids` is the clean way back
+  for one control; resetting everything discards the user's work, so confirm first.
+
+## Commands
+
+| Command | Use it to |
+| --- | --- |
+| `parameters.list` | Read every field (id, label, type, description, value, default, visible, keyframe state, and a JSON Schema with ranges, options or vector size), the preset names and the playhead `time` in ms. Read-only; run it first and after schema changes. |
+| `parameters.set` | Set one or more values: `{ "values": { "<id>": value } }`. All-or-nothing and one undo step; its params schema is generated from the current fields, so types and ranges are enforced. Returns `changed` ids and all `values`. Ints are rounded and colours normalised to lower-case hex; any other invalid value refuses the whole call with a sentence naming the field. |
+| `parameters.reset` | Return fields to their defaults: `ids` (default all). Disabled when nothing is modified and no ids are given. Returns `values`. |
+| `parameters.randomize` | Pick random values within each field's range, snapped to steps: `ids` (default all visible fields, skipping read-only, `randomize: false`, image, text and unbounded number fields) and `seed` (integer) for a repeatable result. Explicit `ids` are randomized even when hidden. Returns `changed` and `values`. |
+| `parameters.applyPreset` | Apply a preset by `name` (from `parameters.list` presets). Fields it leaves out return to defaults unless `merge: true`. Disabled when there are no presets. Returns `values`. |
+| `parameters.savePreset` | Save the current values as a user preset: `name` (required), optional `description`. Replaces a user preset with the same name; a built-in preset's name is refused. Returns `presets`. |
+| `parameters.deletePreset` | Delete a user preset by `name`. Built-in presets cannot be deleted; disabled when there are no user presets. Returns `presets`. |
+| `parameters.toggleKeyframe` | Add a keyframe with the field's current value at `time` (ms, default the playhead), or remove the key already there: `id` (required), `time`. Returns `keyed` (true when added) and the time. Disabled when the panel has no keyframe support. |
+| `parameters.undo` | Undo the last parameter change (a `parameters.set` call, preset, reset, randomize or keyframe toggle is one step). Disabled when there is nothing to undo. |
+| `parameters.redo` | Re-apply the change just undone. Disabled when there is nothing to redo. |
+
+## Pitfalls
+
+- `parameters.set` takes a `values` object, not top-level ids: `{ "values": { "speed": 2 } }`.
+- One out-of-range value fails the whole call (nothing changes). Read the message, fix that
+  value, and resend the full set.
+- Choice values are option `value`s, which can differ from labels (`"bars"`, not `"Bars"`).
+- Colours are hex strings; `"#rrggbbaa"` only on alpha fields. Vectors are arrays, not objects.
+- `toggleKeyframe` is a toggle: running it twice at the same time removes the key. Check
+  `keyed` in the result and `keyframe` in `parameters.list` (`none`, `animated`, `keyed`).
+  To key a new value, `parameters.set` it at the playhead first, then toggle; on an existing
+  key, setting the value updates that key.
+- The schema can change while you work (a shader recompiles); run `parameters.list` again
+  when a set fails with an unknown id.
+- Do not edit fields marked read-only in their schema unless the user asks for it explicitly.

package/skills/pixerate-rich-text/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: pixerate-rich-text
+description: How to read and edit Pixerate rich text documents and prompt editors through agent tools - reading text with document positions (get_text, find_text), minimal-diff edits (replace_range, replace_text, insert_text), selections, tables (edit_table and table.* commands), charts and sparklines embedded in a document, find and replace commands, and prompt editing with templates, variables and instructions (prompt_insert_text, prompt_replace_range, prompt_set_variable, get_editor_state, view_editor). Use when asked to write, rewrite, proofread, restructure or format a document, report, note, heading, paragraph or table, to insert a chart or sparkline into text, or to edit an image-generation or LLM prompt with {{template}}, {variable} and __instruction__ tokens.
+---
+
+# Editing rich text documents and prompts
+
+There are two text surfaces, each with its own tools:
+
+- **Rich text documents** (a TipTap / ProseMirror editor) use `get_text`, `find_text` and the
+  document write tools. Positions are **ProseMirror document positions**, not character
+  offsets into the plain text: every block boundary counts (position 1 is already inside the
+  first block). Never compute positions from `get_text` content; get them from
+  `find_text` matches or from `get_text {blocks: true}` (each paragraph, heading or table cell
+  as `{type, from, to, text}`). Charts in a document have ids (from `list_document_charts`).
+- **Prompt editors** (a prompt with a variables map, often beside a canvas) use
+  `get_editor_state` and the `prompt_*` tools. Positions are host-defined; read them from
+  `get_editor_state` (`document.selection`, `document.text`).
+
+Errors, namespacing (`doc-1__find_text`) and `run_commands` batching are covered by the
+`pixerate-agent-tools` skill. Chart type, axis and colour choices are covered by
+`pixerate-chart`; the same spec fields apply to charts in a document.
+
+## Working method
+
+1. **Read.** `get_text` (`format: "markdown"` shows headings, lists and tables compactly;
+   add `blocks: true` when you will edit by position). For a prompt, `get_editor_state` with
+   `includeCanvas: false`.
+2. **Locate.** `find_text` for each phrase you will change. Use `before` / `after` context to
+   pick the right match when a phrase occurs more than once.
+3. **Write the smallest change.** `replace_range` on the matched `{from, to}`, or
+   `replace_text` with `occurrence` for one known phrase. Rewrite a whole paragraph only when
+   most of it changes. Each call is one undo step.
+4. **Re-anchor after every write.** Positions after the edit point move. Use the `range`
+   returned by the write, or call `find_text` again; never reuse positions read before a
+   write that came earlier in the document. When making several position-based edits from
+   one read, apply them from the end of the document backwards.
+5. **Check.** `get_text` again (or `find_text` for the new wording) and confirm the result.
+   For a prompt, `view_editor` shows how tokens render when layout matters.
+
+## Best practices
+
+- **Structure.** One H1 (the title), then H2 / H3 in order without skipping levels. Headings
+  are short noun phrases that let a reader scan. Keep paragraphs to one idea, roughly 3 to 5
+  sentences. Use a list for three or more parallel items, a numbered list only when order
+  matters.
+- **Front-load.** Lead each section and paragraph with its point; put caveats after.
+- **Plain language.** Prefer short, active sentences and concrete words. Keep terminology
+  consistent; a renamed term must be renamed everywhere (`replace_text` with
+  `wholeWord: true`, `matchCase: true`).
+- **Respect the author.** Preserve the existing voice, spelling variant and formatting.
+  `replace_text` keeps the found text's formatting; `replace_range` inserts plain text, so use
+  it for changes inside a run, not across differently formatted spans you want to keep.
+- **Accessible tables.** Use tables for data with rows and columns, not for layout. Always
+  give a header row (`withHeaderRow: true`, the default), and a header column when the first
+  column labels rows. Avoid merged cells: they break reading order for screen readers and
+  make data hard to reuse. Keep cell text short; align numbers right
+  (`setCellAlignment` with `align: "right"`). Do not rely on cell colour alone to carry
+  meaning.
+- **Charts in text.** Introduce a chart in the sentence before it and state the takeaway in
+  its title ("Revenue doubled in Q3", not "Revenue"). Use a sparkline for a trend inside a
+  sentence or table cell and give it a `label` that says what it shows.
+- **Prompt hygiene.** Put everything that changes between runs in a `{variable}` and set it
+  with `prompt_set_variable` rather than editing the text. Give variables descriptive
+  snake_case names and, where useful, a default and a description:
+  `{subject|a red fox|Describe the main subject}`. Reuse shared phrasing as a `{{template}}`
+  instead of pasting it. Use `{?name}...{/name}` (kept when `name` is set) and
+  `{!name}...{/name}` (kept when unset) for optional clauses. Keep `__instruction__` tokens
+  short and imperative (`__no text in image__`). State subject, then setting, then style,
+  then constraints.
+
+## Tool reference
+
+### Read
+
+| Tool | Use it to |
+| --- | --- |
+| `get_text` | Read the document. `format`: `text` (default), `html` or `markdown`. `blocks: true` adds every textblock with `{type, from, to, text}` positions. Also returns the selection and document `size`. Call first. |
+| `find_text` | Get positions of a phrase: returns `{total, truncated, matches: [{from, to, text, before, after}]}`. Literal by default; `matchCase`, `wholeWord`, `regex` (JavaScript syntax) default false; `maxResults` default 50 (max 500). Feed matches to `replace_range`, `insert_text` `at` or `set_selection`. |
+| `list_document_charts` | List charts in document order (id, `pos`, type, title, categories, series ids and names, width, height, a plain-language description) and inline sparklines (pos, kind, values). `includeSpec: true` adds each full spec. Call before `update_chart_in_document`. |
+| `get_editor_state` | Read a prompt editor: `document` (`text`, `variables`, `selection`, `isDirty`) and, when a canvas is attached, its nodes and edges. Pass `includeCanvas: false` when you only need the prompt. Positions for the `prompt_*` tools come from here. |
+| `view_editor` | Capture an image of the editor (`scope`: `viewport` default or `canvas`; `format`: `jpeg` default or `png`; `maxEdge` default 1024 px). Use once after a batch of edits to check how tokens, tables or charts render; images cost tokens. Only present when the host supports capture. |
+
+### Write
+
+| Tool | Use it to |
+| --- | --- |
+| `replace_range` | Replace the content between `from` and `to` with literal `text` (newlines start new paragraphs). `from === to` inserts; empty `text` deletes. Returns the new `range` and document `size`. The default tool for minimal-diff edits. |
+| `replace_text` | Find and replace a phrase in one undo step, keeping the found text's formatting. Replaces all matches unless `occurrence` (1-based) is given. Same `matchCase` / `wholeWord` / `regex` flags as `find_text`. Fails when nothing matches. Returns `{replaced, total, ranges}`. |
+| `insert_text` | Insert literal `text` at `at` (a document position) or at the cursor. Returns the inserted `range`. Use for new sentences or paragraphs; position from `get_text {blocks: true}` (a block's `to` appends to it). |
+| `replace_selection` | Replace the current selection with literal text (empty string deletes). Use after `set_selection`, or when the user asks to change what they selected. |
+| `set_selection` | Select `from`..`to` (or place the cursor when `to` is omitted). Use to show the user a passage, or to aim `edit_table` and the `table.*` commands at a cell. |
+| `edit_table` | Insert or edit a table. `operation` is one of the `table.*` command names (`insertTable`, `addRowAfter`, `mergeCells`, `setCellAlignment`, ...). `at` moves the cursor first (a position inside a cell). `insertTable` takes `rows` (default 3, max 100), `cols` (default 3, max 50), `withHeaderRow` (default true); `setCellAlignment` takes `align` (left, center, right, justify, null); `setCellBackground` takes `color` (CSS colour or null). Returns the table size and cursor cell. Only present when the schema has tables. |
+| `insert_chart` | Insert a chart block at `at` (or the cursor; a position inside a paragraph splits it). `spec` needs `categories` and `series` (`[{name, values}]`, one value per category) and takes the chart presentation fields (`type`, `title`, axes, legend, `stacking`, `palette`, ...). `width` px or null to fill the line (default null), `height` px (default 320). Returns id, pos and stored spec. |
+| `update_chart_in_document` | Change one chart by `chartId` or `pos` from `list_document_charts`. `changes` merges into the spec (axes and legend field by field); given `series` replace all series. Also `width` / `height`. All-or-nothing; invalid fields come back as sentences. |
+| `insert_sparkline` | Insert a word-sized chart inside a paragraph or cell at `at`. `values` (numbers or null gaps, up to 1000), `kind`: `line` (default), `column` or `win-loss`; `width` default 80 px, `height` default 18 px; `color`; `label` (accessible text). Fails at a position between blocks. |
+| `prompt_insert_text` | Insert text into the prompt at `at`, or at the cursor. Write tokens in their plain syntax (`{subject}`, `{{scene}}`, `__instruction__`). |
+| `prompt_replace_range` | Replace prompt text between `from` and `to` (from `get_editor_state`); empty `text` deletes. `from` must not be after `to`. |
+| `prompt_set_variable` | Set the value of a template variable (`name` without braces, `value` any JSON value). Prefer this over editing the prompt text when only a slot's value changes. |
+| `prompt_select` | Select prompt text between two positions (`from === to` places the cursor), e.g. to show the user what you changed. |
+
+## Commands
+
+Run with `run_command` / `run_commands` when the host registers them. Check
+`list_commands {enabledOnly: true}` first: table commands are disabled outside a table.
+
+| Command | Use it to |
+| --- | --- |
+| `findReplace.open` | Show the find bar to the user. |
+| `findReplace.openReplace` | Show the find bar with the replace field. |
+| `findReplace.find` | Search with Word-style options and get `{count, truncated, matches}` (up to 200). `query` accepts Word `^` codes (`^p` paragraph mark, `^t` tab, `^#` digit) unless `literal: true`; also `matchCase`, `wholeWord`, `matchPrefix`, `matchSuffix`, `ignorePunctuation`, `ignoreWhitespace`, `wildcards`, `regex`. Prefer `find_text` when you only need positions. |
+| `findReplace.next` | Move to and select the next match of the current search. |
+| `findReplace.previous` | Move to and select the previous match. |
+| `findReplace.replaceAll` | Replace every match in one undo step (tracked when Track Changes is on). Same options as `findReplace.find` plus `replacement` (`^&` is the found text; with `wildcards`, `\1`-`\9` are groups). Returns `{replaced}`. Use over `replace_text` when you need Word-style matching. |
+| `table.insertTable` | Insert a table at the cursor (`rows`, `cols`, `withHeaderRow`). Same as `edit_table` `insertTable`. |
+| `table.addRowBefore` | Add a row above the cursor row. |
+| `table.addRowAfter` | Add a row below the cursor row. |
+| `table.deleteRow` | Delete the selected rows. |
+| `table.addColumnBefore` | Add a column left of the cursor column. |
+| `table.addColumnAfter` | Add a column right of the cursor column. |
+| `table.deleteColumn` | Delete the selected columns. |
+| `table.deleteTable` | Delete the table around the cursor. |
+| `table.mergeCells` | Merge the selected cells. Avoid in data tables. |
+| `table.splitCell` | Split a merged cell back into single cells. |
+| `table.toggleHeaderRow` | Turn the first row into header cells, or back. |
+| `table.toggleHeaderColumn` | Turn the first column into header cells, or back. |
+| `table.toggleHeaderCell` | Turn the selected cells into header cells, or back. |
+| `table.goToNextCell` | Move the cursor to the next cell. |
+| `table.goToPreviousCell` | Move the cursor to the previous cell. |
+| `table.setCellAlignment` | Set horizontal alignment of the selected cells (`align`: left, center, right, justify, or null to clear). |
+| `table.setCellBackground` | Set the background of the selected cells (`color`: CSS colour, or null to clear). |
+
+## Pitfalls
+
+- **Positions are not string offsets.** `get_text` content index 10 is not document position
+  10. Always use positions from `find_text`, `get_text {blocks: true}` or a write's `range`.
+- **Stale positions.** Every write shifts later positions. Work back to front, or re-read.
+- **Literal text only.** The text tools insert plain text; markdown such as `**bold**` or
+  `# Heading` is inserted as those characters. A newline in `text` starts a new paragraph. To create tables use `edit_table`, not pipe characters.
+- **Range limits.** `from` after `to`, or a position beyond the document `size`, is a tool
+  error; nothing is applied.
+- **Read-only documents** expose only `get_text`, `find_text` and `list_document_charts`. If
+  the write tools are missing, the document is read-only; tell the user rather than working
+  around it. `edit_table` exists only when tables are enabled, the chart tools only when
+  charts are, `insert_sparkline` only when sparklines are.
+- **Table targeting.** `edit_table` and the `table.*` commands act on the cell at the cursor.
+  Pass `at` (a position inside the target cell, e.g. a cell block's `from` from
+  `get_text {blocks: true}`) or call `set_selection` first. Row and column deletes act on the
+  selected cells.
+- **Regex.** `regex: true` uses JavaScript syntax; an invalid pattern is a tool error. In
+  `replace_text` the replacement is literal (no `$1`); use `findReplace.replaceAll` with
+  `wildcards` when you need group references.
+- **Agent presence.** Hosts may show your caret and type text out gradually; a long insertion
+  is still one undo step. Do not issue the next write before the previous call returns.
+- **Prompt tokens.** Editing inside a token can break it (`{subj|ect}` changes its default).
+  Replace whole tokens, including braces or underscores. A template that includes itself, or nests
+  deeper than the resolver's limit, resolves to an error marker rather than text. A literal `|`,
+  `{` or `}` inside a variable default must be escaped with a backslash.
+- **Prompt writes return only `{applied, steps}`.** Call `get_editor_state` to see the new
+  text and selection before a second position-based prompt edit.

package/skills/pixerate-spreadsheet/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: pixerate-spreadsheet
+description: How to read and edit a Pixerate spreadsheet through agent tools - reading cells and formula results in A1 notation (get_range), writing values and formulas in bulk (set_range, set_cell), inserting and deleting rows and columns with reference shifting, merging, unmerging and transposing ranges, and the spreadsheet.* commands for filters and hidden rows. Covers tidy-data layout, formulas versus values, supported functions (SUM, XLOOKUP, FILTER, LAMBDA and more) and formula errors such as #REF!, #DIV/0! and #SPILL!. Use when asked to fill, clean, restructure, calculate, total or summarise data in a spreadsheet, sheet, grid, table of cells or workbook.
+---
+
+# Editing spreadsheets
+
+A spreadsheet is a grid of rows and columns addressed in **A1 notation**: columns are
+letters (`A`, `B`, ..., `AA`), rows are 1-based numbers, a range is `A1:C10`. Each cell has
+**raw input** (what was typed, e.g. `=SUM(B2:B9)` or `1,234`) and a **computed value**
+(`4200`), plus an error code when evaluation fails. There are no cell ids; the address is the
+handle. Typed input is parsed like a spreadsheet app: `1,234`, `$5`, `10%`, `(100)` become
+numbers, `TRUE` becomes a boolean, `3/4/2026` becomes the ISO date `2026-03-04`, and a
+leading `'` forces text.
+
+Errors, namespacing and `run_commands` batching are in the `pixerate-agent-tools` skill.
+
+## Working method
+
+1. **Read.** `get_range` on the area you will touch (and its header row). The result gives
+   the sheet size (`sheet.rows`, `sheet.columns`), `values`, `raw` and `errors`. Read a
+   generous range such as `A1:Z50` when you do not know where the data is; it is clamped to
+   the sheet.
+2. **Plan the layout** before writing: where the header row goes, which columns hold inputs
+   and which hold formulas, where totals go.
+3. **Write in blocks.** One `set_range` per rectangular block (headers plus data, or a whole
+   formula column) instead of many `set_cell` calls. It is one undo step, grows the sheet to
+   fit, and refuses the whole write if any target cell is read-only.
+4. **Check.** Every write returns `errors` for the cells it wrote; `get_range` the dependent
+   area (totals, lookups) to confirm the computed values. Fix every `#` error before you
+   finish.
+5. **Restructure deliberately.** Use `insert_rows` / `insert_columns` to make room so
+   formulas shift with the data; never move data by rewriting it cell by cell.
+
+## Best practices
+
+- **Tidy data.** One header row of short, unique, plain-text names. One variable per column,
+  one record per row, one data type per column. No blank rows or columns inside a data
+  region, no subtotals mixed into the data, no notes in data cells.
+- **Inputs, then calculations, then outputs.** Keep raw inputs in their own cells or columns
+  and derive everything else with formulas, so a change to an input flows through. Never
+  type a computed number over a formula.
+- **Formulas over pasted values** whenever the result depends on other cells (totals,
+  ratios, lookups). Write a literal value only for genuine inputs.
+- **No magic numbers.** Put rates and thresholds in a labelled cell and reference it with an
+  absolute reference (`=B2*$F$1`), rather than writing `=B2*0.2`.
+- **Whole-column formulas.** Write a calculated column as one `set_range` with a formula per
+  row (`[["=B2*C2"], ["=B3*C3"], ...]`), or use a dynamic array once at the top
+  (`=B2:B100*C2:C100`) and leave the cells below it empty for the spill.
+- **Ranges that grow.** Totals over a whole column (`=SUM(B:B)`) or over a range that
+  includes a spare row stay correct when rows are appended; put totals above the data or in a
+  separate column if you use whole-column references, so the total does not include itself.
+- **Prefer robust lookups.** `XLOOKUP` or `INDEX`/`MATCH` with exact match over `VLOOKUP`
+  with a hard-coded column number, which breaks when a column is inserted.
+- **Handle expected errors explicitly** with `IFERROR` / `IFNA` around lookups and divisions,
+  and only where an error is expected, so real problems still show.
+- **Keep data regions unmerged.** Merged cells break sorting, filtering, transposing and
+  formulas; use them only for titles outside the data.
+- **Consistent types.** Dates as dates (ISO text `2026-03-04` is safe), numbers without
+  units in the cell (put the unit in the header: `Revenue (USD)`), percentages either as
+  `10%` or `0.1` throughout a column.
+
+## Supported formulas
+
+Operators: `+ - * / ^ & = <> < > <= >=`, whole-column (`A:A`) and absolute (`$A$1`)
+references, spill references (`A1#`). Functions, by group:
+
+- Math: SUM, PRODUCT, ROUND, ROUNDUP, ROUNDDOWN, INT, ABS, SIGN, SQRT, POWER, MOD, CEILING,
+  FLOOR, PI, RAND, RANDBETWEEN.
+- Statistics: AVERAGE, COUNT, COUNTA, COUNTBLANK, MIN, MAX, MEDIAN, MODE, STDEV, VAR, LARGE,
+  SMALL, RANK.
+- Conditional: SUMIF(S), COUNTIF(S), AVERAGEIF(S), MAXIFS, MINIFS.
+- Logical: IF, IFS, IFERROR, IFNA, SWITCH, AND, OR, XOR, NOT.
+- Lookup: XLOOKUP, VLOOKUP, HLOOKUP, INDEX, MATCH.
+- Text: CONCAT, TEXTJOIN, UPPER, LOWER, PROPER, TRIM, LEN, LEFT, RIGHT, MID, FIND, SEARCH,
+  SUBSTITUTE, REPLACE, REPT, EXACT, VALUE, TEXT. (No CONCATENATE; use `&` or CONCAT.)
+- Date: TODAY, NOW, DATE, YEAR, MONTH, DAY, WEEKDAY, DAYS, EDATE, EOMONTH, NETWORKDAYS,
+  DATEDIF.
+- Information: ISBLANK, ISNUMBER, ISTEXT, ISERROR, ISNA.
+- Dynamic arrays: FILTER, SORT, SORTBY, UNIQUE, SEQUENCE, TRANSPOSE, RANDARRAY, LET.
+- Lambda: LAMBDA, MAP, REDUCE, SCAN, BYROW, BYCOL, MAKEARRAY, ISOMITTED.
+
+An unlisted function gives `#NAME?`. Error codes: `#DIV/0!`, `#VALUE!`, `#REF!` (a referenced
+cell was deleted), `#NAME?`, `#N/A` (lookup miss), `#NUM!`, `#CYCLE!` (circular reference),
+`#SPILL!` (an array result is blocked by non-empty cells or the sheet edge), `#CALC!`,
+`#ERROR!`.
+
+## Tool reference
+
+### Read
+
+| Tool | Use it to |
+| --- | --- |
+| `get_range` | Read a cell or range (`range`: `"B2"` or `"A1:C5"`). Returns `range` (clamped to the sheet, null if outside it), `values` (computed, row by row), `raw` (the input or formula text), `errors` (`[{cell, error}]`), `merges` (merged ranges touching it, e.g. `["A1:C1"]`; a merged range keeps its value in its top-left cell) and `sheet` size. Read before every write and after it to check computed results. |
+
+### Write
+
+| Tool | Use it to |
+| --- | --- |
+| `set_range` | Write a 2D block of raw inputs from `start` (top-left cell), row by row, as one undo step. Strings starting with `=` are formulas; `null` or `""` clears a cell; numbers and booleans are stored as typed. Up to 10000 rows by 1000 columns. The sheet grows to fit. All-or-nothing: any read-only target cell fails the whole write. Returns the written `range`, `written` count, `errors` and new `sheet` size. The default write tool. |
+| `set_cell` | Set one cell's raw input (`cell` in A1, `value` string, number or boolean; `=` starts a formula). Returns `raw` and the computed `value`. Fails outside the sheet (it does not grow it; use `set_range` or `insert_rows` first) and on read-only cells. Use for a single fix, not for filling data. |
+| `insert_rows` | Insert `count` (default 1, max 1000) empty rows before row number `before` (1-based; one past the last row appends). Formula references below shift down. |
+| `delete_rows` | Delete `count` rows from row `start` with their contents. References below shift up; formulas that pointed at deleted cells become `#REF!`. Read dependents first. |
+| `insert_columns` | Insert `count` empty columns before column letter `before` (one past the last column appends). References to the right shift. |
+| `delete_columns` | Delete `count` columns from column letter `start` with their contents. References shift left; references to deleted cells become `#REF!`. |
+| `merge_cells` | Merge a `range` of at least two cells into one showing the top-left value, as one undo step. Every other value in the range is cleared, and the result lists the `cleared` cells: move content into the top-left cell first. Refused when the range partly overlaps an existing merge (the error names it), touches read-only cells or a spill range, or leaves the sheet. Use for titles above a table, never inside data. |
+| `unmerge_cells` | Split every merge touching a `range` (a single cell is enough) back into cells; the value stays top-left. Returns the ranges unmerged; fails when there are none (`get_range` lists them). Unmerge before sorting, filtering or transposing a region. |
+| `transpose_range` | Swap rows and columns of a `range` in place, anchored at its top-left (`A1:C2` becomes `A1:B3`), moving values, formulas and formats; formulas that pointed into the range follow their cells. Cells the new shape covers outside the old range are overwritten, so check that area is empty first. Refused across merges (unmerge first), read-only cells or spills. Returns the new range. |
+
+## Commands
+
+Run with `run_command` when the host registers them. Merge, unmerge and transpose act on the
+**user's current selection** and are disabled with "Select a range first." without one; use
+the `merge_cells`, `unmerge_cells` and `transpose_range` tools instead, which take a range.
+Use these commands only when the user asks you to act on what they selected. When there is
+nothing to do they fail with the reason.
+
+| Command | Use it to |
+| --- | --- |
+| `spreadsheet.toggleFilters` | Turn filtering on or off (existing filter rules are kept). Filters hide rows in the view only; data and formulas are unchanged. |
+| `spreadsheet.clearFilters` | Remove all filter rules. Disabled when there are none. |
+| `spreadsheet.unhideAll` | Show every hidden row and column. Do this before reasoning about what the user sees versus what `get_range` returns. |
+| `spreadsheet.mergeCells` | Merge the user's selected range (as `merge_cells`). Destroys every value except the top-left one. |
+| `spreadsheet.unmergeCells` | Remove every merge intersecting the user's selection (as `unmerge_cells`). |
+| `spreadsheet.transposeRange` | Transpose the user's selected range in place (as `transpose_range`). |
+
+## Pitfalls
+
+- **Raw versus computed.** `values` holds results, `raw` holds what to edit. When copying or
+  moving a formula, copy from `raw`; `set_range` writes references as given (it does not
+  offset relative references the way paste or fill-down does), so write each row's formula
+  with its own row number.
+- **Strings that look like formulas or numbers.** Any string starting with `=` becomes a
+  formula; `"007"` becomes the number 7. Prefix with `'` to keep text (`"'007"`).
+- **Read-only cells.** Formula-type columns, read-only columns and read-only cells refuse
+  writes; `set_range` names the cells and writes nothing. Write around them, or tell the user.
+- **Spills.** Leave the cells below and right of a dynamic-array formula empty; anything there
+  turns the anchor into `#SPILL!`. Spilled cells show values in `get_range` but have empty
+  `raw` and cannot be edited on their own; edit the anchor formula.
+- **Deleting rows or columns** turns references to the deleted cells into `#REF!`, and ranges
+  that cross the deletion shrink. Check `get_range` on dependent totals afterwards.
+- **Hidden and filtered rows** are still in the sheet and in `get_range` results and are still
+  counted by `SUM`; only the view hides them.
+- **Dates** are stored as ISO text (`2026-03-04`); compute with date functions, not string
+  operations.
+- **Large ranges.** Read only what you need; a full read of a big sheet costs many tokens.

package/skills/pixerate-vector/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: pixerate-vector
+description: How to draw and edit vector artwork in the Pixerate vector editor through its vector.* commands - adding shapes and SVG paths, fills, strokes, gradients (linear, radial, conic, Oklab interpolation), stroke alignment, arrowheads, variable-width and tapered strokes, live corner radii, boolean operations and Pathfinder (unite, subtract, divide, trim), Shape Builder, paint bucket, live path effects (trim paths, repeater, zig zag, offset), envelope warps and free distort, blends and morphing, anchor editing (join, smooth, simplify, scissors, knife, eraser), align, distribute, group, stacking order, and SVG import and export. Use when creating an icon, logo, illustration, glyph, badge or any Bezier path artwork, or editing an SVG in a Pixerate vector editor.
+---
+
+# Pixerate vector editor
+
+The vector document is an artboard (`width` x `height` in document units, y down) holding a tree
+of **nodes**: `path` nodes (one or more subpaths of Bezier anchors, with fill, stroke and stroke
+settings) and `group` nodes. Groups can also be live booleans, live blends, or carry a live
+effect stack. Every command is a `vector.*` command run with `run_command` / `run_commands` (see
+`pixerate-agent-tools` for batching with `"$0.id"` references, `atomic: true` and error codes).
+
+- **Node ids** come from `vector.list` and from what writes return (`{ id }`, `{ ids }`).
+- **Anchors** are `{ nodeId, subpath, index }`: subpath number within the path, then anchor
+  number within the subpath, both from 0. Commands that take `anchors` default to the points
+  selected with the direct tool; those that take `ids` default to the selection.
+- **Paint** is a CSS colour, `null` for none, or a gradient object
+  `{ type, stops: [{ offset, color, opacity?, midpoint? }], ... }`.
+- Coordinates are document units. A rotated node stores its geometry in its own space: the
+  `bounds` that `vector.list` reports are document-space, its `d` is the node's own.
+
+Parameter details (gradient fields, effect parameters, width profiles, envelopes) are in
+[references/commands.md](references/commands.md).
+
+## Working method
+
+1. **Read.** `vector.list` gives the artboard size, every node depth first (id, type, name,
+   bounds, rotation, fill, stroke, `d`, effects, blend and boolean info) and the selection.
+2. **Plan in layers.** Decide the shapes, their stacking (bottom to top) and their grouping
+   before drawing. Start from primitives (`vector.addShape`) and combine them; write raw `d`
+   only for curves primitives cannot make.
+3. **Write in batches.** Put a construction sequence in one `run_commands` with `atomic: true`
+   and a `label`, chaining ids (`"$0.id"`, `"$last.ids"`), so it is one undo step that applies
+   all or nothing.
+4. **Prefer live, expand last.** Use `live: true` booleans, path effects, envelopes, live
+   corners and blends while designing; bake with `vector.expandAppearance`,
+   `vector.expandBlend` or `vector.outlineStroke` only when the user needs plain paths.
+5. **Check.** `vector.list` again: bounds where you meant them, no stray nodes, sensible names.
+   `vector.exportSvg` gives the final markup; review it, or render it if you can, before handing
+   it over.
+
+## Best practices
+
+- **Clean paths.** Use the fewest anchors that describe the shape: anchors at extrema (top,
+  bottom, left, right of a curve) and at true corners, handles horizontal or vertical at extrema,
+  each handle about a third of its segment. Run `vector.removeRedundantPoints` after
+  booleans, knife and pencil work; `vector.smooth` for lumpy curves; `vector.deleteAnchors`
+  keeps the outline by refitting neighbours.
+- **Live corners over drawn arcs.** Give rectangles, polygons and stars a `cornerRadius`
+  (`vector.addShape`) or set it with `vector.setCorners`; the anchors stay sharp and editable and
+  radii shrink to fit short sides. Keep one radius scale across a design.
+- **Non-destructive first.** Live booleans (`vector.boolean` with `live: true`), path effects
+  and envelopes keep the operands editable. A destructive boolean or Pathfinder replaces its
+  inputs; do that last, and only when asked for flat output.
+- **Boolean vs Pathfinder vs Shape Builder.** `vector.boolean` for a single result shape (union
+  for silhouettes, subtract for cut-outs, intersect, exclude). `vector.pathfinder` when you need
+  every region separately (divide), hidden parts removed (trim, merge) or a crop. Shape Builder
+  when you want to merge or delete particular regions picked by point.
+- **Strokes.** Use `strokeAlign: "inside"` for icons and UI shapes so the outer size stays exact,
+  `outside` for outlines around artwork; open paths always stroke centred. Use round caps and
+  joins for friendly line icons, miter for geometric ones. Keep one stroke width across an icon
+  set (for example 1.5 or 2 units on a 24-unit grid).
+- **Icon grid.** Use a square artboard (24, 32 or 48 units), keep a padding margin, place
+  coordinates on whole or half units so strokes render crisp, and align optical centres.
+- **Gradients.** Two to four stops are usually enough. Use `interpolation: "oklab"` for
+  perceptually even blends without the grey or muddy midpoint sRGB gives between saturated hues;
+  `midpoint` to shift the half-way point instead of adding stops. Prefer linear or radial for
+  portability; conic and diamond export as SVG patterns.
+- **Grouping and naming.** Group the parts of one object (`vector.group` with a `name`), name
+  paths that matter (`name` on add), and keep the tree shallow.
+- **SVG hygiene.** Export with `precision` 2 or 3 (default 3); higher only for tiny artboards.
+  Expand effects, blends and variable-width strokes before handing SVG to tools that do not read
+  Pixerate's `data-vector-*` attributes; other readers see the drawn appearance but not the live
+  source.
+
+## Commands
+
+### Read
+
+| Command | Use it to |
+| --- | --- |
+| `vector.list` | Read the document: `{ width, height, nodes, selection, tool }`. Each node has id, type, name, depth, document-space `bounds`, `rotation` (degrees clockwise), visible, locked, selected, and for paths fill, stroke, strokeWidth and `d`; groups list `children`, `blend`, `liveBoolean`, `effects`. Call it first and after any batch. |
+| `vector.shapeBuilderFaces` | List the regions the given paths divide the plane into: path data, area, a point inside each and the ids of paths filling it. Use the points with `vector.shapeBuilder`. |
+| `vector.exportSvg` | Get the document as standalone SVG markup (`{ svg }`); `precision` 0 to 8 decimals (default 3). |
+
+### Create and delete
+
+| Command | Use it to |
+| --- | --- |
+| `vector.addShape` | Add a `kind` `rect`, `ellipse`, `polygon` (`sides`, at least 3), `star` (`points`, `innerRatio` 0 to 1) or `line` at `x`, `y`, `width`, `height` (all required; for a line, width and height are the end's offset). `cornerRadius` and `cornerKind` give live corners; any style field and `name` apply. Uses the editor's default style for anything not given. Returns `{ id }`. |
+| `vector.addPath` | Add a path from SVG path data `d` (absolute or relative M, L, H, V, C, S, Q, T, A, Z; arcs and quadratics become cubics) in document units, with `name` and style fields; unset style comes from the editor defaults. Fails when `d` has no points. Returns `{ id }`. |
+| `vector.importSvg` | Add the shapes of SVG markup `svg` on top of the document, or replace the document with `replace: true`. Reads paths, basic shapes, groups, transforms and linear and radial gradients; skips text, images, masks, filters and `use`. |
+| `vector.delete` | Delete nodes (`ids`). |
+
+### Style
+
+| Command | Use it to |
+| --- | --- |
+| `vector.setStyle` | Set `fill`, `stroke`, `strokeWidth`, `strokeLinecap` (butt, round, square), `strokeLinejoin` (miter, round, bevel), `strokeDasharray`, `fillRule` (nonzero, evenodd), `strokeAlign` (center, inside, outside; closed shapes only), `startArrow` / `endArrow` (triangle, arrow, open, circle, square, bar, or null), `arrowAlign` (extend, tip), `startArrowScale` / `endArrowScale` (multiples of stroke width, default 1), `strokeWidthProfile` on `ids`. Groups apply to every path inside. Pass at least one field. |
+| `vector.setGradient` | Edit the gradient of the fill (`target` default) or stroke of `ids`: `type` (linear, radial, conic, reflected, diamond), `stops`, `angle` (degrees, 0 up, clockwise), `cx` / `cy` / `r`, explicit `start` / `end` / `width` / `focal`, `units`, `spread`, `interpolation` (srgb default, linear, oklab), `smoothness`, `strokeMode`, `aspect`, `reverse`. Missing fields keep their value; a solid colour becomes a gradient from it to white. Returns the gradient. |
+| `vector.setCorners` | Set live corner `radius` (0 makes them sharp) and / or `kind` (round, inverted, chamfer) on `anchors`, else the selected points, else every corner of `ids`. |
+| `vector.setWidthProfile` | Give strokes a variable width: a `preset` (uniform, taperStart, taperEnd, taperBoth, bulge, pinch, teardrop, wave, pressure; `uniform` removes it), explicit `points`, or a parametric `taper` and / or `wave`. Returns the profile points. |
+| `vector.setWidthPoint` | Set one width point of path `id`: `index` of an existing point (from the profile `vector.setWidthProfile` returns) or none to add one at `t` (0 to 1); `left` / `right` are side widths in document units. Returns the profile. |
+
+### Transform and arrange
+
+| Command | Use it to |
+| --- | --- |
+| `vector.transform` | Move by `dx`, `dy`, scale by `sx`, `sy` (along the selection box axes; `sy` defaults to `sx`; negative flips), rotate by `rotate` degrees clockwise about the combined centre, or set each node to absolute `angle` about its own centre, applied in that order. |
+| `vector.skew` | Skew by `ax` degrees horizontally and `ay` degrees vertically (each -89.9 to 89.9) about the box centre or `origin`. |
+| `vector.distort` | Free Distort in perspective: give `corners`, the four new corners of the selection box (top-left, top-right, bottom-right, bottom-left) in document units, forming a convex quad. `tolerance` (default 0.05) controls curve fidelity. Returns the new bounds. |
+| `vector.align` | Align `ids` on `edge` (left, center, right, top, middle, bottom) to their combined bounds, or to the artboard with `to: "artboard"` (also the default for a single node). |
+| `vector.distribute` | Give three or more nodes equal gaps in `direction` horizontal or vertical. |
+| `vector.arrange` | Change stacking `order` within each node's parent: front, forward, backward, back. |
+| `vector.group` | Group nodes that share a parent, with an optional `name`. Returns `{ id }`. |
+| `vector.ungroup` | Replace groups with their children (ungrouping a blend expands it). |
+| `vector.select` | Select nodes by `ids` (`add: true` to extend; an empty list clears). Selection is the default target of most commands. |
+
+### Combine
+
+| Command | Use it to |
+| --- | --- |
+| `vector.boolean` | Combine two or more paths by `operation` union, subtract (upper shapes from the lowest), intersect or exclude into one new path. With `live: true` the shapes become editable operands of a live boolean group instead (with a lone live group selected, its operation changes). Returns `{ id }`. |
+| `vector.pathfinder` | Run a Pathfinder `operation` over paths bottom to top: `divide` (every face its own shape), `trim` (hidden parts removed), `merge` (trim, then same-fill parts joined), `crop` (top shape crops the rest), `outline` (outlines cut into open strokes), `minusBack` (top minus everything below). Results replace the inputs, grouped when several. Returns `{ ids }`. |
+| `vector.shapeBuilder` | Merge the faces a pointer path touches into one shape, or delete them (and touched line pieces and edges) with `erase: true`. `points` is `[[x, y], ...]` in document units (one point is a click; use points from `vector.shapeBuilderFaces`), `tolerance` for edge picks. Returns counts. |
+| `vector.fillRegion` | Paint bucket: fill the area visible outlines enclose around `point` `[x, y]` with a new path in the current fill (islands stay holes). `gap` closes gaps up to that size between loose ends. Returns `{ id }`. |
+| `vector.outlineStroke` | Turn strokes into filled shapes of exactly the painted area (alignment, caps, joins, dashes, arrowheads, width profiles included), above a copy keeping the fill. Returns the new ids. |
+
+### Live effects and envelopes
+
+| Command | Use it to |
+| --- | --- |
+| `vector.addEffect` | Add a live path effect `type` (trim, roundCorners, puckerBloat, twist, zigzag, wiggle, offset, merge, repeater, envelope) with `params` to `ids`, at `index` in the stack (default last). Effects apply top to bottom. Returns `{ effects: [{ nodeId, effectId }] }`. |
+| `vector.updateEffect` | Change effect `effectId` on `nodeId`: `params` (merged), `enabled`, or move it to `index` (0 applies first). Returns the node's effect stack. |
+| `vector.removeEffect` | Remove effect `effectId` from `nodeId`. |
+| `vector.envelope` | Warp with a live envelope: a `preset` (arc, arcLower, arcUpper, arch, bulge, shellLower, shellUpper, flag, wave, fish, rise, fisheye, inflate, squeeze, twist) with `bend`, `horizontal`, `vertical` (percent, -100 to 100) and `orientation`; or a `mesh` of `rows` x `columns` (1 to 16, optional control `points`); or `topObject: true` (top closed path becomes the envelope), `release: true`, `expand: true`. Reapplying changes an existing envelope. |
+| `vector.expandAppearance` | Bake path effects, envelopes and live booleans of `ids` (and everything inside) into plain paths. Returns the ids. |
+
+### Blends
+
+| Command | Use it to |
+| --- | --- |
+| `vector.blend` | Make a live blend of two or more paths or groups sharing a parent (bottom to top, or the order of `ids` with `keepOrder`): shape and paint morph through in-betweens. `spacing` steps (default; `steps` default 5), distance (`distance` default 20) or smoothColor; `orientToSpine`; `linear` for straight anchor paths; `starts` maps key ids to start anchors. Returns `{ id }`. |
+| `vector.blendOptions` | Change `spacing`, `steps`, `distance`, `orientToSpine`, `linear` of blends; in-betweens regenerate. |
+| `vector.replaceSpine` | With one blend and one path given, make the path the blend's spine; keys spread along it by arc length. |
+| `vector.expandBlend` | Turn blends into plain groups of editable keys and in-betweens. Returns the group ids. |
+| `vector.releaseBlend` | Remove the in-betweens and give back the keys (and a replaced spine as an unpainted path). Returns their ids. |
+
+### Path editing
+
+| Command | Use it to |
+| --- | --- |
+| `vector.moveAnchor` | Move anchor (`nodeId`, `subpath`, `index`) to `x`, `y` in document units, carrying its handles; `curvature: true` bends its two segments like the Curvature tool instead (default: the `curvatureMoves` editing setting, off). |
+| `vector.bendSegment` | Bend segment `segment` (anchor `segment` to the next) of `nodeId` / `subpath` so the curve passes through `x`, `y` at parameter `t` (default 0.5). |
+| `vector.deleteAnchors` | Delete `anchors`. `keepShape` (default the editor setting, on) refits the neighbours so the outline keeps its shape. |
+| `vector.join` | Join open subpaths of `ids`, nearest ends first (ends within `tolerance` merge, others get a straight segment); a single open path is closed. |
+| `vector.average` | Move `anchors` to their average: same y (`axis` horizontal), same x (vertical) or same point (both, default). |
+| `vector.removeRedundantPoints` | Drop anchors that can go without moving the outline more than `tolerance` units (default 0.5). |
+| `vector.smooth` | Pull handles of `ids` (or of `anchors`) towards smooth tangents by `amount` 0 to 1 (default 1). |
+| `vector.cut` | Scissors: cut `nodeId` at the outline point nearest `x`, `y`, or cut at `anchors`. A closed path opens; an open one splits in two. Returns the ids. |
+| `vector.knife` | Cut closed paths along a polyline `points` (at least two `[x, y]`) wherever it crosses them edge to edge, leaving no gap. Cuts `ids`, else the selection, else every path crossed. Returns the pieces. |
+| `vector.erase` | Erase along a polyline `points` with a round eraser of diameter `size` (default the eraser setting, 10): fills lose the area, outlines are cut. Returns the changed ids. |
+
+### Editor settings
+
+| Command | Use it to |
+| --- | --- |
+| `vector.setEditing` | Set editing behaviour: `keepShapeOnDelete`, `curvatureMoves`, `pencilSmoothing` (0 to 1), `recognizeShapes`, `eraserSize`, `pencilPressure` (pen, all, off). Returns the settings. |
+| `vector.setTool` | Switch the interactive tool (select, direct, pen, pencil, rect, ellipse, polygon, star, line, scissors, knife, eraser, width, shapeBuilder, paintBucket, blend, gradient, envelope). Only for handing the canvas to the user in a given mode; commands do not need a tool. |
+
+## Pitfalls
+
+- The `d` in `vector.list` draws live corners cut, which adds anchors. On a path with corner
+  radii, anchor indices counted from `d` do not match the stored anchors; count anchors on a path
+  without corners, or clear corners first.
+- `d` and anchor positions are in the node's own space; `bounds` are in document space. For
+  rotated nodes (`rotation` not 0), `vector.moveAnchor` and `vector.bendSegment` take document
+  coordinates, so compute them from the drawn position, not from `d`.
+- `vector.boolean` without `live` fails when the result is empty (shapes that do not overlap)
+  and consumes its inputs. Subtract removes upper shapes from the lowest: restack with
+  `vector.arrange` first.
+- `vector.blend`, `vector.group` and live booleans need nodes that share a parent.
+- Blend in-betweens are locked and regenerate; edit the keys, not the steps.
+- `strokeAlign` inside and outside only apply when every subpath is closed.
+- Stroke widths, corner radii and effect sizes are kept when scaling: scale them yourself if the
+  design should grow proportionally.
+- `vector.importSvg` without `replace` adds on top; with `replace: true` it discards the current
+  document (undoable, but confirm with the user first).
+- A command that fails changes nothing; read its message (for example "Nothing is selected; pass
+  ids.") and retry with the missing input.