docs: correct format and declaration claims the code no longer matches

A deliberate sweep for parquet-only language, after finding two stale
spots by accident.

README's command table and the workflow decision guide still described
`databases load` as parquet-only and instant databases as "parquet files
you own". Both now name csv, newline-delimited json, and parquet, and
the table lists `databases tables add`.

The instant-database workflow carried a callout that was materially
wrong after this branch: it warned that loading into an undeclared table
recreates the database and changes its `id`, and advised against caching
ids across loads. The load declares a missing table and schema in place,
so the id and the other tables survive. The workflow now shows the
declare-a-key step and records that a key cannot be added later.

Two code comments justified themselves by the removed delete+recreate
path: the raw JSON create-request builder ("the delete+recreate path
still consumes the raw JSON form, so the JSON builder stays") and
`delete_raw`'s doc. Both are still used for other reasons, so only the
reasons are corrected.

Author: anoop-narang

README.md

@@ -166,7 +166,8 @@ The full command surface. The top level has nine groups — `auth`, `workspaces`
 | `databases use` | Set the current (default) database |
 | `databases unset` | Clear the current database |
 | `databases remove` | Delete a database and all its tables |
-| `databases load` | Load a parquet file or saved result into a table (replace, or `--append`) |
+| `databases load` | Load a csv/json/parquet file or saved result into a table (`--mode replace\|append\|delete\|update\|upsert`) |
+| `databases tables add` | Declare a table with its key and storage layout |
 | `databases tables list` | List tables in a database |
 | `databases tables show` | Show column definitions for a table |
 | `databases tables load` | Load parquet/result into a table (replace, or `--append`) |

skills/hotdata/references/WORKFLOWS.md

@@ -11,7 +11,7 @@ The `hotdata` skill is always loaded first (auth and workspace setup). The three
 | User goal | Skill | Key commands |
 |-----------|--------|----------------|
 | Login, workspaces, datasources, tables, context | **`hotdata`** | `auth`, `workspaces`, `ingest sources`, `ingest`, `databases tables`, `databases context` |
-| Load parquet files into an instant database | **`hotdata`** | `databases create` + `databases load` |
+| Load csv/json/parquet files into an instant database | **`hotdata`** | `databases create` + `databases tables add` + `databases load` |
 | SQL analytics, aggregations, history, Chain | **`hotdata-analytics`** (`subskills/analytics/SKILL.md`) | `query`, `databases queries`, `databases results` |
 | BM25 / vector search, retrieval indexes | **`hotdata-search`** (`subskills/search/SKILL.md`) | `search`, `search create`, `search embeddings` |
 | Geospatial / PostGIS-style SQL | **`hotdata-geospatial`** (`subskills/geospatial/SKILL.md`) | `query` with `ST_*`, WKB columns |
@@ -94,33 +94,47 @@ A `hotdata query` runs inside **one** instant database; its scope sees that data
 
 | | **Instant databases** |
 |---|------------------------|
-| **Best for** | Parquet files you own; catalog-style `alias.schema.table` |
+| **Best for** | Files you own (csv, newline-delimited json, parquet); catalog-style `alias.schema.table` |
 | **SQL prefix** | `<catalog>.<schema>.<table>` where catalog = `--catalog` alias |
 | **CLI** | `hotdata databases create --catalog` + `databases load` |
-| **Declare schema up front** | Yes — `--table` on create (auto-declared on first `databases load`) |
-| **Parquet file uploads** | `databases load --file` / `--url` / `--upload-id` |
-| **Refresh** | Replace via `databases load` again |
+| **Declare schema up front** | Optional — the load declares a missing table/schema. Declare with `databases tables add --key` when you need the keyed load modes; a key cannot be added later |
+| **File uploads** | `databases load --file` / `--url` / `--upload-id`; format from the extension, or `--format` |
+| **Refresh** | `databases load` again — `--mode replace` (default) or `append`, or `delete`/`update`/`upsert` against a declared key |
 
-**Rule of thumb:** Parquet files you control as **`mydb.public.orders`** → **instant databases**.
+**Rule of thumb:** Files you control as **`mydb.public.orders`** → **instant databases**.
 
-### Workflow: instant database (parquet)
+### Workflow: instant database (file upload)
 
 1. Create the database with a catalog alias:
 
    ```bash
    hotdata databases create --catalog sales
    ```
 
-2. Load parquet per table (tables are auto-declared if needed):
+2. Load a file per table. A missing table or schema is declared as part of the
+   load, and the format comes from the file's extension:
 
    ```bash
-   hotdata databases load --catalog sales --table orders --file ./orders.parquet
+   hotdata databases load --catalog sales --table orders --file ./orders.csv
    hotdata databases load --catalog sales --table customers --url https://example.com/customers.parquet
    ```
 
-   > Auto-declaring a *new* table recreates the database (no add-table API), which **changes its `id`** — the id returned by `databases create` goes stale after the next `load` of an undeclared table. Declare tables up front (`databases create --table orders --table customers`) to avoid the recreate, and don't cache ids across loads: re-read the current id from `databases list` at time of use. (Selection is still always by id — names and catalogs are not unique.)
+   > The database keeps its `id` and its other tables across a load into an
+   > undeclared table — nothing is recreated. Selection is still always by id,
+   > since names and catalogs are not unique.
 
-3. Confirm and query:
+3. Declare the table yourself only when you need something the load cannot
+   infer — a key, a sort order, or partitioning:
+
+   ```bash
+   hotdata databases tables add orders --key order_id --sorted-by created_at=desc
+   hotdata databases load --catalog sales --table orders --file ./changed.csv --mode upsert
+   ```
+
+   > A key is fixed when the table is declared and **cannot be added later**, so
+   > declare it before the first load if you will need `delete`/`update`/`upsert`.
+
+4. Confirm and query:
 
    ```bash
    hotdata databases tables list

src/client/sdk.rs

@@ -852,10 +852,10 @@ impl Api {
     /// `Configuration`, returning the raw status + body text.
     ///
     /// The seam's DELETE counterpart to [`post_raw`](Self::post_raw): used by
-    /// `databases.rs`, where the delete bodies feed the same CLI-side
-    /// `(status, body)` control flow as the old raw `delete_raw` (e.g. the
-    /// delete+recreate path inspects the failure body), so non-success is
-    /// returned as `Ok((status, body))` rather than an error.
+    /// `databases.rs`, where a delete's response body feeds the same CLI-side
+    /// `(status, body)` control flow the raw calls used, so non-success is
+    /// returned as `Ok((status, body))` rather than an error and the caller
+    /// renders the server's own message.
     pub fn delete_raw(&self, path: &str) -> Result<(reqwest::StatusCode, String), ApiError> {
         let cfg = self.client.configuration();
         let url = format!("{}/v1{path}", cfg.base_path);

src/commands/databases.rs

@@ -877,10 +877,9 @@ pub fn fork_database_request(
 }
 
 /// Build the typed `CreateDatabaseRequest` for the SDK's `databases().create`
-/// handle, reusing [`create_database_request`] as the single source of truth for
-/// the body shape. The delete+recreate path still consumes the raw JSON form
-/// (it inspects raw error bodies), so the JSON builder stays; this just adapts
-/// it for the typed call sites.
+/// handle by adapting [`create_database_request`], which stays the single
+/// source of truth for the body shape — the schema-seeding rules it encodes are
+/// specified against the JSON form in this module's tests.
 fn create_database_typed_request(
     name: Option<&str>,
     catalog: Option<&str>,