datanotes 3.0.0 → 3.2.0

package/dist/docs/guides/database-objects/tables.md

@@ -58,7 +58,7 @@ Answer:
 ```json
 {
   "ok": true,
-  "migration_id": "20261012T071946-create_table-create-table-main-public-film",
+  "migration_id": "20261019T040638-create_table-create-table-main-public-film",
   "summary": null
 }
 ```
@@ -67,7 +67,7 @@ Answer:
 
 ```yaml
 # Metastore (Datanotes): catalogs, schemas, tables, columns, views.
-id: 01a12efb-589d-722c-bc9b-81ec34e480a4
+id: 01a15257-09b6-7466-9ee6-59ac45171fa4
 config:
   history: true
 
@@ -305,10 +305,11 @@ Answer (83 lines)
 
 ## Add fixed front matter keys, a note template and tags
 
-`create_table` takes three more arguments:
+`create_table` takes four more arguments:
 
 * **`fields`**: front matter keys every new row gets with a fixed value and no checks, such as `cssclasses`, which styles the notes in Obsidian
 * **`row_template`**: the text of every new row’s note, with `{column}` placeholders
+* **`instructions`**: how an agent fills a row, such as which columns come first and what to ask you
 * **`tags`**: key/value labels for the table, which `list_tables` and `describe_table` return
 
 **`create_table`**
@@ -353,6 +354,7 @@ Answer (83 lines)
   "filename": "{occurred_at:YYYY-MM-DD} {film}",
   "fields": { "cssclasses": ["watch"] },
   "row_template": "Watched {film} ({where}).\n\n## Thoughts\n",
+  "instructions": "1. Ask me which film I watched and where.\n2. Fill `occurred_at` only when I give a time: it defaults to now.\n",
   "tags": { "area": "films" }
 }
 ```
@@ -377,24 +379,24 @@ Answer:
   "ok": true,
   "op": "insert_row",
   "files_created": 1,
-  "planned_creates": ["datanotes/main/public/watch/2026-10-12 Nosferatu.md"],
+  "planned_creates": ["datanotes/main/public/watch/2026-10-19 Nosferatu.md"],
   "commits": [{ "table": "main.public.watch", "version": 1, "operation": "WRITE" }],
-  "migration_id": "20261012T071946-insert_row-insert-into-watch"
+  "migration_id": "20261019T040638-insert_row-insert-into-watch"
 }
 ```
 
-`datanotes/main/public/watch/2026-10-12 Nosferatu.md` now reads:
+`datanotes/main/public/watch/2026-10-19 Nosferatu.md` now reads:
 
 ```markdown
 ---
 table: main.public.watch
 cssclasses:
   - watch
-id: 01a12efb-596f-7f8d-a613-98700dbd6bde
+id: 01a15257-0aa0-7f95-8445-28bb94536020
 film: Nosferatu
 where: outdoor screening
 place: the park by the river
-occurred_at: 2026-10-12T07:19:46Z
+occurred_at: 2026-10-19T04:06:38Z
 ---
 Watched Nosferatu (outdoor screening).
 
@@ -402,6 +404,46 @@ Watched Nosferatu (outdoor screening).
 ## Thoughts
 ```
 
+## Tell agents how to fill a row with `instructions`
+
+`describe_table` returns a table’s `instructions`, so an agent reads them before it writes a row. `alter_table` changes them, and `instructions: ""` removes them.
+
+**`describe_table`**
+
+```json
+{ "table": "watch" }
+```
+
+Answer:
+
+```json
+{
+  "qualified": "main.public.watch",
+  "instructions": "1. Ask me which film I watched and where.\n2. Fill `occurred_at` only when I give a time: it defaults to now.\n"
+}
+```
+
+**`alter_table`**
+
+```json
+{
+  "table": "watch",
+  "instructions": "1. Ask me which film I watched, where and with whom.\n2. Fill `occurred_at` only when I give a time: it defaults to now.\n"
+}
+```
+
+Answer:
+
+```json
+{
+  "ok": true,
+  "op": "alter_table",
+  "planned_texts": ["datanotes/metastore.yaml"],
+  "commits": [{ "table": "main.public.watch", "version": 2, "operation": "ALTER TABLE" }],
+  "migration_id": "20261019T040638-alter_table-alter-table-main-public-watch"
+}
+```
+
 ## Set a table’s options when you create it
 
 `create_table` also takes the options that `alter_table` changes later. Two of them:
@@ -465,28 +507,8 @@ Answer:
   ],
   "planned_moves": [
     {
-      "from": "store:transaction_log/diary.classics.actors/00000000000000000000.json",
-      "to": "store:transaction_log/diary.classics.actor/00000000000000000000.json"
-    },
-    {
-      "from": "store:transaction_log/diary.classics.actors/00000000000000000001.json",
-      "to": "store:transaction_log/diary.classics.actor/00000000000000000001.json"
-    },
-    {
-      "from": "store:transaction_log/diary.classics.actors/00000000000000000002.json",
-      "to": "store:transaction_log/diary.classics.actor/00000000000000000002.json"
-    },
-    {
-      "from": "store:transaction_log/diary.classics.actors/00000000000000000003.json",
-      "to": "store:transaction_log/diary.classics.actor/00000000000000000003.json"
-    },
-    {
-      "from": "store:transaction_log/diary.classics.actors/00000000000000000004.json",
-      "to": "store:transaction_log/diary.classics.actor/00000000000000000004.json"
-    },
-    {
-      "from": "store:transaction_log/diary.classics.actors/00000000000000000005.json",
-      "to": "store:transaction_log/diary.classics.actor/00000000000000000005.json"
+      "from": "store:transaction_log/diary.classics.actors/00000000000000000000.segment.jsonl",
+      "to": "store:transaction_log/diary.classics.actor/00000000000000000000.segment.jsonl"
     },
     {
       "from": "datanotes/diary/classics/actors/Max Schreck.md",
@@ -503,14 +525,14 @@ Answer:
 { "table": "classics.actors", "name": "actor" }
 ```
 
-Answer (48 lines)
+Answer:
 
 ```json
 {
   "ok": true,
   "op": "alter_table",
   "notes_changed": 1,
-  "files_moved": 7,
+  "files_moved": 2,
   "planned_edits": [
     {
       "path": "datanotes/diary/classics/actors/Max Schreck.md",
@@ -520,28 +542,8 @@ Answer (48 lines)
   ],
   "planned_moves": [
     {
-      "from": "store:transaction_log/diary.classics.actors/00000000000000000000.json",
-      "to": "store:transaction_log/diary.classics.actor/00000000000000000000.json"
-    },
-    {
-      "from": "store:transaction_log/diary.classics.actors/00000000000000000001.json",
-      "to": "store:transaction_log/diary.classics.actor/00000000000000000001.json"
-    },
-    {
-      "from": "store:transaction_log/diary.classics.actors/00000000000000000002.json",
-      "to": "store:transaction_log/diary.classics.actor/00000000000000000002.json"
-    },
-    {
-      "from": "store:transaction_log/diary.classics.actors/00000000000000000003.json",
-      "to": "store:transaction_log/diary.classics.actor/00000000000000000003.json"
-    },
-    {
-      "from": "store:transaction_log/diary.classics.actors/00000000000000000004.json",
-      "to": "store:transaction_log/diary.classics.actor/00000000000000000004.json"
-    },
-    {
-      "from": "store:transaction_log/diary.classics.actors/00000000000000000005.json",
-      "to": "store:transaction_log/diary.classics.actor/00000000000000000005.json"
+      "from": "store:transaction_log/diary.classics.actors/00000000000000000000.segment.jsonl",
+      "to": "store:transaction_log/diary.classics.actor/00000000000000000000.segment.jsonl"
     },
     {
       "from": "datanotes/diary/classics/actors/Max Schreck.md",
@@ -552,7 +554,7 @@ Answer (48 lines)
   "commits": [
     { "table": "diary.classics.actor", "version": 6, "operation": "ALTER TABLE" }
   ],
-  "migration_id": "20261012T072004-alter_table-move-table-diary-classics-acto"
+  "migration_id": "20261019T040655-alter_table-move-table-diary-classics-acto"
 }
 ```
 
@@ -564,14 +566,14 @@ Then move it to a schema of its own:
 { "table": "classics.actor", "catalog": "diary", "schema": "credits" }
 ```
 
-Answer (52 lines)
+Answer:
 
 ```json
 {
   "ok": true,
   "op": "alter_table",
   "notes_changed": 1,
-  "files_moved": 8,
+  "files_moved": 2,
   "planned_edits": [
     {
       "path": "datanotes/diary/classics/actor/Max Schreck.md",
@@ -581,32 +583,8 @@ Answer (52 lines)
   ],
   "planned_moves": [
     {
-      "from": "store:transaction_log/diary.classics.actor/00000000000000000000.json",
-      "to": "store:transaction_log/diary.credits.actor/00000000000000000000.json"
-    },
-    {
-      "from": "store:transaction_log/diary.classics.actor/00000000000000000001.json",
-      "to": "store:transaction_log/diary.credits.actor/00000000000000000001.json"
-    },
-    {
-      "from": "store:transaction_log/diary.classics.actor/00000000000000000002.json",
-      "to": "store:transaction_log/diary.credits.actor/00000000000000000002.json"
-    },
-    {
-      "from": "store:transaction_log/diary.classics.actor/00000000000000000003.json",
-      "to": "store:transaction_log/diary.credits.actor/00000000000000000003.json"
-    },
-    {
-      "from": "store:transaction_log/diary.classics.actor/00000000000000000004.json",
-      "to": "store:transaction_log/diary.credits.actor/00000000000000000004.json"
-    },
-    {
-      "from": "store:transaction_log/diary.classics.actor/00000000000000000005.json",
-      "to": "store:transaction_log/diary.credits.actor/00000000000000000005.json"
-    },
-    {
-      "from": "store:transaction_log/diary.classics.actor/00000000000000000006.json",
-      "to": "store:transaction_log/diary.credits.actor/00000000000000000006.json"
+      "from": "store:transaction_log/diary.classics.actor/00000000000000000000.segment.jsonl",
+      "to": "store:transaction_log/diary.credits.actor/00000000000000000000.segment.jsonl"
     },
     {
       "from": "datanotes/diary/classics/actor/Max Schreck.md",
@@ -617,7 +595,7 @@ Answer (52 lines)
   "commits": [
     { "table": "diary.credits.actor", "version": 7, "operation": "ALTER TABLE" }
   ],
-  "migration_id": "20261012T072004-alter_table-move-table-diary-classics-acto-2"
+  "migration_id": "20261019T040655-alter_table-move-table-diary-classics-acto-2"
 }
 ```
 
@@ -681,7 +659,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.film", "version": 13, "operation": "ALTER TABLE" }
   ],
-  "migration_id": "20261012T072004-alter_table-alter-table-diary-classics-fil"
+  "migration_id": "20261019T040655-alter_table-alter-table-diary-classics-fil-5"
 }
 ```
 
@@ -733,7 +711,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.film", "version": 14, "operation": "ALTER TABLE" }
   ],
-  "migration_id": "20261012T072004-alter_table-alter-table-diary-classics-fil-2"
+  "migration_id": "20261019T040655-alter_table-alter-table-diary-classics-fil-6"
 }
 ```
 
@@ -775,7 +753,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.film", "version": 15, "operation": "ALTER TABLE" }
   ],
-  "migration_id": "20261012T072004-alter_table-alter-table-diary-classics-fil-3"
+  "migration_id": "20261019T040655-alter_table-alter-table-diary-classics-fil-7"
 }
 ```
 
@@ -795,7 +773,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.film", "version": 16, "operation": "ALTER TABLE" }
   ],
-  "migration_id": "20261012T072004-alter_table-alter-table-diary-classics-fil-4"
+  "migration_id": "20261019T040655-alter_table-alter-table-diary-classics-fil-8"
 }
 ```
 
@@ -815,7 +793,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.film", "version": 17, "operation": "ALTER TABLE" }
   ],
-  "migration_id": "20261012T072004-alter_table-alter-table-diary-classics-fil-5"
+  "migration_id": "20261019T040655-alter_table-alter-table-diary-classics-fil-9"
 }
 ```
 
@@ -842,7 +820,7 @@ Answer:
   "files_created": 1,
   "planned_creates": ["datanotes/diary/classics/film/1925/Battleship Potemkin (1925).md"],
   "commits": [{ "table": "diary.classics.film", "version": 18, "operation": "WRITE" }],
-  "migration_id": "20261012T072004-insert_row-insert-into-film-3"
+  "migration_id": "20261019T040655-insert_row-insert-into-film-4"
 }
 ```
 
@@ -852,7 +830,7 @@ Answer:
 ---
 table: diary.classics.film
 cut: restored
-id: 01a12efb-9da0-70b8-9f73-bb00b210e05f
+id: 01a15257-4d4f-7108-9b86-834bf7261cc6
 title: Battleship Potemkin
 year: 1925
 minutes: 75
@@ -883,7 +861,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.film", "version": 19, "operation": "ALTER TABLE" }
   ],
-  "migration_id": "20261012T072004-alter_table-alter-table-diary-classics-fil-6"
+  "migration_id": "20261019T040655-alter_table-alter-table-diary-classics-fil-10"
 }
 ```
 
@@ -905,7 +883,7 @@ Answer:
   "files_created": 1,
   "planned_creates": ["datanotes/diary/classics/film/1924/Sherlock Jr. (1924).md"],
   "commits": [{ "table": "diary.classics.film", "version": 20, "operation": "WRITE" }],
-  "migration_id": "20261012T072004-insert_row-insert-into-film-4"
+  "migration_id": "20261019T040655-insert_row-insert-into-film-5"
 }
 ```
 
@@ -915,7 +893,7 @@ Answer:
 ---
 table: diary.classics.film
 cut: restored
-id: 01a12efb-9dba-741f-a279-de88358083ce
+id: 01a15257-4d65-7ac8-9da9-cebd6bcb8f00
 title: Sherlock Jr.
 year: 1924
 minutes: 45
@@ -948,7 +926,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.film", "version": 21, "operation": "ALTER TABLE" }
   ],
-  "migration_id": "20261012T072004-alter_table-alter-table-diary-classics-fil-7"
+  "migration_id": "20261019T040655-alter_table-alter-table-diary-classics-fil-11"
 }
 ```
 
@@ -1030,7 +1008,7 @@ Answer:
 ```json
 {
   "ok": true,
-  "migration_id": "20261012T072004-create_table-create-table-diary-log-watch"
+  "migration_id": "20261019T040655-create_table-create-table-diary-log-watch"
 }
 ```
 
@@ -1059,7 +1037,7 @@ Answer:
   "files_created": 1,
   "planned_creates": ["datanotes/diary/log/watch/2026/10/2026-10-06 2130.md"],
   "commits": [{ "table": "diary.log.watch", "version": 1, "operation": "WRITE" }],
-  "migration_id": "20261012T072004-insert_row-insert-into-watch"
+  "migration_id": "20261019T040655-insert_row-insert-into-watch"
 }
 ```
 
@@ -1068,7 +1046,7 @@ Answer:
 ```markdown
 ---
 table: diary.log.watch
-id: 01a12efb-9e05-7ed2-95c8-870d481fea29
+id: 01a15257-4da6-75c4-814b-80ede5508ccc
 film: "[[Nosferatu (1922)]]"
 occurred_at: 2026-10-06T21:30:00+02:00
 where: outdoor screening
@@ -1104,7 +1082,7 @@ Answer:
   "commits": [
     { "table": "sandbox.classics.film_copy", "version": 0, "operation": "CLONE" }
   ],
-  "migration_id": "20261012T072004-clone_table-clone-diary-classics-film-to-s"
+  "migration_id": "20261019T040655-clone_table-clone-diary-classics-film-to-s"
 }
 ```
 
@@ -1170,7 +1148,7 @@ Answer:
   "commits": [
     { "table": "sandbox.classics.film_empty", "version": 0, "operation": "CLONE" }
   ],
-  "migration_id": "20261012T072004-clone_table-clone-diary-classics-film-to-s-2"
+  "migration_id": "20261019T040655-clone_table-clone-diary-classics-film-to-s-2"
 }
 ```
 
@@ -1252,7 +1230,7 @@ Answer:
   ],
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [{ "table": "main.public.scratch", "version": 2, "operation": "DROP TABLE" }],
-  "migration_id": "20261012T071946-drop_table-drop-table-scratch"
+  "migration_id": "20261019T040638-drop_table-drop-table-scratch"
 }
 ```
 
@@ -1276,7 +1254,7 @@ The engine wrote this file in its own words. It holds `film`, `watch` and `revie
 
 ```yaml
 # Metastore (Datanotes): catalogs, schemas, tables, columns, views.
-id: 01a12efb-589d-722c-bc9b-81ec34e480a4
+id: 01a15257-09b6-7466-9ee6-59ac45171fa4
 config:
   history: true
 
@@ -1335,6 +1313,14 @@ catalogs:
             description: Each time I watch a film
             tags:
               area: films
+            row_template: |
+              Watched {film} ({where}).
+
+
+              ## Thoughts
+            instructions: |
+              1. Ask me which film I watched, where and with whom.
+              2. Fill `occurred_at` only when I give a time: it defaults to now.
             options:
               filename: "{occurred_at:YYYY-MM-DD} {film}"
               archive: _archive
@@ -1344,11 +1330,11 @@ catalogs:
             columns:
               - name: id
                 type: string
-                required: true
-                description: "Unique id of the row (UUIDv7): set when the row is created, never changes"
                 unique: true
                 identity: uuid
+                required: true
                 dense: true
+                description: "Unique id of the row (UUIDv7): set when the row is created, never changes"
               - name: film
                 type: string
                 required: true
@@ -1373,11 +1359,6 @@ catalogs:
                 min: 0
                 step: 0.01
                 description: What the ticket cost, if anything
-            row_template: |
-              Watched {film} ({where}).
-
-
-              ## Thoughts
           review:
             description: What I wrote about a film after watching it
             options: