diff --git a/CLAUDE.md b/CLAUDE.md
index d305927..ff204b8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -61,9 +61,27 @@ Fall back to Grep/Glob/Read **only** when the graph doesn't cover what you need.
 
 - `prisma/schema.prisma` is the source of truth for the `conversion_jobs` schema; `prisma/migrations/` is its version history. `db/schema.sql` no longer exists.
 - Prisma CLI commands (`prisma migrate dev`, `prisma migrate deploy`, `prisma generate`) need `DATABASE_URL` in their own process environment, separate from the app. Compute it from the same `DB_HOST`/`DB_USER`/`DB_PASSWORD`/`DB_NAME` values used for local tests, via `node scripts/printDatabaseUrl.js` — never write `DATABASE_URL` into `.env` or `.env.local`.
-- To create a new migration locally after editing `prisma/schema.prisma`:
+- **`prisma migrate dev` does NOT work against the local dev DB** — verified by actually running it (`DATABASE_URL=$(node scripts/printDatabaseUrl.js) npx prisma migrate dev --name test_shadow_db_probe`). It needs to create/drop a temporary shadow database to detect schema drift, and the local `convert_user` does not have `CREATE DATABASE`/`DROP DATABASE` privileges, so it fails immediately with:
+  ```
+  Error: P3014
+  Prisma Migrate could not create the shadow database. Please make sure the database user has permission to create databases.
+  Original error: Error code: P1010
+  User was denied access on the database `prisma_migrate_shadow_db_...`
+  ```
+  No migration folder is created when it fails this way (it errors before writing anything), so nothing needs cleaning up afterward. Do not use `migrate dev` in this project until `convert_user`'s privileges change.
+- To create a new migration locally after editing `prisma/schema.prisma`, use the shadow-database-free fallback instead (the same pattern Task 3 used for the `0_init` baseline):
   ```
   DB_HOST=127.0.0.1 DB_USER=convert_user DB_PASSWORD=change_me DB_NAME=file_converter STORAGE_DIR=./storage \
-    DATABASE_URL=$(node scripts/printDatabaseUrl.js) npx prisma migrate dev --name <description>
+    DATABASE_URL=$(node scripts/printDatabaseUrl.js) npx prisma migrate diff \
+    --from-migrations prisma/migrations --to-schema-datamodel prisma/schema.prisma --script > migration.sql
+  ```
+  Review `migration.sql`, then manually create the next `prisma/migrations/<timestamp>_<description>/migration.sql` folder with that content, and mark it applied without executing it (since you'll apply it for real via `migrate deploy` or by hand):
+  ```
+  DATABASE_URL=$(node scripts/printDatabaseUrl.js) npx prisma migrate resolve --applied <timestamp>_<description>
   ```
 - To apply pending migrations in production: with the real `DB_*` values loaded from `.env`, run `DATABASE_URL=$(node scripts/printDatabaseUrl.js) npx prisma migrate deploy` before starting the app.
+- **ONE-TIME step, required before the very first `migrate deploy` against any environment whose `conversion_jobs` table predates Prisma** (this includes o2switch production, which still has the table created by hand from the now-deleted `db/schema.sql`, but no `_prisma_migrations` tracking table): do **not** run `migrate deploy` first. Instead, baseline that environment exactly like Task 3 did locally:
+  ```
+  DATABASE_URL=$(node scripts/printDatabaseUrl.js) npx prisma migrate resolve --applied 0_init
+  ```
+  This tells Prisma that `0_init` is already applied (the table already exists) without trying to `CREATE TABLE` it again. Run this once, ever, per environment — after that, `migrate deploy` is the correct command for all subsequent deployments to that environment. Running `migrate deploy` first (without this baseline step) against such an environment will fail with a MySQL "table already exists" error and leave Prisma's migration history in a failed state requiring manual recovery.
diff --git a/README.md b/README.md
index 6816611..a465ab6 100644
--- a/README.md
+++ b/README.md
@@ -3,8 +3,8 @@
 ## Local development
 
 1. Copy `.env.example` to `.env` and fill in your local MariaDB credentials.
-2. Apply the schema: `mysql -h <host> -u <user> -p <database> < db/schema.sql`
-3. Install dependencies: `npm install`
+2. Install dependencies: `npm install`
+3. Export those same `DB_HOST`/`DB_USER`/`DB_PASSWORD`/`DB_NAME` values from `.env` into your shell, then apply the schema with Prisma Migrate (creates the `conversion_jobs` table fresh, since a new local database starts empty): `DATABASE_URL=$(node scripts/printDatabaseUrl.js) npx prisma migrate deploy`
 4. Run the API: `npm start`
 5. Run the worker (separate terminal): `npm run worker`
 6. Run tests: `npm test` (requires the same MariaDB reachable via your `.env` vars, exported into the shell)
@@ -19,4 +19,7 @@
 6. Add a cPanel cron job to run the cleanup script periodically, e.g. every 15 minutes:
    `*/15 * * * * cd /home/gaan6043/convert.ombrora.com-node && /home/gaan6043/nodevenv/convert.ombrora.com-node/24/bin/node src/cleanup.js > /dev/null`
    (adjust the path and node binary location to match your actual account — check with `which node` over SSH).
-7. On every subsequent deployment: pull changes, `npm install`, `npm run build` (frontend), then restart the Passenger app from cPanel and `pm2 restart convert-worker`.
+7. **ONE-TIME, before ever running `prisma migrate deploy` on this server:** the o2switch database already has the `conversion_jobs` table (created by hand, before this project used Prisma), but no `_prisma_migrations` tracking table. Running `migrate deploy` first would try to `CREATE TABLE conversion_jobs` again and fail with a "table already exists" MySQL error, leaving Prisma's migration history stuck and needing manual recovery. Avoid that by baselining the existing table once, ever, on this server, before step 8's `migrate deploy` runs for the first time:
+   `DATABASE_URL=$(node scripts/printDatabaseUrl.js) npx prisma migrate resolve --applied 0_init`
+   Do **not** repeat this step on later deployments — after this one-time run, `migrate deploy` (step 8) is the correct command going forward.
+8. On every subsequent deployment: pull changes, `npm install`, apply any pending migrations with `DATABASE_URL=$(node scripts/printDatabaseUrl.js) npx prisma migrate deploy`, `npm run build` (frontend), then restart the Passenger app from cPanel and `pm2 restart convert-worker`.