datanotes 2.0.0 → 3.0.0

package/dist/docs/guides/agents/how-agents-use-datanotes.md

@@ -0,0 +1,124 @@
+# How agents work with your vault
+
+> What an agent reads first, how it finds tables and views, why the engine validates its writes, and how the journal records and undoes what each agent did.
+
+An agent connected through `datanotes mcp`, the Model Context Protocol (MCP) server of Datanotes, works with your vault the way a careful colleague works with a shared database. It reads the descriptions before it writes, writes only through operations the engine checks, and signs every change with its name in the journal. This page follows that path, from the instructions the agent receives to undoing what it did; the [prompts](https://datanotes.dev/guides/agents/prompts/) show it on concrete requests.
+
+## The agent starts with the server’s instructions
+
+When an MCP client connects, `datanotes mcp` sends instructions with its list of tools. The engine’s part is short:
+
+```text
+Database of Markdown notes: tables defined in metastore.yaml, a row is a note whose front matter key `table` names its table, and each front matter key is a column. Use list_tables / describe_table first, select_rows to read, insert_row / update_row / update_rows / batch to write (validated, journaled, undo with undo_migration). Change the schema only with its operations (create_table, add_column, alter_column, create_view, ...); never edit metastore.yaml. Every table and column needs a `description` of what it holds, or it is refused: descriptions are how agents and people understand the schema. Fill those describe_table lists in `missing_descriptions` with alter_table / alter_column. A body you write links the notes it mentions by name (a one-word name only with a capital, inside a sentence): when a write returns ambiguous_mentions, read the candidate notes and link the right one with update_row and autolink: false, or leave the text. Read the docs of this version with search_docs and read_docs.
+```
+
+The tools are every [operation](https://datanotes.dev/reference/operations/) of the engine, plus three that [read the docs of the installed version](#the-agent-reads-the-docs-of-its-version). To give agents rules and tools of your own, serve [your own MCP server](https://datanotes.dev/develop/build-on-datanotes/#build-your-own-mcp-server) next to it. Each tool’s description says when to call it: `list_tables` asks the agent to call it first, and `add_column` asks the agent to read `describe_table` before it adds a column.
+
+## The agent finds tables by their descriptions
+
+Before it reads or writes, the agent matches your words against what the tables say about themselves:
+
+* **`list_tables`**: every table and view, with its `description`, `aliases` and `tags`, so “my watchlist” leads to `film`, whose aliases include `watchlist`
+* **`describe_table`**: the columns, each with its type, `description`, `aliases`, limits and, for an enum, the meaning of each value, plus the table’s row count
+
+The meanings come from `value_descriptions`, which you give when you create the column. On the film diary, `describe_table` answers this for `status`:
+
+```json
+{
+  "name": "status",
+  "type": "enum",
+  "values": ["to watch", "watched"],
+  "value_descriptions": {
+    "to watch": "on my watchlist, not seen yet",
+    "watched": "I saw it at least once"
+  },
+  "ordered": true,
+  "default": "to watch"
+}
+```
+
+Every table and every column has a description, because the engine refuses one without. Agents and people understand the schema through them, so write each for a reader who never saw your notes. Good aliases help too: the better both are, the less the agent guesses. You set them with `create_table`, `add_column`, `alter_table`, `alter_column` and, for catalogs and schemas, `comment_on`.
+
+A table created before descriptions were required may lack some. `describe_table` lists them in `missing_descriptions`, and the agent fills them with `alter_table` and `alter_column`. [Describe every table and column](https://datanotes.dev/guides/database-objects/tables/#describe-every-table-and-column) shows the rule in use.
+
+## The agent reads views first
+
+A view is a stored query with a name, a description and aliases, such as `vw_to_watch`: the films whose status is `to watch`, shortest first. `list_tables` returns views next to tables, and `select_rows` reads a view like a table and can narrow it further. When a view answers the question, the agent reads it instead of rebuilding the filter, so the answer follows your definition of “to watch” and not the agent’s. [Views](https://datanotes.dev/guides/database-objects/views/) shows views with joins, groups and filters on the note they’re shown for.
+
+## The agent writes only through checked operations
+
+Rows change through `insert_row`, `update_row`, `update_rows`, `delete_rows` and `batch`; the schema changes through operations such as `create_table`, `add_column` and `add_constraint`. The engine checks every one against the table’s column types, limits, links and CHECK constraints, and writes nothing when a check fails. Three arguments make an agent’s writes safer:
+
+* **`dry_run`**: reports what would change, without writing
+* **`batch`**: a group of writes that succeed or fail together, and that you undo as one
+* **`expect`** on `update_row`: writes only if the row still has the values the agent read, so it doesn’t overwrite an edit you made in the meantime
+
+The agent never edits `metastore.yaml`: a hand edit skips validation and has no undo. [Concurrent writes](https://datanotes.dev/develop/concurrency/) explains what happens when agents, programs and people write at the same time.
+
+## A refusal tells the agent what to fix
+
+A refused write names the note, the column or rule, and the values the engine accepts. It ends with a hint on how to fix it and a link to the page that shows the fix. For a film with the status `seen`, the engine answers:
+
+```text
+insert_row refused — nothing was written:
+invalid datanotes/main/public/film/Sunrise.md: status must be one of: to watch (on my watchlist, not seen yet); watched (I saw it at least once)
+Hint: Use one of the allowed values listed in the message, written exactly; describe_table shows what each one means. To add a value, alter_column the enum. Then call insert_row again (dry_run: true checks without writing).
+Docs: read_docs("guides/database-objects/columns#describe-what-each-enum-value-means")
+```
+
+The agent can correct the value and try again, or ask you. Every other error follows the same pattern: a misspelled table or column gets the closest real name, a wrong filter operator gets the one meant, and a tool argument the tool doesn’t take gets the tool’s arguments. [Read the engine’s errors](https://datanotes.dev/guides/agents/reading-errors/) shows them all. Before it writes a link, the agent can call `list_link_targets`, which returns the rows the link column accepts, such as the genres a film may link to. Over HTTP, a refused write comes back with status 422 and the reasons in the body.
+
+## The agent reads the docs of its version
+
+`datanotes mcp` also serves this documentation, read from the installed `datanotes` package, with three tools: `list_docs`, `read_docs` and `search_docs`. The agent looks up an operation or an example without internet access, and the pages always match the version it talks to. [Read the docs offline](https://datanotes.dev/guides/agents/docs-offline/) shows the tools.
+
+## Every write names the agent that made it
+
+The engine records an actor with every change. Through `datanotes mcp`, the actor comes from the MCP connection:
+
+* **`harness`** and **`harness_version`**: the client’s name and version from the MCP handshake, such as `claude-code`
+* **`session`**: the MCP session, shortened to 16 characters
+* **`tool`**: the tool the agent called
+* **`auth`**: `owner`, or the token’s name for a [named token](https://datanotes.dev/start/connect-agents/#give-each-agent-its-own-token)
+* **`model`**: the model, when an MCP server reports it with `POST /datanotes/sessions/identify/`
+
+`describe_history` shows the actor of each commit:
+
+```json
+{
+  "table": "main.public.film",
+  "version": 10,
+  "operation": "UPDATE",
+  "migration_id": "20261009T215306-update_rows-update-film",
+  "actor": {
+    "session": "5d8c0456-3b15-40",
+    "harness": "claude-code",
+    "harness_version": "2.5.0",
+    "tool": "batch",
+    "auth": "owner"
+  },
+  "batch": "20261009T215306-batch-log-the-screening-of-metropoli"
+}
+```
+
+Three operations read this record:
+
+* **`list_migrations`**: the journal, newest first, each operation with `by`, the agent’s name
+* **`describe_history`**: the commits of one table or of every table, with the full actor; it needs history on
+* **`list_changes`**: every row change with its actor, and with `kinds: ["tool_call"]` every tool call the MCP server reported, reads included
+
+A script records its own actor with the `X-Datanotes-Actor` header or the client’s `actor` option, as the [HTTP API guide](https://datanotes.dev/develop/http-api/#record-who-makes-each-write) shows.
+
+## Undo what an agent did
+
+Because the journal records every write, you can take back one operation or a whole run:
+
+* **One operation**: `undo_migration` with its `migration_id`; for a `batch`, it reverts every write in it
+* **A whole run**: `restore_database` with `before_migration` set to the agent’s first operation or batch; every table with history goes back to its state before that operation (run it with `dry_run` first)
+* **One table**: `restore_table` to a version or a time
+
+The journal records an undo too, so you can undo the undo. The engine refuses an undo that would overwrite a note you edited since, and lists the conflicts. [Restore a table or the database](https://datanotes.dev/guides/history/restore/) shows each operation with the engine’s answers, and the [prompts](https://datanotes.dev/guides/agents/prompts/#safety-and-history-prompts) show how to ask for them.
+
+## Give each agent only what it needs
+
+The owner token can do everything. A [named token](https://datanotes.dev/guides/security/tokens/) limits an agent to the tables in `write`, to schema changes only with `ddl`, and to configuration, undo and restore only with `maintain`. The journal then names the token with each of its writes. [Connect agents](https://datanotes.dev/start/connect-agents/) shows how to create one and pass it to an MCP client.

package/dist/docs/guides/agents/prompts.md

@@ -0,0 +1,495 @@
+# Prompts for your agent
+
+> Copy prompts for everyday notes, schema changes, history and imports, with the tools the agent calls and the same calls from code.
+
+Once your agent is [connected](https://datanotes.dev/start/connect-agents/), you talk to your vault in plain words. This page gives prompts to copy, grouped by task. They all use one example: a diary of classic films with the tables `film`, `actor`, `genre` and `watch`.
+
+For each prompt you see what happens, the [operations](https://datanotes.dev/reference/operations/) the agent calls, in order, and what you get. Each one ends with the same call from code, for when you’d rather script it.
+
+The tool sequences and answers come from runs against a real engine through `datanotes mcp`, the Model Context Protocol (MCP) server. Your agent may add a read here and there, such as a second `describe_table`, but the writes are the ones shown.
+
+## Call the same operations from code
+
+Every tool of the agent is an operation of the [HTTP API](https://datanotes.dev/develop/http-api/), so a script makes the calls the agent makes. The snippets on this page use one client of [`datanotes/client`](https://datanotes.dev/develop/client/):
+
+```ts
+import { DatanotesClient } from "datanotes/client";
+
+
+const db = new DatanotesClient({
+  url: "http://127.0.0.1:27150",
+  token: process.env.DATANOTES_TOKEN ?? "",
+  actor: { harness: "my-script" },
+});
+```
+
+`db.call(name, args)` takes the agent’s tool name and arguments, and sends the request the [HTTP API reference](https://datanotes.dev/api/) lists for it. With curl, you send the same JSON to the operation’s route, `POST /datanotes/operations/<operation>/`. The body holds the operation’s arguments, with the same names as the agent’s tool.
+
+## Prompts for everyday notes
+
+These prompts read and write rows of your diary. They need the `watch` table and the `vw_to_watch` view, which the [schema prompts](#schema-prompts) create.
+
+### Log a viewing with where, when and who
+
+```text
+I watched Metropolis tonight at 20:30 at the film club downtown, with
+Anna. Live organ accompaniment. Five stars. Log it in my film diary.
+```
+
+The agent finds the film, adds a `watch` row and marks the film watched, in one `batch`, so both writes succeed or fail together.
+
+* **Tools**: `list_tables`, `describe_table` on `watch`, `select_rows` on `film` for `Metropolis`, then `batch` with `insert_row` and `update_row`
+* **You get**: a new note, `main/public/watch/2026-10-09T2030.md`, and `Metropolis` with `status: watched`, `rating: 5` and `watched_on: 2026-10-09`; one `undo_migration` on the batch’s `migration_id` reverts both
+
+From code, the batch is `POST /datanotes/operations/batch/`:
+
+```ts
+await db.call("batch", {
+  summary: "Log the screening of Metropolis",
+  operations: [
+    {
+      op: "insert_row",
+      table: "watch",
+      values: {
+        film: "[[Metropolis]]",
+        occurred_at: "2026-10-09T20:30:00",
+        where: "cinema",
+        place: "the film club downtown",
+        with: "Anna",
+      },
+      body: "Live organ accompaniment.\n",
+    },
+    {
+      op: "update_row",
+      table: "film",
+      path: "main/public/film/Metropolis.md",
+      set: { status: "watched", rating: 5, watched_on: "2026-10-09" },
+    },
+  ],
+});
+```
+
+### Mark a film to watch
+
+```text
+Put Battleship Potemkin on my watchlist: 1925, 75 minutes, directed by
+Sergei Eisenstein, Soviet montage.
+```
+
+The agent matches “watchlist” against the aliases of the `film` table, checks that the film isn’t there yet, and adds it.
+
+* **Tools**: `list_tables`, `select_rows` on `film` for the title, then `insert_row`
+* **You get**: `main/public/film/Battleship Potemkin.md`, with `status: to watch` and a link to the `Soviet montage` genre
+
+From code, `POST /datanotes/operations/insert_row/`:
+
+```ts
+await db.call("insert_row", {
+  table: "film",
+  values: {
+    title: "Battleship Potemkin",
+    year: 1925,
+    minutes: 75,
+    director: "Sergei Eisenstein",
+    genre: "[[Soviet montage]]",
+    status: "to watch",
+  },
+});
+```
+
+### Ask what to watch tonight
+
+```text
+What should I watch tonight? I have about an hour and a half.
+```
+
+The agent finds the view of your watchlist and narrows it to films that fit the evening.
+
+* **Tools**: `list_tables`, which lists `vw_to_watch` under `views`, then `select_rows` on the view with a filter on `minutes`
+* **You get**: Battleship Potemkin, 75 minutes; Metropolis, at 153 minutes, waits for a longer evening
+
+From code, `POST /datanotes/operations/select_rows/`:
+
+```ts
+const tonight = await db.call("select_rows", {
+  table: "vw_to_watch",
+  where: { minutes: { lte: 100 } },
+});
+```
+
+### Find the films you saw with someone
+
+```text
+Which films did I see with Anna this year?
+```
+
+The agent reads the `watch` table, where `with` holds who came along, and matches the name case-insensitively.
+
+* **Tools**: `list_tables`, `describe_table` on `watch`, then `select_rows` with `icontains` on `with` and `gte` on `occurred_at`
+* **You get**: Sherlock Jr. at home in February, His Girl Friday at the cinema in March, Nosferatu at an outdoor screening in June, and Metropolis tonight
+
+From code, `POST /datanotes/operations/select_rows/`:
+
+```ts
+await db.call("select_rows", {
+  table: "watch",
+  where: { with: { icontains: "anna" }, occurred_at: { gte: "2026-01-01" } },
+  columns: ["occurred_at", "film", "where"],
+  order_by: "occurred_at",
+});
+```
+
+### Write your review
+
+```text
+Add my review of Charade under a "My review" heading: Grant and Hepburn
+trade lines across Paris while everyone lies about the money.
+```
+
+The agent reads the note’s body first, then writes the review under its own heading and keeps the rest of the note.
+
+* **Tools**: `select_rows` on `film` with `include_body`, then `update_row` with `body_sections`
+* **You get**: a `## My review` section at the end of `Charade.md`, below the text the note already had
+
+From code, `POST /datanotes/operations/update_row/`:
+
+```ts
+await db.call("update_row", {
+  table: "film",
+  path: "main/public/film/Charade.md",
+  body_sections: {
+    "My review":
+      "Grant and Hepburn trade lines across Paris while everyone lies " +
+      "about the money.",
+  },
+});
+```
+
+## Schema prompts
+
+These prompts change the tables themselves. The agent changes `metastore.yaml` only through schema operations, which check the change against the rows, journal it and make it undoable. To limit which agents may change the schema, give them a [named token](https://datanotes.dev/start/connect-agents/#give-each-agent-its-own-token) without `ddl`.
+
+### Create the watch table
+
+```text
+Create a table for each time I watch a film: when, the film, where
+(cinema, home or outdoor screening), the place in my words, and who came
+along.
+```
+
+The agent checks that no table records viewings yet, then creates one named by the date and time of each viewing.
+
+* **Tools**: `list_tables`, `describe_table` on `film` to link to it, then `create_table`
+* **You get**: `main.public.watch` in `metastore.yaml`, with `occurred_at` as its time column, so the engine names each note like `2026-10-09T2030.md`; its description and aliases lead an agent to it from words such as “diary”, and each column says what it holds
+
+The engine refuses a table or a column without a description, so the agent writes one for each.
+
+From code, `POST /datanotes/operations/create_table/`:
+
+```ts
+await db.call("create_table", {
+  name: "watch",
+  description: "Each time I watch a film: when, where and with whom",
+  time_column: "occurred_at",
+  columns: [
+    {
+      name: "occurred_at",
+      type: "datetime",
+      required: true,
+      description: "When the film started",
+    },
+    {
+      name: "film",
+      type: "link",
+      ref: "main.public.film",
+      required: true,
+      description: "The film I watched",
+    },
+    {
+      name: "where",
+      type: "enum",
+      values: ["cinema", "home", "outdoor screening"],
+      required: true,
+      description: "The kind of place I watched it in",
+    },
+    { name: "place", type: "string", description: "Where, in my words" },
+    { name: "with", type: "string", description: "Who came along" },
+  ],
+  aliases: ["viewings", "screenings", "diary"],
+});
+```
+
+### Add a column
+
+```text
+Add a column to my film diary for what the ticket cost.
+```
+
+The agent reads the table first, to reuse a column that already means the same, and adds a new one only when none does.
+
+* **Tools**: `describe_table` on `watch`, then `add_column`
+* **You get**: a `price` column, a number of 0 or more with two decimals; existing rows stay as they are, because the engine writes a sparse column only on rows that have a value
+
+From code, `POST /datanotes/operations/add_column/`:
+
+```ts
+await db.call("add_column", {
+  table: "watch",
+  column: {
+    name: "price",
+    type: "number",
+    min: 0,
+    step: 0.01,
+    description: "What the ticket cost",
+  },
+});
+```
+
+### Add the CHECK rated_when_watched
+
+```text
+A film I've watched must have a rating. Make that a rule of the film table.
+```
+
+The agent writes the rule as a filter every row must pass: a film is either not watched, or has a rating.
+
+* **Tools**: `describe_table` on `film`, then `add_constraint`
+* **You get**: the CHECK `rated_when_watched`; the engine refuses it while a row breaks it, listing the rows, and from then on refuses any write that breaks it
+
+Once the rule exists, the engine refuses to mark Battleship Potemkin as watched without a rating, and writes nothing:
+
+```text
+update_row refused — nothing was written:
+invalid main/public/film/Battleship Potemkin.md: rated_when_watched violates CHECK rated_when_watched: {"or":[{"status":{"ne":"watched"}},{"rating":{"exists":true}}]}
+```
+
+The agent then asks you for a rating. From code, the CHECK is `POST /datanotes/operations/add_constraint/`:
+
+```bash
+curl -s http://127.0.0.1:27150/datanotes/operations/add_constraint/ \
+  -H "Authorization: Bearer your_owner_token" \
+  -H "Content-Type: application/json" \
+  -d '{"table": "film",
+       "name": "rated_when_watched",
+       "check": {"or": [{"status": {"ne": "watched"}},
+                        {"rating": {"exists": true}}]}}'
+```
+
+### Make a view of the films to watch
+
+```text
+Make a view of the films I still have to watch, shortest first.
+```
+
+The agent stores the query as a view, with a description and aliases so that later questions such as “what’s on my watchlist?” find it.
+
+* **Tools**: `list_tables`, to reuse a view that exists, then `create_view`
+* **You get**: `vw_to_watch` in `metastore.yaml`, which `list_tables` lists under `views` and `select_rows` reads like a table
+
+From code, `POST /datanotes/operations/create_view/`:
+
+```ts
+await db.call("create_view", {
+  name: "vw_to_watch",
+  query: {
+    table: "film",
+    where: { status: "to watch" },
+    columns: ["title", "year", "minutes", "director"],
+    order_by: "minutes",
+  },
+  description: "Films on my watchlist, shortest first",
+  aliases: ["watchlist", "what to watch"],
+});
+```
+
+## Safety and history prompts
+
+These prompts show what an agent changed and take it back. Every write is in the journal, so `undo_migration` works on any table. Reading a table as it was and restoring the whole database need the tables’ history. A database the engine creates has it on. A database whose `metastore.yaml` lacks the setting, such as one from a version before 3.0.0, has it off. Turn it on once:
+
+```text
+Turn history on for every table.
+```
+
+The agent calls `configure_database` with `history: true`. The journal doesn’t record database settings, so an agent changes them only when you ask. From code, it’s `POST /datanotes/operations/configure_database/` with `{"history": true}`.
+
+### Ask what the agent changed today
+
+```text
+What did you change in my vault today?
+```
+
+The agent reads the journal, where every operation names the agent that made it.
+
+* **Tools**: `list_migrations` with `since`, or `describe_history` without a table for the commits of every table with their full actor
+* **You get**: one line per operation, each with `by: "claude-code"`, such as `batch` “Log the screening of Metropolis” or `add_constraint` on `film`; your own writes from an editor or a script name their own source
+
+From code, `POST /datanotes/operations/list_migrations/`:
+
+```ts
+const today = await db.call("list_migrations", { since: "2026-10-09" });
+```
+
+### Undo the agent’s last change
+
+```text
+Undo your last change.
+```
+
+The agent finds its newest operation in the journal and reverts it.
+
+* **Tools**: `list_migrations`, then `undo_migration` with its `migration_id`
+* **You get**: the notes as they were before that operation, and the undo’s own `migration_id`, since the journal records the undo too; if you edited one of the notes since, the engine refuses and lists the conflicts instead of overwriting your edit
+
+From code, `POST /datanotes/operations/undo_migration/`:
+
+```ts
+await db.call("undo_migration", {
+  migration_id: "20261009T215306-batch-log-the-screening-of-metropoli",
+});
+```
+
+### Put everything back as it was before the agent started
+
+```text
+Put everything back as it was before you started this evening. Show me
+what would change first.
+```
+
+The agent finds its first operation of the session, previews the restore, and runs it once you agree.
+
+* **Tools**: `describe_history` without a table, then `restore_database` with `before_migration` and `dry_run: true`, then `restore_database` again without `dry_run`
+* **You get**: every table with history back to that moment, in one operation that `undo_migration` can revert; in the run behind this page, the restore removed Battleship Potemkin and tonight’s `watch` row, and gave Metropolis and Charade their old content back
+
+The dry run lists what changes in each table before the engine writes anything. Here is its answer, trimmed:
+
+```json
+{
+  "ok": true,
+  "dry_run": true,
+  "planned_deletes": [
+    "main/public/film/Battleship Potemkin.md",
+    "main/public/watch/2026-10-09T2030.md"
+  ],
+  "planned_texts": [
+    "main/public/film/Metropolis.md",
+    "main/public/film/Charade.md"
+  ],
+  "unchanged": ["main.public.actor", "main.public.genre"],
+  "skipped": []
+}
+```
+
+The restore doesn’t rewind views or database settings, and lists a table without history in `skipped`. From code, `POST /datanotes/operations/restore_database/`:
+
+```ts
+await db.call("restore_database", {
+  before_migration: "20261009T215329-insert_row-insert-into-film",
+  dry_run: true,
+});
+```
+
+### Read a note as it was last week
+
+```text
+Show me Nosferatu as it was last week.
+```
+
+The agent reads the `film` table at a past time and picks the row.
+
+* **Tools**: `select_rows` on `film` with `timestamp`, and `describe_history` on `film` when you ask what changed since
+* **You get**: the row with the values it had then, and the table `version` the engine read; if the table didn’t exist yet at that time, the engine answers `main.public.film did not exist at 2026-10-02T09:00:00Z`
+
+From code, `POST /datanotes/operations/select_rows/`:
+
+```ts
+await db.call("select_rows", {
+  table: "film",
+  where: { title: "Nosferatu" },
+  timestamp: "2026-10-02T09:00:00Z",
+});
+```
+
+## Import prompts
+
+This prompt turns notes you already have into rows, without moving them.
+
+### Turn a folder of notes into a table
+
+```text
+Turn my Films/ folder into a table. Show me the columns you propose
+before you create anything.
+```
+
+The agent reads the notes’ front matter, proposes a table, and waits for your review. Review it: on five notes, `infer_table` marked `director` and `minutes` as `unique`, because no two notes shared a value. The engine would then refuse a sixth film by the same director, so ask the agent to drop `unique` there.
+
+The notes can’t say what each key means, so the proposal leaves every `description` `null`. The agent writes them and asks you when a key isn’t clear. `create_table` refuses a table or a column without one.
+
+* **Tools**: `list_folder` on `Films`, `infer_table` with `folder: "Films"`, then, after your review, `create_table` with the reviewed and described proposal, `adopt_rows` with `dry_run: true`, `adopt_rows`, and `check_table`
+* **You get**: a `film` table whose rows are your notes, moved to the table’s folder with the links to them rewritten; each note gets `table` and an `id`, and keeps its body; `check_table` reports no violations
+
+`infer_table` returns `proposal`, the arguments of `create_table`, and `adopt`, the arguments of `adopt_rows`. From code, the inference is `POST /datanotes/operations/infer_table/`:
+
+```ts
+const inferred = await db.call("infer_table", {
+  folder: "Films",
+  name: "film",
+});
+const { proposal, adopt } = inferred.value as {
+  proposal: { columns: { name: string }[] };
+  adopt: Record<string, unknown>;
+};
+```
+
+After you review `proposal`, create the table. The notes keep the title in their file name, so add a `title` column with `identity: "filename"` and name the rows with `filename: "{title}"`. Write a description for every column, or `create_table` refuses the table:
+
+```ts
+const meaning: Record<string, string> = {
+  year: "Year the film first came out",
+  minutes: "Running time in minutes",
+  director: "Who directed the film",
+  // … one for each column of the proposal
+};
+const created = await db.call("create_table", {
+  ...proposal,
+  description: "Classic films I watched or want to watch",
+  filename: "{title}",
+  columns: [
+    {
+      name: "title",
+      type: "string",
+      identity: "filename",
+      description: "The film's title, which is also its note's name",
+    },
+    ...proposal.columns.map((c) => ({
+      ...c,
+      unique: false,
+      description: meaning[c.name],
+    })),
+  ],
+});
+if (!created.ok) throw new Error(String(created.value));
+```
+
+Then adopt the notes with `POST /datanotes/operations/adopt_rows/`. `relocate` moves them to the table’s folder and rewrites the links to them:
+
+```ts
+const { paths, rename } = adopt as {
+  paths: string[];
+  rename: Record<string, string>;
+};
+const adopted = await db.call("adopt_rows", {
+  table: "film",
+  paths,
+  rename,
+  relocate: true,
+});
+if (!adopted.ok) throw new Error(String(adopted.value));
+```
+
+## Learn more about agents and operations
+
+These pages go deeper into what the prompts use:
+
+* [How agents work with your vault](https://datanotes.dev/guides/agents/how-agents-use-datanotes/): what the agent reads first, how it finds tables and what the journal records
+* [Guides](https://datanotes.dev/guides/database-objects/tables/): every operation in use, with the engine’s real answers
+* [Operations](https://datanotes.dev/reference/operations/): every tool and its arguments