docs(changelog): uuidv7 canonical ids entry

changelog.mdx

@@ -7,6 +7,25 @@ description: "Stay up to date with the latest agentsfleet product updates, new f
   agentsfleet is in **stealth-mode testing** and pre-production. APIs and agent behavior may change between releases without long deprecation windows. Email [agentsfleet@agentmail.to](mailto:agentsfleet@agentmail.to) if you want a hand calibrating an agent or to join as a design partner.
 </Tip>
 
+<Update label="Jul 23, 2026" tags={["Breaking", "Bug fixes", "API", "CLI"]}>
+  ## An identifier has exactly one spelling
+
+  Every workspace, fleet, and event id is a lowercase Universally Unique Identifier version 7 (UUIDv7). An uppercase id used to be accepted, and the two spellings could then drift apart: the database read one record, while caches, deduplication keys, and plain string comparisons read two. The API and the `agentsfleet` CLI now reject a non-lowercase id.
+
+  ## API reference
+
+  - **Uppercase and mixed-case ids return `400`** — a request sending `0195B4BA-8D3A-7F13-…` where a `uuid` field is expected now fails with [`UZ-UUIDV7-009`](/api-reference/error-codes) instead of being silently normalized. Routes that validate the id inline answer the generic [`UZ-REQ-001`](/api-reference/error-codes) for the same input, so handle both. Every id the API returns is already lowercase, so anything echoing back a server-issued id is unaffected.
+  - **The CLI rejects the same shape** — `agentsfleet` checks id arguments before the request leaves your machine, so a miscased id fails immediately, not after a round trip.
+
+  ## Upgrading
+
+  - **Lowercase any identifier your code stores or builds itself.** Ids handed back by the API and the CLI are already lowercase, so echoing one straight back needs no change. Action is only required where your code uppercases an id, reads one from a system that upper-cases (some spreadsheet and logging pipelines do), or hard-codes one in a fixture or webhook URL. Those requests now fail with [`UZ-UUIDV7-009`](/api-reference/error-codes), or [`UZ-REQ-001`](/api-reference/error-codes) on routes that validate the id inline, rather than being accepted.
+
+  ## Bug fixes
+
+  - **A clock outside the representable range fails loudly** — minting an id on a host whose clock is set before 1970 now returns an error, instead of an id whose embedded timestamp is corrupted and sorts in the wrong place.
+</Update>
+
 <Update label="Jul 23, 2026" tags={["What's new", "Bug fixes", "API", "UI"]}>
   ## A struggling fleet explains itself