@anchrd/intel 0.59.0

package/migrations/0023_a_board_and_its_tasks.sql

@@ -0,0 +1,116 @@
+-- Two more node kinds, `board` and `task`, and the two side tables that carry what a node row must
+-- not (D66, anchrd/intel#376).
+--
+-- ⚠️ BOTH words in ONE rebuild. Adding them in two migrations would be the same risky operation
+-- twice, and this one has gone wrong before: `0005` committed with every row of `node_links` gone.
+--
+-- The split this migration encodes: IDENTITY through `kind`, FIELDS through a side table.
+--   * `kind` because the tree has to hide `task` on EVERY level query. As a kind that is a condition
+--     on a column the query already carries; as a `document` plus a side-table row it would be a
+--     join on the hottest path in the interface.
+--   * the side table because `status`, `assignee` and the dates are FILTER columns. In the `nodes`
+--     row they would stand empty for every other kind.
+--
+-- The recipe below is the one in `packages/intel/CLAUDE.md`, *Rebuilding `nodes` is a recipe*. All
+-- four points, and each is one a previous migration got wrong first:
+--   1. the new table is created under its FINAL name — never `ALTER TABLE … RENAME`, which rewrites
+--      every `REFERENCES` clause and drags the children onto the table about to be dropped;
+--   2. `node_links` is carried out and back with `INSERT OR IGNORE`, because it is the one child
+--      declared `ON DELETE CASCADE` and `DROP TABLE nodes` fires an implicit `DELETE FROM`;
+--   3. `PRAGMA defer_foreign_keys`, never `foreign_keys = OFF` — D1 ignores the latter over its HTTP
+--      API while miniflare honours it, so a green test here would prove nothing about production;
+--   4. the columns are named on BOTH sides of `INSERT … SELECT`, so a future reordering cannot turn
+--      every title into an owner id and still commit.
+PRAGMA defer_foreign_keys = TRUE;
+
+CREATE TABLE nodes_carry AS SELECT * FROM nodes;
+CREATE TABLE node_links_carry AS SELECT * FROM node_links;
+
+DROP TABLE nodes;
+
+CREATE TABLE nodes (
+  id TEXT PRIMARY KEY NOT NULL,
+  parent_id TEXT REFERENCES nodes(id),
+  kind TEXT NOT NULL CHECK (kind IN ('folder', 'document', 'attachment', 'table', 'board', 'task')),
+  title TEXT NOT NULL CHECK (length(title) BETWEEN 1 AND 240),
+  description TEXT CHECK (description IS NULL OR length(description) <= 2000),
+  owner_id TEXT NOT NULL,
+  current_version_id TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  archived_at TEXT
+);
+
+INSERT INTO nodes (
+  id, parent_id, kind, title, description, owner_id,
+  current_version_id, created_at, updated_at, archived_at
+)
+SELECT
+  id, parent_id, kind, title, description, owner_id,
+  current_version_id, created_at, updated_at, archived_at
+FROM nodes_carry;
+
+INSERT OR IGNORE INTO node_links SELECT * FROM node_links_carry;
+
+DROP TABLE nodes_carry;
+DROP TABLE node_links_carry;
+
+CREATE INDEX nodes_parent_idx ON nodes(parent_id, archived_at, title);
+CREATE INDEX nodes_owner_idx ON nodes(owner_id, archived_at);
+
+-- The board's own configuration: which columns it has and in what order. It is one row per board
+-- node, and it exists because a list of statuses is not a node property — every other kind would
+-- carry it empty.
+--
+-- ⚠️ `ON DELETE CASCADE` here and on `board_tasks` below, and that is deliberate in a repository
+-- whose rule is *refuse rather than cascade*. The rule protects a CONTAINER from taking its contents
+-- down with it; these two rows are not contents but the node's own fields, split off only because
+-- SQLite has no per-kind columns. A board whose row here outlived it would be a configuration for a
+-- board that does not exist.
+CREATE TABLE boards (
+  node_id TEXT PRIMARY KEY NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
+  statuses_json TEXT NOT NULL DEFAULT '[]',
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+
+-- What a task carries beyond a node. Every column here is one somebody filters or sorts by — that
+-- is the whole reason they are not in the body.
+--
+-- ⚠️ `position` is REAL, not INTEGER. Dragging a card between two neighbours then needs no rewrite
+-- of the whole column: the new value is the midpoint of the two. With integers every drop would
+-- renumber the rows below it, and two people dropping at once would fight over rows neither touched.
+CREATE TABLE board_tasks (
+  node_id TEXT PRIMARY KEY NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
+  board_id TEXT NOT NULL REFERENCES nodes(id),
+  status TEXT NOT NULL,
+  assignee_id TEXT,
+  labels_json TEXT NOT NULL DEFAULT '[]',
+  start_date TEXT,
+  due_date TEXT,
+  -- "waits for", as a COLUMN and not as a sentence in the body. The DoD of #376 says it in one
+  -- line: relations are columns the text points at, never the other way round. A dependency living
+  -- in prose cannot be asked "what is blocked right now", and `node_links` cannot answer it either
+  -- — that table says two nodes are related, not that one waits for the other.
+  --
+  -- ⚠️ It points at `nodes`, not at `board_tasks`. A task may wait for something that is not a
+  -- task: a document that has to be approved first, a board that has to be finished. Narrowing it
+  -- to the side table would decide today that only tasks can block, and nothing asked for that.
+  depends_on TEXT REFERENCES nodes(id),
+  position REAL NOT NULL DEFAULT 0,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+
+-- The board view reads one column at a time, ordered. Both columns of the sort are in the index, so
+-- the read needs no sorting pass — the same reason `audit_events_feed_idx` carries its tie-break
+-- (anchrd/intel#620).
+CREATE INDEX board_tasks_column_idx ON board_tasks(board_id, status, position);
+
+-- "What is assigned to me, soonest first" — across every board, which is why `assignee_id` leads
+-- and `board_id` does not appear.
+CREATE INDEX board_tasks_assignee_idx ON board_tasks(assignee_id, due_date);
+
+-- "What is blocked by this node" — the direction the interface asks in. Without it the question is
+-- a scan of every task on every board.
+CREATE INDEX board_tasks_depends_idx ON board_tasks(depends_on) WHERE depends_on IS NOT NULL;

package/migrations/0024_the_archive_is_a_column.sql

@@ -0,0 +1,33 @@
+-- The archive as a column every board has (D68, #674).
+--
+-- ⚠️ Only the VISIBILITY is stored. Which cards are in the archive is `nodes.archived_at` and
+-- nothing else — a second column holding "is archived" would be the two truths D68 exists against.
+-- A card is in the archive column BECAUSE it is archived; dropping it there archives it, and
+-- pulling it out restores it into the working column `board_tasks.status` still names.
+--
+-- ⚠️ Default 1: the column is there on every board unless somebody hides it. A board that predates
+-- this migration therefore shows it too, which is the decided behaviour rather than an accident —
+-- an archive nobody can see is an archive nobody empties.
+ALTER TABLE boards ADD COLUMN archive_visible INTEGER NOT NULL DEFAULT 1;
+
+-- ⚠️ **Existing data.** Until this migration `BoardColumn.id` was a free string: a board could
+-- configure a column called `archived` itself. From here the name is reserved, and without this
+-- step such a board would show TWO columns with one id — the stored one and the derived one — and
+-- the cards of both would be indistinguishable.
+--
+-- ⚠️ **Every row with that status, not only the ones whose board still configures it.** Columns are
+-- REPLACED rather than merged, so a board may have used the column and dropped it again; those
+-- cards still carry `status = 'archived'` while `statuses_json` has long forgotten it. Left alone
+-- they would surface in the archive column with `archived_at` still `null` — a card that looks
+-- archived, is not, and cannot be restored, because there is nothing to restore.
+--
+-- The new name is deliberately ugly, because it is meant to be seen: whoever reads it knows
+-- something was renamed here and can put it right in the settings.
+UPDATE board_tasks SET status = 'archived_column_renamed' WHERE status = 'archived';
+
+UPDATE boards
+SET statuses_json = replace(statuses_json, '"id":"archived"', '"id":"archived_column_renamed"')
+WHERE node_id IN (
+  SELECT b.node_id FROM boards b, json_each(b.statuses_json)
+  WHERE json_extract(json_each.value, '$.id') = 'archived'
+);

package/migrations/0025_archiving_takes_the_subtree.sql

@@ -0,0 +1,29 @@
+-- Archiving takes the whole subtree, and this column is what lets it come back (D71, #733).
+--
+-- ⚠️ **The two steps were the wrong way round.** `purge` cascaded over the subtree since #492 while
+-- `archive` touched a single row, so a folder archived over live children handed those children to
+-- the one step that cannot be undone. Cascading the REVERSIBLE step instead closes the whole chain:
+-- nothing live sits under an archived node any more, so the purge can keep cascading without ever
+-- reaching something alive.
+--
+-- What this column holds is the OPERATION a node fell with, not a flag. A restore brings back
+-- exactly the nodes that fell together, and a child that was already archived before keeps its own
+-- older operation id — and stays archived.
+--
+-- ⚠️ **Existing data keeps `NULL` here**, and that is not the same as "fell alone": it means
+-- "archived before this migration, and nobody recorded what it fell with". A restore therefore
+-- treats `NULL` as itself only, never as a group — otherwise restoring one old node would revive
+-- every node ever archived before today.
+ALTER TABLE nodes ADD COLUMN archived_with TEXT;
+
+-- The restore reads this column for one node and then finds its siblings by it. Without the index
+-- that is a scan of the whole table on every restore of a large folder.
+CREATE INDEX IF NOT EXISTS nodes_archived_with ON nodes (archived_with) WHERE archived_with IS NOT NULL;
+
+-- ⚠️ **Flows fall with the tree, so they need the same column.** They hang in the folder tree by
+-- `parent_id` and carry their own `archived_at`, and `inspectPurgeTree` collects them by that same
+-- parent. A cascade that took only `nodes` would leave exactly one kind of live thing under an
+-- archived folder — the kind this repository's own flows are filed as.
+ALTER TABLE flows ADD COLUMN archived_with TEXT;
+
+CREATE INDEX IF NOT EXISTS flows_archived_with ON flows (archived_with) WHERE archived_with IS NOT NULL;

package/migrations/0026_one_feed_over_two_kinds.sql

@@ -0,0 +1,23 @@
+-- The feed reads both kinds at once — nodes and flows — and `audit_events_feed_idx` cannot serve
+-- that. It leads with `resource_type` because every reader until now named exactly one kind, so for
+-- a query saying `resource_type IN ('node', 'flow')` that column is no longer an equality prefix but
+-- an ordinary filter, and the ordering falls off the index.
+--
+-- ⚠️ Measured against the real `feedPageQuery` before this file existed, not assumed
+-- (anchrd/intel#763):
+--
+--     SEARCH e USING INDEX audit_events_feed_idx (resource_type=?)
+--     … | USE TEMP B-TREE FOR ORDER BY
+--
+-- That last line is a sorting pass over the whole table. It costs nothing on the first page and
+-- everything far down — which is exactly where an endless scroll goes.
+--
+-- ⚠️ Both columns, in the order the cursor compares them, for the reason `0022` gives: two events
+-- written in the same millisecond are the normal case inside one batch, and without the tie-break
+-- on `id` a reader skips the second one with no error and no log.
+--
+-- ⚠️ This does NOT replace `audit_events_feed_idx`. That one still serves `audit_list`, which names
+-- one kind and is the contract `anchrd/signals` builds on; dropping it would put a sorting pass into
+-- the reader that has none today. Two readers, two shapes, two indexes.
+CREATE INDEX audit_events_time_idx
+  ON audit_events(occurred_at, id);

package/migrations/0027_the_runs_of_every_flow.sql

@@ -0,0 +1,27 @@
+-- `flow_run_list` may now be asked without a flow (#774): "did anything run at all", over every
+-- flow the caller may read. `flow_runs_flow_idx (flow_id, created_at DESC)` cannot serve that — it
+-- leads with `flow_id`, and without an equality on that column the ordering falls off the index and
+-- SQLite sorts the whole table instead.
+--
+-- ⚠️ Measured against the real `flowRunsPageQuery({ scoped: false })` before this file existed, on
+-- the same engine and the same schema:
+--
+--     SCAN run
+--     … | USE TEMP B-TREE FOR ORDER BY
+--
+-- That last line is a sorting pass over every run in the installation. It costs nothing while a
+-- customer has fifty runs and everything once an agent has been running for a month.
+--
+-- ⚠️ Both columns, in the order the cursor compares them, for the reason `0022` and `0026` give:
+-- two runs created in the same millisecond are not exotic, and without the tie-break on `id` a
+-- reader continuing on `created_at` alone skips the second one with no error and no log.
+--
+-- ⚠️ `DESC` on both, because this page is newest-first. An ASC index can be walked backwards by
+-- SQLite, but only as long as EVERY term agrees on the direction — matching the `ORDER BY` exactly
+-- is the one shape that keeps that true when a third term is added later.
+--
+-- ⚠️ This does NOT replace `flow_runs_flow_idx`. That one still serves the scoped page — the runs
+-- of ONE flow — which is the older and by far the more frequent question; dropping it would put a
+-- full scan into the call that has none today. Two questions, two shapes, two indexes.
+CREATE INDEX flow_runs_time_idx
+  ON flow_runs(created_at DESC, id DESC);

package/migrations/0028_a_prompt_name_over_two_kinds.sql

@@ -0,0 +1,70 @@
+-- A document and a published flow can both be offered as a slash command (#775). What they need is
+-- one short name, and the name has to be unique across BOTH of them: they land in the same
+-- `prompts/list` catalogue, so a document and a flow can take each other's name.
+--
+-- ⚠️ **One field, not two.** `prompt_name` set means offered, `NULL` means not. A boolean beside it
+-- would allow the state "on, without a name", and that is not a thing `prompts/list` could answer.
+--
+-- ⚠️ **No third table, and the choice is deliberate.** A `prompt_names(name PRIMARY KEY, …)`
+-- catalogue would carry the cross-kind uniqueness as a real constraint, and it would cost two
+-- things this schema is not willing to pay: a second truth about the name of one node — every
+-- `SELECT` over `nodes` would have to remember a join, and the one that forgets it answers `NULL`
+-- in silence — and a fourth child table for the `nodes` rebuild recipe to carry (see the package
+-- CLAUDE.md; `node_links` is the one that already has to be carried out and back). The uniqueness
+-- WITHIN one kind is an index here; the uniqueness ACROSS the two is a condition on the write, on
+-- every statement that sets a name, in the same batch that writes it.
+--
+-- ⚠️ The condition on the write is not a nicety. A `SELECT` before an `UPDATE` in a separate call
+-- decides on a state that may be gone by the time the write lands; the check has to be part of the
+-- statement so that the two cannot come apart. What the caller is told — WHICH node or flow holds
+-- the name — is a second, cheap read that only runs once the write has already refused.
+
+-- ⚠️ **This form is MEASURED against real D1, not only against miniflare.** No other file in this
+-- folder adds a `CHECK` through `ALTER TABLE … ADD COLUMN` that reads a DIFFERENT column, and the
+-- package CLAUDE.md is explicit that a green run under the emulator proves nothing about the
+-- deployment — `foreign_keys = OFF` is honoured there and ignored by D1 over its HTTP API. A
+-- migration file is immutable after release, so the failure would surface at the deploy.
+--
+-- Run against a throwaway D1 (`intel-check-0028`, `--remote`) on 2026-08-25 and then deleted. Both
+-- statements applied, `sqlite_master` shows the CHECK on the column, and all six refusals fire with
+-- `SQLITE_CONSTRAINT_CHECK` / `SQLITE_CONSTRAINT_UNIQUE`: a folder and a table with a name, an
+-- uppercase name, a name with a space, a 41-character name, and a second row taking a name that is
+-- already held. A document with a valid name and two rows with none go through.
+--
+-- ⚠️ `kind = 'document'` is in the CHECK, not only in the service. A prompt is an instruction, not
+-- material: a folder, a table, an attachment, a board or a task never carries one (#775). The
+-- service refuses it with a sentence, and this line is what makes that refusal true even for a
+-- write that never passes the service.
+--
+-- ⚠️ `NOT GLOB '*[^a-z0-9-]*'` is the grammar `^[a-z0-9-]{1,40}$` says on the contract, spelled the
+-- one way SQLite can spell it: "no character outside the class anywhere". The obvious
+-- `GLOB '[a-z0-9-]*'` is NOT that check — it constrains the first character and lets every other
+-- one through, so `a_B C` passes it. The hyphen sits last inside the class, where it is a literal
+-- rather than a range.
+ALTER TABLE nodes ADD COLUMN prompt_name TEXT
+  CHECK (
+    prompt_name IS NULL
+    OR (
+      kind = 'document'
+      AND length(prompt_name) BETWEEN 1 AND 40
+      AND prompt_name NOT GLOB '*[^a-z0-9-]*'
+    )
+  );
+
+ALTER TABLE flows ADD COLUMN prompt_name TEXT
+  CHECK (
+    prompt_name IS NULL
+    OR (length(prompt_name) BETWEEN 1 AND 40 AND prompt_name NOT GLOB '*[^a-z0-9-]*')
+  );
+
+-- ⚠️ Partial, and that is the whole reason they work. A plain `UNIQUE` index would let several
+-- rows carry `NULL` too — SQLite treats NULLs as distinct — so the `WHERE` clause buys no
+-- correctness here; it buys the SIZE. Almost every node has no prompt name, and an index over
+-- them all would be one entry per node in the tree to serve a handful of rows.
+--
+-- ⚠️ These two carry the uniqueness WITHIN a kind and nothing more. Two documents cannot share a
+-- name and two flows cannot; a document and a flow can, as far as these indexes are concerned, and
+-- the condition on the write is the only thing that stops them. Reading one of these index names in
+-- a query plan is therefore not evidence that the cross-kind rule held.
+CREATE UNIQUE INDEX nodes_prompt_name_idx ON nodes(prompt_name) WHERE prompt_name IS NOT NULL;
+CREATE UNIQUE INDEX flows_prompt_name_idx ON flows(prompt_name) WHERE prompt_name IS NOT NULL;

package/package.json

@@ -0,0 +1,118 @@
+{
+  "name": "@anchrd/intel",
+  "version": "0.59.0",
+  "type": "module",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anchrd/intel.git",
+    "directory": "packages/intel"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "intel": "bin/intel.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/intel/intel.d.ts",
+      "default": "./dist/intel/intel.js"
+    },
+    "./cloudflare": {
+      "types": "./dist/adapters/cloudflare/cloudflare.d.ts",
+      "default": "./dist/adapters/cloudflare/cloudflare.js"
+    },
+    "./cloudflare-workflow": {
+      "types": "./dist/adapters/cloudflare/cloudflare-flow-workflow.d.ts",
+      "default": "./dist/adapters/cloudflare/cloudflare-flow-workflow.js"
+    }
+  },
+  "files": [
+    "bin",
+    "dist",
+    "examples",
+    "migrations",
+    "src/contract",
+    "!src/contract/**/*.unit.ts",
+    "ui/package.json",
+    "ui/README.md",
+    "ui/index.html",
+    "ui/vite.config.ts",
+    "ui/tsconfig.json",
+    "ui/components.json",
+    "ui/scripts",
+    "ui/src",
+    "!ui/src/**/*.unit.ts",
+    "!ui/src/**/*.unit.tsx",
+    "!ui/src/**/*.int.ts",
+    "!ui/src/**/*.int.tsx",
+    "!ui/src/**/*.e2e.ts",
+    "!ui/src/**/*.e2e.tsx"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node ../../scripts/pack/fix-dts.mjs",
+    "dev": "vite ui",
+    "lint:tokens": "node ui/scripts/lint-tokens.mjs ui/src",
+    "prepack": "bun run build && node ../../scripts/pack/to-dist-manifest.mjs",
+    "postpack": "node ../../scripts/pack/restore-manifest.mjs",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p ui/tsconfig.json",
+    "typecheck:core": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@anchrd/gate-sdk": "^0.28.0",
+    "@blocknote/core": "^0.52.1",
+    "@blocknote/react": "^0.52.1",
+    "@blocknote/shadcn": "^0.52.1",
+    "@cfworker/json-schema": "^4.1.1",
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
+    "@file-viewer/react": "2.3.0",
+    "@file-viewer/renderer-pdf": "2.3.0",
+    "@file-viewer/renderer-presentation": "2.3.0",
+    "@file-viewer/renderer-spreadsheet": "2.3.2",
+    "@file-viewer/renderer-word": "2.3.1",
+    "@file-viewer/vite-plugin": "2.3.1",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@tailwindcss/vite": "^4.3.3",
+    "@tanstack/react-query": "^5.101.4",
+    "@tanstack/react-router": "^1.170.18",
+    "@tanstack/react-table": "^9.1.2",
+    "@vitejs/plugin-react": "^6.0.4",
+    "@xyflow/react": "^12.11.2",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cmdk": "^1.1.1",
+    "fflate": "^0.8.3",
+    "fractional-indexing": "^4.0.0",
+    "hono": "^4.12.32",
+    "lucide-react": "^1.25.0",
+    "openid-client": "^6.8.4",
+    "radix-ui": "^1.6.7",
+    "react": "^19.2.0",
+    "react-aria-components": "^1.19.0",
+    "react-dom": "^19.2.0",
+    "readable-stream": "2.3.8",
+    "tailwind-merge": "^3.6.0",
+    "tailwindcss": "^4.3.3",
+    "ulid": "^3.0.2",
+    "vite": "^8.1.5",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-pool-workers": "^0.19.0",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^24.13.3",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "jsdom": "^29.1.1",
+    "vitest": "^4.1.10",
+    "wrangler": "^4.115.0"
+  },
+  "main": "./dist/intel/intel.js",
+  "module": "./dist/intel/intel.js",
+  "types": "./dist/intel/intel.d.ts"
+}

package/src/contract/CLAUDE.md

@@ -0,0 +1,152 @@
+# The wire contract
+
+Public, runtime-validated wire formats shared by the Intel server and the browser application.
+
+⚠️ **This was `@anchrd/intel-contract` until #827** (**D84**). It is no longer a package of its own:
+it lives here, inside `@anchrd/intel`, and it has **two** readers with two ways in.
+
+| reader | how it imports |
+|---|---|
+| the server, `packages/intel/src` | **relative** — `../contract/node.ts`; it is the same TypeScript program |
+| the surface, `packages/intel/ui/src` | the **`@contract` alias** — `@contract/node.ts` |
+
+The alias exists because the surface is a separate Vite program that merely shares the directory. It
+resolves to `../src/contract` in `ui/vite.config.ts`, `ui/vitest.config.ts` and `ui/tsconfig.json`,
+and that one relative path is correct **both** in this tree and inside the published tarball — the
+surface sits at `<package>/ui` in both. ⚠️ That is also why `src/contract` is in the `files`
+whitelist as source and not only as built `dist`: a customer's `intel build` compiles these files.
+
+⚠️ **The alias is the surface's ONLY door out of `ui/`**, and `bun run check:boundaries` enforces it
+by name: a relative path climbing out of `ui/src`, or an import of `@anchrd/intel`, is a violation.
+Before #827 the package boundary did that on its own.
+
+- Export schemas and inferred types from the file of their domain; do not add barrels.
+- Inputs are `z.strictObject` schemas. A misspelled field must fail at the boundary.
+- Keep business rules and authorization out of these files.
+- Add a schema only when at least two surfaces consume it — the server, the browser application, or
+  an external caller.
+- Every schema change needs parsing tests for valid, malformed, and unknown-field cases.
+- **A field in a tool input schema without `.describe()` is unfinished**, and `mcp.e2e.ts` says so.
+
+## ⚠️ The description belongs to the field, and the field lives here
+
+A good tool name gets a model to the right **tool**; a described parameter gets it to the right
+**call**. The distance between those two is where the failures live, and they arrive as empty
+results rather than as exceptions — which is why nobody reports them and why this went unnoticed
+until #398: **one** of 119 fields carried a description, and the one that did had been written eight
+months earlier for #126 with the reasoning spelled out beside it.
+
+The description goes on the **Zod schema in this package**, never on the tool registration in
+`mcp.ts`. Then HTTP validation, the MCP schema and the generated types all carry the same sentence
+and there is no second place to drift. `mcp.e2e.ts` asserts it over the whole surface at once, so a
+new field is red on the day it lands rather than when somebody remembers to extend a list.
+
+**What a description does:**
+
+- says what the field **means**, not what type it is — the type is already there;
+- says **where the value comes from** when it is another call's answer ("the `versionId` from
+  `node_version_list`");
+- says **what happens if it is left out**, for an optional field;
+- says **what goes wrong** where that is not obvious — the exact place a model would otherwise guess.
+
+**What it must not do** is restate the field name in prose. `nodeId: "The ID of the node"` costs
+bytes and teaches nothing. ⚠️ **An honest gap beats a filler sentence**: `tools/list` is sent on
+every connection, and the descriptions added in #398 grew it from 47 222 to 65 026 bytes. That is
+worth paying for 118 sentences that answer a question; it is not worth paying for paraphrase.
+
+⚠️ **A word that means the same thing everywhere gets ONE described primitive**, not the same
+sentence twenty times — `IdempotencyKey` in `contract.ts` is the example. Twenty copies are twenty
+places to drift, and every one of them ships in the listing.
+
+## ⚠️ One domain, one file — and why the split has to stay
+
+There is **no barrel**, and `biome.json` enforces it (`noBarrelFile: error`, `noReExportAll: error`).
+Every domain owns a file, and every reader names that file:
+
+```text
+contract.ts   the shared primitives, and nothing else
+node.ts   table.ts   share.ts   tool.ts   flow.ts   flow-run.ts   bundle.ts   audit.ts   board.ts   feed.ts
+```
+
+Until anchrd/intel#394 there was one file with one door, and a package with one door and no barrel
+**must** put everything in it. `contract.ts` was 2219 lines, and it was not carelessness — it was the
+bill.
+
+⚠️ **Until #827 those files were also `exports` subpaths of a published package** — `@anchrd/intel-
+contract/node` and its siblings — and a comment about "a subpath is not a barrel" belonged here. They
+are not exported any more, because nothing outside `@anchrd/intel` reads them: `agents` and `signals`
+talk to Intel over HTTP and MCP (ADR-0007), and the installation only ever imported
+`@anchrd/intel/cloudflare`. Adding a public `./contract*` export back is a YAGNI violation until a
+consumer exists; adding one then is one line.
+
+Three things follow, and none is optional:
+
+- **A new schema goes in the file of its domain**, and a domain with no file gets one. Adding it to
+  `contract.ts` because that is where the imports already point re-grows the file this split paid
+  for.
+- **`contract.ts` holds what every domain needs and nothing else** — `IntelId`, `IsoDateTime`, the
+  handful of primitives. It re-exports nothing. If a schema in it is used by exactly one domain, it
+  is in the wrong file.
+- **An import names the narrowest file that has the symbol.** `flow-run.ts` over `flow.ts`,
+  `flow.ts` over `contract.ts`. That is what makes a change to the flow schemas cost a rebuild of the
+  files that read flows, and nothing else.
+
+⚠️ **The dependency graph between these files has to stay acyclic**, and it is easy to break by
+accident: a name mentioned in a COMMENT looks like a dependency to anything that scans for one. The
+graph today is `table → node`, `flow → node`, `flow-run → flow`, and everything → `contract.ts`. If
+two domains genuinely need each other, the shared part belongs in `contract.ts`.
+
+⚠️ `flow → node` was added in #376 and is worth the edge it costs: `RelationNodeKind` used to write
+the node kinds out by hand, and when D66 added two of them the copy did not follow — the relation
+graph would have gone on answering about four kinds while the tree held six, silently. It is now
+`z.enum([...NodeKind.options, "flow"])`. **A derived union beats an edge**, and the extra member is
+exactly why `check:boundaries` never caught the copy: the rule there refuses a union that only
+restates `NodeKind`, and this one had one word more.
+
+⚠️ **These files ship twice, and both copies are load-bearing.** `tsc -p tsconfig.build.json` emits
+them into `dist/contract/` for the server, and the `files` whitelist ships `src/contract/` verbatim
+for the surface's own Vite build. A new file here needs neither entry changed — both are directory
+whitelists — but `bun run test:pack` installs the real tarball and names it if one of them stops
+arriving.
+
+## ⚠️ `nullable()` is not `optional()`, and the caller who confuses them reads the wrong sentence
+
+A field declared `nullable()` and not `optional()` is **required**: `null` is a value it takes, and
+leaving it out is refused. Both halves are deliberate wherever a write names the version it was made
+against — `SaveNodeVersionInput`, `SaveAttachmentInput`, `SaveFlowVersionInput`. `null` is the only
+way to write the first content of a node that has none, and the field stays required so that a
+caller who simply forgot it is refused instead of overwriting whatever somebody else wrote in
+between.
+
+⚠️ **The trap is not the rule, it is what the refusal says.** Zod answers a missing required field
+with `Invalid input: expected string, received undefined`, and to somebody holding a node created one
+call earlier that reads as "this field needs an id" — about a field that cannot have one yet. #437
+was opened as "the first version of a document cannot be set through the API" for exactly that
+reason, and it was never true: the caller had tried `undefined` and `""`, never `null`.
+
+**A required-nullable field therefore carries its own refusal**, one sentence naming both values it
+takes, on the schema in this package so that HTTP, MCP and the generated types all say it:
+
+```ts
+z.union([IntelId.min(1, { error: rule }), z.null()], { error: rule })
+```
+
+⚠️ **It is `baseVersion(rule)` in `contract.ts`, and all three writers take it** (#459). It lived
+beside the two node writers until the flow graph became the third — the point at which this
+repository stops copying and names the thing. `flow.ts` could not have imported it from `node.ts`
+anyway: the graph is `table → node`, `flow-run → flow`, and everything → `contract.ts`, so the move
+was the only shape that did not either break the graph or leave one sentence in two places to drift.
+
+⚠️ **The sentence says what the field TAKES, not what the caller did wrong.** It answers a wrong
+type as well as an absent field, and "is required" would be false about the first — the same kind of
+misdirection one corner further on. `baseVersionId takes the currentVersionId from node_get, or null
+when the node has no version yet — and it has to be sent.`
+
+The repeated `min(1)` adds no bound — it puts the sentence beside Zod's own `Too small` for the empty
+string, which is the second thing a caller tries after `undefined`. The JSON Schema it produces is
+the one `IntelId.nullable()` produced (`anyOf` of the string with its bounds and `null`, still
+`required`), so nothing on the MCP surface moves.
+
+⚠️ **Making the field `optional()` instead is the repair that breaks the guard.** An absent field
+would then have to mean "there is no version", and the forgetful caller silently replaces the newest
+one — the very overwrite the field exists to refuse.