datanotes 3.1.0 → 3.3.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": "20261014T191527-insert_row-insert-into-film-2",
+  "migration_id": "20261020T173837-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: 01a13bd7-4a17-7131-b737-fb23d7e81b2b
+id: 01a15a64-cc30-746d-8d56-2e96073a7f92
 title: Charade
 year: 1963
 ---
@@ -169,7 +169,7 @@ Answer:
     }
   ],
   "commits": [{ "table": "main.public.film", "version": 3, "operation": "UPDATE" }],
-  "migration_id": "20261014T191527-update_row-update-film",
+  "migration_id": "20261020T173837-update_row-update-film",
   "links_added": [
     {
       "path": "datanotes/main/public/film/Charade.md",
@@ -186,7 +186,7 @@ Answer:
 ```markdown
 ---
 table: main.public.film
-id: 01a13bd7-4a17-7131-b737-fb23d7e81b2b
+id: 01a15a64-cc30-746d-8d56-2e96073a7f92
 title: Charade
 year: 1963
 ---
@@ -229,7 +229,7 @@ Answer:
     }
   ],
   "commits": [{ "table": "main.public.film", "version": 4, "operation": "UPDATE" }],
-  "migration_id": "20261014T191527-update_row-update-film-2",
+  "migration_id": "20261020T173837-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": "20261014T191527-update_row-update-film-3",
+  "migration_id": "20261020T173837-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: 01a13bd7-4a11-7df7-bc89-ce5f25be27d3
+id: 01a15a64-cc27-7889-830d-3f2630d43bc6
 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": "20261014T191527-insert_row-insert-into-film-3",
+  "migration_id": "20261020T173837-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: 01a13bd7-4a3b-797e-b0a9-020b91e12ca1
+id: 01a15a64-cc67-77ea-a705-b2b8b3274155
 title: Persona
 year: 1966
 ---
@@ -472,7 +472,7 @@ Answer:
     }
   ],
   "commits": [{ "table": "main.public.film", "version": 7, "operation": "UPDATE" }],
-  "migration_id": "20261014T191527-update_row-update-film-4",
+  "migration_id": "20261020T173837-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: 01a13bd7-4a3b-797e-b0a9-020b91e12ca1
+id: 01a15a64-cc67-77ea-a705-b2b8b3274155
 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: 01a13bd7-4553-7877-bbf1-25ceb6bb6d1a
+id: 01a15a64-cbfe-7566-a13b-1628b83a1a00
 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": "20261014T191527-insert_row-insert-into-film-4"
+  "migration_id": "20261020T173837-insert_row-insert-into-film-4"
 }
 ```
 
@@ -629,7 +629,7 @@ Answer:
 ```markdown
 ---
 table: main.public.film
-id: 01a13bd7-4a5d-79ee-b163-e15d61052c55
+id: 01a15a64-cc94-72c6-a7d7-7f669c1d1869
 title: His Girl Friday
 year: 1940
 ---
@@ -663,7 +663,7 @@ Answer:
 
 ```yaml
 # Metastore (Datanotes): catalogs, schemas, tables, columns, views.
-id: 01a13bd7-4553-7877-bbf1-25ceb6bb6d1a
+id: 01a15a64-cbfe-7566-a13b-1628b83a1a00
 config:
   history: true
   autolink: false

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

@@ -236,7 +236,7 @@ Refused:
 
 ```text
 pass "time_column" or "filename" (e.g. "{name}") so rows get file names
-Hint: Check the arguments of create_table: name (string, required), description (string), columns (list of objects, required), catalog (string), schema (string), time_column (string), filename (string), partition (string), exclude (list of strings), archive (string), aliases (list of strings), history (boolean), autolink_target (boolean), row_template (string), fields (object), tags (object), dry_run (boolean).
+Hint: Check the arguments of create_table: name (string, required), description (string), columns (list of objects, required), catalog (string), schema (string), time_column (string), filename (string), partition (string), exclude (list of strings), archive (string), aliases (list of strings), history (boolean), autolink_target (boolean), row_template (string), instructions (string), fields (object), tags (object), dry_run (boolean).
 Docs: https://datanotes.dev/reference/operations/schema.md#create_table (offline: read_docs("reference/operations/schema#create_table"))
 ```
 
@@ -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": "20261014T191527-create_table-create-table-main-public-film"
+  "migration_id": "20261020T173838-create_table-create-table-main-public-film"
 }
 ```
 
@@ -359,7 +359,7 @@ Answer (70 lines)
       "path": "Films/Charade.md",
       "set": {
         "table": "main.public.film",
-        "id": "01a13bd7-4bef-7ddf-abde-b91b57090495",
+        "id": "01a15a64-ce9f-7560-9add-1459237106c3",
         "director": "Stanley Donen",
         "title": "Charade"
       },
@@ -369,7 +369,7 @@ Answer (70 lines)
       "path": "Films/His Girl Friday.md",
       "set": {
         "table": "main.public.film",
-        "id": "01a13bd7-4bef-7b33-bb40-437e95d29b11",
+        "id": "01a15a64-ce9f-7172-abbb-020e612ede56",
         "director": "Howard Hawks",
         "title": "His Girl Friday"
       },
@@ -379,7 +379,7 @@ Answer (70 lines)
       "path": "Films/Metropolis.md",
       "set": {
         "table": "main.public.film",
-        "id": "01a13bd7-4bef-78c0-9fae-baa5a384034b",
+        "id": "01a15a64-ce9f-7b50-990c-aa26f69b3ab6",
         "director": "Fritz Lang",
         "title": "Metropolis"
       },
@@ -389,7 +389,7 @@ Answer (70 lines)
       "path": "Films/Nosferatu.md",
       "set": {
         "table": "main.public.film",
-        "id": "01a13bd7-4bef-7530-9686-caa5dae75ba9",
+        "id": "01a15a64-ce9f-7541-8429-fc436df30866",
         "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": "01a13bd7-4bf0-76d1-acad-286dc20353ec",
+        "id": "01a15a64-ce9f-7cf2-8129-a75fb2745cc9",
         "director": "Charlie Chaplin",
         "title": "The Gold Rush"
       },
@@ -458,7 +458,7 @@ Answer (73 lines)
       "path": "Films/Charade.md",
       "set": {
         "table": "main.public.film",
-        "id": "01a13bd7-4bf3-7078-b24f-c1aacdc10722",
+        "id": "01a15a64-cea3-7bf1-ada5-aeb2d9dbb4fd",
         "director": "Stanley Donen",
         "title": "Charade"
       },
@@ -468,7 +468,7 @@ Answer (73 lines)
       "path": "Films/His Girl Friday.md",
       "set": {
         "table": "main.public.film",
-        "id": "01a13bd7-4bf3-72be-9f3c-6af5c1e45507",
+        "id": "01a15a64-cea3-777e-b51d-cfb871067faf",
         "director": "Howard Hawks",
         "title": "His Girl Friday"
       },
@@ -478,7 +478,7 @@ Answer (73 lines)
       "path": "Films/Metropolis.md",
       "set": {
         "table": "main.public.film",
-        "id": "01a13bd7-4bf3-7a1e-b23c-2769c0dc41d3",
+        "id": "01a15a64-cea3-776e-b81b-389706767aa1",
         "director": "Fritz Lang",
         "title": "Metropolis"
       },
@@ -488,7 +488,7 @@ Answer (73 lines)
       "path": "Films/Nosferatu.md",
       "set": {
         "table": "main.public.film",
-        "id": "01a13bd7-4bf3-7289-b3dd-65839150b89a",
+        "id": "01a15a64-cea3-7299-a73b-bb2b9eec0177",
         "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": "01a13bd7-4bf3-7795-afda-7207d19732fb",
+        "id": "01a15a64-cea4-7624-b9be-0e6c6aeb6dfc",
         "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": "20261014T191527-adopt_rows-adopt-5-notes-into-film"
+  "migration_id": "20261020T173838-adopt_rows-adopt-5-notes-into-film"
 }
 ```
 
@@ -536,7 +536,7 @@ Answer:
 ```markdown
 ---
 table: main.public.film
-id: 01a13bd7-4bf3-7078-b24f-c1aacdc10722
+id: 01a15a64-cea3-7bf1-ada5-aeb2d9dbb4fd
 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": "20261014T191527-insert_row-insert-into-film"
+  "migration_id": "20261020T173838-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": "20261014T191529-add_column-add-column-added_by-to-film"
+  "migration_id": "20261020T173839-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": "20261014T191529-insert_row-insert-into-film"
+  "migration_id": "20261020T173839-insert_row-insert-into-film"
 }
 ```
 
@@ -692,7 +692,7 @@ Answer:
 ```markdown
 ---
 table: main.public.film
-id: 01a13bd7-51ec-7ccf-ace8-a87f2b6b5d44
+id: 01a15a64-d4a9-7905-af13-90c8506569c9
 director: George A. Romero
 minutes: 96
 status: to watch
@@ -734,7 +734,7 @@ Answer:
 ```markdown
 ---
 table: main.public.film
-id: 01a13bd7-547d-7d1d-93ff-6eb23257eec6
+id: 01a15a64-d731-7eff-804e-4148716ec5c3
 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": "20261014T191531-alter_table-alter-table-main-public-film"
+  "migration_id": "20261020T173842-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: 01a13bd7-4bd8-7523-b02d-c287216ddcdf
+id: 01a15a64-ce85-731f-bfea-eb573328eb39
 config:
   history: true
 

package/dist/docs/guides/read-and-write/joins-and-aggregates.md

@@ -100,9 +100,9 @@ Answer:
   "table": "main.public.watch",
   "total": 3,
   "rows": [
-    { "date(occurred_at)": "2026-10-09", "viewings": 1 },
-    { "date(occurred_at)": "2026-10-12", "viewings": 1 },
-    { "date(occurred_at)": "2026-10-13", "viewings": 1 }
+    { "date(occurred_at)": "2026-10-15", "viewings": 1 },
+    { "date(occurred_at)": "2026-10-18", "viewings": 1 },
+    { "date(occurred_at)": "2026-10-19", "viewings": 1 }
   ]
 }
 ```
@@ -138,10 +138,10 @@ Answer:
     {
       "path": "datanotes/main/public/film/Night of the Living Dead.md",
       "title": "Night of the Living Dead",
-      "watched_on": "2026-10-13",
+      "watched_on": "2026-10-19",
       "viewing": [
         {
-          "path": "datanotes/main/public/watch/2026-10-13T2200.md",
+          "path": "datanotes/main/public/watch/2026-10-19T2200.md",
           "where": "cinema",
           "with": "Oscar"
         }
@@ -150,10 +150,10 @@ Answer:
     {
       "path": "datanotes/main/public/film/The Gold Rush.md",
       "title": "The Gold Rush",
-      "watched_on": "2026-10-12",
+      "watched_on": "2026-10-18",
       "viewing": [
         {
-          "path": "datanotes/main/public/watch/2026-10-12T2030.md",
+          "path": "datanotes/main/public/watch/2026-10-18T2030.md",
           "where": "home",
           "with": "my sister"
         }

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

@@ -332,23 +332,23 @@ Answer:
   "total": 3,
   "rows": [
     {
-      "path": "datanotes/main/public/watch/2026-10-09T2115.md",
+      "path": "datanotes/main/public/watch/2026-10-15T2115.md",
       "film": "[[Charade]]",
-      "occurred_at": "2026-10-09T21:15",
+      "occurred_at": "2026-10-15T21:15",
       "where": "home",
       "place": "my living room"
     },
     {
-      "path": "datanotes/main/public/watch/2026-10-12T2030.md",
+      "path": "datanotes/main/public/watch/2026-10-18T2030.md",
       "film": "[[The Gold Rush]]",
-      "occurred_at": "2026-10-12T20:30",
+      "occurred_at": "2026-10-18T20:30",
       "where": "home",
       "place": "my living room"
     },
     {
-      "path": "datanotes/main/public/watch/2026-10-13T2200.md",
+      "path": "datanotes/main/public/watch/2026-10-19T2200.md",
       "film": "[[Night of the Living Dead]]",
-      "occurred_at": "2026-10-13T22:00",
+      "occurred_at": "2026-10-19T22:00",
       "where": "cinema",
       "place": "the film club downtown"
     }
@@ -459,12 +459,12 @@ Answer:
   "total": 7,
   "rows": [
     {
-      "path": "datanotes/main/public/watch/2026-10-09T2115.md",
-      "occurred_at": "2026-10-09T21:15"
+      "path": "datanotes/main/public/watch/2026-10-15T2115.md",
+      "occurred_at": "2026-10-15T21:15"
     },
     {
-      "path": "datanotes/main/public/watch/2026-10-05T2130.md",
-      "occurred_at": "2026-10-05T21:30"
+      "path": "datanotes/main/public/watch/2026-10-11T2130.md",
+      "occurred_at": "2026-10-11T21:30"
     }
   ]
 }

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": "20261014T191515-insert_row-insert-into-film"
+  "migration_id": "20261020T173828-insert_row-insert-into-film"
 }
 ```
 
@@ -40,7 +40,7 @@ Answer:
 ```markdown
 ---
 table: main.public.film
-id: 01a13bd7-1a3c-77a0-9b04-bdbf908dd17f
+id: 01a15a64-a8b5-7df3-aef8-9d133af2ff28
 title: Metropolis
 year: 1927
 minutes: 153
@@ -103,7 +103,7 @@ Answer:
     }
   ],
   "commits": [{ "table": "main.public.film", "version": 6, "operation": "UPDATE" }],
-  "migration_id": "20261014T191521-update_row-update-film"
+  "migration_id": "20261020T173832-update_row-update-film"
 }
 ```
 
@@ -174,7 +174,7 @@ Answer:
     }
   ],
   "commits": [{ "table": "main.public.film", "version": 8, "operation": "UPDATE" }],
-  "migration_id": "20261014T191521-update_row-update-film-3",
+  "migration_id": "20261020T173833-update_row-update-film-2",
   "ambiguous_mentions": [
     {
       "path": "datanotes/main/public/film/Nosferatu.md",
@@ -193,7 +193,7 @@ Answer:
 ```markdown
 ---
 table: main.public.film
-id: 01a13bd7-321a-76c1-9810-fe730dc54990
+id: 01a15a64-b97e-7825-b690-1c0bdc44583e
 title: Nosferatu
 year: 1922
 status: watched
@@ -246,7 +246,7 @@ Answer:
     }
   ],
   "commits": [{ "table": "main.public.film", "version": 9, "operation": "UPDATE" }],
-  "migration_id": "20261014T191521-update_row-update-film-4"
+  "migration_id": "20261020T173833-update_row-update-film-3"
 }
 ```
 
@@ -332,7 +332,7 @@ Answer:
     }
   ],
   "commits": [{ "table": "main.public.film", "version": 10, "operation": "UPDATE" }],
-  "migration_id": "20261014T191521-update_rows-update-film"
+  "migration_id": "20261020T173833-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": "20261014T191521-merge_rows-merge-2-rows-into-film"
+  "migration_id": "20261020T173833-merge_rows-merge-2-rows-into-film"
 }
 ```
 
@@ -431,7 +431,7 @@ Answer:
     }
   ],
   "commits": [{ "table": "main.public.film", "version": 12, "operation": "DELETE" }],
-  "migration_id": "20261014T191521-delete_rows-archive-1-rows-of-film"
+  "migration_id": "20261020T173833-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": "20261014T191521-move_rows-move-4-rows-from-film-to-watch"
+  "migration_id": "20261020T173833-move_rows-move-4-rows-from-film-to-watch"
 }
 ```

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

@@ -87,7 +87,7 @@ Answer (62 lines)
         {
           "start": 81,
           "end": 86,
-          "context": "-afa4-921743d3b309\nname: Cary Grant\n---\n\n"
+          "context": "-ad6c-b8dee1b7285e\nname: Cary Grant\n---\n\n"
         }
       ]
     },

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

@@ -67,6 +67,18 @@ The owner creates a named token with `POST /datanotes/tokens/create/`, and the e
 
 A named token can’t create webhooks, manage tokens or read the engine’s status, and without `maintain` it can’t undo.
 
+### 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.
+
+* **Pinned code**: the installer takes a version tag or a full commit id, and refuses a branch. It fetches the tag itself, even when a branch has the same name. It records the commit and the SHA-256 hashes of the manifest and the entry file. The server refuses cached code that differs.
+* **No install scripts**: the installer runs no script, no build and no `npm install`. The entry file may import only Node built-ins. The installer reads the imports in the file. Code that builds a module name at run time escapes this check.
+* **One token for each extension**: `ext-<name>` writes only the tables the manifest lists. It cannot change the schema or undo. The installer changes the schema with the owner’s token, after you confirm the plan.
+* **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.
+
 ### Who made each write
 
 The engine journals every write with its actor. The client sends the agent’s name, model and session, so they’re self-reported. The server sets the credential, `auth` (`owner`, or the named token’s name), and no client can claim another one.

package/dist/docs/reference/cli.md

@@ -3,7 +3,7 @@
 > The datanotes command and its options.
 
 ```text
-datanotes 3.1.0: Markdown notes as database tables, for you and your agents.
+datanotes 3.3.0: Markdown notes as database tables, for you and your agents.
 
 
 Usage:
@@ -15,6 +15,11 @@ Usage:
   datanotes store backup --database <folder>      show or set the store's git backup (--remote <url>, --off)
   datanotes store restore --from <url> --database <folder>   restore the store from its git backup
   datanotes store convert-log --to <files|segments> --database <folder>   rewrite the transaction log in that format
+  datanotes extension install <source> --database <folder>   install an extension: plan, confirm, write
+                                               (a git URL with #<tag>, owner/repo@<tag>, or a folder)
+  datanotes extension update | rollback | remove <name> --database <folder>   change an installed one
+  datanotes extension list --database <folder>    the installed extensions
+  datanotes extension check <folder>             check an extension's repository (for its authors)
   Every command takes --vault <folder> instead of --database for a vault holding the database.
   datanotes mcp --database <folder>            MCP server over stdio, on the engine running on the folder
                                                (or one it starts for the session)
@@ -103,6 +108,27 @@ Options of store:
   ~/.local/share/datanotes (Linux); DATANOTES_DATA_HOME moves it.
 
 
+Options of extension (every command but check works through the engine running on the database):
+  --database <folder>         the database folder (or DATANOTES_DATABASE; --vault <folder> for a vault)
+  --store <folder>            the engine's store, when serve was given one (or DATANOTES_STORE)
+  --settings <file>           settings file with the owner's token (or DATANOTES_SETTINGS;
+                              default settings.json in the store)
+  --url <url>                 an engine at an address (or DATANOTES_URL), with
+  --token-file <file>         a file holding the owner's token (or DATANOTES_TOKEN_FILE)
+  --map <list>                install, update: role=catalog.schema.table or role.column=column
+  --create <roles>            install, update: create these tables the extension depends on
+  --add <list>                install, update: add these role.column columns to matched tables
+  --catalog <name>            install: the catalog of the tables and views it creates
+  --schema <name>             install: the schema of the tables and views it creates
+  --to <ref>                  update: the version tag or commit to move to (default: the newest tag)
+  --from <source>             update: another source, such as the folder you develop in
+  --dry-run                   install, update: print the plan and write nothing
+  --yes                       write without asking (only once the user approved the plan)
+  --json                      print one JSON object (the plan or the result) and never ask
+  Lists (--map, --create, --add) are comma-separated. Exit codes: 0 done; 1 error; 2 the plan has
+  problems (nothing written); 3 confirmation needed (run again with --yes once the user approved)
+
+
 Options of mcp (stdio):
   --database <folder>         the database folder (or DATANOTES_DATABASE); acts with the owner's token,
                               and stops the engine it started when the client closes
@@ -128,6 +154,11 @@ Tools of mcp (both modes; default: every tool except create_webhook and delete_w
                               (or DATANOTES_MCP_OWNER_TOOLS=1)
 
 
+Extensions of mcp (both modes): the tools of the extensions installed in the database (datanotes
+extension install) come after the engine's tools; --profile read keeps only their read-only tools
+  --no-extensions             offer no extension tools (or DATANOTES_MCP_EXTENSIONS=0)
+
+
 Logs of mcp (both modes):
   --otlp-endpoint <url>       export logs over OTLP/HTTP, e.g. http://127.0.0.1:4318 (or the standard
                               OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS, OTEL_SERVICE_NAME)

package/dist/docs/reference/errors.md

@@ -67,6 +67,6 @@ A write the engine refuses lists its violations, each with a `code`; `check_tabl
 | `unknown_column` | Write only the table’s columns: describe_table lists them. To keep a new front matter key, add_column first.                                                                                                                                | [Describe a table before writing to it](https://datanotes.dev/guides/database-objects/tables/#describe-a-table-before-writing-to-it)                      |
 | `check`          | The row breaks a CHECK constraint of the table (named in the message, with its rule): change the values so the rule holds. describe_table lists the table’s constraints.                                                                    | [Enforce rules with CHECK constraints](https://datanotes.dev/guides/data-quality/check-constraints/#enforce-rules-with-check-constraints)                 |
 | `generated`      | A generated column is computed by the engine: do not write it; recompute_columns sets it again.                                                                                                                                             | [Recompute generated columns after a hand edit](https://datanotes.dev/guides/data-quality/hand-edits/#recompute-generated-columns-after-a-hand-edit)      |
-| `cycle`          | A row cannot be its own ancestor: point the hierarchy column to a row that is not below this one.                                                                                                                                           | [Build a tree of rows with a parent link](https://datanotes.dev/guides/database-objects/relations/#build-a-tree-of-rows-with-a-parent-link)               |
+| `cycle`          | A row cannot be its own ancestor in a hierarchy column, nor depend on itself through an acyclic column: the message shows the path. Point the column to a row that is not on that path.                                                     | [Build a tree of rows with a parent link](https://datanotes.dev/guides/database-objects/relations/#build-a-tree-of-rows-with-a-parent-link)               |
 | `inverse`        | Both sides of a two-way link must agree: write one side, or run align_relations to repair them.                                                                                                                                             | [Repair two-way links with `align_relations`](https://datanotes.dev/guides/database-objects/relations/#repair-two-way-links-with-align_relations)         |
 | `unreadable`     | The note’s front matter is not valid YAML (the message quotes the parser), so every read leaves the row out: open the note and fix the YAML, such as a quote or bracket left open or a line without `key: value`. read_note shows its text. | [Find rows whose front matter can’t be read](https://datanotes.dev/guides/data-quality/hand-edits/#find-rows-whose-front-matter-cant-be-read)             |

package/dist/docs/reference/glossary.md

@@ -64,6 +64,10 @@ A UUID at the top of `metastore.yaml`, as `id`, that names the database. The eng
 
 The process that runs a vault as a database, `datanotes serve`. It checks and journals every write and serves the HTTP API. See [Run the engine as a service](https://datanotes.dev/administration/run-the-service/).
 
+## Extension
+
+A git repository that adds tables, views, bases, MCP tools and docs to a database. `datanotes extension install` pins and installs it. See [Install extensions](https://datanotes.dev/administration/extensions/).
+
 ## Front matter
 
 The YAML block at the top of a note, between two `---` lines. Each key of a row’s front matter holds the value of one column. See [How it works](https://datanotes.dev/start/how-it-works/).
@@ -112,6 +116,10 @@ A call the engine runs, such as `create_table`, `insert_row` or `select_rows`. E
 
 The token that can do everything, generated at the engine’s first start and kept in its settings file. See [Tokens and permissions](https://datanotes.dev/guides/security/tokens/).
 
+## Role (extension)
+
+The short name an extension’s manifest gives a table, such as `book`. The installer binds each role to a table of your database. See [Declare the tables](https://datanotes.dev/develop/write-an-extension/#declare-the-tables).
+
 ## Row
 
 A note whose front matter key `table` names a table, wherever it lives in the vault. Its front matter keys are the row’s columns. Each row has an `id` that never changes. See [Tables](https://datanotes.dev/guides/database-objects/tables/).

package/dist/docs/reference/operations/auxiliary.md

@@ -20,7 +20,7 @@ Examples: [Tables](https://datanotes.dev/guides/database-objects/tables/), [View
 
 **Describe Table** · read-only
 
-Describe a table (`catalog.schema.table` or a shorter unambiguous name): `qualified`, `name`, `catalog`, `schema`, `description`, `aliases`, `layout` (`folder`, `row_folder`: the folder pattern of new rows, `archive`), `options` (`partition`, `filename`, `archive`, `exclude`), typed `columns` with label/aliases/description and the dense flag, `untyped_fields`, `row_count`, and when set: `tags`, `bases` (the bases it inherits from, in order), `constraints` (its CHECKs, name → where), `row_template`, `history`, `autolink_target`, `fields` (their values).
+Describe a table (`catalog.schema.table` or a shorter unambiguous name): `qualified`, `name`, `catalog`, `schema`, `description`, `aliases`, `layout` (`folder`, `row_folder`: the folder pattern of new rows, `archive`), `options` (`partition`, `filename`, `archive`, `exclude`), typed `columns` with label/aliases/description and the dense flag, `untyped_fields`, `row_count`, and when set: `tags`, `bases` (the bases it inherits from, in order), `constraints` (its CHECKs, name → where), `constraint_hints` (their own hints, name → hint), `instructions` (how to fill a row: follow them before you write one), `row_template`, `history`, `autolink_target`, `fields` (their values).
 
 Before adding a column (e.g. a new metric), read `columns` and match your concept against `name`, `label`, `aliases` and `description`; reuse an existing column when it means the same.
 
@@ -66,7 +66,7 @@ Examples: [Catalogs, schemas and the database](https://datanotes.dev/guides/data
 
 **Check Table** · read-only
 
-Validate every row against the table (required, types, ranges, enums, links, unknown columns, CHECK constraints, those that follow links included, filtered link targets (ref_where / ref_by), stale generated/identity values, missing inverse links, front matter that cannot be read: code `unreadable`, with no column, for a note whose `table` line names the table but whose YAML is broken, which every other read leaves out). A CHECK violation has code `check` and the CHECK’s name as `constraint` (every other code names its `column`), as in the `violations` of list_changes. Use it to find rows edited by hand that break the schema. Without `table`, every table is checked: each row then names its `table`, `tables_checked` counts the tables checked, and a table that cannot be checked is listed in `errors` ({table, error}) while the others are. The rows with violations are paged: `limit` (default 500, at most 5000) from `offset`; `total` counts them all. (Hand edits are also checked as they happen: see `violations` in list_changes.)
+Validate every row against the table (required, types, ranges, enums, links, unknown columns, CHECK constraints, those that follow links included, filtered link targets (ref_where / ref_by), stale generated/identity values, missing inverse links, cycles of hierarchy and acyclic columns, front matter that cannot be read: code `unreadable`, with no column, for a note whose `table` line names the table but whose YAML is broken, which every other read leaves out). A CHECK violation has code `check` and the CHECK’s name as `constraint` (every other code names its `column`), as in the `violations` of list_changes. Use it to find rows edited by hand that break the schema. Without `table`, every table is checked: each row then names its `table`, `tables_checked` counts the tables checked, and a table that cannot be checked is listed in `errors` ({table, error}) while the others are. The rows with violations are paged: `limit` (default 500, at most 5000) from `offset`; `total` counts them all. (Hand edits are also checked as they happen: see `violations` in list_changes.)
 
 Examples: [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [Hand edits](https://datanotes.dev/guides/data-quality/hand-edits/), [Find rows that break the schema](https://datanotes.dev/guides/data-quality/check-table/).