diff --git a/docs/release-notes/v0.2.2.md b/docs/release-notes/v0.2.2.md
new file mode 100644
index 0000000..4ed0e3e
--- /dev/null
+++ b/docs/release-notes/v0.2.2.md
@@ -0,0 +1,64 @@
+# TiDB Cloud CLI v0.2.2
+
+This release adds complete TiDB Cloud Filesystem token lifecycle management and makes `--output text` reliable across structured commands.
+
+## What's new
+
+- A Filesystem can now have multiple independently managed owner and scoped tokens for machines, CI jobs, and agent sandboxes. New commands generate, list, enable, disable, delete, and refresh tokens.
+- Owner tokens retain full Filesystem access. Scoped tokens can be restricted to selected paths and `read`, `list`, `search`, `write`, or `delete` operations, and the Filesystem backend enforces those boundaries.
+- `TI_FS_TOKEN` and `--fs-token` accept either owner or scoped credentials. Scoped tokens can refresh themselves but cannot issue child tokens or manage token inventory.
+- Token plaintext is returned only when generated or refreshed. `--store-locally` can select a returned token in the local credential registry, while externally supplied tokens remain under the caller's secret-management control.
+- Token-changing operations detect active local mounts and require them to be drained and unmounted first, reducing the risk of invalidating a running mount.
+- Structured commands now provide deterministic text tables or key-value output. `--output text` no longer silently falls back to JSON, and queried scalar lists render one value per line.
+
+## Upgrade from v0.2.1
+
+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.2/install.sh | sh -s -- --yes
+export PATH="$HOME/.ti/bin:$PATH"
+ti --version
+```
+
+## Manage Filesystem tokens
+
+Generate an additional owner token and retain its one-time plaintext response:
+
+```bash
+umask 077
+ti fs generate-file-system-token \
+  --file-system-id "<file-system-id>" \
+  --token-name ci-deploy \
+  --ttl 24h > ./ci-token.json
+ti fs list-file-system-tokens --file-system-id "<file-system-id>" --output text
+```
+
+Use an owner token to issue a path-and-operation-limited token for an agent sandbox:
+
+```bash
+export TI_FS_TOKEN="<owner-fs-token>"
+ti fs generate-file-system-scoped-token \
+  --subject sandbox-agent \
+  --ttl 24h \
+  --allow /workspace:read,list,write \
+  --allow /artifacts:read,list
+```
+
+Use immutable token IDs from the list response for lifecycle operations:
+
+```bash
+ti fs disable-file-system-token --file-system-id "<file-system-id>" --token-id "<token-id>"
+ti fs enable-file-system-token --file-system-id "<file-system-id>" --token-id "<token-id>"
+ti fs delete-file-system-token --file-system-id "<file-system-id>" --token-id "<token-id>"
+```
+
+Authentication changes can take several seconds to converge. For shared environments, distribute and validate a replacement token before disabling or deleting the previous token.