harden media

README.docker.md

@@ -75,15 +75,15 @@ Supporting scripts:
 
 ## Environment Variables
 
-### “Mock vs Real” (Website & API)
+### "Mock vs Real" (Website & API)
 
 There is **no** `AUTOMATION_MODE` equivalent for the Website/API runtime.
 
-- **Website “mock vs real”** is controlled purely by *which API base URL you point it at* via [`getWebsiteApiBaseUrl()`](apps/website/lib/config/apiBaseUrl.ts:6):
+- **Website "mock vs real"** is controlled purely by *which API base URL you point it at* via [`getWebsiteApiBaseUrl()`](apps/website/lib/config/apiBaseUrl.ts:6):
   - Browser calls use `NEXT_PUBLIC_API_BASE_URL`
   - Server/Next.js calls use `API_BASE_URL ?? NEXT_PUBLIC_API_BASE_URL`
 
-- **API “mock vs real”** is controlled by API runtime env:
+- **API "mock vs real"** is controlled by API runtime env:
   - Persistence: `GRIDPILOT_API_PERSISTENCE=postgres|inmemory` in [`AppModule`](apps/api/src/app.module.ts:25)
   - Optional bootstrapping: `GRIDPILOT_API_BOOTSTRAP=0|1` in [`AppModule`](apps/api/src/app.module.ts:35)
 
@@ -103,7 +103,7 @@ The website talks to the API via `fetch()` in [`BaseApiClient`](apps/website/lib
 - The **browser** must be pointed at a host-accessible API URL via `NEXT_PUBLIC_API_BASE_URL`
 - The **server** (Next.js / Node) must be pointed at a container-network API URL via `API_BASE_URL` (when running in Docker)
 
-The single source of truth for “what base URL should I use?” is [`getWebsiteApiBaseUrl()`](apps/website/lib/config/apiBaseUrl.ts:6):
+The single source of truth for "what base URL should I use?" is [`getWebsiteApiBaseUrl()`](apps/website/lib/config/apiBaseUrl.ts:6):
 - Browser: reads `NEXT_PUBLIC_API_BASE_URL`
 - Server: reads `API_BASE_URL ?? NEXT_PUBLIC_API_BASE_URL`
 - In Docker/CI/test: throws if missing (no silent localhost fallback)
@@ -122,13 +122,13 @@ This stack is intended for deterministic smoke tests and uses different host por
 - `NEXT_PUBLIC_API_BASE_URL=http://localhost:3101` (browser → host port)
 - `API_BASE_URL=http://api:3000` (website container → api container)
 
-Important: the test stack’s API is a mock server defined inline in [`docker-compose.test.yml`](docker-compose.test.yml:24). It exists to validate Website ↔ API wiring, not domain correctness.
+Important: the test stack's API is a mock server defined inline in [`docker-compose.test.yml`](docker-compose.test.yml:24). It exists to validate Website ↔ API wiring, not domain correctness.
 
 #### Troubleshooting
 - If `docker:dev` is running, use `npm run docker:dev:down` before `npm run test:docker:website` to avoid port conflicts.
 - If Docker volumes get stuck, run `npm run docker:test:down` (it uses `--remove-orphans` + `rm -f`).
 
-### API “Real vs In-Memory” Mode
+### API "Real vs In-Memory" Mode
 
 The API can now be run either:
 - **postgres**: loads [`DatabaseModule`](apps/api/src/domain/database/DatabaseModule.ts:1) (requires Postgres)
@@ -227,6 +227,57 @@ docker-compose -f docker-compose.dev.yml logs -f website
 docker-compose -f docker-compose.dev.yml logs -f db
 ```
 
+### Database Migration for Media References
+
+If you have existing seeded data with old URL formats (e.g., `/api/avatar/{id}`, `/api/media/teams/{id}/logo`), you need to migrate to the new `MediaReference` format.
+
+#### Option 1: Migration Script (Preserve Data)
+
+Run the migration script to convert old URLs to proper `MediaReference` objects:
+
+```bash
+# Test mode (dry run - shows what would change)
+npm run migrate:media:test
+
+# Execute migration (applies changes)
+npm run migrate:media:exec
+```
+
+The script handles:
+- **Driver avatars**: `/api/avatar/{id}` → `system-default` (deterministic variant)
+- **Team logos**: `/api/media/teams/{id}/logo` → `generated`
+- **League logos**: `/api/media/leagues/{id}/logo` → `generated`
+- **Unknown formats** → `none`
+
+#### Option 2: Wipe and Reseed (Clean Slate)
+
+For development environments, you can wipe all data and start fresh:
+
+```bash
+# Stop services and remove volumes
+npm run docker:dev:clean
+
+# Rebuild and start fresh
+npm run docker:dev:build
+```
+
+This will:
+- Delete all existing data
+- Run fresh seed with correct `MediaReference` format
+- No migration needed
+
+#### When to Use Each Option
+
+**Use Migration Script** when:
+- You have production data you want to preserve
+- You want to understand what changes will be made
+- You need a controlled, reversible process
+
+**Use Wipe and Reseed** when:
+- You're in development/testing
+- You don't care about existing data
+- You want the fastest path to a clean state
+
 ## Tips
 
 1. **First time setup**: Use `docker:dev:build` to ensure images are built