Document prod schema migrate before restore and i18n search index fix.

Release runbook now describes default migrateProdSchema, auto-migrate safety guard, and troubleshooting for updated_at restore failures; i18n docs cover partial entity_translations index.

Co-authored-by: Cursor <cursoragent@cursor.com>

Documentation/deploy-dev-to-prod.md

@@ -34,10 +34,10 @@ For a typical weekly release, use the orchestrator instead of running each step
 
 2. Edit [`infra/deploy/devtoprod.config.json`](../infra/deploy/devtoprod.config.json) (gitignored — safe for SMB password):
    - `profile`: `full` | `code` | `data` (base step set; individual `steps` overrides win)
+   - `steps` — per-step overrides; see table below. On **`full`** profile, `migrateProdSchema` is **on by default** (runs `dev:migrate` on `gallery_prod` before restore).
    - `autoConfirm`: `true` skips restore/image-sync prompts (`CONFIRM_PROD=1`, `-SkipConfirm`)
    - `autoStartDevStack`: `true` starts `dev:server` (or `dev:web`) automatically when `validateBuild` finds API down
    - `git.message`, `git.branch` — used when `gitCommitPush` is enabled
-   - `schemaChanged`: `true` enables prod schema migration on `full` profile
    - `smb.user` / `smb.password` — optional; maps `\\host\share` before image sync
    - `backupFile` — optional fixed path; otherwise uses the newest `gallery_dev_data_*.txt` after backup
 
@@ -67,7 +67,7 @@ npm run devtoprod:release -- -DryRun
 | `thumbnails` | Step 2 — `devtoprod:thumbnails` |
 | `backupDev` | Step 3 — `dev:db:backup` |
 | `backupProd` | Step 3 (rollback) — `prod:db:backup` |
-| `migrateProdSchema` | Step 4 — `dev:migrate` on `gallery_prod` |
+| `migrateProdSchema` | Step 4 — `dev:migrate` on `gallery_prod` (enabled on `full` profile; auto-runs before `restoreProd` if you disabled it but left restore on) |
 | `restoreProd` | Step 5 — `devtoprod:db:restore` |
 | `syncImages` | Step 6 — `devtoprod:images` |
 | `dockerPublish` | Step 7 — `prod:docker:publish` (auto tag: `YYYYMMDD-HHMMSS-<gitsha>` + push `latest`) |
@@ -90,13 +90,13 @@ Use the manual steps below when you need a **partial** release or want to inspec
 
 ## What changed → which steps to run
 
-Run only the steps that match what you changed. Steps are independent except that **code** needs a rebuilt image and **schema changes** must be applied before a **data** restore.
+Run only the steps that match what you changed. Steps are independent except that **code** needs a rebuilt image and **prod schema must match the dev backup** before a data restore (Step 4 before Step 5).
 
 | You changed… | Required steps |
 |--------------|----------------|
 | Application code (client/server) | 0 → 1 → 7 → 8 → 9 |
 | DB schema (new `db/migrate-*.sql`, `schema.sql`) | 0 → 1 → 3 → **4** → (5 if data too) → 8 → 9 |
-| Catalog data (movements, artists, paintings, influences, bios) | 0 → 2 → 3 → 5 → 9 |
+| Catalog data (movements, artists, paintings, influences, bios) | 0 → 2 → 3 → **4** → 5 → 9 |
 | Image files (new/replaced paintings, portraits) | 0 → 2 → 3 → 5 → 6 → 9 |
 | Thumbnails only (rebuild from existing full images) | 0 → 2 → 3 → 5 → 6 → 9 |
 | Everything (typical weekly release) | 0 → 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 |
@@ -364,6 +364,7 @@ Keep at least the most recent `gallery_prod_data_*.txt` from Step 3 so a data ro
 - Prod DB scripts read **only** `infra/docker/.env.prod`; dev scripts refuse `_prod` database names.
 - Prod restore/backup require typing `yes` (or `CONFIRM_PROD=1` / `autoConfirm` in release config).
 - `npm run dev:migrate` targets whatever `DB_NAME` is set — always `Remove-Item Env:\DB_NAME` after Step 4 so later commands stay on dev.
+- **`restoreProd` safety:** if `migrateProdSchema` is disabled in config but `restoreProd` is enabled, the orchestrator runs Step 4 first so prod has columns/tables present in the dev backup (e.g. `updated_at`, `entity_translations`).
 - Deploy-related npm scripts and PowerShell helpers print a final **`===== SUCCESS: … =====`** or **`===== FAILED: … =====`** banner as the last line of output.
 
 ## Troubleshooting
@@ -373,6 +374,7 @@ Keep at least the most recent `gallery_prod_data_*.txt` from Step 3 so a data ro
 | `/api/bounds` returns `{"min_year":null,"max_year":null}` on prod | `gallery_prod` has schema but no data | Run Step 5 (restore); confirm rows with a count query on `art_movements` / `paintings` |
 | `robocopy ... ERROR 5 (0x00000005) Access is denied` on Step 6 | SMB share not mapped/authenticated in this Windows session | `net use \\192.168.10.122\Gallery /user:YOUR_TRUENAS_USER`, verify `Test-Path`, then re-run. If still denied after auth, fix TrueNAS dataset ACL (`chown -R 1001:1001`, grant the SMB user write) |
 | Restore: `permission denied to set parameter "session_replication_role"` | DB role is not superuser | Handled automatically (multi-pass insert). For the fast path, superuser runs `GRANT SET ON PARAMETER session_replication_role TO gallery;` |
+| Restore: `column "updated_at" of relation … does not exist` | Prod schema behind dev backup | Run Step 4 before Step 5; `full` profile enables `migrateProdSchema` by default; partial config with `restoreProd` alone also auto-migrates |
 | Restore: `unterminated quoted string` | Old parser split multi-line values (bios) | Fixed — statements are accumulated until quotes balance; update to latest `scripts/restore-db-data.js` |
 | `git push` → `Failed to authenticate user` (Gitea) | Git Credential Manager cached an expired token | Clear it: `"protocol=https`nhost=gitea.mysuperlab.netcraze.pro`n" \| git credential reject`, then push again to re-prompt |
 | Prod tables empty after a failed restore | Restore truncates **before** inserting; a mid-run error leaves tables empty | Dev is untouched — just re-run Step 5 |