datanotes 3.1.0 → 3.3.0

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

@@ -58,7 +58,7 @@ Answer:
 ```json
 {
   "ok": true,
-  "migration_id": "20261014T191515-create_table-create-table-main-public-film",
+  "migration_id": "20261020T173828-create_table-create-table-main-public-film",
   "summary": null
 }
 ```
@@ -67,7 +67,7 @@ Answer:
 
 ```yaml
 # Metastore (Datanotes): catalogs, schemas, tables, columns, views.
-id: 01a13bd7-1943-7bc6-ab38-ab176313afeb
+id: 01a15a64-a676-7657-9ff4-7a1e6bcc5df3
 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-14 Nosferatu.md"],
+  "planned_creates": ["datanotes/main/public/watch/2026-10-20 Nosferatu.md"],
   "commits": [{ "table": "main.public.watch", "version": 1, "operation": "WRITE" }],
-  "migration_id": "20261014T191515-insert_row-insert-into-watch"
+  "migration_id": "20261020T173828-insert_row-insert-into-watch"
 }
 ```
 
-`datanotes/main/public/watch/2026-10-14 Nosferatu.md` now reads:
+`datanotes/main/public/watch/2026-10-20 Nosferatu.md` now reads:
 
 ```markdown
 ---
 table: main.public.watch
 cssclasses:
   - watch
-id: 01a13bd7-1c3b-7687-845d-b10ea8ff95a2
+id: 01a15a64-a8fb-73f8-a4e2-4263d12c1d9d
 film: Nosferatu
 where: outdoor screening
 place: the park by the river
-occurred_at: 2026-10-14T19:15:15Z
+occurred_at: 2026-10-20T17:38:28Z
 ---
 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": "20261020T173828-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:
@@ -512,7 +554,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.actor", "version": 6, "operation": "ALTER TABLE" }
   ],
-  "migration_id": "20261014T191534-alter_table-move-table-diary-classics-acto"
+  "migration_id": "20261020T173845-alter_table-move-table-diary-classics-acto"
 }
 ```
 
@@ -553,7 +595,7 @@ Answer:
   "commits": [
     { "table": "diary.credits.actor", "version": 7, "operation": "ALTER TABLE" }
   ],
-  "migration_id": "20261014T191534-alter_table-move-table-diary-classics-acto-2"
+  "migration_id": "20261020T173845-alter_table-move-table-diary-classics-acto-2"
 }
 ```
 
@@ -617,7 +659,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.film", "version": 13, "operation": "ALTER TABLE" }
   ],
-  "migration_id": "20261014T191534-alter_table-alter-table-diary-classics-fil-5"
+  "migration_id": "20261020T173845-alter_table-alter-table-diary-classics-fil-3"
 }
 ```
 
@@ -669,7 +711,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.film", "version": 14, "operation": "ALTER TABLE" }
   ],
-  "migration_id": "20261014T191534-alter_table-alter-table-diary-classics-fil-6"
+  "migration_id": "20261020T173845-alter_table-alter-table-diary-classics-fil-4"
 }
 ```
 
@@ -711,7 +753,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.film", "version": 15, "operation": "ALTER TABLE" }
   ],
-  "migration_id": "20261014T191534-alter_table-alter-table-diary-classics-fil-7"
+  "migration_id": "20261020T173845-alter_table-alter-table-diary-classics-fil-5"
 }
 ```
 
@@ -731,7 +773,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.film", "version": 16, "operation": "ALTER TABLE" }
   ],
-  "migration_id": "20261014T191534-alter_table-alter-table-diary-classics-fil-8"
+  "migration_id": "20261020T173845-alter_table-alter-table-diary-classics-fil-6"
 }
 ```
 
@@ -751,7 +793,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.film", "version": 17, "operation": "ALTER TABLE" }
   ],
-  "migration_id": "20261014T191534-alter_table-alter-table-diary-classics-fil-9"
+  "migration_id": "20261020T173845-alter_table-alter-table-diary-classics-fil-7"
 }
 ```
 
@@ -778,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": "20261014T191534-insert_row-insert-into-film-4"
+  "migration_id": "20261020T173845-insert_row-insert-into-film-3"
 }
 ```
 
@@ -788,7 +830,7 @@ Answer:
 ---
 table: diary.classics.film
 cut: restored
-id: 01a13bd7-6708-7c51-9bc8-ec11609a2c93
+id: 01a15a64-ea48-70a1-84d2-829cc3c9da62
 title: Battleship Potemkin
 year: 1925
 minutes: 75
@@ -819,7 +861,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.film", "version": 19, "operation": "ALTER TABLE" }
   ],
-  "migration_id": "20261014T191534-alter_table-alter-table-diary-classics-fil-10"
+  "migration_id": "20261020T173845-alter_table-alter-table-diary-classics-fil-8"
 }
 ```
 
@@ -841,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": "20261014T191534-insert_row-insert-into-film-5"
+  "migration_id": "20261020T173845-insert_row-insert-into-film-4"
 }
 ```
 
@@ -851,7 +893,7 @@ Answer:
 ---
 table: diary.classics.film
 cut: restored
-id: 01a13bd7-6717-7265-ac31-ce2823c07dc6
+id: 01a15a64-ea5e-737b-a2ef-e105a2e98fdc
 title: Sherlock Jr.
 year: 1924
 minutes: 45
@@ -884,7 +926,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.film", "version": 21, "operation": "ALTER TABLE" }
   ],
-  "migration_id": "20261014T191534-alter_table-alter-table-diary-classics-fil-11"
+  "migration_id": "20261020T173845-alter_table-alter-table-diary-classics-fil-9"
 }
 ```
 
@@ -966,7 +1008,7 @@ Answer:
 ```json
 {
   "ok": true,
-  "migration_id": "20261014T191534-create_table-create-table-diary-log-watch"
+  "migration_id": "20261020T173845-create_table-create-table-diary-log-watch"
 }
 ```
 
@@ -995,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": "20261014T191534-insert_row-insert-into-watch"
+  "migration_id": "20261020T173845-insert_row-insert-into-watch"
 }
 ```
 
@@ -1004,7 +1046,7 @@ Answer:
 ```markdown
 ---
 table: diary.log.watch
-id: 01a13bd7-6747-7f6c-aff2-ff81497a9a02
+id: 01a15a64-eaa5-7d15-957a-55f01a116533
 film: "[[Nosferatu (1922)]]"
 occurred_at: 2026-10-06T21:30:00+02:00
 where: outdoor screening
@@ -1040,7 +1082,7 @@ Answer:
   "commits": [
     { "table": "sandbox.classics.film_copy", "version": 0, "operation": "CLONE" }
   ],
-  "migration_id": "20261014T191534-clone_table-clone-diary-classics-film-to-s"
+  "migration_id": "20261020T173845-clone_table-clone-diary-classics-film-to-s"
 }
 ```
 
@@ -1106,7 +1148,7 @@ Answer:
   "commits": [
     { "table": "sandbox.classics.film_empty", "version": 0, "operation": "CLONE" }
   ],
-  "migration_id": "20261014T191534-clone_table-clone-diary-classics-film-to-s-2"
+  "migration_id": "20261020T173845-clone_table-clone-diary-classics-film-to-s-2"
 }
 ```
 
@@ -1188,7 +1230,7 @@ Answer:
   ],
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [{ "table": "main.public.scratch", "version": 2, "operation": "DROP TABLE" }],
-  "migration_id": "20261014T191516-drop_table-drop-table-scratch"
+  "migration_id": "20261020T173828-drop_table-drop-table-scratch"
 }
 ```
 
@@ -1212,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: 01a13bd7-1943-7bc6-ab38-ab176313afeb
+id: 01a15a64-a676-7657-9ff4-7a1e6bcc5df3
 config:
   history: true
 
@@ -1271,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
@@ -1280,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
@@ -1309,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:

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

@@ -41,7 +41,7 @@ Answer:
   "ok": true,
   "op": "create_view",
   "planned_texts": ["datanotes/metastore.yaml"],
-  "migration_id": "20261014T191527-create_view-create-view-main-public-vw_rec"
+  "migration_id": "20261020T173838-create_view-create-view-main-public-vw_rec"
 }
 ```
 
@@ -65,16 +65,16 @@ Answer:
   "total": 2,
   "rows": [
     {
-      "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-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"
     }
@@ -156,7 +156,7 @@ Answer:
   "ok": true,
   "op": "create_view",
   "planned_texts": ["datanotes/metastore.yaml"],
-  "migration_id": "20261014T191527-create_view-create-view-main-public-vw_rec-2"
+  "migration_id": "20261020T173838-create_view-create-view-main-public-vw_rec-2"
 }
 ```
 
@@ -194,7 +194,7 @@ Answer:
   "ok": true,
   "op": "create_view",
   "planned_texts": ["datanotes/metastore.yaml"],
-  "migration_id": "20261014T191527-create_view-create-view-main-public-vw_las"
+  "migration_id": "20261020T173838-create_view-create-view-main-public-vw_las"
 }
 ```
 
@@ -214,59 +214,59 @@ Answer (65 lines)
     {
       "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",
       "cast": [
         {
           "path": "datanotes/main/public/actor/Duane Jones.md",
           "table": "main.public.actor",
-          "id": "01a13bd7-4abf-73f1-b8cf-f4d072fd5faa",
+          "id": "01a15a64-cd02-7854-912e-cabd75c26751",
           "name": "Duane Jones",
           "born": "1937-04-02"
         }
       ],
       "viewing": [
-        { "path": "datanotes/main/public/watch/2026-10-13T2200.md", "where": "cinema" }
+        { "path": "datanotes/main/public/watch/2026-10-19T2200.md", "where": "cinema" }
       ]
     },
     {
       "path": "datanotes/main/public/film/The Gold Rush.md",
       "title": "The Gold Rush",
-      "watched_on": "2026-10-12",
+      "watched_on": "2026-10-18",
       "cast": [
         {
           "path": "datanotes/main/public/actor/Charlie Chaplin.md",
           "table": "main.public.actor",
-          "id": "01a13bd7-4a97-7250-b9b6-b9b6170ddca7",
+          "id": "01a15a64-cce6-7e75-ad76-6a1acf6fdf25",
           "name": "Charlie Chaplin",
           "born": "1889-04-16"
         }
       ],
       "viewing": [
-        { "path": "datanotes/main/public/watch/2026-10-12T2030.md", "where": "home" }
+        { "path": "datanotes/main/public/watch/2026-10-18T2030.md", "where": "home" }
       ]
     },
     {
       "path": "datanotes/main/public/film/Charade.md",
       "title": "Charade",
-      "watched_on": "2026-10-09",
+      "watched_on": "2026-10-15",
       "cast": [
         {
           "path": "datanotes/main/public/actor/Cary Grant.md",
           "table": "main.public.actor",
-          "id": "01a13bd7-4ab2-7812-a387-d772ffb3490f",
+          "id": "01a15a64-ccf1-7ea6-a4ba-74e39aef4496",
           "name": "Cary Grant",
           "born": "1904-01-18"
         },
         {
           "path": "datanotes/main/public/actor/Audrey Hepburn.md",
           "table": "main.public.actor",
-          "id": "01a13bd7-4abb-77f8-82af-5c32a8a392ef",
+          "id": "01a15a64-ccfc-73b5-8bf8-e5a988156438",
           "name": "Audrey Hepburn",
           "born": "1929-05-04"
         }
       ],
       "viewing": [
-        { "path": "datanotes/main/public/watch/2026-10-09T2115.md", "where": "home" }
+        { "path": "datanotes/main/public/watch/2026-10-15T2115.md", "where": "home" }
       ]
     }
   ],
@@ -313,7 +313,7 @@ Answer:
   "ok": true,
   "op": "create_view",
   "planned_texts": ["datanotes/metastore.yaml"],
-  "migration_id": "20261014T191527-create_view-create-view-main-public-vw_mos"
+  "migration_id": "20261020T173838-create_view-create-view-main-public-vw_mos"
 }
 ```
 
@@ -382,7 +382,7 @@ Answer:
   "ok": true,
   "op": "create_view",
   "planned_texts": ["datanotes/metastore.yaml"],
-  "migration_id": "20261014T191527-create_view-create-view-main-public-vw_lat"
+  "migration_id": "20261020T173838-create_view-create-view-main-public-vw_lat"
 }
 ```
 
@@ -400,59 +400,59 @@ Answer (64 lines)
   "total": 4,
   "rows": [
     {
-      "path": "datanotes/main/public/watch/2026-10-13T2200.md",
+      "path": "datanotes/main/public/watch/2026-10-19T2200.md",
       "film": {
         "path": "datanotes/main/public/film/Night of the Living Dead.md",
         "table": "main.public.film",
-        "id": "01a13bd7-4aed-7b64-aca1-e6517bf168a3",
+        "id": "01a15a64-cd43-7e4e-8275-3d766d831eab",
         "title": "Night of the Living Dead",
         "year": 1968,
         "minutes": 96,
         "status": "watched",
         "rating": 4,
-        "watched_on": "2026-10-13",
+        "watched_on": "2026-10-19",
         "director": "George A. Romero",
         "cast": ["[[Duane Jones]]"]
       },
-      "occurred_at": "2026-10-13T22:00",
+      "occurred_at": "2026-10-19T22:00",
       "where": "cinema",
       "_source": "watch"
     },
     {
-      "path": "datanotes/main/public/watch/2026-10-12T2030.md",
+      "path": "datanotes/main/public/watch/2026-10-18T2030.md",
       "film": {
         "path": "datanotes/main/public/film/The Gold Rush.md",
         "table": "main.public.film",
-        "id": "01a13bd7-4ad9-7724-94df-193a3c583568",
+        "id": "01a15a64-cd27-7bc5-ac61-1712f0e17cb4",
         "title": "The Gold Rush",
         "year": 1925,
         "minutes": 95,
         "status": "watched",
         "rating": 5,
-        "watched_on": "2026-10-12",
+        "watched_on": "2026-10-18",
         "director": "Charlie Chaplin",
         "cast": ["[[Charlie Chaplin]]"]
       },
-      "occurred_at": "2026-10-12T20:30",
+      "occurred_at": "2026-10-18T20:30",
       "where": "home",
       "_source": "watch"
     },
     {
-      "path": "datanotes/main/public/watch/2026-10-09T2115.md",
+      "path": "datanotes/main/public/watch/2026-10-15T2115.md",
       "film": {
         "path": "datanotes/main/public/film/Charade.md",
         "table": "main.public.film",
-        "id": "01a13bd7-4ae8-7374-8fea-abdb574685ed",
+        "id": "01a15a64-cd3c-767c-8c4e-bd40e8b9597f",
         "title": "Charade",
         "year": 1963,
         "minutes": 113,
         "status": "watched",
         "rating": 4,
-        "watched_on": "2026-10-09",
+        "watched_on": "2026-10-15",
         "director": "Stanley Donen",
         "cast": ["[[Cary Grant]]", "[[Audrey Hepburn]]"]
       },
-      "occurred_at": "2026-10-09T21:15",
+      "occurred_at": "2026-10-15T21:15",
       "where": "home",
       "_source": "watch"
     }
@@ -476,14 +476,14 @@ Answer:
   "ok": true,
   "op": "drop_view",
   "planned_texts": ["datanotes/metastore.yaml"],
-  "migration_id": "20261014T191527-drop_view-drop-view-main-public-vw_most_"
+  "migration_id": "20261020T173838-drop_view-drop-view-main-public-vw_most_"
 }
 ```
 
 **`undo_migration`**
 
 ```json
-{ "migration_id": "20261014T191527-drop_view-drop-view-main-public-vw_most_" }
+{ "migration_id": "20261020T173838-drop_view-drop-view-main-public-vw_most_" }
 ```
 
 Answer:
@@ -492,8 +492,8 @@ Answer:
 {
   "ok": true,
   "op": "undo_migration",
-  "undoes": "20261014T191527-drop_view-drop-view-main-public-vw_most_",
-  "migration_id": "20261014T191527-undo_migration-undo-20261014t191527-drop_view",
+  "undoes": "20261020T173838-drop_view-drop-view-main-public-vw_most_",
+  "migration_id": "20261020T173838-undo_migration-undo-20261020t173838-drop_view",
   "conflicts": [],
   "failed": []
 }
@@ -526,7 +526,7 @@ Answer:
   "ok": true,
   "op": "create_view",
   "planned_texts": ["datanotes/metastore.yaml"],
-  "migration_id": "20261014T191527-create_view-create-view-main-reports-vw_wa"
+  "migration_id": "20261020T173838-create_view-create-view-main-reports-vw_wa"
 }
 ```
 
@@ -619,7 +619,7 @@ Answer:
 ```json
 {
   "ok": true,
-  "migration_id": "20261014T191527-batch-views-for-film-and-actor-notes",
+  "migration_id": "20261020T173838-batch-views-for-film-and-actor-notes",
   "steps": [
     { "op": "create_view", "ok": true },
     { "op": "create_view", "ok": true },
@@ -645,13 +645,13 @@ Answer:
   "total": 2,
   "rows": [
     {
-      "path": "datanotes/main/public/watch/2026-09-25T2100.md",
-      "occurred_at": "2026-09-25T21:00",
+      "path": "datanotes/main/public/watch/2026-10-01T2100.md",
+      "occurred_at": "2026-10-01T21:00",
       "where": "home"
     },
     {
-      "path": "datanotes/main/public/watch/2026-10-12T2030.md",
-      "occurred_at": "2026-10-12T20:30",
+      "path": "datanotes/main/public/watch/2026-10-18T2030.md",
+      "occurred_at": "2026-10-18T20:30",
       "where": "home"
     }
   ],
@@ -679,9 +679,9 @@ Answer:
   "total": 1,
   "rows": [
     {
-      "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"
     }
   ],
@@ -766,7 +766,7 @@ The engine wrote this page’s views under `views:` in their schema, next to the
 
 ```yaml
 # Metastore (Datanotes): catalogs, schemas, tables, columns, views.
-id: 01a13bd7-4a81-7458-9957-548732f8e35b
+id: 01a15a64-ccbd-7663-822f-4b752a5e5880
 config:
   history: true