datanotes 2.0.1 → 3.1.0

package/dist/docs/guides/security/tokens.md

@@ -0,0 +1,60 @@
+# Give each program its own token
+
+> Create named tokens with their own permissions, so the engine limits what each program or agent can do and the journal says who wrote what.
+
+A named token lets a program, a device or an agent call the engine with only the permissions it needs. The owner token can do everything; a named token reads everything and writes only what you allow. The journal records the token’s name with every write it makes, so you can tell who changed what.
+
+To see a token at work in a complete program, follow [Build an app on Datanotes](https://datanotes.dev/develop/build-an-app/). For the ways to build on the engine, read [Build on Datanotes](https://datanotes.dev/develop/build-on-datanotes/). [Who did what](https://datanotes.dev/guides/security/who-did-what/) shows how the journal names each token.
+
+## Create a token
+
+You create a token with the owner token, and the engine answers with the new token. The engine shows it once and keeps only its Secure Hash Algorithm (SHA-256) hash, in `tokens.json` in its store:
+
+```bash
+curl -X POST http://127.0.0.1:27150/datanotes/tokens/create/ \
+  -H "Authorization: Bearer your_owner_token" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "film-diary", "write": ["main.public.*"]}'
+```
+
+This request creates a token named `film-diary` that may write rows of every table in the `main.public` schema, such as `film` and `actor`. The answer holds the token in `token` and the registry’s entry in `entry`. The name is kebab-case, and `owner` is reserved.
+
+## Manage your tokens
+
+The owner manages tokens with these routes under `/datanotes/`:
+
+* **`tokens/`**: lists the tokens, with their permissions and when each one was last used
+* **`tokens/update/`**: changes a token’s description, permissions or `autolink` default
+* **`tokens/rotate/`**: gives a token a new value; the old one stops working at once
+* **`tokens/delete/`**: revokes a token
+
+`datanotes status` lists every token with its permissions, never its value.
+
+## Choose what a token can do
+
+A named token can always read. Every other permission comes from its entry:
+
+* **Row writes**: only on tables that match a pattern in `write`: `catalog.schema.table`, `catalog.schema.*`, `catalog.*` or `*`
+* **Schema changes**: only with `"ddl": true`
+* **Maintenance**: only with `"maintain": true`, meant for an agent’s own token; it covers configuration, undo, restore, vacuum and rebuilding the semantic index
+
+Whatever its permissions, a named token can’t create or delete tokens and webhooks, list tokens, rotate them or read the engine’s status: those stay the owner’s. A token may list webhooks and read its own entry with `tokens/me/`. With `tokens/update/`, it may change its own `description` and `autolink`.
+
+## Turn automatic links off for a sync program
+
+By default, the text a write puts in a note links the notes it mentions. The engine calls this [automatic links](https://datanotes.dev/guides/read-and-write/automatic-links/). A sync program copies text from elsewhere, such as tasks, calendar events or receipts. That text should stay as it came, so give its token `"autolink": false`:
+
+```bash
+curl -X POST http://127.0.0.1:27150/datanotes/tokens/create/ \
+  -H "Authorization: Bearer your_owner_token" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "tasks-sync", "write": ["main.public.task"], "autolink": false}'
+```
+
+A token’s `autolink` is the default of its writes:
+
+* **`insert_row`, `update_row` and `update_rows`** take it, inside a `batch` too.
+* **A write’s own `autolink`** still wins over it.
+* **Without it**, the token’s writes follow the database’s `autolink` setting.
+
+Turn it off for the tokens of sync programs and of modules that write text for you. Keep it unset for an agent’s token. To change it later, call `tokens/update/` with `autolink`. Pass `null` to follow the database setting again. `tokens/` and `tokens/me/` list it with the other fields of the entry.

package/dist/docs/guides/security/who-did-what.md

@@ -0,0 +1,44 @@
+# See who did what
+
+> Every write records who made it: the token, the program or agent, its model and session. Read it in the journal, the history and the change feed.
+
+Every write records its actor: the credential that made it, and, when the caller says so, the program or agent behind it, its model and its session. The journal, the history and the change feed show it, so you can tell who changed what and undo one agent’s work without touching the rest.
+
+## What the actor records
+
+The actor has these fields:
+
+* **`auth`**: the credential, `owner` or the name of a [named token](https://datanotes.dev/guides/security/tokens/); the engine sets it, and no header can claim it
+* **`harness`** and **`harness_version`**: the program or MCP client, such as `claude-code`
+* **`model`**: the model behind an agent
+* **`session`**: the agent’s session
+* **`tool`**: the tool the agent called
+
+A program sends the other fields with the `X-Datanotes-Actor` header, or the client’s `actor` option, as [Record who makes each write](https://datanotes.dev/develop/http-api/#record-who-makes-each-write) shows. `datanotes mcp` fills them from the MCP connection, as [Every write names the agent that made it](https://datanotes.dev/guides/agents/how-agents-use-datanotes/#every-write-names-the-agent-that-made-it) explains.
+
+## See which token made a change
+
+Every write records the credential as `auth` in its actor: `owner`, or the token’s name. When a program forwards an agent’s `X-Datanotes-Actor` header, the engine records both, as “harness / model via token”. A program that writes for itself, without the header, appears under its token’s name.
+
+`list_migrations` shows this name in the `by` field of each change, and `list_changes` shows the whole actor.
+
+## Report what an agent does
+
+A program that serves its own Model Context Protocol (MCP) server can report its agents to the engine, with any token:
+
+* **`POST /datanotes/sessions/identify/`**: names the model and harness behind an agent’s session; later writes that carry the session in `X-Datanotes-Actor` record them
+* **`POST /datanotes/tool-calls/record/`**: records a tool call on the change feed, with `served_by` naming who served it
+
+Tool calls appear on the change feed as events with `kind: "tool_call"`, sent only to consumers that ask for that kind. The `call` field holds `tool`, `ok`, `served_by`, `duration_ms`, `summary` and `session`, the arguments cut at 300 characters, the value cut at 1,000, and the result’s size in `result_chars` and `result_tokens`.
+
+A large result costs less to report when the program cuts it first. The engine answers `takes_summary: true` when it accepts a cut call. Then send the value cut at 1,000 characters, and the result’s `summary` next to it. The event is the same as for the whole call. `datanotes mcp` does this after its first report.
+
+## Read who did what
+
+Three operations read the record:
+
+* **`list_migrations`**: the journal, newest first, each write with `by`, the actor’s name
+* **`describe_history`**: the commits of one table or of every table, with the full actor; it needs history on
+* **`list_changes`**: every change with its actor, and with `kinds: ["tool_call"]` every tool call an MCP server reported
+
+`restore_database` with `before_migration` brings every table back to the moment before an agent’s first write: [Restore a table or the database](https://datanotes.dev/guides/history/restore/) shows it.

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,143 @@
+# Command line
+
+> The datanotes command and its options.
+
+```text
+datanotes 3.1.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
+  datanotes store convert-log --to <files|segments> --database <folder>   rewrite the transaction log in that format
+  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
+  dnotes is a short name for datanotes: every command works under both names.
+
+
+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
+                              DATANOTES_INDEX_CHECK=1: check the engine's indexes against the vault
+                              after every operation, and log any difference as an error (slow: debugging)
+
+
+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, store convert-log: 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
+  --to <files|segments>       store convert-log: segments (a few large files) or files (one per
+                              version, what Datanotes 3.0 reads); sets transactionLogFormat
+  new-id, backup, restore and convert-log run only while no engine runs on the database, and
+  hold its store while they run: an engine started meanwhile refuses to start.
+  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,83 @@
+# Compatibility
+
+> How Datanotes numbers its versions, what counts as its public interface, and how to write clients that keep working.
+
+Datanotes follows [semantic versioning](https://semver.org). The version number tells you what an update can change.
+
+## Versions
+
+* **Major** (4.0.0): can change or remove parts of the public interface. The release notes list those changes first, with what to do.
+* **Minor** (3.1.0): adds to the public interface without breaking what works.
+* **Patch** (3.0.1): fixes bugs and changes nothing you rely on.
+
+The [release notes](https://datanotes.dev/release-notes/) describe every version.
+
+## The public interface
+
+These parts of Datanotes follow the version rules:
+
+* Operations, their arguments and their answer fields
+* HTTP routes and headers
+* Violation codes
+* The commands the package installs (`datanotes` and `dnotes`), their options and their exit codes
+* Environment variables and settings
+* The words of `metastore.yaml`
+
+These cases fall outside them:
+
+* **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.
+
+## Downgrade to 3.0
+
+From 3.1, the engine writes the transaction log in segments by default. Datanotes 3.0 can’t read segments, so convert the log before you downgrade:
+
+1. Stop the engine.
+
+2. Convert every table’s log to one file per version:
+
+   ```bash
+   datanotes store convert-log --to files --vault ~/notes
+   ```
+
+3. Install Datanotes 3.0 and start it.
+
+The command also sets `transactionLogFormat` to `files`, so a 3.1 engine started on the store again keeps writing files. [How the engine writes the log](https://datanotes.dev/start/how-it-works/#how-the-engine-writes-the-log) describes both formats.
+
+## 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 the tests check it
+
+The repository keeps the public interface in `contract/datanotes-3.txt`. It has one line for every operation, argument, answer field, route, installed command, command option, environment variable, setting and violation code.
+
+The test suite fails when a line goes or changes within a major version, so a breaking change cannot ship by accident. A second test checks every new name against the naming rules.

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)             |