datanotes 2.0.0 → 3.0.0

package/dist/docs/reference/glossary.md

@@ -0,0 +1,161 @@
+# Glossary
+
+> The words of Datanotes, from row and table to journal, transaction log, token and change feed, each with the page that explains it.
+
+The words these docs use, in alphabetical order. Each one links to the page that explains it.
+
+## Actor
+
+Who made a write: the credential as `auth` (`owner` or a token’s name), and, when the caller sends them, the harness, model, session and tool. The journal, the history and the change feed record it. See [Who did what](https://datanotes.dev/guides/security/who-did-what/).
+
+## Agent
+
+A program driven by a language model, such as Claude, Cursor or Codex, that calls the engine’s operations as tools through the MCP server. See [How agents work with your vault](https://datanotes.dev/guides/agents/how-agents-use-datanotes/).
+
+## App
+
+A program that calls the HTTP API with its own named token, such as a script, a service or an MCP server of your own. Each app has its own [named token](https://datanotes.dev/guides/security/tokens/). See [Build on Datanotes](https://datanotes.dev/develop/build-on-datanotes/).
+
+## Automatic link
+
+A link the engine adds where the text of a write mentions another note by name. A doubtful mention stays as text, and the write returns it in `ambiguous_mentions` with the notes it may name. The `autolink` setting turns it off. See [Automatic links](https://datanotes.dev/guides/read-and-write/automatic-links/).
+
+## Base
+
+A named set of columns that tables inherit, like a parent class. One query reads every table that extends a base. See [Bases](https://datanotes.dev/guides/database-objects/bases/).
+
+## Backlinks
+
+The notes that link to a given note. `file_backlink_count` counts them, and the graph operations follow them with the direction `in`. See [Read and filter rows](https://datanotes.dev/guides/read-and-write/read-and-filter/).
+
+## Batch
+
+A list of writes that succeed or fail together, as one journal entry that one undo reverts. See [Batch writes](https://datanotes.dev/guides/read-and-write/batch/).
+
+## Catalog
+
+The top level of the database’s hierarchy: a catalog holds schemas, and a schema holds tables. A table’s full name is `catalog.schema.table`. See [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/).
+
+## Change feed
+
+The numbered list of every change in the vault, writes and hand edits alike, that programs poll, stream or receive by webhook. Also called the change data feed. See [Change data feed](https://datanotes.dev/guides/history/change-data-feed/).
+
+## CHECK constraint
+
+A rule, written as a filter, that every row of a table must pass. It can follow links into other tables. See [CHECK constraints](https://datanotes.dev/guides/data-quality/check-constraints/).
+
+## Column
+
+A typed front matter key of a table’s rows. Its type can be a string, a number, a date, an enum or a link, and it has attributes such as `required`, `unique` and `default`. See [Columns and types](https://datanotes.dev/guides/database-objects/columns/).
+
+## Data home
+
+The folder that holds the engine’s stores, one per database: `%LOCALAPPDATA%\Datanotes` on Windows, `~/Library/Application Support/Datanotes` on macOS and `~/.local/share/datanotes` on Linux. `DATANOTES_DATA_HOME` moves it. See [Run the engine as a service](https://datanotes.dev/administration/run-the-service/#where-the-engine-keeps-its-store).
+
+## Database folder
+
+The folder that holds `metastore.yaml`. With `--database`, it’s the folder you pass, and `metastore.yaml` sits at its root. With `--vault`, it’s a folder inside the vault, `datanotes/` by default: the engine finds it at each start, and `configure_database` with `root` moves it. See [One database per vault](https://datanotes.dev/administration/run-the-service/#one-database-per-vault).
+
+## Database id
+
+A UUID at the top of `metastore.yaml`, as `id`, that names the database. The engine writes it when it creates the database, and finds the database’s store by it. A copy of a vault gets its own with `datanotes store new-id`. See [Run a copy of a vault](https://datanotes.dev/administration/run-the-service/#run-a-copy-of-a-vault).
+
+## Engine
+
+The process that runs a vault as a database, `datanotes serve`. It checks and journals every write and serves the HTTP API. See [Run the engine as a service](https://datanotes.dev/administration/run-the-service/).
+
+## Front matter
+
+The YAML block at the top of a note, between two `---` lines. Each key of a row’s front matter holds the value of one column. See [How it works](https://datanotes.dev/start/how-it-works/).
+
+## Hand edit
+
+A change to a note made outside the engine: in an editor, with git or through a sync tool. The engine checks it against the tables’ rules but never refuses it. See [Hand edits](https://datanotes.dev/guides/data-quality/hand-edits/).
+
+## History
+
+A table’s transaction log, when it’s turned on: every version of the table, for time travel and restores. See [Table history and time travel](https://datanotes.dev/guides/history/table-history/).
+
+## Hybrid search
+
+A search that ranks by words and by meaning, then merges the two rankings with Reciprocal Rank Fusion. `search_docs` works this way when the engine has semantic search on. See [Search by words and by meaning](https://datanotes.dev/guides/agents/docs-offline/#search-by-words-and-by-meaning).
+
+## Journal
+
+The record of every write to rows and to the schema, with the data to undo it and its actor, in `journal/` in the engine’s store. See [Journal and undo](https://datanotes.dev/guides/history/journal-and-undo/).
+
+## MCP
+
+The Model Context Protocol, the way agents call tools. `datanotes mcp`, the MCP server of Datanotes, offers the operations of the engine as tools, the webhook tools only on request. See [Connect your agents](https://datanotes.dev/start/connect-agents/).
+
+## Metastore
+
+The file that defines every catalog, schema, table, column, base and view: `metastore.yaml`, at the root of the database folder. It changes only through operations. See [How it works](https://datanotes.dev/start/how-it-works/#the-metastore-defines-every-table).
+
+## Migration
+
+One journal entry: a write, with its `migration_id`. `list_migrations` lists them, and `undo_migration` reverts one. See [Journal and undo](https://datanotes.dev/guides/history/journal-and-undo/).
+
+## Module
+
+A JavaScript entry point of the `datanotes` package: `datanotes/client` calls the HTTP API, `datanotes/local` finds the local engine, and `datanotes/mcp` gives the engine’s tools to an MCP server of your own. See [Call the engine from JavaScript](https://datanotes.dev/develop/client/).
+
+## Note
+
+A Markdown file in the vault. A note with a front matter key `table` that names a table is a row; any other note is an ordinary note. See [How it works](https://datanotes.dev/start/how-it-works/).
+
+## Operation
+
+A call the engine runs, such as `create_table`, `insert_row` or `select_rows`. Each one is an HTTP route and an MCP tool of the same name. See [Operations](https://datanotes.dev/reference/operations/).
+
+## Owner token
+
+The token that can do everything, generated at the engine’s first start and kept in its settings file. See [Tokens and permissions](https://datanotes.dev/guides/security/tokens/).
+
+## Row
+
+A note whose front matter key `table` names a table, wherever it lives in the vault. Its front matter keys are the row’s columns. Each row has an `id` that never changes. See [Tables](https://datanotes.dev/guides/database-objects/tables/).
+
+## Schema
+
+The level between catalogs and tables: a schema holds tables and views. See [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/).
+
+## Store
+
+The engine’s folder for one database, outside the vault: `<data home>/<database id>/`. It holds the settings, the tokens, the journal, the transaction logs, the change feed and the logs. Results name its files with a `store:` prefix. See [Run the engine as a service](https://datanotes.dev/administration/run-the-service/#where-the-engine-keeps-its-store).
+
+## Store backup
+
+The [store](#store) kept as a git repository of its own and pushed to a private remote, such as a GitHub repository. It keeps the journal, the transaction logs, the change feed and the named tokens’ hashes, never the settings or a secret. Every 60 seconds by default, when the store changed, it commits between two operations, then pushes. `datanotes store restore` brings it back on a new machine. See [Back up the history](https://datanotes.dev/guides/history/back-up/).
+
+## Table
+
+A set of rows with the same columns, defined in the metastore. See [Tables](https://datanotes.dev/guides/database-objects/tables/).
+
+## Token
+
+A credential for the HTTP API, sent as `Authorization: Bearer`. The owner token can do everything; a named token has only the permissions you give it. See [Tokens and permissions](https://datanotes.dev/guides/security/tokens/).
+
+## Transaction log
+
+The numbered versions of a table with history on, in `transaction_log/` in the engine’s store. See [How it works](https://datanotes.dev/start/how-it-works/#the-transaction-log-keeps-every-version).
+
+## Vault
+
+The folder of notes the engine serves. Note editors such as Obsidian, Foam or Zettlr work on a folder like this one too. A vault is optional: with `--database`, the database folder is the folder the engine serves. With `--vault`, the engine serves a whole vault, and the database is a folder inside it. Either way, rows and ordinary notes link to each other, and the engine serves every note. Paths are relative to the folder the engine serves, and the engine never writes outside it. Not every note is a row. See [How it works](https://datanotes.dev/start/how-it-works/#the-engine-runs-on-a-database-folder-or-on-a-vault).
+
+## Version
+
+One numbered state of a table in its transaction log. `select_rows` reads a table at a version or a time. See [Table history and time travel](https://datanotes.dev/guides/history/table-history/).
+
+## View
+
+A query stored under a name in the metastore, read like a table. See [Views](https://datanotes.dev/guides/database-objects/views/).
+
+## Webhook
+
+A web address the engine posts the change feed to. See [Follow the change feed and webhooks](https://datanotes.dev/develop/change-feed-and-webhooks/).
+
+## Wikilink
+
+A link between notes written `[[Note]]`, or `[[Note|alias]]` with an alias as the text it shows. A link column holds wikilinks to rows of its `ref` table. See [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/).

package/dist/docs/reference/operations/auxiliary.md

@@ -0,0 +1,116 @@
+# Auxiliary operations
+
+> Operations that describe and check the database, configure it and maintain its indexes.
+
+Operations that describe and check the database, configure it and maintain its indexes. The [overview](https://datanotes.dev/reference/operations/) lists every operation by kind. The MCP server, `datanotes mcp`, offers each operation as an MCP tool of the same name, and `engineTools()` of `datanotes/mcp` gives the same definitions to [your own MCP server](https://datanotes.dev/develop/build-on-datanotes/#build-your-own-mcp-server). `DatanotesClient.call(name, args)` runs one from code. Over HTTP each one is `POST /datanotes/operations/<name>/`, with its arguments as the JSON body: the [HTTP API reference](https://datanotes.dev/api/) lists them.
+
+Every write is validated. Writes to rows and to the schema are journaled and undone with `undo_migration`; `configure_database`, the webhook operations, `vacuum_table` and `sync_semantic_index` are not journaled.
+
+## `list_tables`
+
+**List Tables** · read-only
+
+List every table: `name`, `catalog`, `schema`, `qualified` (`personal.metrics.mood` — use it wherever a table is expected; `metrics.mood` or `mood` also work when unambiguous), `path` and, when declared, `description`, `aliases` (other words for what it records) and `tags`. Tables are defined in `metastore.yaml` (catalog → schema → table): read it freely, but it is read-only for agents and changes only through the schema operations (create_table, add_column, …). Returns `{tables, views}`: `views` lists the stored views (same fields, no path): select them like tables. `system.information_schema` is read with `select_rows`.
+
+Call this first to find the table for what the user reports (match their words against name, description and aliases), and before creating tables or columns so you reuse existing ones instead of creating duplicates.
+
+Examples: [Tables](https://datanotes.dev/guides/database-objects/tables/), [Views](https://datanotes.dev/guides/database-objects/views/).
+
+## `describe_table`
+
+**Describe Table** · read-only
+
+Describe a table (`catalog.schema.table` or a shorter unambiguous name): `qualified`, `name`, `catalog`, `schema`, `description`, `aliases`, `layout` (`folder`, `row_folder`: the folder pattern of new rows, `archive`), `options` (`partition`, `filename`, `archive`, `exclude`), typed `columns` with label/aliases/description and the dense flag, `untyped_fields`, `row_count`, and when set: `tags`, `bases` (the bases it inherits from, in order), `constraints` (its CHECKs, name → where), `row_template`, `history`, `autolink_target`, `fields` (their values).
+
+Before adding a column (e.g. a new metric), read `columns` and match your concept against `name`, `label`, `aliases` and `description`; reuse an existing column when it means the same.
+
+`missing_descriptions` (`{table, columns}`), present only when something has no description (a table defined before descriptions were required), names what lacks one: write them with alter_table `description` and alter_column `changes.description`, asking the user when the meaning is unclear.
+
+Examples: [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Tables](https://datanotes.dev/guides/database-objects/tables/), [Bases](https://datanotes.dev/guides/database-objects/bases/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/).
+
+| Parameter | Type   | Required | Default | Description |
+| --------- | ------ | -------- | ------- | ----------- |
+| `table`   | string | yes      |         |             |
+
+## `describe_database`
+
+**Describe Database** · read-only
+
+Describe the database: its folder (`root`), `metastore` (`metastore.yaml`: read it freely, but it is read-only for agents and changes only through the schema operations), configuration (default catalog and schema, row partition and file-name formats, archive folder, time zone, history, automatic links), journal folder, `bases` (shared column sets and the tables using them), `catalogs` → `schemas` → `tables` (with `row_count`, `tags`, and `unreadable_count` when some rows’ front matter cannot be read) and `views`; catalogs and schemas show their `comment` (set with `comment_on`). A table or base defined before descriptions were required has `missing_descriptions`: what lacks one, for alter_table / alter_column (define_base for a base) to fill, so every table and column says what it holds.
+
+Examples: [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Hand edits](https://datanotes.dev/guides/data-quality/hand-edits/).
+
+## `configure_database`
+
+**Configure Database** · destructive write
+
+Configure the database (persisted in metastore.yaml `config:`): `root` (rename the database folder; links follow; revert by renaming back), `default_catalog`, `default_schema`, `default_partition` (“” = flat) and `default_filename` (date formats for new time-based tables), `archive_folder`, `timezone` (IANA; completes date-times written without offset), `history` (transaction log for every table: true in a database the engine creates, false when `config` lacks it, as in a metastore from before 3.0.0; change it only on the user’s request), `autolink` (the text a write puts in a body links the notes it mentions; on by default). Returns describe_database. Renaming `root` moves the folder (links to its notes are rewritten; the tables’ archive and `exclude` folders inside it follow); the move is listed in the journal as `move_database` (undo and time travel read older entries with the new paths) and cannot be undone. Settings changes are not journaled (no `migration_id`, nothing for undo_migration): to revert, call it again with the previous values.
+
+The metastore changes only through operations: never edit metastore.yaml by hand (no validation).
+
+Examples: [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Tables](https://datanotes.dev/guides/database-objects/tables/), [Automatic links](https://datanotes.dev/guides/read-and-write/automatic-links/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/).
+
+| Parameter           | Type       | Required | Default | Description |
+| ------------------- | ---------- | -------- | ------- | ----------- |
+| `root`              | string \\  | null     |         | `null`      |
+| `default_catalog`   | string \\  | null     |         | `null`      |
+| `default_schema`    | string \\  | null     |         | `null`      |
+| `default_partition` | string \\  | null     |         | `null`      |
+| `default_filename`  | string \\  | null     |         | `null`      |
+| `archive_folder`    | string \\  | null     |         | `null`      |
+| `timezone`          | string \\  | null     |         | `null`      |
+| `history`           | boolean \\ | null     |         | `null`      |
+| `autolink`          | boolean \\ | null     |         | `null`      |
+
+## `check_table`
+
+**Check Table** · read-only
+
+Validate every row against the table (required, types, ranges, enums, links, unknown columns, CHECK constraints, those that follow links included, filtered link targets (ref_where / ref_by), stale generated/identity values, missing inverse links, front matter that cannot be read: code `unreadable`, with no column, for a note whose `table` line names the table but whose YAML is broken, which every other read leaves out). A CHECK violation has code `check` and the CHECK’s name as `constraint` (every other code names its `column`), as in the `violations` of list_changes. Use it to find rows edited by hand that break the schema. Without `table`, every table is checked: each row then names its `table`, `tables_checked` counts the tables checked, and a table that cannot be checked is listed in `errors` ({table, error}) while the others are. The rows with violations are paged: `limit` (default 500, at most 5000) from `offset`; `total` counts them all. (Hand edits are also checked as they happen: see `violations` in list_changes.)
+
+Examples: [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [Hand edits](https://datanotes.dev/guides/data-quality/hand-edits/), [Find rows that break the schema](https://datanotes.dev/guides/data-quality/check-table/).
+
+| Parameter | Type      | Required | Default | Description                                  |
+| --------- | --------- | -------- | ------- | -------------------------------------------- |
+| `table`   | string \\ | null     |         | `null`                                       |
+| `limit`   | integer   |          | `500`   | Rows with violations returned (paging).      |
+| `offset`  | integer   |          | `0`     | Rows with violations skipped first (paging). |
+
+## `infer_table`
+
+**Infer Table** · read-only
+
+Read-only schema inference from notes’ front matter.
+
+* `folder` (recursive; “” = whole vault) and/or `paths`: notes not yet in a table. Returns `columns` (type, enum `values`, link `ref` to the table most targets belong to, `required`, `unique`, `dense`, `from` when the front matter key is not a valid column name, `stats`), `proposal`, the create_table arguments (`name`, `description`, `filename` or `time_column`, `columns`), and `adopt` ready for adopt_rows (`paths`, `rename`, `relocate: false`), plus `hints` to read. The notes cannot say what the table and its columns mean: `description` is null on the proposal and on every column. Write each one (ask the user when unsure), and review the names, enums and required columns, before you pass the proposal to create_table, which refuses null descriptions.
+* `table`: keys the table’s rows use but the table does not declare (candidates for add_column, each with a description to write, or keys to drop from rows). A string column becomes an enum when its values repeat: at least 3 notes, at most `max_enum_values` distinct values (default 12), each used twice on average, short texts.
+
+Examples: [Hand edits](https://datanotes.dev/guides/data-quality/hand-edits/), [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/).
+
+| Parameter         | Type         | Required | Default | Description |
+| ----------------- | ------------ | -------- | ------- | ----------- |
+| `folder`          | string \\    | null     |         | `null`      |
+| `paths`           | string\[] \\ | null     |         | `null`      |
+| `table`           | string \\    | null     |         | `null`      |
+| `name`            | string \\    | null     |         | `null`      |
+| `max_enum_values` | integer \\   | null     |         | `null`      |
+
+## `describe_semantic_index`
+
+**Describe Semantic Index** · read-only
+
+The semantic search index: `enabled`, `provider`, `model`, `files`, `passages`, `pending`, `running`, `last_sync`, `last_error`. sync_semantic_index brings it up to date.
+
+Examples: [Find notes by meaning](https://datanotes.dev/guides/search/semantic/).
+
+## `sync_semantic_index`
+
+**Sync Semantic Index** · destructive write
+
+Bring the semantic search index up to date: embed the notes changed since the last run (the engine also does it on its own about ten seconds after edits). `rebuild: true` re-embeds everything: slow, and costs money with a paid provider — ask first.
+
+Examples: [Find notes by meaning](https://datanotes.dev/guides/search/semantic/).
+
+| Parameter | Type    | Required | Default | Description                                     |
+| --------- | ------- | -------- | ------- | ----------------------------------------------- |
+| `rebuild` | boolean |          | `false` | Re-embed every note, not only the changed ones. |

package/dist/docs/reference/operations/history.md

@@ -0,0 +1,168 @@
+# History operations
+
+> Operations on the journal, a table's versions, the change feed and webhooks: undo, time travel, restore and vacuum.
+
+Operations on the journal, a table’s versions, the change feed and webhooks: undo, time travel, restore and vacuum. The [overview](https://datanotes.dev/reference/operations/) lists every operation by kind. The MCP server, `datanotes mcp`, offers each operation as an MCP tool of the same name, and `engineTools()` of `datanotes/mcp` gives the same definitions to [your own MCP server](https://datanotes.dev/develop/build-on-datanotes/#build-your-own-mcp-server). `DatanotesClient.call(name, args)` runs one from code. Over HTTP each one is `POST /datanotes/operations/<name>/`, with its arguments as the JSON body: the [HTTP API reference](https://datanotes.dev/api/) lists them.
+
+Every write is validated. Writes to rows and to the schema are journaled and undone with `undo_migration`; `configure_database`, the webhook operations, `vacuum_table` and `sync_semantic_index` are not journaled.
+
+## `list_migrations`
+
+**List Migrations** · read-only
+
+The operation journal, newest first: `total` (the matching operations) and `migrations`, each with `migration_id` (for undo_migration), `op`, `summary`, `table` (when it was about one), `executed_at`, `notes_changed`, `files_changed`, `undone`, `undoes`, `files_failed`, `by` (the agent), and `members` (a batch’s operations) or `batch` (the batch of an operation). Filters: `op` (e.g. “update_rows”), `table` (substring of the table name, e.g. “personal.tasks.task”), `since` (ISO date). `limit` default 50. The journal is kept in the engine’s store, outside the vault (`store:journal/`); entries older than 90 days are dropped.
+
+Examples: [Hand edits](https://datanotes.dev/guides/data-quality/hand-edits/), [Journal and undo](https://datanotes.dev/guides/history/journal-and-undo/).
+
+| Parameter | Type       | Required | Default | Description |
+| --------- | ---------- | -------- | ------- | ----------- |
+| `limit`   | integer \\ | null     |         | `null`      |
+| `op`      | string \\  | null     |         | `null`      |
+| `table`   | string \\  | null     |         | `null`      |
+| `since`   | string \\  | null     |         | `null`      |
+
+## `undo_migration`
+
+**Undo Migration** · destructive write
+
+Revert a journaled table operation by its `migration_id`. Refused (nothing written) when any touched note changed since; the conflicts are listed. Also refused when the revert would leave rows breaking a CHECK that follows links or a `ref_where` / `ref_by` (rows it writes, or rows that link to them), listed like the refusals of other writes with the way out (fix the row, or drop the rule). The rules are those of the schema the revert puts back: undoing a rename_value / rename_column puts the old names back with the rows, and a rule the revert puts back must hold on every row. A `batch` is checked as a whole first (nothing written when refused), then reverted operation by operation, from the last; when one finds a note changed since, those after it stay reverted and a retry skips them. An undo is journaled like any operation: undoing it (the `migration_id` of its answer; `undoes` names the operation undone) is a redo, whatever the operation (a batch included). The revert is a new version (`UNDO`) in the transaction log; undoing a table’s rename or move takes its whole log back to the old name, the versions made under the new one included.
+
+The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).
+
+Examples: [Columns and types](https://datanotes.dev/guides/database-objects/columns/), [Views](https://datanotes.dev/guides/database-objects/views/), [Journal and undo](https://datanotes.dev/guides/history/journal-and-undo/), [Restore a table or the database](https://datanotes.dev/guides/history/restore/).
+
+| Parameter      | Type   | Required | Default | Description |
+| -------------- | ------ | -------- | ------- | ----------- |
+| `migration_id` | string | yes      |         |             |
+
+## `describe_history`
+
+**Describe History** · read-only
+
+DESCRIBE HISTORY: the table’s versions, newest first — `version`, `timestamp`, `operation` (CREATE TABLE, WRITE, UPDATE, DELETE, MERGE, ALTER TABLE, ADD COLUMNS, RESTORE, UNDO, …; `EXTERNAL_EDIT` = changed outside the engine: an editor, git, sync), `operation_metrics` and `migration_id` (undo). An EXTERNAL_EDIT’s `operation_metrics.violations` counts the rules this table’s rows break because of the hand edits it holds (each once): the edited rows whose front matter changed and the rows of the table linking to them, a removed or renamed row included (rows of other tables count in their table; a body-only edit is not checked); every rule its rows break when its definition was edited in metastore.yaml. Absent when nothing was checked, or when the edits were logged right before an engine write (the change feed has them); check_table lists the rows invalid now. Works for dropped tables too (full `catalog.schema.table`). Use a version with `select_rows` (time travel), `table_changes` or `restore_table`. Without `table`: the history of the whole database — the commits of every table with a log (dropped ones included), newest first, each with its `table` (the result’s `tables` lists the logged tables). An operation that changed several tables (a cascade, inverse links, restore_database) commits to each with the same `migration_id`, and the operations of a `batch` carry its id as `batch`: their commits list in `tables` every table that operation (or batch) committed to. Pick a moment for `restore_database` from it (`timestamp`, or `before_migration` with a `migration_id` or a `batch`). `limit` (default 50) counts commits; `since` (ISO date or date-time): only commits at or after it.
+
+Examples: [Table history and time travel](https://datanotes.dev/guides/history/table-history/), [Restore a table or the database](https://datanotes.dev/guides/history/restore/).
+
+| Parameter | Type       | Required | Default | Description |
+| --------- | ---------- | -------- | ------- | ----------- |
+| `table`   | string \\  | null     |         | `null`      |
+| `limit`   | integer \\ | null     |         | `null`      |
+| `since`   | string \\  | null     |         | `null`      |
+
+## `table_changes`
+
+**Table Changes** · read-only
+
+Change data feed between two versions (both included, end defaults to latest): one entry per row change with its values plus `_change_type` (insert, delete, update_preimage, update_postimage, metadata), `_commit_version`, `_commit_timestamp`, `_operation`, `path`. Use it to answer “what changed since …” without diffing full tables.
+
+Examples: [Table history and time travel](https://datanotes.dev/guides/history/table-history/).
+
+| Parameter       | Type       | Required | Default | Description |
+| --------------- | ---------- | -------- | ------- | ----------- |
+| `table`         | string     | yes      |         |             |
+| `start_version` | integer    | yes      |         |             |
+| `end_version`   | integer \\ | null     |         | `null`      |
+
+## `restore_table`
+
+**Restore Table** · destructive write
+
+RESTORE TABLE to a `version` or `timestamp`: rows and definition return to that state — rows added since are deleted, changed rows get their old content, removed rows come back (a dropped table is re-created). History is not rewritten: the restore is a new version, and `undo_migration` reverts it. Refused (rows listed, with the way out) when the rows it writes, or rows that link to them, would break a CHECK that follows links or a `ref_where` / `ref_by` (as the restored definition has them: a rule added since does not hold the old rows). Run with `dry_run` first and show the user what changes.
+
+The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).
+
+Examples: [Restore a table or the database](https://datanotes.dev/guides/history/restore/).
+
+| Parameter   | Type       | Required | Default | Description |
+| ----------- | ---------- | -------- | ------- | ----------- |
+| `table`     | string     | yes      |         |             |
+| `version`   | integer \\ | null     |         | `null`      |
+| `timestamp` | string \\  | null     |         | `null`      |
+| `dry_run`   | boolean    |          | `false` |             |
+
+## `restore_database`
+
+**Restore Database** · destructive write
+
+RESTORE DATABASE to a `timestamp` (each table as of its last version committed at or before it) or to `before_migration` (a `migration_id` or a `batch`: every table as it was just before that operation ran — to rewind an agent’s run). Every table that keeps a transaction log goes back, rows and definition: rows added since are deleted, changed rows get their old content, removed rows come back; a table created since is dropped with its rows moved to its archive folder (as drop_table with mode “archive”: nothing is hard-deleted), a table dropped since comes back. Tables already as they were are left alone (`unchanged`, no new version). One operation: each restored table gets a RESTORE version, all with one `migration_id`, and `undo_migration` on it reverts them all. Refused as a whole, nothing written (rows listed, with the way out), when a row it leaves would break a CHECK that follows links or a `ref_where` / `ref_by`, across tables, as the restored definitions have them. Tables without a log (history off, or vacuumed before that time) cannot be rewound: they stay as they are, listed in `skipped` with the reason (tell the user). Views, bases and the database settings are not rewound (the logs keep tables), nor a rename or move of a table (undo_migration on it does that). Returns `restored_to`, `tables` (per table: `action` restore / drop / recreate, `version`, `creates`, `texts`, `deletes`, `archived`), `unchanged` and `skipped`. Run with `dry_run` first and show the user what changes; describe_history without `table` shows the moments.
+
+The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).
+
+Examples: [Restore a table or the database](https://datanotes.dev/guides/history/restore/).
+
+| Parameter          | Type      | Required | Default | Description |
+| ------------------ | --------- | -------- | ------- | ----------- |
+| `timestamp`        | string \\ | null     |         | `null`      |
+| `before_migration` | string \\ | null     |         | `null`      |
+| `dry_run`          | boolean   |          | `false` |             |
+
+## `vacuum_table`
+
+**Vacuum Table** · destructive write
+
+Delete transaction-log history older than `retain_from_version` (default: keep only the latest version); time travel before it becomes impossible. Rows are not touched. `dry_run` defaults to true: it lists the log files that would go. Only on the user’s explicit request.
+
+Examples: [Vacuum old history](https://datanotes.dev/guides/history/vacuum/).
+
+| Parameter             | Type       | Required | Default | Description |
+| --------------------- | ---------- | -------- | ------- | ----------- |
+| `table`               | string     | yes      |         |             |
+| `retain_from_version` | integer \\ | null     |         | `null`      |
+| `dry_run`             | boolean    |          | `true`  |             |
+
+## `list_changes`
+
+**List Changes** · read-only
+
+Change feed across all tables: numbered row changes (`seq`), oldest first, from engine writes and from hand edits (`source: external`). Each has `table`, `kind` (insert, update, delete, move, metastore, unreadable), `op` (the operation that made it), `path`, `row_id`, `changes` ({column: {before, after}}), `actor`, `migration_id`. Hand edits are compared in batches (0.7 s after the last vault change, at most 5 s after the first), in the order they happened, renames included. A hand edit that creates, changes, renames or removes a row is checked against the tables’ rules (as check_table does) with the rows that link to it: the last event of each row in the batch has `violations` (\[{path, violations: \[{code, column | constraint (the CHECK’s name), index, message}]}]), what the edit breaks (a rule a row already broke is not listed); empty when it breaks nothing, absent when nothing was checked (engine events, a check that failed). A hand edit of metastore.yaml that changes tables’ entries checks every row of those tables: on its `metastore` event. At most 100 per event; `violations_total` then counts them all. A note renamed or moved by hand (a row or a plain note) has the links to its old path rewritten across the vault once the vault is quiet (4 s without a change; not while git pulls, rebases or merges; setting repairLinksOnHandMove, on by default), and its move event does not report them as broken_link: that repair’s events (`op: repair_links`) follow the batch and name the moves in `cause` (\[{path, old_path, seq}], `seq` of the row’s move event). A hand edit that leaves a row’s front matter unreadable (broken YAML) is a `kind: unreadable` event with one violation of code `unreadable`: every read leaves the row out until the note is fixed, and the fix is an update of the row’s last readable state (an insert for a new note). Agents’ tool calls (reported by MCP servers) are `kind: tool_call` events (`call`: tool, args, ok, duration_ms, value, served_by), returned only when `kinds` includes tool_call. Pass the returned `last` as `since` next time (`head` is the newest number); `wait_ms` (max 60000) waits for a new change (long poll); `limit` max 5000. `gap: true` means older changes were dropped: re-read the tables. `where` filters rows as in select_rows (on the values after the change). Per-table versions: `table_changes`.
+
+Examples: [Hand edits](https://datanotes.dev/guides/data-quality/hand-edits/), [Change data feed](https://datanotes.dev/guides/history/change-data-feed/).
+
+| Parameter       | Type          | Required      | Default       | Description |
+| --------------- | ------------- | ------------- | ------------- | ----------- |
+| `since`         | integer       |               | `0`           |             |
+| `tables`        | string\[] \\  | null          |               | `null`      |
+| `kinds`         | `"insert"` \\ | `"update"` \\ | `"delete"` \\ | `"move"` \\ |
+| `columns`       | string\[] \\  | null          |               | `null`      |
+| `where`         | object \\     | null          |               | `null`      |
+| `exclude_actor` | string \\     | null          |               | `null`      |
+| `limit`         | integer       |               | `500`         |             |
+| `wait_ms`       | integer       |               | `0`           |             |
+
+## `list_webhooks`
+
+**List Webhooks** · read-only
+
+Webhooks of the change feed: id, url, filter (tables, ops, columns, exclude_actor), `cursor` (last change delivered), `status` (ok, failing, disabled), `last_delivery`, `last_error`. Secrets are not shown.
+
+Examples: [Change data feed](https://datanotes.dev/guides/history/change-data-feed/).
+
+## `create_webhook`
+
+**Create Webhook** · destructive write
+
+Push row changes to a URL (a service that would rather be called than poll `list_changes`): batches of up to 100 events POSTed as `{webhook, events, last}`, signed with `X-Datanotes-Signature: sha256=<HMAC of the body>`, retried with backoff until a 2xx. Events are those of `list_changes` (hand edits with their `violations`; the hand edits the service has seen are recorded before it stops). Starts from now unless `since`. Returns the webhook with its `secret` — shown only here: give it to the receiver. Only on the user’s explicit request: a webhook sends the database’s changes (and, with `since`, its past ones) to that address.
+
+Examples: [Change data feed](https://datanotes.dev/guides/history/change-data-feed/).
+
+| Parameter       | Type          | Required      | Default       | Description |
+| --------------- | ------------- | ------------- | ------------- | ----------- |
+| `url`           | string        | yes           |               |             |
+| `tables`        | string\[] \\  | null          |               | `null`      |
+| `kinds`         | `"insert"` \\ | `"update"` \\ | `"delete"` \\ | `"move"` \\ |
+| `columns`       | string\[] \\  | null          |               | `null`      |
+| `exclude_actor` | string \\     | null          |               | `null`      |
+| `where`         | object \\     | null          |               | `null`      |
+| `since`         | integer \\    | null          |               | `null`      |
+
+## `delete_webhook`
+
+**Delete Webhook** · destructive write
+
+Stop and remove a webhook (by `id` from list_webhooks).
+
+Examples: [Change data feed](https://datanotes.dev/guides/history/change-data-feed/).
+
+| Parameter | Type   | Required | Default | Description |
+| --------- | ------ | -------- | ------- | ----------- |
+| `id`      | string | yes      |         |             |