datanotes 3.1.0 → 3.2.0

package/dist/api/index.js

@@ -330,7 +330,7 @@ var OPERATIONS = [
   },
   {
     "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": {
@@ -453,6 +453,10 @@ var OPERATIONS = [
               "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.",
@@ -562,6 +566,17 @@ var OPERATIONS = [
           },
           "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."
@@ -595,7 +610,7 @@ var OPERATIONS = [
   },
   {
     "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": {
@@ -756,6 +771,18 @@ var OPERATIONS = [
           "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": [
             {
@@ -893,6 +920,10 @@ var OPERATIONS = [
                       "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": [
@@ -1302,6 +1333,10 @@ var OPERATIONS = [
                       "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": [
@@ -1581,7 +1616,7 @@ var OPERATIONS = [
   },
   {
     "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": {
@@ -1702,6 +1737,10 @@ var OPERATIONS = [
                       "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": [
@@ -2104,6 +2143,10 @@ var OPERATIONS = [
                       "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": [
@@ -2503,6 +2546,10 @@ var OPERATIONS = [
                       "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": [
@@ -2782,7 +2829,7 @@ var OPERATIONS = [
   },
   {
     "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": {
@@ -2907,6 +2954,10 @@ var OPERATIONS = [
                       "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": [
@@ -3186,7 +3237,7 @@ var OPERATIONS = [
   },
   {
     "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": {
@@ -3336,6 +3387,18 @@ var OPERATIONS = [
           "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": [
             {
@@ -3496,6 +3559,10 @@ var OPERATIONS = [
                       "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": [
@@ -3952,6 +4019,10 @@ var OPERATIONS = [
                       "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": [
@@ -4353,6 +4424,10 @@ var OPERATIONS = [
                       "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": [
@@ -5415,6 +5490,10 @@ var OPERATIONS = [
                       "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": [
@@ -5821,6 +5900,10 @@ var OPERATIONS = [
                       "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": [
@@ -6100,7 +6183,7 @@ var OPERATIONS = [
   },
   {
     "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": {
@@ -6255,6 +6338,10 @@ var OPERATIONS = [
                       "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": [
@@ -6693,6 +6780,10 @@ var OPERATIONS = [
                       "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": [
@@ -7206,6 +7297,10 @@ var OPERATIONS = [
                       "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": [
@@ -7637,6 +7732,10 @@ var OPERATIONS = [
                       "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": [
@@ -8085,6 +8184,10 @@ var OPERATIONS = [
                       "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": [
@@ -8545,6 +8648,10 @@ var OPERATIONS = [
                       "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": [
@@ -9053,7 +9160,7 @@ var OPERATIONS = [
   },
   {
     "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": {
@@ -9166,6 +9273,10 @@ var OPERATIONS = [
                       "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": [
@@ -9619,6 +9730,10 @@ var OPERATIONS = [
                                 "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": [
@@ -10062,6 +10177,10 @@ var OPERATIONS = [
                       "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": [
@@ -11145,6 +11264,10 @@ var OPERATIONS = [
                       "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": [
@@ -12582,6 +12705,10 @@ var OPERATIONS = [
                       "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": [
@@ -12992,6 +13119,10 @@ var OPERATIONS = [
                       "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": [
@@ -13458,7 +13589,7 @@ var OPERATIONS = [
   },
   {
     "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": {
@@ -13472,6 +13603,18 @@ var OPERATIONS = [
           "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"
@@ -13582,6 +13725,10 @@ var OPERATIONS = [
                       "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": [
@@ -13980,6 +14127,10 @@ var OPERATIONS = [
                       "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": [
@@ -14445,6 +14596,10 @@ var OPERATIONS = [
                       "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": [
@@ -14839,6 +14994,10 @@ var OPERATIONS = [
                       "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": [
@@ -15264,6 +15423,10 @@ var OPERATIONS = [
                       "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": [
@@ -15676,6 +15839,10 @@ var OPERATIONS = [
                       "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": [