datanotes 3.1.0 → 3.2.0

package/dist/datanotes.cjs

@@ -370,7 +370,7 @@ var init_catalog = __esm({
       },
       {
         "name": "describe_table",
-        "description": "Describe a table (`catalog.schema.table` or a shorter unambiguous name): `qualified`, `name`,\n`catalog`, `schema`, `description`, `aliases`, `layout` (`folder`, `row_folder`: the folder pattern\nof new rows, `archive`), `options` (`partition`, `filename`, `archive`, `exclude`), typed `columns`\nwith label/aliases/description and the dense flag, `untyped_fields`, `row_count`, and when set:\n`tags`, `bases` (the bases it inherits from, in order), `constraints` (its CHECKs, name \u2192 where), `row_template`, `history`,\n`autolink_target`, `fields` (their values).\n\nBefore adding a column (e.g. a new metric), read `columns` and match your concept against\n`name`, `label`, `aliases` and `description`; reuse an existing column when it means the same.\n\n`missing_descriptions` (`{table, columns}`), present only when something has no description (a table\ndefined before descriptions were required), names what lacks one: write them with alter_table\n`description` and alter_column `changes.description`, asking the user when the meaning is unclear.",
+        "description": "Describe a table (`catalog.schema.table` or a shorter unambiguous name): `qualified`, `name`,\n`catalog`, `schema`, `description`, `aliases`, `layout` (`folder`, `row_folder`: the folder pattern\nof new rows, `archive`), `options` (`partition`, `filename`, `archive`, `exclude`), typed `columns`\nwith label/aliases/description and the dense flag, `untyped_fields`, `row_count`, and when set:\n`tags`, `bases` (the bases it inherits from, in order), `constraints` (its CHECKs, name \u2192 where), `constraint_hints` (their own hints, name \u2192 hint), `instructions` (how to fill a row: follow them before you write one), `row_template`, `history`,\n`autolink_target`, `fields` (their values).\n\nBefore adding a column (e.g. a new metric), read `columns` and match your concept against\n`name`, `label`, `aliases` and `description`; reuse an existing column when it means the same.\n\n`missing_descriptions` (`{table, columns}`), present only when something has no description (a table\ndefined before descriptions were required), names what lacks one: write them with alter_table\n`description` and alter_column `changes.description`, asking the user when the meaning is unclear.",
         "inputSchema": {
           "additionalProperties": false,
           "properties": {
@@ -493,6 +493,10 @@ var init_catalog = __esm({
                   "inverse": {
                     "type": "string"
                   },
+                  "acyclic": {
+                    "type": "boolean",
+                    "description": "Link column to its own table whose links never form a cycle (a write that closes one is refused)."
+                  },
                   "ref_where": {
                     "type": "object",
                     "description": "Link column: the where filter every linked row must match.",
@@ -602,6 +606,17 @@ var init_catalog = __esm({
               },
               "description": "Its CHECK constraints: name \u2192 the where every row must match."
             },
+            "constraint_hints": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "string"
+              },
+              "description": "The hint of each CHECK that has one: name \u2192 what to do when a row breaks it."
+            },
+            "instructions": {
+              "type": "string",
+              "description": "How to fill a row of the table (alter_table instructions): follow them before you write one."
+            },
             "row_template": {
               "type": "string",
               "description": "The text of every new row's note."
@@ -635,7 +650,7 @@ var init_catalog = __esm({
       },
       {
         "name": "create_table",
-        "description": 'Create a table: `name`, in `catalog` and `schema` (default: the database\'s defaults); the definition\ngoes in metastore.yaml, the rows in `<root>/<catalog>/<schema>/<name>/`. Names: lowercase letters,\ndigits, `_` (no dots: pass the catalog and the schema as their own arguments).\n- `description` (required): what a row of the table records. Every column needs its own `description`\n  too, what it holds: the table is refused otherwise, with every missing one listed. Descriptions are how\n  agents and people understand the schema, so write them for a reader who never saw the notes. The\n  engine writes those of `id` and of `identity` "uuid" / "created" columns.\n- `columns`: specs like `{"name": "kind", "type": "enum", "values": ["a","b"], "required": true,\n  "description": "What kind of entry the row is"}`.\n  Types: string, integer, number, boolean, date, datetime, enum, link, list (+ `items`), json.\n  Attributes: required, default (`"{now}"`/`"{today}"`), min, max, step, values, `ordered` (enum in\n  order: filters/avg use the position), ref (link target, full `catalog.schema.table` or "self"),\n  unique, label, description, aliases, `generated` (e.g. `"date(occurred_at)"`, `"{name} {surname}"`),\n  `identity` ("filename" | "created"), `vocabulary` (allowed values = names of another table\'s rows),\n  `hierarchy: true` (one parent link to its own table), `dense` (written on every row),\n  `inverse` on a link column: the column of the `ref` table that links back (`friends` \u2194\n  `friends`, `children` \u2194 `parents`, `partner` \u2194 `partner`); writes keep both sides in step.\n- `time_column`: rows named by that date/datetime; otherwise `filename` (e.g. `"{name}"`).\n- The table\'s options, as alter_table names them: `aliases` (how agents find it, with the\n  description), `partition`, `exclude`, `archive`, `history` (keep its versions; default: the\n  database\'s setting), `autolink_target` (true / false: may automatic links link its rows? default:\n  yes, unless its rows are named by a date or a time, as with `time_column`).\n- `row_template`: markdown body of new rows. Shared columns come from bases: `set_table_bases`.\n- `tags`: key/value labels of the table, strings (`{"domain": "health"}`); list_tables and\n  describe_table return them, alter_table changes them.\nEnum columns: `values` and, for each, its meaning in `value_descriptions` (`{"stated": "the user said it", \u2026}`): describe_table shows them and a refused value lists them.\nGenerated 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).\nFiltered 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.\n\nThe schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).',
+        "description": 'Create a table: `name`, in `catalog` and `schema` (default: the database\'s defaults); the definition\ngoes in metastore.yaml, the rows in `<root>/<catalog>/<schema>/<name>/`. Names: lowercase letters,\ndigits, `_` (no dots: pass the catalog and the schema as their own arguments).\n- `description` (required): what a row of the table records. Every column needs its own `description`\n  too, what it holds: the table is refused otherwise, with every missing one listed. Descriptions are how\n  agents and people understand the schema, so write them for a reader who never saw the notes. The\n  engine writes those of `id` and of `identity` "uuid" / "created" columns.\n- `columns`: specs like `{"name": "kind", "type": "enum", "values": ["a","b"], "required": true,\n  "description": "What kind of entry the row is"}`.\n  Types: string, integer, number, boolean, date, datetime, enum, link, list (+ `items`), json.\n  Attributes: required, default (`"{now}"`/`"{today}"`), min, max, step, values, `ordered` (enum in\n  order: filters/avg use the position), ref (link target, full `catalog.schema.table` or "self"),\n  unique, label, description, aliases, `generated` (e.g. `"date(occurred_at)"`, `"{name} {surname}"`),\n  `identity` ("filename" | "created"), `vocabulary` (allowed values = names of another table\'s rows),\n  `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),\n  `inverse` on a link column: the column of the `ref` table that links back (`friends` \u2194\n  `friends`, `children` \u2194 `parents`, `partner` \u2194 `partner`); writes keep both sides in step.\n- `time_column`: rows named by that date/datetime; otherwise `filename` (e.g. `"{name}"`).\n- The table\'s options, as alter_table names them: `aliases` (how agents find it, with the\n  description), `partition`, `exclude`, `archive`, `history` (keep its versions; default: the\n  database\'s setting), `autolink_target` (true / false: may automatic links link its rows? default:\n  yes, unless its rows are named by a date or a time, as with `time_column`).\n- `row_template`: markdown body of new rows. Shared columns come from bases: `set_table_bases`.\n- `instructions`: how to fill a row, for agents (Markdown); describe_table returns them.\n- `tags`: key/value labels of the table, strings (`{"domain": "health"}`); list_tables and\n  describe_table return them, alter_table changes them.\nEnum columns: `values` and, for each, its meaning in `value_descriptions` (`{"stated": "the user said it", \u2026}`): describe_table shows them and a refused value lists them.\nGenerated 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).\nFiltered 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.\n\nThe schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).',
         "inputSchema": {
           "additionalProperties": false,
           "properties": {
@@ -796,6 +811,18 @@ var init_catalog = __esm({
               "default": null,
               "description": "Markdown body of new rows; {column} placeholders are filled from the row."
             },
+            "instructions": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "default": null,
+              "description": "How to fill a row, for agents (Markdown): which columns first, what to ask the user. describe_table returns them."
+            },
             "fields": {
               "anyOf": [
                 {
@@ -933,6 +960,10 @@ var init_catalog = __esm({
                           "type": "string",
                           "description": "The CHECK's name (code check)."
                         },
+                        "hint": {
+                          "type": "string",
+                          "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                        },
                         "code": {
                           "type": "string",
                           "enum": [
@@ -1342,6 +1373,10 @@ var init_catalog = __esm({
                           "type": "string",
                           "description": "The CHECK's name (code check)."
                         },
+                        "hint": {
+                          "type": "string",
+                          "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                        },
                         "code": {
                           "type": "string",
                           "enum": [
@@ -1621,7 +1656,7 @@ var init_catalog = __esm({
       },
       {
         "name": "add_column",
-        "description": 'Add a typed column. Sparse by default (written only on rows that have a value \u2014 use for\nmetrics, e.g. `{"name": "metric_mood", "type": "integer", "min": 1, "max": 5, "label":\n"Mood", "aliases": ["mood"], "description": "Mood of the day, 1 = bad, 5 = great"}`).\n`description` is required: what the column holds, for the agents and people who read the schema\n(the engine writes it for `identity` "uuid" / "created" columns).\n`dense: true` in the spec adds it to every row with its `default`. Call `describe_table` first: never add\na column whose meaning an existing column (name/label/aliases/description) already covers.\nColumn names are permanent identifiers; only `rename_column` changes them.\nEnum columns: `values` and, for each, its meaning in `value_descriptions` (`{"stated": "the user said it", \u2026}`): describe_table shows them and a refused value lists them.\nGenerated 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).\nFiltered 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.\n\nThe schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).',
+        "description": 'Add a typed column. Sparse by default (written only on rows that have a value \u2014 use for\nmetrics, e.g. `{"name": "metric_mood", "type": "integer", "min": 1, "max": 5, "label":\n"Mood", "aliases": ["mood"], "description": "Mood of the day, 1 = bad, 5 = great"}`).\n`description` is required: what the column holds, for the agents and people who read the schema\n(the engine writes it for `identity` "uuid" / "created" columns).\n`dense: true` in the spec adds it to every row with its `default`. Call `describe_table` first: never add\na column whose meaning an existing column (name/label/aliases/description) already covers.\nColumn names are permanent identifiers; only `rename_column` changes them.\nEnum columns: `values` and, for each, its meaning in `value_descriptions` (`{"stated": "the user said it", \u2026}`): describe_table shows them and a refused value lists them.\nGenerated 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).\nFiltered 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.\nAcyclic 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).\n\nThe schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).',
         "inputSchema": {
           "additionalProperties": false,
           "properties": {
@@ -1742,6 +1777,10 @@ var init_catalog = __esm({
                           "type": "string",
                           "description": "The CHECK's name (code check)."
                         },
+                        "hint": {
+                          "type": "string",
+                          "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                        },
                         "code": {
                           "type": "string",
                           "enum": [
@@ -2144,6 +2183,10 @@ var init_catalog = __esm({
                           "type": "string",
                           "description": "The CHECK's name (code check)."
                         },
+                        "hint": {
+                          "type": "string",
+                          "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                        },
                         "code": {
                           "type": "string",
                           "enum": [
@@ -2543,6 +2586,10 @@ var init_catalog = __esm({
                           "type": "string",
                           "description": "The CHECK's name (code check)."
                         },
+                        "hint": {
+                          "type": "string",
+                          "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                        },
                         "code": {
                           "type": "string",
                           "enum": [
@@ -2822,7 +2869,7 @@ var init_catalog = __esm({
       },
       {
         "name": "alter_column",
-        "description": 'Change a column\'s attributes (type, min/max/step, values, required, default, label,\naliases, description, note, `ref_where`, `ref_by` (see list_link_targets); `null` removes an attribute, except\n`description`, which changes but never goes (null or "" is refused); `dense` true/false). Refused with\nthe list of violating rows when existing values do not satisfy the new definition. A\ndifferent scale means a different column: add a new one instead of rescaling. To rename one\nenum value use `rename_value`. Dropping an enum value that a `ref_by` (of any table) allows as a\ntarget level is refused, naming it.\n\nThe schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).',
+        "description": 'Change a column\'s attributes (type, min/max/step, values, required, default, label,\naliases, 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\n`description`, which changes but never goes (null or "" is refused); `dense` true/false). Refused with\nthe list of violating rows when existing values do not satisfy the new definition. A\ndifferent scale means a different column: add a new one instead of rescaling. To rename one\nenum value use `rename_value`. Dropping an enum value that a `ref_by` (of any table) allows as a\ntarget level is refused, naming it.\n\nThe schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).',
         "inputSchema": {
           "additionalProperties": false,
           "properties": {
@@ -2947,6 +2994,10 @@ var init_catalog = __esm({
                           "type": "string",
                           "description": "The CHECK's name (code check)."
                         },
+                        "hint": {
+                          "type": "string",
+                          "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                        },
                         "code": {
                           "type": "string",
                           "enum": [
@@ -3226,7 +3277,7 @@ var init_catalog = __esm({
       },
       {
         "name": "alter_table",
-        "description": 'Alter a table: move it (`catalog`, `schema`), rename it (`name`), change\n`partition` / `filename` patterns, `description` (changes, never goes: "" is refused), `aliases`,\n`exclude` folders, `row_template`\n("" removes it), `history` (true | false | "default"), `autolink_target`\n(true | false | "default": may automatic links link its rows? default: yes, unless its rows are named by\na date or a time) or `tags` (key/value\nlabels merged into the table\'s, e.g. `{"domain": "health"}`; a `null` value removes that tag;\n`clear_tags: true` removes every tag first, so with `tags` the table keeps exactly those),\n`archive` (folder name inside the table folder) or `fields` (untyped fields, name \u2192 default; a\n`null` value removes one). Rows, archive and transaction log follow; links are updated; renamed\nrows keep their old name in `aliases`. A change of metadata only (tags, description, aliases,\nhistory, autolink_target, row_template, fields) rewrites the table entry alone: no row is moved or rewritten. Refused\nwhen a row cannot fill a pattern. Renaming or moving the table is refused while a CHECK that follows\nlinks, or a `ref_where` / `ref_by`, of another table reads it through a link (link targets are not\nrewritten): the conflicts name them. Use `dry_run` to see `planned_moves`; undo with undo_migration.\n\nThe schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).',
+        "description": 'Alter a table: move it (`catalog`, `schema`), rename it (`name`), change\n`partition` / `filename` patterns, `description` (changes, never goes: "" is refused), `aliases`,\n`exclude` folders, `row_template`\n("" removes it), `instructions` (how to fill a row, for agents; "" removes them), `history` (true | false | "default"), `autolink_target`\n(true | false | "default": may automatic links link its rows? default: yes, unless its rows are named by\na date or a time) or `tags` (key/value\nlabels merged into the table\'s, e.g. `{"domain": "health"}`; a `null` value removes that tag;\n`clear_tags: true` removes every tag first, so with `tags` the table keeps exactly those),\n`archive` (folder name inside the table folder) or `fields` (untyped fields, name \u2192 default; a\n`null` value removes one). Rows, archive and transaction log follow; links are updated; renamed\nrows keep their old name in `aliases`. A change of metadata only (tags, description, aliases,\nhistory, autolink_target, row_template, instructions, fields) rewrites the table entry alone: no row is moved or rewritten. Refused\nwhen a row cannot fill a pattern. Renaming or moving the table is refused while a CHECK that follows\nlinks, or a `ref_where` / `ref_by`, of another table reads it through a link (link targets are not\nrewritten): the conflicts name them. Use `dry_run` to see `planned_moves`; undo with undo_migration.\n\nThe schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).',
         "inputSchema": {
           "additionalProperties": false,
           "properties": {
@@ -3376,6 +3427,18 @@ var init_catalog = __esm({
               "default": null,
               "description": 'Markdown body of new rows; "" removes it.'
             },
+            "instructions": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "default": null,
+              "description": 'How to fill a row, for agents (Markdown); "" removes them.'
+            },
             "tags": {
               "anyOf": [
                 {
@@ -3536,6 +3599,10 @@ var init_catalog = __esm({
                           "type": "string",
                           "description": "The CHECK's name (code check)."
                         },
+                        "hint": {
+                          "type": "string",
+                          "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                        },
                         "code": {
                           "type": "string",
                           "enum": [
@@ -3992,6 +4059,10 @@ var init_catalog = __esm({
                           "type": "string",
                           "description": "The CHECK's name (code check)."
                         },
+                        "hint": {
+                          "type": "string",
+                          "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                        },
                         "code": {
                           "type": "string",
                           "enum": [
@@ -4393,6 +4464,10 @@ var init_catalog = __esm({
                           "type": "string",
                           "description": "The CHECK's name (code check)."
                         },
+                        "hint": {
+                          "type": "string",
+                          "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                        },
                         "code": {
                           "type": "string",
                           "enum": [
@@ -5455,6 +5530,10 @@ var init_catalog = __esm({
                           "type": "string",
                           "description": "The CHECK's name (code check)."
                         },
+                        "hint": {
+                          "type": "string",
+                          "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                        },
                         "code": {
                           "type": "string",
                           "enum": [
@@ -5861,6 +5940,10 @@ var init_catalog = __esm({
                           "type": "string",
                           "description": "The CHECK's name (code check)."
                         },
+                        "hint": {
+                          "type": "string",
+                          "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                        },
                         "code": {
                           "type": "string",
                           "enum": [
@@ -6140,7 +6223,7 @@ var init_catalog = __esm({
       },
       {
         "name": "insert_row",
-        "description": "Insert a row (new note). Values are validated against the columns; the note path comes from\nthe table's `path`/`filename` patterns (e.g. an event logged today about last night lands in\nlast night's day folder when you set `occurred_at` to last night). `body` is the note text.\nGenerated / identity columns are computed (do not pass them); CHECK constraints are enforced.\nReturns `migration_id` (undo) and the created path in `planned_creates`.\n`body` links the notes it mentions by name, at their first mention (automatic links; off with\n`autolink: false` or the database's `autolink` setting). `links_added` lists the links made;\n`ambiguous_mentions` lists the mentions left as text with the notes they may name: read those,\nthen link the right one with update_row and `autolink: false`, or leave the text.",
+        "description": "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\nthe table's `path`/`filename` patterns (e.g. an event logged today about last night lands in\nlast night's day folder when you set `occurred_at` to last night). `body` is the note text.\nGenerated / identity columns are computed (do not pass them); CHECK constraints are enforced.\nReturns `migration_id` (undo) and the created path in `planned_creates`.\n`body` links the notes it mentions by name, at their first mention (automatic links; off with\n`autolink: false` or the database's `autolink` setting). `links_added` lists the links made;\n`ambiguous_mentions` lists the mentions left as text with the notes they may name: read those,\nthen link the right one with update_row and `autolink: false`, or leave the text.",
         "inputSchema": {
           "additionalProperties": false,
           "properties": {
@@ -6295,6 +6378,10 @@ var init_catalog = __esm({
                           "type": "string",
                           "description": "The CHECK's name (code check)."
                         },
+                        "hint": {
+                          "type": "string",
+                          "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                        },
                         "code": {
                           "type": "string",
                           "enum": [
@@ -6733,6 +6820,10 @@ var init_catalog = __esm({
                           "type": "string",
                           "description": "The CHECK's name (code check)."
                         },
+                        "hint": {
+                          "type": "string",
+                          "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                        },
                         "code": {
                           "type": "string",
                           "enum": [
@@ -7246,6 +7337,10 @@ var init_catalog = __esm({
                           "type": "string",
                           "description": "The CHECK's name (code check)."
                         },
+                        "hint": {
+                          "type": "string",
+                          "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                        },
                         "code": {
                           "type": "string",
                           "enum": [
@@ -7677,6 +7772,10 @@ var init_catalog = __esm({
                           "type": "string",
                           "description": "The CHECK's name (code check)."
                         },
+                        "hint": {
+                          "type": "string",
+                          "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                        },
                         "code": {
                           "type": "string",
                           "enum": [
@@ -8125,6 +8224,10 @@ var init_catalog = __esm({
                           "type": "string",
                           "description": "The CHECK's name (code check)."
                         },
+                        "hint": {
+                          "type": "string",
+                          "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                        },
                         "code": {
                           "type": "string",
                           "enum": [
@@ -8585,6 +8688,10 @@ var init_catalog = __esm({
                           "type": "string",
                           "description": "The CHECK's name (code check)."
                         },
+                        "hint": {
+                          "type": "string",
+                          "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                        },
                         "code": {
                           "type": "string",
                           "enum": [
@@ -9093,7 +9200,7 @@ var init_catalog = __esm({
       },
       {
         "name": "check_table",
-        "description": "Validate every row against the table (required, types, ranges, enums, links, unknown\ncolumns, 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.)",
+        "description": "Validate every row against the table (required, types, ranges, enums, links, unknown\ncolumns, 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.)",
         "inputSchema": {
           "additionalProperties": false,
           "properties": {
@@ -9206,6 +9313,10 @@ var init_catalog = __esm({
                           "type": "string",
                           "description": "The CHECK's name (code check)."
                         },
+                        "hint": {
+                          "type": "string",
+                          "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                        },
                         "code": {
                           "type": "string",
                           "enum": [
@@ -9659,6 +9770,10 @@ var init_catalog = __esm({
                                     "type": "string",
                                     "description": "The CHECK's name (code check)."
                                   },
+                                  "hint": {
+                                    "type": "string",
+                                    "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                                  },
                                   "code": {
                                     "type": "string",
                                     "enum": [
@@ -10102,6 +10217,10 @@ var init_catalog = __esm({
                           "type": "string",
                           "description": "The CHECK's name (code check)."
                         },
+                        "hint": {
+                          "type": "string",
+                          "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                        },
                         "code": {
                           "type": "string",
                           "enum": [
@@ -11185,6 +11304,10 @@ var init_catalog = __esm({
                           "type": "string",
                           "description": "The CHECK's name (code check)."
                         },
+                        "hint": {
+                          "type": "string",
+                          "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                        },
                         "code": {
                           "type": "string",
                           "enum": [
@@ -12622,6 +12745,10 @@ var init_catalog = __esm({
                           "type": "string",
                           "description": "The CHECK's name (code check)."
                         },
+                        "hint": {
+                          "type": "string",
+                          "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                        },
                         "code": {
                           "type": "string",
                           "enum": [
@@ -13032,6 +13159,10 @@ var init_catalog = __esm({
                           "type": "string",
                           "description": "The CHECK's name (code check)."
                         },
+                        "hint": {
+                          "type": "string",
+                          "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                        },
                         "code": {
                           "type": "string",
                           "enum": [
@@ -13498,7 +13629,7 @@ var init_catalog = __esm({
       },
       {
         "name": "add_constraint",
-        "description": 'ALTER TABLE ADD CONSTRAINT `name` CHECK: `check` is a where filter every row must match,\ne.g. `{"value": {"gte": 1, "lte": 5}}`. A condition on a column the row leaves empty passes, like SQL;\ninside `or` / `and` / `not` an empty value is tested as it is (`{"exists": true}` there fails).\nA key may follow a link column to the row it names, as in queries: `{"parent.kind": "project"}`\n(further dots follow further links). An empty link passes at the top level and fails inside `or` / `and` /\n`not`; only the first link of a longer path is skipped when empty (`parent.parent.kind` fails for a row\nwhose parent has no parent). A link to a row that does not exist fails; on a list of links every linked\nrow must match. `not` turns that into a pass: `{"not": {"parent.kind": "area"}}` passes a link to a\nmissing row, so add `"parent.kind": {"exists": true}` to require a real one. Links resolve as in the\nvault (by path, from the row\'s note: same-named rows in two folders stay apart); renaming or moving a\nlinked row keeps them (they follow it).\nRefused while existing rows violate it (they are listed); then enforced on every write, by the same rule.\nA write that changes a linked row re-checks the rows that link to it and is refused, listing them, when\nit breaks them, naming the changed row (in a batch, re-link them first: each step is checked on the vault\nthe earlier ones left); the inverse links a write adds, undo_migration and restore_table are checked too.\nrename_column / rename_value follow into CHECKs; drop_column of a column a CHECK reads is refused.\n\nThe schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).',
+        "description": 'ALTER TABLE ADD CONSTRAINT `name` CHECK: `check` is a where filter every row must match,\ne.g. `{"value": {"gte": 1, "lte": 5}}`. A condition on a column the row leaves empty passes, like SQL;\ninside `or` / `and` / `not` an empty value is tested as it is (`{"exists": true}` there fails).\nA key may follow a link column to the row it names, as in queries: `{"parent.kind": "project"}`\n(further dots follow further links). An empty link passes at the top level and fails inside `or` / `and` /\n`not`; only the first link of a longer path is skipped when empty (`parent.parent.kind` fails for a row\nwhose parent has no parent). A link to a row that does not exist fails; on a list of links every linked\nrow must match. `not` turns that into a pass: `{"not": {"parent.kind": "area"}}` passes a link to a\nmissing row, so add `"parent.kind": {"exists": true}` to require a real one. Links resolve as in the\nvault (by path, from the row\'s note: same-named rows in two folders stay apart); renaming or moving a\nlinked row keeps them (they follow it).\nRefused while existing rows violate it (they are listed); then enforced on every write, by the same rule.\nA write that changes a linked row re-checks the rows that link to it and is refused, listing them, when\nit breaks them, naming the changed row (in a batch, re-link them first: each step is checked on the vault\nthe earlier ones left); the inverse links a write adds, undo_migration and restore_table are checked too.\nrename_column / rename_value follow into CHECKs; drop_column of a column a CHECK reads is refused.\n`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.\n\nThe schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).',
         "inputSchema": {
           "additionalProperties": false,
           "properties": {
@@ -13512,6 +13643,18 @@ var init_catalog = __esm({
               "additionalProperties": true,
               "type": "object"
             },
+            "hint": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "default": null,
+              "description": "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": {
               "default": false,
               "type": "boolean"
@@ -13622,6 +13765,10 @@ var init_catalog = __esm({
                           "type": "string",
                           "description": "The CHECK's name (code check)."
                         },
+                        "hint": {
+                          "type": "string",
+                          "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                        },
                         "code": {
                           "type": "string",
                           "enum": [
@@ -14020,6 +14167,10 @@ var init_catalog = __esm({
                           "type": "string",
                           "description": "The CHECK's name (code check)."
                         },
+                        "hint": {
+                          "type": "string",
+                          "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                        },
                         "code": {
                           "type": "string",
                           "enum": [
@@ -14485,6 +14636,10 @@ var init_catalog = __esm({
                           "type": "string",
                           "description": "The CHECK's name (code check)."
                         },
+                        "hint": {
+                          "type": "string",
+                          "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                        },
                         "code": {
                           "type": "string",
                           "enum": [
@@ -14879,6 +15034,10 @@ var init_catalog = __esm({
                           "type": "string",
                           "description": "The CHECK's name (code check)."
                         },
+                        "hint": {
+                          "type": "string",
+                          "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                        },
                         "code": {
                           "type": "string",
                           "enum": [
@@ -15304,6 +15463,10 @@ var init_catalog = __esm({
                           "type": "string",
                           "description": "The CHECK's name (code check)."
                         },
+                        "hint": {
+                          "type": "string",
+                          "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                        },
                         "code": {
                           "type": "string",
                           "enum": [
@@ -15716,6 +15879,10 @@ var init_catalog = __esm({
                           "type": "string",
                           "description": "The CHECK's name (code check)."
                         },
+                        "hint": {
+                          "type": "string",
+                          "description": "The CHECK's own hint (code check), when the constraint has one: how to fix the row."
+                        },
                         "code": {
                           "type": "string",
                           "enum": [
@@ -19023,13 +19190,13 @@ var require_stringifyCollection = __commonJS({
       const stringify3 = flow ? stringifyFlowCollection : stringifyBlockCollection;
       return stringify3(collection, ctx, options);
     }
-    function stringifyBlockCollection({ comment, items }, ctx, { blockItemPrefix, flowChars, itemIndent, onChompKeep, onComment }) {
+    function stringifyBlockCollection({ comment, items: items2 }, ctx, { blockItemPrefix, flowChars, itemIndent, onChompKeep, onComment }) {
       const { indent, options: { commentString } } = ctx;
       const itemCtx = Object.assign({}, ctx, { indent: itemIndent, type: null });
       let chompKeep = false;
       const lines = [];
-      for (let i = 0; i < items.length; ++i) {
-        const item = items[i];
+      for (let i = 0; i < items2.length; ++i) {
+        const item = items2[i];
         let comment2 = null;
         if (identity.isNode(item)) {
           if (!chompKeep && item.spaceBefore)
@@ -19072,7 +19239,7 @@ ${indent}${line}` : "\n";
         onChompKeep();
       return str3;
     }
-    function stringifyFlowCollection({ items }, ctx, { flowChars, itemIndent }) {
+    function stringifyFlowCollection({ items: items2 }, ctx, { flowChars, itemIndent }) {
       const { indent, indentStep, flowCollectionPadding: fcPadding, options: { commentString } } = ctx;
       itemIndent += indentStep;
       const itemCtx = Object.assign({}, ctx, {
@@ -19083,8 +19250,8 @@ ${indent}${line}` : "\n";
       let reqNewline = false;
       let linesAtValue = 0;
       const lines = [];
-      for (let i = 0; i < items.length; ++i) {
-        const item = items[i];
+      for (let i = 0; i < items2.length; ++i) {
+        const item = items2[i];
         let comment = null;
         if (identity.isNode(item)) {
           if (item.spaceBefore)
@@ -19115,7 +19282,7 @@ ${indent}${line}` : "\n";
           reqNewline = true;
         let str3 = stringify2.stringify(item, itemCtx, () => comment = null);
         reqNewline || (reqNewline = lines.length > linesAtValue || str3.includes("\n"));
-        if (i < items.length - 1) {
+        if (i < items2.length - 1) {
           str3 += ",";
         } else if (ctx.options.trailingComma) {
           if (ctx.options.lineWidth > 0) {
@@ -19172,9 +19339,9 @@ var require_YAMLMap = __commonJS({
     var identity = require_identity();
     var Pair = require_Pair();
     var Scalar = require_Scalar();
-    function findPair(items, key2) {
+    function findPair(items2, key2) {
       const k = identity.isScalar(key2) ? key2.value : key2;
-      for (const it of items) {
+      for (const it of items2) {
         if (identity.isPair(it)) {
           if (it.key === key2 || it.key === k)
             return it;
@@ -21122,12 +21289,12 @@ var require_util_map_includes = __commonJS({
   "node_modules/yaml/dist/compose/util-map-includes.js"(exports2) {
     "use strict";
     var identity = require_identity();
-    function mapIncludes(ctx, items, search) {
+    function mapIncludes(ctx, items2, search) {
       const { uniqueKeys } = ctx.options;
       if (uniqueKeys === false)
         return false;
       const isEqual = typeof uniqueKeys === "function" ? uniqueKeys : (a, b) => a === b || identity.isScalar(a) && identity.isScalar(b) && a.value === b.value;
-      return items.some((pair) => isEqual(pair.key, search));
+      return items2.some((pair) => isEqual(pair.key, search));
     }
     exports2.mapIncludes = mapIncludes;
   }
@@ -24835,16 +25002,26 @@ function unknownOperator(bad, operators) {
 function violationGuidance(code) {
   return VIOLATION_GUIDANCE[code];
 }
+function guidanceOfViolation(v) {
+  return v.code === "cycle" && typeof v.message === "string" && ACYCLIC_CYCLE.test(v.message) ? ACYCLIC_GUIDANCE : violationGuidance(v.code);
+}
 function undoGuidance(r) {
   if (r.failed.length > 0) return guide("Some files could not be written back: undo_migration again once they are free, or repair them by hand.", "undo");
   if (r.conflicts.some((c) => /already undone/.test(c.message))) return guide("This write is undone already: to redo it, undo the undo (its migration_id is in list_migrations).", "undo");
   return guide("Later changes touched the same notes: undo those first (list_migrations lists them, newest first), or change the rows with update_row.", "undoConflict");
 }
 function refusalGuidance(r) {
-  const codes = [...new Set((r.violations ?? []).flatMap((rv) => rv.violations.map((v) => v.code)))];
-  if (codes.length > 0) {
-    const gs = codes.slice(0, 3).map(violationGuidance);
-    return { hint: `${[...new Set(gs.map((g) => g.hint))].join(" ")} Then call ${r.op} again (dry_run: true checks without writing).`, docs: gs[0].docs };
+  const all = (r.violations ?? []).flatMap((rv) => rv.violations);
+  const kinds = /* @__PURE__ */ new Map();
+  for (const v of all) {
+    const g = guidanceOfViolation(v);
+    const key2 = g === ACYCLIC_GUIDANCE ? "cycle:acyclic" : v.code;
+    if (!kinds.has(key2)) kinds.set(key2, g);
+  }
+  if (kinds.size > 0) {
+    const gs = [...kinds.values()].slice(0, 3);
+    const own2 = [...new Set(all.map((v) => v.hint).filter((h) => typeof h === "string" && h.trim() !== ""))].slice(0, 3);
+    return { hint: `${[...own2, ...new Set(gs.map((g) => g.hint))].join(" ")} Then call ${r.op} again (dry_run: true checks without writing).`, docs: gs[0].docs };
   }
   if ((r.failed?.length ?? 0) > 0) {
     if (r.rolled_back === true) return guide(`A file could not be written (another program may hold it): the engine put back what it had written, so nothing changed. Close that program, then call ${r.op} again.`, "failedWrite");
@@ -24856,7 +25033,7 @@ function refusalGuidance(r) {
   if (known) return known[1](r.op);
   return guide(`Resolve what the message names, then call ${r.op} again; dry_run: true checks without writing.`, "errors");
 }
-var DOCS_BASE2, DOCS, GuidedError, fold2, quoted, GENERATED_HINT, OPERATOR_SYNONYMS, VIOLATION_GUIDANCE, CONFLICTS;
+var DOCS_BASE2, DOCS, GuidedError, fold2, quoted, GENERATED_HINT, OPERATOR_SYNONYMS, VIOLATION_GUIDANCE, ACYCLIC_CYCLE, ACYCLIC_GUIDANCE, CONFLICTS;
 var init_hints = __esm({
   "src/core/hints.ts"() {
     "use strict";
@@ -24887,6 +25064,8 @@ var init_hints = __esm({
       linkFilters: "/guides/read-and-write/read-and-filter.md#filter-rows-by-a-link",
       vocabulary: "/guides/database-objects/relations.md#take-allowed-values-from-another-table",
       tree: "/guides/database-objects/relations.md#build-a-tree-of-rows-with-a-parent-link",
+      acyclic: "/guides/database-objects/relations.md#keep-dependencies-free-of-cycles-with-acyclic",
+      instructions: "/guides/database-objects/tables.md#tell-agents-how-to-fill-a-row-with-instructions",
       checkLinks: "/guides/data-quality/check-constraints.md#write-a-check-rule-that-follows-links",
       linkTargets: "/guides/database-objects/relations.md#limit-link-targets-with-ref_by-and-ref_where",
       inverse: "/guides/database-objects/relations.md#repair-two-way-links-with-align_relations",
@@ -25021,13 +25200,18 @@ var init_hints = __esm({
       unknown_column: guide("Write only the table's columns: describe_table lists them. To keep a new front matter key, add_column first.", "describeTable"),
       check: guide("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.", "check"),
       generated: guide("A generated column is computed by the engine: do not write it; recompute_columns sets it again.", "generated"),
-      cycle: guide("A row cannot be its own ancestor: point the hierarchy column to a row that is not below this one.", "tree"),
+      cycle: guide("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.", "tree"),
       inverse: guide("Both sides of a two-way link must agree: write one side, or run align_relations to repair them.", "inverse"),
       unreadable: guide(
         "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.",
         "unreadable"
       )
     };
+    ACYCLIC_CYCLE = /^(would close|is on) a cycle in "/;
+    ACYCLIC_GUIDANCE = guide(
+      "A row cannot depend on itself through an acyclic column: the message shows the cycle. Remove one of its links, or link to a row that is not on it; check_table lists the cycles already there.",
+      "acyclic"
+    );
     CONFLICTS = [
       [/^row changed: expected/, (op) => guide(`The row changed since you read it: read it again (select_rows), then retry ${op} with "expect" set to what you read.`, "expect")],
       [/^"where" matched \d+ rows, expected \d+/, () => guide(`Check the rows with select_rows and the same "where", then narrow it or change expect_count.`, "updateRows")],
@@ -25539,17 +25723,17 @@ function parseColumn(raw, index, reserved = /* @__PURE__ */ new Set()) {
       `"type" must be one of: ${[...SCALAR_COLUMN_TYPES, "list"].join(", ")}`
     );
   }
-  let items;
+  let items2;
   if (type === "list") {
     const it = entry.items ?? "string";
     if (!isScalarType(it)) {
       throw new MalformedColumnError(index, `"items" must be a scalar column type`);
     }
-    items = it;
+    items2 = it;
   } else if (entry.items !== void 0 && entry.items !== null) {
     throw new MalformedColumnError(index, `"items" is only valid for list columns`);
   }
-  const effective = items ?? type;
+  const effective = items2 ?? type;
   const required2 = entry.required ?? false;
   if (typeof required2 !== "boolean") {
     throw new MalformedColumnError(index, `"required" must be true or false`);
@@ -25596,7 +25780,7 @@ function parseColumn(raw, index, reserved = /* @__PURE__ */ new Set()) {
   const spec = {
     name,
     type,
-    ...items !== void 0 ? { items } : {},
+    ...items2 !== void 0 ? { items: items2 } : {},
     required: required2,
     ...min !== void 0 ? { min } : {},
     ...max !== void 0 ? { max } : {},
@@ -25651,6 +25835,24 @@ function parseColumn(raw, index, reserved = /* @__PURE__ */ new Set()) {
     if (effective !== "link" || !ref2) throw new MalformedColumnError(index, `"inverse" needs a link column (or list of links) with "ref"`);
     spec.inverse = entry.inverse.trim();
   }
+  if (entry.acyclic !== void 0 && entry.acyclic !== null) {
+    if (typeof entry.acyclic !== "boolean") throw new MalformedColumnError(index, `"acyclic" must be true or false`, guide("Set acyclic: true to refuse writes that close a cycle, or leave it out.", "acyclic"));
+    if (entry.acyclic && (effective !== "link" || !ref2)) {
+      throw new MalformedColumnError(
+        index,
+        `"acyclic" needs a link column (or list of links) with "ref" to its own table`,
+        guide('Use acyclic on a link column with ref: "self", such as tasks blocked by tasks.', "acyclic")
+      );
+    }
+    if (entry.acyclic && spec.inverse === name) {
+      throw new MalformedColumnError(
+        index,
+        `"acyclic" cannot be set on a column that is its own inverse: every link would close a cycle`,
+        guide("Name another column of the table as the inverse, such as blocks for blocked_by, or drop acyclic.", "acyclic")
+      );
+    }
+    if (entry.acyclic) spec.acyclic = true;
+  }
   if (entry.vocabulary !== void 0 && entry.vocabulary !== null) {
     if (typeof entry.vocabulary !== "string" || entry.vocabulary.trim() === "") {
       throw new MalformedColumnError(index, `"vocabulary" must be a table name`);
@@ -25807,12 +26009,14 @@ var init_table_loader = __esm({
     init_types_table();
     init_validate();
     init_message();
+    init_hints();
     init_db_paths();
     MalformedColumnError = class extends Error {
-      constructor(index, message) {
+      constructor(index, message, guidance) {
         super(`columns[${index}]: ${message}`);
         this.index = index;
         this.name = "MalformedColumnError";
+        if (guidance) Object.assign(this, guidance);
       }
     };
     MalformedTableOptionsError = class extends Error {
@@ -25843,6 +26047,7 @@ var init_table_loader = __esm({
       "generated",
       "identity",
       "hierarchy",
+      "acyclic",
       "vocabulary",
       "inverse",
       "ref_where",
@@ -26040,6 +26245,19 @@ function tableTags(entry) {
   const pairs = isRecord(tags) ? Object.entries(tags).map(([k, v]) => [k, text5(v)]) : (Array.isArray(tags) ? tags : [tags]).map((k) => [text5(k).trim(), ""]).filter(([k]) => k !== "");
   return pairs.length === 0 ? void 0 : Object.fromEntries(pairs);
 }
+function constraintHints(entry) {
+  const out = {};
+  const raw = entry.constraint_hints;
+  if (!isRecord(raw)) return out;
+  const checks = entry.constraints ?? {};
+  for (const [name, hint] of Object.entries(raw)) {
+    if (typeof hint === "string" && hint.trim() !== "" && Object.prototype.hasOwnProperty.call(checks, name)) out[name] = hint.trim();
+  }
+  return out;
+}
+function tableInstructions(entry) {
+  return typeof entry.instructions === "string" && entry.instructions.trim() !== "" ? entry.instructions : void 0;
+}
 function withTableTags(entry, tags) {
   const { tags: _old, ...rest } = entry;
   const out = {};
@@ -27304,12 +27522,12 @@ async function appendDatabaseMove(app, move) {
 `);
   CACHE2.delete(app);
 }
-async function eachLimit(items, limit, fn) {
+async function eachLimit(items2, limit, fn) {
   let next = 0;
   const worker = async () => {
-    while (next < items.length) await fn(items[next++]);
+    while (next < items2.length) await fn(items2[next++]);
   };
-  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+  await Promise.all(Array.from({ length: Math.min(limit, items2.length) }, worker));
 }
 function moveLinks(text5, from, to, entries = []) {
   const prefix = (t) => t === "" ? "" : `${t}/`;
@@ -27766,9 +27984,9 @@ function buildInverseSpecs(model) {
   return out;
 }
 function linkTargets(app, value, source) {
-  const items = Array.isArray(value) ? value : value === null || value === void 0 ? [] : [value];
+  const items2 = Array.isArray(value) ? value : value === null || value === void 0 ? [] : [value];
   const out = [];
-  for (const v of items) {
+  for (const v of items2) {
     const m = typeof v === "string" ? LINK_RE.exec(v.trim()) : null;
     if (!m) continue;
     const dest = app.metadataCache.getFirstLinkpathDest(m[1].trim(), source)?.path;
@@ -29509,22 +29727,22 @@ async function storeFilesSince(app, moves) {
 function atOnceFor(count2) {
   return count2 >= WRITE_CONCURRENCY.from ? WRITE_CONCURRENCY.atOnce : 1;
 }
-async function inOrder(items, pathOf, fn, limit = atOnceFor(items.length)) {
-  const results = new Array(items.length);
+async function inOrder(items2, pathOf, fn, limit = atOnceFor(items2.length)) {
+  const results = new Array(items2.length);
   let next = 0;
   let stop = false;
   const worker = async () => {
-    while (!stop && next < items.length) {
+    while (!stop && next < items2.length) {
       const i = next++;
       try {
-        results[i] = { ok: true, written: await fn(items[i]) };
+        results[i] = { ok: true, written: await fn(items2[i]) };
       } catch (e) {
         results[i] = { ok: false, error: messageOf(e) };
         stop = true;
       }
     }
   };
-  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+  await Promise.all(Array.from({ length: Math.min(limit, items2.length) }, worker));
   const first2 = results.findIndex((r) => r !== void 0 && !r.ok);
   const kept2 = /* @__PURE__ */ new Set();
   if (first2 >= 0) {
@@ -29543,7 +29761,7 @@ async function inOrder(items, pathOf, fn, limit = atOnceFor(items.length)) {
     if (r?.ok && (first2 < 0 || i < first2 || kept2.has(i))) done.push(r.written.value);
   });
   const f = first2 >= 0 ? results[first2] : null;
-  return { done, failed: f ? { path: pathOf(items[first2]), error: f.error } : null };
+  return { done, failed: f ? { path: pathOf(items2[first2]), error: f.error } : null };
 }
 async function moveFile(app, from, to) {
   if (inStore(from)) return storeRename(app, from, to);
@@ -31269,10 +31487,10 @@ function equalTo(e) {
   if (typeof e === "string") return (a) => typeof a === "string" ? a === e : JSON.stringify(a) === json3;
   return (a) => JSON.stringify(a) === json3;
 }
-function memberOf(items) {
+function memberOf(items2) {
   const strings2 = /* @__PURE__ */ new Set();
   const json3 = /* @__PURE__ */ new Set();
-  for (const i of items) {
+  for (const i of items2) {
     if (typeof i === "string") strings2.add(i);
     json3.add(JSON.stringify(i));
   }
@@ -31739,14 +31957,14 @@ var init_check_links = __esm({
         if (!via) throw new OperationInputError(`where "${col}": "${head}" is not a link column with ref`);
         const key2 = `${t.catalog.ref.full}|${via.ref}`;
         const target = this.tables.get(key2);
-        const byPath2 = target ? this.rows.get(target.catalog.ref.full) : void 0;
-        if (!target || !byPath2) throw new OperationInputError(this.missing.get(key2) ?? `CHECK links not loaded for "${col}"`);
+        const byPath3 = target ? this.rows.get(target.catalog.ref.full) : void 0;
+        if (!target || !byPath3) throw new OperationInputError(this.missing.get(key2) ?? `CHECK links not loaded for "${col}"`);
         const pred = compileWhere({ [col.slice(dot2 + 1)]: cond }, target, this.settings, rowGetter(null, target, this.settings), this);
         return (row) => {
           const v = fmGet(row.ordered, head);
           const paths = (Array.isArray(v) ? v : [v]).filter((x) => !isEmptyValue(x)).map((x) => this.resolve(x, row.file.path));
           return paths.length > 0 && paths.every((p) => {
-            const r = p == null ? void 0 : byPath2.get(p);
+            const r = p == null ? void 0 : byPath3.get(p);
             return r !== void 0 && pred(r);
           });
         };
@@ -31989,8 +32207,8 @@ function findRow(rows, ref2, table) {
   const given = ref2.trim();
   const want = (parseWikilink(given) ?? given).replace(/^\/+/, "").replace(/\.md$/i, "");
   const stem2 = (r) => r.file.path.replace(/\.md$/i, "");
-  const byPath2 = rows.find((r) => r.file.path === given || stem2(r) === want);
-  if (byPath2) return byPath2;
+  const byPath3 = rows.find((r) => r.file.path === given || stem2(r) === want);
+  if (byPath3) return byPath3;
   const hits = want.includes("/") ? rows.filter((r) => stem2(r).endsWith(`/${want}`)) : rows.filter((r) => basenameOf(r.file.path) === want);
   if (hits.length > 1) {
     throw new OperationInputError(
@@ -32179,6 +32397,8 @@ async function linkedCheckViolationsImpl(app, settings, cs, consequential = /* @
     const s = await tableIn(app, settings, metastore, ref2.full);
     for (const [name, where] of Object.entries(s.catalog.entry.constraints)) {
       if (!followsLinks2(where)) continue;
+      const checkHint = constraintHints(s.catalog.entry)[name];
+      const ownHint = checkHint ? { hint: checkHint } : {};
       await after.prepare(s, where);
       const rows = after.rowsOf(s);
       const restored = renewed.has(`${ref2.full}|CHECK ${name}`);
@@ -32202,7 +32422,7 @@ async function linkedCheckViolationsImpl(app, settings, cs, consequential = /* @
         if (passes(r)) continue;
         const message = `violates CHECK ${name}: ${JSON.stringify(where)}`;
         if (own2 === void 0 && restored) {
-          add(r.file.path, { constraint: name, code: "check", message: `${message} (CHECK ${name} comes back with this change)` });
+          add(r.file.path, { constraint: name, code: "check", message: `${message} (CHECK ${name} comes back with this change)`, ...ownHint });
           continue;
         }
         if (own2 === void 0) {
@@ -32210,10 +32430,10 @@ async function linkedCheckViolationsImpl(app, settings, cs, consequential = /* @
             await before.prepare(s, where);
             passed = compileCheck(where, s, settings, before);
           }
-          if (passed(r)) add(r.file.path, { constraint: name, code: "check", message: `${message}${suffix(r, heads)}` });
+          if (passed(r)) add(r.file.path, { constraint: name, code: "check", message: `${message}${suffix(r, heads)}`, ...ownHint });
           continue;
         }
-        add(own2, { constraint: name, code: "check", message: consequential.has(own2) ? `${message}${suffix(r, heads, own2)}` : message });
+        add(own2, { constraint: name, code: "check", message: consequential.has(own2) ? `${message}${suffix(r, heads, own2)}` : message, ...ownHint });
       }
     }
   }
@@ -32240,17 +32460,177 @@ var init_changeset_checks = __esm({
   }
 });
 
+// src/core/acyclic.ts
+var acyclic_exports = {};
+__export(acyclic_exports, {
+  acyclicPairs: () => acyclicPairs,
+  acyclicViolations: () => acyclicViolations,
+  changeSetCycles: () => changeSetCycles,
+  cycleThrough: () => cycleThrough
+});
+function acyclicPairs(columns, table) {
+  const target = (c) => c.ref === "self" ? table : c.ref;
+  return columns.filter((c) => c.acyclic === true).map((c) => {
+    const declared = c.inverse !== void 0 && c.inverse !== c.name ? c.inverse : void 0;
+    const back = declared ?? columns.find((x) => x.name !== c.name && x.inverse === c.name && target(x) === target(c))?.name;
+    return { column: c.name, inverse: back !== void 0 && columns.some((x) => x.name === back) ? back : null };
+  });
+}
+function graphOf(pair, rows) {
+  const names2 = new Set(rows.map((r) => basenameOf(r.path)));
+  const out = /* @__PURE__ */ new Map();
+  const add = (from, to) => {
+    if (!names2.has(from) || !names2.has(to)) return;
+    let s = out.get(from);
+    if (!s) out.set(from, s = /* @__PURE__ */ new Set());
+    s.add(to);
+  };
+  for (const r of rows) {
+    const self = basenameOf(r.path);
+    for (const v of items(fmGet(r.ordered, pair.column))) {
+      const to = linkName(v);
+      if (to !== null) add(self, to);
+    }
+    if (pair.inverse !== null) {
+      for (const v of items(fmGet(r.ordered, pair.inverse))) {
+        const from = linkName(v);
+        if (from !== null) add(from, self);
+      }
+    }
+  }
+  return out;
+}
+function cycleThrough(graph, start) {
+  const prev = /* @__PURE__ */ new Map();
+  const seen = /* @__PURE__ */ new Set([start]);
+  const queue = [start];
+  while (queue.length > 0) {
+    const u = queue.shift();
+    for (const v of [...graph.get(u) ?? []].sort()) {
+      if (v === start) {
+        const chain = [u];
+        while (chain[chain.length - 1] !== start) chain.push(prev.get(chain[chain.length - 1]));
+        return [...chain.reverse(), start];
+      }
+      if (!seen.has(v)) {
+        seen.add(v);
+        prev.set(v, u);
+        queue.push(v);
+      }
+    }
+  }
+  return null;
+}
+function acyclicViolations(columns, table, rows, opts) {
+  const pairs = acyclicPairs(columns, table).filter((p) => opts.involving === void 0 || p.column === opts.involving || p.inverse === opts.involving);
+  const out = /* @__PURE__ */ new Map();
+  const head = opts.wording === "write" ? "would close a cycle in" : "is on a cycle in";
+  for (const pair of pairs) {
+    const after = graphOf(pair, rows);
+    const before = opts.before ? graphOf(pair, opts.before) : null;
+    for (const r of [...rows].sort(byPath2)) {
+      if (opts.only && !opts.only.has(r.path)) continue;
+      const name = basenameOf(r.path);
+      const cycle = cycleThrough(after, name);
+      if (cycle === null || before !== null && cycleThrough(before, name) !== null) continue;
+      const v = { column: pair.column, code: "cycle", message: `${head} "${pair.column}" (${cycle.join(" \u2192 ")})` };
+      out.set(r.path, [...out.get(r.path) ?? [], v]);
+    }
+  }
+  return [...out].map(([path19, violations]) => ({ path: path19, violations })).sort(byPath2);
+}
+function acyclicTables(model) {
+  let out = ACYCLIC_TABLES.get(model);
+  if (!out) {
+    const set = /* @__PURE__ */ new Set();
+    const has = (cols) => cols.some((c) => c.acyclic === true);
+    for (const { ref: ref2, entry } of catalogTables(model)) {
+      const bases = baseChain(model.bases, entry.bases ?? []);
+      if (has(entry.columns) || bases.some((b) => has(model.bases[b].columns))) set.add(ref2.full);
+    }
+    ACYCLIC_TABLES.set(model, out = set);
+  }
+  return out;
+}
+async function changeSetCycles(app, settings, cs) {
+  if (cs.texts.some((t) => t.path === metastorePath(settings))) return [];
+  const model = cachedMetastore(app, settings) ?? (await loadMetastore(app, settings)).model;
+  const tables = acyclicTables(model);
+  if (tables.size === 0) return [];
+  const keep = /* @__PURE__ */ new Set([settings.tableKey]);
+  const tableOf = (o) => rowTableFull(model, fmGet(o, settings.tableKey));
+  const moved = new Map(cs.moves.map((m) => [m.from, m.to]));
+  const created = cs.creates.map((c) => ({ path: c.path, ordered: readOrderedFromMarkdown(c.content, keep).ordered }));
+  const touched = /* @__PURE__ */ new Map();
+  const note = (full, x) => {
+    if (full === null || !tables.has(full)) return;
+    touched.set(full, [...touched.get(full) ?? [], x]);
+  };
+  for (const e of cs.edits) note(tableOf(e.after), { path: e.path, final: moved.get(e.path) ?? e.path, before: e.before, after: e.after });
+  for (const c of created) note(tableOf(c.ordered), { path: c.path, final: c.path, before: null, after: c.ordered });
+  if (touched.size === 0) return [];
+  return phase("engine.checks", async () => {
+    const out = [];
+    for (const [full, list2] of [...touched].sort(([a], [b]) => a < b ? -1 : 1)) {
+      const t = await loadTable(app, settings, full);
+      const pairs = acyclicPairs(t.def.columns, full);
+      const cols = pairs.flatMap((p) => p.inverse === null ? [p.column] : [p.column, p.inverse]);
+      const value = (o, c) => JSON.stringify(o === null ? null : fmGet(o, c) ?? null);
+      if (!list2.some((x) => cols.some((c) => value(x.before, c) !== value(x.after, c)))) continue;
+      const before = (await loadRows(app, settings, t)).map((r) => ({ path: r.file.path, ordered: r.ordered }));
+      const after = new Map(before.map((r) => [r.path, r.ordered]));
+      for (const e of cs.edits) {
+        if (tableOf(e.after) === full) after.set(e.path, e.after);
+        else after.delete(e.path);
+      }
+      const archive = `${t.def.layout.archive}/`;
+      for (const m of cs.moves) {
+        const o = after.get(m.from);
+        if (o === void 0) continue;
+        after.delete(m.from);
+        if (!m.to.startsWith(archive)) after.set(m.to, o);
+      }
+      for (const p of cs.deletes) after.delete(p);
+      for (const c of created) if (tableOf(c.ordered) === full) after.set(c.path, c.ordered);
+      const reportAs = new Map(list2.filter((x) => after.has(x.final)).map((x) => [x.final, x.path]));
+      const found = acyclicViolations(t.def.columns, full, [...after].map(([path19, ordered]) => ({ path: path19, ordered })), {
+        only: new Set(reportAs.keys()),
+        before,
+        wording: "write"
+      });
+      for (const v of found) out.push({ path: reportAs.get(v.path), violations: v.violations });
+    }
+    return out;
+  }, { "datanotes.checks.kind": "acyclic" });
+}
+var items, byPath2, ACYCLIC_TABLES;
+var init_acyclic = __esm({
+  "src/core/acyclic.ts"() {
+    "use strict";
+    init_engine();
+    init_frontmatter();
+    init_metastore();
+    init_path_templates();
+    init_tracing();
+    init_where();
+    items = (v) => Array.isArray(v) ? v : v === null || v === void 0 ? [] : [v];
+    byPath2 = (a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
+    ACYCLIC_TABLES = /* @__PURE__ */ new WeakMap();
+  }
+});
+
 // src/core/row-checks.ts
 function constraintViolationsImpl(t, settings, path19, ordered, links) {
   const raw = t.catalog.entry.constraints;
   if (!raw || typeof raw !== "object") return [];
   const out = [];
+  const hints = constraintHints(t.catalog.entry);
   for (const [name, where] of Object.entries(raw)) {
     if (!where || typeof where !== "object" || Array.isArray(where)) continue;
     if (!links && followsLinks2(where)) continue;
     try {
       if (!compileCheck(where, t, settings, links)({ file: { path: path19 }, ordered })) {
-        out.push({ constraint: name, code: "check", message: `violates CHECK ${name}: ${JSON.stringify(where)}` });
+        out.push({ constraint: name, code: "check", message: `violates CHECK ${name}: ${JSON.stringify(where)}`, ...hints[name] ? { hint: hints[name] } : {} });
       }
     } catch (e) {
       out.push({ constraint: name, code: "check", message: `CHECK ${name} is invalid: ${messageOf(e)}` });
@@ -32289,14 +32669,14 @@ function checkViolation(v) {
 async function checkOne(app, settings, table, everyUnreadable) {
   const t = await loadTable(app, settings, table);
   const violations = [];
-  const byPath2 = /* @__PURE__ */ new Map();
+  const byPath3 = /* @__PURE__ */ new Map();
   const report = (path19, v) => {
-    const existing = byPath2.get(path19);
+    const existing = byPath3.get(path19);
     if (existing) existing.violations.push(...v);
     else {
       const row = { path: path19, violations: v };
       violations.push(row);
-      byPath2.set(path19, row);
+      byPath3.set(path19, row);
     }
   };
   const links = new CheckLinks(app, settings);
@@ -32321,6 +32701,7 @@ async function checkOne(app, settings, table, everyUnreadable) {
   const back = await missingBackLinks(app, settings, t.catalog.model, t.catalog.ref.full, rows.map((r) => ({ path: r.file.path, ordered: r.ordered })));
   for (const [path19, list2] of back) report(path19, list2.map((x) => ({ column: x.column, code: "inverse", message: x.message, value: x.value })));
   for (const h of await hierarchyViolations(app, settings, t, rows.map((r) => ({ path: r.file.path, ordered: r.ordered })), rows)) report(h.path, h.violations);
+  for (const a of acyclicViolations(t.def.columns, t.catalog.ref.full, rows.map((r) => ({ path: r.file.path, ordered: r.ordered })), { wording: "check" })) report(a.path, a.violations);
   const unreadable = everyUnreadable && everyUnreadable.model === t.catalog.model ? everyUnreadable.rows.filter((u) => u.table === t.catalog.ref.full) : await unreadableRows(app, settings, t.catalog.model, t.catalog.ref.full);
   for (const u of unreadable) violations.push({ path: u.path, violations: [{ code: "unreadable", message: unreadableMessage(u.error) }] });
   return { table: t.def.name, rows: rows.length + unreadable.length, violations };
@@ -32393,6 +32774,7 @@ var init_row_checks = __esm({
     init_check_links();
     init_link_targets();
     init_message();
+    init_acyclic();
     init_unreadable();
     init_tracing();
     CHECK_LIMIT = 500;
@@ -32459,7 +32841,7 @@ async function ownViolations(app, settings, t, rows, links) {
   const targetChecks = [];
   for (const c of filteredLinkColumns(t)) targetChecks.push(await linkTargetCheck(t, settings, links, c));
   const computed = computedColumnNames(t);
-  const whole = t.def.columns.some((c) => c.unique && !computed.has(c.name) || c.hierarchy);
+  const whole = t.def.columns.some((c) => c.unique && !computed.has(c.name) || c.hierarchy || c.acyclic === true);
   if (whole) await links.prepare(t, null);
   const all = whole ? links.rowsOf(t) : [];
   const own2 = new Set(rows.map((r) => r.file.path));
@@ -32467,6 +32849,7 @@ async function ownViolations(app, settings, t, rows, links) {
     uniqueViolations(t.def.columns, all.map((r) => ({ path: r.file.path, ordered: r.ordered }))).filter((u) => own2.has(u.path)).map((u) => [u.path, u.violations])
   );
   const cycles = whole ? await hierarchyViolations(app, settings, t, rows.map((r) => ({ path: r.file.path, ordered: r.ordered })), all) : [];
+  const loops = whole ? acyclicViolations(t.def.columns, t.catalog.ref.full, all.map((r) => ({ path: r.file.path, ordered: r.ordered })), { only: own2, wording: "check" }) : [];
   const out = /* @__PURE__ */ new Map();
   for (const r of rows) {
     const path19 = r.file.path;
@@ -32475,17 +32858,18 @@ async function ownViolations(app, settings, t, rows, links) {
       ...unique.get(path19) ?? [],
       ...constraintViolations(t, settings, path19, r.ordered, links),
       ...targetChecks.flatMap((check) => check(r)),
-      ...cycles.filter((c) => c.path === path19).flatMap((c) => c.violations)
+      ...cycles.filter((c) => c.path === path19).flatMap((c) => c.violations),
+      ...loops.filter((c) => c.path === path19).flatMap((c) => c.violations)
     ];
     out.set(path19, v.filter((x) => x.code === "check" || !computed.has(x.column)));
   }
   return out;
 }
 async function checkExternalEdits(app, settings, input) {
-  const byPath2 = /* @__PURE__ */ new Map();
+  const byPath3 = /* @__PURE__ */ new Map();
   const tableOf = /* @__PURE__ */ new Map();
   const model = input.length > 0 ? (await loadMetastore(app, settings))?.model : void 0;
-  if (!model) return { byPath: byPath2, loaded: [], tableOf };
+  if (!model) return { byPath: byPath3, loaded: [], tableOf };
   const tp = settings.tableKey;
   const edits = /* @__PURE__ */ new Map();
   for (const e of input) {
@@ -32553,15 +32937,15 @@ async function checkExternalEdits(app, settings, input) {
   }
   const add = (at, v, full) => {
     if (!v) return;
-    byPath2.set(at, [...byPath2.get(at), v]);
+    byPath3.set(at, [...byPath3.get(at), v]);
     tableOf.set(v.path, full);
   };
   const byTable = /* @__PURE__ */ new Map();
   for (const [path19, { row, full }] of now) {
     byTable.set(full, [...byTable.get(full) ?? [], row]);
-    byPath2.set(path19, []);
+    byPath3.set(path19, []);
   }
-  for (const e of edits.values()) if (!now.has(e.path) && gone.has(e.oldPath ?? e.path)) byPath2.set(e.path, []);
+  for (const e of edits.values()) if (!now.has(e.path) && gone.has(e.oldPath ?? e.path)) byPath3.set(e.path, []);
   for (const [full, rows] of byTable) {
     const t = await table(full);
     const found = await ownViolations(app, settings, t, rows, after);
@@ -32687,7 +33071,7 @@ async function checkExternalEdits(app, settings, input) {
     }
   }
   const loaded = /* @__PURE__ */ new Set([...after.loadedTables(), ...before?.loadedTables() ?? []]);
-  return { byPath: byPath2, loaded: [...loaded].sort(), tableOf };
+  return { byPath: byPath3, loaded: [...loaded].sort(), tableOf };
 }
 async function checkChangedTables(app, settings, tables) {
   const byTable = /* @__PURE__ */ new Map();
@@ -32721,6 +33105,7 @@ var init_external_edits = __esm({
     init_check_links();
     init_link_targets();
     init_row_checks();
+    init_acyclic();
     init_message();
   }
 });
@@ -32844,7 +33229,7 @@ async function rowsInVaultOrder(app, settings, t, keep, bodies) {
   return out.sort((a, b) => a.file.path.localeCompare(b.file.path));
 }
 function uniqueViolations(columns, rows) {
-  const byPath2 = /* @__PURE__ */ new Map();
+  const byPath3 = /* @__PURE__ */ new Map();
   const rowOf = /* @__PURE__ */ new Map();
   for (const r of rows) if (!rowOf.has(r.path)) rowOf.set(r.path, r);
   for (const col of columns.filter((c) => c.unique)) {
@@ -32860,13 +33245,13 @@ function uniqueViolations(columns, rows) {
       if (paths.length < 2) continue;
       for (const p of paths) {
         const others = paths.filter((x) => x !== p).join(", ");
-        let list2 = byPath2.get(p);
-        if (!list2) byPath2.set(p, list2 = []);
+        let list2 = byPath3.get(p);
+        if (!list2) byPath3.set(p, list2 = []);
         list2.push({ column: col.name, code: "unique", message: `must be unique (also used by ${others})`, value: fmGet(rowOf.get(p).ordered, col.name) });
       }
     }
   }
-  return [...byPath2.entries()].map(([path19, violations]) => ({ path: path19, violations }));
+  return [...byPath3.entries()].map(([path19, violations]) => ({ path: path19, violations }));
 }
 function uniqueKey(v) {
   if (isEmptyValue(v)) return null;
@@ -32893,6 +33278,7 @@ function serializeColumn(c) {
   if (c.generated !== void 0) out.generated = c.generated;
   if (c.identity !== void 0) out.identity = c.identity;
   if (c.hierarchy) out.hierarchy = true;
+  if (c.acyclic) out.acyclic = true;
   if (c.vocabulary !== void 0) out.vocabulary = c.vocabulary;
   if (c.inverse !== void 0) out.inverse = c.inverse;
   if (c.ref_where !== void 0) out.ref_where = c.ref_where;
@@ -32955,6 +33341,8 @@ async function finish(app, settings, cs, conflicts, violations, opts) {
       const { linkedCheckViolations: linkedCheckViolations2 } = await Promise.resolve().then(() => (init_changeset_checks(), changeset_checks_exports));
       violations = [...violations, ...await linkedCheckViolations2(app, settings, cs, mirrored)];
     }
+    const { changeSetCycles: changeSetCycles2 } = await Promise.resolve().then(() => (init_acyclic(), acyclic_exports));
+    violations = [...violations, ...await changeSetCycles2(app, settings, cs)];
   }
   const base = emptyResult(cs.op, dryRun);
   base.planned_edits = plannedFrom(cs);
@@ -33161,12 +33549,12 @@ async function externalViolationCounts(app, settings, changes) {
     }
     const out = /* @__PURE__ */ new Map();
     if (edits.length > 0) {
-      const { byPath: byPath2, tableOf } = await checkExternalEdits2(app, settings, edits.map(({ after: _after, ...e }) => e));
+      const { byPath: byPath3, tableOf } = await checkExternalEdits2(app, settings, edits.map(({ after: _after, ...e }) => e));
       const seen = /* @__PURE__ */ new Map();
       for (const e of edits) {
         for (const full of countsIn.get(e.path)) {
           if (!seen.has(full)) seen.set(full, /* @__PURE__ */ new Set());
-          for (const v of byPath2.get(e.path) ?? []) if (tableOf.get(v.path) === full) seen.get(full).add(JSON.stringify(v));
+          for (const v of byPath3.get(e.path) ?? []) if (tableOf.get(v.path) === full) seen.get(full).add(JSON.stringify(v));
         }
       }
       for (const [full, list2] of seen) out.set(full, list2.size);
@@ -33204,7 +33592,7 @@ function addSchemaChange(cs, t, after, settings) {
     const before = new Map(t.catalog.entry.columns.map((c) => [String(c.name), c]));
     const touched = entry.columns.filter((c) => {
       const prev = before.get(String(c.name));
-      return !prev || prev.ref !== c.ref || prev.hierarchy !== c.hierarchy || prev.type !== c.type || prev.items !== c.items || prev.vocabulary !== c.vocabulary || JSON.stringify(prev.ref_by) !== JSON.stringify(c.ref_by);
+      return !prev || prev.ref !== c.ref || prev.hierarchy !== c.hierarchy || prev.acyclic !== c.acyclic || prev.type !== c.type || prev.items !== c.items || prev.vocabulary !== c.vocabulary || JSON.stringify(prev.ref_by) !== JSON.stringify(c.ref_by);
     });
     checkColumnRefs(t.catalog.model, ref2.full, touched, ref2.full, entry.columns);
     def = tableDefinitionFromOrdered(ref2, catalogTablePath(settings, ref2.full), entryToOrdered(ref2, entry, settings, t.catalog.model), settings);
@@ -33244,6 +33632,12 @@ function checkColumnRefs(model, owner, columns, where, own2 = columns) {
     if (c.hierarchy === true && ref2 !== owner) {
       throw new OperationInputError(`${where}.${String(c.name)}: a hierarchy column must point at its own table (ref: self)`);
     }
+    if (c.acyclic === true && ref2 !== owner) {
+      throw new OperationInputError(
+        `${where}.${String(c.name)}: an acyclic column must point at its own table (ref: self)`,
+        guide(`Set ref: "self": acyclic keeps the links between rows of one table free of cycles, such as tasks blocked by tasks.`, "acyclic")
+      );
+    }
     if (typeof c.inverse === "string") checkInverse(model, owner, columns, c, ref2, where);
   }
 }
@@ -33343,6 +33737,9 @@ function assertColumnName(name, what) {
   return name;
 }
 async function createTableImpl(app, settings, input, opts = {}) {
+  if (input.instructions !== void 0 && input.instructions !== null && typeof input.instructions !== "string") {
+    throw new OperationInputError(`"instructions" must be text: how to fill a row of the table`, guide(`Pass instructions as Markdown text, e.g. "1. Ask which film and when.", or leave them out.`, "instructions"));
+  }
   const proposal = input.description === null || input.columns.some((c) => c?.description === null);
   {
     const given = input.columns.find((c) => c.name === SYSTEM_ID_COLUMN);
@@ -33421,6 +33818,7 @@ async function createTableImpl(app, settings, input, opts = {}) {
     tableDefinitionFromOrdered(ref2, pseudo, cat, settings);
     const entry = withTableTags(orderedToEntry(cat, void 0, settings), tags);
     if (typeof input.rowTemplate === "string" && input.rowTemplate.trim() !== "") entry.row_template = input.rowTemplate;
+    if (typeof input.instructions === "string" && input.instructions.trim() !== "") entry.instructions = input.instructions;
     if (typeof linkTarget2 === "boolean") entry.options = { ...entry.options, autolink_target: linkTarget2 };
     if (typeof input.history === "boolean") entry.options = { ...entry.options, history: input.history };
     checkColumnRefs(model, ref2.full, entry.columns, ref2.full);
@@ -33508,6 +33906,16 @@ async function addColumnImpl(app, settings, input, opts = {}) {
     violations.push(...uniqueViolations([spec], (await loadRows(app, settings, t)).map((r) => ({ path: r.file.path, ordered: r.ordered }))));
   }
   violations.push(...await filteredLinkViolations(app, settings, t, [...t.def.columns, spec], spec));
+  const { acyclicPairs: acyclicPairs2, acyclicViolations: acyclicViolations2 } = await Promise.resolve().then(() => (init_acyclic(), acyclic_exports));
+  const withNew = [...t.def.columns, spec];
+  if (acyclicPairs2(withNew, t.catalog.ref.full).some((p) => p.column === spec.name || p.inverse === spec.name)) {
+    const rowsNow = (await loadRows(app, settings, t)).map((r) => {
+      const has = r.ordered.some(([k]) => k === spec.name);
+      const value = has ? fmGet(r.ordered, spec.name) : dense ? fill : void 0;
+      return { path: r.file.path, ordered: value === void 0 ? r.ordered : fmSet(r.ordered, spec.name, value) };
+    });
+    violations.push(...acyclicViolations2(withNew, t.catalog.ref.full, rowsNow, { involving: spec.name, wording: "check" }));
+  }
   return finish(app, settings, cs, [], violations, opts);
 }
 function withRenamedLevels(c, table, from, to) {
@@ -33700,6 +34108,7 @@ async function alterColumnImpl(app, settings, input, opts = {}) {
     else merged[k] = v;
   }
   const spec = parseColumn(merged, idx, META_KEYS);
+  const checked = spec.ref === "self" ? { ...spec, ref: t.catalog.ref.full } : spec;
   const columns = t.def.columns.map((c, i) => i === idx ? spec : c);
   const reserved = META_KEYS;
   let after = withColumns(t.ordered, columns);
@@ -33726,13 +34135,19 @@ async function alterColumnImpl(app, settings, input, opts = {}) {
         violations.push({ path: r.file.path, violations: [{ column: spec.name, code: "required", message: requiredMessage(spec) }] });
       }
     } else {
-      violations.push({ path: r.file.path, violations: validateValue(spec, v, validationContextFor(app, settings, r.file.path)) });
+      violations.push({ path: r.file.path, violations: validateValue(checked, v, validationContextFor(app, settings, r.file.path)) });
     }
     if (makeDense && !has) {
       cs.edits.push({ path: r.file.path, before: r.ordered, after: fmAdd(r.ordered, spec.name, fill ?? null) });
     }
   }
   violations.push(...await filteredLinkViolations(app, settings, t, columns, spec));
+  const { acyclicPairs: acyclicPairs2, acyclicViolations: acyclicViolations2 } = await Promise.resolve().then(() => (init_acyclic(), acyclic_exports));
+  if (acyclicPairs2(columns, t.catalog.ref.full).some((p) => p.column === spec.name || p.inverse === spec.name)) {
+    const afterOf = new Map(cs.edits.map((e) => [e.path, e.after]));
+    const rowsNow = existing.map((r) => ({ path: r.file.path, ordered: afterOf.get(r.file.path) ?? r.ordered }));
+    violations.push(...acyclicViolations2(columns, t.catalog.ref.full, rowsNow, { involving: spec.name, wording: "check" }));
+  }
   const text5 = cs.texts.find((x) => x.path === t.file.path).after;
   const conflicts = levelTargetConflicts(parseMetastore(text5), t.catalog.ref.full, spec.name).map((message) => ({ path: t.file.path, message }));
   return finish(app, settings, cs, conflicts, violations, opts);
@@ -34729,10 +35144,10 @@ var init_otlp = __esm({
           this.timer.unref?.();
         }
       }
-      push(items) {
+      push(items2) {
         const room = this.maxBatch * 8 - this.buffer.length;
-        if (room < items.length) this.dropped += items.length - Math.max(room, 0);
-        for (let i = 0; i < Math.min(items.length, Math.max(room, 0)); i++) this.buffer.push(items[i]);
+        if (room < items2.length) this.dropped += items2.length - Math.max(room, 0);
+        for (let i = 0; i < Math.min(items2.length, Math.max(room, 0)); i++) this.buffer.push(items2[i]);
         if (this.buffer.length >= this.maxBatch) void this.flush();
       }
       resource() {
@@ -48436,14 +48851,14 @@ var require_codegen = __commonJS({
         return replaceName(expr);
       if (!canOptimize(expr))
         return expr;
-      return new code_1._Code(expr._items.reduce((items, c) => {
+      return new code_1._Code(expr._items.reduce((items2, c) => {
         if (c instanceof code_1.Name)
           c = replaceName(c);
         if (c instanceof code_1._Code)
-          items.push(...c._items);
+          items2.push(...c._items);
         else
-          items.push(c);
-        return items;
+          items2.push(c);
+        return items2;
       }, []));
       function replaceName(n) {
         const c = constants2[n.str];
@@ -48601,7 +49016,7 @@ var require_util = __commonJS({
         mergeNames: (gen, from, to) => gen.if((0, codegen_1._)`${to} !== true && ${from} !== undefined`, () => gen.assign(to, (0, codegen_1._)`${from} === true ? true : ${to} > ${from} ? ${to} : ${from}`)),
         mergeToName: (gen, from, to) => gen.if((0, codegen_1._)`${to} !== true`, () => gen.assign(to, from === true ? true : (0, codegen_1._)`${to} > ${from} ? ${to} : ${from}`)),
         mergeValues: (from, to) => from === true ? true : Math.max(from, to),
-        resultToName: (gen, items) => gen.var("items", items)
+        resultToName: (gen, items2) => gen.var("items", items2)
       })
     };
     function evaluatedPropsToName(gen, ps) {
@@ -49109,13 +49524,13 @@ var require_defaults = __commonJS({
     var codegen_1 = require_codegen();
     var util_1 = require_util();
     function assignDefaults(it, ty) {
-      const { properties, items } = it.schema;
+      const { properties, items: items2 } = it.schema;
       if (ty === "object" && properties) {
         for (const key2 in properties) {
           assignDefault(it, key2, properties[key2].default);
         }
-      } else if (ty === "array" && Array.isArray(items)) {
-        items.forEach((sch, i) => assignDefault(it, i, sch.default));
+      } else if (ty === "array" && Array.isArray(items2)) {
+        items2.forEach((sch, i) => assignDefault(it, i, sch.default));
       }
     }
     exports2.assignDefaults = assignDefaults;
@@ -49919,11 +50334,11 @@ var require_validate = __commonJS({
         gen.return((0, codegen_1._)`${names_1.default.errors} === 0`);
       }
     }
-    function assignEvaluated({ gen, evaluated, props, items }) {
+    function assignEvaluated({ gen, evaluated, props, items: items2 }) {
       if (props instanceof codegen_1.Name)
         gen.assign((0, codegen_1._)`${evaluated}.props`, props);
-      if (items instanceof codegen_1.Name)
-        gen.assign((0, codegen_1._)`${evaluated}.items`, items);
+      if (items2 instanceof codegen_1.Name)
+        gen.assign((0, codegen_1._)`${evaluated}.items`, items2);
     }
     function schemaKeywords(it, types, typeErrors, errsCount) {
       const { gen, schema, data, allErrors, opts, self } = it;
@@ -50386,12 +50801,12 @@ var require_compile = __commonJS({
           validate2.source = { validateName, validateCode, scopeValues: gen._values };
         }
         if (this.opts.unevaluated) {
-          const { props, items } = schemaCxt;
+          const { props, items: items2 } = schemaCxt;
           validate2.evaluated = {
             props: props instanceof codegen_1.Name ? void 0 : props,
-            items: items instanceof codegen_1.Name ? void 0 : items,
+            items: items2 instanceof codegen_1.Name ? void 0 : items2,
             dynamicProps: props instanceof codegen_1.Name,
-            dynamicItems: items instanceof codegen_1.Name
+            dynamicItems: items2 instanceof codegen_1.Name
           };
           if (validate2.source)
             validate2.source.evaluated = (0, codegen_1.stringify)(validate2.evaluated);
@@ -52401,8 +52816,8 @@ var require_ref = __commonJS({
               it.items = util_1.mergeEvaluated.items(gen, schEvaluated.items, it.items);
             }
           } else {
-            const items = gen.var("items", (0, codegen_1._)`${source}.evaluated.items`);
-            it.items = util_1.mergeEvaluated.items(gen, items, it.items, codegen_1.Name);
+            const items2 = gen.var("items", (0, codegen_1._)`${source}.evaluated.items`);
+            it.items = util_1.mergeEvaluated.items(gen, items2, it.items, codegen_1.Name);
           }
         }
       }
@@ -52942,28 +53357,28 @@ var require_additionalItems = __commonJS({
       error: error2,
       code(cxt) {
         const { parentSchema, it } = cxt;
-        const { items } = parentSchema;
-        if (!Array.isArray(items)) {
+        const { items: items2 } = parentSchema;
+        if (!Array.isArray(items2)) {
           (0, util_1.checkStrictMode)(it, '"additionalItems" is ignored when "items" is not an array of schemas');
           return;
         }
-        validateAdditionalItems(cxt, items);
+        validateAdditionalItems(cxt, items2);
       }
     };
-    function validateAdditionalItems(cxt, items) {
+    function validateAdditionalItems(cxt, items2) {
       const { gen, schema, data, keyword, it } = cxt;
       it.items = true;
       const len = gen.const("len", (0, codegen_1._)`${data}.length`);
       if (schema === false) {
-        cxt.setParams({ len: items.length });
-        cxt.pass((0, codegen_1._)`${len} <= ${items.length}`);
+        cxt.setParams({ len: items2.length });
+        cxt.pass((0, codegen_1._)`${len} <= ${items2.length}`);
       } else if (typeof schema == "object" && !(0, util_1.alwaysValidSchema)(it, schema)) {
-        const valid = gen.var("valid", (0, codegen_1._)`${len} <= ${items.length}`);
+        const valid = gen.var("valid", (0, codegen_1._)`${len} <= ${items2.length}`);
         gen.if((0, codegen_1.not)(valid), () => validateItems(valid));
         cxt.ok(valid);
       }
       function validateItems(valid) {
-        gen.forRange("i", items.length, len, (i) => {
+        gen.forRange("i", items2.length, len, (i) => {
           cxt.subschema({ keyword, dataProp: i, dataPropType: util_1.Type.Num }, valid);
           if (!it.allErrors)
             gen.if((0, codegen_1.not)(valid), () => gen.break());
@@ -56985,6 +57400,10 @@ async function addConstraintImpl(app, settings, input, opts = {}) {
   if (!input.check || typeof input.check !== "object" || Array.isArray(input.check) || Object.keys(input.check).length === 0) {
     throw new OperationInputError(`"check" must be a non-empty where filter`, guide(`A CHECK is a where filter every row must match, e.g. {"or": [{"status": "to watch"}, {"rating": {"exists": true}}]}.`, "check"));
   }
+  if (input.hint !== void 0 && input.hint !== null && typeof input.hint !== "string") {
+    throw new OperationInputError(`"hint" must be text: what to do when a row breaks the CHECK`, guide(`Pass hint as one or two sentences, e.g. "A watched film needs a rating: ask for it.", or leave it out.`, "check"));
+  }
+  const hint = typeof input.hint === "string" && input.hint.trim() !== "" ? input.hint.trim() : void 0;
   if (cat.entry.constraints?.[input.name]) throw new OperationInputError(`constraint "${input.name}" already exists; drop it first`, guide(`Choose another name, or drop_constraint "${input.name}" first to replace it; describe_table lists the constraints.`, "check"));
   const links = new CheckLinks(app, settings);
   await links.prepare(t, input.check);
@@ -56993,7 +57412,13 @@ async function addConstraintImpl(app, settings, input, opts = {}) {
   for (const r of await loadRows(app, settings, t)) {
     if (!passes(r)) conflicts.push({ path: r.file.path, message: `violates CHECK ${input.name}` });
   }
-  const entry = { ...cat.entry, constraints: { ...cat.entry.constraints ?? {}, [input.name]: input.check } };
+  const hints = { ...constraintHints(cat.entry), ...hint ? { [input.name]: hint } : {} };
+  const { constraint_hints: _h, ...withoutHints } = cat.entry;
+  const entry = {
+    ...withoutHints,
+    constraints: { ...cat.entry.constraints ?? {}, [input.name]: input.check },
+    ...Object.keys(hints).length > 0 ? { constraint_hints: hints } : {}
+  };
   const cs = emptyChangeSet("add_constraint", `add constraint ${input.name} to ${cat.ref.full}`, t.def.schemaPath);
   cs.texts.push({ path: t.file.path, before: cat.text, after: setTableEntry(cat.text, cat.ref, entry) });
   return finish(app, settings, cs, conflicts, [], opts);
@@ -57005,8 +57430,13 @@ async function dropConstraintImpl(app, settings, input, opts = {}) {
     throw new OperationInputError(`${cat.ref.full} has no constraint "${input.name}"`, unknownName(input.name, Object.keys(cat.entry.constraints ?? {}), `constraints of ${cat.ref.full}`, "describe_table lists them.", "check"));
   }
   const { [input.name]: _gone, ...rest } = cat.entry.constraints;
-  const { constraints: _c, ...base } = cat.entry;
-  const entry = Object.keys(rest).length > 0 ? { ...base, constraints: rest } : base;
+  const { [input.name]: _x, ...hintsLeft } = constraintHints(cat.entry);
+  const { constraints: _c, constraint_hints: _h, ...base } = cat.entry;
+  const entry = {
+    ...base,
+    ...Object.keys(rest).length > 0 ? { constraints: rest } : {},
+    ...Object.keys(hintsLeft).length > 0 ? { constraint_hints: hintsLeft } : {}
+  };
   const cs = emptyChangeSet("drop_constraint", `drop constraint ${input.name} from ${cat.ref.full}`, t.def.schemaPath);
   cs.texts.push({ path: t.file.path, before: cat.text, after: setTableEntry(cat.text, cat.ref, entry) });
   return finish(app, settings, cs, [], [], opts);
@@ -57148,7 +57578,8 @@ var INFO_COLUMNS = {
     ["comment", "string"],
     ["row_count", "integer"],
     ["latest_version", "integer"],
-    ["tags", "json"]
+    ["tags", "json"],
+    ["instructions", "string"]
   ],
   columns: [
     ["table_catalog", "string"],
@@ -57164,10 +57595,11 @@ var INFO_COLUMNS = {
     ["is_identity", "string"],
     ["is_unique", "string"],
     ["inherited_from", "string"],
-    ["is_hierarchy", "string"]
+    ["is_hierarchy", "string"],
+    ["is_acyclic", "string"]
   ],
   views: [["table_catalog", "string"], ["table_schema", "string"], ["table_name", "string"], ["view_definition", "string"], ["comment", "string"], ["aliases", "list"], ["labels", "string"]],
-  check_constraints: [["table_catalog", "string"], ["table_schema", "string"], ["table_name", "string"], ["constraint_name", "string"], ["check_clause", "string"]]
+  check_constraints: [["table_catalog", "string"], ["table_schema", "string"], ["table_name", "string"], ["constraint_name", "string"], ["check_clause", "string"], ["hint", "string"]]
 };
 function informationSchemaTable(ref2) {
   const parts = ref2.trim().split(".");
@@ -57210,7 +57642,8 @@ async function informationRows(app, settings, name) {
           comment: entry.description ?? null,
           row_count: rows.get(ref2.full).length,
           latest_version: latest,
-          tags: tableTags(entry) ?? null
+          tags: tableTags(entry) ?? null,
+          instructions: tableInstructions(entry) ?? null
         });
       }
       for (const { ref: ref2, view } of catalogViews(model)) {
@@ -57223,7 +57656,8 @@ async function informationRows(app, settings, name) {
           comment: view.description ?? null,
           row_count: null,
           latest_version: null,
-          tags: null
+          tags: null,
+          instructions: null
         });
       }
       return out;
@@ -57245,7 +57679,8 @@ async function informationRows(app, settings, name) {
           is_identity: c.identity ? String(c.identity) : "NO",
           is_unique: c.unique ? "YES" : "NO",
           inherited_from: from.get(String(c.name)) ?? null,
-          is_hierarchy: c.hierarchy ? "YES" : "NO"
+          is_hierarchy: c.hierarchy ? "YES" : "NO",
+          is_acyclic: c.acyclic ? "YES" : "NO"
         }));
       });
     case "views":
@@ -57259,15 +57694,17 @@ async function informationRows(app, settings, name) {
         labels: view.labels ? JSON.stringify(view.labels) : null
       }));
     case "check_constraints":
-      return tables.flatMap(
-        ({ ref: ref2, entry }) => Object.entries(entry.constraints ?? {}).map(([n, where]) => ({
+      return tables.flatMap(({ ref: ref2, entry }) => {
+        const hintsOf = constraintHints(entry);
+        return Object.entries(entry.constraints ?? {}).map(([n, where]) => ({
           table_catalog: ref2.catalog,
           table_schema: ref2.schema,
           table_name: ref2.table,
           constraint_name: n,
-          check_clause: JSON.stringify(where)
-        }))
-      );
+          check_clause: JSON.stringify(where),
+          hint: hintsOf[n] ?? null
+        }));
+      });
   }
 }
 async function informationSchemaTableData(app, settings, name) {
@@ -57493,7 +57930,7 @@ async function defineBaseImpl(app, settings, input, opts = {}) {
   const violations = await planInheritedRows(app, settings, next, after, tablesInheriting(next, input.name), rewrite, cs);
   return finish(app, settings, cs, [], [...violations, ...await inheritedLinkViolations(app, settings, cs)], opts);
 }
-var CONSTRAINT_KEYS = ["required", "unique", "min", "max", "step", "values", "ordered", "ref", "generated", "identity", "default", "hierarchy", "ref_where", "ref_by"];
+var CONSTRAINT_KEYS = ["required", "unique", "min", "max", "step", "values", "ordered", "ref", "generated", "identity", "default", "hierarchy", "acyclic", "ref_where", "ref_by"];
 async function setTableBasesImpl(app, settings, input, opts = {}) {
   const t = await loadTable(app, settings, input.table);
   const cat = requireCatalog(t, "Inheritance");
@@ -57864,8 +58301,8 @@ function groupSelect(t, rows, join, input, known, specs, limit, offset, get) {
     let keys = [[]];
     for (const e of groupExprs) {
       const v = e.eval(q);
-      const items = Array.isArray(v) ? [...new Set(v.map((x) => groupDisplay(x)))] : [groupDisplay(v)];
-      const options = items.length > 0 ? items : [null];
+      const items2 = Array.isArray(v) ? [...new Set(v.map((x) => groupDisplay(x)))] : [groupDisplay(v)];
+      const options = items2.length > 0 ? items2 : [null];
       keys = keys.flatMap((k) => options.map((o) => [...k, o]));
     }
     for (const key2 of keys) {
@@ -58425,7 +58862,7 @@ function mentionsIn(text5, frag, ix, self) {
     if (matches2.length === 0) continue;
     const inMatch = /* @__PURE__ */ new Set();
     for (const m of matches2) for (let t = m.ti; t <= m.tj; t++) inMatch.add(t);
-    const items = [];
+    const items2 = [];
     for (let g = 0; g < matches2.length; ) {
       const group = [matches2[g]];
       let end = matches2[g].end;
@@ -58439,16 +58876,16 @@ function mentionsIn(text5, frag, ix, self) {
       const tj = Math.max(...group.map((m) => m.tj));
       if (longest.start === start && longest.end === end) {
         const kind = longest.self ? "self" : longest.cands.length > 1 ? "same_name" : "clear";
-        items.push({ frag, start, end, keys: [longest.key], cands: longest.cands, kind, ti, tj });
+        items2.push({ frag, start, end, keys: [longest.key], cands: longest.cands, kind, ti, tj });
       } else {
         const cands = [...new Set(group.flatMap((m) => m.cands))].sort();
-        items.push({ frag, start, end, keys: group.map((m) => m.key), cands, kind: cands.length === 0 ? "self" : "overlap", ti, tj });
+        items2.push({ frag, start, end, keys: group.map((m) => m.key), cands, kind: cands.length === 0 ? "self" : "overlap", ti, tj });
       }
     }
-    for (let i = 0; i < items.length; ) {
+    for (let i = 0; i < items2.length; ) {
       let j = i;
-      while (j + 1 < items.length && items[j].kind !== "self" && items[j + 1].kind !== "self" && PHRASE_SEP.test(text5.slice(items[j].end, items[j + 1].start))) j++;
-      const run = items.slice(i, j + 1);
+      while (j + 1 < items2.length && items2[j].kind !== "self" && items2[j + 1].kind !== "self" && PHRASE_SEP.test(text5.slice(items2[j].end, items2[j + 1].start))) j++;
+      const run = items2.slice(i, j + 1);
       const cands = [...new Set(run.flatMap((m) => m.cands))].sort();
       if (run.length > 1 && cands.length > 1) {
         out.push({ frag, start: run[0].start, end: run.at(-1).end, keys: run.flatMap((m) => m.keys), cands, kind: "adjacent" });
@@ -58681,7 +59118,7 @@ async function verifyUniqueValues(app, settings) {
     const v = VALUES.get(app).get(full);
     const rows = await loadRows(app, settings, t);
     const want = new Map(rows.map((r) => [r.file.path, v.columns.map((c) => uniqueKey(fmGet(r.ordered, c)))]));
-    const show = (byPath2) => JSON.stringify([...byPath2].sort(([a], [b]) => a < b ? -1 : 1));
+    const show = (byPath3) => JSON.stringify([...byPath3].sort(([a], [b]) => a < b ? -1 : 1));
     if (show(v.byPath) !== show(want)) out.push(`unique values of ${full} differ from its rows`);
     const byKey = v.columns.map((_, i) => {
       const m = /* @__PURE__ */ new Map();
@@ -59464,6 +59901,7 @@ init_path_templates();
 init_computed_columns();
 init_where();
 init_message();
+init_hints();
 init_descriptions();
 function escapeRegExp(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -59478,7 +59916,7 @@ function archivedRowFiles(app, settings, t) {
     return rowTableFull(model, fm?.[settings.tableKey]) === full;
   });
 }
-async function relocateTable(app, settings, t, dest, changes, opts, properties = {}, rowTemplate2, tags, fields = {}) {
+async function relocateTable(app, settings, t, dest, changes, opts, properties = {}, rowTemplate2, tags, fields = {}, instructions) {
   const conflicts = [];
   const merged = { ...serializeOptions(t.def.options)[0] };
   for (const [k, v] of Object.entries(changes)) {
@@ -59518,6 +59956,8 @@ async function relocateTable(app, settings, t, dest, changes, opts, properties =
     }
     if (rowTemplate2 === null || typeof rowTemplate2 === "string" && rowTemplate2.trim() === "") delete entry.row_template;
     else if (typeof rowTemplate2 === "string") entry.row_template = rowTemplate2;
+    if (instructions === null || typeof instructions === "string" && instructions.trim() === "") delete entry.instructions;
+    else if (typeof instructions === "string") entry.instructions = instructions;
     const after = setTableEntries(text5, [...t.catalog.ref.full !== ref2.full ? [[t.catalog.ref, null]] : [], [ref2, tags === void 0 ? entry : withTableTags(entry, tags)]]);
     const from = t.catalog.ref.full;
     cs = emptyChangeSet("alter_table", from === ref2.full ? `alter table ${from}` : `move table ${from} to ${ref2.full}`, catalogTablePath(settings, ref2.full));
@@ -59612,6 +60052,9 @@ function fieldsInput(t, settings, value) {
   return out;
 }
 async function alterTableImpl(app, settings, input, opts = {}) {
+  if (input.instructions !== void 0 && input.instructions !== null && typeof input.instructions !== "string") {
+    throw new OperationInputError(`"instructions" must be text: how to fill a row of the table`, guide(`Pass instructions as Markdown text, e.g. "1. Ask which film and when.", or leave them out; "" removes them.`, "instructions"));
+  }
   const t = await loadTable(app, settings, input.table);
   const cfg = await readDatabaseConfig(app, settings);
   const schema = assertIdentifier("schema", input.schema ?? t.def.schema);
@@ -59661,7 +60104,7 @@ async function alterTableImpl(app, settings, input, opts = {}) {
   return relocateTable(app, settings, t, { catalogRef: refOf(catalog, schema, name) }, changes, opts, {
     ...input.history !== void 0 ? { history: input.history } : {},
     ...input.autolinkTarget !== void 0 ? { autolink_target: input.autolinkTarget } : {}
-  }, input.rowTemplate, tags, fields);
+  }, input.rowTemplate, tags, fields, input.instructions);
 }
 var alterTable = instrumented("alter_table", alterTableImpl, (i) => ({ table: i.table, schema: i.schema, name: i.name }));
 
@@ -60743,13 +61186,13 @@ function inferColumns(app, settings, observed, files, maxEnum) {
     if (kind === null && kinds.has("list")) kind = "list";
     if (kind === null) kind = "string";
     if (kind === "list") {
-      const items = filled.flatMap((x) => Array.isArray(x.value) ? x.value : [x.value]).filter((v) => !isEmpty(v));
-      const itemKind = mergeKinds(new Set(items.map(kindOf))) ?? "string";
+      const items2 = filled.flatMap((x) => Array.isArray(x.value) ? x.value : [x.value]).filter((v) => !isEmpty(v));
+      const itemKind = mergeKinds(new Set(items2.map(kindOf))) ?? "string";
       col.type = "list";
-      const itemDistinct = [...new Set(items.map((v) => String(v).trim()))];
-      if (itemKind === "string" && itemDistinct.length > 0 && itemDistinct.length <= maxEnum && items.length >= 3 && itemDistinct.length * 2 <= items.length) {
+      const itemDistinct = [...new Set(items2.map((v) => String(v).trim()))];
+      if (itemKind === "string" && itemDistinct.length > 0 && itemDistinct.length <= maxEnum && items2.length >= 3 && itemDistinct.length * 2 <= items2.length) {
         col.items = "enum";
-        col.values = frequencyOrder(items.map((v) => String(v).trim()));
+        col.values = frequencyOrder(items2.map((v) => String(v).trim()));
       } else {
         col.items = itemKind === "list" ? "string" : itemKind;
       }
@@ -60990,6 +61433,8 @@ async function describeTable(app, settings, table) {
   const o = def.options;
   const e = t.catalog.entry;
   const tags = tableTags(e);
+  const hints = constraintHints(e);
+  const instructions = tableInstructions(e);
   const missing = missingDescriptions(o.description, def.columns);
   return {
     qualified: t.catalog.ref.full,
@@ -61012,6 +61457,8 @@ async function describeTable(app, settings, table) {
     ...missing ? { missing_descriptions: missing } : {},
     ...e.bases && e.bases.length > 0 ? { bases: [...e.bases] } : {},
     ...e.constraints && Object.keys(e.constraints).length > 0 ? { constraints: e.constraints } : {},
+    ...Object.keys(hints).length > 0 ? { constraint_hints: hints } : {},
+    ...instructions !== void 0 ? { instructions } : {},
     ...typeof e.row_template === "string" ? { row_template: e.row_template } : {},
     ...typeof e.options?.history === "boolean" ? { history: e.options.history } : {},
     ...typeof e.options?.autolink_target === "boolean" ? { autolink_target: e.options.autolink_target } : {},
@@ -61476,17 +61923,17 @@ var SemanticIndex = class {
     const staged = /* @__PURE__ */ new Map();
     const empty = new Int8Array(0);
     const flush2 = async () => {
-      const items = queue.filter((x) => staged.has(x.path));
+      const items2 = queue.filter((x) => staged.has(x.path));
       queue = [];
-      if (items.length === 0) return;
+      if (items2.length === 0) return;
       try {
-        const vectors = await embed(this.transport, cfg, items.map((x) => x.text));
-        items.forEach((x, j) => {
+        const vectors = await embed(this.transport, cfg, items2.map((x) => x.text));
+        items2.forEach((x, j) => {
           staged.get(x.path).vectors[x.i] = normalize(vectors[j]);
         });
       } catch (e) {
         const error2 = messageOf(e);
-        for (const x of new Set(items.map((y) => y.path))) {
+        for (const x of new Set(items2.map((y) => y.path))) {
           staged.delete(x);
           result.failed.push({ path: x, error: error2 });
           this.pending.add(x);
@@ -62781,12 +63228,12 @@ var ChangeFeed = class {
         };
       });
       try {
-        const { byPath: byPath2, tableOf } = await checkExternalEdits(this.app, s, edits);
+        const { byPath: byPath3, tableOf } = await checkExternalEdits(this.app, s, edits);
         const rows = /* @__PURE__ */ new Set();
         const tables = /* @__PURE__ */ new Set();
         let n = 0;
         for (const [path19, i] of last) {
-          const violations = byPath2.get(path19) ?? [];
+          const violations = byPath3.get(path19) ?? [];
           out[i] = { ...out[i], ...capped(violations) };
           n += violations.length;
           for (const v of violations) {
@@ -63837,6 +64284,7 @@ function createHandlers(app, getSettings, saveSettings = async () => {
       if (target !== void 0) options2.autolink_target = target;
       const history2 = optBool(b, "history");
       const template = text3(b, "row_template");
+      const instructions = text3(b, "instructions");
       return opResponse(
         await createTable(
           app,
@@ -63853,6 +64301,7 @@ function createHandlers(app, getSettings, saveSettings = async () => {
             ...obj(b, "fields") ? { fields: obj(b, "fields") } : {},
             columns: list(b, "columns"),
             ...template !== void 0 ? { rowTemplate: template } : {},
+            ...instructions !== void 0 ? { instructions } : {},
             ...obj(b, "tags") ? { tags: obj(b, "tags") } : {}
           },
           runOpts(b)
@@ -63869,6 +64318,7 @@ function createHandlers(app, getSettings, saveSettings = async () => {
       const target = b.autolink_target;
       const description = text3(b, "description");
       const template = text3(b, "row_template");
+      const instructions = text3(b, "instructions");
       const archive = text3(b, "archive");
       const partition = text3(b, "partition");
       return opResponse(
@@ -63889,6 +64339,8 @@ function createHandlers(app, getSettings, saveSettings = async () => {
             ...target === "default" ? { autolinkTarget: null } : typeof target === "boolean" ? { autolinkTarget: target } : {},
             // "" removes the template
             ...template !== void 0 ? { rowTemplate: template === "" ? null : template } : {},
+            // "" removes the instructions
+            ...instructions !== void 0 ? { instructions: instructions === "" ? null : instructions } : {},
             ...obj(b, "tags") ? { tags: obj(b, "tags") } : {},
             ...optBool(b, "clear_tags") === true ? { clearTags: true } : {},
             ...archive !== void 0 ? { archive } : {},
@@ -63936,7 +64388,7 @@ function createHandlers(app, getSettings, saveSettings = async () => {
       );
     },
     set_table_bases: async (b) => opResponse(await setTableBases(app, s(), { table: str(b, "table"), bases: strings(b, "bases") }, runOpts(b))),
-    add_constraint: async (b) => opResponse(await addConstraint(app, s(), { table: str(b, "table"), name: str(b, "name"), check: obj(b, "check") }, runOpts(b))),
+    add_constraint: async (b) => opResponse(await addConstraint(app, s(), { table: str(b, "table"), name: str(b, "name"), check: obj(b, "check"), ...text3(b, "hint") !== void 0 ? { hint: text3(b, "hint") } : {} }, runOpts(b))),
     drop_constraint: async (b) => opResponse(await dropConstraint(app, s(), { table: str(b, "table"), name: str(b, "name") }, runOpts(b))),
     create_view: async (b) => opResponse(
       await createView(
@@ -71693,7 +72145,7 @@ function setUp(o, vault, home, explicit, self) {
 // src/node/service.ts
 init_local();
 init_hints();
-var VERSION = true ? "3.1.0" : "dev";
+var VERSION = true ? "3.2.0" : "dev";
 function parsePort(raw, from = "--port") {
   const n = /^\s*\d+\s*$/.test(raw) ? Number(raw) : NaN;
   if (n === 0 || Number.isInteger(n) && n >= 1024 && n <= 65535) return n;
@@ -72731,7 +73183,7 @@ Docs: https://datanotes.dev`;
 
 // src/node/cli.ts
 init_message();
-var VERSION2 = true ? "3.1.0" : "dev";
+var VERSION2 = true ? "3.2.0" : "dev";
 var consoleError = console.error;
 async function main5(argv = process.argv.slice(2)) {
   const [command, ...rest] = argv;