datanotes 2.0.0 → 3.0.0

package/dist/docs/guides/read-and-write/automatic-links.md

@@ -0,0 +1,768 @@
+# Automatic links
+
+> The text you write links the notes it mentions by name. See what the engine links, how it asks about a doubtful name, and how to turn it off.
+
+When you or an agent write a note’s text, the engine links the notes it mentions by name. A review that says Cary Grant links the note `Cary Grant`, even when the agent wrote plain text.
+
+The engine links what it’s sure of and asks about the rest. The write’s answer lists the links in `links_added`. It lists the doubtful mentions in `ambiguous_mentions`, each with the notes it may name.
+
+## What the engine links
+
+The engine knows every note by its file name and its `aliases` property, rows and plain notes alike. It looks for these names in the text you write:
+
+* **`insert_row`**: `body`
+* **`update_row`**: `body`, `body_sections`, `body_prepend` and `body_append`, and only the text you pass
+* **`update_rows`**: `body`
+* **`batch`**: the same operations inside it
+
+A mention becomes a link when all of these hold:
+
+* **Whole words on one line**: case doesn’t matter for a name of two words or more, and the link keeps your spelling, as in `[[Cary Grant|cary grant]]`.
+* **A capital for one word**: a one-word name links only when you write it with a capital, such as `House` for the note `House` or `house`.
+* **Inside a sentence**: a one-word name at the start of a sentence, a line, a list item or a label isn’t linked. There every word has a capital, so the capital says nothing.
+* **Standing alone**: a name glued to a path, a domain, an address or a snake_case word is part of it, as in `Documents/House/bill.pdf`, `greenmart.com` or `House_new`.
+* **The first mention**: the note gets one link per body, and none when the body links it already.
+* **Another note**: the engine never links the note you write.
+* **A link target**: a row in a table’s archive folder is never one. Neither is a row of a table that isn’t a target, as the next section explains.
+* **The longest name**: `Nora Wells` links the note `Nora Wells`, not the note `Nora`.
+
+The engine leaves these parts of the text alone:
+
+* **The front matter**, code blocks and inline code
+* **Links**, web addresses, email addresses, tags, HyperText Markup Language (HTML), comments and math
+* **Headings**: a heading’s text is the anchor that `body_sections` and `[[note#heading]]` links look for
+* **Dataview inline fields**: a `key:: value` line, `[key:: value]` and `(key:: value)`
+* **Templater blocks**: `<% ... %>`
+
+It also skips names that would link ordinary words:
+
+* **Short names**: fewer than three characters, such as `Al`
+* **Numbers, dates and ids**: names without a letter, or named after a date, such as `2026-09-27`
+* **Common words**: names such as `The`, `Index` or `Welcome`
+* **Lowercase words**: a one-word mention in lowercase, such as `will` for the note `Will`
+
+In a Markdown table, a link with an alias escapes its bar, as in `[[Cary Grant\|cary grant]]`. The engine treats a line as a table row when it has a bar outside links and code.
+
+Each link has the form new links take in your vault, as seen from where the note ends up. A write that renames the note links from its new path. `links_added` lists each link. The links are part of the write. `dry_run` shows them before you write, and `undo_migration` takes them back.
+
+## Which notes a link may point to
+
+Plain notes are always link targets. A table decides for its rows with the option `autolink_target`:
+
+* **Absent**: the rows are targets, unless the table names them by a date or a time. A table created with `time_column` names its rows that way, as do tables of meals, readings or events.
+* **`true`**: the rows are targets, whatever their file names.
+* **`false`**: the rows are never targets. Set it on a table of tasks, so an old task `Call Oscar` never takes the words `call Oscar` from the person `Oscar`.
+
+Pass it to `create_table` or `alter_table`. `alter_table` with `"default"` goes back to the default.
+
+## Writes from sync programs
+
+A sync program writes text it copied from elsewhere, such as tasks, calendar events or receipts. That text should stay as it came. Give the program’s token `"autolink": false`, and its writes link nothing unless a write asks with `autolink: true`. [Tokens and permissions](https://datanotes.dev/guides/security/tokens/#turn-automatic-links-off-for-a-sync-program) shows how.
+
+## When the engine asks
+
+The engine never guesses. It leaves a mention as text and lists it in `ambiguous_mentions` for one of these reasons:
+
+* **`same_name`**: several notes have the name.
+* **`adjacent`**: names of two notes stand side by side and may form one name. With the notes `Nora` and `Wells`, the text `Nora Wells` may name neither of them.
+* **`overlap`**: names of two notes overlap, such as `New York` and `York City` in `New York City`.
+* **`part_of_name`**: a capitalized word next to the name suggests a longer name, such as `Philadelphia` in `The Philadelphia Story`.
+* **`sentence_start`**: a one-word name starts a sentence, a line, a list item or a label, such as `House` in `House: clean the bathroom`.
+
+Each entry gives the mention as `text` and the notes it may name as `candidates`. It adds the line around it as `context`, and a `hint`. The other mentions of that name in the same text stay as text too. A `sentence_start` mention is the exception: a later mention of the name inside a sentence is linked. To resolve one:
+
+1. Read the candidates with `read_note`.
+2. Decide from the text which note the mention names, if any.
+3. Write the link with `update_row` and `autolink: false`, or leave the text as it is.
+
+## Link the notes a text mentions
+
+Write a note’s text as plain prose. The engine links each note the text mentions by name, at its first mention. `links_added` lists the links. This review of Charade names two actors, each a row, and the director, a plain note.
+
+**`insert_row`**
+
+```json
+{
+  "table": "film",
+  "values": { "title": "Charade", "year": 1963 },
+  "body": "Cary Grant and Audrey Hepburn in Paris, directed by Stanley Donen.\n\nCary Grant has never been more charming.\n"
+}
+```
+
+Answer:
+
+```json
+{
+  "ok": true,
+  "op": "insert_row",
+  "files_created": 1,
+  "planned_creates": ["datanotes/main/public/film/Charade.md"],
+  "commits": [{ "table": "main.public.film", "version": 2, "operation": "WRITE" }],
+  "migration_id": "20261012T071956-insert_row-insert-into-film-2",
+  "links_added": [
+    {
+      "path": "datanotes/main/public/film/Charade.md",
+      "text": "Cary Grant",
+      "target": "datanotes/main/public/actor/Cary Grant.md",
+      "link": "[[Cary Grant]]"
+    },
+    {
+      "path": "datanotes/main/public/film/Charade.md",
+      "text": "Audrey Hepburn",
+      "target": "datanotes/main/public/actor/Audrey Hepburn.md",
+      "link": "[[Audrey Hepburn]]"
+    },
+    {
+      "path": "datanotes/main/public/film/Charade.md",
+      "text": "Stanley Donen",
+      "target": "People/Stanley Donen.md",
+      "link": "[[Stanley Donen]]"
+    }
+  ]
+}
+```
+
+`datanotes/main/public/film/Charade.md` now reads:
+
+```markdown
+---
+table: main.public.film
+id: 01a12efb-7eff-795a-b759-91ed39941b17
+title: Charade
+year: 1963
+---
+[[Cary Grant]] and [[Audrey Hepburn]] in Paris, directed by [[Stanley Donen]].
+
+
+Cary Grant has never been more charming.
+```
+
+The second mention of Cary Grant stays as text: one link per note is enough. Paris has no note, so it stays as text too.
+
+## Link only the text you add
+
+`update_row` links the text it writes, and leaves the rest of the note alone. A note the body links already doesn’t get a second link.
+
+**`update_row`**
+
+```json
+{
+  "table": "film",
+  "path": "datanotes/main/public/film/Charade.md",
+  "body_append": "Audrey Hepburn wears Givenchy. Watch it with Notorious, the other Cary Grant thriller.\n"
+}
+```
+
+Answer:
+
+```json
+{
+  "ok": true,
+  "op": "update_row",
+  "notes_changed": 1,
+  "planned_edits": [
+    {
+      "path": "datanotes/main/public/film/Charade.md",
+      "set": {},
+      "remove": [],
+      "body": true
+    }
+  ],
+  "commits": [{ "table": "main.public.film", "version": 3, "operation": "UPDATE" }],
+  "migration_id": "20261012T071956-update_row-update-film",
+  "links_added": [
+    {
+      "path": "datanotes/main/public/film/Charade.md",
+      "text": "Notorious",
+      "target": "datanotes/main/public/film/Notorious.md",
+      "link": "[[Notorious]]"
+    }
+  ]
+}
+```
+
+`datanotes/main/public/film/Charade.md` now reads:
+
+```markdown
+---
+table: main.public.film
+id: 01a12efb-7eff-795a-b759-91ed39941b17
+title: Charade
+year: 1963
+---
+[[Cary Grant]] and [[Audrey Hepburn]] in Paris, directed by [[Stanley Donen]].
+
+
+Cary Grant has never been more charming.
+
+
+Audrey Hepburn wears Givenchy. Watch it with [[Notorious]], the other Cary Grant thriller.
+```
+
+## Resolve a doubtful mention
+
+When the engine can’t tell which note a name means, it leaves the text alone and asks. This review of Notorious names Ingrid Bergman. The vault has your friend `Ingrid` and the director `Bergman`, but no note for the actress. The engine links neither.
+
+**`update_row`**
+
+```json
+{
+  "table": "film",
+  "path": "datanotes/main/public/film/Notorious.md",
+  "body": "Ingrid Bergman and Cary Grant, directed by Alfred Hitchcock.\n"
+}
+```
+
+Answer:
+
+```json
+{
+  "ok": true,
+  "op": "update_row",
+  "notes_changed": 1,
+  "planned_edits": [
+    {
+      "path": "datanotes/main/public/film/Notorious.md",
+      "set": {},
+      "remove": [],
+      "body": true
+    }
+  ],
+  "commits": [{ "table": "main.public.film", "version": 4, "operation": "UPDATE" }],
+  "migration_id": "20261012T071956-update_row-update-film-2",
+  "links_added": [
+    {
+      "path": "datanotes/main/public/film/Notorious.md",
+      "text": "Cary Grant",
+      "target": "datanotes/main/public/actor/Cary Grant.md",
+      "link": "[[Cary Grant]]"
+    }
+  ],
+  "ambiguous_mentions": [
+    {
+      "path": "datanotes/main/public/film/Notorious.md",
+      "text": "Ingrid Bergman",
+      "reason": "adjacent",
+      "candidates": ["Directors/Bergman.md", "Friends/Ingrid.md"],
+      "context": "Ingrid Bergman and Cary Grant, directed by Alfred Hitchcock.",
+      "hint": "\"Ingrid Bergman\" may name one thing, and each note names a part of it: read the notes and the text around it, then write the link with update_row and autolink: false, or leave the text as it is."
+    }
+  ]
+}
+```
+
+The agent reads both candidates and the line around the mention. Neither note is the actress, so it adds her as an actor:
+
+**`insert_row`**
+
+```json
+{ "table": "actor", "values": { "name": "Ingrid Bergman" } }
+```
+
+Now the longest name wins. The same text links the actress, and nobody is asked:
+
+**`update_row`**
+
+```json
+{
+  "table": "film",
+  "path": "datanotes/main/public/film/Notorious.md",
+  "body": "Ingrid Bergman and Cary Grant, directed by Alfred Hitchcock.\n"
+}
+```
+
+Answer:
+
+```json
+{
+  "ok": true,
+  "op": "update_row",
+  "notes_changed": 1,
+  "planned_edits": [
+    {
+      "path": "datanotes/main/public/film/Notorious.md",
+      "set": {},
+      "remove": [],
+      "body": true
+    }
+  ],
+  "commits": [{ "table": "main.public.film", "version": 5, "operation": "UPDATE" }],
+  "migration_id": "20261012T071956-update_row-update-film-3",
+  "links_added": [
+    {
+      "path": "datanotes/main/public/film/Notorious.md",
+      "text": "Ingrid Bergman",
+      "target": "datanotes/main/public/actor/Ingrid Bergman.md",
+      "link": "[[Ingrid Bergman]]"
+    },
+    {
+      "path": "datanotes/main/public/film/Notorious.md",
+      "text": "Cary Grant",
+      "target": "datanotes/main/public/actor/Cary Grant.md",
+      "link": "[[Cary Grant]]"
+    }
+  ]
+}
+```
+
+`datanotes/main/public/film/Notorious.md` now reads:
+
+```markdown
+---
+table: main.public.film
+id: 01a12efb-7ef7-77d9-9050-281d995d2d49
+title: Notorious
+year: 1946
+---
+[[Ingrid Bergman]] and [[Cary Grant]], directed by Alfred Hitchcock.
+```
+
+To link a candidate yourself, write the link in the text and pass `autolink: false`. The engine then writes the text as you give it. If no candidate fits and the name deserves no note, leave the text as it is.
+
+## Choose the tables a link may point to
+
+A table’s rows are link targets by default. A table whose rows are named by a date or a time is the exception, such as a table of meals or screenings. The table option `autolink_target` decides for one table. These tasks say no, so the task `Call Ingrid` never takes a mention of Ingrid:
+
+**`create_table`**
+
+```json
+{
+  "name": "task",
+  "columns": [
+    {
+      "name": "title",
+      "type": "string",
+      "required": true,
+      "description": "What to do, in a few words"
+    }
+  ],
+  "filename": "{title}",
+  "description": "Things I have to do",
+  "autolink_target": false
+}
+```
+
+Answer:
+
+```json
+{ "ok": true }
+```
+
+**`insert_row`**
+
+```json
+{ "table": "task", "values": { "title": "Call Ingrid" } }
+```
+
+**`insert_row`**
+
+```json
+{
+  "table": "film",
+  "values": { "title": "Persona", "year": 1966 },
+  "body": "After the film, call Ingrid to talk about it.\n"
+}
+```
+
+Answer:
+
+```json
+{
+  "ok": true,
+  "op": "insert_row",
+  "files_created": 1,
+  "planned_creates": ["datanotes/main/public/film/Persona.md"],
+  "commits": [{ "table": "main.public.film", "version": 6, "operation": "WRITE" }],
+  "migration_id": "20261012T071956-insert_row-insert-into-film-3",
+  "links_added": [
+    {
+      "path": "datanotes/main/public/film/Persona.md",
+      "text": "Ingrid",
+      "target": "Friends/Ingrid.md",
+      "link": "[[Ingrid]]"
+    }
+  ]
+}
+```
+
+`datanotes/main/public/film/Persona.md` now reads:
+
+```markdown
+---
+table: main.public.film
+id: 01a12efb-7f3f-7575-a9da-6beb5ecbe530
+title: Persona
+year: 1966
+---
+After the film, call [[Ingrid]] to talk about it.
+```
+
+Screenings are named by the time they start, so they are no targets. This one has an alias you mention in your notes:
+
+**`create_table`**
+
+```json
+{
+  "name": "screening",
+  "time_column": "starts_at",
+  "columns": [
+    {
+      "name": "starts_at",
+      "type": "datetime",
+      "required": true,
+      "description": "When the screening starts"
+    },
+    {
+      "name": "aliases",
+      "type": "list",
+      "items": "string",
+      "description": "Other names of the screening"
+    }
+  ],
+  "description": "Film club screenings"
+}
+```
+
+**`insert_row`**
+
+```json
+{
+  "table": "screening",
+  "values": { "starts_at": "2026-10-09T21:00", "aliases": ["Swedish night"] }
+}
+```
+
+`autolink_target: true` makes the screenings link targets:
+
+**`alter_table`**
+
+```json
+{ "table": "screening", "autolink_target": true }
+```
+
+Answer:
+
+```json
+{ "ok": true }
+```
+
+**`update_row`**
+
+```json
+{
+  "table": "film",
+  "path": "datanotes/main/public/film/Persona.md",
+  "body_append": "We watched it at Swedish night.\n"
+}
+```
+
+Answer:
+
+```json
+{
+  "ok": true,
+  "op": "update_row",
+  "notes_changed": 1,
+  "planned_edits": [
+    {
+      "path": "datanotes/main/public/film/Persona.md",
+      "set": {},
+      "remove": [],
+      "body": true
+    }
+  ],
+  "commits": [{ "table": "main.public.film", "version": 7, "operation": "UPDATE" }],
+  "migration_id": "20261012T071956-update_row-update-film-4",
+  "links_added": [
+    {
+      "path": "datanotes/main/public/film/Persona.md",
+      "text": "Swedish night",
+      "target": "datanotes/main/public/screening/2026-10-09T2100.md",
+      "link": "[[2026-10-09T2100|Swedish night]]"
+    }
+  ]
+}
+```
+
+`datanotes/main/public/film/Persona.md` now reads:
+
+```markdown
+---
+table: main.public.film
+id: 01a12efb-7f3f-7575-a9da-6beb5ecbe530
+title: Persona
+year: 1966
+---
+After the film, call [[Ingrid]] to talk about it.
+
+
+We watched it at [[2026-10-09T2100|Swedish night]].
+```
+
+`metastore.yaml` keeps the option in the table’s `options`:
+
+`datanotes/metastore.yaml` now reads:
+
+```yaml
+# Metastore (Datanotes): catalogs, schemas, tables, columns, views.
+id: 01a12efb-7ed1-752d-9a1f-21e06985a6cb
+config:
+  history: true
+
+
+catalogs:
+  main:
+    schemas:
+      public:
+        tables:
+          actor:
+            description: Actors of the classic films I watch
+            options:
+              filename: "{name}"
+              archive: _archive
+            columns:
+              - name: id
+                type: string
+                required: true
+                description: "Unique id of the row (UUIDv7): set when the row is created, never changes"
+                unique: true
+                identity: uuid
+                dense: true
+              - name: name
+                type: string
+                required: true
+                description: The actor's name, as in the credits
+          film:
+            description: Classic films I watched, with my reviews
+            options:
+              filename: "{title}"
+              archive: _archive
+            columns:
+              - name: id
+                type: string
+                required: true
+                description: "Unique id of the row (UUIDv7): set when the row is created, never changes"
+                unique: true
+                identity: uuid
+                dense: true
+              - name: title
+                type: string
+                required: true
+                description: The film's title, as on its poster
+              - name: year
+                type: integer
+                description: Year the film first came out
+          task:
+            description: Things I have to do
+            options:
+              filename: "{title}"
+              archive: _archive
+              autolink_target: false
+            columns:
+              - name: id
+                type: string
+                required: true
+                description: "Unique id of the row (UUIDv7): set when the row is created, never changes"
+                unique: true
+                identity: uuid
+                dense: true
+              - name: title
+                type: string
+                required: true
+                description: What to do, in a few words
+          screening:
+            description: Film club screenings
+            options:
+              filename: "{starts_at:YYYY-MM-DD[T]HHmm}"
+              archive: _archive
+              autolink_target: true
+            columns:
+              - name: id
+                type: string
+                unique: true
+                identity: uuid
+                required: true
+                dense: true
+                description: "Unique id of the row (UUIDv7): set when the row is created, never changes"
+              - name: starts_at
+                type: datetime
+                required: true
+                description: When the screening starts
+              - name: aliases
+                type: list
+                items: string
+                description: Other names of the screening
+```
+
+Pass `autolink_target: "default"` to `alter_table` to follow the default again. Archived rows are never link targets, whatever the option says.
+
+## Turn automatic links off
+
+`autolink: false` writes one text as you give it. To turn the links off for every write, call `configure_database` with `autolink: false`. A write can still ask for them with `autolink: true`.
+
+**`insert_row`**
+
+```json
+{
+  "table": "film",
+  "values": { "title": "His Girl Friday", "year": 1940 },
+  "body": "Cary Grant and Rosalind Russell, the fastest talkers in film.\n",
+  "autolink": false
+}
+```
+
+Answer:
+
+```json
+{
+  "ok": true,
+  "op": "insert_row",
+  "files_created": 1,
+  "planned_creates": ["datanotes/main/public/film/His Girl Friday.md"],
+  "commits": [{ "table": "main.public.film", "version": 8, "operation": "WRITE" }],
+  "migration_id": "20261012T071956-insert_row-insert-into-film-4"
+}
+```
+
+`datanotes/main/public/film/His Girl Friday.md` now reads:
+
+```markdown
+---
+table: main.public.film
+id: 01a12efb-7f79-70da-99fb-2387bf605ab3
+title: His Girl Friday
+year: 1940
+---
+Cary Grant and Rosalind Russell, the fastest talkers in film.
+```
+
+**`configure_database`**
+
+```json
+{ "autolink": false }
+```
+
+Answer:
+
+```json
+{
+  "default_catalog": "main",
+  "default_schema": "public",
+  "default_partition": "",
+  "default_filename": "YYYY-MM-DD[T]HHmm",
+  "archive_folder": "_archive",
+  "timezone": "",
+  "history": true,
+  "autolink": false
+}
+```
+
+`metastore.yaml` keeps the setting under `config:`:
+
+`datanotes/metastore.yaml` now reads:
+
+```yaml
+# Metastore (Datanotes): catalogs, schemas, tables, columns, views.
+id: 01a12efb-7ed1-752d-9a1f-21e06985a6cb
+config:
+  history: true
+  autolink: false
+
+
+catalogs:
+  main:
+    schemas:
+      public:
+        tables:
+          actor:
+            description: Actors of the classic films I watch
+            options:
+              filename: "{name}"
+              archive: _archive
+            columns:
+              - name: id
+                type: string
+                required: true
+                description: "Unique id of the row (UUIDv7): set when the row is created, never changes"
+                unique: true
+                identity: uuid
+                dense: true
+              - name: name
+                type: string
+                required: true
+                description: The actor's name, as in the credits
+          film:
+            description: Classic films I watched, with my reviews
+            options:
+              filename: "{title}"
+              archive: _archive
+            columns:
+              - name: id
+                type: string
+                required: true
+                description: "Unique id of the row (UUIDv7): set when the row is created, never changes"
+                unique: true
+                identity: uuid
+                dense: true
+              - name: title
+                type: string
+                required: true
+                description: The film's title, as on its poster
+              - name: year
+                type: integer
+                description: Year the film first came out
+          task:
+            description: Things I have to do
+            options:
+              filename: "{title}"
+              archive: _archive
+              autolink_target: false
+            columns:
+              - name: id
+                type: string
+                required: true
+                description: "Unique id of the row (UUIDv7): set when the row is created, never changes"
+                unique: true
+                identity: uuid
+                dense: true
+              - name: title
+                type: string
+                required: true
+                description: What to do, in a few words
+          screening:
+            description: Film club screenings
+            options:
+              filename: "{starts_at:YYYY-MM-DD[T]HHmm}"
+              archive: _archive
+              autolink_target: true
+            columns:
+              - name: id
+                type: string
+                unique: true
+                identity: uuid
+                required: true
+                dense: true
+                description: "Unique id of the row (UUIDv7): set when the row is created, never changes"
+              - name: starts_at
+                type: datetime
+                required: true
+                description: When the screening starts
+              - name: aliases
+                type: list
+                items: string
+                description: Other names of the screening
+```
+
+This call turns them on again:
+
+**`configure_database`**
+
+```json
+{ "autolink": true }
+```
+
+Answer:
+
+```json
+{ "autolink": true }
+```