datanotes 3.1.0 → 3.2.0

package/dist/docs/api/operations/add_column.md

@@ -13,6 +13,7 @@ Column names are permanent identifiers; only `rename_column` changes them.
 Enum columns: `values` and, for each, its meaning in `value_descriptions` (`{"stated": "the user said it", …}`): describe_table shows them and a refused value lists them.
 Generated link columns: `generated: "link({occurred_at:YYYY-MM-DD})"` with `ref` = the days table links each row to the row of `ref` named by the template (its folder read from the schema; the target may not exist yet).
 Filtered link targets (link columns): `ref_where` (a `where` every target must match) and `ref_by` (a column of the row picks the target level: `{"column": "kind", "levels": ["area", "project", "workstream"]}` or `{"column": "kind", "map": {"area": null, "project": ["area"]}}`; null = top level, no link; `target_column` when the target names it differently: an enum target column must have every value the map allows, a string one takes any value). A link to no row of the table, or to the row itself, is refused too. Existing rows that break them refuse the change; `list_link_targets` lists the valid targets of a row.
+Acyclic links: `acyclic: true` on a link (or list of links) to the table itself refuses every write that closes a cycle, on either side of an `inverse`; refused while existing rows form one (they are listed).
 
 The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).
 

package/dist/docs/api/operations/add_constraint.md

@@ -18,6 +18,7 @@ A write that changes a linked row re-checks the rows that link to it and is refu
 it breaks them, naming the changed row (in a batch, re-link them first: each step is checked on the vault
 the earlier ones left); the inverse links a write adds, undo_migration and restore_table are checked too.
 rename_column / rename_value follow into CHECKs; drop_column of a column a CHECK reads is refused.
+`hint`: what to do when a row breaks the rule, in your words; a refused write puts it first in its hint, and each violation of the CHECK carries it.
 
 The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).
 
@@ -36,6 +37,7 @@ The schema changes only through operations like this one: never edit metastore.y
 | `table` | `string` | yes |  |  |
 | `name` | `string` | yes |  |  |
 | `check` | `object` | yes |  |  |
+| `hint` | `string \| null` | no | `null` | What a refused write tells the agent when a row breaks this CHECK: how to fix the row. It comes first in the refusal's hint; describe_table lists it in constraint_hints. |
 | `dry_run` | `boolean` | no | `false` |  |
 
 ## Responses

package/dist/docs/api/operations/alter_column.md

@@ -3,7 +3,7 @@
 `POST /datanotes/operations/alter_column/` (operation `alter_column`)
 
 Change a column's attributes (type, min/max/step, values, required, default, label,
-aliases, description, note, `ref_where`, `ref_by` (see list_link_targets); `null` removes an attribute, except
+aliases, description, note, `ref_where`, `ref_by` (see list_link_targets), `acyclic` (refused while the rows already form a cycle: they are listed); `null` removes an attribute, except
 `description`, which changes but never goes (null or "" is refused); `dense` true/false). Refused with
 the list of violating rows when existing values do not satisfy the new definition. A
 different scale means a different column: add a new one instead of rescaling. To rename one

package/dist/docs/api/operations/alter_table.md

@@ -5,7 +5,7 @@
 Alter a table: move it (`catalog`, `schema`), rename it (`name`), change
 `partition` / `filename` patterns, `description` (changes, never goes: "" is refused), `aliases`,
 `exclude` folders, `row_template`
-("" removes it), `history` (true | false | "default"), `autolink_target`
+("" removes it), `instructions` (how to fill a row, for agents; "" removes them), `history` (true | false | "default"), `autolink_target`
 (true | false | "default": may automatic links link its rows? default: yes, unless its rows are named by
 a date or a time) or `tags` (key/value
 labels merged into the table's, e.g. `{"domain": "health"}`; a `null` value removes that tag;
@@ -13,7 +13,7 @@ labels merged into the table's, e.g. `{"domain": "health"}`; a `null` value remo
 `archive` (folder name inside the table folder) or `fields` (untyped fields, name → default; a
 `null` value removes one). Rows, archive and transaction log follow; links are updated; renamed
 rows keep their old name in `aliases`. A change of metadata only (tags, description, aliases,
-history, autolink_target, row_template, fields) rewrites the table entry alone: no row is moved or rewritten. Refused
+history, autolink_target, row_template, instructions, fields) rewrites the table entry alone: no row is moved or rewritten. Refused
 when a row cannot fill a pattern. Renaming or moving the table is refused while a CHECK that follows
 links, or a `ref_where` / `ref_by`, of another table reads it through a link (link targets are not
 rewritten): the conflicts name them. Use `dry_run` to see `planned_moves`; undo with undo_migration.
@@ -44,6 +44,7 @@ The schema changes only through operations like this one: never edit metastore.y
 | `autolink_target` | `boolean \| "default" \| null` | no | `null` | May automatic links link the table's rows? true, false, or "default" (yes, unless its rows are named by a date or a time). |
 | `exclude` | `string[] \| null` | no | `null` |  |
 | `row_template` | `string \| null` | no | `null` | Markdown body of new rows; "" removes it. |
+| `instructions` | `string \| null` | no | `null` | How to fill a row, for agents (Markdown); "" removes them. |
 | `tags` | `object \| null` | no | `null` | Tags to add or change (strings); a null value removes that tag. The other tags are kept. |
 | `clear_tags` | `boolean` | no | `false` | Remove every tag first (with `tags`: the table keeps exactly those). |
 | `archive` | `string \| null` | no | `null` | Archive folder: a folder name inside the table folder (e.g. "_archive"); "" = the database default (`archive_folder`). Archived rows follow. |

package/dist/docs/api/operations/check_table.md

@@ -3,7 +3,7 @@
 `POST /datanotes/operations/check_table/` (operation `check_table`)
 
 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.)
+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.)
 
 ## Request body
 

package/dist/docs/api/operations/create_table.md

@@ -16,7 +16,7 @@ digits, `_` (no dots: pass the catalog and the schema as their own arguments).
   order: filters/avg use the position), ref (link target, full `catalog.schema.table` or "self"),
   unique, label, description, aliases, `generated` (e.g. `"date(occurred_at)"`, `"{name} {surname}"`),
   `identity` ("filename" | "created"), `vocabulary` (allowed values = names of another table's rows),
-  `hierarchy: true` (one parent link to its own table), `dense` (written on every row),
+  `hierarchy: true` (one parent link to its own table), `acyclic: true` (links to rows of its own table that never loop back, such as tasks blocked by tasks; with `inverse`, the rule holds on both sides), `dense` (written on every row),
   `inverse` on a link column: the column of the `ref` table that links back (`friends` ↔
   `friends`, `children` ↔ `parents`, `partner` ↔ `partner`); writes keep both sides in step.
 - `time_column`: rows named by that date/datetime; otherwise `filename` (e.g. `"{name}"`).
@@ -25,6 +25,7 @@ digits, `_` (no dots: pass the catalog and the schema as their own arguments).
   database's setting), `autolink_target` (true / false: may automatic links link its rows? default:
   yes, unless its rows are named by a date or a time, as with `time_column`).
 - `row_template`: markdown body of new rows. Shared columns come from bases: `set_table_bases`.
+- `instructions`: how to fill a row, for agents (Markdown); describe_table returns them.
 - `tags`: key/value labels of the table, strings (`{"domain": "health"}`); list_tables and
   describe_table return them, alter_table changes them.
 Enum columns: `values` and, for each, its meaning in `value_descriptions` (`{"stated": "the user said it", …}`): describe_table shows them and a refused value lists them.
@@ -59,6 +60,7 @@ The schema changes only through operations like this one: never edit metastore.y
 | `history` | `boolean \| null` | no | `null` | Keep the table's versions (time travel, restore); default: the database's setting. |
 | `autolink_target` | `boolean \| null` | no | `null` | May automatic links link the table's rows? Default: yes, unless its rows are named by a date or a time. |
 | `row_template` | `string \| null` | no | `null` | Markdown body of new rows; {column} placeholders are filled from the row. |
+| `instructions` | `string \| null` | no | `null` | How to fill a row, for agents (Markdown): which columns first, what to ask the user. describe_table returns them. |
 | `fields` | `object \| null` | no | `null` | Untyped fields of the table (name → default), kept on every row; a field cannot share a name with a column. |
 | `tags` | `object \| null` | no | `null` | Key/value labels of the table (strings), e.g. {"domain": "health"}. |
 | `dry_run` | `boolean` | no | `false` |  |

package/dist/docs/api/operations/describe_table.md

@@ -6,7 +6,7 @@ Describe a table (`catalog.schema.table` or a shorter unambiguous name): `qualif
 `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`,
+`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

package/dist/docs/api/operations/insert_row.md

@@ -1,8 +1,8 @@
-# Insert a row (new note). Values are validated against the columns; the note path comes from
+# Insert a row (new note). When describe_table gives the table's `instructions`, fill the row as they say. Values are validated against the columns; the note path comes from
 
 `POST /datanotes/operations/insert_row/` (operation `insert_row`)
 
-Insert a row (new note). Values are validated against the columns; the note path comes from
+Insert a row (new note). When describe_table gives the table's `instructions`, fill the row as they say. Values are validated against the columns; the note path comes from
 the table's `path`/`filename` patterns (e.g. an event logged today about last night lands in
 last night's day folder when you set `occurred_at` to last night). `body` is the note text.
 Generated / identity columns are computed (do not pass them); CHECK constraints are enforced.

package/dist/docs/api/operations/tags/rows-dml.md

@@ -4,7 +4,7 @@ Operations that write rows: insert, update, merge, delete, move, adopt and batch
 
 ## Operations
 
-- [Insert a row (new note). Values are validated against the columns; the note path comes from](https://datanotes.dev/api/operations/insert_row/): `POST /datanotes/operations/insert_row/`
+- [Insert a row (new note). When describe_table gives the table's `instructions`, fill the row as they say. Values are validated against the columns; the note path comes from](https://datanotes.dev/api/operations/insert_row/): `POST /datanotes/operations/insert_row/`
 - [Update every row matching `where` (required: `{}` is every row). `where`: keys AND-ed; values are equality or operators](https://datanotes.dev/api/operations/update_rows/): `POST /datanotes/operations/update_rows/`
 - [Update exactly ONE row, addressed by its `id` (the system UUID) or its `path`; refused when](https://datanotes.dev/api/operations/update_row/): `POST /datanotes/operations/update_row/`
 - [Delete rows matching `where`. `mode`: "archive" (default, move to the table's archive](https://datanotes.dev/api/operations/delete_rows/): `POST /datanotes/operations/delete_rows/`

package/dist/docs/api.md

@@ -1,6 +1,6 @@
 # Datanotes HTTP API
 
-> OpenAPI 3.1.0 description of the Datanotes 3.1.0 HTTP API: https://datanotes.dev/openapi.json
+> OpenAPI 3.1.0 description of the Datanotes 3.2.0 HTTP API: https://datanotes.dev/openapi.json
 
 Database of Markdown notes: tables of notes, rows, queries, history, a change feed and the vault's notes.
 
@@ -47,7 +47,7 @@ Operations that define the database: tables, columns, constraints, bases and vie
 
 Operations that write rows: insert, update, merge, delete, move, adopt and batch.
 
-- [Insert a row (new note). Values are validated against the columns; the note path comes from](https://datanotes.dev/api/operations/insert_row/): `POST /datanotes/operations/insert_row/`
+- [Insert a row (new note). When describe_table gives the table's `instructions`, fill the row as they say. Values are validated against the columns; the note path comes from](https://datanotes.dev/api/operations/insert_row/): `POST /datanotes/operations/insert_row/`
 - [Update every row matching `where` (required: `{}` is every row). `where`: keys AND-ed; values are equality or operators](https://datanotes.dev/api/operations/update_rows/): `POST /datanotes/operations/update_rows/`
 - [Update exactly ONE row, addressed by its `id` (the system UUID) or its `path`; refused when](https://datanotes.dev/api/operations/update_row/): `POST /datanotes/operations/update_row/`
 - [Delete rows matching `where`. `mode`: "archive" (default, move to the table's archive](https://datanotes.dev/api/operations/delete_rows/): `POST /datanotes/operations/delete_rows/`

package/dist/docs/guides/data-quality/check-constraints.md

@@ -6,7 +6,7 @@ A CHECK constraint is a rule written as a `where` filter, such as “a watched f
 
 ## Enforce rules with CHECK constraints
 
-`add_constraint` adds a CHECK constraint, a rule every row must satisfy, written as a `where` filter. The engine refuses it while existing rows break the rule and lists them; after that, it enforces the rule on every write. A condition on a column the row leaves empty passes, as in Structured Query Language (SQL). Inside `or`, `and` and `not`, the engine tests an empty value as it is, so a watched film without a `rating` breaks `rated_when_watched`.
+`add_constraint` adds a CHECK constraint, a rule every row must satisfy, written as a `where` filter. The engine refuses it while existing rows break the rule and lists them; after that, it enforces the rule on every write. A condition on a column the row leaves empty passes, as in Structured Query Language (SQL). Inside `or`, `and` and `not`, the engine tests an empty value as it is, so a watched film without a `rating` breaks `rated_when_watched`. `hint` says what to do when a row breaks the rule. The refusal puts it first, and `describe_table` lists it in `constraint_hints`.
 
 **`add_constraint`**
 
@@ -14,7 +14,8 @@ A CHECK constraint is a rule written as a `where` filter, such as “a watched f
 {
   "table": "film",
   "name": "rated_when_watched",
-  "check": { "or": [{ "status": { "ne": "watched" } }, { "rating": { "exists": true } }] }
+  "check": { "or": [{ "status": { "ne": "watched" } }, { "rating": { "exists": true } }] },
+  "hint": "A watched film needs a rating from 1 to 5: ask me for it."
 }
 ```
 
@@ -28,7 +29,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.film", "version": 8, "operation": "ADD CONSTRAINT" }
   ],
-  "migration_id": "20261014T191534-add_constraint-add-constraint-rated_when_watc"
+  "migration_id": "20261019T040655-add_constraint-add-constraint-rated_when_watc"
 }
 ```
 
@@ -57,7 +58,7 @@ Refused:
 ```text
 insert_row refused — nothing was written:
 invalid datanotes/diary/classics/film/His Girl Friday.md: rated_when_watched violates CHECK rated_when_watched: {"or":[{"status":{"ne":"watched"}},{"rating":{"exists":true}}]}
-Hint: 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. Then call insert_row again (dry_run: true checks without writing).
+Hint: A watched film needs a rating from 1 to 5: ask me for it. 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. Then call insert_row again (dry_run: true checks without writing).
 Docs: https://datanotes.dev/guides/data-quality/check-constraints.md#enforce-rules-with-check-constraints (offline: read_docs("guides/data-quality/check-constraints#enforce-rules-with-check-constraints"))
 ```
 
@@ -85,7 +86,7 @@ Answer:
   "files_created": 1,
   "planned_creates": ["datanotes/diary/classics/film/His Girl Friday.md"],
   "commits": [{ "table": "diary.classics.film", "version": 10, "operation": "WRITE" }],
-  "migration_id": "20261014T191534-insert_row-insert-into-film-2"
+  "migration_id": "20261019T040655-insert_row-insert-into-film-2"
 }
 ```
 
@@ -107,7 +108,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.film", "version": 11, "operation": "DROP CONSTRAINT" }
   ],
-  "migration_id": "20261014T191534-drop_constraint-drop-constraint-at_most_three_"
+  "migration_id": "20261019T040655-drop_constraint-drop-constraint-at_most_three_"
 }
 ```
 
@@ -148,7 +149,7 @@ Answer:
   "commits": [
     { "table": "main.public.genre", "version": 4, "operation": "ADD CONSTRAINT" }
   ],
-  "migration_id": "20261014T191519-add_constraint-add-constraint-parent_by_level"
+  "migration_id": "20261019T040641-add_constraint-add-constraint-parent_by_level"
 }
 ```
 
@@ -227,34 +228,34 @@ Answer:
   "ok": true,
   "op": "batch",
   "dry_run": false,
-  "migration_id": "20261014T191519-batch-add-the-silent-era-and-slapsti",
+  "migration_id": "20261019T040641-batch-add-the-silent-era-and-slapsti",
   "steps": [
     {
       "index": 0,
       "op": "insert_row",
       "ok": true,
-      "migration_id": "20261014T191519-insert_row-insert-into-genre-4",
+      "migration_id": "20261019T040641-insert_row-insert-into-genre",
       "result": {
         "ok": true,
         "op": "insert_row",
         "files_created": 1,
         "planned_creates": ["datanotes/main/public/genre/Silent cinema.md"],
         "commits": [{ "table": "main.public.genre", "version": 5, "operation": "WRITE" }],
-        "migration_id": "20261014T191519-insert_row-insert-into-genre-4"
+        "migration_id": "20261019T040641-insert_row-insert-into-genre"
       }
     },
     {
       "index": 1,
       "op": "insert_row",
       "ok": true,
-      "migration_id": "20261014T191519-insert_row-insert-into-genre-5",
+      "migration_id": "20261019T040641-insert_row-insert-into-genre-2",
       "result": {
         "ok": true,
         "op": "insert_row",
         "files_created": 1,
         "planned_creates": ["datanotes/main/public/genre/Slapstick comedy.md"],
         "commits": [{ "table": "main.public.genre", "version": 6, "operation": "WRITE" }],
-        "migration_id": "20261014T191519-insert_row-insert-into-genre-5"
+        "migration_id": "20261019T040641-insert_row-insert-into-genre-2"
       }
     }
   ]
@@ -342,7 +343,7 @@ Answer:
     }
   ],
   "commits": [{ "table": "main.public.genre", "version": 7, "operation": "UPDATE" }],
-  "migration_id": "20261014T191519-update_row-update-genre"
+  "migration_id": "20261019T040641-update_row-update-genre"
 }
 ```
 

package/dist/docs/guides/data-quality/hand-edits.md

@@ -35,7 +35,7 @@ You edit `datanotes/main/public/genre/Silent film.md` by hand, outside the engin
 ```markdown
 ---
 table: main.public.genre
-id: 01a13bd7-2bd8-71e9-a39c-6ec373b79149
+id: 01a15257-1485-7217-8806-89c6ca196427
 name: Silent film
 kind: cinema
 parent: "[[Cinema]]"
@@ -47,7 +47,7 @@ Read the hand edit’s event. `list_changes` long-polls with `wait_ms` until the
 **`list_changes`**
 
 ```json
-{ "since": 39, "tables": ["genre"], "wait_ms": 10000 }
+{ "since": 45, "tables": ["genre"], "wait_ms": 10000 }
 ```
 
 Answer:
@@ -55,7 +55,7 @@ Answer:
 ```json
 [
   {
-    "seq": 40,
+    "seq": 46,
     "kind": "update",
     "path": "datanotes/main/public/genre/Silent film.md",
     "source": "external",
@@ -152,7 +152,7 @@ Answer:
     }
   ],
   "commits": [{ "table": "main.public.genre", "version": 9, "operation": "UPDATE" }],
-  "migration_id": "20261014T191521-update_row-update-genre"
+  "migration_id": "20261019T040642-update_row-update-genre"
 }
 ```
 
@@ -167,7 +167,7 @@ You edit `datanotes/main/public/watch/2026-10-03T2130.md` by hand, outside the e
 ```markdown
 ---
 table: main.public.watch
-id: 01a13bd7-2222-7352-9dea-dd1d7658c61f
+id: 01a15257-0c9b-7856-9c12-bebb7eaf82e5
 film: His Girl Friday
 occurred_at: 2026-10-03T21:30
 where: cinema
@@ -226,7 +226,7 @@ Answer:
     }
   ],
   "commits": [{ "table": "main.public.watch", "version": 3, "operation": "RECOMPUTE" }],
-  "migration_id": "20261014T191518-recompute_columns-recompute-id-day-label-of-watc"
+  "migration_id": "20261019T040640-recompute_columns-recompute-id-day-label-of-watc"
 }
 ```
 
@@ -292,7 +292,7 @@ Answer:
 ```markdown
 ---
 table: main.public.watch
-id: 01a13bd7-8a28-7d6f-843c-977d6d33e981
+id: 01a15257-70f0-7ede-9186-f790fe037b07
 occurred_at: 2026-09-25T21:00
 film: "[[Charade]]"
 where: home
@@ -311,7 +311,7 @@ You edit `datanotes/main/public/film/Metropolis.md` by hand, outside the engine.
 ```markdown
 ---
 table: main.public.film
-id: 01a13bd7-4bf3-7a1e-b23c-2769c0dc41d3
+id: 01a15257-31bb-7113-b86a-5d6fdca79420
 year: 1927
 minutes: 153
 status: to watch
@@ -384,7 +384,7 @@ You edit `datanotes/main/public/film/Sherlock Jr..md` by hand, outside the engin
 ```markdown
 ---
 table: main.public.film
-id: 01a13bd7-3226-73d9-ba6b-80f93c52766a
+id: 01a15257-1cbb-7591-97e2-5b880ad79d39
 title: Sherlock Jr.: the projectionist
 year: 1924
 status: watched
@@ -471,7 +471,7 @@ You edit `datanotes/main/public/film/Sherlock Jr..md` by hand, outside the engin
 ```markdown
 ---
 table: main.public.film
-id: 01a13bd7-3226-73d9-ba6b-80f93c52766a
+id: 01a15257-1cbb-7591-97e2-5b880ad79d39
 title: "Sherlock Jr.: the projectionist"
 year: 1924
 status: watched

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

@@ -30,7 +30,7 @@ Answer:
   "ok": true,
   "op": "define_base",
   "planned_texts": ["datanotes/metastore.yaml"],
-  "migration_id": "20261014T191534-define_base-create-base-entry"
+  "migration_id": "20261019T040655-define_base-create-base-entry"
 }
 ```
 
@@ -50,7 +50,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.film", "version": 6, "operation": "SET TABLE BASES" }
   ],
-  "migration_id": "20261014T191534-set_table_bases-diary-classics-film-extends-en"
+  "migration_id": "20261019T040655-set_table_bases-diary-classics-film-extends-en"
 }
 ```
 
@@ -118,14 +118,14 @@ Answer:
   "rows": [
     {
       "path": "datanotes/diary/classics/actors/Max Schreck.md",
-      "id": "01a13bd7-65fe-747a-b7cc-7c6c8d09e39d",
+      "id": "01a15257-4be9-775a-9d44-7c12bf38b0ed",
       "added_on": "2026-10-05",
       "note": "The face of Nosferatu",
       "_source": "diary.classics.actors"
     },
     {
       "path": "datanotes/diary/classics/film/Nosferatu.md",
-      "id": "01a13bd7-659b-7233-a73c-4f8191e95b0e",
+      "id": "01a15257-4b79-7e2f-83db-94f0aef0d4ae",
       "added_on": "2026-10-05",
       "note": null,
       "_source": "diary.classics.film"
@@ -169,7 +169,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.actors", "version": 3, "operation": "DEFINE BASE" }
   ],
-  "migration_id": "20261014T191534-define_base-alter-base-entry"
+  "migration_id": "20261019T040655-define_base-alter-base-entry"
 }
 ```
 
@@ -246,7 +246,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.actors", "version": 4, "operation": "DEFINE BASE" }
   ],
-  "migration_id": "20261014T191534-define_base-alter-base-entry-2"
+  "migration_id": "20261019T040655-define_base-alter-base-entry-2"
 }
 ```
 
@@ -280,7 +280,7 @@ Answer:
   "ok": true,
   "op": "define_base",
   "planned_texts": ["datanotes/metastore.yaml"],
-  "migration_id": "20261014T191534-define_base-create-base-credited"
+  "migration_id": "20261019T040655-define_base-create-base-credited"
 }
 ```
 
@@ -300,7 +300,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.actors", "version": 5, "operation": "SET TABLE BASES" }
   ],
-  "migration_id": "20261014T191534-set_table_bases-diary-classics-actors-extends--2"
+  "migration_id": "20261019T040655-set_table_bases-diary-classics-actors-extends--2"
 }
 ```
 
@@ -329,7 +329,7 @@ Answer:
   "ok": true,
   "op": "define_base",
   "planned_texts": ["datanotes/metastore.yaml"],
-  "migration_id": "20261014T191534-define_base-create-base-tree"
+  "migration_id": "20261019T040655-define_base-create-base-tree"
 }
 ```
 
@@ -369,7 +369,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.genre", "version": 1, "operation": "SET TABLE BASES" }
   ],
-  "migration_id": "20261014T191534-set_table_bases-diary-classics-genre-extends-t"
+  "migration_id": "20261019T040655-set_table_bases-diary-classics-genre-extends-t"
 }
 ```
 
@@ -475,6 +475,6 @@ Answer:
       "operation": "SET TABLE BASES"
     }
   ],
-  "migration_id": "20261014T191534-set_table_bases-diary-classics-genre_draft-ext"
+  "migration_id": "20261019T040655-set_table_bases-diary-classics-genre_draft-ext"
 }
 ```

package/dist/docs/guides/database-objects/catalogs-and-schemas.md

@@ -63,7 +63,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.film", "version": 0, "operation": "CREATE TABLE" }
   ],
-  "migration_id": "20261014T191534-create_table-create-table-diary-classics-fi"
+  "migration_id": "20261019T040655-create_table-create-table-diary-classics-fi"
 }
 ```
 
@@ -91,7 +91,7 @@ Answer:
   "files_created": 1,
   "planned_creates": ["datanotes/diary/classics/film/Nosferatu.md"],
   "commits": [{ "table": "diary.classics.film", "version": 1, "operation": "WRITE" }],
-  "migration_id": "20261014T191534-insert_row-insert-into-film"
+  "migration_id": "20261019T040655-insert_row-insert-into-film"
 }
 ```
 
@@ -127,7 +127,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.film", "version": 3, "operation": "ALTER TABLE" }
   ],
-  "migration_id": "20261014T191534-alter_table-alter-table-diary-classics-fil-2"
+  "migration_id": "20261019T040655-alter_table-alter-table-diary-classics-fil-2"
 }
 ```
 
@@ -144,7 +144,7 @@ Answer:
   "ok": true,
   "op": "comment_on",
   "planned_texts": ["datanotes/metastore.yaml"],
-  "migration_id": "20261014T191534-comment_on-comment-on-catalog-diary"
+  "migration_id": "20261019T040655-comment_on-comment-on-catalog-diary"
 }
 ```
 
@@ -165,7 +165,7 @@ Answer:
   "ok": true,
   "op": "comment_on",
   "planned_texts": ["datanotes/metastore.yaml"],
-  "migration_id": "20261014T191534-comment_on-comment-on-schema-diary-classi"
+  "migration_id": "20261019T040655-comment_on-comment-on-schema-diary-classi"
 }
 ```
 
@@ -173,7 +173,7 @@ Answer:
 
 ```yaml
 # Metastore (Datanotes): catalogs, schemas, tables, columns, views.
-id: 01a13bd7-658e-7cd5-b7f5-0b4bc7c37f45
+id: 01a15257-4b68-7b8b-bf1b-44c297b63995
 config:
   history: true
 
@@ -270,7 +270,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.film", "version": 4, "operation": "ALTER TABLE" }
   ],
-  "migration_id": "20261014T191534-alter_table-alter-table-diary-classics-fil-3"
+  "migration_id": "20261019T040655-alter_table-alter-table-diary-classics-fil-3"
 }
 ```
 
@@ -287,7 +287,7 @@ Answer:
   "ok": true,
   "op": "comment_on",
   "planned_texts": ["datanotes/metastore.yaml"],
-  "migration_id": "20261014T191534-comment_on-remove-the-comment-on-schema-d"
+  "migration_id": "20261019T040655-comment_on-remove-the-comment-on-schema-d"
 }
 ```
 
@@ -309,7 +309,7 @@ Answer:
   "commits": [
     { "table": "diary.classics.film", "version": 5, "operation": "ALTER TABLE" }
   ],
-  "migration_id": "20261014T191534-alter_table-alter-table-diary-classics-fil-4"
+  "migration_id": "20261019T040655-alter_table-alter-table-diary-classics-fil-4"
 }
 ```
 
@@ -593,7 +593,7 @@ This is the database of this page as the engine wrote it. `metastore.yaml` holds
 
 ```yaml
 # Metastore (Datanotes): catalogs, schemas, tables, columns, views.
-id: 01a13bd7-658e-7cd5-b7f5-0b4bc7c37f45
+id: 01a15257-4b68-7b8b-bf1b-44c297b63995
 config:
   history: true
   default_catalog: diary
@@ -626,6 +626,8 @@ catalogs:
                       ne: watched
                   - rating:
                       exists: true
+            constraint_hints:
+              rated_when_watched: "A watched film needs a rating from 1 to 5: ask me for it."
             options:
               partition: "{year}"
               filename: "{title} ({year})"
@@ -777,6 +779,8 @@ catalogs:
                       ne: watched
                   - rating:
                       exists: true
+            constraint_hints:
+              rated_when_watched: "A watched film needs a rating from 1 to 5: ask me for it."
             options:
               partition: "{year}"
               filename: "{title} ({year})"
@@ -831,6 +835,8 @@ catalogs:
                       ne: watched
                   - rating:
                       exists: true
+            constraint_hints:
+              rated_when_watched: "A watched film needs a rating from 1 to 5: ask me for it."
             options:
               partition: "{year}"
               filename: "{title} ({year})"