From 2e1def42c71fcf02d118bf54f66529cdfe3db343 Mon Sep 17 00:00:00 2001
From: Cheese <cheese.javaee@gmail.com>
Date: Wed, 9 Sep 2026 11:52:27 -0400
Subject: [PATCH] docs: add v0.2.4 release notes

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

diff --git a/docs/release-notes/v0.2.4.md b/docs/release-notes/v0.2.4.md
new file mode 100644
index 0000000..b928f85
--- /dev/null
+++ b/docs/release-notes/v0.2.4.md
@@ -0,0 +1,74 @@
+# TiDB Cloud CLI v0.2.4
+
+This release adds copy-on-write Filesystem layer workflows and tenant-scoped AI provider configuration, improves quota and authentication guidance, and tightens Filesystem authorization boundaries.
+
+## What's new
+
+- New `ti fs fork-layer`, `list-layer-chain`, and `delete-layer` commands support parallel copy-on-write workspaces, ancestry inspection, and explicit abandonment of rejected timelines.
+- `ti fs mount-file-system` can mount a writable layer or a read-only historical checkpoint through `--layer-ref` and `--checkpoint-id`. Existing checkpoint, diff, rollback, and commit commands complete the versioned workspace workflow.
+- New extract and embedding configuration commands let organization administrators inspect, enable, update, and disable tenant-scoped image, audio, video, and embedding providers. Provider secrets are accepted only through `TI_FS_AI_PROVIDER_API_KEY` and are never persisted or printed by `ti`.
+- Filesystem inventory now includes media quota fields returned by the service.
+- `ti fs create-file-system` recognizes structured free-plan quota errors and links directly to TiDB Cloud billing when a payment method is required.
+- Missing TiDB Cloud API credentials now include the API key creation URL in the actionable error.
+- Filesystem deletion and token administration consistently require TiDB Cloud API credentials. An FS token grants data-plane use and does not imply resource-administration permission.
+- Telemetry ingestion now stores events only in TiDB. Compatibility with both current `ti` and legacy `tdc` telemetry clients is retained.
+
+## Breaking change
+
+The public `--foreground` flag has been removed from `ti fs mount-file-system` and its `mount` alias. Mounts are background operations managed by `ti`; use `drain-file-system` and `unmount-file-system` to stop them safely.
+
+## Upgrade from v0.2.3
+
+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.4/install.sh | sh -s -- --yes
+export PATH="$HOME/.ti/bin:$PATH"
+ti --version
+```
+
+## Fork a versioned workspace
+
+Fork two independent child layers from a checkpoint and inspect one child's ancestry:
+
+```bash
+SEED="$(ti fs create-layer-checkpoint \
+  --layer-id research-base \
+  --checkpoint-id seed \
+  --label workspace-seed \
+  --query checkpoint_id \
+  --output text)"
+
+ti fs fork-layer \
+  --parent-layer-ref research-base \
+  --layer-name style-brief \
+  --checkpoint-id "$SEED"
+ti fs fork-layer \
+  --parent-layer-ref research-base \
+  --layer-name style-analyst \
+  --checkpoint-id "$SEED"
+ti fs list-layer-chain --layer-ref style-analyst
+```
+
+Mount a historical checkpoint for read-only comparison:
+
+```bash
+mkdir -p ./peek/v5
+ti fs mount-file-system \
+  --mount-path ./peek/v5 \
+  --remote-path /research/q3-market \
+  --driver fuse \
+  --layer-ref style-analyst \
+  --checkpoint-id v5
+```
+
+Checkpoint mounts require FUSE. Recursive `copy-file` and `--layer-id` remain mutually exclusive; seed a directory tree through a writable FUSE layer mount instead.
+