From 165871998a62f0c90bc3d9308566da9010da7a8f Mon Sep 17 00:00:00 2001
From: Cheese <cheese.javaee@gmail.com>
Date: Tue, 11 Aug 2026 17:04:46 +0800
Subject: [PATCH] docs: add v0.2.1 release notes

---
 docs/release-notes/v0.2.1.md | 59 ++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)
 create mode 100644 docs/release-notes/v0.2.1.md

diff --git a/docs/release-notes/v0.2.1.md b/docs/release-notes/v0.2.1.md
new file mode 100644
index 0000000..dbcf058
--- /dev/null
+++ b/docs/release-notes/v0.2.1.md
@@ -0,0 +1,59 @@
+# TiDB Cloud CLI v0.2.1
+
+This release makes TiDB Cloud Filesystem inventory portable across machines and removes client-side TiDB Cloud Project selection from Starter database workflows.
+
+## What's new
+
+- `ti fs list-file-systems` now reads the remote Drive9 inventory by using the configured TiDB Cloud API keys. Filesystems are identified by their server-assigned `file_system_id` instead of a client-only name.
+- Filesystem create returns the server-assigned ID and owner token. Local state stores only known tokens and routing hints keyed by that ID; remote inventory remains authoritative for resource existence and status.
+- `ti fs import-file-system-token` imports an existing owner token on another machine. Because the token contains its Filesystem ID, data-plane and mount commands can also run in a clean sandbox with `TI_FS_TOKEN` and `TI_REGION_CODE` only.
+- `ti configure` now validates and stores local input without making a TiDB Cloud API request. Authentication and authorization errors are reported by the first remote command that uses the configured keys.
+- Starter cluster creation no longer accepts `--project-id`, reads a saved project default, or sends project-selection labels. TiDB Cloud selects the server-side default project, while project metadata returned by TiDB Cloud remains unchanged in command output.
+- The `ti organization list-projects` command and its project-read permission are removed.
+
+## Breaking changes and migration
+
+Filesystem commands that select an existing resource now use `--file-system-id` or `TI_FS_FILE_SYSTEM_ID`. `ti fs create-file-system` no longer accepts a user-defined Filesystem name. Existing complete name-keyed local credentials are migrated to the ID-keyed credential store without deleting the legacy source.
+
+Existing `project_id` values in `~/.ti/config` are ignored immediately. Running `ti configure` for that profile removes its legacy project value while preserving other profiles.
+
+## Upgrade from v0.2.0
+
+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.1/install.sh | sh -s -- --yes
+export PATH="$HOME/.ti/bin:$PATH"
+ti --version
+```
+
+## Updated workflows
+
+Configure and create a Starter cluster without selecting a project:
+
+```bash
+ti configure
+ti db create-db-cluster --db-cluster-type starter --db-cluster-name my-app-db --wait
+```
+
+Inspect remote Filesystems and select one for subsequent commands:
+
+```bash
+ti fs list-file-systems --output text
+export TI_FS_FILE_SYSTEM_ID="<file-system-id>"
+ti fs check-file-system
+```
+
+Provision a Filesystem and retain the one-time owner token returned in the JSON result:
+
+```bash
+ti fs create-file-system --wait
+```