diff --git a/docs/release-notes/v0.2.9.md b/docs/release-notes/v0.2.9.md
new file mode 100644
index 0000000..fb43a44
--- /dev/null
+++ b/docs/release-notes/v0.2.9.md
@@ -0,0 +1,45 @@
+# TiDB Cloud CLI v0.2.9
+
+This patch release addresses mount readiness and initial-synchronization errors that could still affect v0.2.8. It includes ti's background mount readiness fix and is intended for use with the published Drive9 build `a9acf30`.
+
+## Bug fixes
+
+- `ti fs mount-file-system` and `ti fs-vault mount-vault` now check that the mount is active and its root can be listed before reporting success. Readiness checks honor `--ready-timeout` (default: `30s`) and cancellation. If waiting fails, the background mount and its local locator are retained, and the error provides the matching unmount command. [ti #69](https://github.com/tidbcloud/ti-cli/pull/69)
+- The updated companion fixes an additional source of `EAGAIN` (`Resource temporarily unavailable`) during cold FUSE mounts: file lookups and attribute reads now retry once when they cross the first synchronization reset. The earlier companion build `c6e057f` handled this race for directory listings; this fix extends that handling to `Lookup` and `GetAttr`. [Drive9 #1013](https://github.com/mem9-ai/drive9/pull/1013)
+
+Successful readiness checks establish that the mount root is readable. They do not guarantee that every cold-file read or concurrent operation will succeed. Authentication failures, remote failures, cancellation, and subsequent synchronization resets retain their existing error handling.
+
+## Upgrade from v0.2.8
+
+Upgrade both ti and its companion to receive both fixes. Reinstalling v0.2.8 can refresh Drive9, but it does not add the ti readiness fix.
+
+Drain FUSE mounts and unmount all active Filesystem and Vault mounts before replacing the binaries. On macOS or Linux with a ti-owned installation, run:
+
+```bash
+ti update --check
+ti update --target-version v0.2.9
+ti --version
+"$(dirname "$(command -v ti)")/ti-drive9" version
+```
+
+New installations and reinstalls can use the version-specific installer:
+
+```bash
+curl -fsSL https://github.com/tidbcloud/ti-cli/releases/download/v0.2.9/install.sh | sh -s -- --version v0.2.9 --yes
+export PATH="$HOME/.ti/bin:$PATH"
+ti --version
+"$HOME/.ti/bin/ti-drive9" version
+```
+
+For a custom installation directory, pass `--install-dir` with that directory. On Windows, rerun the PowerShell installer because in-place self-update is unsupported:
+
+```powershell
+$script = "$env:TEMP\install-ti.ps1"
+iwr https://github.com/tidbcloud/ti-cli/releases/download/v0.2.9/install.ps1 -OutFile $script
+powershell -ExecutionPolicy Bypass -File $script -Version v0.2.9 -Yes
+$env:Path = "$HOME\.ti\bin;$env:Path"
+ti --version
+& "$HOME\.ti\bin\ti-drive9.exe" version
+```
+
+The companion is downloaded separately from mutable Drive9 endpoints. `a9acf30` identifies the upstream build used for release preparation, not a dependency pin. Record both installed versions when reporting an issue. Pinning or rolling back ti does not pin or roll back Drive9.