From 42a86fd7fa0e2c221f6e1d2579470daefa47e33a Mon Sep 17 00:00:00 2001
From: imeepos <imeepos@outlook.com>
Date: Wed, 10 Jun 2026 03:48:54 -0700
Subject: [PATCH] docs: document auth migration workflow

---
 docs/auth-migrations.md | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)
 create mode 100644 docs/auth-migrations.md

diff --git a/docs/auth-migrations.md b/docs/auth-migrations.md
new file mode 100644
index 0000000..0814c08
--- /dev/null
+++ b/docs/auth-migrations.md
@@ -0,0 +1,35 @@
+# Auth Migrations
+
+This project uses Better Auth CLI to generate SQLite-compatible SQL for Cloudflare D1, then uses Wrangler to apply the SQL as D1 migrations.
+
+## Generate
+
+Run this after changing Better Auth options or plugins that affect persistence:
+
+```bash
+pnpm db:generate
+```
+
+Review the generated SQL in:
+
+```text
+migrations/0001_better_auth_account_center.sql
+```
+
+## Check
+
+CI and local readiness use:
+
+```bash
+pnpm db:check
+```
+
+This command generates SQL into a temporary file with Better Auth CLI and compares it with the committed migration file.
+
+## Apply Locally
+
+```bash
+pnpm db:apply:local
+```
+
+Do not use `auth migrate` for D1. D1 migrations are applied by Wrangler so local and remote environments use the same migration history.