From a70f17d06ae7f74127527c3facd9f619db54ef97 Mon Sep 17 00:00:00 2001
From: Eddie A Tejeda <669988+eddietejeda@users.noreply.github.com>
Date: Sun, 2 Aug 2026 11:25:21 -0700
Subject: [PATCH] refactor: replace user-facing "connection" with "catalog"
 (keep wire contract)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

"Connection" was overloaded in the user-facing surface: it named the
attachable/queryable thing (`databases attach`, cross-source joins), duplicated
the ingest "datasource" concept in stale comments, and even appeared as a
`hotdata connections list` command that does not exist. A connection is a
distinct server concept from a datasource, so the fix is to rename what users
see to "catalog" (how it's already addressed in SQL: `<catalog>.schema.table`,
and via `--catalog`/`--alias`) — not to "datasource".

Scope is user-facing only. The wire contract is untouched: `/connections/...`
endpoints, the `connection_id`/`default_connection_id` JSON keys, the
`data_refresh_connection` job-type value (still shown/typed in `jobs --job-type`
because the server defines it), and `connection_string` credential keys all stay.
Internal identifiers and private-fn rustdoc that say "connection" are left as-is
(they track the wire concept).

CLI (user-facing):
- `databases attach`/`detach`: help, printed output, and the positional arg
  (`<CONNECTION>` -> `<CATALOG>`); `create --attach` help; `fork` help.
- `databases delete` arg help; `databases show` label `default_connection_id:`
  -> `catalog id:` (the `-o json` key is unchanged).
- `indexes delete --catalog` help note; two `query` cross-catalog hints (one had
  pointed at the non-existent `hotdata connections list`).
- Removed the deprecated hidden `ingest *-connection` aliases; corrected the
  ingest-client comments that called a datasource a "connection".

Skills:
- Renamed "connection" -> "catalog" throughout (attach, cross-catalog joins,
  data-model template); renamed the "Querying across connections" anchor to
  "-catalogs-" and updated all links.
- Corrected the earlier connections->datasources mis-mapping: onboarding /
  model-building now discover queryable catalogs+tables (`databases list`,
  `tables list`), with ingest datasources as a separate optional step.
---
 skills/hotdata/SKILL.md                       | 33 ++++++------
 .../hotdata/references/DATA_MODEL.template.md | 16 +++---
 skills/hotdata/references/MODEL_BUILD.md      | 29 ++++++-----
 skills/hotdata/references/WORKFLOWS.md        | 31 ++++++-----
 skills/hotdata/subskills/analytics/SKILL.md   |  6 +--
 skills/hotdata/subskills/geospatial/SKILL.md  |  2 +-
 skills/hotdata/subskills/search/SKILL.md      |  6 +--
 .../subskills/search/references/INDEXES.md    | 10 ++--
 src/client/ingest.rs                          | 16 +++---
 src/commands/databases.rs                     | 52 +++++++++----------
 src/commands/indexes.rs                       |  2 +-
 src/commands/ingest.rs                        |  4 --
 src/commands/query.rs                         | 10 ++--
 src/main.rs                                   | 11 ++--
 tests/databases_cli.rs                        |  8 +--
 15 files changed, 116 insertions(+), 120 deletions(-)

diff --git a/skills/hotdata/SKILL.md b/skills/hotdata/SKILL.md
index ee8b70f..515998c 100644
--- a/skills/hotdata/SKILL.md
+++ b/skills/hotdata/SKILL.md
@@ -59,7 +59,7 @@ A workspace's query worker scales to zero after inactivity. The **first** comman
 
 **Agents — list before show.** Run `hotdata context list` (optionally `--prefix DATAMODEL`) first; run `hotdata context show DATAMODEL` *only if* the stem is listed. A missing stem makes `show` exit 1 — normal for a fresh database, not a failure: don't retry in a loop or run speculative `show` in parallel with other tools. Proceed without context:DATAMODEL until one exists.
 
-**context:DATAMODEL is the durable, shared store** — entities, keys, cross-connection joins, and the naming/query conventions the whole team relies on. Keep task-scoped exploration (scratch SQL, hypotheses, one-off join checks) in the conversation or local notes; **promote** to context:DATAMODEL only when findings should outlive the session and guide everyone — reconcile against `context show DATAMODEL` (if listed), write `./DATAMODEL.md`, then `hotdata context push DATAMODEL`. No need to update it after every ad-hoc query. What to write inside the document: [references/DATA_MODEL.template.md](references/DATA_MODEL.template.md) and [references/MODEL_BUILD.md](references/MODEL_BUILD.md).
+**context:DATAMODEL is the durable, shared store** — entities, keys, cross-catalog joins, and the naming/query conventions the whole team relies on. Keep task-scoped exploration (scratch SQL, hypotheses, one-off join checks) in the conversation or local notes; **promote** to context:DATAMODEL only when findings should outlive the session and guide everyone — reconcile against `context show DATAMODEL` (if listed), write `./DATAMODEL.md`, then `hotdata context push DATAMODEL`. No need to update it after every ad-hoc query. What to write inside the document: [references/DATA_MODEL.template.md](references/DATA_MODEL.template.md) and [references/MODEL_BUILD.md](references/MODEL_BUILD.md).
 
 ## Multi-step workflows
 
@@ -104,9 +104,9 @@ hotdata databases delete <id> [--workspace-id <workspace_id>]
 hotdata databases run [--database <id>] [--name <label>] [--schema public] [--table <table> ...] [--expires-at <duration|timestamp>] [--workspace-id <workspace_id>] <cmd> [args...]
 hotdata databases <id> run <cmd> [args...]
 
-# Attach a connection as a queryable catalog (enables cross-source queries — see below)
-hotdata databases attach <connection_id|name> [--database <id>] [--alias <alias>]
-hotdata databases detach <connection_id|name|alias> [--database <id>]
+# Attach a catalog so its tables are queryable (enables cross-catalog queries — see below)
+hotdata databases attach <catalog|name> [--database <id>] [--alias <alias>]
+hotdata databases detach <catalog|name|alias> [--database <id>]
 
 # Preferred: load by catalog alias (auto-declares table if needed)
 hotdata databases load --catalog <alias> --table <table> [--schema public] (--file <path> | --url <url> | --upload-id <id> | --result-id <id>) [--workspace-id <workspace_id>]
@@ -119,7 +119,7 @@ hotdata databases tables delete <table> [--database <id>] [--schema public] [--w
 
 - `list` — all managed databases in the workspace. Active database is marked with `*` under the DEFAULT column; CREATED shows when each database was made.
 - `create` — creates a new managed database. `--name` is an optional human-readable display name. `--catalog` sets the SQL alias used in queries (`SELECT … FROM <catalog>.schema.table`); must be `[a-z_][a-z0-9_]*`. `--expires-at` accepts relative durations (`24h`, `7d`, `90m`) or an RFC 3339 timestamp; omitting means no expiry. Repeat `--table` to declare tables up front.
-- `fork` — creates a new managed database that is an independent deep copy of an existing one (same schemas, tables, and data); the source is left unchanged and the two diverge freely afterwards. The source defaults to the active database; pass the database `<id>` to fork another. `--name` defaults to `<source>-fork` (so the two stay distinguishable in `list`); `--expires-at` accepts a relative duration or RFC 3339 timestamp, and when omitted a still-future source expiry is carried over. The fork becomes the active database on success. The fork answers to the **same catalog alias** as its source inside its own scope; connection catalogs attached to the source are **re-attached** to the fork, but indexes are **not** carried over. Only databases created with the current (DuckLake) storage engine can be forked — older parquet-backed databases return an error.
+- `fork` — creates a new managed database that is an independent deep copy of an existing one (same schemas, tables, and data); the source is left unchanged and the two diverge freely afterwards. The source defaults to the active database; pass the database `<id>` to fork another. `--name` defaults to `<source>-fork` (so the two stay distinguishable in `list`); `--expires-at` accepts a relative duration or RFC 3339 timestamp, and when omitted a still-future source expiry is carried over. The fork becomes the active database on success. The fork answers to the **same catalog alias** as its source inside its own scope; catalogs attached to the source are **re-attached** to the fork, but indexes are **not** carried over. Only databases created with the current (DuckLake) storage engine can be forked — older parquet-backed databases return an error.
 - `set` — saves the database **id** as the active database. Subsequent `databases tables` and `context` commands use it automatically. Note that a successful `fork` also updates this: the fork becomes the active database.
 - `unset` — clears the active database from config.
 - `<id>` — inspect one database (returns id, catalog, name, expires_at).
@@ -129,9 +129,9 @@ hotdata databases tables delete <table> [--database <id>] [--schema public] [--w
 - `tables load` — publishes to a managed-database table (with **replace** mode) from a local parquet file (`--file`), a remote parquet URL (`--url`), a pre-staged upload (`--upload-id`), or a saved query result (`--result-id`, must belong to the target database).
 - `tables delete` — drops a table from the managed database.
 - `run` — mints a database-scoped JWT (via `POST /v1/auth/database`) and execs `<cmd>` with `HOTDATA_DATABASE_TOKEN`, `HOTDATA_DATABASE_REFRESH_TOKEN`, `HOTDATA_DATABASE`, `HOTDATA_WORKSPACE`, and `HOTDATA_API_URL` injected. Pass a database id as a group positional (`hotdata databases <id> run ...`) or via `--database <id>`; omit both to auto-create a scratch database using `--name` / `--schema` / `--table` / `--expires-at`. Use this to launch an agent or child process whose API access is scoped to a single database. The minted JWT carries `database`, `workspaces`, `permissions:["read","write"]`, and `source:"database_token"` — read+write within the token's workspace, with that database as the default query scope. The child `hotdata` (or any tool) picks the token up from `HOTDATA_DATABASE_TOKEN`. The session is persisted at `~/.hotdata/database_session.json` (mode `0600`); the child's exit code is propagated.
-- `attach` — attaches a **connection** as a queryable catalog on a managed database, so the connection's **live** tables become visible inside that database's query scope. Defaults to the active database; target another with `--database`. `--alias` sets the SQL name the catalog answers to (defaults to the connection's name). This is how you query connection tables and **join across sources** — see [Querying across connections](#querying-across-connections-attach).
-- `detach` — removes an attached connection catalog. Accepts the connection name/id **or** the alias you attached it under. Defaults to the active database.
-- `create --attach <connection>[=<alias>]` — attach one or more connections at creation time (repeatable), e.g. `--attach github --attach salesdb=sales`.
+- `attach` — attaches a **catalog** to a managed database, so the catalog's **live** tables become visible inside that database's query scope. Defaults to the active database; target another with `--database`. `--alias` sets the SQL name the catalog answers to (defaults to the catalog's name). This is how you query an attached catalog's tables and **join across catalogs** — see [Querying across catalogs](#querying-across-catalogs-attach).
+- `detach` — removes an attached catalog. Accepts the catalog name/id **or** the alias you attached it under. Defaults to the active database.
+- `create --attach <catalog>[=<alias>]` — attach one or more catalogs at creation time (repeatable), e.g. `--attach github --attach salesdb=sales`.
 
 Example:
 
@@ -141,20 +141,20 @@ hotdata databases load --catalog airbnb --table listings --url https://example.c
 hotdata query "SELECT count(*) FROM airbnb.public.listings"
 ```
 
-#### Querying across connections (attach)
+#### Querying across catalogs (attach)
 
-**A `hotdata query` runs inside exactly one managed database** — the active database (`hotdata databases set <id>`) or the one named by `--database`. With none set, the query fails with *"a database is required."* That database's query scope sees **only its own catalog plus any connection catalogs explicitly attached to it** — a workspace connection is **not** visible just because it exists. Referencing an unattached connection fails with *"table '\<catalog\>.\<schema\>.\<table\>' not found."*
+**A `hotdata query` runs inside exactly one managed database** — the active database (`hotdata databases set <id>`) or the one named by `--database`. With none set, the query fails with *"a database is required."* That database's query scope sees **only its own catalog plus any catalogs explicitly attached to it** — a workspace catalog is **not** visible just because it exists. Referencing an unattached catalog fails with *"table '\<catalog\>.\<schema\>.\<table\>' not found."*
 
-To query a connection's tables, or **join a managed table against a connection table in one query**, attach the connection to the database first. The connection's data stays **live** (synced) — this is not a copy:
+To query an attached catalog's tables, or **join a managed table against an attached catalog's table in one query**, attach the catalog to the database first. The catalog's data stays **live** (synced) — this is not a copy:
 
 ```
-# Attach the 'github' connection (live) to the active database under alias 'gh'
+# Attach the 'github' catalog (live) to the active database under alias 'gh'
 hotdata databases attach github --alias gh
 
-# Now both the database's own tables and the attached connection are in scope:
+# Now both the database's own tables and the attached catalog are in scope:
 hotdata query "SELECT * FROM gh.github.issues WHERE state = 'OPEN' LIMIT 10"
 
-# Cross-source join: a managed table JOINed against the live connection table
+# Cross-catalog join: a managed table JOINed against the live attached-catalog table
 hotdata query "
   SELECT t.id, i.title
   FROM mycatalog.public.tickets t
@@ -164,7 +164,7 @@ hotdata query "
 hotdata databases detach gh   # when finished (optional)
 ```
 
-Without `--alias`, the catalog answers to the connection's own name (`github.github.issues`). Do **not** export a connection to parquet just to query it — attach is the live, sync-preserving path.
+Without `--alias`, the catalog answers to its own name (`github.github.issues`). Do **not** export a catalog to parquet just to query it — attach is the live, sync-preserving path.
 
 ### Tables
 
@@ -213,7 +213,7 @@ hotdata query status <query_run_id>
 ```
 
 - Default output is `table` (row count and execution time).
-- **A query runs inside one managed database** (active database or `--database`); with none set it fails *"a database is required."* The scope sees the database's own catalog **plus any attached connection catalogs only**. To query a connection's tables or join across sources, attach the connection first — see [Querying across connections (attach)](#querying-across-connections-attach).
+- **A query runs inside one managed database** (active database or `--database`); with none set it fails *"a database is required."* The scope sees the database's own catalog **plus any attached catalogs only**. To query an attached catalog's tables or join across catalogs, attach the catalog first — see [Querying across catalogs (attach)](#querying-across-catalogs-attach).
 - Use `hotdata tables list` and `hotdata tables show` for discovery — not `information_schema` via `query`. (Discovery lists every workspace table; queryability still requires the table's catalog to be in the active database's scope.)
 - **PostgreSQL dialect.** Quote non-lowercase columns with double quotes.
 - Async runs return `query_run_id` → poll with `query status <id>` (do not re-run the same heavy SQL). `query status` exit codes: `0` succeeded, `1` failed, `2` still running (poll again), `3` succeeded but the result is a truncated/incomplete preview.
@@ -291,7 +291,6 @@ Agent tips:
 - Tables print oldest→newest; `-o json` is newest-first (`[0]` = latest).
 - Once an import is `done`, its database is a regular managed DB: query it with `hotdata query --database <db-id> "SELECT … FROM public.<table>"`.
 - Table names per type: `buckets` datasources expose one table named `files` (`FROM <name>` or `FROM <name>.files`); iceberg tables are addressed by the exact onboarded name (`FROM ice."ns.orders"`), the underscored form (`FROM ice.ns_orders`), or the bare table name — `show-datasource` lists what was discovered.
-- The pre-0.14 `*-connection` verbs still work as hidden aliases of the `*-datasource` ones.
 
 ### Usage
 ```
diff --git a/skills/hotdata/references/DATA_MODEL.template.md b/skills/hotdata/references/DATA_MODEL.template.md
index 99c2547..db539a5 100644
--- a/skills/hotdata/references/DATA_MODEL.template.md
+++ b/skills/hotdata/references/DATA_MODEL.template.md
@@ -10,15 +10,15 @@
 ## Overview
 
 What data exists, which business domains it covers, and who owns this document.  
-_(Large workspaces: add a **table of contents** here—per connection, table counts.)_
+_(Large workspaces: add a **table of contents** here—per catalog, table counts.)_
 
 ## Purpose
 
 Short description of what this workspace is for and how the model should be used for queries.
 
-## Connections & sources
+## Catalogs & sources
 
-| Connection ID | Name | Type | Role / domain |
+| Catalog ID | Name | Type | Role / domain |
 |---------------|------|------|---------------|
 | | | | |
 
@@ -26,7 +26,7 @@ Short description of what this workspace is for and how the model should be used
 
 _Use for important tables only, or expand all via [MODEL_BUILD.md](MODEL_BUILD.md). **Duplicate** this whole block (from the heading through the horizontal rule) for each table._
 
-#### `<connection>.<schema>.<table>`
+#### `<catalog>.<schema>.<table>`
 
 **Grain:** one row = one `…`  
 **Description:**  
@@ -45,14 +45,14 @@ For each business entity:
 
 - **Entity:**  
 - **Grain:** one row per …  
-- **Primary tables:** `connection.schema.table`  
+- **Primary tables:** `catalog.schema.table`  
 - **Key columns:**  
 
-## Cross-connection joins
+## Cross-catalog joins
 
 Document safe join paths and caveats (fan-out, timing, different refresh cadence, type mismatches).
 
-> A cross-connection join runs inside one managed database; each connection it touches must be **attached** to that database (`hotdata databases attach <connection>`) so its live tables are in query scope. Note here which connections a join requires attached, and the alias each is attached under. See **`hotdata`** skill → Querying across connections.
+> A cross-catalog join runs inside one managed database; each catalog it touches must be **attached** to that database (`hotdata databases attach <catalog>`) so its live tables are in query scope. Note here which catalogs a join requires attached, and the alias each is attached under. See **`hotdata`** skill → Querying across catalogs.
 
 ## Search & index summary (optional)
 
@@ -60,7 +60,7 @@ Document safe join paths and caveats (fan-out, timing, different refresh cadence
 |-------|--------|--------------------------|--------------|-------|
 | | | | | |
 
-_Use `hotdata indexes list` (no flags — covers connection tables **and** managed databases; see **hotdata-search** skill). Record bm25/vector indexes here; sorted indexes for OLAP filters in **hotdata-analytics**._
+_Use `hotdata indexes list` (no flags — covers catalog tables **and** managed databases; see **hotdata-search** skill). Record bm25/vector indexes here; sorted indexes for OLAP filters in **hotdata-analytics**._
 
 ## Managed databases (uploaded)
 
diff --git a/skills/hotdata/references/MODEL_BUILD.md b/skills/hotdata/references/MODEL_BUILD.md
index 9acd0d1..1580143 100644
--- a/skills/hotdata/references/MODEL_BUILD.md
+++ b/skills/hotdata/references/MODEL_BUILD.md
@@ -8,13 +8,16 @@ Optional **deep pass** for a single authoritative markdown document stored as **
 
 ---
 
-## 1. Discover datasources
+## 1. Discover catalogs and tables
+
+List the catalogs you can query — managed databases you own and any attached catalogs — and the tables they expose:
 
 ```bash
-hotdata ingest list-datasources
+hotdata databases list       # managed databases (catalogs you own)
+hotdata tables list          # every workspace table, as <catalog>.<schema>.<table>
 ```
 
-For each datasource, record `id`, `name`, and `source_type`.
+For each catalog, record its name and the tables it exposes. (Pulling *new* external data into a managed database is a separate step — see the `ingest` datasource commands in the core skill.)
 
 ---
 
@@ -58,7 +61,7 @@ Use **connector and tooling docs** when `source_type` (or table shapes) match:
 Do **not** invent facts: if **context:DATAMODEL** (or needed facts) is missing, say so and suggest a small sample query:
 
 ```bash
-hotdata query "SELECT * FROM <connection>.<schema>.<table> LIMIT 5"
+hotdata query "SELECT * FROM <catalog>.<schema>.<table> LIMIT 5"
 ```
 
 ---
@@ -71,7 +74,7 @@ For each table, capture where reasonable:
 2. **Primary keys** — `id`, `<entity>_id`, or composite patterns from names + types.
 3. **Foreign keys** — `_id` / `_fk` / name matches to other tables; confirm with connector docs when possible.
 4. **Parent–child** — Flattened API/JSON tables (often nested names) and dlt parent keys.
-5. **Cross-connection** — Same logical entity in two connections (keys, type mismatches, caveats).
+5. **Cross-catalog** — Same logical entity in two catalogs (keys, type mismatches, caveats).
 
 For **small** schemas (e.g. ≤5 tables in a domain), a short **ASCII diagram** helps. For larger ones, group by domain in prose (e.g. billing, identity, product).
 
@@ -100,7 +103,7 @@ Note:
 - **Time** columns — event grain vs slowly changing dimensions.
 - **Facts vs dimensions** — for analytics-oriented workspaces.
 
-When suggesting a new index, use the same connection/schema/table/column names as in `tables list` and **`hotdata-search`** / **`hotdata-analytics`** `indexes create` examples (bm25/vector vs sorted).
+When suggesting a new index, use the same catalog/schema/table/column names as in `tables list` and **`hotdata-search`** / **`hotdata-analytics`** `indexes create` examples (bm25/vector vs sorted).
 
 ---
 
@@ -109,20 +112,20 @@ When suggesting a new index, use the same connection/schema/table/column names a
 This Markdown body is what you store as **context:DATAMODEL** (`hotdata context push DATAMODEL`). Start from [DATA_MODEL.template.md](DATA_MODEL.template.md) and extend as needed:
 
 - **Overview** — Domains and what the workspace is for.
-- **Per connection** — Optional subsection per source; for **deep** models, **repeat** one block per `connection.schema.table` (grain, column table with name/type/nullable/PK-FK/notes, relationships, queryability, caveats)—the template’s single `####` heading is a pattern to copy for each table.
-- **Managed databases** — Same treatment as connection tables where relevant.
-- **Cross-connection joins** — Keys, semantics, type caveats.
+- **Per catalog** — Optional subsection per source; for **deep** models, **repeat** one block per `catalog.schema.table` (grain, column table with name/type/nullable/PK-FK/notes, relationships, queryability, caveats)—the template’s single `####` heading is a pattern to copy for each table.
+- **Managed databases** — Same treatment as catalog tables where relevant.
+- **Cross-catalog joins** — Keys, semantics, type caveats.
 - **Search / index summary** — Table, column, index status, intended use.
 
-If the workspace has **many** tables (e.g. 50+), add a **table of contents** after the overview (connection → table counts).
+If the workspace has **many** tables (e.g. 50+), add a **table of contents** after the overview (catalog → table counts).
 
 ---
 
 ## Error handling
 
 - If a CLI command fails, record the error in the doc and **continue** when possible.
-- Unreachable connections or empty table lists: note in the connections table (e.g. unreachable / no tables).
-- Do not abort the whole model for one bad connection.
+- Unreachable catalogs or empty table lists: note in the catalogs table (e.g. unreachable / no tables).
+- Do not abort the whole model for one bad catalog.
 
 ---
 
@@ -133,4 +136,4 @@ If the workspace has **many** tables (e.g. 50+), add a **table of contents** aft
 - Flag **test/dev** tables (`test`, `tmp`, `dev`, `staging` in names) as non-production when applicable.
 - Note **Utf8-stored numbers** and cast requirements where relevant.
 - Do not leave column **Notes** empty when domain knowledge or docs apply; “—” is weak unless the column is opaque/internal.
-- Align table names with **`hotdata tables list`** output (`connection.schema.table`).
+- Align table names with **`hotdata tables list`** output (`catalog.schema.table`).
diff --git a/skills/hotdata/references/WORKFLOWS.md b/skills/hotdata/references/WORKFLOWS.md
index d9fdf89..fec3199 100644
--- a/skills/hotdata/references/WORKFLOWS.md
+++ b/skills/hotdata/references/WORKFLOWS.md
@@ -36,12 +36,11 @@ End-to-end checklists. Use the linked sections for command detail and guardrails
 
 1. [ ] `hotdata auth login`
 2. [ ] `hotdata workspaces list` → `hotdata workspaces set` if not on the right workspace
-3. [ ] `hotdata ingest list-datasources` — note datasource ids and names
-4. [ ] (Optional) `hotdata ingest new-datasource --service <type>` — add a datasource (see **`hotdata`** skill → **Ingest external data**)
-5. [ ] `hotdata ingest show-datasource <datasource_id>` to re-check discovered tables/columns if the source schema may have changed
-6. [ ] `hotdata tables list` (add `--schema`/`--table` filters to narrow) and `hotdata tables show <table>` for columns
-7. [ ] (Optional) `hotdata context list` — if `DATAMODEL` is listed, `hotdata context show DATAMODEL`; else skip `show`
-8. [ ] (Optional) Bootstrap **context:DATAMODEL** — [Model](#model), [DATA_MODEL.template.md](DATA_MODEL.template.md)
+3. [ ] `hotdata databases list` and `hotdata tables list` — see the catalogs and tables you can query (tables print as `<catalog>.<schema>.<table>`)
+4. [ ] `hotdata tables show <table>` for columns (add `--schema`/`--table` filters to `tables list` to narrow)
+5. [ ] (Optional, to pull external data) `hotdata ingest list-datasources`; add one with `hotdata ingest new-datasource --service <type>`, then re-check its discovered schema with `hotdata ingest show-datasource <datasource_id>` — see **`hotdata`** skill → **Ingest external data**
+6. [ ] (Optional) `hotdata context list` — if `DATAMODEL` is listed, `hotdata context show DATAMODEL`; else skip `show`
+7. [ ] (Optional) Bootstrap **context:DATAMODEL** — [Model](#model), [DATA_MODEL.template.md](DATA_MODEL.template.md)
 
 **Next:** upload data ([Managed databases](#managed-databases)) or run analytics (**Chain** below).
 
@@ -65,7 +64,7 @@ End-to-end checklists. Use the linked sections for command detail and guardrails
 2. [ ] `hotdata indexes list` — avoid duplicate bm25/vector indexes on the same column
 3. [ ] Create index:
    - [ ] **Managed DB:** `hotdata indexes create --catalog <alias> --table <tbl> --column <text_col> --type bm25|vector`
-   - [ ] **Connection:** `hotdata indexes create --catalog <connection-name-or-id> --schema <s> --table <t> --column <col> --type bm25|vector [--metric cosine|l2|dot]`
+   - [ ] **Catalog:** `hotdata indexes create --catalog <catalog-name-or-id> --schema <s> --table <t> --column <col> --type bm25|vector [--metric cosine|l2|dot]`
    - [ ] Large build: add `--async`, then `hotdata jobs <job_id>`
 4. [ ] Search (--type and --column inferred when one search index exists):
    - [ ] `hotdata search "…" --table <catalog.schema.table>` (auto-infer)
@@ -74,20 +73,20 @@ End-to-end checklists. Use the linked sections for command detail and guardrails
 
 **Detail:** [hotdata-search INDEXES.md](../subskills/search/references/INDEXES.md)
 
-### Cross-source query (attach a connection)
+### Cross-source query (attach a catalog)
 
 **Skill:** **`hotdata`**
 
-A `hotdata query` runs inside **one** managed database; its scope sees that database's own catalog plus **attached** connection catalogs only. To query a connection's tables — or join a managed table against a live connection table in one query — attach the connection. (No managed database set → *"a database is required."*; an unattached catalog → *"table not found."*)
+A `hotdata query` runs inside **one** managed database; its scope sees that database's own catalog plus **attached** catalog catalogs only. To query a catalog's tables — or join a managed table against a live catalog table in one query — attach the catalog. (No managed database set → *"a database is required."*; an unattached catalog → *"table not found."*)
 
 1. [ ] Pick/create the managed database that will be the query context (`hotdata databases set <id>` or `databases create --catalog <alias>`)
-2. [ ] Attach the connection(s) you need (live, sync intact): `hotdata databases attach <connection> [--alias <a>]`
-   - Or attach at creation: `hotdata databases create --catalog <alias> --attach <connection>[=<alias>]`
+2. [ ] Attach the catalog(s) you need (live, sync intact): `hotdata databases attach <catalog> [--alias <a>]`
+   - Or attach at creation: `hotdata databases create --catalog <alias> --attach <catalog>[=<alias>]`
 3. [ ] Confirm scope: `hotdata databases <id>` lists attached catalogs
-4. [ ] Query across sources: `hotdata query "SELECT … FROM <my_catalog>.public.<t> JOIN <connection_or_alias>.<schema>.<table> ON …"`
-5. [ ] (Optional) `hotdata databases detach <connection|alias>` when finished; record required attachments in **context:DATAMODEL → Cross-connection joins**
+4. [ ] Query across sources: `hotdata query "SELECT … FROM <my_catalog>.public.<t> JOIN <catalog_or_alias>.<schema>.<table> ON …"`
+5. [ ] (Optional) `hotdata databases detach <catalog|alias>` when finished; record required attachments in **context:DATAMODEL → Cross-catalog joins**
 
-**Do not** export a connection to parquet just to query it — attach is the live, sync-preserving path.
+**Do not** export a catalog to parquet just to query it — attach is the live, sync-preserving path.
 
 ---
 
@@ -143,13 +142,13 @@ hotdata databases fork --expires-at 24h   # deep copy; becomes the active databa
 hotdata databases load --catalog sales --table orders --file ./risky.parquet  # hits the fork
 ```
 
-**Capture both ids.** After the fork, both databases answer to the same catalog alias (here `sales`), so ids are the only unambiguous way to refer to either one — the source id comes from `databases list` up front, the fork id from the `fork` output. The shared alias means experimental SQL runs unchanged against the fork. Attached connections are re-attached to the fork; indexes are not carried over. When done, keep the fork (`databases set <source_id>` to switch back to the source) or delete it (`databases delete <fork_id>`). Only DuckLake-backed databases can be forked — see `fork` in the main skill for details.
+**Capture both ids.** After the fork, both databases answer to the same catalog alias (here `sales`), so ids are the only unambiguous way to refer to either one — the source id comes from `databases list` up front, the fork id from the `fork` output. The shared alias means experimental SQL runs unchanged against the fork. Attached catalogs are re-attached to the fork; indexes are not carried over. When done, keep the fork (`databases set <source_id>` to switch back to the source) or delete it (`databases delete <fork_id>`). Only DuckLake-backed databases can be forked — see `fork` in the main skill for details.
 
 ---
 
 ## Model
 
-**Goal:** A markdown map of entities, keys, grain, and how connections relate—stored as **context:DATAMODEL** on top of the live **catalog** from Hotdata.
+**Goal:** A markdown map of entities, keys, grain, and how catalogs relate—stored as **context:DATAMODEL** on top of the live **catalog** from Hotdata.
 
 ### Initialize
 
diff --git a/skills/hotdata/subskills/analytics/SKILL.md b/skills/hotdata/subskills/analytics/SKILL.md
index f9bd2a3..df969b1 100644
--- a/skills/hotdata/subskills/analytics/SKILL.md
+++ b/skills/hotdata/subskills/analytics/SKILL.md
@@ -23,8 +23,8 @@ hotdata query status <query_run_id>
 
 - **PostgreSQL dialect.** Quote mixed-case identifiers: `"CustomerName"`.
 - Use **`hotdata tables list`** for schema discovery — not `information_schema` via `query`.
-- Fully qualified names: `<connection>.<schema>.<table>`, `<database>.<schema>.<table>`.
-- **Query scope:** every query runs inside one managed database (active or `--database`); it sees that database's own catalog plus **attached** connection catalogs only. To query a connection table, or **join a managed table against a connection table**, attach the connection first: `hotdata databases attach <connection>` — see **`hotdata`** skill → [Querying across connections](../../SKILL.md#querying-across-connections-attach). No managed database set → *"a database is required."*
+- Fully qualified names: `<catalog>.<schema>.<table>`, `<database>.<schema>.<table>`.
+- **Query scope:** every query runs inside one managed database (active or `--database`); it sees that database's own catalog plus **attached** catalogs only. To query an attached catalog's table, or **join a managed table against an attached catalog's table**, attach the catalog first: `hotdata databases attach <catalog>` — see **`hotdata`** skill → [Querying across catalogs](../../SKILL.md#querying-across-catalogs-attach). No managed database set → *"a database is required."*
 - Long-running queries may return `query_run_id` → poll with **`query status`** (exit `2` = still running). Do not re-run identical heavy SQL while polling.
 - For **workspace-wide** joins and naming, load **context:DATAMODEL** when listed (`hotdata context list` → `show DATAMODEL`) — see **`hotdata`** skill.
 
@@ -33,7 +33,7 @@ hotdata query status <query_run_id>
 Typical analytics SQL (all via `hotdata query`):
 
 - **Aggregations:** `COUNT`, `SUM`, `AVG`, `MIN`, `MAX` with `GROUP BY`
-- **Joins:** `INNER` / `LEFT JOIN` across `<catalog>.<schema>.<table>` names — every referenced catalog (managed or connection) must be in the active database's scope; attach connections first (`hotdata databases attach`)
+- **Joins:** `INNER` / `LEFT JOIN` across `<catalog>.<schema>.<table>` names — every referenced catalog (the managed database's own or an attached one) must be in the active database's scope; attach catalogs first (`hotdata databases attach`)
 - **Filtering:** `WHERE` on partition-friendly columns (consider **sorted** indexes below)
 - **Ordering:** `ORDER BY` on metrics or dimensions
 - **Bounded exploration:** always `LIMIT` while iterating; widen once validated
diff --git a/skills/hotdata/subskills/geospatial/SKILL.md b/skills/hotdata/subskills/geospatial/SKILL.md
index accce9c..fcd4a7d 100644
--- a/skills/hotdata/subskills/geospatial/SKILL.md
+++ b/skills/hotdata/subskills/geospatial/SKILL.md
@@ -18,7 +18,7 @@ All SQL below runs through the core CLI:
 hotdata query "<sql>" [--workspace-id <id>] [--database <db>] [--output table|json|csv]
 ```
 
-- **Fully qualify tables** as `<connection>.<schema>.<table>` (or `<catalog>.<schema>.<table>` for a managed database) — every `<table>` placeholder below means a qualified name.
+- **Fully qualify tables** as `<catalog>.<schema>.<table>` (or `<catalog>.<schema>.<table>` for a managed database) — every `<table>` placeholder below means a qualified name.
 - **PostgreSQL dialect:** double-quote any non-lowercase identifier (e.g. `"GeoID"`).
 - Discover candidate tables/columns with **`hotdata tables list`** (filter with `--schema`/`--table`) or **`hotdata databases tables list`** (tables inside a managed database) — see core skill.
 
diff --git a/skills/hotdata/subskills/search/SKILL.md b/skills/hotdata/subskills/search/SKILL.md
index 8930859..794a528 100644
--- a/skills/hotdata/subskills/search/SKILL.md
+++ b/skills/hotdata/subskills/search/SKILL.md
@@ -40,19 +40,19 @@ hotdata search "<query>" --table <schema.table> [--type bm25|vector] [--column <
 - **Custom embedding model, raw query vector, or no vector index?** Use `hotdata query` directly (e.g. `cosine_distance(col, [<vec>])`) — `search` only auto-embeds the query text via the index's own provider.
 - **Before search:** create the right index (`indexes create --type bm25` or `--type vector`). See [references/INDEXES.md](references/INDEXES.md).
 - Default `--limit` is 10.
-- **Active database:** with `hotdata databases set <db>`, you can pass `schema.table` directly (e.g. `--table public.articles`) — the active database's catalog is resolved automatically. Or use the full `catalog.schema.table` form. Do **not** use the internal `__db_<id>` label or raw connection ID prefix — `bm25_search`/`vector_distance` resolve a catalog attached to the active database, so an `__db_…` or `conn…` prefix errors with *catalog … is not attached*.
+- **Active database:** with `hotdata databases set <db>`, you can pass `schema.table` directly (e.g. `--table public.articles`) — the active database's catalog is resolved automatically. Or use the full `catalog.schema.table` form. Do **not** use the internal `__db_<id>` label or raw catalog ID prefix — `bm25_search`/`vector_distance` resolve a catalog attached to the active database, so an `__db_…` or `conn…` prefix errors with *catalog … is not attached*.
 
 ---
 
 ## Indexes (BM25 and vector)
 
-Create attaches to a table via its `--catalog` alias (a managed-database catalog or a connection name). `list` narrows to the **active database** when one is set; without one it scans the whole workspace. Filter further with `--schema` / `--table`. `delete` **requires all of** `--catalog` + `--schema` + `--table` + `--name`.
+Create attaches to a table via its `--catalog` alias (a managed database or an attached catalog). `list` narrows to the **active database** when one is set; without one it scans the whole workspace. Filter further with `--schema` / `--table`. `delete` **requires all of** `--catalog` + `--schema` + `--table` + `--name`.
 
 ```bash
 # List — active-database scope when a DB is set, else whole-workspace scan
 hotdata indexes list [--schema <schema>] [--table <table>] [--workspace-id <ws>] [--output table|json|yaml]
 
-# Create — by catalog alias (resolves a managed-database catalog or a connection name)
+# Create — by catalog alias (resolves a managed database or an attached catalog)
 hotdata indexes create --catalog <alias> --schema <schema> --table <table> \
   --column <col> --type bm25|vector \
   [--name <name>] [--metric l2|cosine|dot] [--async] \
diff --git a/skills/hotdata/subskills/search/references/INDEXES.md b/skills/hotdata/subskills/search/references/INDEXES.md
index 9866459..3376181 100644
--- a/skills/hotdata/subskills/search/references/INDEXES.md
+++ b/skills/hotdata/subskills/search/references/INDEXES.md
@@ -29,7 +29,7 @@ With no filters, this is a whole-workspace scan that **includes managed-database
 
 ## 3. Create indexes
 
-For managed databases (catalog alias — auto-selects the active database connection):
+For managed databases (catalog alias — auto-selects the active database catalog):
 
 ```bash
 hotdata indexes create --catalog <alias> --schema <schema> --table <table> \
@@ -39,13 +39,13 @@ hotdata indexes create --catalog <alias> --schema <schema> --table <table> \
   --column embedding --type vector --metric cosine
 ```
 
-For a regular connection, pass its name or ID to `--catalog`:
+For a regular catalog, pass its name or ID to `--catalog`:
 
 ```bash
-hotdata indexes create --catalog <connection-name-or-id> --schema <schema> --table <table> \
+hotdata indexes create --catalog <catalog-name-or-id> --schema <schema> --table <table> \
   --name idx_posts_body_bm25 --column body --type bm25
 
-hotdata indexes create --catalog <connection-name-or-id> --schema <schema> --table <table> \
+hotdata indexes create --catalog <catalog-name-or-id> --schema <schema> --table <table> \
   --name idx_chunks_embedding --column embedding --type vector --metric cosine
 ```
 
@@ -59,4 +59,4 @@ Re-run `hotdata search` or representative SQL. Update **context:DATAMODEL → Se
 
 - Prefer evidence (repeated search workloads) over speculative indexes.
 - Get approval before production `indexes create` when cost/impact is uncertain.
-- Align connection/schema/table with `hotdata tables list` output.
+- Align catalog/schema/table with `hotdata tables list` output.
diff --git a/src/client/ingest.rs b/src/client/ingest.rs
index 1a2f820..397da4f 100644
--- a/src/client/ingest.rs
+++ b/src/client/ingest.rs
@@ -22,9 +22,9 @@
 //! When the ingest routes land in the public OpenAPI and the SDK regenerates,
 //! delete this module and move the commands onto `sdk::Api`.
 //!
-//! Surface: `create_source` (onboard, backs `new-connection`), `create_query`
+//! Surface: `create_source` (onboard, backs `new-datasource`), `create_query`
 //! (SQL front-door, backs `new-import`), `list_sources` / `list_queries` (the
-//! registries behind `list-connections` / `list-imports`), `rerun` (backs
+//! registries behind `list-datasources` / `list-imports`), `rerun` (backs
 //! `trigger-import`), `connectors` (the catalog), `drain` + `job_status` (the
 //! async run loop). The result-reading endpoints are intentionally absent —
 //! that path is the core `query`/`databases`/`results` commands.
@@ -326,7 +326,7 @@ impl IngestClient {
         )
     }
 
-    /// Remove a connection from the registry (`DELETE /sources/{id}`):
+    /// Remove a datasource from the registry (`DELETE /sources/{id}`):
     /// the request row (with its stored encrypted credentials) and any run
     /// row. The discovery database is untouched — the command layer decides
     /// its fate. The server 422s import rows and 409s while a drain is in
@@ -338,8 +338,8 @@ impl IngestClient {
         )
     }
 
-    /// The onboarded-source registry (`GET /sources`) — one row per connection,
-    /// newest first, each with its own ingest id (the connection id). The
+    /// The onboarded-source registry (`GET /sources`) — one row per datasource,
+    /// newest first, each with its own ingest id (the datasource id). The
     /// default view is the current set: the latest onboard per connector name
     /// plus unnamed onboards; `all` includes superseded onboards too.
     pub fn list_sources(&self, all: bool) -> Result<SourcesResponse, IngestError> {
@@ -528,8 +528,8 @@ pub struct SourcesResponse {
     pub sources: Vec<SourceRow>,
 }
 
-/// One connection in the onboarded-source registry. `ingest_id` is the
-/// connection's own id — the pin key `new-import --source` accepts. `active`
+/// One datasource in the onboarded-source registry. `ingest_id` is the
+/// datasource's own id — the pin key `new-import --source` accepts. `active`
 /// marks the row by-name resolution picks (always true in the default view;
 /// superseded onboards surface with `all=true`).
 #[derive(Debug, Deserialize, Serialize)]
@@ -563,7 +563,7 @@ pub struct QueriesResponse {
 }
 
 /// One import in the registry: the SQL that produced it (verbatim for new
-/// rows, server-reconstructed for older ones), the connection it drew from,
+/// rows, server-reconstructed for older ones), the datasource it drew from,
 /// and the managed DB it landed in.
 #[derive(Debug, Deserialize, Serialize)]
 pub struct QueryRow {
diff --git a/src/commands/databases.rs b/src/commands/databases.rs
index eeb6657..6097df2 100644
--- a/src/commands/databases.rs
+++ b/src/commands/databases.rs
@@ -59,8 +59,8 @@ pub enum DatabasesCommands {
         #[arg(long)]
         expires_at: Option<String>,
 
-        /// Attach a connection as a queryable catalog on the new database (repeatable).
-        /// Accepts a connection name or id, optionally `connection=alias` to set the
+        /// Attach a catalog to the new database so its tables are queryable (repeatable).
+        /// Accepts a catalog name or id, optionally `catalog=alias` to set the
         /// SQL alias it answers to: `--attach github --attach salesdb=sales`.
         #[arg(long = "attach")]
         attach: Vec<String>,
@@ -75,7 +75,7 @@ pub enum DatabasesCommands {
     /// The fork contains the same schemas, tables, and data as the source, and
     /// answers to the same SQL catalog alias inside its own query scope; the
     /// two databases diverge freely afterwards (writes to one never affect the
-    /// other). Connection catalogs attached to the source are re-attached to
+    /// other). Catalogs attached to the source are re-attached to
     /// the fork; indexes are not carried over.
     Fork {
         /// Source database id, catalog, or name (defaults to the current database)
@@ -97,30 +97,30 @@ pub enum DatabasesCommands {
         output: String,
     },
 
-    /// Attach a connection as a queryable catalog on a managed database.
+    /// Attach a catalog to a managed database so its tables are queryable.
     ///
-    /// A `query` runs inside one managed database; attaching a connection makes
+    /// A `query` runs inside one managed database; attaching a catalog makes
     /// its live tables visible in that database's scope, so you can join across
-    /// sources in a single query without exporting data. Reachable in SQL as
-    /// `<alias>.<schema>.<table>`, or `<connection-name>.<schema>.<table>` when
+    /// catalogs in a single query without exporting data. Reachable in SQL as
+    /// `<alias>.<schema>.<table>`, or `<catalog-name>.<schema>.<table>` when
     /// `--alias` is omitted.
     Attach {
-        /// Connection name or id to attach (e.g. `github`)
-        connection: String,
+        /// Catalog name or id to attach (e.g. `github`)
+        catalog: String,
 
         /// Database id, catalog, or name to attach into (defaults to the current database)
         #[arg(long, short = 'd')]
         database: Option<String>,
 
-        /// Alias the catalog answers to in SQL. Defaults to the connection's name.
+        /// Alias the catalog answers to in SQL. Defaults to the catalog's name.
         #[arg(long)]
         alias: Option<String>,
     },
 
-    /// Detach a previously attached connection catalog from a managed database.
+    /// Detach a previously attached catalog from a managed database.
     Detach {
-        /// Connection name or id to detach
-        connection: String,
+        /// Catalog name or id to detach
+        catalog: String,
 
         /// Database id, catalog, or name to detach from (defaults to the current database)
         #[arg(long, short = 'd')]
@@ -138,7 +138,7 @@ pub enum DatabasesCommands {
 
     /// Delete a managed database and its tables
     Delete {
-        /// Database name or connection ID
+        /// Managed database id or name
         name_or_id: String,
     },
 
@@ -1029,7 +1029,7 @@ pub fn get(workspace_id: &str, id_or_name: &str, format: &str) {
             }
             println!(
                 "{}{}",
-                label("default_connection_id:"),
+                label("catalog id:"),
                 db.default_connection_id.clone().dark_cyan()
             );
             let catalog = db
@@ -1065,7 +1065,7 @@ pub fn get(workspace_id: &str, id_or_name: &str, format: &str) {
 /// Attach a connection as a queryable catalog on a managed database, so its
 /// live tables are visible inside that database's query scope (cross-source
 /// joins without exporting data). Defaults to the current database.
-pub fn attach(workspace_id: &str, connection: &str, database: Option<&str>, alias: Option<&str>) {
+pub fn attach(workspace_id: &str, catalog: &str, database: Option<&str>, alias: Option<&str>) {
     use crossterm::style::Stylize;
 
     let database = resolve_current_database(database, workspace_id);
@@ -1081,14 +1081,14 @@ pub fn attach(workspace_id: &str, connection: &str, database: Option<&str>, alia
     // exits with the resolver's message, and an API failure goes through
     // `ApiError::exit`, which upgrades a masked 401/403 into the re-auth hint.
     // (The non-fatal `create --attach` loop uses `attach_connection` instead.)
-    let connection_id = crate::commands::connections::resolve_connection_id(&api, connection);
+    let connection_id = crate::commands::connections::resolve_connection_id(&api, catalog);
     send_attach(&api, &db.id, connection_id, alias).unwrap_or_else(|e| e.exit());
 
     match alias {
         Some(a) => println!(
             "{}",
             format!(
-                "Attached '{connection}' to database '{where_}' as catalog '{a}'.\n\
+                "Attached '{catalog}' to database '{where_}' as catalog '{a}'.\n\
                  Query: hotdata query \"SELECT * FROM {a}.<schema>.<table> LIMIT 10\" -d {where_}"
             )
             .green()
@@ -1096,17 +1096,17 @@ pub fn attach(workspace_id: &str, connection: &str, database: Option<&str>, alia
         None => println!(
             "{}",
             format!(
-                "Attached '{connection}' to database '{where_}'. It is reachable by the \
-                 connection's name; run `hotdata databases {where_}` to see attached catalogs."
+                "Attached '{catalog}' to database '{where_}'. It is reachable by the \
+                 catalog's name; run `hotdata databases {where_}` to see attached catalogs."
             )
             .green()
         ),
     }
 }
 
-/// Detach a previously attached connection catalog from a managed database.
+/// Detach a previously attached catalog from a managed database.
 /// Defaults to the current database.
-pub fn detach(workspace_id: &str, connection: &str, database: Option<&str>) {
+pub fn detach(workspace_id: &str, catalog: &str, database: Option<&str>) {
     use crossterm::style::Stylize;
 
     let database = resolve_current_database(database, workspace_id);
@@ -1120,14 +1120,14 @@ pub fn detach(workspace_id: &str, connection: &str, database: Option<&str>) {
         .to_string();
     // Detach is keyed by the underlying connection id, but a user who attached
     // `github=gh` will naturally type `detach gh`. Resolve an attachment alias to
-    // its connection id first; otherwise treat the argument as a connection
+    // its connection id first; otherwise treat the argument as a catalog
     // name/id like everywhere else.
     let connection_id = db
         .attachments
         .iter()
-        .find(|a| a.alias.as_deref() == Some(connection))
+        .find(|a| a.alias.as_deref() == Some(catalog))
         .map(|a| a.connection_id.clone())
-        .unwrap_or_else(|| crate::commands::connections::resolve_connection_id(&api, connection));
+        .unwrap_or_else(|| crate::commands::connections::resolve_connection_id(&api, catalog));
 
     block(
         api.client()
@@ -1138,7 +1138,7 @@ pub fn detach(workspace_id: &str, connection: &str, database: Option<&str>) {
 
     println!(
         "{}",
-        format!("Detached '{connection}' from database '{where_}'.").green()
+        format!("Detached '{catalog}' from database '{where_}'.").green()
     );
 }
 
diff --git a/src/commands/indexes.rs b/src/commands/indexes.rs
index ee8413f..bd4223b 100644
--- a/src/commands/indexes.rs
+++ b/src/commands/indexes.rs
@@ -77,7 +77,7 @@ pub enum IndexesCommands {
 
     /// Delete an index from a table
     Delete {
-        /// SQL catalog alias of the target database or connection name (same flag as `indexes create`)
+        /// SQL catalog alias of the target database or catalog name (same flag as `indexes create`)
         #[arg(long)]
         catalog: String,
 
diff --git a/src/commands/ingest.rs b/src/commands/ingest.rs
index e289d3f..0a74de1 100644
--- a/src/commands/ingest.rs
+++ b/src/commands/ingest.rs
@@ -93,7 +93,6 @@ pub enum IngestCommands {
     /// Interactive by default; pass `--service` with config flags to add
     /// non-interactively. Pull rows separately with `hotdata ingest
     /// new-import`; browse available types with `hotdata ingest datasources`.
-    #[command(alias = "new-connection")]
     NewDatasource {
         #[command(flatten)]
         create: CreateArgs,
@@ -103,7 +102,6 @@ pub enum IngestCommands {
     },
 
     /// Show a datasource's details: status and discovered tables + columns
-    #[command(alias = "show-connection")]
     ShowDatasource {
         /// Datasource id (from `list-datasources`)
         id: String,
@@ -113,7 +111,6 @@ pub enum IngestCommands {
     ///
     /// Imports you've already run keep working — each carries its own
     /// credential copy.
-    #[command(alias = "delete-connection")]
     DeleteDatasource {
         /// Datasource id (from `list-datasources`)
         id: String,
@@ -124,7 +121,6 @@ pub enum IngestCommands {
     },
 
     /// List the datasources you've added (each has its own datasource id)
-    #[command(alias = "list-connections")]
     ListDatasources {
         /// Include datasources replaced by a newer one of the same name
         #[arg(long)]
diff --git a/src/commands/query.rs b/src/commands/query.rs
index d94903e..f4bcbaa 100644
--- a/src/commands/query.rs
+++ b/src/commands/query.rs
@@ -393,21 +393,21 @@ fn cross_source_hint(error_msg: &str) -> Option<String> {
     if lower.contains("a database is required") {
         return Some(
             "Tip: a query runs inside one managed database. Set one with `hotdata databases \
-             set <id>`, then attach any connection whose tables you need: `hotdata databases \
-             attach <connection>`. List connections with `hotdata connections list`."
+             set <id>`, then attach any catalog whose tables you need: `hotdata databases \
+             attach <catalog>`. See available catalogs and tables with `hotdata tables list`."
                 .to_string(),
         );
     }
     // "table 'catalog.schema.table' not found" — surface the catalog so the user
-    // can attach it if it's a connection simply outside this database's scope.
+    // can attach it if it's a catalog simply outside this database's scope.
     if lower.contains("not found")
         && let Some(quoted) = error_msg.split('\'').nth(1)
         && quoted.contains('.')
         && let Some(catalog) = quoted.split('.').next().filter(|c| !c.is_empty())
     {
         return Some(format!(
-            "Tip: '{catalog}' isn't in the current database's scope. If it's a connection, \
-             attach it to query across sources: `hotdata databases attach {catalog}`."
+            "Tip: '{catalog}' isn't in the current database's scope. If it's a catalog, \
+             attach it to query across catalogs: `hotdata databases attach {catalog}`."
         ));
     }
     None
diff --git a/src/main.rs b/src/main.rs
index f76806b..95b4fc7 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -296,19 +296,18 @@ fn main() {
                             &output,
                         ),
                         Some(DatabasesCommands::Attach {
-                            connection,
+                            catalog,
                             database,
                             alias,
                         }) => databases::attach(
                             &workspace_id,
-                            &connection,
+                            &catalog,
                             database.as_deref(),
                             alias.as_deref(),
                         ),
-                        Some(DatabasesCommands::Detach {
-                            connection,
-                            database,
-                        }) => databases::detach(&workspace_id, &connection, database.as_deref()),
+                        Some(DatabasesCommands::Detach { catalog, database }) => {
+                            databases::detach(&workspace_id, &catalog, database.as_deref())
+                        }
                         Some(DatabasesCommands::Set { id }) => databases::set(&workspace_id, &id),
                         Some(DatabasesCommands::Unset) => databases::unset(&workspace_id),
                         Some(DatabasesCommands::Delete { name_or_id }) => {
diff --git a/tests/databases_cli.rs b/tests/databases_cli.rs
index b8fb5b4..3b79634 100644
--- a/tests/databases_cli.rs
+++ b/tests/databases_cli.rs
@@ -30,8 +30,8 @@ fn databases_create_help_documents_attach_flag() {
     assert!(output.status.success());
     let help = String::from_utf8_lossy(&output.stdout);
     assert!(help.contains("--attach"), "help: {help}");
-    // The `connection=alias` form is the documented way to set the SQL alias.
-    assert!(help.contains("connection=alias"), "help: {help}");
+    // The `catalog=alias` form is the documented way to set the SQL alias.
+    assert!(help.contains("catalog=alias"), "help: {help}");
 }
 
 #[test]
@@ -48,7 +48,7 @@ fn databases_attach_help_documents_connection_and_alias() {
 
 #[test]
 fn databases_attach_requires_a_connection_argument() {
-    // `connection` is a required positional — parsing must fail without it.
+    // `catalog` is a required positional — parsing must fail without it.
     let output = hotdata().args(["databases", "attach"]).output().unwrap();
     assert!(!output.status.success());
     let combined = format!(
@@ -57,7 +57,7 @@ fn databases_attach_requires_a_connection_argument() {
         String::from_utf8_lossy(&output.stderr)
     );
     assert!(
-        combined.contains("required") || combined.contains("CONNECTION"),
+        combined.contains("required") || combined.contains("CATALOG"),
         "output: {combined}"
     );
 }