docs(units): a create may name its unit by unitExternalId alone

docs/guides/work-with-units.mdx

@@ -44,11 +44,23 @@ for u in api.units.list().await?.get_items() {
 
 ## Tag a series with a unit
 
-A series carries two unit fields. `unit` is required free text of at most 64 characters, the
-label a chart shows (`bar`, `°C`); it is never checked against the catalogue. `unitExternalId`
-is optional and is the catalogue key (`pressure_bar`); set it when a consumer should be able to
-resolve the unit's symbol, quantity and conversion. The unit leaves the value type alone (the Python
-and Rust examples set `float`); it describes what the numbers mean.
+A series carries two unit fields. `unit` is free text of at most 64 characters, the label a
+chart shows (`bar`, `°C`). `unitExternalId` is the catalogue key (`pressure_bar`); set it when a
+consumer should be able to resolve the unit's symbol, quantity and conversion. A create needs at
+least one of them:
+
+| You send | Result |
+| --- | --- |
+| `unitExternalId` only | Accepted if the catalogue has it; `unit` is filled from the entry's symbol (its name if it has no symbol). |
+| `unit` and `unitExternalId` | Both kept as sent, as long as the catalogue has the `unitExternalId`. |
+| `unit` only | Accepted as is; the catalogue is not consulted. |
+| A blank `unitExternalId`, or one the catalogue does not have | `400`, with a field error on `unitExternalId`, whether or not `unit` is set. |
+| Neither | `400`. |
+
+The lookup normalises the id to lower snake_case first, so `Temperature_Deg_C` finds
+`temperature_deg_c`. An update that sets `unitExternalId` is checked the same way before
+anything is written; clearing it with `setNull` is still allowed. The unit leaves the value type
+alone (the Python and Rust examples set `float`); it describes what the numbers mean.
 
 <Tabs groupId="lang">
 <TabItem value="java" label="Java">

docs/mcp-server.mdx

@@ -177,7 +177,7 @@ neighbour ("the time series measuring this pump").
 | `timeseries_list` | Browse when you do not yet have a search term |
 | `timeseries_search` | Full-text search over name, externalId and description, ranked by relevance |
 | `timeseries_get` | Look up by externalId or numeric id |
-| `timeseries_create` | Create one time series, returns the assigned id. Needs a `unit` or a `unitExternalId` (see `unit_list`) |
+| `timeseries_create` | Create one time series, returns the assigned id. Needs a `unit` or a `unitExternalId`; a `unitExternalId` must be in the catalogue (see `unit_list`) |
 | `timeseries_update` | Update common fields by id |
 | `timeseries_delete` | Delete the definition. Existing datapoints are not removed |
 | `timeseries_get_latest` | Most recent datapoint, for "what is it reading now?" |

docs/reference/timeseries.md

@@ -57,6 +57,11 @@ api.time_series.create_one(&ts).await?;
 </TabItem>
 </Tabs>
 
+A create needs a `unit` (free text), a `unitExternalId` from the [unit catalogue](./units), or
+both. Given only `unitExternalId`, the series gets its `unit` from the catalogue entry; a
+`unitExternalId` the catalogue does not have is a `400` on that field.
+[Tag a series with a unit →](../guides/work-with-units#tag-a-series-with-a-unit)
+
 ## Value types
 
 Every series has a **value type** that decides how its datapoints are stored. A create that
@@ -369,7 +374,9 @@ set and everything beneath it in the `BELONGS_TO` hierarchy. Anything narrower b
 `POST /timeseries/update` changes fields on series that already exist. It is a partial update:
 only the fields named in each entry's `update` block change, and the series is identified by
 `id` or `externalId`. Changing `valueType` on a series that already holds data is refused,
-because the stored points would no longer parse; create a new series instead.
+because the stored points would no longer parse; create a new series instead. Setting
+`unitExternalId` to a blank value or one the [unit catalogue](./units) does not have is a `400`
+on `unitExternalId`, before anything is written; `setNull` still clears it.
 
 ```java
 import ai.intellistream.datahub.timeseries.UpdateTimeseries;