datanotes 3.3.1 → 3.4.0

package/dist/docs/administration/extensions.md

@@ -111,7 +111,7 @@ Each extension gets a named token, `ext-<name>`. The token has three limits:
 
 * It writes only the tables of the roles in the manifest’s `permissions.write`.
 * It never changes the schema and never undoes. The installer changes the schema with the owner’s token.
-* It reads every table, like every named token today.
+* It reads every table: the installer gives it no `read` patterns. You may limit it, as [Limit what a token can read](https://datanotes.dev/guides/security/tokens/#change-what-a-token-reads) shows.
 
 The tools of an extension run when an agent calls them. Before a tool that writes runs, the MCP server checks the agent’s own token. If that token may not write the tool’s tables, the call fails. A read-only client cannot write through an extension. To allow the call, add the table to the `write` patterns of the client’s token. Or call the tool with a token that may write.
 
@@ -127,7 +127,7 @@ The code runs inside the MCP server’s process. It is trusted code, not a sandb
 Known limits in this version:
 
 * **No isolation.** Extension code has the privileges of the MCP server’s process.
-* **No read-scoped tokens.** The token of an extension reads every table. When read patterns ship, the installer will limit it to the extension’s tables.
+* **No read patterns from the installer.** The token of an extension reads every table. If you limit its `read`, cover the tables it writes. An install or update that writes a table outside `read` is refused with 400: widen `read` first.
 * **No data-converting migrations.** A migration lists operations. It cannot run code to convert rows.
 
 ## Update an extension

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

@@ -12,6 +12,7 @@ a column whose meaning an existing column (name/label/aliases/description) alrea
 Column names are permanent identifiers; only `rename_column` changes them.
 Enum columns: `values` and, for each, its meaning in `value_descriptions` (`{"stated": "the user said it", …}`): describe_table shows them and a refused value lists them.
 Generated link columns: `generated: "link({occurred_at:YYYY-MM-DD})"` with `ref` = the days table links each row to the row of `ref` named by the template (its folder read from the schema; the target may not exist yet).
+Generated aggregates of a json column holding a list of objects (integer or number columns; avg: number): `count(feeds)`, `count(feeds.min)` (the items with a min), `sum(feeds.min)`, `avg(…)`, `min(…)`, `max(…)`, with an optional filter on one field: `count(feeds, side = "left")`, `sum(feeds.min, min > 0)` (=, !=, <, <=, >, >=; "text", a number, true or false). Recomputed on every write; no list: count and sum 0, avg/min/max empty; a field that is not a number: empty.
 Filtered link targets (link columns): `ref_where` (a `where` every target must match) and `ref_by` (a column of the row picks the target level: `{"column": "kind", "levels": ["area", "project", "workstream"]}` or `{"column": "kind", "map": {"area": null, "project": ["area"]}}`; null = top level, no link; `target_column` when the target names it differently: an enum target column must have every value the map allows, a string one takes any value). A link to no row of the table, or to the row itself, is refused too. Existing rows that break them refuse the change; `list_link_targets` lists the valid targets of a row.
 Acyclic links: `acyclic: true` on a link (or list of links) to the table itself refuses every write that closes a cycle, on either side of an `inverse`; refused while existing rows form one (they are listed).
 

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

@@ -22,6 +22,7 @@ columns, CHECK constraints, those that follow links included, filtered link targ
 | 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 whose `read` patterns do not cover the table, view or note the request names (such as `token cook may not read personal.health.weight`). Sets it did not name (listings, bases, search, the graph, the change feed) are filtered instead. | `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) |

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

@@ -30,6 +30,7 @@ digits, `_` (no dots: pass the catalog and the schema as their own arguments).
   describe_table return them, alter_table changes them.
 Enum columns: `values` and, for each, its meaning in `value_descriptions` (`{"stated": "the user said it", …}`): describe_table shows them and a refused value lists them.
 Generated link columns: `generated: "link({occurred_at:YYYY-MM-DD})"` with `ref` = the days table links each row to the row of `ref` named by the template (its folder read from the schema; the target may not exist yet).
+Generated aggregates of a json column holding a list of objects (integer or number columns; avg: number): `count(feeds)`, `count(feeds.min)` (the items with a min), `sum(feeds.min)`, `avg(…)`, `min(…)`, `max(…)`, with an optional filter on one field: `count(feeds, side = "left")`, `sum(feeds.min, min > 0)` (=, !=, <, <=, >, >=; "text", a number, true or false). Recomputed on every write; no list: count and sum 0, avg/min/max empty; a field that is not a number: empty.
 Filtered link targets (link columns): `ref_where` (a `where` every target must match) and `ref_by` (a column of the row picks the target level: `{"column": "kind", "levels": ["area", "project", "workstream"]}` or `{"column": "kind", "map": {"area": null, "project": ["area"]}}`; null = top level, no link; `target_column` when the target names it differently: an enum target column must have every value the map allows, a string one takes any value). A link to no row of the table, or to the row itself, is refused too. Existing rows that break them refuse the change; `list_link_targets` lists the valid targets of a row.
 
 The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).

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

@@ -10,6 +10,7 @@ journal folder, `bases` (shared column sets and the tables using them), `catalog
 catalogs and schemas show their `comment` (set with `comment_on`). A table or base defined before
 descriptions were required has `missing_descriptions`: what lacks one, for alter_table / alter_column
 (define_base for a base) to fill, so every table and column says what it holds.
+A token with `read` patterns sees only the tables, views and bases it may read.
 
 ## Request body
 
@@ -25,6 +26,7 @@ descriptions were required has `missing_descriptions`: what lacks one, for alter
 | 200 | Done. | `DatabaseDescription` (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 whose `read` patterns do not cover the table, view or note the request names (such as `token cook may not read personal.health.weight`). Sets it did not name (listings, bases, search, the graph, the change feed) are filtered instead. | `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/describe_history.md

@@ -33,6 +33,7 @@ from it (`timestamp`, or `before_migration` with a `migration_id` or a `batch`).
 | 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 whose `read` patterns do not cover the table, view or note the request names (such as `token cook may not read personal.health.weight`). Sets it did not name (listings, bases, search, the graph, the change feed) are filtered instead. | `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) |

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

@@ -19,6 +19,7 @@ The semantic search index: `enabled`, `provider`, `model`, `files`, `passages`,
 | 200 | Done. | `SemanticStatus` (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 whose `read` patterns do not cover the table, view or note the request names (such as `token cook may not read personal.health.weight`). Sets it did not name (listings, bases, search, the graph, the change feed) are filtered instead. | `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/describe_table.md

@@ -31,6 +31,7 @@ defined before descriptions were required), names what lacks one: write them wit
 | 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 whose `read` patterns do not cover the table, view or note the request names (such as `token cook may not read personal.health.weight`). Sets it did not name (listings, bases, search, the graph, the change feed) are filtered instead. | `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) |

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

@@ -27,6 +27,7 @@ start notes). Edges are labelled with their link column (`people`, `event`, …)
 | 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 whose `read` patterns do not cover the table, view or note the request names (such as `token cook may not read personal.health.weight`). Sets it did not name (listings, bases, search, the graph, the change feed) are filtered instead. | `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) |

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

@@ -25,6 +25,7 @@ and/or `{"tables": [...]}`): `found`, `length` and `path`: the steps (`from`, `l
 | 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 whose `read` patterns do not cover the table, view or note the request names (such as `token cook may not read personal.health.weight`). Sets it did not name (listings, bases, search, the graph, the change feed) are filtered instead. | `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) |

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

@@ -36,6 +36,7 @@ with Alice: from `{"table": "person", "where": {"name": "Alice"}}`, direction `i
 | 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 whose `read` patterns do not cover the table, view or note the request names (such as `token cook may not read personal.health.weight`). Sets it did not name (listings, bases, search, the graph, the change feed) are filtered instead. | `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) |

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

@@ -36,6 +36,7 @@ distinct values (default 12), each used twice on average, short texts.
 | 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 whose `read` patterns do not cover the table, view or note the request names (such as `token cook may not read personal.health.weight`). Sets it did not name (listings, bases, search, the graph, the change feed) are filtered instead. | `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) |

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

@@ -30,6 +30,7 @@ older changes were dropped: re-read the tables. `where` filters rows as in selec
 | 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 whose `read` patterns do not cover the table, view or note the request names (such as `token cook may not read personal.health.weight`). Sets it did not name (listings, bases, search, the graph, the change feed) are filtered instead. | `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

@@ -21,6 +21,7 @@ error.
 | 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 whose `read` patterns do not cover the table, view or note the request names (such as `token cook may not read personal.health.weight`). Sets it did not name (listings, bases, search, the graph, the change feed) are filtered instead. | `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) |

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

@@ -37,6 +37,7 @@ reason, for a level the map lacks); write a row's `link` as the value.
 | 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 whose `read` patterns do not cover the table, view or note the request names (such as `token cook may not read personal.health.weight`). Sets it did not name (listings, bases, search, the graph, the change feed) are filtered instead. | `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) |

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

@@ -28,6 +28,7 @@ engine's store, outside the vault (`store:journal/`); entries older than 90 days
 | 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 whose `read` patterns do not cover the table, view or note the request names (such as `token cook may not read personal.health.weight`). Sets it did not name (listings, bases, search, the graph, the change feed) are filtered instead. | `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) |

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

@@ -8,6 +8,7 @@ when declared, `description`, `aliases` (other words for what it records) and `t
 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`.
+A token with `read` patterns sees only the tables and views it may read.
 
 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
@@ -27,6 +28,7 @@ ones instead of creating duplicates.
 | 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 whose `read` patterns do not cover the table, view or note the request names (such as `token cook may not read personal.health.weight`). Sets it did not name (listings, bases, search, the graph, the change feed) are filtered instead. | `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

@@ -18,6 +18,7 @@ Webhooks of the change feed: id, url, filter (tables, ops, columns, exclude_acto
 | 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 whose `read` patterns do not cover the table, view or note the request names (such as `token cook may not read personal.health.weight`). Sets it did not name (listings, bases, search, the graph, the change feed) are filtered instead. | `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

@@ -22,6 +22,7 @@ an error. `path`: vault-relative, forward slashes.
 | 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 whose `read` patterns do not cover the table, view or note the request names (such as `token cook may not read personal.health.weight`). Sets it did not name (listings, bases, search, the graph, the change feed) are filtered instead. | `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) |

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

@@ -0,0 +1,39 @@
+# Search the notes by their words and, when semantic search is on, by their meaning:
+
+`POST /datanotes/operations/search/` (operation `search`)
+
+Search the notes by their words and, when semantic search is on, by their meaning:
+`{query, results: [{path, table?, score, heading, snippet, matched_by}], meaning}`, one result per
+note, best first. It always works: with semantic search off it ranks by words alone (BM25:
+rare words count more; a word in the note's name or properties counts more), with it on it fuses
+both rankings (Reciprocal Rank Fusion), so a note found only by its words or only by its meaning
+is still there. `matched_by` says which (`words`, `meaning`); `meaning` is `on`, `off` or `failed`
+(the embedding provider failed: words only, `meaning_error` says why). Query syntax as search_docs:
+`"a phrase"` and `+word` must appear, `-word` must not (both rankings); words in any language,
+case and accents ignored, no stemming. Filters: `tables` (qualified or short names), `folder`,
+`min_score` (the meaning ranking's cosine floor). `limit`: default 10, max 100. Then read_note /
+select_rows for the details.
+
+## 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) |
+| 403 | A named token whose `read` patterns do not cover the table, view or note the request names (such as `token cook may not read personal.health.weight`). Sets it did not name (listings, bases, search, the graph, the change feed) are filtered instead. | `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/search_notes.md

@@ -23,6 +23,7 @@ matches per note. `context_length`: characters of context on each side (default
 | 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 whose `read` patterns do not cover the table, view or note the request names (such as `token cook may not read personal.health.weight`). Sets it did not name (listings, bases, search, the graph, the change feed) are filtered instead. | `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

@@ -54,6 +54,7 @@ on the base's columns, each row tagged `_source` with its table.
 | 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 whose `read` patterns do not cover the table, view or note the request names (such as `token cook may not read personal.health.weight`). Sets it did not name (listings, bases, search, the graph, the change feed) are filtered instead. | `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) |

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

@@ -29,6 +29,7 @@ the engine settings.
 | 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 whose `read` patterns do not cover the table, view or note the request names (such as `token cook may not read personal.health.weight`). Sets it did not name (listings, bases, search, the graph, the change feed) are filtered instead. | `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

@@ -24,6 +24,7 @@ Use it to answer "what changed since …" without diffing full tables.
 | 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 whose `read` patterns do not cover the table, view or note the request names (such as `token cook may not read personal.health.weight`). Sets it did not name (listings, bases, search, the graph, the change feed) are filtered instead. | `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) |

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

@@ -10,6 +10,7 @@ Operations that read rows and notes: select_rows, link targets, text and semanti
 - [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/`
+- [Search the notes by their words and, when semantic search is on, by their meaning:](https://datanotes.dev/api/operations/search/): `POST /datanotes/operations/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": [...]}`, `{"table", "where"}` and/or `{"tables": [...]}`).](https://datanotes.dev/api/operations/graph_traverse/): `POST /datanotes/operations/graph_traverse/`
 - [Shortest chain of links between two sets of notes (each `{"paths": [...]}`, `{"table", "where"}`](https://datanotes.dev/api/operations/graph_path/): `POST /datanotes/operations/graph_path/`

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

@@ -8,6 +8,6 @@ Named tokens and their permissions; what MCP servers report about their agents'
 - [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/`
+- [Change a named token. A token may change its own description and autolink default; permissions (`read`, `write`, `ddl`, `maintain`) 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

@@ -16,6 +16,7 @@
 | --- | --- | --- | --- | --- |
 | `name` | `string` | yes |  | Kebab-case; the journal records it as `auth`. `owner` is reserved. |
 | `description` | `string` | no |  |  |
+| `read` | `string[]` | no |  | Tables the token may read, as patterns like `write`'s. Absent (or with `*`): every table. It must cover every `write` pattern, and stay absent with `ddl` or `maintain` (400 otherwise). |
 | `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.) |

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

@@ -1,4 +1,4 @@
-# Change a named token. A token may change its own description and autolink default; permissions are the owner's.
+# Change a named token. A token may change its own description and autolink default; permissions (`read`, `write`, `ddl`, `maintain`) are the owner's.
 
 `POST /datanotes/tokens/update/` (operation `tokens_update`)
 
@@ -16,6 +16,7 @@
 | --- | --- | --- | --- | --- |
 | `name` | `string` | no |  | Owner only (a named token updates itself). |
 | `description` | `string` | no |  | An empty string removes it. |
+| `read` | `array \| null` | no |  | The tables the token may read; null reads every table again. Checked against `write`, `ddl` and `maintain` as on create. |
 | `write` | `string[]` | no |  |  |
 | `ddl` | `boolean` | no |  |  |
 | `maintain` | `boolean` | no |  |  |

package/dist/docs/api.md

@@ -1,16 +1,16 @@
 # Datanotes HTTP API
 
-> OpenAPI 3.1.0 description of the Datanotes 3.3.1 HTTP API: https://datanotes.dev/openapi.json
+> OpenAPI 3.1.0 description of the Datanotes 3.4.0 HTTP API: https://datanotes.dev/openapi.json
 
 Database of Markdown notes: tables of notes, rows, queries, history, a change feed and the vault's notes.
 
 **Operations**: every operation is `POST /datanotes/operations/<name>/`, its body the operation's arguments (the same names as the MCP tool of the same name). An unknown argument is refused (400) with the closest real one.
 
-**Authentication**: every route but `GET /`, this document and `/datanotes/docs` needs `Authorization: Bearer <token>`: the owner's token (`httpServerToken` in the settings: everything) or a named token (`/datanotes/tokens/create/`: reads everything; writes the tables in its `write` patterns, changes the schema with `ddl`; the engine's administration stays the owner's: 403 otherwise).
+**Authentication**: every route but `GET /`, this document and `/datanotes/docs` needs `Authorization: Bearer <token>`: the owner's token (`httpServerToken` in the settings: everything) or a named token (`/datanotes/tokens/create/`: reads the tables in its `read` patterns, every table without them; writes the tables in its `write` patterns, changes the schema with `ddl`; the engine's administration stays the owner's: 403 otherwise).
 
 **Actor**: send `X-Datanotes-Actor: {"harness": …, "model": …, "session": …}` (JSON) to record on whose behalf a write is made; the journal adds the credential (`auth`: `owner`, or the named token's name), which the client cannot claim.
 
-**Errors**: `{error}` with 400 (bad input), 401 (missing or wrong token), 403 (a named token beyond its permissions), 404 (unknown table, view, migration or note), 409 (ambiguous table name), 500. A refused write answers 422 (409 for undo) with the operation's result, `ok: false`: nothing was written.
+**Errors**: `{error}` with 400 (bad input), 401 (missing or wrong token), 403 (a named token beyond its permissions, or a read of a table outside its `read` patterns), 404 (unknown table, view, migration or note), 409 (ambiguous table name), 500. A refused write answers 422 (409 for undo) with the operation's result, `ok: false`: nothing was written.
 
 ## Servers
 
@@ -68,6 +68,7 @@ Operations that read rows and notes: select_rows, link targets, text and semanti
 - [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/`
+- [Search the notes by their words and, when semantic search is on, by their meaning:](https://datanotes.dev/api/operations/search/): `POST /datanotes/operations/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": [...]}`, `{"table", "where"}` and/or `{"tables": [...]}`).](https://datanotes.dev/api/operations/graph_traverse/): `POST /datanotes/operations/graph_traverse/`
 - [Shortest chain of links between two sets of notes (each `{"paths": [...]}`, `{"table", "where"}`](https://datanotes.dev/api/operations/graph_path/): `POST /datanotes/operations/graph_path/`
@@ -116,7 +117,7 @@ Named tokens and their permissions; what MCP servers report about their agents'
 - [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/`
+- [Change a named token. A token may change its own description and autolink default; permissions (`read`, `write`, `ddl`, `maintain`) 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/develop/build-an-app.md

@@ -64,13 +64,14 @@ The app has four small files in `src/`: the client, the films, the change feed a
    console.log(r.token);
    ```
 
-   The token can read every table, and write rows of `watch` and `film` only. It can’t change the schema, undo, or touch `actor`. The engine lists it like this:
+   The request passes no `read`, so the token can read every table. It writes rows of `watch` and `film` only. It can’t change the schema, undo, or touch `actor`. The engine lists it like this:
 
    ```json
    {
      "name": "film-night",
      "description": "Logs film nights and picks the next film",
      "write": ["main.public.watch", "main.public.film"],
+     "read": ["*"],
      "ddl": false
    }
    ```

package/dist/docs/develop/change-feed-and-webhooks.md

@@ -67,4 +67,4 @@ A 2xx answer moves the webhook on. Any other answer is retried with backoff, fro
 
 ## Choose the feed or a webhook
 
-A named token can read the feed, while only the owner creates webhooks. So a program with its own token long-polls or streams the feed, as [Build an app on Datanotes](https://datanotes.dev/develop/build-an-app/) does, and a service the owner sets up receives a webhook.
+A named token can read the feed, while only the owner creates webhooks. So a program with its own token long-polls or streams the feed, as [Build an app on Datanotes](https://datanotes.dev/develop/build-an-app/) does, and a service the owner sets up receives a webhook. A token with `read` patterns sees only the events of its readable tables, and only its own tool calls.

package/dist/docs/develop/http-api.md

@@ -58,7 +58,7 @@ Errors come back as JSON `{"error": "…", "hint": "…", "docs": "…"}`: what
 
 * **400**: bad input
 * **401**: missing or wrong token
-* **403**: a named token beyond its permissions
+* **403**: a named token beyond its permissions, such as a table outside its `read` or `write` patterns
 * **404**: unknown table, view, migration or note
 * **409**: ambiguous table name
 * **500**: an unexpected error, or a write that failed partway and couldn’t be [rolled back](https://datanotes.dev/guides/history/journal-and-undo/#the-engine-rolls-back-a-write-it-cannot-finish)

package/dist/docs/guides/data-quality/check-constraints.md

@@ -29,7 +29,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.film", "version": 8, "operation": "ADD CONSTRAINT" }
   ],
-  "migration_id": "20261024T053837-add_constraint-add-constraint-rated_when_watc"
+  "migration_id": "20261024T063921-add_constraint-add-constraint-rated_when_watc"
 }
 ```
 
@@ -86,7 +86,7 @@ Answer:
   "files_created": 1,
   "planned_creates": ["datanotes/diary/classics/film/His Girl Friday.md"],
   "commits": [{ "table": "diary.classics.film", "version": 10, "operation": "WRITE" }],
-  "migration_id": "20261024T053837-insert_row-insert-into-film-2"
+  "migration_id": "20261024T063921-insert_row-insert-into-film"
 }
 ```
 
@@ -108,7 +108,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.film", "version": 11, "operation": "DROP CONSTRAINT" }
   ],
-  "migration_id": "20261024T053837-drop_constraint-drop-constraint-at_most_three_"
+  "migration_id": "20261024T063921-drop_constraint-drop-constraint-at_most_three_"
 }
 ```
 
@@ -149,7 +149,7 @@ Answer:
   "commits": [
     { "table": "main.public.genre", "version": 4, "operation": "ADD CONSTRAINT" }
   ],
-  "migration_id": "20261024T053821-add_constraint-add-constraint-parent_by_level"
+  "migration_id": "20261024T063906-add_constraint-add-constraint-parent_by_level"
 }
 ```
 
@@ -228,34 +228,34 @@ Answer:
   "ok": true,
   "op": "batch",
   "dry_run": false,
-  "migration_id": "20261024T053821-batch-add-the-silent-era-and-slapsti",
+  "migration_id": "20261024T063906-batch-add-the-silent-era-and-slapsti",
   "steps": [
     {
       "index": 0,
       "op": "insert_row",
       "ok": true,
-      "migration_id": "20261024T053821-insert_row-insert-into-genre-4",
+      "migration_id": "20261024T063906-insert_row-insert-into-genre",
       "result": {
         "ok": true,
         "op": "insert_row",
         "files_created": 1,
         "planned_creates": ["datanotes/main/public/genre/Silent cinema.md"],
         "commits": [{ "table": "main.public.genre", "version": 5, "operation": "WRITE" }],
-        "migration_id": "20261024T053821-insert_row-insert-into-genre-4"
+        "migration_id": "20261024T063906-insert_row-insert-into-genre"
       }
     },
     {
       "index": 1,
       "op": "insert_row",
       "ok": true,
-      "migration_id": "20261024T053821-insert_row-insert-into-genre-5",
+      "migration_id": "20261024T063906-insert_row-insert-into-genre-2",
       "result": {
         "ok": true,
         "op": "insert_row",
         "files_created": 1,
         "planned_creates": ["datanotes/main/public/genre/Slapstick comedy.md"],
         "commits": [{ "table": "main.public.genre", "version": 6, "operation": "WRITE" }],
-        "migration_id": "20261024T053821-insert_row-insert-into-genre-5"
+        "migration_id": "20261024T063906-insert_row-insert-into-genre-2"
       }
     }
   ]
@@ -343,7 +343,7 @@ Answer:
     }
   ],
   "commits": [{ "table": "main.public.genre", "version": 7, "operation": "UPDATE" }],
-  "migration_id": "20261024T053821-update_row-update-genre"
+  "migration_id": "20261024T063906-update_row-update-genre"
 }
 ```
 

package/dist/docs/guides/data-quality/hand-edits.md

@@ -35,7 +35,7 @@ You edit `datanotes/main/public/genre/Silent film.md` by hand, outside the engin
 ```markdown
 ---
 table: main.public.genre
-id: 01a16c6a-d02a-78b2-b025-40ae0348957b
+id: 01a16ca2-6b55-78e6-a355-a9890248c59d
 name: Silent film
 kind: cinema
 parent: "[[Cinema]]"
@@ -152,7 +152,7 @@ Answer:
     }
   ],
   "commits": [{ "table": "main.public.genre", "version": 9, "operation": "UPDATE" }],
-  "migration_id": "20261024T053823-update_row-update-genre"
+  "migration_id": "20261024T063907-update_row-update-genre"
 }
 ```
 
@@ -167,7 +167,7 @@ You edit `datanotes/main/public/watch/2026-10-03T2130.md` by hand, outside the e
 ```markdown
 ---
 table: main.public.watch
-id: 01a16c6a-c91c-75d4-af58-f40270afa72e
+id: 01a16ca2-6327-778b-85f9-d586c0c733a8
 film: His Girl Friday
 occurred_at: 2026-10-03T21:30
 where: cinema
@@ -226,7 +226,7 @@ Answer:
     }
   ],
   "commits": [{ "table": "main.public.watch", "version": 3, "operation": "RECOMPUTE" }],
-  "migration_id": "20261024T053821-recompute_columns-recompute-id-day-label-of-watc"
+  "migration_id": "20261024T063905-recompute_columns-recompute-id-day-label-of-watc"
 }
 ```
 
@@ -292,7 +292,7 @@ Answer:
 ```markdown
 ---
 table: main.public.watch
-id: 01a16c6b-31f3-71ea-805b-9a972bd80279
+id: 01a16ca2-ca05-74ee-97ba-2dcfcbb41703
 occurred_at: 2026-09-25T21:00
 film: "[[Charade]]"
 where: home
@@ -311,7 +311,7 @@ You edit `datanotes/main/public/film/Metropolis.md` by hand, outside the engine.
 ```markdown
 ---
 table: main.public.film
-id: 01a16c6a-f3db-73dd-9ca7-c1c2c0456765
+id: 01a16ca2-8b18-71f0-92e4-4e2492953fa5
 year: 1927
 minutes: 153
 status: to watch
@@ -384,7 +384,7 @@ You edit `datanotes/main/public/film/Sherlock Jr..md` by hand, outside the engin
 ```markdown
 ---
 table: main.public.film
-id: 01a16c6a-d660-7ca7-ab67-0e0e1c2d096a
+id: 01a16ca2-719a-7e26-8d8b-e4471d2b154f
 title: Sherlock Jr.: the projectionist
 year: 1924
 status: watched
@@ -471,7 +471,7 @@ You edit `datanotes/main/public/film/Sherlock Jr..md` by hand, outside the engin
 ```markdown
 ---
 table: main.public.film
-id: 01a16c6a-d660-7ca7-ab67-0e0e1c2d096a
+id: 01a16ca2-719a-7e26-8d8b-e4471d2b154f
 title: "Sherlock Jr.: the projectionist"
 year: 1924
 status: watched