datanotes 3.3.1 → 3.4.0

package/dist/docs/guides/read-and-write/automatic-links.md

@@ -98,7 +98,7 @@ Answer:
   "files_created": 1,
   "planned_creates": ["datanotes/main/public/film/Charade.md"],
   "commits": [{ "table": "main.public.film", "version": 2, "operation": "WRITE" }],
-  "migration_id": "20261024T053829-insert_row-insert-into-film-2",
+  "migration_id": "20261024T063913-insert_row-insert-into-film-2",
   "links_added": [
     {
       "path": "datanotes/main/public/film/Charade.md",
@@ -127,7 +127,7 @@ Answer:
 ```markdown
 ---
 table: main.public.film
-id: 01a16c6a-ef34-786c-8a16-70940d66ab4d
+id: 01a16ca2-86d8-79ee-89ef-e5a776a8d6b7
 title: Charade
 year: 1963
 ---
@@ -169,7 +169,7 @@ Answer:
     }
   ],
   "commits": [{ "table": "main.public.film", "version": 3, "operation": "UPDATE" }],
-  "migration_id": "20261024T053829-update_row-update-film",
+  "migration_id": "20261024T063913-update_row-update-film",
   "links_added": [
     {
       "path": "datanotes/main/public/film/Charade.md",
@@ -186,7 +186,7 @@ Answer:
 ```markdown
 ---
 table: main.public.film
-id: 01a16c6a-ef34-786c-8a16-70940d66ab4d
+id: 01a16ca2-86d8-79ee-89ef-e5a776a8d6b7
 title: Charade
 year: 1963
 ---
@@ -229,7 +229,7 @@ Answer:
     }
   ],
   "commits": [{ "table": "main.public.film", "version": 4, "operation": "UPDATE" }],
-  "migration_id": "20261024T053830-update_row-update-film",
+  "migration_id": "20261024T063913-update_row-update-film-2",
   "links_added": [
     {
       "path": "datanotes/main/public/film/Notorious.md",
@@ -287,7 +287,7 @@ Answer:
     }
   ],
   "commits": [{ "table": "main.public.film", "version": 5, "operation": "UPDATE" }],
-  "migration_id": "20261024T053830-update_row-update-film-2",
+  "migration_id": "20261024T063913-update_row-update-film-3",
   "links_added": [
     {
       "path": "datanotes/main/public/film/Notorious.md",
@@ -310,7 +310,7 @@ Answer:
 ```markdown
 ---
 table: main.public.film
-id: 01a16c6a-ee8a-7114-9ab1-7733fe30087c
+id: 01a16ca2-86cb-7322-8189-f01f3c6119a3
 title: Notorious
 year: 1946
 ---
@@ -373,7 +373,7 @@ Answer:
   "files_created": 1,
   "planned_creates": ["datanotes/main/public/film/Persona.md"],
   "commits": [{ "table": "main.public.film", "version": 6, "operation": "WRITE" }],
-  "migration_id": "20261024T053830-insert_row-insert-into-film",
+  "migration_id": "20261024T063913-insert_row-insert-into-film-3",
   "links_added": [
     {
       "path": "datanotes/main/public/film/Persona.md",
@@ -390,7 +390,7 @@ Answer:
 ```markdown
 ---
 table: main.public.film
-id: 01a16c6a-f25c-707a-b5aa-8f4b2499198f
+id: 01a16ca2-87b5-7b97-9da8-c6fa7447798b
 title: Persona
 year: 1966
 ---
@@ -472,7 +472,7 @@ Answer:
     }
   ],
   "commits": [{ "table": "main.public.film", "version": 7, "operation": "UPDATE" }],
-  "migration_id": "20261024T053830-update_row-update-film-3",
+  "migration_id": "20261024T063913-update_row-update-film-4",
   "links_added": [
     {
       "path": "datanotes/main/public/film/Persona.md",
@@ -489,7 +489,7 @@ Answer:
 ```markdown
 ---
 table: main.public.film
-id: 01a16c6a-f25c-707a-b5aa-8f4b2499198f
+id: 01a16ca2-87b5-7b97-9da8-c6fa7447798b
 title: Persona
 year: 1966
 ---
@@ -505,7 +505,7 @@ We watched it at [[2026-10-09T2100|Swedish night]].
 
 ```yaml
 # Metastore (Datanotes): catalogs, schemas, tables, columns, views.
-id: 01a16c6a-e9ae-7998-8aa6-0918b4ce87d7
+id: 01a16ca2-8469-7992-baf9-477d38fdf2ed
 config:
   history: true
 
@@ -620,7 +620,7 @@ Answer:
   "files_created": 1,
   "planned_creates": ["datanotes/main/public/film/His Girl Friday.md"],
   "commits": [{ "table": "main.public.film", "version": 8, "operation": "WRITE" }],
-  "migration_id": "20261024T053830-insert_row-insert-into-film-2"
+  "migration_id": "20261024T063913-insert_row-insert-into-film-4"
 }
 ```
 
@@ -629,7 +629,7 @@ Answer:
 ```markdown
 ---
 table: main.public.film
-id: 01a16c6a-f278-7de9-8d9d-2ea9726437f4
+id: 01a16ca2-880e-7cef-83a8-5888eb8601d0
 title: His Girl Friday
 year: 1940
 ---
@@ -663,7 +663,7 @@ Answer:
 
 ```yaml
 # Metastore (Datanotes): catalogs, schemas, tables, columns, views.
-id: 01a16c6a-e9ae-7998-8aa6-0918b4ce87d7
+id: 01a16ca2-8469-7992-baf9-477d38fdf2ed
 config:
   history: true
   autolink: false

package/dist/docs/guides/read-and-write/import-notes.md

@@ -314,7 +314,7 @@ Answer:
   "op": "create_table",
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [{ "table": "main.public.film", "version": 0, "operation": "CREATE TABLE" }],
-  "migration_id": "20261024T053830-create_table-create-table-main-public-film"
+  "migration_id": "20261024T063914-create_table-create-table-main-public-film"
 }
 ```
 
@@ -359,7 +359,7 @@ Answer (70 lines)
       "path": "Films/Charade.md",
       "set": {
         "table": "main.public.film",
-        "id": "01a16c6a-f3d8-7a71-935b-e3cdd49c2cec",
+        "id": "01a16ca2-8b15-7b17-9621-47ebd428dcb2",
         "director": "Stanley Donen",
         "title": "Charade"
       },
@@ -369,7 +369,7 @@ Answer (70 lines)
       "path": "Films/His Girl Friday.md",
       "set": {
         "table": "main.public.film",
-        "id": "01a16c6a-f3d8-7b3a-a052-76112f5037b7",
+        "id": "01a16ca2-8b15-736e-b2e9-b44812311845",
         "director": "Howard Hawks",
         "title": "His Girl Friday"
       },
@@ -379,7 +379,7 @@ Answer (70 lines)
       "path": "Films/Metropolis.md",
       "set": {
         "table": "main.public.film",
-        "id": "01a16c6a-f3d8-7dda-93e2-1ad75dd46ee2",
+        "id": "01a16ca2-8b16-7de3-b3c7-f99fea697aef",
         "director": "Fritz Lang",
         "title": "Metropolis"
       },
@@ -389,7 +389,7 @@ Answer (70 lines)
       "path": "Films/Nosferatu.md",
       "set": {
         "table": "main.public.film",
-        "id": "01a16c6a-f3d8-7b11-bdee-5230b4678352",
+        "id": "01a16ca2-8b16-7f5e-a304-e715a1815b66",
         "director": "F. W. Murnau",
         "title": "Nosferatu"
       },
@@ -399,7 +399,7 @@ Answer (70 lines)
       "path": "Films/The Gold Rush.md",
       "set": {
         "table": "main.public.film",
-        "id": "01a16c6a-f3d8-71bc-a2b9-70a1be84f56f",
+        "id": "01a16ca2-8b16-747f-9e49-aefd3f27fd58",
         "director": "Charlie Chaplin",
         "title": "The Gold Rush"
       },
@@ -458,7 +458,7 @@ Answer (73 lines)
       "path": "Films/Charade.md",
       "set": {
         "table": "main.public.film",
-        "id": "01a16c6a-f3db-705d-a092-d386d6b8d680",
+        "id": "01a16ca2-8b18-7e55-9cbc-a983a43ae96c",
         "director": "Stanley Donen",
         "title": "Charade"
       },
@@ -468,7 +468,7 @@ Answer (73 lines)
       "path": "Films/His Girl Friday.md",
       "set": {
         "table": "main.public.film",
-        "id": "01a16c6a-f3db-7ce9-9b15-ffdf1d9e94f9",
+        "id": "01a16ca2-8b18-739c-9058-e32e9f3a61d4",
         "director": "Howard Hawks",
         "title": "His Girl Friday"
       },
@@ -478,7 +478,7 @@ Answer (73 lines)
       "path": "Films/Metropolis.md",
       "set": {
         "table": "main.public.film",
-        "id": "01a16c6a-f3db-73dd-9ca7-c1c2c0456765",
+        "id": "01a16ca2-8b18-71f0-92e4-4e2492953fa5",
         "director": "Fritz Lang",
         "title": "Metropolis"
       },
@@ -488,7 +488,7 @@ Answer (73 lines)
       "path": "Films/Nosferatu.md",
       "set": {
         "table": "main.public.film",
-        "id": "01a16c6a-f3db-7a47-8726-24e829d99493",
+        "id": "01a16ca2-8b18-78be-9435-87eca4fa962e",
         "director": "F. W. Murnau",
         "title": "Nosferatu"
       },
@@ -498,7 +498,7 @@ Answer (73 lines)
       "path": "Films/The Gold Rush.md",
       "set": {
         "table": "main.public.film",
-        "id": "01a16c6a-f3db-77f9-a8b3-30bb65a6cc26",
+        "id": "01a16ca2-8b18-76bd-b55f-ba6aadec67b1",
         "director": "Charlie Chaplin",
         "title": "The Gold Rush"
       },
@@ -519,7 +519,7 @@ Answer (73 lines)
     }
   ],
   "commits": [{ "table": "main.public.film", "version": 1, "operation": "ADOPT ROWS" }],
-  "migration_id": "20261024T053831-adopt_rows-adopt-5-notes-into-film"
+  "migration_id": "20261024T063914-adopt_rows-adopt-5-notes-into-film"
 }
 ```
 
@@ -536,7 +536,7 @@ Answer:
 ```markdown
 ---
 table: main.public.film
-id: 01a16c6a-f3db-705d-a092-d386d6b8d680
+id: 01a16ca2-8b18-7e55-9cbc-a983a43ae96c
 year: 1963
 minutes: 113
 status: watched
@@ -623,7 +623,7 @@ Answer:
   "files_created": 1,
   "planned_creates": ["datanotes/main/public/film/Battleship Potemkin.md"],
   "commits": [{ "table": "main.public.film", "version": 2, "operation": "WRITE" }],
-  "migration_id": "20261024T053831-insert_row-insert-into-film"
+  "migration_id": "20261024T063914-insert_row-insert-into-film"
 }
 ```
 
@@ -655,7 +655,7 @@ Answer:
   "op": "add_column",
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [{ "table": "main.public.film", "version": 4, "operation": "ADD COLUMNS" }],
-  "migration_id": "20261024T053832-add_column-add-column-added_by-to-film"
+  "migration_id": "20261024T063915-add_column-add-column-added_by-to-film"
 }
 ```
 
@@ -683,7 +683,7 @@ Answer:
   "files_created": 1,
   "planned_creates": ["datanotes/main/public/film/Night of the Living Dead.md"],
   "commits": [{ "table": "main.public.film", "version": 5, "operation": "WRITE" }],
-  "migration_id": "20261024T053832-insert_row-insert-into-film"
+  "migration_id": "20261024T063915-insert_row-insert-into-film"
 }
 ```
 
@@ -692,7 +692,7 @@ Answer:
 ```markdown
 ---
 table: main.public.film
-id: 01a16c6a-f9d0-7e20-8311-52386a251707
+id: 01a16ca2-915b-736c-a394-c98699327151
 director: George A. Romero
 minutes: 96
 status: to watch
@@ -734,7 +734,7 @@ Answer:
 ```markdown
 ---
 table: main.public.film
-id: 01a16c6a-fc6c-7872-89fb-d51beace835e
+id: 01a16ca2-943a-7248-9a53-5c7f7532b5af
 year: 1924
 minutes: 45
 status: to watch
@@ -762,7 +762,7 @@ Answer:
   "op": "alter_table",
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [{ "table": "main.public.film", "version": 7, "operation": "ALTER TABLE" }],
-  "migration_id": "20261024T053835-alter_table-alter-table-main-public-film"
+  "migration_id": "20261024T063918-alter_table-alter-table-main-public-film"
 }
 ```
 
@@ -825,7 +825,7 @@ This is the table as you inferred, corrected and extended it on this page. Its d
 
 ```yaml
 # Metastore (Datanotes): catalogs, schemas, tables, columns, views.
-id: 01a16c6a-f3c8-7bd8-8ca7-e31ab9cbc5a7
+id: 01a16ca2-8b02-76f7-8686-40530eaf4e87
 config:
   history: true
 

package/dist/docs/guides/read-and-write/write-rows.md

@@ -31,7 +31,7 @@ Answer:
   "files_created": 1,
   "planned_creates": ["datanotes/main/public/film/Metropolis.md"],
   "commits": [{ "table": "main.public.film", "version": 1, "operation": "WRITE" }],
-  "migration_id": "20261024T053819-insert_row-insert-into-film"
+  "migration_id": "20261024T063903-insert_row-insert-into-film"
 }
 ```
 
@@ -40,7 +40,7 @@ Answer:
 ```markdown
 ---
 table: main.public.film
-id: 01a16c6a-c7b1-7337-8349-70046fead6ac
+id: 01a16ca2-615c-78e9-af82-5d7ee065ac91
 title: Metropolis
 year: 1927
 minutes: 153
@@ -103,7 +103,7 @@ Answer:
     }
   ],
   "commits": [{ "table": "main.public.film", "version": 6, "operation": "UPDATE" }],
-  "migration_id": "20261024T053823-update_row-update-film"
+  "migration_id": "20261024T063907-update_row-update-film"
 }
 ```
 
@@ -174,7 +174,7 @@ Answer:
     }
   ],
   "commits": [{ "table": "main.public.film", "version": 8, "operation": "UPDATE" }],
-  "migration_id": "20261024T053823-update_row-update-film-3",
+  "migration_id": "20261024T063907-update_row-update-film-3",
   "ambiguous_mentions": [
     {
       "path": "datanotes/main/public/film/Nosferatu.md",
@@ -193,7 +193,7 @@ Answer:
 ```markdown
 ---
 table: main.public.film
-id: 01a16c6a-d656-749e-960a-7aa338a198ae
+id: 01a16ca2-718e-7219-9638-3d26346a9a88
 title: Nosferatu
 year: 1922
 status: watched
@@ -246,7 +246,7 @@ Answer:
     }
   ],
   "commits": [{ "table": "main.public.film", "version": 9, "operation": "UPDATE" }],
-  "migration_id": "20261024T053823-update_row-update-film-4"
+  "migration_id": "20261024T063907-update_row-update-film-4"
 }
 ```
 
@@ -332,7 +332,7 @@ Answer:
     }
   ],
   "commits": [{ "table": "main.public.film", "version": 10, "operation": "UPDATE" }],
-  "migration_id": "20261024T053823-update_rows-update-film"
+  "migration_id": "20261024T063907-update_rows-update-film"
 }
 ```
 
@@ -370,7 +370,7 @@ Answer:
   ],
   "planned_creates": ["datanotes/main/public/film/Battleship Potemkin.md"],
   "commits": [{ "table": "main.public.film", "version": 11, "operation": "MERGE" }],
-  "migration_id": "20261024T053823-merge_rows-merge-2-rows-into-film"
+  "migration_id": "20261024T063907-merge_rows-merge-2-rows-into-film"
 }
 ```
 
@@ -431,7 +431,7 @@ Answer:
     }
   ],
   "commits": [{ "table": "main.public.film", "version": 12, "operation": "DELETE" }],
-  "migration_id": "20261024T053823-delete_rows-archive-1-rows-of-film"
+  "migration_id": "20261024T063907-delete_rows-archive-1-rows-of-film"
 }
 ```
 
@@ -568,6 +568,6 @@ Answer (51 lines)
     { "table": "main.public.film", "version": 22, "operation": "MOVE ROWS" },
     { "table": "main.public.watchlist", "version": 1, "operation": "MOVE ROWS" }
   ],
-  "migration_id": "20261024T053823-move_rows-move-4-rows-from-film-to-watch"
+  "migration_id": "20261024T063907-move_rows-move-4-rows-from-film-to-watch"
 }
 ```

package/dist/docs/guides/search/hybrid.md

@@ -0,0 +1,162 @@
+# Search notes by words and meaning
+
+> Search every note by its words, and by its meaning too when semantic search is on, in one call.
+
+The [`search`](https://datanotes.dev/reference/operations/queries/#search) operation always works. It ranks the notes by their words, and by their meaning too when [semantic search](https://datanotes.dev/guides/search/semantic/) is on. A note found only one way is still in the answer. The vault has three actors, two classic films, a viewing and two plain notes.
+
+## Choose the search to use
+
+The engine has three ways to search the notes:
+
+| Operation         | Finds                                                                                           | Use it for                                  |
+| ----------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------- |
+| `search`          | Notes with any word of the query, ranked; with semantic search on, notes that mean the same too | Most searches, by agents and programs       |
+| `search_notes`    | Notes with every word of the query, as text                                                     | Exact passages, such as a code or a name    |
+| `semantic_search` | Notes by meaning only                                                                           | Vague questions, when semantic search is on |
+
+## How the words rank the notes
+
+`search` scores each note with BM25, the ranking of most search engines:
+
+* **Rare words count more.** A word that few notes have says more than a word that every note has.
+* **The name and the properties count more.** A word in the note’s name, or in a value of its front matter, adds to its score. Property names, `id` and `table` don’t count.
+* **Every word counts.** A note with every word of the query ranks above a note with some of them.
+* **Words in a row count more.** Two words next to each other, as in the query, add a little.
+
+The engine ignores case and accents, so `Uovo` finds `uovo` and `perche` finds `perché`. It doesn’t reduce words to a stem, because notes are in many languages: `uova` doesn’t find `uovo`. Semantic search finds those other forms. A single letter is never searched, but a single digit is, so `6 mesi` works.
+
+## Write a query
+
+A query takes the syntax of `search_docs`:
+
+* `"6 mesi"`: the words must appear in a row.
+* `+uovo`: the word must appear.
+* `-latte`: no note with the word is returned.
+* Any other word only ranks the notes.
+
+`tables` keeps the rows of some tables, by full or short name. `folder` keeps the notes of one folder. `limit` sets how many notes come back: 10 by default, at most 100.
+
+## Fuse the words with the meaning
+
+When semantic search is on, `search` also ranks the notes by meaning. It then fuses the two rankings with Reciprocal Rank Fusion. A note scores more for each ranking it is in, and more near the top of each.
+
+Each hit says how the engine found it in `matched_by`: `words`, `meaning` or both. The answer’s `meaning` field says what ran:
+
+* `on`: both rankings, fused.
+* `off`: semantic search is off, so only the words ranked.
+* `failed`: the embedding provider failed, so only the words ranked. `meaning_error` says why.
+
+The required and excluded words filter both rankings. `min_score` drops the passages of the meaning ranking below that similarity, from 0 to 1.
+
+## What a token may search
+
+A named token with [`read` patterns](https://datanotes.dev/guides/security/tokens/#limit-what-a-token-can-read) searches only the notes it may read. A table it may not read, named exactly in `tables`, answers 403.
+
+## Search by words and meaning
+
+`search` ranks every note that has a word of the query. A rare word counts more than a common one. A word in the note’s name or properties counts more than one in its text. Here semantic search is off, so `meaning` is `off` and every hit has `matched_by: ["words"]`.
+
+**`search`**
+
+```json
+{ "query": "cary grant film" }
+```
+
+Answer (52 lines)
+
+```json
+{
+  "query": "cary grant film",
+  "results": [
+    {
+      "path": "Notes/Film night.md",
+      "score": 4.57,
+      "heading": "",
+      "snippet": "…ry other Friday. Next up: [[Charade]]. October’s theme is [[Cary Grant]].",
+      "matched_by": ["words"]
+    },
+    {
+      "path": "Notes/Rewatch ideas.md",
+      "score": 1.95,
+      "heading": "",
+      "snippet": "A Cary Grant weekend: every film with him, in release order.",
+      "matched_by": ["words"]
+    },
+    {
+      "path": "datanotes/main/public/actor/Cary Grant.md",
+      "table": "main.public.actor",
+      "score": 1.92,
+      "heading": "",
+      "snippet": "Cary Grant",
+      "matched_by": ["words"]
+    },
+    {
+      "path": "datanotes/main/public/film/Charade.md",
+      "table": "main.public.film",
+      "score": 0.9,
+      "heading": "",
+      "snippet": "[[Cary Grant]] again, 23 years after [[His Girl Friday]]. Watch them back to back.",
+      "matched_by": ["words"]
+    },
+    {
+      "path": "datanotes/main/public/film/His Girl Friday.md",
+      "table": "main.public.film",
+      "score": 0.6,
+      "heading": "",
+      "snippet": "\"Cary Grant\"",
+      "matched_by": ["words"]
+    },
+    {
+      "path": "datanotes/main/public/watch/2026-09-25T2100.md",
+      "table": "main.public.watch",
+      "score": 0.07,
+      "heading": "",
+      "snippet": "Part of [[Film night]]. Four of us on the sofa, and nobody guessed the ending.",
+      "matched_by": ["words"]
+    }
+  ],
+  "meaning": "off"
+}
+```
+
+Quotes keep words together, and a minus sign leaves notes out. This query wants the two words in a row, and no note that names Charade:
+
+**`search`**
+
+```json
+{ "query": "\"cary grant\" -charade" }
+```
+
+Answer:
+
+```json
+{
+  "query": "\"cary grant\" -charade",
+  "results": [
+    {
+      "path": "datanotes/main/public/actor/Cary Grant.md",
+      "table": "main.public.actor",
+      "score": 4.31,
+      "heading": "",
+      "snippet": "Cary Grant",
+      "matched_by": ["words"]
+    },
+    {
+      "path": "datanotes/main/public/film/His Girl Friday.md",
+      "table": "main.public.film",
+      "score": 1.35,
+      "heading": "",
+      "snippet": "\"Cary Grant\"",
+      "matched_by": ["words"]
+    },
+    {
+      "path": "Notes/Rewatch ideas.md",
+      "score": 1.18,
+      "heading": "",
+      "snippet": "A Cary Grant weekend: every film with him, in release order.",
+      "matched_by": ["words"]
+    }
+  ],
+  "meaning": "off"
+}
+```

package/dist/docs/guides/search/text.md

@@ -87,7 +87,7 @@ Answer (62 lines)
         {
           "start": 81,
           "end": 86,
-          "context": "-9421-e41365b64268\nname: Cary Grant\n---\n\n"
+          "context": "-9707-5a03c150e424\nname: Cary Grant\n---\n\n"
         }
       ]
     },

package/dist/docs/guides/security/security-model.md

@@ -60,13 +60,15 @@ The owner token is `httpServerToken` in the settings file. It can do everything:
 
 The owner creates a named token with `POST /datanotes/tokens/create/`, and the engine stores only its hash, in `tokens.json` in its store, outside the vault. A named token has these permissions:
 
-* **Read**: everything
+* **Read**: only the tables in its `read` patterns; without `read`, every table
 * **Write rows**: only the tables in its `write` patterns
 * **Change the schema**: only with `ddl`
 * **Maintain**: with `maintain`, it may also undo, restore, vacuum, configure the database and rebuild the semantic index; use it for an agent’s own token
 
 A named token can’t create webhooks, manage tokens or read the engine’s status, and without `maintain` it can’t undo.
 
+With `read` patterns, a token reads only the tables they match. It never reads the notes outside tables. Listings, search, the graph and the change feed leave out the rest. A query that names another table gets 403. A token always reads what it writes, and a token with `ddl` or `maintain` reads every table. Listings hide the other tables’ names. A refusal repeats a name the caller gave, so a guessed name isn’t secret. [Limit what a token can read](https://datanotes.dev/guides/security/tokens/#limit-what-a-token-can-read) lists the rules and the known gaps.
+
 ### Extensions
 
 An extension adds tables and Model Context Protocol (MCP) tools from a git repository. Its code is trusted code that runs inside the MCP server’s process, not in a sandbox. Install only extensions you trust, and read the plan first.
@@ -77,7 +79,7 @@ An extension adds tables and Model Context Protocol (MCP) tools from a git repos
 * **An invoker check**: before a tool that writes runs, the server checks the calling agent’s token. That token must be able to write the tool’s tables. A read-only client cannot write through an extension.
 * **The secret stays on one machine**: the token file sits under the data home with mode 0600. The registry in the engine’s store holds no secret.
 
-Known limits: extension code is not isolated from the MCP server’s process. Its token reads every table until read patterns ship. Migrations are declarative and run no code. [Install extensions](https://datanotes.dev/administration/extensions/) has the details.
+Known limits: extension code is not isolated from the MCP server’s process. The installer gives its token no `read`, so it reads every table. The owner may limit it with `read` patterns that cover the tables it writes. Migrations are declarative and run no code. [Install extensions](https://datanotes.dev/administration/extensions/) has the details.
 
 ### Who made each write
 
@@ -105,7 +107,7 @@ An agent reads your notes, and a note can hold text written to manipulate it: a
 
 Limit what each agent can do:
 
-* **Give it a named token**: grant only the tables it writes, and leave out `ddl` and `maintain` unless it needs them
+* **Give it a named token**: grant only the tables it reads and writes, and leave out `ddl` and `maintain` unless it needs them
 * **Give it only the tools it needs**: start the MCP server with `datanotes mcp --profile`, `--tools` or `--except`
 * **Keep the webhook tools off**: they’re off by default, because a webhook sends change events to any URL