datanotes 2.0.1 → 3.1.0

package/dist/docs/guides/agents/prompts.md

@@ -0,0 +1,495 @@
+# Prompts for your agent
+
+> Copy prompts for everyday notes, schema changes, history and imports, with the tools the agent calls and the same calls from code.
+
+Once your agent is [connected](https://datanotes.dev/start/connect-agents/), you talk to your vault in plain words. This page gives prompts to copy, grouped by task. They all use one example: a diary of classic films with the tables `film`, `actor`, `genre` and `watch`.
+
+For each prompt you see what happens, the [operations](https://datanotes.dev/reference/operations/) the agent calls, in order, and what you get. Each one ends with the same call from code, for when you’d rather script it.
+
+The tool sequences and answers come from runs against a real engine through `datanotes mcp`, the Model Context Protocol (MCP) server. Your agent may add a read here and there, such as a second `describe_table`, but the writes are the ones shown.
+
+## Call the same operations from code
+
+Every tool of the agent is an operation of the [HTTP API](https://datanotes.dev/develop/http-api/), so a script makes the calls the agent makes. The snippets on this page use one client of [`datanotes/client`](https://datanotes.dev/develop/client/):
+
+```ts
+import { DatanotesClient } from "datanotes/client";
+
+
+const db = new DatanotesClient({
+  url: "http://127.0.0.1:27150",
+  token: process.env.DATANOTES_TOKEN ?? "",
+  actor: { harness: "my-script" },
+});
+```
+
+`db.call(name, args)` takes the agent’s tool name and arguments, and sends the request the [HTTP API reference](https://datanotes.dev/api/) lists for it. With curl, you send the same JSON to the operation’s route, `POST /datanotes/operations/<operation>/`. The body holds the operation’s arguments, with the same names as the agent’s tool.
+
+## Prompts for everyday notes
+
+These prompts read and write rows of your diary. They need the `watch` table and the `vw_to_watch` view, which the [schema prompts](#schema-prompts) create.
+
+### Log a viewing with where, when and who
+
+```text
+I watched Metropolis tonight at 20:30 at the film club downtown, with
+Anna. Live organ accompaniment. Five stars. Log it in my film diary.
+```
+
+The agent finds the film, adds a `watch` row and marks the film watched, in one `batch`, so both writes succeed or fail together.
+
+* **Tools**: `list_tables`, `describe_table` on `watch`, `select_rows` on `film` for `Metropolis`, then `batch` with `insert_row` and `update_row`
+* **You get**: a new note, `main/public/watch/2026-10-09T2030.md`, and `Metropolis` with `status: watched`, `rating: 5` and `watched_on: 2026-10-09`; one `undo_migration` on the batch’s `migration_id` reverts both
+
+From code, the batch is `POST /datanotes/operations/batch/`:
+
+```ts
+await db.call("batch", {
+  summary: "Log the screening of Metropolis",
+  operations: [
+    {
+      op: "insert_row",
+      table: "watch",
+      values: {
+        film: "[[Metropolis]]",
+        occurred_at: "2026-10-09T20:30:00",
+        where: "cinema",
+        place: "the film club downtown",
+        with: "Anna",
+      },
+      body: "Live organ accompaniment.\n",
+    },
+    {
+      op: "update_row",
+      table: "film",
+      path: "main/public/film/Metropolis.md",
+      set: { status: "watched", rating: 5, watched_on: "2026-10-09" },
+    },
+  ],
+});
+```
+
+### Mark a film to watch
+
+```text
+Put Battleship Potemkin on my watchlist: 1925, 75 minutes, directed by
+Sergei Eisenstein, Soviet montage.
+```
+
+The agent matches “watchlist” against the aliases of the `film` table, checks that the film isn’t there yet, and adds it.
+
+* **Tools**: `list_tables`, `select_rows` on `film` for the title, then `insert_row`
+* **You get**: `main/public/film/Battleship Potemkin.md`, with `status: to watch` and a link to the `Soviet montage` genre
+
+From code, `POST /datanotes/operations/insert_row/`:
+
+```ts
+await db.call("insert_row", {
+  table: "film",
+  values: {
+    title: "Battleship Potemkin",
+    year: 1925,
+    minutes: 75,
+    director: "Sergei Eisenstein",
+    genre: "[[Soviet montage]]",
+    status: "to watch",
+  },
+});
+```
+
+### Ask what to watch tonight
+
+```text
+What should I watch tonight? I have about an hour and a half.
+```
+
+The agent finds the view of your watchlist and narrows it to films that fit the evening.
+
+* **Tools**: `list_tables`, which lists `vw_to_watch` under `views`, then `select_rows` on the view with a filter on `minutes`
+* **You get**: Battleship Potemkin, 75 minutes; Metropolis, at 153 minutes, waits for a longer evening
+
+From code, `POST /datanotes/operations/select_rows/`:
+
+```ts
+const tonight = await db.call("select_rows", {
+  table: "vw_to_watch",
+  where: { minutes: { lte: 100 } },
+});
+```
+
+### Find the films you saw with someone
+
+```text
+Which films did I see with Anna this year?
+```
+
+The agent reads the `watch` table, where `with` holds who came along, and matches the name case-insensitively.
+
+* **Tools**: `list_tables`, `describe_table` on `watch`, then `select_rows` with `icontains` on `with` and `gte` on `occurred_at`
+* **You get**: Sherlock Jr. at home in February, His Girl Friday at the cinema in March, Nosferatu at an outdoor screening in June, and Metropolis tonight
+
+From code, `POST /datanotes/operations/select_rows/`:
+
+```ts
+await db.call("select_rows", {
+  table: "watch",
+  where: { with: { icontains: "anna" }, occurred_at: { gte: "2026-01-01" } },
+  columns: ["occurred_at", "film", "where"],
+  order_by: "occurred_at",
+});
+```
+
+### Write your review
+
+```text
+Add my review of Charade under a "My review" heading: Grant and Hepburn
+trade lines across Paris while everyone lies about the money.
+```
+
+The agent reads the note’s body first, then writes the review under its own heading and keeps the rest of the note.
+
+* **Tools**: `select_rows` on `film` with `include_body`, then `update_row` with `body_sections`
+* **You get**: a `## My review` section at the end of `Charade.md`, below the text the note already had
+
+From code, `POST /datanotes/operations/update_row/`:
+
+```ts
+await db.call("update_row", {
+  table: "film",
+  path: "main/public/film/Charade.md",
+  body_sections: {
+    "My review":
+      "Grant and Hepburn trade lines across Paris while everyone lies " +
+      "about the money.",
+  },
+});
+```
+
+## Schema prompts
+
+These prompts change the tables themselves. The agent changes `metastore.yaml` only through schema operations, which check the change against the rows, journal it and make it undoable. To limit which agents may change the schema, give them a [named token](https://datanotes.dev/start/connect-agents/#give-each-agent-its-own-token) without `ddl`.
+
+### Create the watch table
+
+```text
+Create a table for each time I watch a film: when, the film, where
+(cinema, home or outdoor screening), the place in my words, and who came
+along.
+```
+
+The agent checks that no table records viewings yet, then creates one named by the date and time of each viewing.
+
+* **Tools**: `list_tables`, `describe_table` on `film` to link to it, then `create_table`
+* **You get**: `main.public.watch` in `metastore.yaml`, with `occurred_at` as its time column, so the engine names each note like `2026-10-09T2030.md`; its description and aliases lead an agent to it from words such as “diary”, and each column says what it holds
+
+The engine refuses a table or a column without a description, so the agent writes one for each.
+
+From code, `POST /datanotes/operations/create_table/`:
+
+```ts
+await db.call("create_table", {
+  name: "watch",
+  description: "Each time I watch a film: when, where and with whom",
+  time_column: "occurred_at",
+  columns: [
+    {
+      name: "occurred_at",
+      type: "datetime",
+      required: true,
+      description: "When the film started",
+    },
+    {
+      name: "film",
+      type: "link",
+      ref: "main.public.film",
+      required: true,
+      description: "The film I watched",
+    },
+    {
+      name: "where",
+      type: "enum",
+      values: ["cinema", "home", "outdoor screening"],
+      required: true,
+      description: "The kind of place I watched it in",
+    },
+    { name: "place", type: "string", description: "Where, in my words" },
+    { name: "with", type: "string", description: "Who came along" },
+  ],
+  aliases: ["viewings", "screenings", "diary"],
+});
+```
+
+### Add a column
+
+```text
+Add a column to my film diary for what the ticket cost.
+```
+
+The agent reads the table first, to reuse a column that already means the same, and adds a new one only when none does.
+
+* **Tools**: `describe_table` on `watch`, then `add_column`
+* **You get**: a `price` column, a number of 0 or more with two decimals; existing rows stay as they are, because the engine writes a sparse column only on rows that have a value
+
+From code, `POST /datanotes/operations/add_column/`:
+
+```ts
+await db.call("add_column", {
+  table: "watch",
+  column: {
+    name: "price",
+    type: "number",
+    min: 0,
+    step: 0.01,
+    description: "What the ticket cost",
+  },
+});
+```
+
+### Add the CHECK rated_when_watched
+
+```text
+A film I've watched must have a rating. Make that a rule of the film table.
+```
+
+The agent writes the rule as a filter every row must pass: a film is either not watched, or has a rating.
+
+* **Tools**: `describe_table` on `film`, then `add_constraint`
+* **You get**: the CHECK `rated_when_watched`; the engine refuses it while a row breaks it, listing the rows, and from then on refuses any write that breaks it
+
+Once the rule exists, the engine refuses to mark Battleship Potemkin as watched without a rating, and writes nothing:
+
+```text
+update_row refused — nothing was written:
+invalid main/public/film/Battleship Potemkin.md: rated_when_watched violates CHECK rated_when_watched: {"or":[{"status":{"ne":"watched"}},{"rating":{"exists":true}}]}
+```
+
+The agent then asks you for a rating. From code, the CHECK is `POST /datanotes/operations/add_constraint/`:
+
+```bash
+curl -s http://127.0.0.1:27150/datanotes/operations/add_constraint/ \
+  -H "Authorization: Bearer your_owner_token" \
+  -H "Content-Type: application/json" \
+  -d '{"table": "film",
+       "name": "rated_when_watched",
+       "check": {"or": [{"status": {"ne": "watched"}},
+                        {"rating": {"exists": true}}]}}'
+```
+
+### Make a view of the films to watch
+
+```text
+Make a view of the films I still have to watch, shortest first.
+```
+
+The agent stores the query as a view, with a description and aliases so that later questions such as “what’s on my watchlist?” find it.
+
+* **Tools**: `list_tables`, to reuse a view that exists, then `create_view`
+* **You get**: `vw_to_watch` in `metastore.yaml`, which `list_tables` lists under `views` and `select_rows` reads like a table
+
+From code, `POST /datanotes/operations/create_view/`:
+
+```ts
+await db.call("create_view", {
+  name: "vw_to_watch",
+  query: {
+    table: "film",
+    where: { status: "to watch" },
+    columns: ["title", "year", "minutes", "director"],
+    order_by: "minutes",
+  },
+  description: "Films on my watchlist, shortest first",
+  aliases: ["watchlist", "what to watch"],
+});
+```
+
+## Safety and history prompts
+
+These prompts show what an agent changed and take it back. Every write is in the journal, so `undo_migration` works on any table. Reading a table as it was and restoring the whole database need the tables’ history. A database the engine creates has it on. A database whose `metastore.yaml` lacks the setting, such as one from a version before 3.0.0, has it off. Turn it on once:
+
+```text
+Turn history on for every table.
+```
+
+The agent calls `configure_database` with `history: true`. The journal doesn’t record database settings, so an agent changes them only when you ask. From code, it’s `POST /datanotes/operations/configure_database/` with `{"history": true}`.
+
+### Ask what the agent changed today
+
+```text
+What did you change in my vault today?
+```
+
+The agent reads the journal, where every operation names the agent that made it.
+
+* **Tools**: `list_migrations` with `since`, or `describe_history` without a table for the commits of every table with their full actor
+* **You get**: one line per operation, each with `by: "claude-code"`, such as `batch` “Log the screening of Metropolis” or `add_constraint` on `film`; your own writes from an editor or a script name their own source
+
+From code, `POST /datanotes/operations/list_migrations/`:
+
+```ts
+const today = await db.call("list_migrations", { since: "2026-10-09" });
+```
+
+### Undo the agent’s last change
+
+```text
+Undo your last change.
+```
+
+The agent finds its newest operation in the journal and reverts it.
+
+* **Tools**: `list_migrations`, then `undo_migration` with its `migration_id`
+* **You get**: the notes as they were before that operation, and the undo’s own `migration_id`, since the journal records the undo too; if you edited one of the notes since, the engine refuses and lists the conflicts instead of overwriting your edit
+
+From code, `POST /datanotes/operations/undo_migration/`:
+
+```ts
+await db.call("undo_migration", {
+  migration_id: "20261009T215306-batch-log-the-screening-of-metropoli",
+});
+```
+
+### Put everything back as it was before the agent started
+
+```text
+Put everything back as it was before you started this evening. Show me
+what would change first.
+```
+
+The agent finds its first operation of the session, previews the restore, and runs it once you agree.
+
+* **Tools**: `describe_history` without a table, then `restore_database` with `before_migration` and `dry_run: true`, then `restore_database` again without `dry_run`
+* **You get**: every table with history back to that moment, in one operation that `undo_migration` can revert; in the run behind this page, the restore removed Battleship Potemkin and tonight’s `watch` row, and gave Metropolis and Charade their old content back
+
+The dry run lists what changes in each table before the engine writes anything. Here is its answer, trimmed:
+
+```json
+{
+  "ok": true,
+  "dry_run": true,
+  "planned_deletes": [
+    "main/public/film/Battleship Potemkin.md",
+    "main/public/watch/2026-10-09T2030.md"
+  ],
+  "planned_texts": [
+    "main/public/film/Metropolis.md",
+    "main/public/film/Charade.md"
+  ],
+  "unchanged": ["main.public.actor", "main.public.genre"],
+  "skipped": []
+}
+```
+
+The restore doesn’t rewind views or database settings, and lists a table without history in `skipped`. From code, `POST /datanotes/operations/restore_database/`:
+
+```ts
+await db.call("restore_database", {
+  before_migration: "20261009T215329-insert_row-insert-into-film",
+  dry_run: true,
+});
+```
+
+### Read a note as it was last week
+
+```text
+Show me Nosferatu as it was last week.
+```
+
+The agent reads the `film` table at a past time and picks the row.
+
+* **Tools**: `select_rows` on `film` with `timestamp`, and `describe_history` on `film` when you ask what changed since
+* **You get**: the row with the values it had then, and the table `version` the engine read; if the table didn’t exist yet at that time, the engine answers `main.public.film did not exist at 2026-10-02T09:00:00Z`
+
+From code, `POST /datanotes/operations/select_rows/`:
+
+```ts
+await db.call("select_rows", {
+  table: "film",
+  where: { title: "Nosferatu" },
+  timestamp: "2026-10-02T09:00:00Z",
+});
+```
+
+## Import prompts
+
+This prompt turns notes you already have into rows, without moving them.
+
+### Turn a folder of notes into a table
+
+```text
+Turn my Films/ folder into a table. Show me the columns you propose
+before you create anything.
+```
+
+The agent reads the notes’ front matter, proposes a table, and waits for your review. Review it: on five notes, `infer_table` marked `director` and `minutes` as `unique`, because no two notes shared a value. The engine would then refuse a sixth film by the same director, so ask the agent to drop `unique` there.
+
+The notes can’t say what each key means, so the proposal leaves every `description` `null`. The agent writes them and asks you when a key isn’t clear. `create_table` refuses a table or a column without one.
+
+* **Tools**: `list_folder` on `Films`, `infer_table` with `folder: "Films"`, then, after your review, `create_table` with the reviewed and described proposal, `adopt_rows` with `dry_run: true`, `adopt_rows`, and `check_table`
+* **You get**: a `film` table whose rows are your notes, moved to the table’s folder with the links to them rewritten; each note gets `table` and an `id`, and keeps its body; `check_table` reports no violations
+
+`infer_table` returns `proposal`, the arguments of `create_table`, and `adopt`, the arguments of `adopt_rows`. From code, the inference is `POST /datanotes/operations/infer_table/`:
+
+```ts
+const inferred = await db.call("infer_table", {
+  folder: "Films",
+  name: "film",
+});
+const { proposal, adopt } = inferred.value as {
+  proposal: { columns: { name: string }[] };
+  adopt: Record<string, unknown>;
+};
+```
+
+After you review `proposal`, create the table. The notes keep the title in their file name, so add a `title` column with `identity: "filename"` and name the rows with `filename: "{title}"`. Write a description for every column, or `create_table` refuses the table:
+
+```ts
+const meaning: Record<string, string> = {
+  year: "Year the film first came out",
+  minutes: "Running time in minutes",
+  director: "Who directed the film",
+  // … one for each column of the proposal
+};
+const created = await db.call("create_table", {
+  ...proposal,
+  description: "Classic films I watched or want to watch",
+  filename: "{title}",
+  columns: [
+    {
+      name: "title",
+      type: "string",
+      identity: "filename",
+      description: "The film's title, which is also its note's name",
+    },
+    ...proposal.columns.map((c) => ({
+      ...c,
+      unique: false,
+      description: meaning[c.name],
+    })),
+  ],
+});
+if (!created.ok) throw new Error(String(created.value));
+```
+
+Then adopt the notes with `POST /datanotes/operations/adopt_rows/`. `relocate` moves them to the table’s folder and rewrites the links to them:
+
+```ts
+const { paths, rename } = adopt as {
+  paths: string[];
+  rename: Record<string, string>;
+};
+const adopted = await db.call("adopt_rows", {
+  table: "film",
+  paths,
+  rename,
+  relocate: true,
+});
+if (!adopted.ok) throw new Error(String(adopted.value));
+```
+
+## Learn more about agents and operations
+
+These pages go deeper into what the prompts use:
+
+* [How agents work with your vault](https://datanotes.dev/guides/agents/how-agents-use-datanotes/): what the agent reads first, how it finds tables and what the journal records
+* [Guides](https://datanotes.dev/guides/database-objects/tables/): every operation in use, with the engine’s real answers
+* [Operations](https://datanotes.dev/reference/operations/): every tool and its arguments

package/dist/docs/guides/agents/reading-errors.md

@@ -0,0 +1,112 @@
+# Read the engine’s errors
+
+> Every error of the engine says what is wrong, how to fix it and where to read more: the shape of an error, the mistakes agents make most, and the operations that look up the right answer.
+
+Every error the engine returns answers three questions, so an agent can correct its call without guessing:
+
+1. **What is wrong**: the column, value, rule or argument the engine refused
+2. **How to fix it**: the allowed values, the closest real name, the right shape, or the operation that looks up the answer
+3. **Where to read more**: a page of this site in Markdown, with an anchor on the section that shows the fix
+
+This page shows how an error looks, how the engine finds the fix in your data, and the mistakes agents make most often.
+
+## Every error has a message, a hint and a docs link
+
+Through the Model Context Protocol (MCP) server, `datanotes mcp`, a failed call comes back as a tool error. Its text ends with two lines, `Hint:` and `Docs:`. An agent that writes a film with the status `seen` reads:
+
+```text
+insert_row refused — nothing was written:
+invalid datanotes/main/public/film/Nosferatu.md: status must be one of: to watch (on the list, not seen yet); watched (seen at least once)
+Hint: Use one of the allowed values listed in the message, written exactly; describe_table shows what each one means. To add a value, alter_column the enum. Then call insert_row again (dry_run: true checks without writing).
+Docs: read_docs("guides/database-objects/columns#describe-what-each-enum-value-means")
+```
+
+Over HTTP, the same error is JSON, with `hint` and `docs` next to `error`:
+
+```json
+{
+  "error": "Table not found: flim",
+  "hint": "Did you mean \"film\"? Tables: film. list_tables lists them …",
+  "docs": "https://datanotes.dev/guides/database-objects/tables.md#find-the-table-that-matches-a-request"
+}
+```
+
+A refused write, with status 422, keeps its usual body: the operation’s result with `ok: false` and the reasons. The engine adds `hint` and `docs` to it. In code, `DatanotesClient` appends both lines to two texts:
+
+* **`call`**: the `value` of a failed call
+* **`post`**: the message of the `DatanotesError` it throws, which also has `hint` and `docs` as fields
+
+The `docs` link always points to a `.md` page, the Markdown version of a page of this site. Agents read Markdown best. The reference of an operation is the page of its kind, followed by an anchor with the operation’s name, such as `https://datanotes.dev/reference/operations/rows.md#insert_row`.
+
+The `Docs:` line of the text names the page in two ways:
+
+* **`datanotes mcp`**: only the `read_docs` call, which reads the page from the docs of the installed version. Its agents always have the docs tools, so they need no internet access and no web address.
+* **`DatanotesClient` and `datanotes/mcp`**: the address, then the same `read_docs` call in parentheses. Your own MCP server may not serve the docs tools, so its agents keep the address. A server that serves them passes each result to `offlineDocs`, which keeps only the call. See [Build on Datanotes](https://datanotes.dev/develop/build-on-datanotes/).
+
+[Read the docs offline](https://datanotes.dev/guides/agents/docs-offline/) describes the docs tools.
+
+## The engine finds the fix in your data
+
+When the answer is data, the hint reads it from your database:
+
+* **A table or view that doesn’t exist**: the closest names, by spelling, by case and by the table’s `aliases`. `movies` leads to `film`, and a short database lists every table and view.
+* **A column that doesn’t exist**: the closest column and the table’s columns. This works wherever a call names a column: `values`, `where`, `columns`, `order_by`, `join`, `group_by` and `aggregates`.
+* **A value outside an enum**: the allowed values, each with its meaning from `value_descriptions`.
+* **A wrong operator in a filter**: the operator you meant, from a typo (`gtee`) or another language’s word (`>=`, `like`, `not_in`, `is_null`). Then every operator.
+* **A link to a row that doesn’t exist**: `list_link_targets`, which lists the rows the link column accepts.
+* **A row that doesn’t exist**: the row with the closest note name, and how to find a row’s `path` or `id`.
+* **A write to a view**: the view’s own table, since you can only read a view.
+
+## The MCP server checks a call before the engine runs it
+
+`datanotes mcp` checks a call against the tool’s input schema before it sends anything. It catches four mistakes:
+
+* A tool that doesn’t exist
+* An argument the tool doesn’t take
+* A required argument that is missing
+* A value of the wrong type
+
+Each comes back as a tool error that lists the tool’s arguments with their types and links the tool’s reference:
+
+```text
+select_rows: unknown argument "wehre"
+Hint: For "wehre" use "where". select_rows takes: table (string, required), columns (list of strings), where (object), …
+Docs: read_docs("reference/operations/queries#select_rows")
+```
+
+Your own MCP server gets the same checks from `callEngineTool` in `datanotes/mcp`. A program checks arguments with `checkArguments` from `datanotes/client`.
+
+## Fix the mistakes agents make most
+
+| Mistake                                    | What the agent reads                                 | The fix                                                |
+| ------------------------------------------ | ---------------------------------------------------- | ------------------------------------------------------ |
+| A misspelled table, `flim`                 | `Table not found: flim` and `Did you mean "film"?`   | Use the name given, or call `list_tables`              |
+| A misspelled column, `titel`               | `unknown column "titel"` and `Did you mean "title"?` | Use the name given; `describe_table` lists the columns |
+| A value outside an enum, `seen`            | The allowed values and their meanings                | Pick one, or ask the user which one they meant         |
+| A wrong operator, `">="`                   | `For ">=" use "gte"` and every operator              | Write `{"rating": {"gte": 4}}`                         |
+| A value of the wrong type                  | `minutes expected a number`                          | Send numbers unquoted and dates as `YYYY-MM-DD`        |
+| A row the table’s CHECK refuses            | `violates CHECK rated_when_watched` and the rule     | Change the values so the rule holds                    |
+| A row path that doesn’t exist              | `film has no row at …` and the closest row           | Use the path given, or find it with `select_rows`      |
+| An argument the tool doesn’t take, `wehre` | `For "wehre" use "where"` and the tool’s arguments   | Rename the argument                                    |
+| A write to a view                          | The view’s table                                     | Write to the table, and read the view                  |
+| An undo blocked by later changes           | Which notes changed since                            | Undo the later writes first, newest first              |
+
+## Look up the answer before you write
+
+The hints name these operations because each one answers a whole class of mistakes:
+
+* **`list_tables`**: every table and view, with descriptions and aliases
+* **`describe_table`**: a table’s columns, types, limits, enum values with their meanings, and CHECK constraints
+* **`describe_database`**: catalogs, schemas, bases and the database’s settings
+* **`list_link_targets`**: the rows a link column may point to, filtered by its `ref_where` and `ref_by`
+* **`check_table`**: the rows that break the schema, such as notes edited by hand
+* **`list_migrations`** and **`describe_history`**: the writes to undo, and a table’s versions
+
+A refused write changes nothing, so the agent can fix the call and send it again. To check a write without making it, pass `dry_run: true`. To make several writes succeed or fail together, send them in one `batch`.
+
+## Learn more about operations and refusals
+
+* [How agents work with your vault](https://datanotes.dev/guides/agents/how-agents-use-datanotes/): what an agent reads first, and how the journal records its writes
+* [Operations and MCP tools](https://datanotes.dev/reference/operations/): every operation with its arguments
+* [See how the engine refuses bad values](https://datanotes.dev/guides/data-quality/validation/#see-how-the-engine-refuses-bad-values): refusals on a real engine
+* [Read errors over HTTP](https://datanotes.dev/develop/http-api/#read-errors): the status codes of the HTTP API