@pvidaal07/heydb 2.0.0-beta.0 → 2.0.0-beta.1

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [2.0.0-beta.1]
+
+- Documentation, the bundled skill and tests use generic examples only.
+- Releases are published from GitHub Actions through npm trusted publishing.
+
 ## [2.0.0-beta.0]
 
 heydb is rebuilt from scratch in TypeScript as a [Pi](https://pi.dev) package. The Go CLI and MCP server (v1) are archived at tag `v1.3.1`.

package/README.md

@@ -11,10 +11,10 @@ It is a [Pi](https://pi.dev) package: Pi gets agent tools, slash commands and a
 
 ## Why
 
-On a legacy database the agent guesses. A table called `gar` "looks like" guarantees and turns out to hold the articles; `estado = 3` means something only the team knows; half the joins have no foreign key. heydb gives the agent the evidence instead of the name:
+On a legacy database the agent guesses. A table called `art` "looks like" artwork and turns out to hold the articles; `estado = 3` means something only the team knows; half the joins have no foreign key. heydb gives the agent the evidence instead of the name:
 
 - the structure, read-only and complete, with warnings for anything your privileges hide;
-- who references each table and how those columns are commented (`ref_gar` "Artículo" ×12 says more than the name `gar`);
+- who references each table and how those columns are commented (`ref_art` "Artículo" ×12 says more than the name `art`);
 - the notes your team and your agent saved, each with its author and its source.
 
 The agent is told to present inferences as inferences and ask before saving them.
@@ -45,7 +45,7 @@ Then just work: ask your agent about the database. It reads the snapshot with th
 
 | Engine | Tested in CI | Notes |
 |---|---|---|
-| MySQL | 8.0 | 5.7 used on a real 1,500-table ERP |
+| MySQL | 8.0 | 5.7 used on a schema with about 1,500 tables |
 | MariaDB | 10.6 | 10.2 or later expected |
 | PostgreSQL | 16 | 14 or later expected; one connection reaches one database, choose schemas inside it |
 
@@ -85,9 +85,9 @@ Notes saved by the agent are signed `<your git user.name> (via agent)` and end w
 
 After a sync, heydb looks for code in the project that uses the synced tables. It walks the folders, including ones git ignores (a reference copy of another repository, for example), and skips `node_modules`, `vendor`, build output, CI folders and lockfiles. It reads modern and legacy languages: PHP, TypeScript, JavaScript, Python, Java, C#, Go, Ruby, SQL, Kotlin, Scala, Harbour/Clipper, Delphi, Visual Basic, COBOL, ABL and RPG.
 
-A table only counts in database context: SQL with its statement verb (`SELECT … FROM gar`, `UPDATE gar … SET`, `INSERT INTO gar`), including SQL whose database prefix is built by code (`"FROM " + cEmp + ".gar"`), or a table declaration (`protected $table = 'gar'`, `cTabla := "gar"`, `@Table(name = "gar")`, `__tablename__`, `DB::table('gar')`…). A table called `config` is not matched by every comment that says "config".
+A table only counts in database context: SQL with its statement verb (`SELECT … FROM art`, `UPDATE art … SET`, `INSERT INTO art`), including SQL whose database prefix is built by code (`"FROM " + cDb + ".art"`), or a table declaration (`protected $table = 'art'`, `cTabla := "art"`, `@Table(name = "art")`, `__tablename__`, `DB::table('art')`…). A table called `config` is not matched by every comment that says "config".
 
-If it finds such code it asks first, because reading it costs tokens. The agent then notes only what the code makes explicit (valid values, units, joins without a foreign key), stops after about 20 notes and leaves what remains unclear as questions. `/heydb:learn-code eagle ../api-eagle` reads code that lives in another folder. The scan stops after 10 seconds or 50 MB on very large codebases.
+If it finds such code it asks first, because reading it costs tokens. The agent then notes only what the code makes explicit (valid values, units, joins without a foreign key), stops after about 20 notes and leaves what remains unclear as questions. `/heydb:learn-code acme ../legacy-app` reads code that lives in another folder. The scan stops after 10 seconds or 50 MB on very large codebases.
 
 Without such code, notes come from your conversations: tell the agent what a table means and it saves it.
 
@@ -95,8 +95,8 @@ Without such code, notes come from your conversations: tell the agent what a tab
 
 A project can have as many connections as it needs: `dev` and `prod`, or one per service. Commands and tools use the default unless you name one (`/heydb:sync prod`). Each connection has its own snapshot and notes.
 
-- **Across connections:** when `crm.clientes.cod_erp` holds codes of `erp`'s `gcl.cod`, the agent records it with `heydb_relate` and `to_connection: "erp"`, and `heydb_table gcl` on `erp` shows it.
-- **Project notes:** facts about the whole system ("one database per client; the central one is eagle") are saved with `scope: "project"` and shown first by `heydb_overview`.
+- **Across connections:** when `crm.clientes.cod_erp` holds codes of `erp`'s `cus.cod`, the agent records it with `heydb_relate` and `to_connection: "erp"`, and `heydb_table cus` on `erp` shows it.
+- **Project notes:** facts about the whole system ("one database per client; the central one is acme") are saved with `scope: "project"` and shown first by `heydb_overview`.
 - **Microservices:** give each service its own `.heydb/`; heydb uses the nearest one above the folder Pi runs in.
 
 ## Passwords
@@ -114,7 +114,7 @@ This keeps passwords out of git and out of the chat, not away from your own user
 | Path | Commit it? |
 |---|---|
 | `.heydb/config.json` | Yes: connections, with password references only |
-| `.heydb/snapshots/*.json.gz` | Yes: the schema, compressed (a 1,500-table ERP is about 470 KB) |
+| `.heydb/snapshots/*.json.gz` | Yes: the schema, compressed (a schema with about 1,500 tables is about 470 KB) |
 | `.heydb/knowledge/` | Yes: the team's notes and relationships |
 | `.heydb/.env` | Never: local passwords |
 
@@ -131,6 +131,10 @@ If your project's `.gitignore` excludes `.heydb/`, notes stay on your machine; h
 
 Ideas and bugs are welcome in [issues](https://github.com/pvidaal07/heydb/issues).
 
+## Contributing
+
+Contributions are welcome: open an issue, wait for `status:approved`, then fork and send a pull request to `main` that says `Closes #<issue>`. [CONTRIBUTING.md](CONTRIBUTING.md) explains the workflow, the setup and how the code is organized. Security problems go to a [private advisory](https://github.com/pvidaal07/heydb/security/advisories/new).
+
 ## Development
 
 ```sh
@@ -143,7 +147,7 @@ node --run db:down
 pi -e .                    # try the local copy in Pi
 ```
 
-Releases: bump `version` in `package.json`, add the entry to `CHANGELOG.md`, and push a tag `vX.Y.Z`; the publish workflow tests, publishes to npm and creates the GitHub release.
+Releases (maintainers): bump `version` in `package.json`, add the entry to `CHANGELOG.md`, merge, and push a tag `vX.Y.Z` on `main`; the publish workflow tests, stages the version on npm through trusted publishing and creates the GitHub release. The version becomes public once a maintainer approves it on npmjs.com (Staged Packages) with 2FA.
 
 ## License
 

package/extensions/commands.ts

@@ -430,7 +430,7 @@ interface CodeFolder {
 
 /**
  * Same offer as after a sync, from the stored snapshot: it never connects.
- * The code may live elsewhere (`/heydb:learn-code eagle ../api-eagle`); a
+ * The code may live elsewhere (`/heydb:learn-code acme ../legacy-app`); a
  * single argument that is not a connection but an existing folder is that
  * path, with the default connection.
  */

package/extensions/tools.ts

@@ -245,7 +245,7 @@ export function createRelateTool(deps: HeydbDeps): ToolDefinition<typeof RELATE_
 		promptSnippet: "Record a join between tables that has no foreign key",
 		promptGuidelines: [
 			"When you find tables joined without a foreign key (in code, queries or data), record it with heydb_relate and say how you know in the note.",
-			"When the referenced table is in another connection of the project (crm.clientes.cod_erp → erp's gcl.cod), call heydb_relate from the referencing connection with to_connection.",
+			"When the referenced table is in another connection of the project (crm.clientes.cod_erp → erp's cus.cod), call heydb_relate from the referencing connection with to_connection.",
 		],
 		parameters: RELATE_PARAMETERS,
 		executionMode: "sequential",

package/lib/knowledge/query.ts

@@ -59,7 +59,7 @@ export function knowledgeForTable(knowledge: Knowledge, tableName: string): Tabl
 /**
  * The relationships of a knowledge file that point to `table` of another
  * connection, `connection`: crm's file stores crm.clientes(cod_erp) → erp's
- * gcl(cod), and erp's gcl must show it.
+ * cus(cod), and erp's cus must show it.
  */
 export function relationshipsInto(knowledge: Knowledge, connection: string, table: string): Relationship[] {
 	const into = (side: RelationshipSide) => side.connection === connection && side.table === table;

package/lib/knowledge/types.ts

@@ -54,7 +54,7 @@ export interface Relationship {
 export interface RelationshipSide {
 	/**
 	 * The connection the table belongs to when it is not the one whose file
-	 * stores the relationship (crm.clientes.cod_erp → erp's gcl.cod). Absent
+	 * stores the relationship (crm.clientes.cod_erp → erp's cus.cod). Absent
 	 * means that connection, so files written before this field stay valid.
 	 */
 	readonly connection?: string;

package/lib/model/references.ts

@@ -3,13 +3,13 @@ import { formatName, type ObjectRef, parseName, parseSegments } from "./names.ts
 import type { Snapshot, Table } from "./snapshot.ts";
 
 // Who points to a table. In a legacy schema this is the strongest evidence of
-// what a table means: "gar" has no comment and looks like "garantías", but 500
-// columns elsewhere called ref_gar or id_gar say "Artículo" in their comments.
+// what a table means: "art" has no comment and looks like artwork, but 500
+// columns elsewhere called ref_art or id_art say "Artículo" in their comments.
 //
 // Three kinds of evidence, strongest first:
 // - declared foreign keys, enforced by the engine;
 // - implicit relationships the team documented (knowledge);
-// - name-pattern guesses: a column called ref_gar, id_gar, cod_gar, gar_id…
+// - name-pattern guesses: a column called ref_art, id_art, cod_art, art_id…
 //   in another table of the same database. Nothing enforces them, so they are
 //   always shown as guesses.
 //
@@ -155,9 +155,9 @@ export function incomingCounts(snapshot: Snapshot, knowledge: Knowledge): Map<st
 
 /**
  * The table names a column name may point to, lowercased: what comes before
- * or after any "_". ref_gar → ref, gar; cod_gar_ant → cod, cod_gar, gar_ant,
- * ant. So "gar" matches ref_gar, id_gar, cod_gar, gar_id and gar_precio as a
- * whole token, but never ref_garantia.
+ * or after any "_". ref_art → ref, art; cod_art_ant → cod, cod_art, art_ant,
+ * ant. So "art" matches ref_art, id_art, cod_art, art_id and art_precio as a
+ * whole token, but never ref_artista.
  */
 export function namePatternTargets(columnName: string): string[] {
 	const lower = columnName.toLowerCase();

package/lib/model/stats.ts

@@ -82,7 +82,7 @@ export function schemaStats(snapshot: Snapshot, knowledge: Knowledge, counts = i
 /**
  * The family a table name belongs to: the start of the name up to the first
  * "_" ("sii_fac" → "sii_") or digit ("log2020" → "log0-9"), lowercased. null
- * when there is no such start ("gcl", "_tmp", "2020_log").
+ * when there is no such start ("cus", "_tmp", "2020_log").
  */
 export function tablePrefix(name: string): string | null {
 	const match = /^([^_0-9]+)([_0-9])/.exec(name);

package/lib/render/markdown.ts

@@ -416,7 +416,7 @@ function implicitRelationship(relationship: Relationship, tableName: string, con
 	return `- ${left} → ${right} · implicit, documented by ${relationship.author}${note} [id ${relationship.id}${where} · ${day(relationship.createdAt)}]`;
 }
 
-/** "erp: erp.gcl(cod)" for a side in another connection than `current`, "shop.orders(id)" otherwise. */
+/** "erp: erp.cus(cod)" for a side in another connection than `current`, "shop.orders(id)" otherwise. */
 function sideText(side: RelationshipSide, current?: string): string {
 	const prefix = side.connection === undefined || side.connection === current ? "" : `${side.connection}: `;
 	return `${prefix}${displayText(side.table)}${list(side.columns)}`;

package/lib/search.ts

@@ -29,8 +29,8 @@ import type { Snapshot, Table } from "./model/snapshot.ts";
 // by its note (120 as a word, 30 inside one). A table name is also an exact
 // match when only a plural differs: "cliente" finds a table called clientes.
 //
-// Inferred meaning is how "cliente" finds gcl, a table without comment that
-// fifty columns called cod_gcl describe as "Cliente Habitual". It is evidence,
+// Inferred meaning is how "cliente" finds cus, a table without comment that
+// fifty columns called cod_cus describe as "Cliente Habitual". It is evidence,
 // not a fact: such results carry `inferred` so the agent says so. The
 // evidence is the summary heydb_table shows ("Referencing columns are
 // commented as", from incomingReferences), read for the MAX_INFERRED_TABLES
@@ -78,7 +78,7 @@ export interface SearchResults {
 
 export interface SearchOptions {
 	readonly limit?: number;
-	/** Only this database: "eagle", "eagle.eagle", or in PostgreSQL "app" or "app.public". */
+	/** Only this database: "acme", "acme.acme", or in PostgreSQL "app" or "app.public". */
 	readonly database?: string;
 }
 
@@ -150,7 +150,7 @@ export function searchSchema(snapshot: Snapshot, knowledge: Knowledge, query: st
 	};
 
 	// Per database, lowercased table name → canonical names: where a column
-	// named cod_gcl may point. Two entries when names differ only by case.
+	// named cod_cus may point. Two entries when names differ only by case.
 	const byName = new Map<string, Map<string, string[]>>();
 	const kinds = new Map<string, Table["kind"]>();
 	for (const database of snapshot.databases) {

package/lib/store/guards.ts

@@ -25,8 +25,8 @@ export function assertConnectionName(name: string): void {
 }
 
 /**
- * Turns what a person typed ("Eagle", "Prod EU", "Producción") into a name
- * assertConnectionName accepts ("eagle", "prod-eu", "produccion"), so the
+ * Turns what a person typed ("Acme", "Prod EU", "Producción") into a name
+ * assertConnectionName accepts ("acme", "prod-eu", "produccion"), so the
  * rule protects the files without getting in the user's way. Returns null
  * when nothing usable is left.
  */

package/lib/store/snapshots.ts

@@ -12,11 +12,12 @@ import { HEYDB_DIR } from "./project.ts";
 // Snapshots live in <project>/.heydb/snapshots/<connection>.json.gz and are
 // meant to be committed: teammates without database credentials still get the
 // schema. The content is the same stable JSON earlier builds wrote as plain
-// <connection>.json, gzip-compressed: a 1,500-table ERP was 395,460 lines of
-// JSON, which nobody reviews in a pull request. Reading decompresses on every
-// load: on 1,500 tables × 60 columns that is ~13 ms of the ~75 ms a load
-// takes (JSON.parse and validation are the rest), so a decompressed local
-// copy would save little and add a second file to keep in step.
+// <connection>.json, gzip-compressed: a schema with about 1,500 tables was
+// about 400,000 lines of JSON, which nobody reviews in a pull request.
+// Reading decompresses on every load: on 1,500 tables × 60 columns that is
+// ~13 ms of the ~75 ms a load takes (JSON.parse and validation are the rest),
+// so a decompressed local copy would save little and add a second file to
+// keep in step.
 
 const SUPPORTED_FORMAT_VERSION = 1;
 

package/lib/usecases/code-scan.ts

@@ -13,7 +13,7 @@ import { HEYDB_DIR } from "../store/project.ts";
 // and then the notes come from conversations instead.
 //
 // This only finds candidates: a table name in database context, that is SQL
-// (`SELECT … FROM gar`) or an ORM declaration (`protected $table = 'gar'`).
+// (`SELECT … FROM art`) or an ORM declaration (`protected $table = 'art'`).
 // A name that is only mentioned (a comment, help text, a variable) does not
 // count: tables called "config" or "para" are ordinary words. It never
 // interprets the code; the agent does that, if the person agrees. The scan runs right after a sync, so it is bounded in files,
@@ -36,7 +36,7 @@ export const DEFAULT_SCAN_LIMITS: ScanLimits = {
 	maxFiles: 5000,
 	maxBytes: 50 * 1024 * 1024,
 	maxFileBytes: 512 * 1024,
-	// A large legacy codebase (900 Harbour files) needs about 9 s; progress is shown meanwhile.
+	// A large legacy codebase (about 900 source files) needs about 9 s; progress is shown meanwhile.
 	maxMillis: 10_000,
 	maxTables: 300,
 };
@@ -124,9 +124,9 @@ export interface ScanOptions {
 }
 
 export interface TableUsage {
-	/** Display name, e.g. "erp.gar"; tables with the same name in several databases are joined with " / ". */
+	/** Display name, e.g. "erp.art"; tables with the same name in several databases are joined with " / ". */
 	readonly table: string;
-	/** The table name as the schema writes it, e.g. "gar". */
+	/** The table name as the schema writes it, e.g. "art". */
 	readonly name: string;
 	/** Files that use it most, at most 5. */
 	readonly files: readonly string[];
@@ -216,21 +216,21 @@ export async function findSchemaUsage(projectRoot: string, snapshot: Snapshot, o
 }
 
 // The patterns of database context. Each captures the table name as `name`:
-// a whole identifier (letters, digits, "_"), so "gar" never matches in
-// ref_gar or garage. Keywords are case-insensitive.
+// a whole identifier (letters, digits, "_"), so "art" never matches in
+// ref_art or article. Keywords are case-insensitive.
 
 const ID = "[\\p{L}\\p{N}_]+";
 /** A name as SQL writes it: optionally quoted (` " ' [ ]) and qualified (db.table, db.schema.table). */
 const SQL_NAME = `(?:[\`"'\\[]?${ID}[\`"'\\]]?\\.){0,2}[\`"'\\[]?(?<name>${ID})(?![\\p{L}\\p{N}_])`;
 /**
  * A database prefix built by code in front of the table, as legacy and web
- * code often write it: "FROM "+cEmp+".gar" (Harbour, JS), "FROM " . $db . ".gar"
- * (PHP), `FROM ${db}.gar` (template strings). Bounded, so it stays cheap.
+ * code often write it: "FROM "+cDb+".art" (Harbour, JS), "FROM " . $db . ".art"
+ * (PHP), `FROM ${db}.art` (template strings). Bounded, so it stays cheap.
  */
 const BUILT_PREFIX = `(?:["'\`]\\s*(?:\\+|\\.|&|\\|\\|)\\s*[^"'\`\\n]{1,60}?\\s*(?:\\+|\\.|&|\\|\\|)\\s*["'\`]\\.|\\$\\{[^}\\n]{1,60}\\}\\.)`;
 /** A table name after a SQL keyword: plain, quoted or qualified, or behind a built prefix. */
 const SQL_TARGET = `(?:${BUILT_PREFIX})?${SQL_NAME}`;
-/** A quoted string that holds only the name: 'gar', "gar", `gar`. */
+/** A quoted string that holds only the name: 'art', "art", `art`. */
 const QUOTED_NAME = `["'\`](?<name>${ID})["'\`]`;
 /** How far back, within one statement (no ";"), the verb that opens it may be. */
 const STATEMENT_CHARS = 2000;
@@ -257,7 +257,7 @@ const STATEMENT_CHARS = 2000;
  * A keyword match plus the context it needs. The keyword is searched first and
  * the context is checked only around each match, in a bounded window cut at
  * the statement end (";"). A lookbehind such as (?<=SELECT[^;]{0,2000}?) would
- * be tried at every position of the file: on a real 500 KB Harbour source that
+ * be tried at every position of the file: on a 500 KB legacy source file that
  * meant minutes per file.
  */
 interface ReferenceRule {
@@ -368,9 +368,9 @@ function tableNames(snapshot: Snapshot, maxTables: number): Map<string, TableNam
  */
 // The folders are walked directly, never listed through git: the code that
 // uses a database is often a reference copy kept in a folder the project's
-// .gitignore excludes (found on a real ERP: source-code/), and git would hide
-// it. Generated and third-party folders are skipped by name, and the walk is
-// bounded by the file and time limits.
+// .gitignore excludes, and git would hide it. Generated and third-party
+// folders are skipped by name, and the walk is bounded by the file and time
+// limits.
 async function listSources(
 	files: CodeFiles,
 	maxFiles: number,

package/lib/usecases/knowledge.ts

@@ -43,7 +43,7 @@ import { loadSnapshot } from "../store/snapshots.ts";
 // corrected or forgotten after a column is dropped.
 //
 // A relationship may cross connections (crm.clientes.cod_erp → erp's
-// gcl.cod). It is stored in the file of its "from" connection, and its "to"
+// cus.cod). It is stored in the file of its "from" connection, and its "to"
 // side names the other connection and is checked against that snapshot.
 
 export function annotate(

package/lib/usecases/project.ts

@@ -314,9 +314,9 @@ export type TargetKind = "database" | "table" | "column";
  * every reading is tried, and the target must be exactly one object.
  *
  * A name without a dot is a table (or a database), never a column when one
- * of those matches: in a legacy ERP the articles table "gar" shares its name
- * with a column postv.gar, and "gar" must still name the table. A column then
- * needs its table: "postv.gar". Errors use display names.
+ * of those matches: in a legacy schema the articles table "art" shares its name
+ * with a column pos.art, and "art" must still name the table. A column then
+ * needs its table: "pos.art". Errors use display names.
  */
 export function resolveTarget(snapshot: Snapshot, input: string): { kind: TargetKind; name: string } {
 	const segments = parseSegments(input);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pvidaal07/heydb",
-	"version": "2.0.0-beta.0",
+	"version": "2.0.0-beta.1",
 	"description": "Database schema context for AI agents: introspect MySQL, MariaDB and PostgreSQL, keep a local snapshot, and share annotated knowledge through git.",
 	"license": "MIT",
 	"author": "pvidaal07",

package/skills/heydb/SKILL.md

@@ -10,17 +10,17 @@ heydb keeps a snapshot of the project's database structure (`.heydb/snapshots/`)
 ## Read before you write SQL
 
 1. Unknown schema: `heydb_overview` once. It shows, per database, how many tables have comments and which tables the rest point to (the core).
-2. Looking for a concept ("invoices", "fecha de baja"): `heydb_search`. It ignores case, accents and simple plurals, lists tables (with their matching columns) before anything else, and can keep to one `database`. Results also include tables whose meaning is inferred from the columns that reference them, marked `(inferred)`: `gcl` has no comment, but columns pointing to it say "Cliente Habitual". Present those as inferences, never as facts.
+2. Looking for a concept ("invoices", "fecha de baja"): `heydb_search`. It ignores case, accents and simple plurals, lists tables (with their matching columns) before anything else, and can keep to one `database`. Results also include tables whose meaning is inferred from the columns that reference them, marked `(inferred)`: `cus` has no comment, but columns pointing to it say "Cliente Habitual". Present those as inferences, never as facts.
 3. Before using a table: `heydb_table`. Use the real column names, types and joins it shows, including implicit relationships and notes. On wide tables it lists the 60 most telling columns; ask for `columns: "all"` or a `column_filter` when you need the rest.
 
 Never guess table or column names from memory when heydb can answer.
 
 ## Never guess a meaning from a table name
 
-Legacy names lie. In one ERP, `gar` looked like "garantías"; it holds the articles. Before you say what a table is, read the `heydb_table` header, strongest evidence first:
+Legacy names lie. A table named `art` looks like artwork; it holds the articles. Before you say what a table is, read the `heydb_table` header, strongest evidence first:
 
 1. Team notes and the table comment.
-2. Who points to it ("Referenced by"): foreign keys, documented relationships and the comments of columns like `ref_gar`, `cod_gar`. `Referencing columns are commented as: "Artículo" ×12` is strong evidence. Name-pattern guesses are not enforced; treat them as clues.
+2. Who points to it ("Referenced by"): foreign keys, documented relationships and the comments of columns like `ref_art`, `cod_art`. `Referencing columns are commented as: "Artículo" ×12` is strong evidence. Name-pattern guesses are not enforced; treat them as clues.
 3. Its own columns.
 
 When the meaning comes from 2 or 3, say it is an inference and ask the user to confirm. Once confirmed, save it with `heydb_annotate` so nobody has to guess again. When the overview says most tables have no comment, do not infer anything from names alone.
@@ -39,9 +39,9 @@ When the conversation or the code teaches you something the schema does not say,
 
 - `heydb_annotate` for meaning: valid values, units, encodings, who writes the column, legacy quirks.
 - `heydb_relate` for joins without a foreign key: `orders.customer_id → customers.id`. Say how you know in `note`.
-- `heydb_annotate` with `scope: "project"` and no `target` for facts above any one database: "the ERP uses one database per client; the central one is eagle". `heydb_overview` shows them first. A table called `project` is still `target: "project"`.
-- `heydb_relate` with `to_connection` when the referenced table is in another connection of the project (`crm.clientes.cod_erp → erp`'s `gcl.cod`). Call it from the referencing connection; `heydb_table` on the other side shows it too, prefixed with the connection.
-- A name without a dot is a table: `heydb_annotate` with `gar` notes the table even if some column is also called `gar`; write `postv.gar` for the column.
+- `heydb_annotate` with `scope: "project"` and no `target` for facts above any one database: "the ERP uses one database per client; the central one is acme". `heydb_overview` shows them first. A table called `project` is still `target: "project"`.
+- `heydb_relate` with `to_connection` when the referenced table is in another connection of the project (`crm.clientes.cod_erp → erp`'s `cus.cod`). Call it from the referencing connection; `heydb_table` on the other side shows it too, prefixed with the connection.
+- A name without a dot is a table: `heydb_annotate` with `art` notes the table even if some column is also called `art`; write `pos.art` for the column.
 - If the save result says git ignores the notes, tell the user: the note stays on their machine until the project shares `.heydb/knowledge/`.
 - End every note with its source: `(code: src/Models/Order.php)` when code shows it, `(told by the user)` when the user said it. An inference is saved only after the user confirms it.
 - After `/heydb:sync` (or `/heydb:learn-code`) the user may ask you to read the project's code: follow the rules in that message and stop after about 20 notes.