datanotes 3.0.0 → 3.2.0

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": "20261012T071957-create_table-create-table-main-public-film"
+  "migration_id": "20261019T040648-create_table-create-table-main-public-film"
 }
 ```
 
@@ -359,7 +359,7 @@ Answer (70 lines)
       "path": "Films/Charade.md",
       "set": {
         "table": "main.public.film",
-        "id": "01a12efb-81a4-717d-a664-f60882bb8996",
+        "id": "01a15257-31b6-75a9-bb7e-06ebf5b385a4",
         "director": "Stanley Donen",
         "title": "Charade"
       },
@@ -369,7 +369,7 @@ Answer (70 lines)
       "path": "Films/His Girl Friday.md",
       "set": {
         "table": "main.public.film",
-        "id": "01a12efb-81a4-7e0e-8864-4d93d474be34",
+        "id": "01a15257-31b6-7aac-9ba1-16fb7e23aa0a",
         "director": "Howard Hawks",
         "title": "His Girl Friday"
       },
@@ -379,7 +379,7 @@ Answer (70 lines)
       "path": "Films/Metropolis.md",
       "set": {
         "table": "main.public.film",
-        "id": "01a12efb-81a4-747e-8aef-048494381ac2",
+        "id": "01a15257-31b6-7d6a-998e-fd8f06c27786",
         "director": "Fritz Lang",
         "title": "Metropolis"
       },
@@ -389,7 +389,7 @@ Answer (70 lines)
       "path": "Films/Nosferatu.md",
       "set": {
         "table": "main.public.film",
-        "id": "01a12efb-81a4-71bf-9b8f-a28f778461db",
+        "id": "01a15257-31b6-7a33-a502-afc11c66b564",
         "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": "01a12efb-81a4-7628-817c-ce1281d27329",
+        "id": "01a15257-31b6-7124-9bc9-40a032066bd3",
         "director": "Charlie Chaplin",
         "title": "The Gold Rush"
       },
@@ -458,7 +458,7 @@ Answer (73 lines)
       "path": "Films/Charade.md",
       "set": {
         "table": "main.public.film",
-        "id": "01a12efb-81ad-7350-b6fc-3607a2c36814",
+        "id": "01a15257-31bb-7a46-8ac7-181fa5bacea7",
         "director": "Stanley Donen",
         "title": "Charade"
       },
@@ -468,7 +468,7 @@ Answer (73 lines)
       "path": "Films/His Girl Friday.md",
       "set": {
         "table": "main.public.film",
-        "id": "01a12efb-81ad-76cb-a7d9-1d8bcd578f6d",
+        "id": "01a15257-31bb-7754-a84c-ada8c44c4f96",
         "director": "Howard Hawks",
         "title": "His Girl Friday"
       },
@@ -478,7 +478,7 @@ Answer (73 lines)
       "path": "Films/Metropolis.md",
       "set": {
         "table": "main.public.film",
-        "id": "01a12efb-81ad-7b8f-aa3d-16ff4a7685be",
+        "id": "01a15257-31bb-7113-b86a-5d6fdca79420",
         "director": "Fritz Lang",
         "title": "Metropolis"
       },
@@ -488,7 +488,7 @@ Answer (73 lines)
       "path": "Films/Nosferatu.md",
       "set": {
         "table": "main.public.film",
-        "id": "01a12efb-81ad-7a1c-b7d7-c6ce93fd565e",
+        "id": "01a15257-31bc-7f8b-b4a7-376f074e01cb",
         "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": "01a12efb-81ad-7816-bbb2-0c7ac62d182a",
+        "id": "01a15257-31bc-7554-a326-0e8b427aa5c6",
         "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": "20261012T071957-adopt_rows-adopt-5-notes-into-film"
+  "migration_id": "20261019T040648-adopt_rows-adopt-5-notes-into-film"
 }
 ```
 
@@ -536,7 +536,7 @@ Answer:
 ```markdown
 ---
 table: main.public.film
-id: 01a12efb-81ad-7350-b6fc-3607a2c36814
+id: 01a15257-31bb-7a46-8ac7-181fa5bacea7
 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": "20261012T071957-insert_row-insert-into-film"
+  "migration_id": "20261019T040648-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": "20261012T071958-add_column-add-column-added_by-to-film"
+  "migration_id": "20261019T040650-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": "20261012T071958-insert_row-insert-into-film"
+  "migration_id": "20261019T040650-insert_row-insert-into-film"
 }
 ```
 
@@ -692,7 +692,7 @@ Answer:
 ```markdown
 ---
 table: main.public.film
-id: 01a12efb-87b5-7e4d-95f6-04c05995e9df
+id: 01a15257-37bf-770c-a384-b360bb939197
 director: George A. Romero
 minutes: 96
 status: to watch
@@ -734,7 +734,7 @@ Answer:
 ```markdown
 ---
 table: main.public.film
-id: 01a12efb-8a37-7b33-bb22-169f2afb9934
+id: 01a15257-3a49-7617-a437-430fcfdc292a
 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": "20261012T072001-alter_table-alter-table-main-public-film"
+  "migration_id": "20261019T040652-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: 01a12efb-8191-7a5c-9aee-8ffe9c6f215a
+id: 01a15257-319e-7663-863b-41ff43d87deb
 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-07", "viewings": 1 },
-    { "date(occurred_at)": "2026-10-10", "viewings": 1 },
-    { "date(occurred_at)": "2026-10-11", "viewings": 1 }
+    { "date(occurred_at)": "2026-10-14", "viewings": 1 },
+    { "date(occurred_at)": "2026-10-17", "viewings": 1 },
+    { "date(occurred_at)": "2026-10-18", "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-11",
+      "watched_on": "2026-10-18",
       "viewing": [
         {
-          "path": "datanotes/main/public/watch/2026-10-11T2200.md",
+          "path": "datanotes/main/public/watch/2026-10-18T2200.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-10",
+      "watched_on": "2026-10-17",
       "viewing": [
         {
-          "path": "datanotes/main/public/watch/2026-10-10T2030.md",
+          "path": "datanotes/main/public/watch/2026-10-17T2030.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-07T2115.md",
+      "path": "datanotes/main/public/watch/2026-10-14T2115.md",
       "film": "[[Charade]]",
-      "occurred_at": "2026-10-07T21:15",
+      "occurred_at": "2026-10-14T21:15",
       "where": "home",
       "place": "my living room"
     },
     {
-      "path": "datanotes/main/public/watch/2026-10-10T2030.md",
+      "path": "datanotes/main/public/watch/2026-10-17T2030.md",
       "film": "[[The Gold Rush]]",
-      "occurred_at": "2026-10-10T20:30",
+      "occurred_at": "2026-10-17T20:30",
       "where": "home",
       "place": "my living room"
     },
     {
-      "path": "datanotes/main/public/watch/2026-10-11T2200.md",
+      "path": "datanotes/main/public/watch/2026-10-18T2200.md",
       "film": "[[Night of the Living Dead]]",
-      "occurred_at": "2026-10-11T22:00",
+      "occurred_at": "2026-10-18T22:00",
       "where": "cinema",
       "place": "the film club downtown"
     }
@@ -459,12 +459,12 @@ Answer:
   "total": 7,
   "rows": [
     {
-      "path": "datanotes/main/public/watch/2026-10-07T2115.md",
-      "occurred_at": "2026-10-07T21:15"
+      "path": "datanotes/main/public/watch/2026-10-14T2115.md",
+      "occurred_at": "2026-10-14T21:15"
     },
     {
-      "path": "datanotes/main/public/watch/2026-10-03T2130.md",
-      "occurred_at": "2026-10-03T21:30"
+      "path": "datanotes/main/public/watch/2026-10-10T2130.md",
+      "occurred_at": "2026-10-10T21: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": "20261012T071946-insert_row-insert-into-film"
+  "migration_id": "20261019T040638-insert_row-insert-into-film"
 }
 ```
 
@@ -40,7 +40,7 @@ Answer:
 ```markdown
 ---
 table: main.public.film
-id: 01a12efb-5925-7551-9fc3-ca301818d73d
+id: 01a15257-0a57-7094-a53c-2ffddb1a5284
 title: Metropolis
 year: 1927
 minutes: 153
@@ -103,7 +103,7 @@ Answer:
     }
   ],
   "commits": [{ "table": "main.public.film", "version": 6, "operation": "UPDATE" }],
-  "migration_id": "20261012T071951-update_row-update-film"
+  "migration_id": "20261019T040643-update_row-update-film"
 }
 ```
 
@@ -174,7 +174,7 @@ Answer:
     }
   ],
   "commits": [{ "table": "main.public.film", "version": 8, "operation": "UPDATE" }],
-  "migration_id": "20261012T071951-update_row-update-film-3",
+  "migration_id": "20261019T040643-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: 01a12efb-6c2e-7852-8b4b-ed121d84aec5
+id: 01a15257-1ca9-7d11-a4d0-bc403634a138
 title: Nosferatu
 year: 1922
 status: watched
@@ -246,7 +246,7 @@ Answer:
     }
   ],
   "commits": [{ "table": "main.public.film", "version": 9, "operation": "UPDATE" }],
-  "migration_id": "20261012T071951-update_row-update-film-4"
+  "migration_id": "20261019T040643-update_row-update-film-4"
 }
 ```
 
@@ -332,7 +332,7 @@ Answer:
     }
   ],
   "commits": [{ "table": "main.public.film", "version": 10, "operation": "UPDATE" }],
-  "migration_id": "20261012T071951-update_rows-update-film"
+  "migration_id": "20261019T040643-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": "20261012T071951-merge_rows-merge-2-rows-into-film"
+  "migration_id": "20261019T040643-merge_rows-merge-2-rows-into-film"
 }
 ```
 
@@ -431,7 +431,7 @@ Answer:
     }
   ],
   "commits": [{ "table": "main.public.film", "version": 12, "operation": "DELETE" }],
-  "migration_id": "20261012T071951-delete_rows-archive-1-rows-of-film"
+  "migration_id": "20261019T040643-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": "20261012T071951-move_rows-move-4-rows-from-film-to-watch"
+  "migration_id": "20261019T040643-move_rows-move-4-rows-from-film-to-watch"
 }
 ```

package/dist/docs/guides/search/link-graph.md

@@ -45,6 +45,101 @@ Answer:
 }
 ```
 
+## Read the whole graph in one call
+
+`tables` starts from the rows of several tables at once. Name the tables, or use a pattern: `*` is every table, `main.*` every table of the `main` catalog. With `direction: "out"`, one call returns every link of every row: the whole graph, for an app that draws it. The start set holds at most 5,000 notes.
+
+**`graph_neighbors`**
+
+```json
+{ "from_nodes": { "tables": ["*"] }, "direction": "out" }
+```
+
+Answer (80 lines)
+
+```json
+{
+  "nodes": [
+    {
+      "path": "datanotes/main/public/actor/Audrey Hepburn.md",
+      "table": "main.public.actor",
+      "counts": {},
+      "edges": []
+    },
+    {
+      "path": "datanotes/main/public/actor/Cary Grant.md",
+      "table": "main.public.actor",
+      "counts": {},
+      "edges": []
+    },
+    {
+      "path": "datanotes/main/public/actor/Rosalind Russell.md",
+      "table": "main.public.actor",
+      "counts": {},
+      "edges": []
+    },
+    {
+      "path": "datanotes/main/public/film/Charade.md",
+      "table": "main.public.film",
+      "counts": { "out:cast": 2, "out:link": 1 },
+      "edges": [
+        {
+          "path": "datanotes/main/public/actor/Cary Grant.md",
+          "table": "main.public.actor",
+          "label": "cast",
+          "direction": "out"
+        },
+        {
+          "path": "datanotes/main/public/actor/Audrey Hepburn.md",
+          "table": "main.public.actor",
+          "label": "cast",
+          "direction": "out"
+        },
+        {
+          "path": "datanotes/main/public/film/His Girl Friday.md",
+          "table": "main.public.film",
+          "label": "link",
+          "direction": "out"
+        }
+      ]
+    },
+    {
+      "path": "datanotes/main/public/film/His Girl Friday.md",
+      "table": "main.public.film",
+      "counts": { "out:cast": 2 },
+      "edges": [
+        {
+          "path": "datanotes/main/public/actor/Cary Grant.md",
+          "table": "main.public.actor",
+          "label": "cast",
+          "direction": "out"
+        },
+        {
+          "path": "datanotes/main/public/actor/Rosalind Russell.md",
+          "table": "main.public.actor",
+          "label": "cast",
+          "direction": "out"
+        }
+      ]
+    },
+    {
+      "path": "datanotes/main/public/watch/2026-09-25T2100.md",
+      "table": "main.public.watch",
+      "counts": { "out:film": 1, "out:link": 1 },
+      "edges": [
+        {
+          "path": "datanotes/main/public/film/Charade.md",
+          "table": "main.public.film",
+          "label": "film",
+          "direction": "out"
+        },
+        { "path": "Notes/Film night.md", "label": "link", "direction": "out" }
+      ]
+    }
+  ]
+}
+```
+
 ## Walk the links from a note
 
 `graph_traverse` follows links breadth-first, in the `direction` you choose: `out`, `in` or `both`. Here it starts from Audrey Hepburn, goes up to two steps in both directions and keeps only films. It finds Charade, the film she’s in, and His Girl Friday, which the Charade note links to. `via` shows the route to each one.

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

@@ -87,7 +87,7 @@ Answer (62 lines)
         {
           "start": 81,
           "end": 86,
-          "context": "-bd1b-d5bf80031dd6\nname: Cary Grant\n---\n\n"
+          "context": "-a8aa-d00b2c25ad08\nname: Cary Grant\n---\n\n"
         }
       ]
     },

package/dist/docs/guides/security/who-did-what.md

@@ -31,6 +31,8 @@ A program that serves its own Model Context Protocol (MCP) server can report its
 
 Tool calls appear on the change feed as events with `kind: "tool_call"`, sent only to consumers that ask for that kind. The `call` field holds `tool`, `ok`, `served_by`, `duration_ms`, `summary` and `session`, the arguments cut at 300 characters, the value cut at 1,000, and the result’s size in `result_chars` and `result_tokens`.
 
+A large result costs less to report when the program cuts it first. The engine answers `takes_summary: true` when it accepts a cut call. Then send the value cut at 1,000 characters, and the result’s `summary` next to it. The event is the same as for the whole call. `datanotes mcp` does this after its first report.
+
 ## Read who did what
 
 Three operations read the record:

package/dist/docs/reference/cli.md

@@ -3,7 +3,7 @@
 > The datanotes command and its options.
 
 ```text
-datanotes 3.0.0: Markdown notes as database tables, for you and your agents.
+datanotes 3.2.0: Markdown notes as database tables, for you and your agents.
 
 
 Usage:
@@ -14,12 +14,14 @@ Usage:
   datanotes store new-id --database <folder>      a new database id (a copied folder gets its own store)
   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
   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)
   datanotes mcp --url <url> --token-file <f>   MCP server over stdio, on an engine at an address
   datanotes mcp serve [options]                MCP server over Streamable HTTP at /mcp (each agent sends its token)
   datanotes --version | --help
+  dnotes is a short name for datanotes: every command works under both names.
 
 
 Options of serve:
@@ -49,6 +51,8 @@ Options of serve:
                               between two operations, then a push (or DATANOTES_STORE_BACKUP_INTERVAL_S;
                               default: the setting storeBackupIntervalSeconds, 60)
   --log <file>                append console output to a file
+                              DATANOTES_INDEX_CHECK=1: check the engine's indexes against the vault
+                              after every operation, and log any difference as an error (slow: debugging)
 
 
 Options of status (the engine is found through the lock in its store, called with the owner's token):
@@ -79,7 +83,7 @@ commit and push, releases its lock and exits):
 
 Options of store:
   --database <folder>         the database folder (or DATANOTES_DATABASE; --vault <folder> for a vault)
-  --json                      store path, store backup: the answer as JSON
+  --json                      store path, store backup, store convert-log: the answer as JSON
   --remote <url>              store backup: turn it on, pushing to this git repository (a first push now)
   --ssh-command <cmd>         store backup, with --remote: the store repository's core.sshCommand
                               (default: the vault repository's), e.g. C:/Windows/System32/OpenSSH/ssh.exe
@@ -90,7 +94,10 @@ Options of store:
   --port <port>               store restore: the HTTP port in the new settings (default 27150)
   --force                     store restore: restore over a store that exists (kept aside, renamed)
   --no-backup                 store restore: leave the store backup off in the new settings
-  backup and restore change the store only while no engine runs on the database.
+  --to <files|segments>       store convert-log: segments (a few large files) or files (one per
+                              version, what Datanotes 3.0 reads); sets transactionLogFormat
+  new-id, backup, restore and convert-log run only while no engine runs on the database, and
+  hold its store while they run: an engine started meanwhile refuses to start.
   The data home holds one store per database: %LOCALAPPDATA%\Datanotes (Windows),
   ~/Library/Application Support/Datanotes (macOS), $XDG_DATA_HOME/datanotes or
   ~/.local/share/datanotes (Linux); DATANOTES_DATA_HOME moves it.

package/dist/docs/reference/compatibility.md

@@ -1,25 +1,29 @@
 # Compatibility
 
-> What Datanotes 3 promises: every 3.x version adds to what you use and never takes it away.
+> How Datanotes numbers its versions, what counts as its public interface, and how to write clients that keep working.
 
-Datanotes 3 keeps working with your programs, scripts and vaults in every 3.x version. The number after the 3 only says how recent a release is: 3.1, 3.2, and on.
+Datanotes follows [semantic versioning](https://semver.org). The version number tells you what an update can change.
 
-## The promise
+## Versions
 
-What works in Datanotes 3 keeps working the same way in every 3.x version:
+* **Major** (4.0.0): can change or remove parts of the public interface. The release notes list those changes first, with what to do.
+* **Minor** (3.1.0): adds to the public interface without breaking what works.
+* **Patch** (3.0.1): fixes bugs and changes nothing you rely on.
+
+The [release notes](https://datanotes.dev/release-notes/) describe every version.
+
+## The public interface
+
+These parts of Datanotes follow the version rules:
 
 * Operations, their arguments and their answer fields
 * HTTP routes and headers
 * Violation codes
-* Commands, their options and their exit codes
+* The commands the package installs (`datanotes` and `dnotes`), their options and their exit codes
 * Environment variables and settings
 * The words of `metastore.yaml`
 
-A new version can add to these. It never removes or renames them, and a name never changes meaning. When Datanotes needs a different behavior, it adds a new name. The old name keeps doing what it did.
-
-For example, a program that calls `insert_row` with `table` and `values`, then reads `planned_creates`, works with every 3.x version. A later version can add an optional argument, a new answer field or a new operation, and the program doesn’t notice.
-
-These cases fall outside the promise:
+These cases fall outside them:
 
 * **Security fixes**: a fix can change a behavior. The release notes say so.
 * **Bugs**: Datanotes fixes behavior that contradicts the documentation.
@@ -27,6 +31,22 @@ These cases fall outside the promise:
 * **Messages**: the text of refusals and hints can improve in any version.
 * **Node.js versions**: support follows the Node.js long-term support releases.
 
+## Downgrade to 3.0
+
+From 3.1, the engine writes the transaction log in segments by default. Datanotes 3.0 can’t read segments, so convert the log before you downgrade:
+
+1. Stop the engine.
+
+2. Convert every table’s log to one file per version:
+
+   ```bash
+   datanotes store convert-log --to files --vault ~/notes
+   ```
+
+3. Install Datanotes 3.0 and start it.
+
+The command also sets `transactionLogFormat` to `files`, so a 3.1 engine started on the store again keeps writing files. [How the engine writes the log](https://datanotes.dev/start/how-it-works/#how-the-engine-writes-the-log) describes both formats.
+
 ## Write tolerant clients
 
 Answers can gain fields, and enums can gain values. Write your client to accept them:
@@ -56,8 +76,8 @@ const r = await db.call("insert_row", {
 if (r.ok) console.log((r.value as Created).planned_creates);
 ```
 
-## How Datanotes keeps it
+## How the tests check it
 
-The repository keeps the whole public contract in `contract/datanotes-3.txt`. It has one line for every operation, argument, answer field, route, command option, environment variable, setting and violation code.
+The repository keeps the public interface in `contract/datanotes-3.txt`. It has one line for every operation, argument, answer field, route, installed command, command option, environment variable, setting and violation code.
 
-The test suite fails when a line goes or changes, so a machine checks the promise. A second test checks every new name against the naming rules before it ships.
+The test suite fails when a line goes or changes within a major version, so a breaking change cannot ship by accident. A second test checks every new name against the naming rules.

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/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/).