@pixerate/editor 0.139.1 → 0.140.1

package/dist/video-editor/index.js

@@ -134,7 +134,7 @@ import {
   videoTransitionEase,
   videoValueAt,
   videoWipeRect
-} from "../chunk-6NCBFBXA.js";
+} from "../chunk-IQ6KKXOU.js";
 import "../chunk-EHLOCVWB.js";
 import {
   namedWithSuggestion
@@ -143,7 +143,7 @@ import {
   EffectsSlot,
   createEffectToolProvider,
   isEffectError
-} from "../chunk-KHMVB3SJ.js";
+} from "../chunk-7KWJEYIK.js";
 import "../chunk-V2ZCJRDM.js";
 import {
   HistoryManager
@@ -4621,6 +4621,9 @@ function createVideoEditorToolProvider(controller, options = {}) {
   return {
     id: options.id ?? "video",
     namespace: options.namespace,
+    title: "Video editor",
+    description: "Non-linear video editing: assets, tracks and clips, trims, ripples and gaps, transitions and speed, grading and LUTs, keyframes, audio, transcripts, markers, and EDL or ffmpeg export.",
+    skill: "pixerate-video-editor",
     tools: () => readOnlyReason() ? reads : [...reads, ...writes],
     subscribe: (notify) => {
       let last = readOnlyReason();
@@ -4683,6 +4686,9 @@ function createVideoEffectsToolProvider(controller, options = {}) {
   return createEffectToolProvider({
     id: options.id ?? "video-effects",
     namespace: options.namespace,
+    title: "Video effects",
+    description: "Provider effects on video clips, effect clips and effect transitions.",
+    skill: "pixerate-video-editor",
     target: { noun: "clip", id: 'A clip id from get_video_project (e.g. "c1").' },
     applyUses: ["filter", "overlay"],
     applyDetails: "Filters change the clip's picture and overlays draw over it, in stack order, on the picture as it comes from the source, before the clip's grade, placement, opacity and blend; numbers may be keyframed (clip-relative ms). Transitions go through set_video_effect_transition and generators or titles through add_video_effect_clip. The preview renders them frame by frame; the ffmpeg export then needs rendered frames (see export_video_ffmpeg).",

package/dist/video-editor/tools.d.cts

@@ -6,7 +6,7 @@ import { type VideoProject, type VideoSequence } from './types.cjs';
 export interface VideoEditorToolProviderOptions {
     /** Provider id (unique per registry). Default `video`. */
     id?: string;
-    /** Always prefix tool names with `<namespace>__`. */
+    /** Tool-name prefix (`<namespace>__<name>`); defaults to the provider id, `''` for bare names. */
     namespace?: string;
     /** The project cannot be edited: write tools are hidden and `get_video_project` says why. A string is the reason. */
     readOnly?: boolean | string | (() => boolean | string);

package/dist/video-editor/tools.d.ts

@@ -6,7 +6,7 @@ import { type VideoProject, type VideoSequence } from './types.js';
 export interface VideoEditorToolProviderOptions {
     /** Provider id (unique per registry). Default `video`. */
     id?: string;
-    /** Always prefix tool names with `<namespace>__`. */
+    /** Tool-name prefix (`<namespace>__<name>`); defaults to the provider id, `''` for bare names. */
     namespace?: string;
     /** The project cannot be edited: write tools are hidden and `get_video_project` says why. A string is the reason. */
     readOnly?: boolean | string | (() => boolean | string);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor",
-  "version": "0.139.1",
+  "version": "0.140.1",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",
@@ -315,50 +315,51 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@tiptap/extension-character-count": "^2.11.5",
-    "@tiptap/extension-color": "^2.11.5",
-    "@tiptap/extension-highlight": "^2.11.5",
-    "@tiptap/extension-image": "^2.11.5",
-    "@tiptap/extension-link": "^2.11.5",
-    "@tiptap/extension-mention": "^2.11.5",
-    "@tiptap/extension-placeholder": "^2.11.5",
-    "@tiptap/extension-subscript": "^2.11.5",
-    "@tiptap/extension-superscript": "^2.11.5",
-    "@tiptap/extension-table": "^2.11.5",
-    "@tiptap/extension-table-cell": "^2.11.5",
-    "@tiptap/extension-table-header": "^2.11.5",
-    "@tiptap/extension-table-row": "^2.11.5",
-    "@tiptap/extension-task-item": "^2.11.5",
-    "@tiptap/extension-task-list": "^2.11.5",
-    "@tiptap/extension-text-align": "^2.11.5",
-    "@tiptap/extension-text-style": "^2.11.5",
-    "@tiptap/extension-typography": "^2.11.5",
-    "@tiptap/extension-underline": "^2.11.5",
-    "@tiptap/starter-kit": "^2.11.5",
-    "@tiptap/suggestion": "^2.11.5",
+    "@tiptap/extension-character-count": "^2.27.3",
+    "@tiptap/extension-color": "^2.27.3",
+    "@tiptap/extension-highlight": "^2.27.3",
+    "@tiptap/extension-image": "^2.27.3",
+    "@tiptap/extension-link": "^2.27.3",
+    "@tiptap/extension-mention": "^2.27.3",
+    "@tiptap/extension-placeholder": "^2.27.3",
+    "@tiptap/extension-subscript": "^2.27.3",
+    "@tiptap/extension-superscript": "^2.27.3",
+    "@tiptap/extension-table": "^2.27.3",
+    "@tiptap/extension-table-cell": "^2.27.3",
+    "@tiptap/extension-table-header": "^2.27.3",
+    "@tiptap/extension-table-row": "^2.27.3",
+    "@tiptap/extension-task-item": "^2.27.3",
+    "@tiptap/extension-task-list": "^2.27.3",
+    "@tiptap/extension-text-align": "^2.27.3",
+    "@tiptap/extension-text-style": "^2.27.3",
+    "@tiptap/extension-typography": "^2.27.3",
+    "@tiptap/extension-underline": "^2.27.3",
+    "@tiptap/starter-kit": "^2.27.3",
+    "@tiptap/suggestion": "^2.27.3",
     "markdown-it": "^15.0.3",
     "markdown-it-task-lists": "^2.1.1",
     "prosemirror-markdown": "^1.13.8"
   },
   "devDependencies": {
+    "@anthropic-ai/sdk": "0.137.0",
     "@dagrejs/dagre": "^1.1.8",
-    "@tiptap/core": "^2.11.5",
-    "@tiptap/pm": "^2.11.5",
+    "@tiptap/core": "^2.27.3",
+    "@tiptap/pm": "^2.27.3",
     "@types/dagre": "^0.7.54",
     "@types/markdown-it": "^14.2.0",
     "@types/node": "^26.6.5",
     "assemblyscript": "0.28.20",
     "fast-check": "^3.23.2",
-    "mermaid": "12.0.0",
+    "mermaid": "12.2.0",
     "tiptap-markdown": "^0.8.10",
-    "tsup": "^8.4.0",
+    "tsup": "^9.0.0",
     "typescript": "^5.7.3",
     "vitest": "^5.0.5"
   },
   "peerDependencies": {
     "@dagrejs/dagre": "^1.1.8",
-    "@tiptap/core": "^2.11.5",
-    "@tiptap/pm": "^2.11.5"
+    "@tiptap/core": "^2.27.3",
+    "@tiptap/pm": "^2.27.3"
   },
   "peerDependenciesMeta": {
     "@dagrejs/dagre": {
@@ -370,6 +371,7 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:corpus": "node scripts/fetch-psd-corpus.mjs && PSD_CORPUS=1 vitest run tests/psd-corpus.test.ts",
-    "build:wasm": "node scripts/build-wet-wasm.mjs"
+    "build:wasm": "node scripts/build-wet-wasm.mjs",
+    "eval:tools": "vitest run --config vitest.eval.config.ts --disableConsoleIntercept"
   }
 }

package/skills/README.md

@@ -7,7 +7,7 @@ that uses the tools can load the matching skill.
 
 | Skill | Covers |
 | --- | --- |
-| [`pixerate-agent-tools`](pixerate-agent-tools/SKILL.md) | What every editor has in common: the MCP bridge, tool naming and namespaces, `list_commands` / `run_command` / `run_commands`, errors, undo. Load it with any domain skill. |
+| [`pixerate-agent-tools`](pixerate-agent-tools/SKILL.md) | What every editor has in common: the MCP bridge, toolsets and tool naming, finding tools with `list_toolsets` / `search_tools` / `enable_tools` / `get_skill`, `list_commands` / `run_command` / `run_commands`, errors, undo. Load it with any domain skill. |
 | [`pixerate-rich-text`](pixerate-rich-text/SKILL.md) | Documents and prompts: text, tables, find and replace, charts in documents, prompt variables. |
 | [`pixerate-spreadsheet`](pixerate-spreadsheet/SKILL.md) | Cells, ranges, rows and columns, filters, merges. |
 | [`pixerate-canvas`](pixerate-canvas/SKILL.md) | Node-graph canvas, components and variants, arranging, shape booleans, keyframe animation. |
@@ -29,8 +29,13 @@ Copy or symlink the directories into your agent's skills folder, for example for
 cp -R node_modules/@pixerate/editor/skills/* .claude/skills/
 ```
 
-Skills use bare tool names (`get_chart`). A host that namespaces providers exposes them as
-`<namespace>__get_chart`.
+Skills use bare tool names (`get_chart`). Registries expose them as `<toolset>__get_chart`
+(the provider's namespace, or its id), and accept the bare name when only one toolset has it.
+
+They can also be served rather than copied: the MCP bridge (`pixerate-mcp-bridge`) serves them as
+MCP prompts and `skill://<name>/SKILL.md` resources, `createMcpServer(source, { skills })` does
+the same for your own server, and a discovery view (`registry.view({ discovery: { skills } })`)
+adds a `get_skill` tool. In Node, `loadSkillFiles()` from `@pixerate/editor/bridge` reads them.
 
 ## Maintaining them
 

package/skills/pixerate-agent-tools/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pixerate-agent-tools
-description: How to drive any Pixerate editor (rich text, spreadsheet, canvas, vector, chart, diagram, image, animation, video, generation) through its agent tools - finding the right editor over the MCP bridge, reading tool names and namespaces, running editor commands with list_commands / run_command / run_commands, batching with result references, undo, and recovering from tool errors. Use whenever Pixerate editor tools are available, before the domain skill for the editor at hand.
+description: How to drive any Pixerate editor (rich text, spreadsheet, canvas, vector, chart, diagram, image, animation, video, generation) through its agent tools - finding the right editor over the MCP bridge, reading toolset-namespaced tool names, finding tools in a large catalogue with list_toolsets / search_tools / enable_tools and reading a toolset's skill with get_skill, running editor commands with list_commands / run_command / run_commands, batching with result references, undo, and recovering from tool errors. Use whenever Pixerate editor tools are available, before the domain skill for the editor at hand.
 ---
 
 # Driving Pixerate editors with agent tools
@@ -15,16 +15,35 @@ editor domain has its own skill for its tools: `pixerate-rich-text`, `pixerate-s
 
 ## How tools are named
 
-- Tool names are `snake_case` verbs on a noun: `get_*` / `list_*` / `find_*` / `render_*` read,
-  everything else writes.
-- When several editors register a tool with the same name, or a host gives a provider a
-  namespace, the name is prefixed: `chart__get_chart`, `doc-1__find_text`. Skills use the bare
-  name; match on the suffix after `__`.
+- Tools come in toolsets, one per open editor or feature (`chart`, `video`, `image-editor`,
+  `doc-1`), and are named `<toolset>__<tool>`: `chart__get_chart`, `doc-1__find_text`. Skills use
+  the bare name; match on the part after `__`.
+- The tool part is a `snake_case` verb on a noun: `get_*` / `list_*` / `find_*` / `render_*`
+  read, everything else writes.
+- A bare name (`get_chart`) also works when only one toolset has that tool. When several do (two
+  documents open), the error names each full name: pick the one for the editor you mean.
 - The annotations are reliable: `readOnlyHint: true` never changes anything, `destructiveHint:
   true` removes content, `idempotentHint: true` is safe to retry.
 - The tool list changes while you work (an editor mounts, a chart becomes read-only and its
   write tools disappear). If a tool you used before is gone, list tools again rather than guess.
 
+## Finding the right tool
+
+A host with many editors open can have hundreds of tools. It may list them all, only the open
+editor's, or (in discovery mode) only `list_toolsets`, `search_tools`, `enable_tools`,
+`disable_tools` and `get_skill` at first.
+
+1. **Know what is open.** `list_toolsets` gives each toolset's title, what it covers, its skill
+   and whether its tools are in your list.
+2. **Search by task, not by guessing names.** `search_tools` with a few plain words ("add a
+   trendline", "remove silences") returns the best matches with a one-line summary. Pass
+   `toolset` to search one editor.
+3. **Enable only what you need.** `enable_tools` with the tool names from the search (or a whole
+   toolset when you will use many of its tools). The tools then appear in your list. Use
+   `disable_tools` to drop a toolset you are done with.
+4. **Read the skill before working in a toolset.** `get_skill` with the skill `list_toolsets`
+   names (or the MCP prompt / `skill://` resource of the same name).
+
 ## Working method
 
 1. **Read before you write.** Start with the domain's `get_*` tool. Write tools take the ids,
@@ -51,7 +70,9 @@ it, with `structuredContent.error.code`:
   Fix the arguments and call again.
 - `tool_failed`: the editor refused the change (unknown id, out-of-range position, read-only
   target). Nothing was applied. Read the state again, then retry with valid input.
-- `unknown_tool`: the tool is not registered now (the editor closed, or it is read-only).
+- `unknown_tool`: the tool is not registered now (the editor closed, or it is read-only), a
+  bare name matches several toolsets (use a full name from the message), or this agent may not
+  use that toolset or write at all (the message says which).
 
 Never repeat an identical failing call. Never work around a read-only refusal; tell the user.
 
@@ -60,6 +81,11 @@ Never repeat an identical failing call. Never work around a read-only refusal; t
 | Tool | Use it to |
 | --- | --- |
 | `list_editors` | See which editors are open in the browser and connected to the MCP bridge (id, name, kind, tool count, last activity). Call it first when tools come through the bridge; pass an id or part of a name as `editor` to any tool to pick one when several are open, otherwise the most recently active editor with that tool answers. If none is connected, ask the user to open the app and connect it. |
+| `list_toolsets` | See the toolsets open now: name, title, what each covers, its skill, how many tools it has and whether they are in your tool list (`enabled`: all, some, none). Call it first in a discovery view, then `search_tools` or `enable_tools`. |
+| `search_tools` | Find the tool for a task: pass `query` in plain words (and `toolset` to search one editor, `limit` for more than 10). Returns the best matches first with name, toolset, title, one-sentence summary, whether it only reads and whether it is listed. Follow with `enable_tools`. |
+| `enable_tools` | Add tools to your tool list by full name (`tools`, from `search_tools`) and/or whole `toolsets` (from `list_toolsets`). Returns the names added and how many are listed. Prefer single tools to large toolsets. Unknown names fail and change nothing. Allowed tools can also be called by name without enabling them. |
+| `disable_tools` | Drop tools or whole toolsets you are done with from your tool list, to keep it short. Returns the names removed. |
+| `get_skill` | Read a toolset's skill (markdown) before working with it; pass `file` for one of its reference files (listed at the top). The note at the top says how names are prefixed here. |
 | `list_commands` | Discover the commands an editor registers: id, label, group, params JSON Schema, shortcuts, and whether each is enabled now (with the reason when it is not). Filter with `query`; pass `enabledOnly: true` to see only what you can run now. |
 | `run_command` | Run one command by `id` with `params` matching its schema. Disabled commands and unknown params fail with a reason; read it before retrying. |
 | `run_commands` | Run several commands in order as `steps`. A param string `"$0.id"` or `"$last.id"` is replaced by that path of an earlier step's result, so a step can use an id an earlier step created. Pass `atomic: true` and a `label` to make the batch one undo step that rolls back entirely on failure; without it, steps before a failure stay applied. |

package/skills/pixerate-animation-editor/SKILL.md

@@ -34,6 +34,8 @@ The full command vocabulary (every type, option and default) is in
    edits as one undo step (`dry_run: true` first when unsure; `"$0.indexes[0]"` and
    `"$last.shot"` refer to earlier ops). Refine with `add_commands`, `update_command`,
    `move_command`, `delete_commands`. Use `write_animation` only to replace every shot.
+   For a command type you have not written before, `describe_animation_command` returns its
+   exact fields first.
 4. **Fit and cue.** `fit_animation` to hit a length (keep shots whose pace matters). For music
    or voiceover, `set_animation_settings` with `beat` or `narration`, read cues with
    `get_timing_grid`, and give shots `"at": { "beat": n }` or `{ "word": i }`.
@@ -88,6 +90,7 @@ The full command vocabulary (every type, option and default) is in
 | --- | --- |
 | `get_animation` | Start here. Returns name, artwork size, length (ms), loop, elements (id, type, name, parent, bounds, solid paints, live effects with numeric params), every shot with each command's index, start, end and `flairPrimitive`, clips, drivers, controls and an issue summary, plus `readOnly` when edits are refused. `includeElements: false` (default true) skips the element list on large artwork. |
 | `get_shot` | Read one shot as stored (`shot` id) with its start/end and each command's start/end in ms; cheaper than `get_animation` while refining one shot. |
+| `describe_animation_command` | Before writing a command type you have not used yet, or when a write rejects a field: returns the full JSON Schema of each of `types` (e.g. `["enter", "move"]`), with every field's type, range, default and meaning and which are required. The write tools list every command field once in short, prefixed with the types that take it. |
 | `find_animation_elements` | Find elements whose id or name contains `query` (case-insensitive; `limit` default 20, max 200) when the artwork is large. Returns id, type, name, parent, bounds, paints, effects. |
 | `get_text_layout` | Before animating outlined text with `split`: returns the `group`'s lines, words and letter ids in reading order. Errors if the element is not a group of paths (convert text to outlines, one path a letter, and group it). |
 | `get_motion_path` | Check spacing, arcs and landing points as numbers: samples a `node`'s centre (document units) from `from` to `to` ms every `step` ms (default 33, at most 400 samples), with where each moving change starts and ends. |
@@ -150,6 +153,10 @@ refuse.
 - **Some provider motion cannot be carried over.** Counting, writing text and similar changes are
   skipped. The result's `notes` say what was left out.
 
+- **Fields belong to types.** The write tools' command schema lists every field of every type
+  once; a field the type does not take (`clip` on a `move`, `to` as a point on a `fade`) is
+  refused when the edit is applied, naming the shot, command and field. Call
+  `describe_animation_command` for the exact fields of a type rather than guessing.
 - **Unknown ids are refused** with a "did you mean" suggestion. Take ids from `get_animation` or
   the elements `set_animation_artwork_svg` returns; never guess them.
 - **`enter-visible`**: an element that enters while already showing blinks out first. Give an

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

@@ -1,6 +1,6 @@
 ---
 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.
+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), formatting (format_text for bold, italic, links and colour; set_block_type for headings, lists and quotes; set_text_align), 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
@@ -35,7 +35,11 @@ Errors, namespacing (`doc-1__find_text`) and `run_commands` batching are covered
    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.
+5. **Format.** Write the words first, then format them: `find_text` (or the write's `range`)
+   gives the positions for `format_text` (bold, italic, links, colour...), `set_block_type`
+   (headings, lists, quotes, code blocks) and `set_text_align`. Never type markdown such as
+   `**bold**` or `# Heading`; it is inserted as those characters.
+6. **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
@@ -89,6 +93,9 @@ Errors, namespacing (`doc-1__find_text`) and `run_commands` batching are covered
 | `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. |
+| `format_text` | Set or clear inline formatting on `from`..`to` (or the selection when both are omitted): `bold`, `italic`, `underline`, `strike`, `code` (true sets, false clears), `link` (a URL, or null to remove), `highlight` and `color` (CSS colours, or null), `fontSize` (e.g. `"18px"`, or null). Only the properties you pass change; the schema decides which exist. One undo step; the user's selection stays put. Returns the `range`, its `text` and the `formatting` now on it (`partly` / `mixed` where only some of the text has it). Position from `find_text`. |
+| `set_block_type` | Make every block the range touches (or the one at the cursor) a `paragraph`, `heading` (with `level`, 1 to 4 by default), `bullet_list`, `ordered_list`, `task_list`, `blockquote` or `code_block`. Blocks leave any list or quote first, so one call switches a bulleted list to a numbered one; `paragraph` takes them out of lists and quotes. Returns the resulting `blocks` (type, positions, text, level, align, the list or quote they are `in`). |
+| `set_text_align` | Align every paragraph and heading the range touches: `left`, `center`, `right`, `justify`, or null for the default. Returns the `blocks` with their `align`. Table cells are aligned with `edit_table` `setCellAlignment` instead. |
 | `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. |
@@ -136,10 +143,17 @@ Run with `run_command` / `run_commands` when the host registers them. Check
   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.
+  `# Heading` is inserted as those characters. A newline in `text` starts a new paragraph.
+  Format with `format_text` and `set_block_type` after writing; create tables with
+  `edit_table`, not pipe characters.
+- **Formatting a heading.** Headings are already bold in most themes; make a phrase a heading
+  with `set_block_type`, not with `format_text` `bold` and a bigger `fontSize`.
+- **Inline code.** In most schemas `code: true` removes the other marks on that text, and a
+  code block drops all marks.
 - **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
+- **Read-only documents** expose only `get_text`, `find_text` and `list_document_charts` (no
+  formatting tools). 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.