datanotes 2.0.1 → 3.0.0

package/dist/docs/index.md

@@ -0,0 +1,113 @@
+# Use your Markdown notes as a database
+
+> Datanotes runs your vault, a folder of Markdown notes, as typed database tables for you and your agents.
+
+Datanotes turns the notes you already keep into typed tables that you, your programs and your agents share. The engine checks every write. Every write through the engine is journaled and can be undone.
+
+- [Get Started](https://datanotes.dev/start/quick-start/)
+- [Connect an Agent](https://datanotes.dev/start/connect-agents/)
+
+## Why use Datanotes
+
+Your notes stay plain Markdown files. The engine adds what a database gives you.
+
+* [Tables from your notes](https://datanotes.dev/guides/database-objects/tables/)
+
+  Each note with a `table` property is a row. One file, `metastore.yaml`, defines the columns.
+
+* [Every write checked](https://datanotes.dev/guides/data-quality/validation/)
+
+  The engine checks types, links, unique values and CHECK rules. It refuses a bad write and changes nothing.
+
+* [All or nothing, with many clients](https://datanotes.dev/develop/concurrency/)
+
+  Agents, programs and your phone write at the same time. Each write is checked on the latest data and applies whole or not at all.
+
+* [Joins, views and bases](https://datanotes.dev/guides/read-and-write/joins-and-aggregates/)
+
+  Filter, join and aggregate rows. Save a query as a view, and share columns through bases.
+
+* [History, time travel and undo](https://datanotes.dev/guides/history/journal-and-undo/)
+
+  The journal records every write through the engine and who made it. Undo a write, or, with history on, read a table as it was last week.
+
+* [Made for agents](https://datanotes.dev/start/connect-agents/)
+
+  Claude, Cursor and Codex call every operation through the Model Context Protocol (MCP). Each refusal says how to fix the call.
+
+* [HTTP API and client](https://datanotes.dev/develop/http-api/)
+
+  Programs call the same operations over HTTP, or from JavaScript with `datanotes/client`.
+
+* [Search by text, meaning and links](https://datanotes.dev/guides/search/text/)
+
+  Search the text of every note, find notes by meaning, and walk the links between them.
+
+* [Git sync and store backup](https://datanotes.dev/administration/git-sync/)
+
+  The engine commits and pushes your vault with git. A private repository backs up undo and history too.
+
+* [Edit notes by hand](https://datanotes.dev/guides/data-quality/hand-edits/)
+
+  Use Obsidian, VS Code or git. The engine checks each edit and reports what it breaks.
+
+## What you can build
+
+The guides build one example you can follow: a diary of classic films in the public domain.
+
+* [A second brain for your agent](https://datanotes.dev/guides/agents/how-agents-use-datanotes/)
+
+  Tell your agent you watched Metropolis with Anna. It logs the viewing and finds it when you ask next month.
+
+* [Databases in your notes](https://datanotes.dev/guides/database-objects/relations/)
+
+  Keep films, actors, genres and viewings as linked tables. Every row stays a note you can open and edit.
+
+* [Apps over your vault](https://datanotes.dev/develop/build-an-app/)
+
+  Build film night, a TypeScript app that lists the films to watch and logs each viewing.
+
+* [Several agents, one memory](https://datanotes.dev/guides/security/tokens/)
+
+  Give each agent and script its own token. The journal shows which one wrote what.
+
+## Run it on your notes
+
+You need Node.js 22 or newer and a folder for your database: an empty one, or a folder of notes.
+
+1. Start the engine on your folder:
+
+   ```bash
+   npx -y datanotes serve --database your_database_folder
+   ```
+
+2. Connect your agent. This command adds Datanotes to Claude Code, and [Connect your agents](https://datanotes.dev/start/connect-agents/) covers Cursor, Codex and others:
+
+   ```bash
+   claude mcp add datanotes -- \
+     npx -y datanotes mcp --database your_database_folder
+   ```
+
+3. Ask in your own words:
+
+   ```text
+   Make a table of the classic films I watch, then add Nosferatu (1922).
+   ```
+
+Then read the page that fits what you want to do next:
+
+* [Run Datanotes on your notes](https://datanotes.dev/start/quick-start/)
+
+  Create a table, add a row and see a refusal.
+
+* [Prompts for your agent](https://datanotes.dev/guides/agents/prompts/)
+
+  Prompts to copy, with the tools they call.
+
+* [Build on Datanotes](https://datanotes.dev/develop/build-on-datanotes/)
+
+  Programs, apps and your own MCP server.
+
+* [How it works](https://datanotes.dev/start/how-it-works/)
+
+  Tables, rows, the journal and the store.

package/dist/docs/llms.txt

@@ -0,0 +1,33 @@
+# Datanotes
+
+> The engine of your second brain: Markdown notes as database tables, for you and your agents.
+
+Datanotes runs a folder of Markdown notes as typed database tables defined in `metastore.yaml`, for people, programs and AI agents. The engine (`npx datanotes serve`) exposes an HTTP API; `datanotes/client` calls it from JavaScript; agents connect through its MCP server, `npx datanotes mcp`. Every write is validated, journaled and undoable.
+
+Every page of the site is also published as Markdown: add `.md` to its path (`https://datanotes.dev/start/quick-start.md` for `https://datanotes.dev/start/quick-start/`; the home page is `https://datanotes.dev/index.md`), or ask for the page itself with `Accept: text/markdown`.
+
+## Documentation Sets
+
+- [Abridged documentation](https://datanotes.dev/llms-small.txt): a compact version of the documentation for Datanotes, with non-essential content removed
+- [Complete documentation](https://datanotes.dev/llms-full.txt): the full documentation for Datanotes
+- [Get started](https://datanotes.dev/_llms-txt/get-started.txt): what Datanotes is, running the engine on your notes, connecting agents, and how the engine works
+- [Database objects](https://datanotes.dev/_llms-txt/database-objects.txt): catalogs and schemas, tables, columns and types, views, bases, relations and hierarchies, with the engine's real answers
+- [Data quality](https://datanotes.dev/_llms-txt/data-quality.txt): validation of every write, CHECK constraints, hand edits, check_table and a vault synced between devices
+- [Read and write data](https://datanotes.dev/_llms-txt/read-and-write-data.txt): filters, joins and aggregates, writing and moving rows, automatic links, batches, importing existing notes
+- [Search](https://datanotes.dev/_llms-txt/search.txt): reading and searching notes, semantic search, the link graph
+- [History and recovery](https://datanotes.dev/_llms-txt/history-and-recovery.txt): the journal and undo, table history and time travel, the change data feed, restores and vacuum
+- [Agents](https://datanotes.dev/_llms-txt/agents.txt): how an agent works with the vault, prompts with the tools they call, reading errors, the docs offline
+- [Security](https://datanotes.dev/_llms-txt/security.txt): named tokens and permissions, who did what, the security model
+- [Develop](https://datanotes.dev/_llms-txt/develop.txt): HTTP API, JavaScript client, concurrent writes, building an app or your own MCP server, the change feed and webhooks, telemetry
+- [Operations reference](https://datanotes.dev/_llms-txt/operations-reference.txt): every operation of the API (also the MCP tools), by kind, with its parameters
+- [Administration](https://datanotes.dev/_llms-txt/administration.txt): running the service, Docker, git sync, datanotes status, configuration
+
+## Notes
+
+- The complete documentation includes all content from the official documentation
+- The content is automatically generated from the same source as the official documentation
+
+## Optional
+
+- [Connect agents](https://datanotes.dev/start/connect-agents.md): how an agent reaches the engine: the MCP server datanotes mcp, its configuration in MCP clients, and named tokens for agents
+- [OpenAPI](https://datanotes.dev/openapi.json): OpenAPI 3.1 description of the /datanotes/* routes

package/dist/docs/reference/cli.md

@@ -0,0 +1,136 @@
+# Command line
+
+> The datanotes command and its options.
+
+```text
+datanotes 3.0.0: Markdown notes as database tables, for you and your agents.
+
+
+Usage:
+  datanotes serve --database <folder> [options]   run the engine and its HTTP API (/datanotes/*)
+  datanotes status --database <folder> [--json]   the running engine's health
+  datanotes stop --database <folder> [--timeout-s <s>] stop the running engine gracefully
+  datanotes store path --database <folder>        where the engine keeps the database's store
+  datanotes store new-id --database <folder>      a new database id (a copied folder gets its own store)
+  datanotes store backup --database <folder>      show or set the store's git backup (--remote <url>, --off)
+  datanotes store restore --from <url> --database <folder>   restore the store from its git backup
+  Every command takes --vault <folder> instead of --database for a vault holding the database.
+  datanotes mcp --database <folder>            MCP server over stdio, on the engine running on the folder
+                                               (or one it starts for the session)
+  datanotes mcp --url <url> --token-file <f>   MCP server over stdio, on an engine at an address
+  datanotes mcp serve [options]                MCP server over Streamable HTTP at /mcp (each agent sends its token)
+  datanotes --version | --help
+
+
+Options of serve:
+  --database <folder>         the database folder (or DATANOTES_DATABASE): metastore.yaml at its
+                              root (created there for a new database); paths start with the catalog
+  --vault <folder>            or a vault holding the database (or DATANOTES_VAULT), for apps such as
+                              Obsidian: the database is the folder of the vault's one metastore.yaml
+                              (a new database: datanotes/); paths start at the vault's root
+  --store <folder>            the engine's store (or DATANOTES_STORE; default <data home>/<database id>)
+  --settings <file>           settings file (or DATANOTES_SETTINGS; default settings.json in the store)
+  --host <address>            listen address (or DATANOTES_HOST; default 127.0.0.1)
+  --port <port>               HTTP port for this run (or DATANOTES_PORT; default: the setting
+                              httpServerPort, 27150); 0 for any free port, printed at start
+  --watch events|poll         how file changes are seen (or DATANOTES_WATCH; default events)
+  --poll-ms <ms>              poll interval (or DATANOTES_POLL_MS; default 3000)
+  --embedding-key-file <file> file with the API key of the embedding provider (or DATANOTES_EMBEDDING_KEY_FILE;
+                              DATANOTES_EMBEDDING_KEY gives the key itself)
+  --git-sync                  commit, pull and push the vault (or DATANOTES_GIT_SYNC=1; --git-no-push)
+  --git-interval-min <min>    minutes between two syncs (or DATANOTES_GIT_INTERVAL_MIN; default 10)
+  --git-quiet-s <s>           a sync also <s> seconds after the last write (or DATANOTES_GIT_QUIET_S; default 60)
+                              DATANOTES_GIT_NETWORK_TIMEOUT_S: the time limit of a pull or push (default 600)
+  --store-backup              back up the store to git for this run (or DATANOTES_STORE_BACKUP=1; the
+                              setting storeBackupEnabled keeps it on; --no-store-backup or =0 turns it off)
+  --store-backup-remote <url> the store backup's git remote; turns the backup on
+                              (or DATANOTES_STORE_BACKUP_REMOTE; default: the setting storeBackupRemote)
+  --store-backup-interval-s <s> every <s> seconds (at least 10), when the store changed: a commit
+                              between two operations, then a push (or DATANOTES_STORE_BACKUP_INTERVAL_S;
+                              default: the setting storeBackupIntervalSeconds, 60)
+  --log <file>                append console output to a file
+
+
+Options of status (the engine is found through the lock in its store, called with the owner's token):
+  --database <folder>         the database folder (or DATANOTES_DATABASE; --vault <folder> for a vault)
+  --store <folder>            the engine's store, when serve was given one (or DATANOTES_STORE)
+  --settings <file>           settings file with the owner's token (or DATANOTES_SETTINGS;
+                              default settings.json in the store)
+  --url <url> --token <token> call this engine instead, e.g. on another machine (or DATANOTES_URL, DATANOTES_TOKEN)
+  --json                      the report as JSON
+  Exit codes: 0 healthy; 1 needs attention (git sync blocked, store backup failing, a webhook failing, change feed not
+  running, hand edits breaking the tables' rules in the last 24 h); 2 no engine running on the folder (or
+  not reachable); 3 an engine runs but its status could not be read (no owner token, token refused, an error).
+
+
+Options of stop (the engine finishes the requests under way, makes its last git sync and store backup
+commit and push, releases its lock and exits):
+  --database <folder>         the database folder (or DATANOTES_DATABASE; --vault <folder> for a vault)
+  --store <folder>            the engine's store, when serve was given one (or DATANOTES_STORE)
+  --settings <file>           settings file with the owner's token (or DATANOTES_SETTINGS;
+                              default settings.json in the store)
+  --url <url> --token <token> stop this engine instead (or DATANOTES_URL, DATANOTES_TOKEN)
+  --timeout-s <seconds>       how long to wait for the engine to exit (default 60)
+  --json                      the report as JSON
+  Exit codes: 0 stopped; 1 not stopped (not answering, or still running after the timeout: stop it by
+  force); 2 no engine running on the folder; 3 the stop could not be asked (another machine, still
+  starting, token refused).
+
+
+Options of store:
+  --database <folder>         the database folder (or DATANOTES_DATABASE; --vault <folder> for a vault)
+  --json                      store path, store backup: the answer as JSON
+  --remote <url>              store backup: turn it on, pushing to this git repository (a first push now)
+  --ssh-command <cmd>         store backup, with --remote: the store repository's core.sshCommand
+                              (default: the vault repository's), e.g. C:/Windows/System32/OpenSSH/ssh.exe
+  --interval-s <seconds>      store backup: every <seconds> (at least 10, default 60), when the
+                              store changed: a commit between two operations, then a push
+  --off                       store backup: turn it off (the store's repository stays)
+  --from <url>                store restore: the git repository of the store backup
+  --port <port>               store restore: the HTTP port in the new settings (default 27150)
+  --force                     store restore: restore over a store that exists (kept aside, renamed)
+  --no-backup                 store restore: leave the store backup off in the new settings
+  backup and restore change the store only while no engine runs on the database.
+  The data home holds one store per database: %LOCALAPPDATA%\Datanotes (Windows),
+  ~/Library/Application Support/Datanotes (macOS), $XDG_DATA_HOME/datanotes or
+  ~/.local/share/datanotes (Linux); DATANOTES_DATA_HOME moves it.
+
+
+Options of mcp (stdio):
+  --database <folder>         the database folder (or DATANOTES_DATABASE); acts with the owner's token,
+                              and stops the engine it started when the client closes
+  --vault <folder>            or a vault holding the database (or DATANOTES_VAULT)
+  --url <url>                 the engine's address (or DATANOTES_URL), with
+  --token-file <file>         a file holding the token (or DATANOTES_TOKEN_FILE, or the token in DATANOTES_TOKEN)
+                              DATANOTES_ENGINE_START_TIMEOUT_S: how long --database waits for the engine
+                              it starts, in seconds (default 60; a large database starts slowly)
+
+
+Options of mcp serve:
+  --url <url>                 the engine (default http://127.0.0.1:27150, or DATANOTES_URL)
+  --host <address>            listen address (default 127.0.0.1, or DATANOTES_MCP_HOST)
+  --port <n>                  port (default 27151, or DATANOTES_MCP_PORT)
+
+
+Tools of mcp (both modes; default: every tool except create_webhook and delete_webhook):
+  --profile <name>            read (read-only tools), write (no schema changes, no webhooks) or
+                              all (every tool, webhooks included) (or DATANOTES_MCP_PROFILE)
+  --tools <names>             only these tools, separated by commas (or DATANOTES_MCP_TOOLS)
+  --except <names>            none of these tools, separated by commas (or DATANOTES_MCP_EXCEPT)
+  --owner-tools               also offer create_webhook and delete_webhook
+                              (or DATANOTES_MCP_OWNER_TOOLS=1)
+
+
+Logs of mcp (both modes):
+  --otlp-endpoint <url>       export logs over OTLP/HTTP, e.g. http://127.0.0.1:4318 (or the standard
+                              OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS, OTEL_SERVICE_NAME)
+
+
+Docs of mcp (both modes): the tools list_docs, read_docs and search_docs read the docs of this
+version from the package (dist/docs), or from the folder in DATANOTES_DOCS_DIR; search_docs also
+ranks them by meaning when the engine has semantic search on (hybrid search)
+
+
+Agents connect through the MCP server: npx -y datanotes mcp (https://datanotes.dev/start/connect-agents/).
+Docs: https://datanotes.dev
+```

package/dist/docs/reference/compatibility.md

@@ -0,0 +1,63 @@
+# Compatibility
+
+> What Datanotes 3 promises: every 3.x version adds to what you use and never takes it away.
+
+Datanotes 3 keeps working with your programs, scripts and vaults in every 3.x version. The number after the 3 only says how recent a release is: 3.1, 3.2, and on.
+
+## The promise
+
+What works in Datanotes 3 keeps working the same way in every 3.x version:
+
+* Operations, their arguments and their answer fields
+* HTTP routes and headers
+* Violation codes
+* Commands, their options and their exit codes
+* Environment variables and settings
+* The words of `metastore.yaml`
+
+A new version can add to these. It never removes or renames them, and a name never changes meaning. When Datanotes needs a different behavior, it adds a new name. The old name keeps doing what it did.
+
+For example, a program that calls `insert_row` with `table` and `values`, then reads `planned_creates`, works with every 3.x version. A later version can add an optional argument, a new answer field or a new operation, and the program doesn’t notice.
+
+These cases fall outside the promise:
+
+* **Security fixes**: a fix can change a behavior. The release notes say so.
+* **Bugs**: Datanotes fixes behavior that contradicts the documentation.
+* **Undocumented behavior**: only what the docs describe is covered.
+* **Messages**: the text of refusals and hints can improve in any version.
+* **Node.js versions**: support follows the Node.js long-term support releases.
+
+## Write tolerant clients
+
+Answers can gain fields, and enums can gain values. Write your client to accept them:
+
+* Ignore fields you don’t know.
+* Handle an enum value you don’t know, for example as “other”.
+* Read refusals by their HTTP status, not by their text.
+
+```ts
+import { DatanotesClient } from "datanotes/client";
+
+
+const db = new DatanotesClient({
+  url: "http://127.0.0.1:27150",
+  token: process.env.DATANOTES_TOKEN ?? "",
+});
+
+
+type Created = { planned_creates: string[] };
+
+
+const r = await db.call("insert_row", {
+  table: "film",
+  values: { title: "Metropolis" },
+});
+// read the fields you need: new ones may appear
+if (r.ok) console.log((r.value as Created).planned_creates);
+```
+
+## How Datanotes keeps it
+
+The repository keeps the whole public contract in `contract/datanotes-3.txt`. It has one line for every operation, argument, answer field, route, command option, environment variable, setting and violation code.
+
+The test suite fails when a line goes or changes, so a machine checks the promise. A second test checks every new name against the naming rules before it ships.

package/dist/docs/reference/errors.md

@@ -0,0 +1,72 @@
+# Errors
+
+> Every kind of error the engine and the MCP server answer, with its status, what its hint gives and the page its docs link names.
+
+Every error of the engine says three things: what is wrong (`error`), how to fix it (`hint`) and where to read more (`docs`, a page of this site in Markdown, with its anchor). The HTTP API sends them as JSON fields; the MCP server and `DatanotesError` end the text with a `Hint:` and a `Docs:` line. The docs line of `DatanotesError` gives the address, then the `read_docs` call that reads the same section offline; `datanotes mcp` gives only the call:
+
+```text
+insert_row refused — nothing was written:
+invalid datanotes/main/public/film/Sunrise.md: status must be one of: to watch; watched
+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.
+Docs: https://datanotes.dev/guides/database-objects/columns.md#describe-what-each-enum-value-means (offline: read_docs("guides/database-objects/columns#describe-what-each-enum-value-means"))
+```
+
+[Read the engine’s errors](https://datanotes.dev/guides/agents/reading-errors/) shows how an agent uses them.
+
+## Kinds of error
+
+| Error                                                                                                                     | Status                                        | The hint gives                                                                                   | Docs                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Unknown tool or operation                                                                                                 | MCP tool error; 400                           | The closest tools                                                                                | [Operations](https://datanotes.dev/reference/operations/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| Argument unknown, missing or of the wrong type                                                                            | MCP tool error, before the call               | The argument meant, and the tool’s arguments with their types                                    | The operation’s reference                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| Bad input to an operation or a route                                                                                      | 400                                           | Its own where the answer is data, else the operation’s arguments                                 | The topic’s page, or the operation’s reference                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| Table or view not found                                                                                                   | 404                                           | The closest names and aliases, the tables and views, or the view’s table where a table is needed | [Find the table that matches a request](https://datanotes.dev/guides/database-objects/tables/#find-the-table-that-matches-a-request), [Store a query as a view](https://datanotes.dev/guides/database-objects/views/#store-a-query-as-a-view)                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| Ambiguous table name                                                                                                      | 409                                           | The full names                                                                                   | [Place tables in catalogs and schemas](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/#place-tables-in-catalogs-and-schemas)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| Unknown column                                                                                                            | 400                                           | The closest column, the table’s columns, `describe_table` and `add_column`                       | [Describe a table before writing to it](https://datanotes.dev/guides/database-objects/tables/#describe-a-table-before-writing-to-it)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| Unknown filter operator                                                                                                   | 400                                           | The operator meant, every operator, and the shape of a condition                                 | [Compare values with operators](https://datanotes.dev/guides/read-and-write/read-and-filter/#compare-values-with-operators)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| Bad expression or aggregate                                                                                               | 400                                           | The columns and the shape                                                                        | [Group rows and compute totals](https://datanotes.dev/guides/read-and-write/joins-and-aggregates/#group-rows-and-compute-totals)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| Unknown base, constraint, catalog, schema, enum value or link column                                                      | 400                                           | The closest name, the list, and the operation that lists them                                    | The topic’s page                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| A name that isn’t an identifier                                                                                           | 400                                           | The name it could be                                                                             | [Place tables in catalogs and schemas](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/#place-tables-in-catalogs-and-schemas)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| A table, base or column without a description, or one removed                                                             | 400                                           | Every missing description, and the call’s shape with each in place                               | [Describe every table and column](https://datanotes.dev/guides/database-objects/tables/#describe-every-table-and-column)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| Row not found                                                                                                             | 400                                           | The closest note name, and how to find a row’s `path` or `id`                                    | [Update one row](https://datanotes.dev/guides/read-and-write/write-rows/#update-one-row)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| A value breaks a rule (a violation)                                                                                       | 422                                           | The hint of its kind: [Violations](#violations)                                                  | The page of its kind                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| A conflict: `expect`, linked rows, rows that break a new CHECK, a column others read, `cascade`, a name taken, merge keys | 422                                           | What the conflict means and what to do                                                           | [Guard a write against concurrent edits with `expect`](https://datanotes.dev/guides/read-and-write/write-rows/#guard-a-write-against-concurrent-edits-with-expect), [Delete a row that other notes link to](https://datanotes.dev/guides/database-objects/relations/#delete-a-row-that-other-notes-link-to), [Enforce rules with CHECK constraints](https://datanotes.dev/guides/data-quality/check-constraints/#enforce-rules-with-check-constraints), [Drop a table and archive its rows](https://datanotes.dev/guides/database-objects/tables/#drop-a-table-and-archive-its-rows), [Insert or update rows with `merge_rows`](https://datanotes.dev/guides/read-and-write/write-rows/#insert-or-update-rows-with-merge_rows) |
+| A write that failed partway, rolled back by the engine                                                                    | 503, with the result as the body              | Free the file, then send the write again                                                         | [The engine rolls back a write it cannot finish](https://datanotes.dev/guides/history/journal-and-undo/#the-engine-rolls-back-a-write-it-cannot-finish)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| A write that failed partway, and its rollback too                                                                         | 500, with the result as the body              | `undo_migration`                                                                                 | [Undo a write](https://datanotes.dev/guides/history/journal-and-undo/#undo-a-write)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| Undo refused, or migration not found                                                                                      | 409, 404                                      | Undone already, the later changes, `list_migrations`                                             | [Undo a write](https://datanotes.dev/guides/history/journal-and-undo/#undo-a-write), [Undo refuses to overwrite later changes](https://datanotes.dev/guides/history/journal-and-undo/#undo-refuses-to-overwrite-later-changes)                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| No history, no such version, a time before the table existed                                                              | 400                                           | `alter_table` with `history: "on"`, `describe_history`, `timestamp`                              | [Turn history on for a table](https://datanotes.dev/guides/history/table-history/#turn-history-on-for-a-table), [List the versions of a table](https://datanotes.dev/guides/history/table-history/#list-the-versions-of-a-table)                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| A batch with an operation refused or unknown                                                                              | 422, 400                                      | Each operation’s own; fix it and send the whole batch again                                      | [Group several writes with `batch`](https://datanotes.dev/guides/read-and-write/batch/#group-several-writes-with-batch)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| A token beyond its permissions                                                                                            | 403                                           | The permissions, and who changes them                                                            | [Choose what a token can do](https://datanotes.dev/guides/security/tokens/#choose-what-a-token-can-do)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| Token missing or wrong                                                                                                    | 401                                           | Which token to send, as a bearer token                                                           | [Authenticate your requests](https://datanotes.dev/develop/http-api/#authenticate-your-requests)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| Unknown operation, route, argument, method or body                                                                        | 404, 400, 405                                 | The closest operation, route or argument, and the routes in `openapi.json`                       | [Call the engines routes](https://datanotes.dev/develop/http-api/#call-the-engines-routes)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| Note or folder not found                                                                                                  | 404                                           | Vault paths, `list_folder` and `search_notes`                                                    | [Read a note](https://datanotes.dev/guides/search/text/#read-a-note)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| Change feed, webhooks or semantic search off                                                                              | 400, 503                                      | How to turn it on                                                                                | [Follow every change with the change feed](https://datanotes.dev/guides/history/change-data-feed/#follow-every-change-with-the-change-feed), [Turn on semantic search](https://datanotes.dev/guides/search/semantic/#turn-on-semantic-search)                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| Engine unreachable                                                                                                        | Thrown by the client; 502 from the MCP server | Start the engine, or check its address                                                           | [How the mcp server reaches the engine](https://datanotes.dev/start/connect-agents/#how-the-mcp-server-reaches-the-engine)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| The engine can’t listen: a port in use or reserved, an address of another machine                                         | Exit code 1 of `datanotes serve`              | Another `--port`, `--port 0`, or an address of this machine                                      | [Choose the port](https://datanotes.dev/administration/run-the-service/#choose-the-port)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| A request while the engine stops                                                                                          | 503                                           | Wait for the stop, then start the engine again                                                   | [Stop the engine](https://datanotes.dev/administration/run-the-service/#stop-the-engine)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| Unexpected error                                                                                                          | 500                                           | None: it isn’t a mistake of the caller                                                           | None                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+
+A refused write writes nothing, so the caller can fix the call and send it again. Hand edits that break a rule aren’t errors: `check_table` and the change feed report them as violations.
+
+## Violations
+
+A write the engine refuses lists its violations, each with a `code`; `check_table` and the change feed report the violations of hand edits with the same codes.
+
+| Code             | Hint                                                                                                                                                                                                                                        | Docs                                                                                                                                 |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `required`       | Give a value to every required column; describe_table marks them (required: true) and lists an enum’s values.                                                                                                                               | [Describe a table before writing to it](https://datanotes.dev/guides/database-objects/tables/#describe-a-table-before-writing-to-it)                      |
+| `type`           | Give each value the column’s type (describe_table shows it): numbers unquoted, dates as YYYY-MM-DD, links as “\[\[Note]]”, lists as JSON arrays.                                                                                            | [Create a table with typed columns](https://datanotes.dev/guides/database-objects/tables/#create-a-table-with-typed-columns)                              |
+| `enum`           | 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.                                                                                      | [Describe what each enum value means](https://datanotes.dev/guides/database-objects/columns/#describe-what-each-enum-value-means)                         |
+| `vocabulary`     | Use one of the values listed in the message, or first insert the new value as a row of the vocabulary table.                                                                                                                                | [Take allowed values from another table](https://datanotes.dev/guides/database-objects/relations/#take-allowed-values-from-another-table)                 |
+| `min`            | Give a value inside the column’s range (the message names the bound); describe_table shows its min and max.                                                                                                                                 | [Describe a table before writing to it](https://datanotes.dev/guides/database-objects/tables/#describe-a-table-before-writing-to-it)                      |
+| `max`            | Give a value inside the column’s range (the message names the bound); describe_table shows its min and max.                                                                                                                                 | [Describe a table before writing to it](https://datanotes.dev/guides/database-objects/tables/#describe-a-table-before-writing-to-it)                      |
+| `step`           | Give a multiple of the column’s step (describe_table shows it).                                                                                                                                                                             | [Describe a table before writing to it](https://datanotes.dev/guides/database-objects/tables/#describe-a-table-before-writing-to-it)                      |
+| `broken_link`    | Link to a note that exists, as “\[\[Note name]]”: list_link_targets(table, column) lists the rows the column may point to.                                                                                                                  | [Point a column to a row of another table](https://datanotes.dev/guides/database-objects/relations/#point-a-column-to-a-row-of-another-table)             |
+| `ref`            | Link to a row of the table the column points to (its ref) that its ref_where / ref_by allow: list_link_targets(table, column) lists them.                                                                                                   | [Limit link targets with `ref_by` and `ref_where`](https://datanotes.dev/guides/database-objects/relations/#limit-link-targets-with-ref_by-and-ref_where) |
+| `unique`         | Another row already has this value: choose another one, or update that row instead (select_rows finds it).                                                                                                                                  | [Update one row](https://datanotes.dev/guides/read-and-write/write-rows/#update-one-row)                                                                  |
+| `unknown_column` | Write only the table’s columns: describe_table lists them. To keep a new front matter key, add_column first.                                                                                                                                | [Describe a table before writing to it](https://datanotes.dev/guides/database-objects/tables/#describe-a-table-before-writing-to-it)                      |
+| `check`          | The row breaks a CHECK constraint of the table (named in the message, with its rule): change the values so the rule holds. describe_table lists the table’s constraints.                                                                    | [Enforce rules with CHECK constraints](https://datanotes.dev/guides/data-quality/check-constraints/#enforce-rules-with-check-constraints)                 |
+| `generated`      | A generated column is computed by the engine: do not write it; recompute_columns sets it again.                                                                                                                                             | [Recompute generated columns after a hand edit](https://datanotes.dev/guides/data-quality/hand-edits/#recompute-generated-columns-after-a-hand-edit)      |
+| `cycle`          | A row cannot be its own ancestor: point the hierarchy column to a row that is not below this one.                                                                                                                                           | [Build a tree of rows with a parent link](https://datanotes.dev/guides/database-objects/relations/#build-a-tree-of-rows-with-a-parent-link)               |
+| `inverse`        | Both sides of a two-way link must agree: write one side, or run align_relations to repair them.                                                                                                                                             | [Repair two-way links with `align_relations`](https://datanotes.dev/guides/database-objects/relations/#repair-two-way-links-with-align_relations)         |
+| `unreadable`     | The note’s front matter is not valid YAML (the message quotes the parser), so every read leaves the row out: open the note and fix the YAML, such as a quote or bracket left open or a line without `key: value`. read_note shows its text. | [Find rows whose front matter can’t be read](https://datanotes.dev/guides/data-quality/hand-edits/#find-rows-whose-front-matter-cant-be-read)             |