@@ -236,12 +236,14 @@ hotdata jobs <job_id> [--workspace-id <workspace_id>] [--output table|json|yaml]
 
 ### Ingest external data (`datasource`, `ingest`, `run`)
 
-Pull data from external sources (SQL databases, APIs, S3/GCS/Azure buckets, Iceberg catalogs, Kafka) into managed databases. **Three nouns, three ids, and the id is always the argument** — display names are shown but never resolved against:
+Pull data from external sources (SQL databases, APIs, S3/GCS/Azure buckets, Iceberg catalogs, Kafka) into managed databases. **Three nouns, three ids, and an id is always what goes on the wire** — the service has no name lookup, because a display name is a label and nothing stops two rows sharing one:
 
 - **datasource** (`ds_…`) — what a credential opens: a server, a bucket root, a catalog, a cluster. Holds config + credentials, loads no data.
 - **ingest** (`ing_…`) — a saved load definition: `datasource + selector + destination + type/schedule`. One datasource can back many ingests.
 - **run** (`run_…`) — one execution attempt, with snapshots of the config version, selector, and destination it used.
 
+One flag softens that for typing, and only for typing: `ingest create --source` accepts a display name and resolves it to an id **client-side, before the request**, erroring with both ids if the name matches two datasources rather than picking one. Every other argument, and every request the CLI sends, takes ids only.
+
 Read commands (`datasource list|show|types|fields`, `ingest list|show|runs`, `run show`) work with a login session JWT. Commands that persist a credential (`datasource create`, `datasource update-config`, `ingest create`) **require a workspace API key** (`HOTDATA_API_KEY` / `--api-key`, `hd_...`) — the run outlives the 5-minute JWT.
 
 ```bash
 
@@ -1141,6 +1141,67 @@ pub const FAMILY_REFERENCE_BODY: &str = r#"{
   }
 }"#;
 
+/// The same family, with its selector encoded the other legal way: the `oneOf`
+/// branches hoisted into `$defs` and referenced instead of written inline.
+///
+/// Both encodings describe the identical pair of forms, and which one arrives
+/// is the schema generator's choice — a discriminated union is hoisted by
+/// default and only inlined when something asks it to be. The body above is
+/// inlined, so on its own it cannot tell "the service inlines" apart from "the
+/// renderer only handles inline", and a renderer that reads `properties`
+/// straight off a branch passes it while printing the `sql` family — the one
+/// whose two selector forms are the reason the field reference exists — as a
+/// family that takes no fields at all.
+///
+/// Trimmed to the selector: the other schemas are exercised above, and what is
+/// being pinned here is the indirection, including the discriminator `const`
+/// living a hop away from the `discriminator` that names it.
+///
+/// `r##` rather than the `r#` the other bodies use: a JSON pointer is written
+/// `"#/$defs/…"`, and that `"#` would close an `r#` string mid-literal.
+#[cfg(test)]
+pub const FAMILY_REFERENCE_REF_SELECTOR_BODY: &str = r##"{
+  "family": "sql",
+  "config_schema": {"properties": {}, "type": "object"},
+  "credentials_schema": {"properties": {}, "type": "object"},
+  "selector_schema": {
+    "$defs": {
+      "SqlTableSelector": {
+        "additionalProperties": false,
+        "properties": {
+          "mode": {"const": "tables", "default": "tables", "title": "Mode",
+                   "type": "string"},
+          "schema": {"anyOf": [{"type": "string"}, {"type": "null"}],
+                     "default": null, "title": "Schema"},
+          "tables": {"items": {"type": "string"}, "minItems": 1,
+                     "title": "Tables", "type": "array",
+                     "description": "Source tables to read. Each lands in a destination table of the same name."}
+        },
+        "required": ["tables"], "title": "SqlTableSelector", "type": "object"},
+      "SqlQuerySelector": {
+        "additionalProperties": false,
+        "properties": {
+          "mode": {"const": "query", "title": "Mode", "type": "string"},
+          "sql": {"minLength": 1, "title": "Sql", "type": "string"}
+        },
+        "required": ["mode", "sql"], "title": "SqlQuerySelector", "type": "object"}
+    },
+    "discriminator": {"propertyName": "mode",
+                      "mapping": {"tables": "#/$defs/SqlTableSelector",
+                                  "query": "#/$defs/SqlQuerySelector"}},
+    "oneOf": [{"$ref": "#/$defs/SqlTableSelector"},
+              {"$ref": "#/$defs/SqlQuerySelector"}]
+  },
+  "capabilities": {
+    "write_modes": ["replace", "append"],
+    "continuous": false,
+    "recoverable": true,
+    "supports_where": true,
+    "multi_table": true,
+    "immutable_config_fields": []
+  }
+}"##;
+
 /// A `GET /families` body: the same shape, several families, trimmed to the
 /// parts the index table reads.
 #[cfg(test)]
 
@@ -1034,20 +1034,60 @@ fn print_schema(schema: &serde_json::Value) {
 /// a complete alternative with its own required set, so rendering one of them
 /// (or merging them into a single table) would describe a request the service
 /// does not accept.
+///
+/// The root and every branch are followed through a local `$ref` first. A
+/// schema generator may write a form inline or hoist it into `$defs` and point
+/// at it, and the two say the same thing — but everything downstream reads
+/// `properties`, which a `$ref` object does not have. An unfollowed branch
+/// therefore renders as a form with no fields and no label: the field
+/// reference answering "what does this family take?" with nothing, for exactly
+/// the multi-form families whose fields are hardest to guess.
+///
+/// Branches resolve against the ORIGINAL root, not the resolved one, because
+/// `$defs` sits on the document — a root that was itself a `$ref` resolves to
+/// a definition that does not carry it.
 fn schema_variants(schema: &serde_json::Value) -> Vec<(Option<String>, &serde_json::Value)> {
-    let Some(branches) = schema.get("oneOf").and_then(|b| b.as_array()) else {
-        return vec![(None, schema)];
+    let root = resolve_local_ref(schema, schema);
+    let Some(branches) = root.get("oneOf").and_then(|b| b.as_array()) else {
+        return vec![(None, root)];
     };
-    let discriminator = schema
+    let discriminator = root
         .get("discriminator")
         .and_then(|d| d.get("propertyName"))
         .and_then(|p| p.as_str());
     branches
         .iter()
+        .map(|b| resolve_local_ref(schema, b))
         .map(|b| (variant_label(b, discriminator), b))
         .collect()
 }
 
+/// Follow a `$ref` pointing inside this document. Anything else is returned as
+/// it stands.
+///
+/// Resolved with `Value::pointer`, so `#/$defs/X` and the older
+/// `#/definitions/X` both work without either spelling being written here —
+/// which of the two arrives is the generator's business, not this command's.
+///
+/// A `$ref` to another document is left unresolved rather than fetched: this
+/// renders one response, and reaching the network mid-render would make
+/// `datasource fields` fail for a reason that has nothing to do with the
+/// family being asked about. A pointer that resolves to nothing falls back the
+/// same way, so an unfamiliar schema degrades to the previous rendering
+/// instead of panicking on a family the CLI has never seen.
+fn resolve_local_ref<'a>(
+    root: &'a serde_json::Value,
+    node: &'a serde_json::Value,
+) -> &'a serde_json::Value {
+    let Some(reference) = node.get("$ref").and_then(|r| r.as_str()) else {
+        return node;
+    };
+    let Some(pointer) = reference.strip_prefix('#') else {
+        return node;
+    };
+    root.pointer(pointer).unwrap_or(node)
+}
+
 /// How to ask for one variant: the discriminator field and the value that
 /// selects it (`mode = query`), since that key is what the caller must send.
 fn variant_label(branch: &serde_json::Value, discriminator: Option<&str>) -> Option<String> {
@@ -1666,6 +1706,77 @@ mod tests {
         assert_eq!(row(&rows, "mode"), ["mode", "query", "yes", "-", "-"]);
     }
 
+    /// The same two forms, hoisted into `$defs` and referenced — the encoding
+    /// a discriminated union gets by default, and the one the test above
+    /// cannot distinguish from an inlined response because its body has no
+    /// `$defs` at all.
+    ///
+    /// Left unfollowed, a `$ref` branch has no `properties`: `field_rows`
+    /// returns nothing, `variant_label` finds neither a `const` nor a title,
+    /// and the section prints as two unlabelled empty forms while the family
+    /// index shows a dash for required — the field reference reporting that
+    /// the family with the most to explain takes no fields.
+    #[test]
+    fn a_selector_whose_forms_are_refs_renders_like_one_whose_forms_are_inline() {
+        let reference: FamilyReference =
+            serde_json::from_str(crate::client::ingest::FAMILY_REFERENCE_REF_SELECTOR_BODY)
+                .expect("the pinned family reference decodes");
+        let variants = schema_variants(&reference.selector_schema);
+        assert_eq!(variants.len(), 2, "both forms must be described");
+
+        // The `discriminator` is on the root and the `const` answering it is a
+        // hop away in `$defs`, so a label at all means the branch was followed.
+        let (tables_label, tables) = &variants[0];
+        assert_eq!(tables_label.as_deref(), Some("mode = tables"));
+        let rows = field_rows(tables);
+        assert_eq!(
+            row(&rows, "tables"),
+            [
+                "tables",
+                "string[]",
+                "yes",
+                "-",
+                "Source tables to read. Each lands in a destination table of the same name."
+            ]
+        );
+        assert_eq!(row(&rows, "mode"), ["mode", "tables", "no", "tables", "-"]);
+
+        let (query_label, query) = &variants[1];
+        assert_eq!(query_label.as_deref(), Some("mode = query"));
+        assert_eq!(
+            row(&field_rows(query), "sql"),
+            ["sql", "string", "yes", "-", "-"]
+        );
+
+        // Each form keeps its own required set through the indirection, which
+        // is the cell the family index prints for the whole family.
+        assert_eq!(
+            required_cell(&reference.selector_schema),
+            "tables, mode, sql"
+        );
+    }
+
+    #[test]
+    fn a_ref_this_document_cannot_answer_leaves_the_branch_alone() {
+        // Resolution is best effort by design: a pointer into a `$defs` that
+        // is not there, and a `$ref` to another document, both render the way
+        // they did before any ref was followed rather than failing the whole
+        // command. An unfamiliar schema costs the section, not the process.
+        for unresolvable in [
+            serde_json::json!({"oneOf": [{"$ref": "#/$defs/Absent"}]}),
+            serde_json::json!({"oneOf": [{"$ref": "https://example.invalid/s.json"}]}),
+        ] {
+            let variants = schema_variants(&unresolvable);
+            assert_eq!(variants.len(), 1);
+            assert!(variants[0].0.is_none());
+            assert!(field_rows(variants[0].1).is_empty());
+        }
+        // A schema carrying no `$ref` is returned untouched, so the ordinary
+        // path is not paying for any of this.
+        let plain = serde_json::json!({"properties": {"a": {"type": "string"}}});
+        assert_eq!(field_rows(schema_variants(&plain)[0].1).len(), 1);
+    }
+
     /// The destination is per-family, and a family that describes one is
     /// carried through the passthrough map rather than a field of the CLI's:
     /// which of `table` / `table_prefix` a family takes is the service's
 
@@ -1631,6 +1631,58 @@ mod tests {
         assert_eq!(p.limit, Some(5));
     }
 
+    #[test]
+    fn select_reads_the_same_query_laid_out_across_lines() {
+        // SQL pasted out of a script or a heredoc arrives across lines, and
+        // every keyword match in `parse_select` looks for a literal
+        // single-space form — "SELECT ", " FROM ", " LIMIT ". They see any of
+        // this only because whitespace is collapsed BEFORE the first of them
+        // runs.
+        //
+        // The two layouts below are the ones that pin that, and the obvious
+        // pretty-printed query is not among them: an INDENTED continuation
+        // parses even uncollapsed, because the indent happens to supply the
+        // space the search wanted — "\n  FROM " contains " FROM ". A test
+        // written the natural way would stay green with the collapse deleted.
+        // What actually breaks is a line break with nothing after it: a
+        // keyword at column zero, and a break straight after SELECT.
+        //
+        // Each assertion is equality with the single-line form rather than a
+        // bare `is_ok`, so it also pins that layout moves no clause boundary —
+        // a `WHERE` predicate silently gaining or losing its last word would
+        // pass an `is_ok` and reach the source engine.
+        let across_lines =
+            parse_select("SELECT id, status\nFROM public.orders\nWHERE status = 'open'\nLIMIT 5")
+                .unwrap();
+        assert_eq!(
+            across_lines,
+            parse_select("SELECT id, status FROM public.orders WHERE status = 'open' LIMIT 5")
+                .unwrap()
+        );
+        // Uncollapsed this one fails the `starts_with("SELECT ")` prefix
+        // rather than the FROM search, so it covers the other keyword match
+        // and the other error message.
+        assert_eq!(
+            parse_select("SELECT\n\t*\n\tFROM orders").unwrap(),
+            parse_select("SELECT * FROM orders").unwrap()
+        );
+        // Tabs and ragged indentation land on the same parse, which is the
+        // form someone actually pastes.
+        assert_eq!(
+            parse_select(
+                "SELECT id,\n\tstatus\n  FROM public.orders\n  WHERE status = 'open'\n  LIMIT 5"
+            )
+            .unwrap(),
+            across_lines
+        );
+        // Collapsing is not a licence to accept more: a query genuinely
+        // missing a clause is still rejected, and for the right reason.
+        assert!(
+            parse_select("SELECT\n  1\n").unwrap_err().contains("FROM"),
+            "a multi-line SELECT with no FROM must still be rejected as such"
+        );
+    }
+
     #[test]
     fn select_does_not_mistake_the_word_limit_inside_a_predicate() {
         // "LIMIT" in a string literal is not a LIMIT clause: only a trailing
 
@@ -8,17 +8,32 @@ use std::process::Command;
 fn hotdata() -> Command {
     let mut cmd = Command::new(env!("CARGO_BIN_EXE_hotdata"));
     // ISOLATED FROM THE MACHINE RUNNING THE TEST. A spawned process inherits
-    // this one's environment, so without these two the assertions below run
-    // against whatever profile the developer happens to be logged into — and
-    // the failure that produces is invisible locally and only shows up in CI,
-    // which is the one place nobody is watching a test they just wrote.
+    // this one's environment, so without the four lines below the assertions
+    // run against whatever profile the developer happens to be logged into —
+    // and the failure that produces is invisible locally and only shows up in
+    // CI, which is the one place nobody is watching a test they just wrote.
     //
     // That is not hypothetical: three tests here asserted a retired verb's
     // explanation and passed on a laptop with a default workspace, while CI
     // had none and got an auth error instead.
+    //
+    // HOTDATA_WORKSPACE is the variable that locks a workspace, and it locks
+    // it hard: it outranks an explicit --workspace-id rather than merely
+    // supplying a default, so a developer with it exported would drive every
+    // command here past the resolution these tests exist to observe. A name
+    // that is nearly it clears nothing while looking like it clears
+    // everything, which is the worst of the three outcomes.
+    //
+    // The working directory is isolation too, not housekeeping. The binary
+    // loads a .env from its own cwd and the directories above it at startup,
+    // which is after this env_remove — so under `cargo test`, where the cwd is
+    // the crate root, a .env there would hand the key straight back. The empty
+    // config dir is a directory no .env is in, so pointing the child at it
+    // closes that and any stray file further up.
     cmd.env("HOTDATA_CONFIG_DIR", config_dir());
     cmd.env_remove("HOTDATA_API_KEY");
-    cmd.env_remove("HOTDATA_WORKSPACE_ID");
+    cmd.env_remove("HOTDATA_WORKSPACE");
+    cmd.current_dir(config_dir());
     cmd
 }