diff --git a/docs/release-notes/v0.2.3.md b/docs/release-notes/v0.2.3.md
new file mode 100644
index 0000000..1301a0f
--- /dev/null
+++ b/docs/release-notes/v0.2.3.md
@@ -0,0 +1,55 @@
+# TiDB Cloud CLI v0.2.3
+
+This release moves TiDB Cloud Filesystem resource inventory and lifecycle management onto the TiDB Cloud control plane, adds organization-visible metadata, and makes Filesystem region and mount behavior more predictable.
+
+## What's new
+
+- `ti fs create-file-system`, `list-file-systems`, `describe-file-system`, and `delete-file-system` now use the typed TiDB Cloud Filesystem tenant API. Remote inventory is authoritative and remains selected by immutable `file_system_id`.
+- Filesystem creation accepts an optional display name and repeatable labels. List supports display-name and exact-label filters, while list and describe expose status, labels, quota usage, and whether the current machine has a local token without revealing token plaintext.
+- TiDB Cloud Filesystem endpoint mappings for `aws-us-east-1`, `aws-ap-southeast-1`, `aws-us-west-2`, and `alicloud-ap-southeast-1` are built into `ti`. Runtime commands and installers no longer depend on downloading a Drive9 region manifest.
+- Alibaba Cloud placement now uses the canonical `alicloud-ap-southeast-1` code. Existing local credentials using the legacy `ali-ap-southeast-1` code remain usable.
+- Successful background mounts now return the structured `ti` result without raw Drive9 startup or misleading unmount guidance. Foreground mounts still stream companion output, and failed background mounts retain their diagnostic log path.
+- Installer output is shorter and command help fixes several visible wording and spacing errors.
+
+## Upgrade from v0.2.2
+
+Drain and unmount active Filesystem mounts before replacing `ti` and its bundled `ti-drive9` companion, then run:
+
+```bash
+ti update --check
+ti update
+ti --version
+```
+
+New installations can use:
+
+```bash
+curl -fsSL https://github.com/tidbcloud/ti-cli/releases/download/v0.2.3/install.sh | sh -s -- --yes
+export PATH="$HOME/.ti/bin:$PATH"
+ti --version
+```
+
+## Manage Filesystem metadata
+
+Create a Filesystem with organization-visible metadata and wait for it to become ready:
+
+```bash
+FILE_SYSTEM_ID="$(ti fs create-file-system \
+  --display-name agent-workspace \
+  --label environment=development \
+  --wait \
+  --query file_system_id \
+  --output text)"
+```
+
+Filter remote inventory and inspect the selected resource:
+
+```bash
+ti fs list-file-systems \
+  --display-name agent-workspace \
+  --label environment=development \
+  --output text
+ti fs describe-file-system --file-system-id "$FILE_SYSTEM_ID" --output text
+```
+
+Display names and labels are metadata only. Continue to use `--file-system-id`, `TI_FS_FILE_SYSTEM_ID`, or an explicitly supplied Filesystem token to select a resource.