datanotes 3.1.0 → 3.2.0

package/dist/docs/reference/operations/schema.md

@@ -13,10 +13,11 @@ Every write is validated. Writes to rows and to the schema are journaled and und
 Create a table: `name`, in `catalog` and `schema` (default: the database’s defaults); the definition goes in metastore.yaml, the rows in `<root>/<catalog>/<schema>/<name>/`. Names: lowercase letters, digits, `_` (no dots: pass the catalog and the schema as their own arguments).
 
 * `description` (required): what a row of the table records. Every column needs its own `description` too, what it holds: the table is refused otherwise, with every missing one listed. Descriptions are how agents and people understand the schema, so write them for a reader who never saw the notes. The engine writes those of `id` and of `identity` “uuid” / “created” columns.
-* `columns`: specs like `{"name": "kind", "type": "enum", "values": ["a","b"], "required": true, "description": "What kind of entry the row is"}`. Types: string, integer, number, boolean, date, datetime, enum, link, list (+ `items`), json. Attributes: required, default (`"{now}"`/`"{today}"`), min, max, step, values, `ordered` (enum in order: filters/avg use the position), ref (link target, full `catalog.schema.table` or “self”), unique, label, description, aliases, `generated` (e.g. `"date(occurred_at)"`, `"{name} {surname}"`), `identity` (“filename” | “created”), `vocabulary` (allowed values = names of another table’s rows), `hierarchy: true` (one parent link to its own table), `dense` (written on every row), `inverse` on a link column: the column of the `ref` table that links back (`friends` ↔ `friends`, `children` ↔ `parents`, `partner` ↔ `partner`); writes keep both sides in step.
+* `columns`: specs like `{"name": "kind", "type": "enum", "values": ["a","b"], "required": true, "description": "What kind of entry the row is"}`. Types: string, integer, number, boolean, date, datetime, enum, link, list (+ `items`), json. Attributes: required, default (`"{now}"`/`"{today}"`), min, max, step, values, `ordered` (enum in order: filters/avg use the position), ref (link target, full `catalog.schema.table` or “self”), unique, label, description, aliases, `generated` (e.g. `"date(occurred_at)"`, `"{name} {surname}"`), `identity` (“filename” | “created”), `vocabulary` (allowed values = names of another table’s rows), `hierarchy: true` (one parent link to its own table), `acyclic: true` (links to rows of its own table that never loop back, such as tasks blocked by tasks; with `inverse`, the rule holds on both sides), `dense` (written on every row), `inverse` on a link column: the column of the `ref` table that links back (`friends` ↔ `friends`, `children` ↔ `parents`, `partner` ↔ `partner`); writes keep both sides in step.
 * `time_column`: rows named by that date/datetime; otherwise `filename` (e.g. `"{name}"`).
 * The table’s options, as alter_table names them: `aliases` (how agents find it, with the description), `partition`, `exclude`, `archive`, `history` (keep its versions; default: the database’s setting), `autolink_target` (true / false: may automatic links link its rows? default: yes, unless its rows are named by a date or a time, as with `time_column`).
 * `row_template`: markdown body of new rows. Shared columns come from bases: `set_table_bases`.
+* `instructions`: how to fill a row, for agents (Markdown); describe_table returns them.
 * `tags`: key/value labels of the table, strings (`{"domain": "health"}`); list_tables and describe_table return them, alter_table changes them. Enum columns: `values` and, for each, its meaning in `value_descriptions` (`{"stated": "the user said it", …}`): describe_table shows them and a refused value lists them. Generated link columns: `generated: "link({occurred_at:YYYY-MM-DD})"` with `ref` = the days table links each row to the row of `ref` named by the template (its folder read from the schema; the target may not exist yet). Filtered link targets (link columns): `ref_where` (a `where` every target must match) and `ref_by` (a column of the row picks the target level: `{"column": "kind", "levels": ["area", "project", "workstream"]}` or `{"column": "kind", "map": {"area": null, "project": ["area"]}}`; null = top level, no link; `target_column` when the target names it differently: an enum target column must have every value the map allows, a string one takes any value). A link to no row of the table, or to the row itself, is refused too. Existing rows that break them refuse the change; `list_link_targets` lists the valid targets of a row.
 
 The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).
@@ -39,6 +40,7 @@ Examples: [Catalogs, schemas and the database](https://datanotes.dev/guides/data
 | `history`         | boolean \\   | null     |         | `null`      |
 | `autolink_target` | boolean \\   | null     |         | `null`      |
 | `row_template`    | string \\    | null     |         | `null`      |
+| `instructions`    | string \\    | null     |         | `null`      |
 | `fields`          | object \\    | null     |         | `null`      |
 | `tags`            | object \\    | null     |         | `null`      |
 | `dry_run`         | boolean      |          | `false` |             |
@@ -63,7 +65,7 @@ Examples: [Tables](https://datanotes.dev/guides/database-objects/tables/).
 
 **Alter Table** · destructive write
 
-Alter a table: move it (`catalog`, `schema`), rename it (`name`), change `partition` / `filename` patterns, `description` (changes, never goes: “” is refused), `aliases`, `exclude` folders, `row_template` (“” removes it), `history` (true | false | “default”), `autolink_target` (true | false | “default”: may automatic links link its rows? default: yes, unless its rows are named by a date or a time) or `tags` (key/value labels merged into the table’s, e.g. `{"domain": "health"}`; a `null` value removes that tag; `clear_tags: true` removes every tag first, so with `tags` the table keeps exactly those), `archive` (folder name inside the table folder) or `fields` (untyped fields, name → default; a `null` value removes one). Rows, archive and transaction log follow; links are updated; renamed rows keep their old name in `aliases`. A change of metadata only (tags, description, aliases, history, autolink_target, row_template, fields) rewrites the table entry alone: no row is moved or rewritten. Refused when a row cannot fill a pattern. Renaming or moving the table is refused while a CHECK that follows links, or a `ref_where` / `ref_by`, of another table reads it through a link (link targets are not rewritten): the conflicts name them. Use `dry_run` to see `planned_moves`; undo with undo_migration.
+Alter a table: move it (`catalog`, `schema`), rename it (`name`), change `partition` / `filename` patterns, `description` (changes, never goes: “” is refused), `aliases`, `exclude` folders, `row_template` (“” removes it), `instructions` (how to fill a row, for agents; “” removes them), `history` (true | false | “default”), `autolink_target` (true | false | “default”: may automatic links link its rows? default: yes, unless its rows are named by a date or a time) or `tags` (key/value labels merged into the table’s, e.g. `{"domain": "health"}`; a `null` value removes that tag; `clear_tags: true` removes every tag first, so with `tags` the table keeps exactly those), `archive` (folder name inside the table folder) or `fields` (untyped fields, name → default; a `null` value removes one). Rows, archive and transaction log follow; links are updated; renamed rows keep their old name in `aliases`. A change of metadata only (tags, description, aliases, history, autolink_target, row_template, instructions, fields) rewrites the table entry alone: no row is moved or rewritten. Refused when a row cannot fill a pattern. Renaming or moving the table is refused while a CHECK that follows links, or a `ref_where` / `ref_by`, of another table reads it through a link (link targets are not rewritten): the conflicts name them. Use `dry_run` to see `planned_moves`; undo with undo_migration.
 
 The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).
 
@@ -83,6 +85,7 @@ Examples: [Catalogs, schemas and the database](https://datanotes.dev/guides/data
 | `autolink_target` | boolean \\   | `"default"` \\ | null    |                                                                      |
 | `exclude`         | string\[] \\ | null           |         | `null`                                                               |
 | `row_template`    | string \\    | null           |         | `null`                                                               |
+| `instructions`    | string \\    | null           |         | `null`                                                               |
 | `tags`            | object \\    | null           |         | `null`                                                               |
 | `clear_tags`      | boolean      |                | `false` | Remove every tag first (with `tags`: the table keeps exactly those). |
 | `archive`         | string \\    | null           |         | `null`                                                               |
@@ -112,7 +115,7 @@ Examples: [Tables](https://datanotes.dev/guides/database-objects/tables/), [Base
 
 **Add Column** · write
 
-Add a typed column. Sparse by default (written only on rows that have a value — use for metrics, e.g. `{"name": "metric_mood", "type": "integer", "min": 1, "max": 5, "label": "Mood", "aliases": ["mood"], "description": "Mood of the day, 1 = bad, 5 = great"}`). `description` is required: what the column holds, for the agents and people who read the schema (the engine writes it for `identity` “uuid” / “created” columns). `dense: true` in the spec adds it to every row with its `default`. Call `describe_table` first: never add a column whose meaning an existing column (name/label/aliases/description) already covers. Column names are permanent identifiers; only `rename_column` changes them. Enum columns: `values` and, for each, its meaning in `value_descriptions` (`{"stated": "the user said it", …}`): describe_table shows them and a refused value lists them. Generated link columns: `generated: "link({occurred_at:YYYY-MM-DD})"` with `ref` = the days table links each row to the row of `ref` named by the template (its folder read from the schema; the target may not exist yet). Filtered link targets (link columns): `ref_where` (a `where` every target must match) and `ref_by` (a column of the row picks the target level: `{"column": "kind", "levels": ["area", "project", "workstream"]}` or `{"column": "kind", "map": {"area": null, "project": ["area"]}}`; null = top level, no link; `target_column` when the target names it differently: an enum target column must have every value the map allows, a string one takes any value). A link to no row of the table, or to the row itself, is refused too. Existing rows that break them refuse the change; `list_link_targets` lists the valid targets of a row.
+Add a typed column. Sparse by default (written only on rows that have a value — use for metrics, e.g. `{"name": "metric_mood", "type": "integer", "min": 1, "max": 5, "label": "Mood", "aliases": ["mood"], "description": "Mood of the day, 1 = bad, 5 = great"}`). `description` is required: what the column holds, for the agents and people who read the schema (the engine writes it for `identity` “uuid” / “created” columns). `dense: true` in the spec adds it to every row with its `default`. Call `describe_table` first: never add a column whose meaning an existing column (name/label/aliases/description) already covers. Column names are permanent identifiers; only `rename_column` changes them. Enum columns: `values` and, for each, its meaning in `value_descriptions` (`{"stated": "the user said it", …}`): describe_table shows them and a refused value lists them. Generated link columns: `generated: "link({occurred_at:YYYY-MM-DD})"` with `ref` = the days table links each row to the row of `ref` named by the template (its folder read from the schema; the target may not exist yet). Filtered link targets (link columns): `ref_where` (a `where` every target must match) and `ref_by` (a column of the row picks the target level: `{"column": "kind", "levels": ["area", "project", "workstream"]}` or `{"column": "kind", "map": {"area": null, "project": ["area"]}}`; null = top level, no link; `target_column` when the target names it differently: an enum target column must have every value the map allows, a string one takes any value). A link to no row of the table, or to the row itself, is refused too. Existing rows that break them refuse the change; `list_link_targets` lists the valid targets of a row. Acyclic links: `acyclic: true` on a link (or list of links) to the table itself refuses every write that closes a cycle, on either side of an `inverse`; refused while existing rows form one (they are listed).
 
 The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).
 
@@ -161,7 +164,7 @@ Examples: [Columns and types](https://datanotes.dev/guides/database-objects/colu
 
 **Alter Column** · destructive write
 
-Change a column’s attributes (type, min/max/step, values, required, default, label, aliases, description, note, `ref_where`, `ref_by` (see list_link_targets); `null` removes an attribute, except `description`, which changes but never goes (null or “” is refused); `dense` true/false). Refused with the list of violating rows when existing values do not satisfy the new definition. A different scale means a different column: add a new one instead of rescaling. To rename one enum value use `rename_value`. Dropping an enum value that a `ref_by` (of any table) allows as a target level is refused, naming it.
+Change a column’s attributes (type, min/max/step, values, required, default, label, aliases, description, note, `ref_where`, `ref_by` (see list_link_targets), `acyclic` (refused while the rows already form a cycle: they are listed); `null` removes an attribute, except `description`, which changes but never goes (null or “” is refused); `dense` true/false). Refused with the list of violating rows when existing values do not satisfy the new definition. A different scale means a different column: add a new one instead of rescaling. To rename one enum value use `rename_value`. Dropping an enum value that a `ref_by` (of any table) allows as a target level is refused, naming it.
 
 The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).
 
@@ -249,18 +252,19 @@ Examples: [Bases](https://datanotes.dev/guides/database-objects/bases/).
 
 **Add Constraint** · write
 
-ALTER TABLE ADD CONSTRAINT `name` CHECK: `check` is a where filter every row must match, e.g. `{"value": {"gte": 1, "lte": 5}}`. A condition on a column the row leaves empty passes, like SQL; inside `or` / `and` / `not` an empty value is tested as it is (`{"exists": true}` there fails). A key may follow a link column to the row it names, as in queries: `{"parent.kind": "project"}` (further dots follow further links). An empty link passes at the top level and fails inside `or` / `and` / `not`; only the first link of a longer path is skipped when empty (`parent.parent.kind` fails for a row whose parent has no parent). A link to a row that does not exist fails; on a list of links every linked row must match. `not` turns that into a pass: `{"not": {"parent.kind": "area"}}` passes a link to a missing row, so add `"parent.kind": {"exists": true}` to require a real one. Links resolve as in the vault (by path, from the row’s note: same-named rows in two folders stay apart); renaming or moving a linked row keeps them (they follow it). Refused while existing rows violate it (they are listed); then enforced on every write, by the same rule. A write that changes a linked row re-checks the rows that link to it and is refused, listing them, when it breaks them, naming the changed row (in a batch, re-link them first: each step is checked on the vault the earlier ones left); the inverse links a write adds, undo_migration and restore_table are checked too. rename_column / rename_value follow into CHECKs; drop_column of a column a CHECK reads is refused.
+ALTER TABLE ADD CONSTRAINT `name` CHECK: `check` is a where filter every row must match, e.g. `{"value": {"gte": 1, "lte": 5}}`. A condition on a column the row leaves empty passes, like SQL; inside `or` / `and` / `not` an empty value is tested as it is (`{"exists": true}` there fails). A key may follow a link column to the row it names, as in queries: `{"parent.kind": "project"}` (further dots follow further links). An empty link passes at the top level and fails inside `or` / `and` / `not`; only the first link of a longer path is skipped when empty (`parent.parent.kind` fails for a row whose parent has no parent). A link to a row that does not exist fails; on a list of links every linked row must match. `not` turns that into a pass: `{"not": {"parent.kind": "area"}}` passes a link to a missing row, so add `"parent.kind": {"exists": true}` to require a real one. Links resolve as in the vault (by path, from the row’s note: same-named rows in two folders stay apart); renaming or moving a linked row keeps them (they follow it). Refused while existing rows violate it (they are listed); then enforced on every write, by the same rule. A write that changes a linked row re-checks the rows that link to it and is refused, listing them, when it breaks them, naming the changed row (in a batch, re-link them first: each step is checked on the vault the earlier ones left); the inverse links a write adds, undo_migration and restore_table are checked too. rename_column / rename_value follow into CHECKs; drop_column of a column a CHECK reads is refused. `hint`: what to do when a row breaks the rule, in your words; a refused write puts it first in its hint, and each violation of the CHECK carries it.
 
 The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).
 
 Examples: [CHECK constraints](https://datanotes.dev/guides/data-quality/check-constraints/).
 
-| Parameter | Type    | Required | Default | Description |
-| --------- | ------- | -------- | ------- | ----------- |
-| `table`   | string  | yes      |         |             |
-| `name`    | string  | yes      |         |             |
-| `check`   | object  | yes      |         |             |
-| `dry_run` | boolean |          | `false` |             |
+| Parameter | Type      | Required | Default | Description |
+| --------- | --------- | -------- | ------- | ----------- |
+| `table`   | string    | yes      |         |             |
+| `name`    | string    | yes      |         |             |
+| `check`   | object    | yes      |         |             |
+| `hint`    | string \\ | null     |         | `null`      |
+| `dry_run` | boolean   |          | `false` |             |
 
 ## `drop_constraint`
 

package/dist/docs/reference/operations.md

@@ -10,24 +10,24 @@ Next to them, `datanotes mcp` offers three tools that read these docs offline, `
 
 Operations that define the database: tables, columns, constraints, bases and views. [Schema operations (DDL)](https://datanotes.dev/reference/operations/schema/) lists their parameters.
 
-| Operation                                                          | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Examples                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`create_table`](https://datanotes.dev/reference/operations/schema/#create_table)       | Create a table: `name`, in `catalog` and `schema` (default: the database’s defaults); the definition goes in metastore.yaml, the rows in `<root>/<catalog>/<schema>/<name>/`.                                                                                                                                                                                                                                                                                                  | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Tables](https://datanotes.dev/guides/database-objects/tables/), [Columns and types](https://datanotes.dev/guides/database-objects/columns/), [Bases](https://datanotes.dev/guides/database-objects/bases/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [Write and move rows](https://datanotes.dev/guides/read-and-write/write-rows/), [Automatic links](https://datanotes.dev/guides/read-and-write/automatic-links/), [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/) |
-| [`drop_table`](https://datanotes.dev/reference/operations/schema/#drop_table)           | Drop a table.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | [Tables](https://datanotes.dev/guides/database-objects/tables/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| [`alter_table`](https://datanotes.dev/reference/operations/schema/#alter_table)         | Alter a table: move it (`catalog`, `schema`), rename it (`name`), change `partition` / `filename` patterns, `description` (changes, never goes: “” is refused), `aliases`, `exclude` folders, `row_template` (“” removes it), `history` (true \| false \| “default”), `autolink_target` (true \| false \| “default”: may automatic links link its rows? default: yes, unless its rows are named by a date or a time) or `tags` (key/value labels merged into the table’s, e.g. | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Tables](https://datanotes.dev/guides/database-objects/tables/), [Automatic links](https://datanotes.dev/guides/read-and-write/automatic-links/), [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/)                                                                                                                                                                                                                                |
-| [`clone_table`](https://datanotes.dev/reference/operations/schema/#clone_table)         | CREATE TABLE `target` CLONE `source`: same definition plus independent copies of its rows (deep clone), optionally as of a `version` / `timestamp`.                                                                                                                                                                                                                                                                                                                            | [Tables](https://datanotes.dev/guides/database-objects/tables/), [Bases](https://datanotes.dev/guides/database-objects/bases/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/)                                                                                                                                                                                                                                                                                                                                                                                                       |
-| [`add_column`](https://datanotes.dev/reference/operations/schema/#add_column)           | Add a typed column.                                                                                                                                                                                                                                                                                                                                                                                                                                                            | [Columns and types](https://datanotes.dev/guides/database-objects/columns/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/)                                                                                                                                                                                                                                                                                                                                                                     |
-| [`rename_column`](https://datanotes.dev/reference/operations/schema/#rename_column)     | Rename a column in metastore.yaml and on every row.                                                                                                                                                                                                                                                                                                                                                                                                                            | [Columns and types](https://datanotes.dev/guides/database-objects/columns/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| [`drop_column`](https://datanotes.dev/reference/operations/schema/#drop_column)         | Remove a column from the schema and every row.                                                                                                                                                                                                                                                                                                                                                                                                                                 | [Columns and types](https://datanotes.dev/guides/database-objects/columns/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| [`alter_column`](https://datanotes.dev/reference/operations/schema/#alter_column)       | Change a column’s attributes (type, min/max/step, values, required, default, label, aliases, description, note, `ref_where`, `ref_by` (see list_link_targets); `null` removes an attribute, except `description`, which changes but never goes (null or “” is refused); `dense` true/false).                                                                                                                                                                                   | [Tables](https://datanotes.dev/guides/database-objects/tables/), [Columns and types](https://datanotes.dev/guides/database-objects/columns/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/)                                                                                                                                                                                                                                                                                                                                                                                        |
-| [`rename_value`](https://datanotes.dev/reference/operations/schema/#rename_value)       | Rename one value of an enum column (e.g.                                                                                                                                                                                                                                                                                                                                                                                                                                       | [Columns and types](https://datanotes.dev/guides/database-objects/columns/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| [`comment_on`](https://datanotes.dev/reference/operations/schema/#comment_on)           | COMMENT ON CATALOG / SCHEMA: set the `description` of a catalog (`catalog` alone) or of one of its schemas (`catalog` and `schema`) in metastore.yaml: what it holds, so agents pick the right place.                                                                                                                                                                                                                                                                          | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| [`define_base`](https://datanotes.dev/reference/operations/schema/#define_base)         | Create or replace a base: a named set of columns (same spec as `create_table`) that tables inherit, like a parent class (`bases` in `metastore.yaml`).                                                                                                                                                                                                                                                                                                                         | [Bases](https://datanotes.dev/guides/database-objects/bases/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| [`set_table_bases`](https://datanotes.dev/reference/operations/schema/#set_table_bases) | Set the bases a table inherits from (`bases`, in order; `[]` removes them).                                                                                                                                                                                                                                                                                                                                                                                                    | [Bases](https://datanotes.dev/guides/database-objects/bases/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| [`add_constraint`](https://datanotes.dev/reference/operations/schema/#add_constraint)   | ALTER TABLE ADD CONSTRAINT `name` CHECK: `check` is a where filter every row must match, e.g.                                                                                                                                                                                                                                                                                                                                                                                  | [CHECK constraints](https://datanotes.dev/guides/data-quality/check-constraints/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| [`drop_constraint`](https://datanotes.dev/reference/operations/schema/#drop_constraint) | Remove the CHECK constraint `name` from `table`.                                                                                                                                                                                                                                                                                                                                                                                                                               | [CHECK constraints](https://datanotes.dev/guides/data-quality/check-constraints/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| [`create_view`](https://datanotes.dev/reference/operations/schema/#create_view)         | Create (or `replace`) a view: a named select stored in metastore.yaml.                                                                                                                                                                                                                                                                                                                                                                                                         | [Views](https://datanotes.dev/guides/database-objects/views/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| [`drop_view`](https://datanotes.dev/reference/operations/schema/#drop_view)             | Remove a view from `metastore.yaml` (undo with `undo_migration`).                                                                                                                                                                                                                                                                                                                                                                                                              | [Views](https://datanotes.dev/guides/database-objects/views/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| Operation                                                          | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Examples                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`create_table`](https://datanotes.dev/reference/operations/schema/#create_table)       | Create a table: `name`, in `catalog` and `schema` (default: the database’s defaults); the definition goes in metastore.yaml, the rows in `<root>/<catalog>/<schema>/<name>/`.                                                                                                                                                                                                                                                                                                                                                                   | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Tables](https://datanotes.dev/guides/database-objects/tables/), [Columns and types](https://datanotes.dev/guides/database-objects/columns/), [Bases](https://datanotes.dev/guides/database-objects/bases/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [Write and move rows](https://datanotes.dev/guides/read-and-write/write-rows/), [Automatic links](https://datanotes.dev/guides/read-and-write/automatic-links/), [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/) |
+| [`drop_table`](https://datanotes.dev/reference/operations/schema/#drop_table)           | Drop a table.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | [Tables](https://datanotes.dev/guides/database-objects/tables/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| [`alter_table`](https://datanotes.dev/reference/operations/schema/#alter_table)         | Alter a table: move it (`catalog`, `schema`), rename it (`name`), change `partition` / `filename` patterns, `description` (changes, never goes: “” is refused), `aliases`, `exclude` folders, `row_template` (“” removes it), `instructions` (how to fill a row, for agents; “” removes them), `history` (true \| false \| “default”), `autolink_target` (true \| false \| “default”: may automatic links link its rows? default: yes, unless its rows are named by a date or a time) or `tags` (key/value labels merged into the table’s, e.g. | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Tables](https://datanotes.dev/guides/database-objects/tables/), [Automatic links](https://datanotes.dev/guides/read-and-write/automatic-links/), [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/)                                                                                                                                                                                                                                |
+| [`clone_table`](https://datanotes.dev/reference/operations/schema/#clone_table)         | CREATE TABLE `target` CLONE `source`: same definition plus independent copies of its rows (deep clone), optionally as of a `version` / `timestamp`.                                                                                                                                                                                                                                                                                                                                                                                             | [Tables](https://datanotes.dev/guides/database-objects/tables/), [Bases](https://datanotes.dev/guides/database-objects/bases/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/)                                                                                                                                                                                                                                                                                                                                                                                                       |
+| [`add_column`](https://datanotes.dev/reference/operations/schema/#add_column)           | Add a typed column.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | [Columns and types](https://datanotes.dev/guides/database-objects/columns/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/)                                                                                                                                                                                                                                                                                                                                                                     |
+| [`rename_column`](https://datanotes.dev/reference/operations/schema/#rename_column)     | Rename a column in metastore.yaml and on every row.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | [Columns and types](https://datanotes.dev/guides/database-objects/columns/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| [`drop_column`](https://datanotes.dev/reference/operations/schema/#drop_column)         | Remove a column from the schema and every row.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | [Columns and types](https://datanotes.dev/guides/database-objects/columns/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| [`alter_column`](https://datanotes.dev/reference/operations/schema/#alter_column)       | Change a column’s attributes (type, min/max/step, values, required, default, label, aliases, description, note, `ref_where`, `ref_by` (see list_link_targets), `acyclic` (refused while the rows already form a cycle: they are listed); `null` removes an attribute, except `description`, which changes but never goes (null or “” is refused); `dense` true/false).                                                                                                                                                                          | [Tables](https://datanotes.dev/guides/database-objects/tables/), [Columns and types](https://datanotes.dev/guides/database-objects/columns/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/)                                                                                                                                                                                                                                                                                                                                                                                        |
+| [`rename_value`](https://datanotes.dev/reference/operations/schema/#rename_value)       | Rename one value of an enum column (e.g.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | [Columns and types](https://datanotes.dev/guides/database-objects/columns/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| [`comment_on`](https://datanotes.dev/reference/operations/schema/#comment_on)           | COMMENT ON CATALOG / SCHEMA: set the `description` of a catalog (`catalog` alone) or of one of its schemas (`catalog` and `schema`) in metastore.yaml: what it holds, so agents pick the right place.                                                                                                                                                                                                                                                                                                                                           | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| [`define_base`](https://datanotes.dev/reference/operations/schema/#define_base)         | Create or replace a base: a named set of columns (same spec as `create_table`) that tables inherit, like a parent class (`bases` in `metastore.yaml`).                                                                                                                                                                                                                                                                                                                                                                                          | [Bases](https://datanotes.dev/guides/database-objects/bases/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| [`set_table_bases`](https://datanotes.dev/reference/operations/schema/#set_table_bases) | Set the bases a table inherits from (`bases`, in order; `[]` removes them).                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | [Bases](https://datanotes.dev/guides/database-objects/bases/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| [`add_constraint`](https://datanotes.dev/reference/operations/schema/#add_constraint)   | ALTER TABLE ADD CONSTRAINT `name` CHECK: `check` is a where filter every row must match, e.g.                                                                                                                                                                                                                                                                                                                                                                                                                                                   | [CHECK constraints](https://datanotes.dev/guides/data-quality/check-constraints/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| [`drop_constraint`](https://datanotes.dev/reference/operations/schema/#drop_constraint) | Remove the CHECK constraint `name` from `table`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | [CHECK constraints](https://datanotes.dev/guides/data-quality/check-constraints/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| [`create_view`](https://datanotes.dev/reference/operations/schema/#create_view)         | Create (or `replace`) a view: a named select stored in metastore.yaml.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | [Views](https://datanotes.dev/guides/database-objects/views/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| [`drop_view`](https://datanotes.dev/reference/operations/schema/#drop_view)             | Remove a view from `metastore.yaml` (undo with `undo_migration`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | [Views](https://datanotes.dev/guides/database-objects/views/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 
 ## Rows (DML)
 
@@ -84,13 +84,13 @@ Operations on the journal, a table’s versions, the change feed and webhooks: u
 
 Operations that describe and check the database, configure it and maintain its indexes. [Auxiliary operations](https://datanotes.dev/reference/operations/auxiliary/) lists their parameters.
 
-| Operation                                                                             | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Examples                                                                                                                                                                                                                                                      |
-| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`list_tables`](https://datanotes.dev/reference/operations/auxiliary/#list_tables)                         | List every table: `name`, `catalog`, `schema`, `qualified` (`personal.metrics.mood` — use it wherever a table is expected; `metrics.mood` or `mood` also work when unambiguous), `path` and, when declared, `description`, `aliases` (other words for what it records) and `tags`.                                                                                                                                                                                                                                                                                                                                                                        | [Tables](https://datanotes.dev/guides/database-objects/tables/), [Views](https://datanotes.dev/guides/database-objects/views/)                                                                                                                                                                          |
-| [`describe_table`](https://datanotes.dev/reference/operations/auxiliary/#describe_table)                   | Describe a table (`catalog.schema.table` or a shorter unambiguous name): `qualified`, `name`, `catalog`, `schema`, `description`, `aliases`, `layout` (`folder`, `row_folder`: the folder pattern of new rows, `archive`), `options` (`partition`, `filename`, `archive`, `exclude`), typed `columns` with label/aliases/description and the dense flag, `untyped_fields`, `row_count`, and when set: `tags`, `bases` (the bases it inherits from, in order), `constraints` (its CHECKs, name → where), `row_template`, `history`, `autolink_target`, `fields` (their values).                                                                            | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Tables](https://datanotes.dev/guides/database-objects/tables/), [Bases](https://datanotes.dev/guides/database-objects/bases/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/)                  |
-| [`describe_database`](https://datanotes.dev/reference/operations/auxiliary/#describe_database)             | Describe the database: its folder (`root`), `metastore` (`metastore.yaml`: read it freely, but it is read-only for agents and changes only through the schema operations), configuration (default catalog and schema, row partition and file-name formats, archive folder, time zone, history, automatic links), journal folder, `bases` (shared column sets and the tables using them), `catalogs` → `schemas` → `tables` (with `row_count`, `tags`, and `unreadable_count` when some rows’ front matter cannot be read) and `views`; catalogs and schemas show their `comment` (set with `comment_on`).                                                 | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Hand edits](https://datanotes.dev/guides/data-quality/hand-edits/)                                                                                                                          |
-| [`configure_database`](https://datanotes.dev/reference/operations/auxiliary/#configure_database)           | Configure the database (persisted in metastore.yaml `config:`): `root` (rename the database folder; links follow; revert by renaming back), `default_catalog`, `default_schema`, `default_partition` (“” = flat) and `default_filename` (date formats for new time-based tables), `archive_folder`, `timezone` (IANA; completes date-times written without offset), `history` (transaction log for every table: true in a database the engine creates, false when `config` lacks it, as in a metastore from before 3.0.0; change it only on the user’s request), `autolink` (the text a write puts in a body links the notes it mentions; on by default). | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Tables](https://datanotes.dev/guides/database-objects/tables/), [Automatic links](https://datanotes.dev/guides/read-and-write/automatic-links/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/) |
-| [`check_table`](https://datanotes.dev/reference/operations/auxiliary/#check_table)                         | Validate every row against the table (required, types, ranges, enums, links, unknown columns, CHECK constraints, those that follow links included, filtered link targets (ref_where / ref_by), stale generated/identity values, missing inverse links, front matter that cannot be read: code `unreadable`, with no column, for a note whose `table` line names the table but whose YAML is broken, which every other read leaves out).                                                                                                                                                                                                                   | [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [Hand edits](https://datanotes.dev/guides/data-quality/hand-edits/), [Find rows that break the schema](https://datanotes.dev/guides/data-quality/check-table/)                                                                        |
-| [`infer_table`](https://datanotes.dev/reference/operations/auxiliary/#infer_table)                         | Read-only schema inference from notes’ front matter.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [Hand edits](https://datanotes.dev/guides/data-quality/hand-edits/), [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/)                                                                                                                                                 |
-| [`describe_semantic_index`](https://datanotes.dev/reference/operations/auxiliary/#describe_semantic_index) | The semantic search index: `enabled`, `provider`, `model`, `files`, `passages`, `pending`, `running`, `last_sync`, `last_error`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | [Find notes by meaning](https://datanotes.dev/guides/search/semantic/)                                                                                                                                                                                                             |
-| [`sync_semantic_index`](https://datanotes.dev/reference/operations/auxiliary/#sync_semantic_index)         | Bring the semantic search index up to date: embed the notes changed since the last run (the engine also does it on its own about ten seconds after edits).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | [Find notes by meaning](https://datanotes.dev/guides/search/semantic/)                                                                                                                                                                                                             |
+| Operation                                                                             | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Examples                                                                                                                                                                                                                                                      |
+| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`list_tables`](https://datanotes.dev/reference/operations/auxiliary/#list_tables)                         | List every table: `name`, `catalog`, `schema`, `qualified` (`personal.metrics.mood` — use it wherever a table is expected; `metrics.mood` or `mood` also work when unambiguous), `path` and, when declared, `description`, `aliases` (other words for what it records) and `tags`.                                                                                                                                                                                                                                                                                                                                                                                                                      | [Tables](https://datanotes.dev/guides/database-objects/tables/), [Views](https://datanotes.dev/guides/database-objects/views/)                                                                                                                                                                          |
+| [`describe_table`](https://datanotes.dev/reference/operations/auxiliary/#describe_table)                   | Describe a table (`catalog.schema.table` or a shorter unambiguous name): `qualified`, `name`, `catalog`, `schema`, `description`, `aliases`, `layout` (`folder`, `row_folder`: the folder pattern of new rows, `archive`), `options` (`partition`, `filename`, `archive`, `exclude`), typed `columns` with label/aliases/description and the dense flag, `untyped_fields`, `row_count`, and when set: `tags`, `bases` (the bases it inherits from, in order), `constraints` (its CHECKs, name → where), `constraint_hints` (their own hints, name → hint), `instructions` (how to fill a row: follow them before you write one), `row_template`, `history`, `autolink_target`, `fields` (their values). | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Tables](https://datanotes.dev/guides/database-objects/tables/), [Bases](https://datanotes.dev/guides/database-objects/bases/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/)                  |
+| [`describe_database`](https://datanotes.dev/reference/operations/auxiliary/#describe_database)             | Describe the database: its folder (`root`), `metastore` (`metastore.yaml`: read it freely, but it is read-only for agents and changes only through the schema operations), configuration (default catalog and schema, row partition and file-name formats, archive folder, time zone, history, automatic links), journal folder, `bases` (shared column sets and the tables using them), `catalogs` → `schemas` → `tables` (with `row_count`, `tags`, and `unreadable_count` when some rows’ front matter cannot be read) and `views`; catalogs and schemas show their `comment` (set with `comment_on`).                                                                                               | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Hand edits](https://datanotes.dev/guides/data-quality/hand-edits/)                                                                                                                          |
+| [`configure_database`](https://datanotes.dev/reference/operations/auxiliary/#configure_database)           | Configure the database (persisted in metastore.yaml `config:`): `root` (rename the database folder; links follow; revert by renaming back), `default_catalog`, `default_schema`, `default_partition` (“” = flat) and `default_filename` (date formats for new time-based tables), `archive_folder`, `timezone` (IANA; completes date-times written without offset), `history` (transaction log for every table: true in a database the engine creates, false when `config` lacks it, as in a metastore from before 3.0.0; change it only on the user’s request), `autolink` (the text a write puts in a body links the notes it mentions; on by default).                                               | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Tables](https://datanotes.dev/guides/database-objects/tables/), [Automatic links](https://datanotes.dev/guides/read-and-write/automatic-links/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/) |
+| [`check_table`](https://datanotes.dev/reference/operations/auxiliary/#check_table)                         | Validate every row against the table (required, types, ranges, enums, links, unknown columns, CHECK constraints, those that follow links included, filtered link targets (ref_where / ref_by), stale generated/identity values, missing inverse links, 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).                                                                                                                                                                                                                        | [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [Hand edits](https://datanotes.dev/guides/data-quality/hand-edits/), [Find rows that break the schema](https://datanotes.dev/guides/data-quality/check-table/)                                                                        |
+| [`infer_table`](https://datanotes.dev/reference/operations/auxiliary/#infer_table)                         | Read-only schema inference from notes’ front matter.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | [Hand edits](https://datanotes.dev/guides/data-quality/hand-edits/), [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/)                                                                                                                                                 |
+| [`describe_semantic_index`](https://datanotes.dev/reference/operations/auxiliary/#describe_semantic_index) | The semantic search index: `enabled`, `provider`, `model`, `files`, `passages`, `pending`, `running`, `last_sync`, `last_error`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | [Find notes by meaning](https://datanotes.dev/guides/search/semantic/)                                                                                                                                                                                                             |
+| [`sync_semantic_index`](https://datanotes.dev/reference/operations/auxiliary/#sync_semantic_index)         | Bring the semantic search index up to date: embed the notes changed since the last run (the engine also does it on its own about ten seconds after edits).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | [Find notes by meaning](https://datanotes.dev/guides/search/semantic/)                                                                                                                                                                                                             |

package/dist/docs/release-notes.md

@@ -4,6 +4,30 @@
 
 This page lists each version of Datanotes, newest first. Datanotes follows [semantic versioning](https://semver.org): a major version can break what you rely on, and its notes list those changes first. The package is on [npm](https://www.npmjs.com/package/datanotes), and each version has a [GitHub release](https://github.com/davidefornelli/datanotes/releases).
 
+## 3.2.0
+
+Datanotes 3.2.0 keeps the links between rows of one table free of cycles. It also lets a table tell agents how to fill its rows. It only adds to 3.1: no operation, argument or setting goes away.
+
+### Links without cycles
+
+A link column, or a list of links, to its own table takes `acyclic: true`. The engine then refuses a write that makes a row depend on itself through that column. An example is a task blocked by a task it blocks. [Keep dependencies free of cycles with `acyclic`](https://datanotes.dev/guides/database-objects/relations/#keep-dependencies-free-of-cycles-with-acyclic) shows it.
+
+* **Both sides**: with `inverse`, a write to either column is checked. The links the engine adds on the other side count too.
+* **Existing rows**: `add_column` and `alter_column` refuse `acyclic: true` while rows already form a cycle, and list them.
+* **Hand edits**: `check_table` and the change feed report a cycle made outside the engine.
+* **The refusal**: it shows the cycle, such as `would close a cycle in "blocked_by" (A → B → A)`. It has its own hint and docs.
+* **`system.information_schema.columns`**: a new column, `is_acyclic`.
+
+### Tell agents how to fill a table
+
+* **`instructions`**: `create_table` and `alter_table` take Markdown text that says how to fill a row. It can list which columns come first and what to ask the user. `describe_table` returns it, and `instructions: ""` removes it. [Tell agents how to fill a row with `instructions`](https://datanotes.dev/guides/database-objects/tables/#tell-agents-how-to-fill-a-row-with-instructions) shows it.
+* **A hint for each CHECK**: `add_constraint` takes `hint`, what to do when a row breaks the rule. A refused write puts it first in its `hint`, and each violation of that CHECK carries it as `hint`. `describe_table` lists the hints in `constraint_hints`, next to `constraints`.
+* **`system.information_schema`**: `tables` has a new column, `instructions`, and `check_constraints` a new column, `hint`.
+
+### Fixes
+
+* `alter_column` with `ref: "self"` no longer refuses the links a column already holds.
+
 ## 3.1.0
 
 Datanotes 3.1.0 makes the engine fast at scale and adds OpenTelemetry traces. It only adds to 3.0: no operation, argument or setting goes away. One default changes: the transaction log now writes segments. Read [Before you downgrade to 3.0](#before-you-downgrade-to-30) if you may go back.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "datanotes",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "mcpName": "io.github.davidefornelli/datanotes",
   "description": "The engine of your second brain: Markdown notes as database tables, for you and your agents.",
   "keywords": [