datanotes 2.0.0 → 3.0.0

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

@@ -0,0 +1,38 @@
+# Remove a view from `metastore.yaml` (undo with `undo_migration`).
+
+`POST /datanotes/operations/drop_view/` (operation `drop_view`)
+
+Remove a view from `metastore.yaml` (undo with `undo_migration`).
+
+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 |
+| --- | --- | --- | --- | --- |
+| `view` | `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/engine_status.md

@@ -0,0 +1,23 @@
+# 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.
+
+`POST /datanotes/status/` (operation `engine_status`)
+
+Reads what the engine already knows (nothing is checked again): hand edits are judged by the checks the change feed recorded with them. `healthy` is false when `problems` lists something. A named token is refused (403), even with `maintain`.
+
+## Request body
+
+`application/json`
+
+Type: `object`
+
+## Responses
+
+| Status | Description | Body |
+| --- | --- | --- |
+| 200 | Done. | `EngineStatus` (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/graph_neighbors.md

@@ -0,0 +1,32 @@
+# Direct neighbours of notes: what they link to (`out`) and what links to them (`in`,
+
+`POST /datanotes/operations/graph_neighbors/` (operation `graph_neighbors`)
+
+Direct neighbours of notes: what they link to (`out`) and what links to them (`in`,
+backlinks), with counts per edge label. `direction`: out, in or both (default).
+
+`from_nodes` selects the notes: `{"paths": [...]}` and/or `{"table": ..., "where": {...}}`.
+Edges are labelled with their link column (`people`, `event`, …) or `link` for other links.
+
+## Request body
+
+`application/json`, required
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `from_nodes` | `object` | yes |  |  |
+| `direction` | `"out" \| "in" \| "both" \| null` | no | `null` |  |
+| `edges` | `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/graph_path.md

@@ -0,0 +1,32 @@
+# Shortest chain of links between two sets of notes (each `{"paths": [...]}` and/or
+
+`POST /datanotes/operations/graph_path/` (operation `graph_path`)
+
+Shortest chain of links between two sets of notes (each `{"paths": [...]}` and/or
+`{"table", "where"}`): `found`, `length` and `path`: the steps (`from`, `label`, `direction`, `to`).
+`direction` both by default; `max_depth` default 6 (max 10).
+
+## Request body
+
+`application/json`, required
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `from_nodes` | `object` | yes |  |  |
+| `to_nodes` | `object` | yes |  |  |
+| `direction` | `"out" \| "in" \| "both" \| null` | no | `null` |  |
+| `edges` | `string[] \| null` | no | `null` |  |
+| `max_depth` | `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`).

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

@@ -0,0 +1,43 @@
+# Breadth-first walk over links from `from_nodes` (`{"paths": [...]}` and/or `{"table", "where"}`).
+
+`POST /datanotes/operations/graph_traverse/` (operation `graph_traverse`)
+
+Breadth-first walk over links from `from_nodes` (`{"paths": [...]}` and/or `{"table", "where"}`).
+
+- `direction`: out (default, follow links), in (follow backlinks) or both.
+- `edges`: edge labels to follow (link columns such as `people`, `event`, or `link`).
+- `tables`: return only notes of these tables; `through`: only walk on through these tables.
+- `min_depth` (default 1) / `max_depth` (default 2, max 10), `limit` (default 500).
+
+Each node comes with `depth` and `via` (one shortest route). Example — moods tied to events
+with Alice: from `{"table": "person", "where": {"name": "Alice"}}`, direction `in`, edges
+`["people", "event"]`, tables `["mood"]`, max_depth 2. Feed the paths to `select_rows` with
+`where: {"path": {"in": [...]}}` to aggregate them.
+
+## Request body
+
+`application/json`, required
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `from_nodes` | `object` | yes |  |  |
+| `direction` | `"out" \| "in" \| "both" \| null` | no | `null` |  |
+| `edges` | `string[] \| null` | no | `null` |  |
+| `tables` | `string[] \| null` | no | `null` |  |
+| `through` | `string[] \| null` | no | `null` |  |
+| `min_depth` | `integer \| null` | no | `null` |  |
+| `max_depth` | `integer \| null` | no | `null` |  |
+| `limit` | `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`).

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

@@ -0,0 +1,24 @@
+# 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.
+
+`POST /datanotes/sessions/identify/` (operation `identify_session`)
+
+## Request body
+
+`application/json`, required
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `session` | `string` | yes |  |  |
+| `model` | `string` | no |  |  |
+| `harness` | `string` | 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/infer_table.md

@@ -0,0 +1,43 @@
+# Read-only schema inference from notes' front matter.
+
+`POST /datanotes/operations/infer_table/` (operation `infer_table`)
+
+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.
+
+## Request body
+
+`application/json`
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `folder` | `string \| null` | no | `null` |  |
+| `paths` | `string[] \| null` | no | `null` |  |
+| `table` | `string \| null` | no | `null` |  |
+| `name` | `string \| null` | no | `null` |  |
+| `max_enum_values` | `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`).

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

@@ -0,0 +1,48 @@
+# Insert a row (new note). Values are validated against the columns; the note path comes from
+
+`POST /datanotes/operations/insert_row/` (operation `insert_row`)
+
+Insert a row (new note). Values are validated against the columns; the note path comes from
+the table's `path`/`filename` patterns (e.g. an event logged today about last night lands in
+last night's day folder when you set `occurred_at` to last night). `body` is the note text.
+Generated / identity columns are computed (do not pass them); CHECK constraints are enforced.
+Returns `migration_id` (undo) and the created path in `planned_creates`.
+`body` links the notes it mentions by name, at their first mention (automatic links; off with
+`autolink: false` or the database's `autolink` setting). `links_added` lists the links made;
+`ambiguous_mentions` lists 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 |  |  |
+| `values` | `object` | yes |  |  |
+| `body` | `string \| null` | no | `null` |  |
+| `path` | `string \| null` | no | `null` | Optional note path (vault-relative), instead of the table's file-name pattern; `.md` is added if missing; it must stay inside the vault. |
+| `dry_run` | `boolean` | no | `false` |  |
+| `autolink` | `boolean \| null` | no | `null` | Automatic links for this write: true links the notes `body` 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/list_changes.md

@@ -0,0 +1,35 @@
+# Change feed across all tables: numbered row changes (`seq`), oldest first, from engine writes
+
+`POST /datanotes/operations/list_changes/` (operation `list_changes`)
+
+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`.
+
+## Request body
+
+`application/json`
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `since` | `integer` | no | `0` |  |
+| `tables` | `string[] \| null` | no | `null` |  |
+| `kinds` | `("insert" \| "update" \| "delete" \| "move" \| "metastore" \| "tool_call" \| "unreadable")[] \| null` | no | `null` |  |
+| `columns` | `string[] \| null` | no | `null` |  |
+| `where` | `object \| null` | no | `null` |  |
+| `exclude_actor` | `string \| null` | no | `null` |  |
+| `limit` | `integer` | no | `500` |  |
+| `wait_ms` | `integer` | no | `0` |  |
+
+## 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/list_folder.md

@@ -0,0 +1,28 @@
+# The direct children of a vault folder: `{folder, folders, files}`, each a vault path, sorted;
+
+`POST /datanotes/operations/list_folder/` (operation `list_folder`)
+
+The direct children of a vault folder: `{folder, folders, files}`, each a vault path, sorted;
+dot-files and dot-folders are left out. `folder` "" is the vault root. A missing folder is an
+error.
+
+## Request body
+
+`application/json`
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `folder` | `string` | no | `""` | Vault-relative folder; "" is the vault root. |
+
+## 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/list_link_targets.md

@@ -0,0 +1,44 @@
+# The rows a link column may point to, for one row: what an agent or a picker offers before writing
+
+`POST /datanotes/operations/list_link_targets/` (operation `list_link_targets`)
+
+The rows a link column may point to, for one row: what an agent or a picker offers before writing
+the link. A link column can filter its targets:
+- `ref_where`: a `where` filter every target must match (`{"kind": {"in": ["area", "project"]}}`).
+- `ref_by`: a column of the row picks the targets' level: `{"column": "kind", "map": {"area": null,
+  "project": ["area"], "workstream": ["project"]}}`: a workstream's parent must have kind project; `null`
+  is a top level (the link must stay empty); any other level needs the link; a value missing from the
+  map is refused. `levels: ["area", "project", "workstream"]` writes the same chain short (each
+  level's parent is the level before it). `target_column` reads another column of the target
+  (default: the same name). describe_table shows the expanded map.
+Writes refuse other targets (code `ref`, listing the valid ones), a link to the row itself (`ref`),
+a link to no row of the table (`broken_link`) and a missing link a level needs (`required`). Pass the
+row (`row`: path, link or name; a name rows in different folders share is refused, listing their
+paths) and/or its values (`values`, e.g. `{"kind": "workstream"}` for a new row). Returns
+`{rows: [{name, link, path, <level column>}], total, required, empty, reason}` (no rows, and the
+reason, for a level the map lacks); write a row's `link` as the value.
+
+## Request body
+
+`application/json`, required
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `table` | `string` | yes |  |  |
+| `column` | `string` | yes |  | A link column (or list of links) with ref. |
+| `row` | `string \| null` | no | `null` | The row the link is for: its path, a link to it or its name (its values are read). |
+| `values` | `object \| null` | no | `null` | Values of the row (a new one, or changes to `row`), e.g. {"kind": "workstream"}. |
+| `limit` | `integer \| null` | no | `null` | At most this many targets: a positive integer (default 50, at most 500). |
+
+## 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/list_migrations.md

@@ -0,0 +1,35 @@
+# The operation journal, newest first: `total` (the matching operations) and `migrations`, each with
+
+`POST /datanotes/operations/list_migrations/` (operation `list_migrations`)
+
+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.
+
+## Request body
+
+`application/json`
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `limit` | `integer \| null` | no | `null` |  |
+| `op` | `string \| null` | no | `null` |  |
+| `table` | `string \| null` | no | `null` |  |
+| `since` | `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/list_tables.md

@@ -0,0 +1,32 @@
+# List every table: `name`, `catalog`, `schema`, `qualified` (`personal.metrics.mood` — use it
+
+`POST /datanotes/operations/list_tables/` (operation `list_tables`)
+
+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.
+
+## Request body
+
+`application/json`
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+
+## 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/list_webhooks.md

@@ -0,0 +1,23 @@
+# 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.
+
+`POST /datanotes/operations/list_webhooks/` (operation `list_webhooks`)
+
+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.
+
+## Request body
+
+`application/json`
+
+| Property | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+
+## 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/manual_index.md

@@ -0,0 +1,14 @@
+# 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.
+
+`GET /datanotes/manual/` (operation `manual_index`)
+
+## Responses
+
+| Status | Description | Body |
+| --- | --- | --- |
+| 200 | The index, in Markdown. | `string` (text/markdown) |
+| 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/manual_page.md

@@ -0,0 +1,22 @@
+# 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.
+
+`GET /datanotes/manual/{page}.md` (operation `manual_page`)
+
+## Parameters
+
+| Name | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `page` | path | `string` | yes | The page's path on the site, such as `guides/read-and-write/read-and-filter` (its `/` as is, or URL-encoded as %2F). |
+| `section` | query | `string` | no | The anchor of a section, such as `compare-values-with-operators`: only that section, with its subsections. |
+
+## Responses
+
+| Status | Description | Body |
+| --- | --- | --- |
+| 200 | The page or section. | `string` (text/markdown) |
+| 401 | Missing or wrong bearer token. | `Error` (application/json) |
+| 404 | No such page or section: `hint` names the closest ones. | `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/merge_rows.md

@@ -0,0 +1,44 @@
+# MERGE (upsert) `rows` into `table` by the key columns `on` (e.g. `["occurred_at"]` or
+
+`POST /datanotes/operations/merge_rows/` (operation `merge_rows`)
+
+MERGE (upsert) `rows` into `table` by the key columns `on` (e.g. `["occurred_at"]` or
+`["id"]`): a row matching an existing one updates it (`when_matched`: "update" default or
+"ignore"), the others are inserted (`when_not_matched`: "insert" default or "ignore").
+Date-times are compared after completion with the database time zone. A source key matching
+several rows, or repeated, is a conflict. One journaled, undoable operation.
+
+## 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 |  |  |
+| `on` | `string[]` | yes |  |  |
+| `rows` | `object[]` | yes |  |  |
+| `when_matched` | `"update" \| "ignore" \| null` | no | `null` |  |
+| `when_not_matched` | `"insert" \| "ignore" \| 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/move_rows.md

@@ -0,0 +1,52 @@
+# Move rows matching `where` (required: `{}` is every row) to another table (e.g. split a domain out of `log` into its own
+
+`POST /datanotes/operations/move_rows/` (operation `move_rows`)
+
+Move rows matching `where` (required: `{}` is every row) to another table (e.g. split a domain out of `log` into its own
+table): sets each row's `table` to the destination, applies `rename` (`{"metric_distance_km":
+"distance_km"}`), `set` and `drop`, adds the destination's missing dense fields, and
+validates every row against the destination first. Keys unknown to the destination are
+reported, never dropped silently — rename or drop them explicitly. `relocate: true` also moves
+the files to the destination table's folder (named by its filename pattern); by default rows stay where
+they are, as rows already in folders of their own usually do (adopt_rows, for notes that are no rows
+yet, moves them by default). Refused while rows
+staying behind link to a moved row through a column whose `ref` is the source table (the
+conflicts name them): change those links first. Undo with
+`undo_migration`.
+
+## 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 |  |  |
+| `to_table` | `string` | yes |  |  |
+| `where` | `object` | yes |  | The rows to change; {} is every row of the table. |
+| `rename` | `object \| null` | no | `null` |  |
+| `set` | `object \| null` | no | `null` |  |
+| `drop` | `string[] \| null` | no | `null` |  |
+| `relocate` | `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`).