datanotes 2.0.0 → 3.0.0

package/dist/docs/api/operations/tags/auxiliary.md

@@ -0,0 +1,14 @@
+# Auxiliary
+
+Operations that describe and check the database, configure it and maintain its indexes.
+
+## Operations
+
+- [List every table: `name`, `catalog`, `schema`, `qualified` (`personal.metrics.mood` — use it](https://datanotes.dev/api/operations/list_tables/): `POST /datanotes/operations/list_tables/`
+- [Describe a table (`catalog.schema.table` or a shorter unambiguous name): `qualified`, `name`,](https://datanotes.dev/api/operations/describe_table/): `POST /datanotes/operations/describe_table/`
+- [Describe the database: its folder (`root`), `metastore` (`metastore.yaml`: read it freely,](https://datanotes.dev/api/operations/describe_database/): `POST /datanotes/operations/describe_database/`
+- [Configure the database (persisted in metastore.yaml `config:`): `root` (rename the database](https://datanotes.dev/api/operations/configure_database/): `POST /datanotes/operations/configure_database/`
+- [Validate every row against the table (required, types, ranges, enums, links, unknown](https://datanotes.dev/api/operations/check_table/): `POST /datanotes/operations/check_table/`
+- [Read-only schema inference from notes' front matter.](https://datanotes.dev/api/operations/infer_table/): `POST /datanotes/operations/infer_table/`
+- [The semantic search index: `enabled`, `provider`, `model`, `files`, `passages`, `pending`,](https://datanotes.dev/api/operations/describe_semantic_index/): `POST /datanotes/operations/describe_semantic_index/`
+- [Bring the semantic search index up to date: embed the notes changed since the last run (the](https://datanotes.dev/api/operations/sync_semantic_index/): `POST /datanotes/operations/sync_semantic_index/`

package/dist/docs/api/operations/tags/change-feed.md

@@ -0,0 +1,8 @@
+# change feed
+
+The change feed as Server-Sent Events, and the tool calls MCP servers report.
+
+## Operations
+
+- [Record an agent's tool call in the change feed (`tool_call` events): what an MCP server reports after each call, its own tools included (`served_by`). Any token may call it.](https://datanotes.dev/api/operations/record_tool_call/): `POST /datanotes/tool-calls/record/`
+- [The change feed as Server-Sent Events (id = sequence number). Resumes from Last-Event-ID or `since`.](https://datanotes.dev/api/operations/changes_stream/): `GET /datanotes/changes/stream`

package/dist/docs/api/operations/tags/history.md

@@ -0,0 +1,17 @@
+# History
+
+Operations on the journal, a table's versions, the change feed and webhooks: undo, time travel, restore and vacuum.
+
+## Operations
+
+- [Revert a journaled table operation by its `migration_id`. Refused (nothing written) when any](https://datanotes.dev/api/operations/undo_migration/): `POST /datanotes/operations/undo_migration/`
+- [The operation journal, newest first: `total` (the matching operations) and `migrations`, each with](https://datanotes.dev/api/operations/list_migrations/): `POST /datanotes/operations/list_migrations/`
+- [DESCRIBE HISTORY: the table's versions, newest first — `version`, `timestamp`, `operation`](https://datanotes.dev/api/operations/describe_history/): `POST /datanotes/operations/describe_history/`
+- [Change data feed between two versions (both included, end defaults to latest): one entry](https://datanotes.dev/api/operations/table_changes/): `POST /datanotes/operations/table_changes/`
+- [Change feed across all tables: numbered row changes (`seq`), oldest first, from engine writes](https://datanotes.dev/api/operations/list_changes/): `POST /datanotes/operations/list_changes/`
+- [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.](https://datanotes.dev/api/operations/list_webhooks/): `POST /datanotes/operations/list_webhooks/`
+- [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.](https://datanotes.dev/api/operations/create_webhook/): `POST /datanotes/operations/create_webhook/`
+- [Stop and remove a webhook (by `id` from list_webhooks).](https://datanotes.dev/api/operations/delete_webhook/): `POST /datanotes/operations/delete_webhook/`
+- [RESTORE TABLE to a `version` or `timestamp`: rows and definition return to that state —](https://datanotes.dev/api/operations/restore_table/): `POST /datanotes/operations/restore_table/`
+- [RESTORE DATABASE to a `timestamp` (each table as of its last version committed at or before it) or](https://datanotes.dev/api/operations/restore_database/): `POST /datanotes/operations/restore_database/`
+- [Delete transaction-log history older than `retain_from_version` (default: keep only the](https://datanotes.dev/api/operations/vacuum_table/): `POST /datanotes/operations/vacuum_table/`

package/dist/docs/api/operations/tags/queries.md

@@ -0,0 +1,15 @@
+# Queries
+
+Operations that read rows and notes: select_rows, link targets, text and semantic search, the link graph.
+
+## Operations
+
+- [Read a note or another file of the vault: `{path, content, front_matter, tags, modified_at,](https://datanotes.dev/api/operations/read_note/): `POST /datanotes/operations/read_note/`
+- [The direct children of a vault folder: `{folder, folders, files}`, each a vault path, sorted;](https://datanotes.dev/api/operations/list_folder/): `POST /datanotes/operations/list_folder/`
+- [Plain-text search: every word of `query` must occur, case- and accent-insensitive, in the](https://datanotes.dev/api/operations/search_notes/): `POST /datanotes/operations/search_notes/`
+- [Query rows: `{table, total, rows: [{path, ...}]}`. `table` may be a view,](https://datanotes.dev/api/operations/select_rows/): `POST /datanotes/operations/select_rows/`
+- [The rows a link column may point to, for one row: what an agent or a picker offers before writing](https://datanotes.dev/api/operations/list_link_targets/): `POST /datanotes/operations/list_link_targets/`
+- [Find notes by meaning, not exact words: `{query, results: [{path, score, heading, snippet,](https://datanotes.dev/api/operations/semantic_search/): `POST /datanotes/operations/semantic_search/`
+- [Direct neighbours of notes: what they link to (`out`) and what links to them (`in`,](https://datanotes.dev/api/operations/graph_neighbors/): `POST /datanotes/operations/graph_neighbors/`
+- [Breadth-first walk over links from `from_nodes` (`{"paths": [...]}` and/or `{"table", "where"}`).](https://datanotes.dev/api/operations/graph_traverse/): `POST /datanotes/operations/graph_traverse/`
+- [Shortest chain of links between two sets of notes (each `{"paths": [...]}` and/or](https://datanotes.dev/api/operations/graph_path/): `POST /datanotes/operations/graph_path/`

package/dist/docs/api/operations/tags/rows-dml.md

@@ -0,0 +1,16 @@
+# Rows (DML)
+
+Operations that write rows: insert, update, merge, delete, move, adopt and batch.
+
+## Operations
+
+- [Insert a row (new note). Values are validated against the columns; the note path comes from](https://datanotes.dev/api/operations/insert_row/): `POST /datanotes/operations/insert_row/`
+- [Update every row matching `where` (required: `{}` is every row). `where`: keys AND-ed; values are equality or operators](https://datanotes.dev/api/operations/update_rows/): `POST /datanotes/operations/update_rows/`
+- [Update exactly ONE row, addressed by its `id` (the system UUID) or its `path`; refused when](https://datanotes.dev/api/operations/update_row/): `POST /datanotes/operations/update_row/`
+- [Delete rows matching `where`. `mode`: "archive" (default, move to the table's archive](https://datanotes.dev/api/operations/delete_rows/): `POST /datanotes/operations/delete_rows/`
+- [Move rows matching `where` (required: `{}` is every row) to another table (e.g. split a domain out of `log` into its own](https://datanotes.dev/api/operations/move_rows/): `POST /datanotes/operations/move_rows/`
+- [Turn existing notes (not rows of any table yet) into rows of `table`, keeping their body and](https://datanotes.dev/api/operations/adopt_rows/): `POST /datanotes/operations/adopt_rows/`
+- [Several writes that succeed or fail together. `operations`: `[{"op": ..., ...arguments}]` where](https://datanotes.dev/api/operations/batch/): `POST /datanotes/operations/batch/`
+- [Add the reciprocal links missing on a table's `inverse` link columns (e.g. Alice lists Carol](https://datanotes.dev/api/operations/align_relations/): `POST /datanotes/operations/align_relations/`
+- [MERGE (upsert) `rows` into `table` by the key columns `on` (e.g. `["occurred_at"]` or](https://datanotes.dev/api/operations/merge_rows/): `POST /datanotes/operations/merge_rows/`
+- [Bring generated and identity columns up to date (all rows, or only `paths`), e.g. after](https://datanotes.dev/api/operations/recompute_columns/): `POST /datanotes/operations/recompute_columns/`

package/dist/docs/api/operations/tags/schema-ddl.md

@@ -0,0 +1,22 @@
+# Schema (DDL)
+
+Operations that define the database: tables, columns, constraints, bases and views.
+
+## Operations
+
+- [Create a table: `name`, in `catalog` and `schema` (default: the database's defaults); the definition](https://datanotes.dev/api/operations/create_table/): `POST /datanotes/operations/create_table/`
+- [Drop a table. Refused while it has rows unless `mode: "archive"`, which removes the](https://datanotes.dev/api/operations/drop_table/): `POST /datanotes/operations/drop_table/`
+- [Add a typed column. Sparse by default (written only on rows that have a value — use for](https://datanotes.dev/api/operations/add_column/): `POST /datanotes/operations/add_column/`
+- [Rename a column in metastore.yaml and on every row. Refused if `to_column` is already a column](https://datanotes.dev/api/operations/rename_column/): `POST /datanotes/operations/rename_column/`
+- [Remove a column from the schema and every row. Previous values are journaled; revert with](https://datanotes.dev/api/operations/drop_column/): `POST /datanotes/operations/drop_column/`
+- [Change a column's attributes (type, min/max/step, values, required, default, label,](https://datanotes.dev/api/operations/alter_column/): `POST /datanotes/operations/alter_column/`
+- [Alter a table: move it (`catalog`, `schema`), rename it (`name`), change](https://datanotes.dev/api/operations/alter_table/): `POST /datanotes/operations/alter_table/`
+- [Create or replace a base: a named set of columns (same spec as `create_table`) that tables](https://datanotes.dev/api/operations/define_base/): `POST /datanotes/operations/define_base/`
+- [Set the bases a table inherits from (`bases`, in order; `[]` removes them). Inherited](https://datanotes.dev/api/operations/set_table_bases/): `POST /datanotes/operations/set_table_bases/`
+- [COMMENT ON CATALOG / SCHEMA: set the `description` of a catalog (`catalog` alone) or of one of its](https://datanotes.dev/api/operations/comment_on/): `POST /datanotes/operations/comment_on/`
+- [Rename one value of an enum column (e.g. `high` → `very high`) in metastore.yaml and every](https://datanotes.dev/api/operations/rename_value/): `POST /datanotes/operations/rename_value/`
+- [ALTER TABLE ADD CONSTRAINT `name` CHECK: `check` is a where filter every row must match,](https://datanotes.dev/api/operations/add_constraint/): `POST /datanotes/operations/add_constraint/`
+- [Remove the CHECK constraint `name` from `table`.](https://datanotes.dev/api/operations/drop_constraint/): `POST /datanotes/operations/drop_constraint/`
+- [Create (or `replace`) a view: a named select stored in metastore.yaml. Name it with the prefix](https://datanotes.dev/api/operations/create_view/): `POST /datanotes/operations/create_view/`
+- [Remove a view from `metastore.yaml` (undo with `undo_migration`).](https://datanotes.dev/api/operations/drop_view/): `POST /datanotes/operations/drop_view/`
+- [CREATE TABLE `target` CLONE `source`: same definition plus independent copies of its rows](https://datanotes.dev/api/operations/clone_table/): `POST /datanotes/operations/clone_table/`

package/dist/docs/api/operations/tags/service.md

@@ -0,0 +1,15 @@
+# service
+
+Status, stop, this document, the interactive console, the docs.
+
+## Operations
+
+- [The sections of the docs of this version closest in meaning to a query: what `search_docs` fuses with its ranking by words (hybrid search).](https://datanotes.dev/api/operations/semantic_search_docs/): `POST /datanotes/manual/search/`
+- [The engine's health at a glance (owner only; `datanotes status` prints it): engine, database, journal, git sync, change feed, webhooks, named tokens, hand edits breaking the rules in the last 24 h, logs.](https://datanotes.dev/api/operations/engine_status/): `POST /datanotes/status/`
+- [Stop the engine gracefully (owner only; `datanotes stop` calls it): it answers at once, then finishes the requests under way, makes the last git sync and store backup commit and push, releases its lock and exits.](https://datanotes.dev/api/operations/stop_engine/): `POST /datanotes/stop/`
+- [This document (as `GET /datanotes/openapi.json`, with a token).](https://datanotes.dev/api/operations/openapi_post/): `POST /datanotes/openapi/`
+- [Status and version (no token needed; `authenticated` tells whether the token sent is accepted, `auth` whose it is).](https://datanotes.dev/api/operations/status/): `GET /`
+- [This document (public: it describes the API, it holds no data).](https://datanotes.dev/api/operations/openapi/): `GET /datanotes/openapi.json`
+- [This document in an interactive console (Swagger UI, served by the engine; public). Authorize with a token to try the routes.](https://datanotes.dev/api/operations/docs/): `GET /datanotes/docs`
+- [The index of the docs of this version (every page of datanotes.dev as Markdown, shipped with the package): each page with its description and route.](https://datanotes.dev/api/operations/manual_index/): `GET /datanotes/manual/`
+- [A page of the docs of this version as Markdown, or one of its sections with `section`, the anchor of its heading. The same text as the page with `.md` on datanotes.dev, offline.](https://datanotes.dev/api/operations/manual_page/): `GET /datanotes/manual/{page}.md`

package/dist/docs/api/operations/tags/tokens.md

@@ -0,0 +1,13 @@
+# tokens
+
+Named tokens and their permissions; what MCP servers report about their agents' sessions.
+
+## Operations
+
+- [Tell the engine the model and harness behind an agent session (what an MCP server reports): later requests carrying that session in `X-Datanotes-Actor` are journaled with it. Any token may call it.](https://datanotes.dev/api/operations/identify_session/): `POST /datanotes/sessions/identify/`
+- [List the named tokens (owner only).](https://datanotes.dev/api/operations/tokens_list/): `POST /datanotes/tokens/`
+- [The calling token's own entry (a named token; 400 for the owner).](https://datanotes.dev/api/operations/tokens_me/): `POST /datanotes/tokens/me/`
+- [Create a named token (owner only). Returns the token once.](https://datanotes.dev/api/operations/tokens_create/): `POST /datanotes/tokens/create/`
+- [Change a named token. A token may change its own description and autolink default; permissions are the owner's.](https://datanotes.dev/api/operations/tokens_update/): `POST /datanotes/tokens/update/`
+- [Revoke a named token (owner only): it stops working at once.](https://datanotes.dev/api/operations/tokens_delete/): `POST /datanotes/tokens/delete/`
+- [Give a named token a new value (owner only): the old one stops working.](https://datanotes.dev/api/operations/tokens_rotate/): `POST /datanotes/tokens/rotate/`

package/dist/docs/api/operations/tokens_create.md

@@ -0,0 +1,34 @@
+# Create a named token (owner only). Returns the token once.
+
+`POST /datanotes/tokens/create/` (operation `tokens_create`)
+
+## Parameters
+
+| Name | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `X-Datanotes-Actor` | header | `string` | no | JSON: on whose behalf the write is made, recorded in the journal (`harness`, `model`, `session`). |
+
+## Request body
+
+`application/json`
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `string` | yes |  | Kebab-case; the journal records it as `auth`. `owner` is reserved. |
+| `description` | `string` | no |  |  |
+| `write` | `string[]` | no |  | Tables the token may write: catalog.schema.table, catalog.schema.*, catalog.* or *. |
+| `ddl` | `boolean` | no |  | May the token change the schema? |
+| `maintain` | `boolean` | no |  | May the token also undo, restore, vacuum, configure and rebuild the semantic index? (For an agent's own token.) |
+| `autolink` | `boolean` | no |  | Automatic links of the token's writes that pass no `autolink`: false for a sync program's token. Absent: the database's `autolink` setting. |
+
+## Responses
+
+| Status | Description | Body |
+| --- | --- | --- |
+| 200 | Done. | `object` (application/json) |
+| 400 | Bad input: the body is not a JSON object, or an argument is unknown, missing or of the wrong type. | `Error` (application/json) |
+| 401 | Missing or wrong bearer token. | `Error` (application/json) |
+| 403 | A named token beyond its permissions (the engine's administration, tables outside its `write` patterns, schema changes without `ddl`). | `Error` (application/json) |
+| 500 | Unexpected error. | `Error` (application/json) |
+
+The schemas named here are in [openapi.json](https://datanotes.dev/openapi.json) (`components.schemas`).

package/dist/docs/api/operations/tokens_delete.md

@@ -0,0 +1,29 @@
+# Revoke a named token (owner only): it stops working at once.
+
+`POST /datanotes/tokens/delete/` (operation `tokens_delete`)
+
+## Parameters
+
+| Name | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `X-Datanotes-Actor` | header | `string` | no | JSON: on whose behalf the write is made, recorded in the journal (`harness`, `model`, `session`). |
+
+## Request body
+
+`application/json`
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `string` | yes |  |  |
+
+## Responses
+
+| Status | Description | Body |
+| --- | --- | --- |
+| 200 | Done. | `object` (application/json) |
+| 400 | Bad input: the body is not a JSON object, or an argument is unknown, missing or of the wrong type. | `Error` (application/json) |
+| 401 | Missing or wrong bearer token. | `Error` (application/json) |
+| 403 | A named token beyond its permissions (the engine's administration, tables outside its `write` patterns, schema changes without `ddl`). | `Error` (application/json) |
+| 500 | Unexpected error. | `Error` (application/json) |
+
+The schemas named here are in [openapi.json](https://datanotes.dev/openapi.json) (`components.schemas`).

package/dist/docs/api/operations/tokens_list.md

@@ -0,0 +1,21 @@
+# List the named tokens (owner only).
+
+`POST /datanotes/tokens/` (operation `tokens_list`)
+
+## Request body
+
+`application/json`
+
+Type: `object`
+
+## Responses
+
+| Status | Description | Body |
+| --- | --- | --- |
+| 200 | Done. | `object` (application/json) |
+| 400 | Bad input: the body is not a JSON object, or an argument is unknown, missing or of the wrong type. | `Error` (application/json) |
+| 401 | Missing or wrong bearer token. | `Error` (application/json) |
+| 403 | A named token beyond its permissions (the engine's administration, tables outside its `write` patterns, schema changes without `ddl`). | `Error` (application/json) |
+| 500 | Unexpected error. | `Error` (application/json) |
+
+The schemas named here are in [openapi.json](https://datanotes.dev/openapi.json) (`components.schemas`).

package/dist/docs/api/operations/tokens_me.md

@@ -0,0 +1,20 @@
+# The calling token's own entry (a named token; 400 for the owner).
+
+`POST /datanotes/tokens/me/` (operation `tokens_me`)
+
+## Request body
+
+`application/json`
+
+Type: `object`
+
+## Responses
+
+| Status | Description | Body |
+| --- | --- | --- |
+| 200 | Done. | `object` (application/json) |
+| 400 | Bad input: the body is not a JSON object, or an argument is unknown, missing or of the wrong type. | `Error` (application/json) |
+| 401 | Missing or wrong bearer token. | `Error` (application/json) |
+| 500 | Unexpected error. | `Error` (application/json) |
+
+The schemas named here are in [openapi.json](https://datanotes.dev/openapi.json) (`components.schemas`).

package/dist/docs/api/operations/tokens_rotate.md

@@ -0,0 +1,29 @@
+# Give a named token a new value (owner only): the old one stops working.
+
+`POST /datanotes/tokens/rotate/` (operation `tokens_rotate`)
+
+## Parameters
+
+| Name | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `X-Datanotes-Actor` | header | `string` | no | JSON: on whose behalf the write is made, recorded in the journal (`harness`, `model`, `session`). |
+
+## Request body
+
+`application/json`
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `string` | yes |  |  |
+
+## Responses
+
+| Status | Description | Body |
+| --- | --- | --- |
+| 200 | Done. | `object` (application/json) |
+| 400 | Bad input: the body is not a JSON object, or an argument is unknown, missing or of the wrong type. | `Error` (application/json) |
+| 401 | Missing or wrong bearer token. | `Error` (application/json) |
+| 403 | A named token beyond its permissions (the engine's administration, tables outside its `write` patterns, schema changes without `ddl`). | `Error` (application/json) |
+| 500 | Unexpected error. | `Error` (application/json) |
+
+The schemas named here are in [openapi.json](https://datanotes.dev/openapi.json) (`components.schemas`).

package/dist/docs/api/operations/tokens_update.md

@@ -0,0 +1,34 @@
+# Change a named token. A token may change its own description and autolink default; permissions are the owner's.
+
+`POST /datanotes/tokens/update/` (operation `tokens_update`)
+
+## Parameters
+
+| Name | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `X-Datanotes-Actor` | header | `string` | no | JSON: on whose behalf the write is made, recorded in the journal (`harness`, `model`, `session`). |
+
+## Request body
+
+`application/json`
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `string` | no |  | Owner only (a named token updates itself). |
+| `description` | `string` | no |  | An empty string removes it. |
+| `write` | `string[]` | no |  |  |
+| `ddl` | `boolean` | no |  |  |
+| `maintain` | `boolean` | no |  |  |
+| `autolink` | `boolean \| null` | no |  | The default of the token's writes for automatic links; null follows the database's setting again. |
+
+## Responses
+
+| Status | Description | Body |
+| --- | --- | --- |
+| 200 | Done. | `object` (application/json) |
+| 400 | Bad input: the body is not a JSON object, or an argument is unknown, missing or of the wrong type. | `Error` (application/json) |
+| 401 | Missing or wrong bearer token. | `Error` (application/json) |
+| 403 | A named token beyond its permissions (the engine's administration, tables outside its `write` patterns, schema changes without `ddl`). | `Error` (application/json) |
+| 500 | Unexpected error. | `Error` (application/json) |
+
+The schemas named here are in [openapi.json](https://datanotes.dev/openapi.json) (`components.schemas`).

package/dist/docs/api/operations/undo_migration.md

@@ -0,0 +1,46 @@
+# Revert a journaled table operation by its `migration_id`. Refused (nothing written) when any
+
+`POST /datanotes/operations/undo_migration/` (operation `undo_migration`)
+
+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).
+
+## Parameters
+
+| Name | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `X-Datanotes-Actor` | header | `string` | no | JSON: on whose behalf the write is made, recorded in the journal (`harness`, `model`, `session`). |
+
+## Request body
+
+`application/json`, required
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `migration_id` | `string` | yes |  |  |
+
+## Responses
+
+| Status | Description | Body |
+| --- | --- | --- |
+| 200 | Done. | `object` (application/json) |
+| 400 | Bad input: the body is not a JSON object, or an argument is unknown, missing or of the wrong type. | `Error` (application/json) |
+| 401 | Missing or wrong bearer token. | `Error` (application/json) |
+| 403 | A named token beyond its permissions (the engine's administration, tables outside its `write` patterns, schema changes without `ddl`). | `Error` (application/json) |
+| 404 | Unknown table, view, migration, note or folder. | `Error` (application/json) |
+| 409 | Undo refused (later changes depend on it, or it was undone already): nothing written (a batch is checked as a whole first; when one of its operations then finds a note changed since, the operations after it stay reverted: `touched`, and a retry skips them). Same body as 200, with `ok: false`. | `object \| AmbiguousName` (application/json) |
+| 500 | Unexpected error (`{error}`), or a write that failed partway and could not be rolled back: `rolled_back: false`, `failed` lists the files left (undo_migration on `migration_id` retries the rollback). | `object \| Error` (application/json) |
+
+The schemas named here are in [openapi.json](https://datanotes.dev/openapi.json) (`components.schemas`).

package/dist/docs/api/operations/update_row.md

@@ -0,0 +1,60 @@
+# Update exactly ONE row, addressed by its `id` (the system UUID) or its `path`; refused when
+
+`POST /datanotes/operations/update_row/` (operation `update_row`)
+
+Update exactly ONE row, addressed by its `id` (the system UUID) or its `path`; refused when
+the row does not exist (or id and path disagree). Same validation, journal and history as
+`update_rows`.
+
+- `set` / `unset`: columns to set or remove.
+- `body`: replace the whole note body; or edit it keeping the rest:
+  `body_sections` `{"History": "…"}` replaces the text under that heading (any level, up to the
+  next heading of the same level; added as `## History` when missing), `body_prepend` /
+  `body_append` add text before / after.
+- `expect`: compare-and-set — `{"status": "open"}` writes only if the row still has those
+  values (a person may have changed it since you read it); otherwise refused, nothing written.
+- `autolink`: the text written links the notes it mentions by name, at their first mention
+  (off with `autolink: false` or the database's setting). `links_added` lists the links made;
+  `ambiguous_mentions` the mentions left as text with the notes they may name: read those, then
+  link the right one with update_row and `autolink: false`, or leave the text.
+
+## Parameters
+
+| Name | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `X-Datanotes-Actor` | header | `string` | no | JSON: on whose behalf the write is made, recorded in the journal (`harness`, `model`, `session`). |
+
+## Request body
+
+`application/json`, required
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `table` | `string` | yes |  |  |
+| `id` | `string \| null` | no | `null` |  |
+| `path` | `string \| null` | no | `null` |  |
+| `set` | `object \| null` | no | `null` |  |
+| `unset` | `string[] \| null` | no | `null` |  |
+| `body` | `string \| null` | no | `null` |  |
+| `body_sections` | `object \| null` | no | `null` |  |
+| `body_prepend` | `string \| null` | no | `null` |  |
+| `expect` | `object \| null` | no | `null` |  |
+| `body_append` | `string \| null` | no | `null` |  |
+| `dry_run` | `boolean` | no | `false` |  |
+| `autolink` | `boolean \| null` | no | `null` | Automatic links for this write: true links the notes the text written (`body`, `body_sections`, `body_prepend`, `body_append`) mentions by name, false writes it as given. Default: the calling token's `autolink` default, else the database's `autolink` setting (on unless configure_database turned it off). |
+
+## Responses
+
+| Status | Description | Body |
+| --- | --- | --- |
+| 200 | Done. | `OpResult` (application/json) |
+| 400 | Bad input: the body is not a JSON object, or an argument is unknown, missing or of the wrong type. | `Error` (application/json) |
+| 401 | Missing or wrong bearer token. | `Error` (application/json) |
+| 403 | A named token beyond its permissions (the engine's administration, tables outside its `write` patterns, schema changes without `ddl`). | `Error` (application/json) |
+| 404 | Unknown table, view, migration, note or folder. | `Error` (application/json) |
+| 409 | Ambiguous table name: it matches several tables (`paths` or `tables` lists them). | `AmbiguousName` (application/json) |
+| 422 | Refused (validation failures, conflicts, an unmet `expect`): nothing written. Same body as 200, with `ok: false` and the reasons. | `OpResult` (application/json) |
+| 500 | Unexpected error (`{error}`), or a write that failed partway and could not be rolled back: `rolled_back: false`, `failed` lists the files left (undo_migration on `migration_id` retries the rollback). | `OpResult \| Error` (application/json) |
+| 503 | A write that failed partway (a file another program holds) and was rolled back: `rolled_back: true`, nothing written. Send it again later. Same body as 200, with `ok: false` and `failed`. | `OpResult` (application/json) |
+
+The schemas named here are in [openapi.json](https://datanotes.dev/openapi.json) (`components.schemas`).

package/dist/docs/api/operations/update_rows.md

@@ -0,0 +1,46 @@
+# Update every row matching `where` (required: `{}` is every row). `where`: keys AND-ed; values are equality or operators
+
+`POST /datanotes/operations/update_rows/` (operation `update_rows`)
+
+Update every row matching `where` (required: `{}` is every row). `where`: keys AND-ed; values are equality or operators
+eq, ne, gt, gte, lt, lte, in, contains, icontains (case/accent-insensitive, also inside lists —
+use it for names and aliases), exists, within (a hierarchy link: that row and everything below);
+combine with `or` / `and` / `not` (nestable); `path` is a pseudo-column. A dotted key follows a
+link column: `{"project.area": "[[Work]]"}` matches rows whose `project` links a row with that `area`. `set` sets, `unset`
+removes; all rows are validated first.
+`expect_count`: refuse unless exactly that many match. One row, or its text: update_row.
+
+## Parameters
+
+| Name | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `X-Datanotes-Actor` | header | `string` | no | JSON: on whose behalf the write is made, recorded in the journal (`harness`, `model`, `session`). |
+
+## Request body
+
+`application/json`, required
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `table` | `string` | yes |  |  |
+| `where` | `object` | yes |  | The rows to change; {} is every row of the table. |
+| `set` | `object \| null` | no | `null` |  |
+| `unset` | `string[] \| null` | no | `null` |  |
+| `dry_run` | `boolean` | no | `false` |  |
+| `expect_count` | `integer \| null` | no | `null` | Refuse (nothing written) unless `where` matches exactly this many rows. |
+
+## Responses
+
+| Status | Description | Body |
+| --- | --- | --- |
+| 200 | Done. | `OpResult` (application/json) |
+| 400 | Bad input: the body is not a JSON object, or an argument is unknown, missing or of the wrong type. | `Error` (application/json) |
+| 401 | Missing or wrong bearer token. | `Error` (application/json) |
+| 403 | A named token beyond its permissions (the engine's administration, tables outside its `write` patterns, schema changes without `ddl`). | `Error` (application/json) |
+| 404 | Unknown table, view, migration, note or folder. | `Error` (application/json) |
+| 409 | Ambiguous table name: it matches several tables (`paths` or `tables` lists them). | `AmbiguousName` (application/json) |
+| 422 | Refused (validation failures, conflicts, an unmet `expect`): nothing written. Same body as 200, with `ok: false` and the reasons. | `OpResult` (application/json) |
+| 500 | Unexpected error (`{error}`), or a write that failed partway and could not be rolled back: `rolled_back: false`, `failed` lists the files left (undo_migration on `migration_id` retries the rollback). | `OpResult \| Error` (application/json) |
+| 503 | A write that failed partway (a file another program holds) and was rolled back: `rolled_back: true`, nothing written. Send it again later. Same body as 200, with `ok: false` and `failed`. | `OpResult` (application/json) |
+
+The schemas named here are in [openapi.json](https://datanotes.dev/openapi.json) (`components.schemas`).

package/dist/docs/api/operations/vacuum_table.md

@@ -0,0 +1,37 @@
+# Delete transaction-log history older than `retain_from_version` (default: keep only the
+
+`POST /datanotes/operations/vacuum_table/` (operation `vacuum_table`)
+
+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.
+
+## Parameters
+
+| Name | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `X-Datanotes-Actor` | header | `string` | no | JSON: on whose behalf the write is made, recorded in the journal (`harness`, `model`, `session`). |
+
+## Request body
+
+`application/json`, required
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `table` | `string` | yes |  |  |
+| `retain_from_version` | `integer \| null` | no | `null` |  |
+| `dry_run` | `boolean` | no | `true` |  |
+
+## Responses
+
+| Status | Description | Body |
+| --- | --- | --- |
+| 200 | Done. | `object` (application/json) |
+| 400 | Bad input: the body is not a JSON object, or an argument is unknown, missing or of the wrong type. | `Error` (application/json) |
+| 401 | Missing or wrong bearer token. | `Error` (application/json) |
+| 403 | A named token beyond its permissions (the engine's administration, tables outside its `write` patterns, schema changes without `ddl`). | `Error` (application/json) |
+| 404 | Unknown table, view, migration, note or folder. | `Error` (application/json) |
+| 409 | Ambiguous table name: it matches several tables (`paths` or `tables` lists them). | `AmbiguousName` (application/json) |
+| 500 | Unexpected error. | `Error` (application/json) |
+
+The schemas named here are in [openapi.json](https://datanotes.dev/openapi.json) (`components.schemas`).