datanotes 2.0.1 → 3.0.0

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

@@ -0,0 +1,13 @@
+# This document (public: it describes the API, it holds no data).
+
+`GET /datanotes/openapi.json` (operation `openapi`)
+
+No authentication needed.
+
+## Responses
+
+| Status | Description | Body |
+| --- | --- | --- |
+| 200 | OpenAPI 3.1. | `object` (application/json) |
+
+The schemas named here are in [openapi.json](https://datanotes.dev/openapi.json) (`components.schemas`).

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

@@ -0,0 +1,20 @@
+# This document (as `GET /datanotes/openapi.json`, with a token).
+
+`POST /datanotes/openapi/` (operation `openapi_post`)
+
+## 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/read_note.md

@@ -0,0 +1,29 @@
+# Read a note or another file of the vault: `{path, content, front_matter, tags, modified_at,
+
+`POST /datanotes/operations/read_note/` (operation `read_note`)
+
+Read a note or another file of the vault: `{path, content, front_matter, tags, modified_at,
+created_at, size}`. `content` is the whole text, front matter included; `tags` are without `#`,
+from the text and the front matter; the times are in the database's time zone. A missing file is
+an error. `path`: vault-relative, forward slashes.
+
+## Request body
+
+`application/json`, required
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `path` | `string` | yes |  | The file's vault path, with its extension ("Films/Metropolis.md"). |
+
+## 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) |
+| 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`).

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

@@ -0,0 +1,44 @@
+# Bring generated and identity columns up to date (all rows, or only `paths`), e.g. after
+
+`POST /datanotes/operations/recompute_columns/` (operation `recompute_columns`)
+
+Bring generated and identity columns up to date (all rows, or only `paths`), e.g. after
+rows were edited by hand (an editor, git, sync) or a generated expression changed with `alter_column`.
+Also gives rows without an `id` a new one, and a duplicated note (same `id` as an older row)
+a new id. `new_ids=true` regenerates every id in scope (new ones on every call): only on the user's
+explicit request.
+`check_table` reports stale values with code `generated`. No-op when nothing is stale;
+otherwise journaled (undo_migration) and a RECOMPUTE version in the table's history.
+
+## 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 |  |  |
+| `paths` | `string[] \| null` | no | `null` |  |
+| `new_ids` | `boolean` | no | `false` |  |
+| `dry_run` | `boolean` | no | `false` |  |
+
+## 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/record_tool_call.md

@@ -0,0 +1,36 @@
+# 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.
+
+`POST /datanotes/tool-calls/record/` (operation `record_tool_call`)
+
+## 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 |
+| --- | --- | --- | --- | --- |
+| `tool` | `string` | yes |  |  |
+| `args` | `object` | no |  |  |
+| `ok` | `boolean` | no |  |  |
+| `duration_ms` | `number` | no |  |  |
+| `value` | `any` | no |  |  |
+| `served_by` | `string` | no |  |  |
+| `session` | `string` | no |  |  |
+| `result_chars` | `number` | no |  |  |
+| `result_tokens` | `number` | no |  |  |
+
+## 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/rename_column.md

@@ -0,0 +1,44 @@
+# Rename a column in metastore.yaml and on every row. Refused if `to_column` is already a column
+
+`POST /datanotes/operations/rename_column/` (operation `rename_column`)
+
+Rename a column in metastore.yaml and on every row. Refused if `to_column` is already a column
+of the table; a row that has a stray `to_column` key with a different value is a conflict, and
+nothing is written. CHECKs, `ref_where` and `ref_by` that read the column (in this table, or through
+a link from another table: `parent.kind`) follow the new name. Views and note text that mention the
+old name are not rewritten.
+
+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 |
+| --- | --- | --- | --- | --- |
+| `table` | `string` | yes |  |  |
+| `from_column` | `string` | yes |  |  |
+| `to_column` | `string` | yes |  |  |
+| `dry_run` | `boolean` | no | `false` |  |
+
+## 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/rename_value.md

@@ -0,0 +1,45 @@
+# Rename one value of an enum column (e.g. `high` → `very high`) in metastore.yaml and every
+
+`POST /datanotes/operations/rename_value/` (operation `rename_value`)
+
+Rename one value of an enum column (e.g. `high` → `very high`) in metastore.yaml and every
+row, keeping its position, so an ordered scale is unchanged. CHECKs and `ref_where` conditions on
+the column (also through a link from another table) and `ref_by` levels / maps that name the value
+use the new one. Note text (queries, prose) is not rewritten. Refused if `to_value` already exists. Undo with `undo_migration`. Adding or
+removing classes changes the scale: create a new table instead.
+
+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 |
+| --- | --- | --- | --- | --- |
+| `table` | `string` | yes |  |  |
+| `column` | `string` | yes |  |  |
+| `from_value` | `string` | yes |  |  |
+| `to_value` | `string` | yes |  |  |
+| `dry_run` | `boolean` | no | `false` |  |
+
+## 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/restore_database.md

@@ -0,0 +1,51 @@
+# RESTORE DATABASE to a `timestamp` (each table as of its last version committed at or before it) or
+
+`POST /datanotes/operations/restore_database/` (operation `restore_database`)
+
+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).
+
+## 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 |
+| --- | --- | --- | --- | --- |
+| `timestamp` | `string \| null` | no | `null` |  |
+| `before_migration` | `string \| null` | no | `null` |  |
+| `dry_run` | `boolean` | no | `false` |  |
+
+## Responses
+
+| Status | Description | Body |
+| --- | --- | --- |
+| 200 | Done. | `RestoreDatabaseResult` (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) |
+| 422 | Refused (validation failures, conflicts, an unmet `expect`): nothing written. Same body as 200, with `ok: false` and the reasons. | `RestoreDatabaseResult` (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). | `RestoreDatabaseResult \| 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`. | `RestoreDatabaseResult` (application/json) |
+
+The schemas named here are in [openapi.json](https://datanotes.dev/openapi.json) (`components.schemas`).

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

@@ -0,0 +1,46 @@
+# RESTORE TABLE to a `version` or `timestamp`: rows and definition return to that state —
+
+`POST /datanotes/operations/restore_table/` (operation `restore_table`)
+
+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).
+
+## 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 |  |  |
+| `version` | `integer \| null` | no | `null` |  |
+| `timestamp` | `string \| null` | no | `null` |  |
+| `dry_run` | `boolean` | no | `false` |  |
+
+## 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/search_notes.md

@@ -0,0 +1,28 @@
+# Plain-text search: every word of `query` must occur, case- and accent-insensitive, in the
+
+`POST /datanotes/operations/search_notes/` (operation `search_notes`)
+
+Plain-text search: every word of `query` must occur, case- and accent-insensitive, in the
+note's path or text; there are no operators. Returns `{query, results: [{path, score, matches:
+[{start, end, context}]}], total}`, best first: at most 200 notes (`total` counts them all) and 20
+matches per note. `context_length`: characters of context on each side (default 100, max 1000).
+
+## Request body
+
+`application/json`, required
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `query` | `string` | yes |  |  |
+| `context_length` | `integer` | no | `100` | Characters of context on each side of a match (at most 1000). |
+
+## 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/select_rows.md

@@ -0,0 +1,61 @@
+# Query rows: `{table, total, rows: [{path, ...}]}`. `table` may be a view,
+
+`POST /datanotes/operations/select_rows/` (operation `select_rows`)
+
+Query rows: `{table, total, rows: [{path, ...}]}`. `table` may be a view,
+`system.information_schema.<catalogs|schemata|tables|columns|views|check_constraints>`, or
+`base:<name>` — every table that extends that base (e.g. `base:record`: all event-like tables),
+on the base's columns, each row tagged `_source` with its table.
+- `where`: as in update_rows; relative dates `"{today}"`, `"{today-7d}"`, `"{now-24h}"` (on a date column a date-time
+  counts by its day); file columns
+  `file_name`, `file_link`, `file_modified`, `file_backlink_count`.
+- `columns`, `order_by` (`-col` descending), `limit` (default 100, max 1000), `offset`,
+  `expand` (inline linked rows' frontmatter), `include_body` (the note body as `body`).
+- `join`: `{"table", "on": {"date(occurred_at)+1": "date(timestamp)"}, "as", "type": "inner"|"left",
+  "columns", "where"}` — matches attached under `as`.
+- `group_by` (column, `path` or `date(col)±n`; a list column counts once per item) + `aggregates`
+  `{"n": "count", "kcal": "sum:meal.kcal"}` (count, count:col, sum, avg, min, max).
+- `this_note`: vault path of the note the result is for: `{this.*}` tokens in a view's query
+  and in `where` read it (`{this.date}`, `{this.link}`, `{this.name}`, `{this.path}`); without
+  it (or a front matter key the note lacks) a token stays as written and matches no row, whatever the
+  operator (`within` included).
+- Ordered enums compare by position. Time travel: `version` (of one table) or `timestamp`. With
+  `timestamp` a join, a view, a union or `base:<name>` reads every table in it as of that time
+  (`versions`: the version read of each); a table that did not exist then adds no rows to a union or
+  base. `version` is refused where several tables are read; information_schema has no history.
+  Views and bases keep today's definition, and links followed by `where` (`project.kind`, `within`)
+  or `expand` read the linked rows as they are now.
+
+## Request body
+
+`application/json`, required
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `table` | `string` | yes |  |  |
+| `columns` | `string[] \| null` | no | `null` |  |
+| `where` | `object \| null` | no | `null` |  |
+| `order_by` | `string \| string[] \| null` | no | `null` |  |
+| `limit` | `integer \| null` | no | `null` |  |
+| `offset` | `integer \| null` | no | `null` |  |
+| `expand` | `string[] \| null` | no | `null` |  |
+| `join` | `object \| null` | no | `null` |  |
+| `group_by` | `string \| string[] \| null` | no | `null` |  |
+| `aggregates` | `object \| null` | no | `null` |  |
+| `include_body` | `boolean` | no | `false` |  |
+| `version` | `integer \| null` | no | `null` |  |
+| `timestamp` | `string \| null` | no | `null` |  |
+| `this_note` | `string \| null` | no | `null` |  |
+
+## 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) |
+| 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`).

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

@@ -0,0 +1,34 @@
+# Find notes by meaning, not exact words: `{query, results: [{path, score, heading, snippet,
+
+`POST /datanotes/operations/semantic_search/` (operation `semantic_search`)
+
+Find notes by meaning, not exact words: `{query, results: [{path, score, heading, snippet,
+table?}]}`, one result per note (its best passage), best first. Use it for vague questions
+("the dinner where we talked about moving", "what did I decide about the car") and to find the
+rows to read or update; then read_note / select_rows for the details. Filters: `tables`
+(qualified or short names), `folder`, `min_score` (cosine 0–1; ~0.5+ is usually relevant).
+`limit`: default 10, max 100. Fails with a clear message when semantic search is not enabled in
+the engine settings.
+
+## Request body
+
+`application/json`, required
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `query` | `string` | yes |  |  |
+| `limit` | `integer` | no | `10` |  |
+| `tables` | `string[] \| null` | no | `null` |  |
+| `folder` | `string \| null` | no | `null` |  |
+| `min_score` | `number \| null` | no | `null` |  |
+
+## 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/semantic_search_docs.md

@@ -0,0 +1,26 @@
+# 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).
+
+`POST /datanotes/manual/search/` (operation `semantic_search_docs`)
+
+The engine embeds every section of the docs it ships with the provider of semantic search, in an index of its own (`semantic/docs.json` in its store), rebuilt when the docs change. It builds the index in the background, after it starts and when a search finds it out of date: until the index covers the docs, the answer has `ready: false` and no results. 400 when semantic search is off.
+
+## Request body
+
+`application/json`, required
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `query` | `string` | yes |  | The words to rank the sections by, such as `time travel a view`. |
+| `limit` | `integer` | no | `50` | The most sections to return. |
+
+## Responses
+
+| Status | Description | Body |
+| --- | --- | --- |
+| 200 | Done. | `DocsSemanticResults` (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) |
+| 503 | The docs are not in this installation (a checkout where they were not built). | `Error` (application/json) |
+
+The schemas named here are in [openapi.json](https://datanotes.dev/openapi.json) (`components.schemas`).

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

@@ -0,0 +1,44 @@
+# Set the bases a table inherits from (`bases`, in order; `[]` removes them). Inherited
+
+`POST /datanotes/operations/set_table_bases/` (operation `set_table_bases`)
+
+Set the bases a table inherits from (`bases`, in order; `[]` removes them). Inherited
+columns come after `id` and before the table's own columns. An own column with the name of an
+inherited one is replaced by the inherited definition (rows must fit it, its `ref_where` /
+`ref_by` included); a table may only
+restyle an inherited column (label, description, aliases, note, dense) with `alter_column`.
+Dense and generated/identity columns are filled on existing rows.
+
+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 |
+| --- | --- | --- | --- | --- |
+| `table` | `string` | yes |  |  |
+| `bases` | `string[]` | yes |  |  |
+| `dry_run` | `boolean` | no | `false` |  |
+
+## 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/status.md

@@ -0,0 +1,13 @@
+# Status and version (no token needed; `authenticated` tells whether the token sent is accepted, `auth` whose it is).
+
+`GET /` (operation `status`)
+
+No authentication needed.
+
+## Responses
+
+| Status | Description | Body |
+| --- | --- | --- |
+| 200 | Running. | `object` (application/json) |
+
+The schemas named here are in [openapi.json](https://datanotes.dev/openapi.json) (`components.schemas`).

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

@@ -0,0 +1,23 @@
+# 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.
+
+`POST /datanotes/stop/` (operation `stop_engine`)
+
+From the answer on, new requests get 503 (the engine is stopping) and long polls of the change feed answer at once. The engine waits for the requests under way for up to 30 s. Then it makes the vault's last git sync and the store backup's last commit and push, releases the lock and exits. The caller learns the end from the process (`datanotes stop` waits for it) or from `GET /`, which stops answering. A named token is refused (403), even with `maintain`. A host that cannot stop on request does not serve the route (404).
+
+## 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/sync_semantic_index.md

@@ -0,0 +1,33 @@
+# Bring the semantic search index up to date: embed the notes changed since the last run (the
+
+`POST /datanotes/operations/sync_semantic_index/` (operation `sync_semantic_index`)
+
+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.
+
+## 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 |
+| --- | --- | --- | --- | --- |
+| `rebuild` | `boolean` | no | `false` | Re-embed every note, not only the changed ones. |
+
+## Responses
+
+| Status | Description | Body |
+| --- | --- | --- |
+| 200 | Done. | `SemanticSyncResult` (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/table_changes.md

@@ -0,0 +1,31 @@
+# Change data feed between two versions (both included, end defaults to latest): one entry
+
+`POST /datanotes/operations/table_changes/` (operation `table_changes`)
+
+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.
+
+## Request body
+
+`application/json`, required
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `table` | `string` | yes |  |  |
+| `start_version` | `integer` | yes |  |  |
+| `end_version` | `integer \| null` | no | `null` |  |
+
+## 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) |
+| 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`).