Add skill writeup for datasets commands and show full_name in table details for datasets

Author: pthurlow

skills/hotdata-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hotdata-cli
-description: Use this skill when the user wants to run hotdata CLI commands, query the HotData API, list workspaces, list connections, list tables, execute SQL queries, or interact with the hotdata service. Activate when the user says "run hotdata", "query hotdata", "list workspaces", "list connections", "list tables", "execute a query", or asks you to use the hotdata CLI.
+description: Use this skill when the user wants to run hotdata CLI commands, query the HotData API, list workspaces, list connections, list tables, manage datasets, execute SQL queries, or interact with the hotdata service. Activate when the user says "run hotdata", "query hotdata", "list workspaces", "list connections", "list tables", "list datasets", "create a dataset", "upload a dataset", "execute a query", or asks you to use the hotdata CLI.
 version: 0.1.3
 ---
 
@@ -50,6 +50,46 @@ hotdata tables list [--workspace-id <workspace_id>] [--connection-id <connection
 - `--schema` and `--table` support SQL `%` wildcard patterns (e.g. `--table order%` matches `orders`, `order_items`, etc.).
 - Results are paginated (default 100 per page). If more results are available, a `--cursor` token is printed — pass it to fetch the next page.
 
+### Datasets
+
+Datasets are managed files uploaded to HotData and queryable as tables.
+
+#### List datasets
+```
+hotdata datasets list [--workspace-id <workspace_id>] [--limit <int>] [--offset <int>] [--format table|json|yaml]
+```
+- Default format is `table`.
+- Returns `id`, `label`, `table_name`, `created_at`.
+- Results are paginated (default 100). Use `--offset` to fetch further pages.
+
+#### Get dataset details
+```
+hotdata datasets <dataset_id> [--workspace-id <workspace_id>] [--format table|json|yaml]
+```
+- Shows dataset metadata and a full column listing with `name`, `data_type`, `nullable`.
+- Use this to inspect schema before querying.
+
+#### Create a dataset
+```
+hotdata datasets create --label "My Dataset" --file data.csv [--table-name my_dataset] [--workspace-id <workspace_id>]
+```
+- `--file` uploads a local file. Omit to pipe data via stdin: `cat data.csv | hotdata datasets create --label "My Dataset"`
+- Format is auto-detected from file extension (`.csv`, `.json`, `.parquet`) or file content.
+- `--label` is optional when `--file` is provided — defaults to the filename without extension.
+- `--table-name` is optional — derived from the label if omitted.
+
+#### Querying datasets
+
+Datasets are queryable using the catalog `datasets` and schema `main`. Always reference dataset tables as:
+```
+datasets.main.<table_name>
+```
+For example:
+```
+hotdata query "SELECT * FROM datasets.main.my_dataset LIMIT 10"
+```
+Use `hotdata datasets <dataset_id>` to look up the `table_name` before writing queries.
+
 ### Execute SQL Query
 ```
 hotdata query "<sql>" [--workspace-id <workspace_id>] [--connection <connection_id>] [--format table|json|csv]

src/datasets.rs

@@ -319,7 +319,7 @@ pub fn create(
     println!("{}", "Dataset created".green());
     println!("id:         {}", dataset.id);
     println!("label:      {}", dataset.label);
-    println!("table_name: {}", dataset.table_name);
+    println!("full_name:  datasets.main.{}", dataset.table_name);
 }
 
 pub fn list(workspace_id: &str, limit: Option<u32>, offset: Option<u32>, format: &str) {
@@ -378,13 +378,14 @@ pub fn list(workspace_id: &str, limit: Option<u32>, offset: Option<u32>, format:
         "yaml" => print!("{}", serde_yaml::to_string(&body.datasets).unwrap()),
         "table" => {
             let mut table = crate::util::make_table();
-            table.set_header(["ID", "LABEL", "TABLE NAME", "CREATED AT"]);
+            table.set_header(["ID", "LABEL", "FULL NAME", "CREATED AT"]);
             table.column_mut(1).unwrap().set_constraint(
                 comfy_table::ColumnConstraint::UpperBoundary(comfy_table::Width::Fixed(30))
             );
             for d in &body.datasets {
                 let created_at = d.created_at.split('.').next().unwrap_or(&d.created_at).replace('T', " ");
-                table.add_row([&d.id, &d.label, &d.table_name, &created_at]);
+                let full_name = format!("datasets.main.{}", d.table_name);
+                table.add_row([&d.id, &d.label, &full_name, &created_at]);
             }
             println!("{table}");
             if body.has_more {
@@ -452,8 +453,7 @@ pub fn get(dataset_id: &str, workspace_id: &str, format: &str) {
             let updated_at = d.updated_at.split('.').next().unwrap_or(&d.updated_at).replace('T', " ");
             println!("id:          {}", d.id);
             println!("label:       {}", d.label);
-            println!("schema:      {}", d.schema_name);
-            println!("table:       {}", d.table_name);
+            println!("full_name:   datasets.main.{}", d.table_name);
             println!("source_type: {}", d.source_type);
             println!("created_at:  {created_at}");
             println!("updated_at:  {updated_at}");