docs: declare the key before the first load in both worked examples

Running the examples found an ordering bug I had just introduced. The
instant-database workflow loaded into `orders` at step 2, then ran
`tables add orders --key` at step 3 — which returns 409, because the
load had already declared the table. It also contradicted its own note
in the same step to declare before the first load. Declaration is now
step 2 and the load step 3, with the keyed sync as step 4.

SKILL.md's keyed example had the same trap across two adjacent blocks:
it declared `listings`, the table the preceding example had already
loaded into. It uses its own table and includes the initial load, so the
block stands alone and runs in the order given.

Both sequences were then run verbatim against the API: declare with key
and sort, load, upsert, delete, and read back the expected rows.

Also fixes the `databases tables load` row in README's command table,
which still described parquet and `--append` after the sweep updated the
row above it.

Author: anoop-narang

README.md

@@ -170,7 +170,7 @@ The full command surface. The top level has nine groups — `auth`, `workspaces`
 | `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`) |
+| `databases tables load` | Same as `databases load`, addressed by database instead of catalog |
 | `databases tables remove` | Delete a table from a database |
 | `databases context list` | List named contexts in a database |
 | `databases context show` | Print context content to stdout |

skills/hotdata/SKILL.md

@@ -146,16 +146,19 @@ hotdata databases load --catalog airbnb --table listings --url https://example.c
 hotdata query "SELECT count(*) FROM airbnb.public.listings"
 ```
 
-Keeping a table in sync by key — declare the key once, then load changes:
+Keeping a table in sync by key. Declare the key **before the table's first
+load** — `tables add` on a table that already exists returns 409, and a key
+cannot be added afterwards:
 
 ```
-hotdata databases tables add listings --key listing_id --sorted-by updated_at=desc
-hotdata databases load --catalog airbnb --table listings --file changed.csv --mode upsert
-hotdata databases load --catalog airbnb --table listings --file removed.csv --mode delete
+hotdata databases tables add bookings --key booking_id --sorted-by updated_at=desc
+hotdata databases load --catalog airbnb --table bookings --file bookings.csv
+hotdata databases load --catalog airbnb --table bookings --file changed.csv --mode upsert
+hotdata databases load --catalog airbnb --table bookings --file removed.csv --mode delete
 ```
 
-`removed.csv` carries only the key columns. On a table declared without a key,
-name one per load instead: `--mode upsert --key listing_id`.
+`removed.csv` carries only the key columns. On a table already declared without
+a key, name one per load instead: `--mode upsert --key booking_id`.
 
 #### Querying across catalogs (attach)
 

skills/hotdata/references/WORKFLOWS.md

@@ -111,8 +111,18 @@ A `hotdata query` runs inside **one** instant database; its scope sees that data
    hotdata databases create --catalog sales
    ```
 
-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:
+2. **Before the first load**, declare any table that needs a key, a sort order,
+   or partitioning — the load cannot infer these, and a key cannot be added to
+   a table that already exists:
+
+   ```bash
+   hotdata databases tables add orders --key order_id --sorted-by created_at=desc
+   ```
+
+   Skip this for a table you will only ever replace or append to.
+
+3. Load a file per table. A table or schema not declared above 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.csv
@@ -123,18 +133,17 @@ A `hotdata query` runs inside **one** instant database; its scope sees that data
    > undeclared table — nothing is recreated. Selection is still always by id,
    > since names and catalogs are not unique.
 
-3. Declare the table yourself only when you need something the load cannot
-   infer — a key, a sort order, or partitioning:
+4. Keep a keyed table in sync by loading only what changed:
 
    ```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
+   hotdata databases load --catalog sales --table orders --file ./removed.csv --mode delete
    ```
 
-   > 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`.
+   `removed.csv` carries only the key columns. This needs the key declared in
+   step 2, or named per load with `--key order_id`.
 
-4. Confirm and query:
+5. Confirm and query:
 
    ```bash
    hotdata databases tables list