Initial commit of Descrybe v2 without local scratch artifacts.

Drop one-shot tmp/axe scripts and agent i18n scratch so the Gitea tree is deployable.

.env.example

@@ -0,0 +1,132 @@
+# Descrybe v2 - REQUIRED bootstrap env only.
+# Copy to repo-root `.env` (single source of truth). Do not create apps/api/.env.
+# Product secrets (OpenAI, Stripe, mail, Pinecone, store connectors)
+# belong in the admin dashboard -- do NOT put them here:
+#   platform: /admin/settings (stripe.* , feeds.private_url_allowlist)
+#   tenant: /integrations/ai , /integrations/email , /stores
+# EPREL enrichment is on by default for all plans (public EU API). No activation
+# step. Optional kill-switch only: EPREL_ENABLED=false here, or eprel.enabled=false
+# under /admin/settings.
+#
+# How apps load env:
+# - Go API/worker/mailhooks: config.Load() loads this monorepo-root `.env`
+#   (never overrides already-set process env). Override path: DOTENV_PATH=...
+# - npm run dev:api / scripts/run-in-dir.mjs / run-api.ps1 / migrate.*: same root `.env`
+# - SvelteKit: Vite envDir + kit.env.dir = monorepo root; PUBLIC_API_URL (+ optional PUBLIC_CSRF_COOKIE_NAME)
+#
+# Generate secrets locally (never commit real values):
+#   openssl rand -hex 32
+
+# Postgres (required). Default matches docker-compose local DB on :5433.
+DATABASE_URL=postgres://descrybe:descrybe@localhost:5433/descrybe?sslmode=disable
+
+# development | staging | production
+# Production fails closed: SESSION_SECURE=true, https WEB_ORIGIN, APP_ENCRYPTION_KEY,
+# TOKEN_SIGNING_SECRET (see config.Load validate).
+APP_ENV=development
+
+# API listen address (npm run dev:api forces :28471 so a stale local .env cannot bind :8080)
+HTTP_ADDR=:28471
+
+# Optional Prometheus scrape (no secrets). Docs: docs/production-readiness.md#ops-prometheus-scrape
+# Examples: deploy/prometheus/scrape.example.yml + alerts.example.yml
+# METRICS_PUBLIC=1   # prod only: expose /metrics beyond loopback (private VIP/mesh only)
+# METRICS_ADDR=127.0.0.1:9091  # worker-only listener for sync_* series
+
+# Background worker — included in `npm run dev` (api+web+worker).
+# Also: npm run dev:worker  |  make worker  |  .\scripts\run-api.ps1 worker
+# Required for processing jobs, Woo/Shopify claim, support AI auto, billing, and GET /readyz.
+
+# Browser origin for CORS / cookies (must be https + non-loopback in production).
+# Dev web is Vite :28472 (strictPort). npm run dev forces matching WEB_ORIGIN / PUBLIC_API_URL.
+# Local: API also accepts the localhost/127.0.0.1 twin for credentialed CORS (same port).
+WEB_ORIGIN=http://localhost:28472
+
+# Public API origin (web PUBLIC_API_URL should match; empty web = same-origin + Vite proxy)
+PUBLIC_API_URL=http://localhost:28471
+
+# Session cookie Secure flag (required true when APP_ENV=production|prod).
+# Keep false on http://localhost — Secure cookies are dropped by the browser on HTTP.
+SESSION_SECURE=false
+
+# Browser smoke (codehelper site=local-descrybe). Never commit a real password.
+# Set to the local demo password from docs/demo-user.md (a1-primary / demo),
+# OR store it out-of-repo: printf '%s' "$DESCRYBE_SMOKE_PASS" | codehelper connections set-secret --name local-descrybe
+# (then password_ref=secret). Unset/empty -> headless Sign-in submits no password -> /api/auth/me 401.
+# DESCRYBE_SMOKE_PASS=
+
+# Session / invite token HMAC. Required in production. openssl rand -hex 32
+TOKEN_SIGNING_SECRET=
+
+# AES key for credentials at rest (Woo/email/AI BYOK ciphertext).
+# Required in production. Prefer this over legacy CREDENTIALS_ENCRYPTION_KEY.
+# openssl rand -hex 32
+APP_ENCRYPTION_KEY=
+
+# --- Optional bootstrap (safe defaults in code; uncomment to override) ---
+# TRUSTED_PROXIES - hop-1 reverse-proxy / LB peers only (CIDR or IP, comma-separated).
+# When set, TrustedRealIP rewrites RemoteAddr from X-Forwarded-For / X-Real-IP only if
+# the TCP peer is on this allowlist. Empty (default) ignores client IP headers (safe
+# without a proxy; required behind CDN/LB so auth IP RPM + login lockout key correctly).
+# TRUSTED_PROXIES=127.0.0.1,10.0.0.0/8
+# RATE_LIMIT_REPLICAS=1
+# RATE_LIMIT_MULTI_REPLICA=false
+# RATE_LIMIT_BACKEND=memory
+# ASSUMPTION (Product 10): in-process rate limits + email login lockout are OK on a single
+# API instance. Multi-replica cutover = edge/WAF hard global RPM (see deploy/examples/edge-rate-limit.md).
+# Optional RATE_LIMIT_REPLICAS divides HTTP middleware caps only (not lockout/StartLimiter/AI/email)
+# — not a shared store. RATE_LIMIT_BACKEND=redis|postgres is docs-only and forced to memory.
+# SESSION_COOKIE_NAME=descrybe_session
+# CSRF_COOKIE_NAME=descrybe_csrf
+# PUBLIC_CSRF_COOKIE_NAME=descrybe_csrf
+# SESSION_IDLE_HOURS=24
+# UPLOAD_DIR=data/uploads
+# MAINTENANCE_MODE=false
+# READ_ONLY_MODE=false
+# CREDENTIALS_ENCRYPTION_KEY=   # legacy alias for APP_ENCRYPTION_KEY
+
+# --- Locales (not process-env; listed for agents/ops) ---
+# UI dashboard locales (browser localStorage key descrybe-ui-locale; default en):
+#   en, es, fr, de, it, pt, nl, pl, ja
+#   Source: apps/web/src/lib/i18n/locales.ts (+ message catalogs under lib/i18n/messages)
+# Content / AI language (companies.language via /settings Content Language; default en):
+#   en, fr, de, es, it, nl, pt, pl, cs, sk, hu, ro, bg, hr, sl, sv, da, fi, el, et, lv, lt, mt, ga, ja
+#   Sources: apps/web/src/lib/content-languages.ts , apps/api/internal/company/language.go
+# Optional EPREL fiche PDF language (prefer /admin/settings eprel.fiche_language):
+# EPREL_FICHE_LANGUAGE=EN
+
+# --- Prefer dashboard (optional env fallback still accepted by resolvers) ---
+# Platform /admin/settings (GET/PUT /api/admin/settings -> values.*):
+#   stripe.* , feeds.private_url_allowlist
+# Optional EPREL overrides (not required - enrichment defaults on):
+#   eprel.enabled=false  (or EPREL_ENABLED=false in this file) to disable
+#   eprel.base_url / eprel.timeout / eprel.fiche_language if tuning
+# OPENAI_*/RESEND_*/SMTP_* may still work as process-env fallbacks; prefer UI.
+# PROCESSING_*, DB_* pool knobs: code defaults; set in process env only if tuning.
+# MIGRATE_MYSQL_DSN: migrator CLI only - not API boot.
+
+# --- LLM test provider (optional; no production secrets) ---
+# Tiny OpenAI-compatible stub for CI/local processing proofs. See docs/mock-llm.md.
+# Start (separate terminal):
+#   cd apps/api && go run ./cmd/mock-llm -addr 127.0.0.1:18767
+# Stub-only knobs (read by mock-llm process, not by Descrybe API):
+# MOCK_LLM_API_KEY=local-test
+# MOCK_LLM_MODEL=mock-llm
+# Platform Completer fallback (root .env - restart api + worker after change):
+# OPENAI_API_KEY=local-test
+# OPENAI_BASE_URL=http://127.0.0.1:18767/v1
+# OPENAI_MODEL=mock-llm
+# PROCESSING_RPM=60
+# PROCESSING_MAX_RETRIES=3
+# Prefer tenant /integrations/ai (custom base + key) over process env when possible.
+# Do NOT put real OpenAI/Green Chat secrets here - use dashboard or a private root .env.
+# Verify translation + processing: docs/mock-llm.md ("Translation + processing verification").
+
+# --- Web analytics (optional; SvelteKit PUBLIC_* from this root .env) ---
+# Google Tag Manager container ID. When unset/empty, no GTM/GA tags load.
+# Consent Mode v2 defaults to denied until the cookie banner grants categories.
+# Setup: create GA4 property → GTM web container → GA4 Configuration tag with
+# Consent Settings (require analytics_storage; ad_* for ads) → publish.
+# SPA page views: Custom Event trigger `page_view` from the app. Do NOT also
+# enable GTM History Change / GA4 enhanced measurement page_views (double count).
+# PUBLIC_GTM_ID=GTM-XXXXXXX

.gitignore

@@ -0,0 +1,60 @@
+node_modules/
+**/node_modules.__bak*/
+**/node_modules.bak*/
+dist/
+build/
+.svelte-kit/
+.env
+.env.local
+*.exe
+*.test
+bin/
+.tmp*
+tmp/
+.DS_Store
+apps/api/internal/db/sqlc/
+coverage/
+.idea/
+.vscode/
+*.log
+*cookies.txt
+*.cookies.txt
+
+# Runtime uploads (keep data/sample-*.csv)
+data/uploads/
+apps/api/data/uploads/
+
+# codehelper (generated local - do not commit)
+.codehelper/
+.cursor/
+.claude/
+.codex/
+.mcp.json
+AGENTS.md
+CLAUDE.md
+CODEHELPER*.md
+
+# Migrator artifacts (ID maps / set-password hooks may contain PII - never commit)
+artifacts/
+maps/
+**/set-password-hooks.json
+**/password_invites.json
+**/id-map.json
+**/validation-report.json
+# Local run artifacts
+.bin/
+**/.bin/
+**/restart.pids.json
+*.pids.json
+
+# Local scratch / one-shot agent artifacts (never ship)
+.tmp/
+.tmp-*/
+**/.tmp/
+**/.tmp-*/
+*_test-out*.txt
+*.ps1.tmp
+scripts/_layout_snip.js
+scripts/write_001.py
+apps/web/scripts/_*
+apps/web/scripts/tr-*

Makefile

@@ -0,0 +1,70 @@
+.PHONY: up down api worker backend web migrate sqlc test test-api check-web vet seed seed-woo mock-woo health setup cutover-rehearsal
+
+# Start local Postgres only (:5433 — pairs with host npm run setup / npm run dev)
+up:
+	docker compose up -d
+
+# Stop local Postgres
+down:
+	docker compose down
+
+# One-shot: .env + Postgres + goose migrate (cross-platform via Node)
+setup:
+	node scripts/setup.mjs
+
+# Run Go API (config.Load reads monorepo-root .env; or: .\scripts\run-api.ps1)
+api:
+	cd apps/api && go run ./cmd/api
+
+# Background job worker (processing + Woo claim + billing; required for GET /readyz)
+worker:
+	cd apps/api && go run ./cmd/worker
+
+# API + worker together (readyz/jobs). Prefer: npm run dev:backend (or npm run dev for +web)
+backend:
+	npm run dev:backend
+
+# Run SvelteKit web (Vite proxies /api → :28471; port 28472)
+web:
+	cd apps/web && npm install && npm run dev
+
+# Apply goose migrations and regenerate sqlc (any OS: npm run migrate)
+migrate:
+	node scripts/migrate.mjs
+
+# Seed local demo user (any OS: npm run seed)
+seed:
+	node scripts/seed-local.mjs
+
+# Seed WooCommerce demo orders/reviews/audience campaign (no live Woo required)
+seed-woo:
+	cd apps/api && go run ./cmd/seed-woo-demo
+
+# Local WooCommerce REST fixtures for live client proofs (see docs/live-woo-test.md)
+mock-woo:
+	cd apps/api && go run ./cmd/mock-woo -addr 127.0.0.1:19090
+
+# Quick health probes (API :28471; /readyz needs worker)
+health:
+	node scripts/health.mjs
+
+# Local cutover rehearsal: deploy-check + list-* + orphan dry-run (no Clerk/SMTP/Stripe/-confirm)
+cutover-rehearsal:
+	node scripts/cutover-local-rehearsal.mjs
+
+# Regenerate sqlc only
+sqlc:
+	cd apps/api && sqlc generate
+
+# Unit tests (API) — no live DB required for default suite
+test: test-api
+
+test-api:
+	cd apps/api && go test ./...
+
+vet:
+	cd apps/api && go vet ./...
+
+# Type-check SvelteKit (install deps first if needed)
+check-web:
+	cd apps/web && npm run check

README.md

@@ -0,0 +1,219 @@
+# Descrybe v2
+
+Go API + SvelteKit frontend + PostgreSQL rewrite of Descrybe (no Clerk).
+
+## Stack
+
+- **API:** Go, chi, pgx, sqlc, goose, River jobs
+- **Web:** SvelteKit 2, Svelte 5, Tailwind
+- **DB:** PostgreSQL 16
+- **Migrator:** MySQL → Postgres ETL with Clerk ID remapping
+
+## Local setup (any OS)
+
+Docker Compose runs **Postgres only** (host **:5433**). API, web, and worker run on the host via `npm run setup` + `npm run dev` (fast reload; no Laragon/XAMPP required). OS-specific Docker notes: [docs/docker.md](docs/docker.md). Ports match `docker-compose.yml` + `scripts/dev-ports.mjs`.
+
+**After the stack is up:** operator path (login → feed → process → export) → [docs/getting-started.md](docs/getting-started.md).
+
+### Two-step path (recommended)
+
+```bash
+npm run setup        # .env (if missing) + docker Postgres :5433 + goose migrate
+npm install && npm run dev   # API :28471 + web :28472 + worker (needed for /readyz + jobs)
+```
+
+Same on Windows PowerShell, macOS, and Linux (Node scripts; Docker Desktop or Engine + Compose v2). Equivalents: `make setup` then `make` targets / `npm run …`.
+
+Optional: `npm run seed` (demo login) · `npm run health` (`/healthz` + `/readyz`).
+
+### Prerequisites
+
+| Tool | Version / notes |
+|------|-----------------|
+| **Docker** | Docker Engine + Compose v2 (`docker compose`) — Postgres only on **:5433** |
+| **Node.js** | **≥ 20** (`package.json` `engines.node`) |
+| **Go** | **1.25.0** (`apps/api/go.mod`) |
+| **sqlc** (optional) | On `PATH` for migrate regen; scripts fall back to `go run …/sqlc` if missing |
+| **Make** (optional) | `make setup` / `make up` / `make migrate` — macOS/Linux/WSL; Windows can use `npm run …` |
+
+### Local ports (canonical)
+
+| Service | Host |
+|---------|------|
+| Postgres | `localhost:5433` → container `5432` (`postgres:16-alpine`) |
+| API | `http://localhost:28471` (`HTTP_ADDR=:28471`) |
+| Web | `http://localhost:28472` (Vite `strictPort`; proxies `/api`, `/healthz`, `/readyz`) |
+
+Do **not** use older docs that mention `:8080` / `:5174` for day-to-day `npm run dev`.
+
+### Environment (one file)
+
+Use a **single root `.env`** (copy from [`.env.example`](.env.example)). Do **not** create `apps/api/.env`. `npm run setup` creates `.env` from the example and fills empty `TOKEN_SIGNING_SECRET` / `APP_ENCRYPTION_KEY` with local random hex (never commit `.env`).
+
+| Variable | Local default / note |
+|----------|----------------------|
+| `DATABASE_URL` | `postgres://descrybe:descrybe@localhost:5433/descrybe?sslmode=disable` (matches `docker-compose.yml`) |
+| `HTTP_ADDR` | `:28471` |
+| `WEB_ORIGIN` | `http://localhost:28472` |
+| `PUBLIC_API_URL` | `http://localhost:28471` |
+| `APP_ENV` | `development` |
+| `SESSION_SECURE` | `false` locally; `true` in production |
+| `TOKEN_SIGNING_SECRET` | `openssl rand -hex 32` (or let `npm run setup` generate) |
+| `APP_ENCRYPTION_KEY` | Prefer this for at-rest secrets (`CREDENTIALS_ENCRYPTION_KEY` is legacy). Same generate rule |
+
+Leave OpenAI, Stripe, EPREL, marketing mail, Woo, and Shopify **out of** `.env` for day-to-day setup. Configure them in the app after login:
+
+| Integration | Where |
+|-------------|--------|
+| AI (OpenAI-compatible / BYOK) | `/integrations/ai` (tenant) and/or `/admin/settings` (platform) |
+| Stripe, EPREL, feed private-URL allowlist | `/admin/settings` (`GET/PUT /api/admin/settings` → `values.*`; env optional fallback) |
+| Marketing email (Resend / SMTP) | `/integrations/email` |
+| Stores (Woo / Shopify / feeds) | `/stores` |
+
+Platform set-password / invite SMTP may still use process `SMTP_*` when you enable live invite mail (see [docs/ops-runtime.md](docs/ops-runtime.md)). Session/encryption fail-closed rules are in `.env.example` and [docs/production-checklist.md](docs/production-checklist.md). Production does **not** require Stripe secrets at boot.
+
+The API/worker load the **monorepo-root** `.env` automatically (`apps/api/internal/config` `loadDotEnv`).
+
+### Manual steps (if you skip `npm run setup`)
+
+`docker-compose.yml` defines **only** Postgres (`descrybe-v2-postgres`, user/db/password `descrybe`, volume `descrybe_v2_pg`, `pg_isready` healthcheck). OS-specific Docker Desktop / Engine notes: [docs/docker.md](docs/docker.md).
+
+```bash
+cp .env.example .env          # PowerShell: Copy-Item .env.example .env
+docker compose up -d          # or: npm run db:up / make up
+npm run migrate               # goose up + sqlc (loads root .env)
+npm install && npm run dev
+```
+
+Migrate wrappers: `bash scripts/migrate.sh` · `.\scripts\migrate.ps1` · `make migrate` (all call `scripts/migrate.mjs`).
+
+### Worker and `/readyz`
+
+`npm run dev` starts **API + web + worker**. Processing jobs and `GET /readyz` need that worker heartbeat (stale after **60s**).
+
+| Script | What runs |
+|--------|-----------|
+| `npm run dev` / `npm run dev:app` | api + web + worker |
+| `npm run dev:backend` / `make backend` | api + worker (no web; enough for `/readyz`) |
+| `npm run dev:api` | api only → `/readyz` 503 until a worker is started |
+| `npm run dev:worker` | worker only |
+| `make worker` / `.\scripts\run-api.ps1 worker` | worker only |
+
+### Verify
+
+```bash
+npm run health
+# or:
+curl -sS http://127.0.0.1:28471/healthz
+curl -sS http://127.0.0.1:28471/readyz
+```
+
+Open the app: [http://localhost:28472](http://localhost:28472). Demo seed: `npm run seed`.
+
+### Split processes (optional)
+
+```bash
+npm run dev:web      # web only
+npm run dev:api      # API only (readyz 503 without worker)
+npm run dev:worker   # worker only
+npm run dev:backend  # api + worker
+npm run dev:ps1      # PowerShell: api + web + worker
+```
+
+### OS notes
+
+- **Windows / macOS / Linux Docker details** (Desktop vs Engine, WSL2, ports): [docs/docker.md](docs/docker.md).
+- **Windows:** Docker Desktop running; use `npm run setup` / `npm run migrate` / `npm run seed` (Node) — no Git Bash required. Optional: `.\scripts\migrate.ps1`, `.\scripts\dev.ps1`.
+- **macOS / Linux:** same npm commands; `make setup` / `make migrate` work if Make is installed.
+- **WSL2:** Docker Desktop WSL integration or Linux engine; keep `DATABASE_URL` on `localhost:5433` from the same environment as the API.
+
+### Troubleshooting: `/readyz` returns 503
+
+`GET /healthz` = process liveness. `GET /readyz` = Postgres ping **and** a fresh worker heartbeat (`worker_id=processing`, stale after **60s**). On worker failure the JSON keeps a short `error` and adds operator `reason` (how to start the host worker). See also [docs/ops-runtime.md](docs/ops-runtime.md) and [docs/production-checklist.md](docs/production-checklist.md).
+
+| Symptom | Meaning | Fix |
+|---------|---------|-----|
+| `/healthz` 200, `/readyz` 503, `checks.worker` = `missing`, error `worker heartbeat missing` | API up, **worker never started** (or migrations before `039_worker_heartbeats`) | Use `npm run dev` (includes worker), or `npm run dev:worker` / `make worker`; ensure goose is up through **039**. Read JSON `reason`. |
+| `/readyz` 503, `checks.worker` = `stale`, error `worker heartbeat stale` | Worker was up but heartbeat older than 60s | Restart the worker; confirm it stays running. Read JSON `reason`. |
+| `/readyz` 503, `checks.database` = `fail` / `unavailable` | DB down or bad `DATABASE_URL` | `docker compose ps`, fix URL (host **5433**), re-run migrate |
+| `/readyz` still 503 after starting worker | Heartbeat table missing or wrong DB | Re-run migrate; confirm worker and API share the same `DATABASE_URL` |
+
+**Expected:** API-only local (`cmd/api` without `cmd/worker`, or `npm run dev:api`) → `/readyz` **503**. That is not a broken API binary — start the worker (`npm run dev`, `npm run dev:backend`, or `npm run dev:worker`) before treating readiness as green. Jobs on `/processing` also need the worker. Compose does **not** start the worker (Postgres only).
+
+### Routes
+
+| Path | Purpose |
+|------|---------|
+| `/` | Public marketing homepage (sell copy, FAQ, pricing teaser; no app shell) |
+| `/pricing` | Public marketing pricing (Free→Enterprise; no client deals) |
+| `/features` | Optional features deep-dive (not primary nav) |
+| `/privacy`, `/terms` | Legal pages |
+| `/login`, `/register` | Auth (login success → `/dashboard`) |
+| `/dashboard` | App home (sidebar shell) |
+| `/plans` | In-app plans (authenticated) |
+| `/standard-fields`, `/feeds`, `/feeds/{id}/mapping` | Catalog ingest + mapping |
+| `/products`, `/processing` | Catalog + background process jobs |
+| `/export-feeds` | Outbound CSV/XML templates + generate |
+| `/stores`, `/stores/shopify` | Store connectors hub (Woo, Shopify sibling, feed URL, CSV) |
+| `/campaigns`, `/seo`, `/brand`, `/marketing/calendar` | Marketing suite |
+| `/reviews` | Alias to WooCommerce Reviews tab |
+| `/admin/*` | Platform admin |
+
+### Demo login (migrated staging data)
+
+Alias `demo@descrybe.test` is also seeded. Platform admin + **admin of Platform Demo only** (not A1). Default session company: **Platform Demo**. Act for A1 via Admin → Users → Switch to user (`a1-primary@descrybe.local`). Details: [docs/demo-user.md](docs/demo-user.md), [docs/safe-test-fixtures.md](docs/safe-test-fixtures.md).
+
+```bash
+npm run seed
+# or: node scripts/seed-local.mjs
+# or: pwsh -File .\scripts\seed-local.ps1
+```
+
+## Migrations
+
+Prefer the cross-platform script (loads root `.env`):
+
+```bash
+npm run migrate
+# equivalents: node scripts/migrate.mjs  |  make migrate  |  .\scripts\migrate.ps1
+```
+
+Manual:
+
+```bash
+cd apps/api
+go run github.com/pressly/goose/v3/cmd/goose@v3.24.3 -dir sql/schema postgres "$DATABASE_URL" up
+sqlc generate
+```
+
+## Migrator
+
+Live MySQL → staging Postgres load **succeeded** (2026-08-03); production cutover is still **NO-GO** until emails/roles/SMTP login are proven. Evidence: [docs/migration-run-log.md](docs/migration-run-log.md).
+
+```bash
+cd apps/api
+go run ./cmd/migrator -mysql "$MIGRATE_MYSQL_DSN" -postgres "$DATABASE_URL" -dry-run
+```
+
+## Docs
+- **[Local setup (README)](README.md#local-setup-any-os)** — any-OS Docker/Node/Go/migrate; `/readyz` 503 troubleshooting
+- **[docs/getting-started.md](docs/getting-started.md)** — operator checklist: login → feed → process → export
+- **[docs/store-connectors.md](docs/store-connectors.md)** — Woo / Shopify / feed URL / CSV / export REST
+- **[docs/marketing-suite-user-guide.md](docs/marketing-suite-user-guide.md)** — seasons, Black Friday in 5 clicks, tutorial start
+- **[docs/free-tier.md](docs/free-tier.md)** — Free plan 0 AI credits + marketing gates
+- **[docs/green-chat-ai.md](docs/green-chat-ai.md)** — Green Chat / OPENAI_BASE_URL for processing + campaign AI
+- **[docs/mock-llm.md](docs/mock-llm.md)** — Tiny OpenAI-compatible stub (`cmd/mock-llm`) for CI/dev processing without production keys
+- [Email sending](docs/email-sending.md) — Resend/SMTP, encryption, dry-run
+
+- **[docs/process-and-sell-summary.md](docs/process-and-sell-summary.md)** — process & sell E2E test path (standard fields, sync/process, EPREL, export, public API)
+- **[docs/demo-user.md](docs/demo-user.md)** — demo login + company data counts for staging testing
+- **[docs/woocommerce-demo.md](docs/woocommerce-demo.md)** — Woo store setup, WOO_* env, seed-woo-demo, audience/campaigns
+- **[docs/go-live-checklist.md](docs/go-live-checklist.md)** — go/no-go cutover checklist (design, stubs, migrate, set-password)
+- [docs/migration-run-log.md](docs/migration-run-log.md) — live dry-run + staging load report
+- [docs/status-and-gaps.md](docs/status-and-gaps.md) — what works, what's stubbed, what's missing, priority order
+- [docs/design-gaps.md](docs/design-gaps.md) — UI/UX parity vs legacy
+- [docs/migration-readiness.md](docs/migration-readiness.md) — ETL status + post-import set-password
+- [docs/features.md](docs/features.md) — phase checklist
+- [docs/schema-map.md](docs/schema-map.md) — MySQL → Postgres ID maps
+- [docs/cutover.md](docs/cutover.md) — production cutover runbook
+- [docs/ops-runtime.md](docs/ops-runtime.md) — SMTP, sessions, Woo encryption

apps/api/Makefile

@@ -0,0 +1,29 @@
+DATABASE_URL ?= postgres://descrybe:descrybe@localhost:5433/descrybe?sslmode=disable
+GOOSE ?= go run github.com/pressly/goose/v3/cmd/goose@v3.24.1
+SQLC ?= go run github.com/sqlc-dev/sqlc/cmd/sqlc@v1.29.0
+
+.PHONY: migrate-up sqlc run worker migrator tidy test vet
+
+migrate-up:
+	$(GOOSE) -dir sql/schema postgres "$(DATABASE_URL)" up
+
+sqlc:
+	$(SQLC) generate
+
+run:
+	go run ./cmd/api
+
+worker:
+	go run ./cmd/worker
+
+migrator:
+	go run ./cmd/migrator -mysql "$(MIGRATE_MYSQL_DSN)" -postgres "$(DATABASE_URL)"
+
+tidy:
+	go mod tidy
+
+test:
+	go test ./...
+
+vet:
+	go vet ./...

apps/api/cmd/api/main.go

@@ -0,0 +1,110 @@
+package main
+
+import (
+	"context"
+	"log"
+	"log/slog"
+	"net"
+	"net/http"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+
+	"github.com/descrybe/descrybe-v2/apps/api/internal/auth"
+	"github.com/descrybe/descrybe-v2/apps/api/internal/config"
+	"github.com/descrybe/descrybe-v2/apps/api/internal/db"
+	"github.com/descrybe/descrybe-v2/apps/api/internal/httpapi"
+	"github.com/descrybe/descrybe-v2/apps/api/internal/logredact"
+)
+
+func main() {
+	log.SetOutput(logredact.Writer(os.Stderr))
+	slog.SetDefault(slog.New(logredact.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelInfo})))
+
+	cfg, err := config.Load()
+	if err != nil {
+		log.Fatalf("config: %v", err)
+	}
+	if cfg.ShouldWarnRateLimits() {
+		slog.Warn(cfg.RateLimitWarningMessage(),
+			"rate_limit_replicas", cfg.RateLimitReplicas,
+			"rate_limit_multi_replica", cfg.RateLimitMultiReplica,
+			"rate_limit_backend", cfg.RateLimitBackend,
+			"rate_limit_backend_requested", cfg.RateLimitBackendRequested,
+		)
+	}
+
+	ctx := context.Background()
+	pool, err := db.NewPool(ctx, cfg.DatabaseURL, db.PoolOptions{
+		MaxConns:              int32(cfg.DBMaxConns),
+		MinConns:              int32(cfg.DBMinConns),
+		MaxConnLifetime:       cfg.DBMaxConnLifetime,
+		MaxConnLifetimeJitter: cfg.DBMaxConnLifetimeJitter,
+		MaxConnIdleTime:       cfg.DBMaxConnIdleTime,
+		HealthCheckPeriod:     cfg.DBHealthCheckPeriod,
+		StatementTimeout:      cfg.DBStatementTimeout,
+	})
+	if err != nil {
+		log.Fatalf("db: %v", err)
+	}
+	defer pool.Close()
+
+	sessions := auth.NewSessionManager(pool, cfg.SessionCookieName, cfg.CookieSecure(), cfg.SessionIdleHours)
+	srv := httpapi.NewServer(cfg, pool, sessions)
+
+	runCtx, runCancel := context.WithCancel(context.Background())
+	defer runCancel()
+	// Lightweight AI fallback poller so FAQ-miss tickets drain without a separate worker.
+	if srv.Support != nil {
+		go srv.Support.RunAutoJobsLoop(runCtx, 2*time.Second, 3)
+	}
+
+	httpServer := newHTTPServer(cfg.HTTPAddr, srv.Router())
+
+	ln, err := net.Listen("tcp", cfg.HTTPAddr)
+	if err != nil {
+		log.Fatalf("listen: %v", err)
+	}
+	slog.Info("api_listening", "addr", cfg.HTTPAddr, "maintenance", cfg.MaintenanceMode, "read_only", cfg.ReadOnlyMode)
+
+	go func() {
+		if err := httpServer.Serve(ln); err != nil && err != http.ErrServerClosed {
+			log.Fatalf("serve: %v", err)
+		}
+	}()
+
+	stop := make(chan os.Signal, 1)
+	signal.Notify(stop, syscall.SIGINT, syscall.SIGTERM)
+	<-stop
+	runCancel()
+
+	shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	_ = httpServer.Shutdown(shutdownCtx)
+}
+
+// newHTTPServer configures net/http timeouts for the API listener.
+//
+// Tradeoff — WriteTimeout vs long sync/export:
+// WriteTimeout bounds the whole ServeHTTP + response write. Feed export
+// streams and sync-style handlers can run for many minutes; a short
+// WriteTimeout aborts them mid-stream (clients see truncated/hanging
+// responses). We use a long WriteTimeout ceiling instead of 0 (unlimited)
+// so wedged handlers still release connections eventually. Finer per-route
+// deadlines belong on request contexts / middleware for normal JSON APIs.
+// Leaving WriteTimeout unset (0) would never reclaim a stuck writer.
+func newHTTPServer(addr string, handler http.Handler) *http.Server {
+	return &http.Server{
+		Addr:    addr,
+		Handler: handler,
+		// Headers-only Slowloris guard (independent of ReadTimeout).
+		ReadHeaderTimeout: 10 * time.Second,
+		// Full request read (headers + body). Above typical API JSON uploads.
+		ReadTimeout: 60 * time.Second,
+		// Long ceiling so streaming exports/sync can finish; see comment above.
+		WriteTimeout: 15 * time.Minute,
+		// Close keep-alive connections idle between requests.
+		IdleTimeout: 120 * time.Second,
+	}
+}

apps/api/cmd/api/main_test.go

@@ -0,0 +1,34 @@
+package main
+
+import (
+	"net/http"
+	"testing"
+	"time"
+)
+
+func TestNewHTTPServerTimeouts(t *testing.T) {
+	t.Parallel()
+
+	handler := http.HandlerFunc(func(http.ResponseWriter, *http.Request) {})
+	srv := newHTTPServer(":0", handler)
+
+	if srv.Addr != ":0" {
+		t.Fatalf("Addr = %q, want :0", srv.Addr)
+	}
+	if srv.Handler == nil {
+		t.Fatal("Handler is nil")
+	}
+	if got, want := srv.ReadHeaderTimeout, 10*time.Second; got != want {
+		t.Fatalf("ReadHeaderTimeout = %v, want %v", got, want)
+	}
+	if got, want := srv.ReadTimeout, 60*time.Second; got != want {
+		t.Fatalf("ReadTimeout = %v, want %v", got, want)
+	}
+	// Long WriteTimeout preserves streaming feed exports/sync; must stay >> typical JSON handlers.
+	if got, want := srv.WriteTimeout, 15*time.Minute; got != want {
+		t.Fatalf("WriteTimeout = %v, want %v", got, want)
+	}
+	if got, want := srv.IdleTimeout, 120*time.Second; got != want {
+		t.Fatalf("IdleTimeout = %v, want %v", got, want)
+	}
+}

apps/api/cmd/mailhooks/main.go

@@ -0,0 +1,111 @@
+package main
+
+import (
+	"encoding/json"
+	"errors"
+	"flag"
+	"fmt"
+	"log"
+	"os"
+	"time"
+
+	"github.com/descrybe/descrybe-v2/apps/api/internal/config"
+	"github.com/descrybe/descrybe-v2/apps/api/internal/mail"
+	"github.com/google/uuid"
+)
+
+// Hook matches migrator maps/set-password-hooks.json (invite tokens for must_set_password users).
+type Hook struct {
+	UserID    uuid.UUID `json:"user_id"`
+	Email     string    `json:"email"`
+	CompanyID uuid.UUID `json:"company_id"`
+	Role      string    `json:"role"`
+	Token     string    `json:"token"`
+	ExpiresAt time.Time `json:"expires_at"`
+	InviteID  uuid.UUID `json:"invite_id"`
+}
+
+func main() {
+	hooksPath := flag.String("hooks", "", "Path to set-password-hooks.json from migrator maps-dir")
+	dryRun := flag.Bool("dry-run", false, "Print counts without sending")
+	delayMS := flag.Int("delay-ms", 100, "Pause between sends (SMTP rate limit)")
+	flag.Parse()
+
+	if *hooksPath == "" {
+		log.Fatal("-hooks is required (e.g. ../../artifacts/maps/set-password-hooks.json)")
+	}
+
+	cfg, err := config.Load()
+	if err != nil {
+		log.Fatalf("config: %v", err)
+	}
+
+	raw, err := os.ReadFile(*hooksPath)
+	if err != nil {
+		log.Fatalf("read hooks: %v", err)
+	}
+	var hooks []Hook
+	if err := json.Unmarshal(raw, &hooks); err != nil {
+		log.Fatalf("parse hooks: %v", err)
+	}
+
+	mailer := mail.New(mail.Config{
+		Enabled:  cfg.SMTPEnabled,
+		Host:     cfg.SMTPHost,
+		Port:     cfg.SMTPPort,
+		User:     cfg.SMTPUser,
+		Password: cfg.SMTPPassword,
+		From:     cfg.SMTPFrom,
+	})
+	if err := assertMailhooksReady(*dryRun, mailer.Enabled(), cfg.EmailDryRun); err != nil {
+		log.Fatal(err)
+	}
+
+	sent, skipped, failed := 0, 0, 0
+	now := time.Now().UTC()
+	for _, h := range hooks {
+		if h.Token == "" || h.Email == "" {
+			skipped++
+			continue
+		}
+		if !h.ExpiresAt.IsZero() && now.After(h.ExpiresAt) {
+			skipped++
+			continue
+		}
+		msg := mail.MigratedSetPasswordMessage(cfg.WebOrigin, h.Email, h.Token)
+		if *dryRun {
+			log.Printf("mailhooks: dry-run subject=%q", msg.Subject)
+			sent++
+			continue
+		}
+		if err := mailer.Send(msg); err != nil {
+			log.Printf("mailhooks: send failed subject=%q", msg.Subject)
+			failed++
+			continue
+		}
+		sent++
+		if *delayMS > 0 {
+			time.Sleep(time.Duration(*delayMS) * time.Millisecond)
+		}
+	}
+
+	fmt.Printf("mailhooks: sent=%d skipped=%d failed=%d smtp_enabled=%v total=%d\n",
+		sent, skipped, failed, mailer.Enabled(), len(hooks))
+	if failed > 0 {
+		os.Exit(1)
+	}
+}
+
+// assertMailhooksReady fails closed for live sends when SMTP is a no-op or EMAIL_DRY_RUN is on.
+func assertMailhooksReady(dryRun, mailerEnabled, emailDryRun bool) error {
+	if dryRun {
+		return nil
+	}
+	if emailDryRun {
+		return errors.New("mailhooks: email dry-run is on; pass -dry-run or disable dry-run in admin platform mail settings (or EMAIL_DRY_RUN=false)")
+	}
+	if !mailerEnabled {
+		return errors.New("mailhooks: SMTP not configured; pass -dry-run or set platform mail SMTP in admin (smtp.enabled + host/from)")
+	}
+	return nil
+}

apps/api/cmd/mailhooks/ready_test.go

@@ -0,0 +1,19 @@
+package main
+
+import "testing"
+
+func TestAssertMailhooksReady(t *testing.T) {
+	t.Parallel()
+	if err := assertMailhooksReady(true, false, true); err != nil {
+		t.Fatalf("dry-run should always allow: %v", err)
+	}
+	if err := assertMailhooksReady(false, false, true); err == nil {
+		t.Fatal("expected EMAIL_DRY_RUN block")
+	}
+	if err := assertMailhooksReady(false, false, false); err == nil {
+		t.Fatal("expected SMTP disabled block")
+	}
+	if err := assertMailhooksReady(false, true, false); err != nil {
+		t.Fatalf("live SMTP should allow: %v", err)
+	}
+}

apps/api/cmd/migrator/admins.go

@@ -0,0 +1,99 @@
+package main
+
+import (
+	"context"
+	"database/sql"
+	"log"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// applyPlatformAdmins maps legacy admin_users → users.is_platform_admin.
+// Matching prefers remapped Clerk/legacy user_id, then email. Never creates orphan admin rows.
+// Company-admin memberships (member→admin) are a separate post-load step:
+// see runMembershipRoleRepair (-list-member-memberships / -promote-company-admins).
+func applyPlatformAdmins(
+	ctx context.Context,
+	mysqlDB *sql.DB,
+	pg *pgxpool.Pool,
+	userMap map[string]string,
+	report map[string]int,
+	dryRun bool,
+) {
+	if !mysqlTableExists(ctx, mysqlDB, "admin_users") {
+		log.Printf("admin_users skipped: table missing")
+		return
+	}
+
+	// Legacy shape: user_id (Clerk text) + email. Column presence varies by dump age.
+	hasUserID := mysqlColumnExists(ctx, mysqlDB, "admin_users", "user_id")
+	hasEmail := mysqlColumnExists(ctx, mysqlDB, "admin_users", "email")
+	if !hasUserID && !hasEmail {
+		log.Printf("admin_users skipped: no user_id/email columns")
+		return
+	}
+
+	q := `SELECT `
+	switch {
+	case hasUserID && hasEmail:
+		q += `COALESCE(user_id, ''), COALESCE(email, '') FROM admin_users`
+	case hasUserID:
+		q += `user_id, '' FROM admin_users`
+	default:
+		q += `'', email FROM admin_users`
+	}
+
+	rows, err := mysqlDB.QueryContext(ctx, q)
+	if err != nil {
+		log.Printf("admin_users skipped: %v", err)
+		return
+	}
+	defer rows.Close()
+
+	for rows.Next() {
+		var legacyUserID, email string
+		if err := rows.Scan(&legacyUserID, &email); err != nil {
+			report["admin_users_skipped"]++
+			continue
+		}
+		pgUserID, ok := userMap[legacyUserID]
+		if !ok && email != "" {
+			// Resolve via email already loaded into Postgres (or dry-run map miss).
+			if dryRun {
+				report["admin_users_unmatched"]++
+				continue
+			}
+			var id string
+			err := pg.QueryRow(ctx, `SELECT id::text FROM users WHERE lower(email) = lower($1)`, email).Scan(&id)
+			if err != nil {
+				report["admin_users_unmatched"]++
+				continue
+			}
+			pgUserID = id
+		}
+		if pgUserID == "" {
+			report["admin_users_unmatched"]++
+			continue
+		}
+		if dryRun {
+			report["admin_users"]++
+			continue
+		}
+		tag, err := pg.Exec(ctx, `
+			UPDATE users
+			SET is_platform_admin = true,
+				staff_role = COALESCE(staff_role, 'admin'),
+				updated_at = now()
+			WHERE id = $1::uuid`, pgUserID)
+		if err != nil {
+			log.Printf("admin_users update %s: %v", legacyUserID, err)
+			report["admin_users_skipped"]++
+			continue
+		}
+		if tag.RowsAffected() == 0 {
+			report["admin_users_unmatched"]++
+			continue
+		}
+		report["admin_users"]++
+	}
+}

apps/api/cmd/migrator/company_plans_repair.go

@@ -0,0 +1,158 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"strings"
+
+	"github.com/descrybe/descrybe-v2/apps/api/internal/billing"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// runCompaniesWithoutPlansRepair lists and/or assigns plans for companies that
+// have no active company_plans row. Postgres-only; never deletes or overwrites
+// an existing active plan. Live writes require confirm=true (no blind assigns).
+func runCompaniesWithoutPlansRepair(postgresURL, planName string, listOnly, assign bool, dryRun, confirm bool) {
+	if postgresURL == "" {
+		log.Fatal("-postgres / DATABASE_URL is required for companies-without-plans tooling")
+	}
+	planName, err := normalizeAssignPlanName(planName, assign)
+	if err != nil {
+		log.Fatal(err)
+	}
+	if !listOnly && !assign {
+		log.Fatal("pass -list-companies-without-plans and/or -assign-missing-plans")
+	}
+	if err := guardLiveMutation(assign, dryRun, confirm, "-assign-missing-plans"); err != nil {
+		log.Fatal(err)
+	}
+
+	ctx := context.Background()
+	pg, err := pgxpool.New(ctx, postgresURL)
+	if err != nil {
+		log.Fatalf("postgres: %v", err)
+	}
+	defer pg.Close()
+
+	svc := &billing.Service{Pool: pg}
+	if err := svc.EnsureDefaultPlans(ctx); err != nil {
+		log.Fatalf("ensure default plans: %v", err)
+	}
+
+	total, err := svc.CountCompaniesWithoutActivePlan(ctx)
+	if err != nil {
+		log.Fatalf("count companies without active plan: %v", err)
+	}
+	fmt.Printf("companies_without_active_plan: %d\n", total)
+
+	const page = 200
+	offset := 0
+	listed := 0
+	assigned := 0
+	skipped := 0
+	a1Skipped := 0
+
+	for {
+		rows, err := svc.ListCompaniesWithoutActivePlan(ctx, page, offset)
+		if err != nil {
+			log.Fatalf("list companies without active plan: %v", err)
+		}
+		if len(rows) == 0 {
+			break
+		}
+		pageAssigned := 0
+		for _, c := range rows {
+			listed++
+			a1 := billing.IsA1CohortCompany(c.LegacyCompanyID, c.Name)
+			if listOnly || !assign {
+				fmt.Printf("  %s\t%s\t%s\ta1=%v\n", c.ID, c.Name, c.Language, a1)
+			}
+			mutate, skipReason := decideAssignMissingPlan(assign, c.LegacyCompanyID, c.Name)
+			if !mutate {
+				if assign && skipReason != "" {
+					fmt.Printf("skip\t%s\t%s\t%s\n", c.ID, c.Name, skipReason)
+					skipped++
+					a1Skipped++
+				}
+				continue
+			}
+			if dryRun {
+				fmt.Printf("dry-run: would assign plan %q to company %s (%s)\n", planName, c.ID, c.Name)
+				assigned++
+				continue
+			}
+			ok, err := svc.AssignPlanByNameIfMissing(ctx, c.ID, planName)
+			if err != nil {
+				log.Printf("assign plan %q to company %s: %v", planName, c.ID, err)
+				skipped++
+				continue
+			}
+			if !ok {
+				skipped++
+				continue
+			}
+			fmt.Printf("assigned plan %q to company %s (%s)\n", planName, c.ID, c.Name)
+			assigned++
+			pageAssigned++
+		}
+		if len(rows) < page {
+			break
+		}
+		if assign && !dryRun {
+			// Live assigns shrink the result set, so restart from offset 0.
+			// If this page assigned nothing (e.g. all A1 skips), advance offset
+			// so we cannot spin forever on the same unassignable rows.
+			if pageAssigned == 0 {
+				offset += page
+			} else {
+				offset = 0
+			}
+			continue
+		}
+		offset += page
+	}
+
+	if assign {
+		fmt.Printf("listed=%d assigned=%d skipped=%d a1_skipped=%d dry_run=%v plan=%q\n", listed, assigned, skipped, a1Skipped, dryRun, planName)
+	} else {
+		fmt.Printf("listed=%d\n", listed)
+	}
+}
+
+// decideAssignMissingPlan is the assign gate used by dry-run and -confirm.
+// A1 cohort companies always skip (never get Free/other fallback), even when confirm=true.
+func decideAssignMissingPlan(assign bool, legacyCompanyID, companyName string) (mutate bool, skipReason string) {
+	if !assign {
+		return false, ""
+	}
+	if billing.IsA1CohortCompany(legacyCompanyID, companyName) {
+		return false, "a1_cohort"
+	}
+	return true, ""
+}
+
+func normalizeAssignPlanName(planName string, assign bool) (string, error) {
+	planName = strings.TrimSpace(planName)
+	if assign && planName == "" {
+		return "", fmt.Errorf("-plan-name is required with -assign-missing-plans (e.g. Free)")
+	}
+	return planName, nil
+}
+
+// guardLiveAssign is kept for tests; prefer guardLiveMutation for new call sites.
+func guardLiveAssign(assign, dryRun, confirm bool) error {
+	return guardLiveMutation(assign, dryRun, confirm, "-assign-missing-plans")
+}
+
+func resolveFallbackPlanID(ctx context.Context, pg *pgxpool.Pool, planName string) (int64, error) {
+	planName = strings.TrimSpace(planName)
+	if planName == "" {
+		return 0, nil
+	}
+	svc := &billing.Service{Pool: pg}
+	if err := svc.EnsureDefaultPlans(ctx); err != nil {
+		return 0, err
+	}
+	return svc.PlanIDByName(ctx, planName)
+}

apps/api/cmd/migrator/company_plans_repair_test.go

@@ -0,0 +1,75 @@
+package main
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"github.com/descrybe/descrybe-v2/apps/api/internal/billing"
+)
+
+func TestDecideAssignMissingPlanSkipsA1(t *testing.T) {
+	t.Parallel()
+	mutate, reason := decideAssignMissingPlan(true, billing.A1LegacyCompanyID, "Anything")
+	if mutate || reason != "a1_cohort" {
+		t.Fatalf("A1 legacy id must never assign (even with -confirm): mutate=%v reason=%q", mutate, reason)
+	}
+	mutate, reason = decideAssignMissingPlan(true, "other-legacy-id", "A1 Slovenija")
+	if !mutate || reason != "" {
+		t.Fatalf("display name alone must not skip assign: mutate=%v reason=%q", mutate, reason)
+	}
+	mutate, reason = decideAssignMissingPlan(false, billing.A1LegacyCompanyID, "A1")
+	if mutate || reason != "" {
+		t.Fatalf("list-only: mutate=%v reason=%q", mutate, reason)
+	}
+}
+
+func TestResolveFallbackPlanIDEmpty(t *testing.T) {
+	t.Parallel()
+	id, err := resolveFallbackPlanID(context.Background(), nil, "  ")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if id != 0 {
+		t.Fatalf("got %d, want 0", id)
+	}
+}
+
+func TestNormalizeAssignPlanName(t *testing.T) {
+	t.Parallel()
+	got, err := normalizeAssignPlanName(" Free ", true)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got != "Free" {
+		t.Fatalf("got %q", got)
+	}
+	_, err = normalizeAssignPlanName("  ", true)
+	if err == nil || !strings.Contains(err.Error(), "-plan-name") {
+		t.Fatalf("expected plan-name error, got %v", err)
+	}
+	got, err = normalizeAssignPlanName("  ", false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got != "" {
+		t.Fatalf("list-only allows empty plan name, got %q", got)
+	}
+}
+
+func TestGuardLiveAssign(t *testing.T) {
+	t.Parallel()
+	if err := guardLiveAssign(false, false, false); err != nil {
+		t.Fatalf("list-only: %v", err)
+	}
+	if err := guardLiveAssign(true, true, false); err != nil {
+		t.Fatalf("dry-run: %v", err)
+	}
+	if err := guardLiveAssign(true, false, true); err != nil {
+		t.Fatalf("confirm: %v", err)
+	}
+	err := guardLiveAssign(true, false, false)
+	if err == nil || !strings.Contains(err.Error(), "no blind live writes") {
+		t.Fatalf("expected blind-assign refusal, got %v", err)
+	}
+}

apps/api/cmd/migrator/config.go

@@ -0,0 +1,181 @@
+package main
+
+import (
+	"fmt"
+	"strings"
+	"time"
+)
+
+// MigratorConfig holds portable CLI options for MySQL → Postgres ETL.
+type MigratorConfig struct {
+	MySQLDSN       string
+	PostgresURL    string
+	DryRun         bool
+	MapsDir        string
+	IDMapPath      string
+	ReportDir      string
+	FixturePath    string
+	Resume         bool
+	CompanyFilter  []string // legacy company ids; empty = all
+	Domains        domainSet
+	SkipPostImport bool
+	EnsureDemo     bool
+	DemoEmail      string
+	DemoPassword   string
+	DemoName       string
+	LocalDemoCo    string
+}
+
+type domainSet map[string]bool
+
+func parseDomains(raw string) domainSet {
+	raw = strings.TrimSpace(strings.ToLower(raw))
+	if raw == "" || raw == "all" {
+		return domainSet{"all": true}
+	}
+	out := domainSet{}
+	for _, p := range strings.Split(raw, ",") {
+		p = strings.TrimSpace(p)
+		if p == "" {
+			continue
+		}
+		out[p] = true
+	}
+	if len(out) == 0 {
+		return domainSet{"all": true}
+	}
+	return out
+}
+
+func (d domainSet) has(name string) bool {
+	if d == nil || d["all"] {
+		return true
+	}
+	return d[name]
+}
+
+func (d domainSet) String() string {
+	if d == nil || d["all"] {
+		return "all"
+	}
+	parts := make([]string, 0, len(d))
+	for k := range d {
+		parts = append(parts, k)
+	}
+	return strings.Join(parts, ",")
+}
+
+func parseCompanyFilter(raw string) []string {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return nil
+	}
+	var out []string
+	seen := map[string]bool{}
+	for _, p := range strings.Split(raw, ",") {
+		p = strings.TrimSpace(p)
+		if p == "" || seen[p] {
+			continue
+		}
+		seen[p] = true
+		out = append(out, p)
+	}
+	return out
+}
+
+func companyFilterSet(ids []string) map[string]bool {
+	if len(ids) == 0 {
+		return nil
+	}
+	m := make(map[string]bool, len(ids))
+	for _, id := range ids {
+		m[id] = true
+	}
+	return m
+}
+
+func filterCompanies(rows []companyRow, allow map[string]bool) []companyRow {
+	if allow == nil {
+		return rows
+	}
+	out := make([]companyRow, 0, len(rows))
+	for _, c := range rows {
+		if allow[c.LegacyID] {
+			out = append(out, c)
+		}
+	}
+	return out
+}
+
+// mysqlCompanyFilter appends AND company_id IN (...) when a filter is set.
+// Values are bound as ? placeholders; the column path is validated and quoted.
+func mysqlCompanyFilter(column string, allow map[string]bool) (clause string, args []any) {
+	if len(allow) == 0 {
+		return "", nil
+	}
+	quotedCol, err := quoteMySQLIdentPath(column)
+	if err != nil {
+		panic(err)
+	}
+	ids := make([]string, 0, len(allow))
+	for id := range allow {
+		ids = append(ids, id)
+	}
+	placeholders := make([]string, len(ids))
+	args = make([]any, len(ids))
+	for i, id := range ids {
+		placeholders[i] = "?"
+		args[i] = id
+	}
+	return fmt.Sprintf(" AND %s IN (%s)", quotedCol, strings.Join(placeholders, ",")), args
+}
+
+// MigrationRunReport is the portable JSON artifact written after each run.
+type MigrationRunReport struct {
+	GeneratedAt   string         `json:"generated_at"`
+	Mode          string         `json:"mode"`
+	Domains       string         `json:"domains"`
+	CompanyFilter []string       `json:"company_filter,omitempty"`
+	Resume        bool           `json:"resume"`
+	Counts        map[string]int `json:"counts"`
+	Validation    any            `json:"validation,omitempty"`
+	Demo          *DemoReport    `json:"demo,omitempty"`
+	Notes         []string       `json:"notes,omitempty"`
+	ElapsedMS     int64          `json:"elapsed_ms"`
+}
+
+// DemoReport documents the ensure-demo outcome (no password plaintext).
+type DemoReport struct {
+	Email          string `json:"email"`
+	PasswordSet    bool   `json:"password_set"`
+	UserID         string `json:"user_id,omitempty"`
+	PrimaryCompany string `json:"primary_company,omitempty"`
+	PrimaryName    string `json:"primary_company_name,omitempty"`
+	Memberships    int64  `json:"memberships_admin"`
+	PlatformAdmin  bool   `json:"platform_admin"`
+	Note           string `json:"note,omitempty"`
+}
+
+func newRunReport(cfg MigratorConfig, dryRun bool) *MigrationRunReport {
+	mode := "live"
+	if dryRun {
+		mode = "dry-run"
+	}
+	return &MigrationRunReport{
+		GeneratedAt:   time.Now().UTC().Format(time.RFC3339),
+		Mode:          mode,
+		Domains:       cfg.Domains.String(),
+		CompanyFilter: append([]string(nil), cfg.CompanyFilter...),
+		Resume:        cfg.Resume,
+		Counts:        map[string]int{},
+		Notes: []string{
+			"Clerk is excluded: users mapped by email only; no Clerk API.",
+			"Legacy password hashes are never imported.",
+			"API key secrets are not migrated; clients must mint new keys (seed-demo / ensure-demo for local).",
+			"File blobs are metadata-only; resync object storage separately.",
+			"Job history: domain jobs migrates processing_jobs (+ best-effort job_products) and tasks; tagged ai_provider_mode=migrated so retention keeps them.",
+			"company_settings: language + merge_products only (domain settings); other legacy settings fields are not imported.",
+			"woocommerce_configs: migrated from wc_* custom_fields when domain woo is enabled.",
+		},
+	}
+}

apps/api/cmd/migrator/config_test.go

@@ -0,0 +1,53 @@
+package main
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestParseDomains(t *testing.T) {
+	all := parseDomains("all")
+	if !all.has("products") || !all.has("woo") {
+		t.Fatalf("all should include every domain")
+	}
+	d := parseDomains("settings,formulas,tags")
+	if d.has("products") {
+		t.Fatalf("products should be excluded")
+	}
+	if !d.has("settings") || !d.has("formulas") || !d.has("tags") {
+		t.Fatalf("expected settings/formulas/tags: %#v", d)
+	}
+}
+
+func TestParseCompanyFilter(t *testing.T) {
+	ids := parseCompanyFilter(" a ,b, a ")
+	if len(ids) != 2 || ids[0] != "a" || ids[1] != "b" {
+		t.Fatalf("got %#v", ids)
+	}
+	set := companyFilterSet(ids)
+	if !set["a"] || set["c"] {
+		t.Fatalf("set %#v", set)
+	}
+	filtered := filterCompanies([]companyRow{{LegacyID: "a"}, {LegacyID: "c"}}, set)
+	if len(filtered) != 1 || filtered[0].LegacyID != "a" {
+		t.Fatalf("filtered %#v", filtered)
+	}
+}
+
+func TestMysqlCompanyFilter(t *testing.T) {
+	clause, args := mysqlCompanyFilter("company_id", map[string]bool{"x": true, "y": true})
+	if clause == "" || len(args) != 2 {
+		t.Fatalf("clause=%q args=%v", clause, args)
+	}
+	if !strings.Contains(clause, "`company_id`") || !strings.Contains(clause, "?") {
+		t.Fatalf("expected quoted column and placeholders: %q", clause)
+	}
+	qual, qArgs := mysqlCompanyFilter("cf.company_id", map[string]bool{"a": true})
+	if len(qArgs) != 1 || qual != " AND `cf`.`company_id` IN (?)" {
+		t.Fatalf("qualified: clause=%q args=%v", qual, qArgs)
+	}
+	empty, emptyArgs := mysqlCompanyFilter("company_id", nil)
+	if empty != "" || emptyArgs != nil {
+		t.Fatalf("expected empty filter")
+	}
+}

apps/api/cmd/migrator/demo.go

@@ -0,0 +1,150 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"github.com/descrybe/descrybe-v2/apps/api/internal/auth"
+	"github.com/descrybe/descrybe-v2/apps/api/internal/billing"
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+const defaultMigratorDemoCompany = "Platform Demo"
+
+// ensureDemoUser upserts a local demo account (no Clerk), makes them platform admin,
+// and binds them only to a standalone Platform Demo company (never A1 / every tenant).
+func ensureDemoUser(
+	ctx context.Context,
+	pg *pgxpool.Pool,
+	email, password, displayName, localDemoName string,
+	dryRun bool,
+	report map[string]int,
+) (*DemoReport, error) {
+	emailNorm := strings.ToLower(strings.TrimSpace(email))
+	if emailNorm == "" || password == "" {
+		return nil, fmt.Errorf("demo email and password required")
+	}
+	if localDemoName == "" {
+		localDemoName = defaultMigratorDemoCompany
+	}
+	if displayName == "" {
+		displayName = "Demo User"
+	}
+	out := &DemoReport{
+		Email:         emailNorm,
+		PasswordSet:   true,
+		PlatformAdmin: true,
+		Note:          "Password documented in docs/portable-mysql-pg-migration.md (not written to report JSON).",
+	}
+	if dryRun {
+		report["demo_user"] = 1
+		out.Note = "dry-run: demo user not written"
+		out.PasswordSet = false
+		return out, nil
+	}
+
+	hash, err := auth.HashPassword(password)
+	if err != nil {
+		return nil, err
+	}
+
+	tx, err := pg.Begin(ctx)
+	if err != nil {
+		return nil, err
+	}
+	defer tx.Rollback(ctx)
+
+	var userID uuid.UUID
+	err = tx.QueryRow(ctx, `
+		INSERT INTO users (
+			email, name, password_hash, must_set_password,
+			is_platform_admin, is_active, updated_at
+		) VALUES ($1, $2, $3, false, true, true, now())
+		ON CONFLICT (email) DO UPDATE SET
+			name = EXCLUDED.name,
+			password_hash = EXCLUDED.password_hash,
+			must_set_password = false,
+			is_platform_admin = true,
+			is_active = true,
+			updated_at = now()
+		RETURNING id`, emailNorm, displayName, hash).Scan(&userID)
+	if err != nil {
+		return nil, fmt.Errorf("upsert demo user: %w", err)
+	}
+	out.UserID = userID.String()
+
+	demoCompanyID, demoName, err := ensureMigratorDemoCompany(ctx, tx, localDemoName)
+	if err != nil {
+		return nil, err
+	}
+	out.PrimaryCompany = demoCompanyID.String()
+	out.PrimaryName = demoName
+
+	ct, err := tx.Exec(ctx, `
+		INSERT INTO memberships (company_id, user_id, role, status)
+		VALUES ($1, $2, 'admin', 'active')
+		ON CONFLICT (company_id, user_id) DO UPDATE
+		SET role = 'admin', status = 'active', updated_at = now()`, demoCompanyID, userID)
+	if err != nil {
+		return nil, fmt.Errorf("demo membership: %w", err)
+	}
+	if _, err := tx.Exec(ctx, `
+		DELETE FROM memberships
+		WHERE user_id = $1 AND company_id <> $2`, userID, demoCompanyID); err != nil {
+		return nil, fmt.Errorf("remove non-demo memberships: %w", err)
+	}
+	out.Memberships = ct.RowsAffected()
+
+	if err := tx.Commit(ctx); err != nil {
+		return nil, err
+	}
+	report["demo_user"] = 1
+	report["demo_memberships"] = int(out.Memberships)
+	return out, nil
+}
+
+func ensureMigratorDemoCompany(ctx context.Context, tx pgx.Tx, name string) (uuid.UUID, string, error) {
+	name = strings.TrimSpace(name)
+	if name == "" {
+		name = defaultMigratorDemoCompany
+	}
+	if strings.EqualFold(name, "A1 Slovenija") || strings.EqualFold(name, "A1") || strings.EqualFold(name, "Local Demo Co") {
+		return uuid.Nil, "", fmt.Errorf("demo company name %q collides with A1 tenant — use %q", name, defaultMigratorDemoCompany)
+	}
+
+	var id uuid.UUID
+	err := tx.QueryRow(ctx, `
+		SELECT c.id
+		FROM companies c
+		WHERE c.name = $1
+		  AND COALESCE(c.legacy_company_id, '') <> $2
+		ORDER BY c.created_at ASC
+		LIMIT 1`, name, billing.A1LegacyCompanyID).Scan(&id)
+	if err == nil {
+		if _, err := tx.Exec(ctx, `INSERT INTO company_settings (company_id) VALUES ($1) ON CONFLICT DO NOTHING`, id); err != nil {
+			return uuid.Nil, "", err
+		}
+		if _, err := tx.Exec(ctx, `INSERT INTO credit_balances (company_id) VALUES ($1) ON CONFLICT DO NOTHING`, id); err != nil {
+			return uuid.Nil, "", err
+		}
+		return id, name, nil
+	}
+	if err != pgx.ErrNoRows {
+		return uuid.Nil, "", err
+	}
+
+	err = tx.QueryRow(ctx, `INSERT INTO companies (name) VALUES ($1) RETURNING id`, name).Scan(&id)
+	if err != nil {
+		return uuid.Nil, "", err
+	}
+	if _, err := tx.Exec(ctx, `INSERT INTO company_settings (company_id) VALUES ($1) ON CONFLICT DO NOTHING`, id); err != nil {
+		return uuid.Nil, "", err
+	}
+	if _, err := tx.Exec(ctx, `INSERT INTO credit_balances (company_id) VALUES ($1) ON CONFLICT DO NOTHING`, id); err != nil {
+		return uuid.Nil, "", err
+	}
+	return id, name, nil
+}

apps/api/cmd/migrator/files.go

@@ -0,0 +1,109 @@
+package main
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"log"
+	"strconv"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// migrateFiles copies file *metadata* only.
+//
+// Blobs strategy (cutover):
+//   - Do NOT stream MySQL/local blob bytes through the migrator.
+//   - Preserve legacy url/path in files.path and legacy id in metadata._legacy_file_id.
+//   - Operators re-attach object storage / local volumes under the same relative paths,
+//     or run a separate rsync/S3 sync keyed by legacy id after DNS freeze.
+//   - raw_products.file_id is left unset until a follow-up remapper exists.
+func migrateFiles(
+	ctx context.Context,
+	mysqlDB *sql.DB,
+	pg *pgxpool.Pool,
+	companyMap, userMap, fileMap map[string]string,
+	allow map[string]bool,
+	report map[string]int,
+	dryRun bool,
+) {
+	if !mysqlTableExists(ctx, mysqlDB, "files") {
+		log.Printf("files skipped: table missing (blobs strategy: metadata-only when present)")
+		return
+	}
+
+	clause, cargs := mysqlCompanyFilter("company_id", allow)
+	rows, err := mysqlDB.QueryContext(ctx, `
+		SELECT id, company_id, COALESCE(user_id, ''), file_name,
+			COALESCE(file_type, ''), COALESCE(file_size, 0),
+			COALESCE(status, 'uploaded'), url, metadata
+		FROM files WHERE 1=1`+clause, cargs...)
+	if err != nil {
+		// Older dumps may lack metadata/url/status.
+		rows, err = mysqlDB.QueryContext(ctx, `
+			SELECT id, company_id, COALESCE(user_id, ''), file_name,
+				COALESCE(file_type, ''), COALESCE(file_size, 0),
+				'uploaded', NULL, NULL
+			FROM files WHERE 1=1`+clause, cargs...)
+	}
+	if err != nil {
+		log.Printf("files skipped: %v", err)
+		return
+	}
+	defer rows.Close()
+
+	for rows.Next() {
+		var legacyID int64
+		var companyLegacy, userLegacy, name, fileType, status string
+		var size int64
+		var url sql.NullString
+		var metadata []byte
+		if err := rows.Scan(&legacyID, &companyLegacy, &userLegacy, &name, &fileType, &size, &status, &url, &metadata); err != nil {
+			report["files_skipped"]++
+			continue
+		}
+		cid, ok := companyMap[companyLegacy]
+		if !ok {
+			report["files_skipped"]++
+			continue
+		}
+		meta := map[string]any{}
+		if len(metadata) > 0 {
+			_ = json.Unmarshal(metadata, &meta)
+		}
+		meta["_legacy_file_id"] = legacyID
+		meta["_blob_strategy"] = "metadata_only_resync_paths"
+		if fileType != "" {
+			meta["file_type"] = fileType
+		}
+		metaBytes, _ := json.Marshal(meta)
+
+		newID := uuid.New()
+		legacyKey := strconv.FormatInt(legacyID, 10)
+		fileMap[legacyKey] = newID.String()
+
+		var uid *string
+		if userLegacy != "" {
+			if mapped, ok := userMap[userLegacy]; ok {
+				uid = &mapped
+			}
+		}
+
+		if dryRun {
+			report["files"]++
+			continue
+		}
+		_, err = pg.Exec(ctx, `
+			INSERT INTO files (id, company_id, user_id, name, path, content_type, size_bytes, status, metadata)
+			VALUES ($1, $2, $3::uuid, $4, $5, $6, $7, $8, $9::jsonb)`,
+			newID, cid, uid, name, nullString(url), nullStr(fileType), size, status, string(metaBytes))
+		if err != nil {
+			log.Printf("files insert %d: %v", legacyID, err)
+			delete(fileMap, legacyKey)
+			report["files_skipped"]++
+			continue
+		}
+		report["files"]++
+	}
+}

apps/api/cmd/migrator/fixture.go

@@ -0,0 +1,165 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"log"
+	"os"
+	"path/filepath"
+
+	"github.com/google/uuid"
+)
+
+// MigratorFixture is a minimal offline dump for dry-run without MySQL.
+// It is NOT a substitute for validating against production MySQL.
+type MigratorFixture struct {
+	Companies []struct {
+		ID       string `json:"id"`
+		Name     string `json:"name"`
+		Language string `json:"language"`
+	} `json:"companies"`
+	Users []struct {
+		ID     string `json:"id"`
+		Email  string `json:"email"`
+		Name   string `json:"name"`
+		Active bool   `json:"active"`
+	} `json:"users"`
+	AdminUsers []struct {
+		UserID string `json:"user_id"`
+		Email  string `json:"email"`
+	} `json:"admin_users"`
+	Profiles []struct {
+		CompanyID string `json:"company_id"`
+		UserID    string `json:"user_id"`
+		Role      string `json:"role"`
+		Status    string `json:"status"`
+	} `json:"profiles"`
+	XMLFeeds []struct {
+		ID            int64           `json:"id"`
+		CompanyID     string          `json:"company_id"`
+		Name          string          `json:"name"`
+		FieldMappings json.RawMessage `json:"field_mappings"`
+	} `json:"xml_feeds"`
+	Files []struct {
+		ID        int64  `json:"id"`
+		CompanyID string `json:"company_id"`
+		FileName  string `json:"file_name"`
+	} `json:"files"`
+	RawProducts int `json:"raw_products_count"`
+}
+
+func loadFixture(path string) (*MigratorFixture, error) {
+	b, err := os.ReadFile(path)
+	if err != nil {
+		return nil, err
+	}
+	var f MigratorFixture
+	if err := json.Unmarshal(b, &f); err != nil {
+		return nil, err
+	}
+	return &f, nil
+}
+
+// runFixtureDryRun remaps fixture rows and writes id-map + validation-style counts
+// without connecting to MySQL or Postgres.
+func runFixtureDryRun(fixturePath, mapsDir, idMapPath string) {
+	fx, err := loadFixture(fixturePath)
+	if err != nil {
+		log.Fatalf("fixture: %v", err)
+	}
+	if err := os.MkdirAll(mapsDir, 0o755); err != nil {
+		log.Fatalf("maps dir: %v", err)
+	}
+	outIDMap := idMapPath
+	if outIDMap == "" {
+		outIDMap = filepath.Join(mapsDir, "id-map.json")
+	}
+
+	report := map[string]int{}
+	companyMap := map[string]string{}
+	userMap := map[string]string{}
+	feedMap := map[string]string{}
+	fileMap := map[string]string{}
+
+	for _, c := range fx.Companies {
+		companyMap[c.ID] = uuid.New().String()
+		report["companies"]++
+	}
+	for _, u := range fx.Users {
+		userMap[u.ID] = uuid.New().String()
+		report["users"]++
+	}
+	for _, a := range fx.AdminUsers {
+		if _, ok := userMap[a.UserID]; ok {
+			report["admin_users"]++
+		} else {
+			report["admin_users_unmatched"]++
+		}
+	}
+	for _, p := range fx.Profiles {
+		if _, okC := companyMap[p.CompanyID]; !okC {
+			report["memberships_skipped"]++
+			continue
+		}
+		if _, okU := userMap[p.UserID]; !okU {
+			report["memberships_skipped"]++
+			continue
+		}
+		report["memberships"]++
+	}
+	for _, f := range fx.XMLFeeds {
+		if _, ok := companyMap[f.CompanyID]; !ok {
+			report["input_feeds_skipped"]++
+			continue
+		}
+		feedMap[fmt.Sprintf("%d", f.ID)] = uuid.New().String()
+		report["input_feeds"]++
+		if len(f.FieldMappings) > 0 && string(f.FieldMappings) != "null" && string(f.FieldMappings) != "{}" {
+			report["feed_mappings"]++
+		}
+	}
+	for _, f := range fx.Files {
+		if _, ok := companyMap[f.CompanyID]; !ok {
+			report["files_skipped"]++
+			continue
+		}
+		fileMap[fmt.Sprintf("%d", f.ID)] = uuid.New().String()
+		report["files"]++
+	}
+	report["raw_products"] = fx.RawProducts
+
+	idDoc := NewIDMapDocument(userMap, companyMap, true)
+	idDoc.Source = "fixture"
+	idDoc.AttachEntityMaps(nil, nil, feedMap, nil, fileMap, report)
+	if err := WriteIDMap(outIDMap, idDoc); err != nil {
+		log.Fatalf("id-map: %v", err)
+	}
+	writeEntityMapFiles(mapsDir, companyMap, userMap, nil, nil, feedMap, nil, fileMap)
+
+	counts := []CountPair{
+		{Entity: "companies", MySQL: int64(len(fx.Companies)), Note: "fixture"},
+		{Entity: "users", MySQL: int64(len(fx.Users)), Note: "fixture; password_hash never imported"},
+		{Entity: "admin_users", MySQL: int64(len(fx.AdminUsers)), Note: "→ is_platform_admin"},
+		{Entity: "profiles", MySQL: int64(len(fx.Profiles)), Note: "→ memberships"},
+		{Entity: "xml_feeds", MySQL: int64(len(fx.XMLFeeds)), Note: "→ input_feeds + feed_mappings"},
+		{Entity: "files", MySQL: int64(len(fx.Files)), Note: "metadata only"},
+		{Entity: "raw_products", MySQL: int64(fx.RawProducts), Note: "count-only in fixture"},
+	}
+	v := ValidationReport{
+		Mode:   "fixture-dry-run",
+		Counts: counts,
+		Orphans: []OrphanFinding{{
+			Check:  "skipped_fixture",
+			Pass:   true,
+			Sample: "orphan checks need live Postgres after a real load",
+		}},
+		OK: true,
+	}
+	v.OrphanSummary = summarizeOrphans(v.Orphans)
+	printValidation(v)
+	_ = writeJSON(filepath.Join(mapsDir, "validation-report.json"), v)
+
+	printMigrationReport(report, true)
+	fmt.Printf("wrote maps under %s (unified: %s)\n", mapsDir, outIDMap)
+	fmt.Println("BLOCKER: fixture mode is not a substitute for dry-run against production MySQL — set MIGRATE_MYSQL_DSN and re-run before cutover.")
+}

apps/api/cmd/migrator/gaps.go

@@ -0,0 +1,619 @@
+package main
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"log"
+	"strconv"
+	"strings"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// migrateGapDomains loads settings, formulas (standard fields), tags, woo, and usage snapshots.
+func migrateGapDomains(
+	ctx context.Context,
+	mysqlDB *sql.DB,
+	pg *pgxpool.Pool,
+	companyMap map[string]string,
+	feedMap map[string]string,
+	allow map[string]bool,
+	domains domainSet,
+	report map[string]int,
+	dryRun bool,
+) {
+	if domains.has("settings") {
+		migrateCompanySettings(ctx, mysqlDB, pg, companyMap, allow, report, dryRun)
+	}
+	if domains.has("formulas") {
+		migrateFieldGroupsAndStandards(ctx, mysqlDB, pg, companyMap, allow, report, dryRun)
+		migrateStructuredDescriptionFields(ctx, mysqlDB, pg, companyMap, allow, report, dryRun)
+	}
+	if domains.has("tags") {
+		migrateFeedTags(ctx, mysqlDB, pg, companyMap, feedMap, allow, report, dryRun)
+	}
+	if domains.has("woo") {
+		migrateWooConfigs(ctx, mysqlDB, pg, companyMap, allow, report, dryRun)
+	}
+	if domains.has("usage") {
+		migrateUsageIntoSettings(ctx, mysqlDB, pg, companyMap, allow, report, dryRun)
+	}
+}
+
+func migrateCompanySettings(
+	ctx context.Context,
+	mysqlDB *sql.DB,
+	pg *pgxpool.Pool,
+	companyMap map[string]string,
+	allow map[string]bool,
+	report map[string]int,
+	dryRun bool,
+) {
+	if !mysqlTableExists(ctx, mysqlDB, "company_settings") {
+		log.Printf("company_settings skipped: table missing")
+		return
+	}
+	lang := mysqlCoalesce(ctx, mysqlDB, "company_settings", "language", "'en'")
+	merge := mysqlCoalesce(ctx, mysqlDB, "company_settings", "merge_products", "1")
+	q := "SELECT company_id, " + lang + ", " + merge + " FROM company_settings WHERE company_id IS NOT NULL AND company_id <> ''"
+	clause, args := mysqlCompanyFilter("company_id", allow)
+	q += clause
+	rows, err := mysqlDB.QueryContext(ctx, q, args...)
+	if err != nil {
+		log.Printf("company_settings skipped: %v", err)
+		return
+	}
+	defer rows.Close()
+	for rows.Next() {
+		var companyLegacy, language string
+		var mergeProducts int
+		if err := rows.Scan(&companyLegacy, &language, &mergeProducts); err != nil {
+			report["company_settings_skipped"]++
+			continue
+		}
+		cid, ok := companyMap[companyLegacy]
+		if !ok {
+			report["company_settings_skipped"]++
+			continue
+		}
+		if language == "" {
+			language = "en"
+		}
+		settings := map[string]any{
+			"language":       language,
+			"merge_products": mergeProducts == 1,
+			"_legacy":        true,
+		}
+		b, _ := json.Marshal(settings)
+		if dryRun {
+			report["company_settings"]++
+			continue
+		}
+		_, err = pg.Exec(ctx, `
+			INSERT INTO company_settings (company_id, settings, updated_at)
+			VALUES ($1, $2::jsonb, now())
+			ON CONFLICT (company_id) DO UPDATE SET
+				settings = company_settings.settings || EXCLUDED.settings,
+				updated_at = now()`, cid, string(b))
+		if err != nil {
+			log.Printf("company_settings %s: %v", companyLegacy, err)
+			report["company_settings_skipped"]++
+			continue
+		}
+		report["company_settings"]++
+	}
+}
+
+func migrateFieldGroupsAndStandards(
+	ctx context.Context,
+	mysqlDB *sql.DB,
+	pg *pgxpool.Pool,
+	companyMap map[string]string,
+	allow map[string]bool,
+	report map[string]int,
+	dryRun bool,
+) {
+	if !mysqlTableExists(ctx, mysqlDB, "field_groups") {
+		log.Printf("field_groups skipped: table missing")
+		return
+	}
+	groupMap := map[string]string{} // legacy group uuid → new uuid
+	clause, args := mysqlCompanyFilter("company_id", allow)
+	orderCol := mustQuoteMySQLIdent("order")
+	q := "SELECT id, company_id, name, COALESCE(description, ''), COALESCE(" + orderCol + ", 0), COALESCE(is_system, 0) FROM field_groups WHERE company_id IS NOT NULL AND company_id <> ''" + clause
+	// MySQL may use order without backticks in some dumps — try fallbacks.
+	rows, err := mysqlDB.QueryContext(ctx, q, args...)
+	if err != nil {
+		q2 := `SELECT id, company_id, name, COALESCE(description, ''), 0, COALESCE(is_system, 0)
+			FROM field_groups WHERE company_id IS NOT NULL AND company_id <> ''` + clause
+		rows, err = mysqlDB.QueryContext(ctx, q2, args...)
+	}
+	if err != nil {
+		log.Printf("field_groups skipped: %v", err)
+		return
+	}
+	defer rows.Close()
+	for rows.Next() {
+		var legacyID, companyLegacy, name, desc string
+		var order, isSystem int
+		if err := rows.Scan(&legacyID, &companyLegacy, &name, &desc, &order, &isSystem); err != nil {
+			report["field_groups_skipped"]++
+			continue
+		}
+		cid, ok := companyMap[companyLegacy]
+		if !ok {
+			report["field_groups_skipped"]++
+			continue
+		}
+		newID := uuid.New()
+		if parsed, err := uuid.Parse(legacyID); err == nil {
+			newID = parsed // preserve UUID when already uuid-shaped
+		}
+		groupMap[legacyID] = newID.String()
+		if dryRun {
+			report["field_groups"]++
+			continue
+		}
+		_, err = pg.Exec(ctx, `
+			INSERT INTO field_groups (id, company_id, name, description, "order", is_system)
+			VALUES ($1, $2, $3, NULLIF($4, ''), $5, $6)
+			ON CONFLICT (id) DO UPDATE SET
+				name = EXCLUDED.name,
+				description = EXCLUDED.description,
+				"order" = EXCLUDED."order",
+				updated_at = now()`,
+			newID, cid, name, desc, order, isSystem == 1)
+		if err != nil {
+			log.Printf("field_group %s: %v", legacyID, err)
+			report["field_groups_skipped"]++
+			delete(groupMap, legacyID)
+			continue
+		}
+		report["field_groups"]++
+	}
+
+	if !mysqlTableExists(ctx, mysqlDB, "standard_fields") {
+		return
+	}
+	keyCol := mustQuoteMySQLIdent("key")
+	sq := "SELECT id, company_id, name, " + keyCol + ", type, group_id, COALESCE(is_required, 0), COALESCE(description, ''), COALESCE(default_value, ''), validation, COALESCE(is_system, 0) FROM standard_fields WHERE company_id IS NOT NULL AND company_id <> ''" + clause
+	srows, err := mysqlDB.QueryContext(ctx, sq, args...)
+	if err != nil {
+		log.Printf("standard_fields skipped: %v", err)
+		return
+	}
+	defer srows.Close()
+	for srows.Next() {
+		var legacyID, companyLegacy, name, key, typ, groupLegacy string
+		var desc, defVal string
+		var required, isSystem int
+		var validation []byte
+		if err := srows.Scan(&legacyID, &companyLegacy, &name, &key, &typ, &groupLegacy,
+			&required, &desc, &defVal, &validation, &isSystem); err != nil {
+			report["standard_fields_skipped"]++
+			continue
+		}
+		cid, ok := companyMap[companyLegacy]
+		if !ok {
+			report["standard_fields_skipped"]++
+			continue
+		}
+		gid, okG := groupMap[groupLegacy]
+		if !okG {
+			// group may already exist in PG with same UUID
+			gid = groupLegacy
+		}
+		newID := uuid.New()
+		if parsed, err := uuid.Parse(legacyID); err == nil {
+			newID = parsed
+		}
+		if typ == "" {
+			typ = "string"
+		}
+		if dryRun {
+			report["standard_fields"]++
+			continue
+		}
+		_, err = pg.Exec(ctx, `
+			INSERT INTO standard_fields (
+				id, company_id, name, key, type, group_id, is_required,
+				description, default_value, validation, is_system
+			) VALUES (
+				$1, $2, $3, $4, $5, $6::uuid, $7, NULLIF($8, ''), NULLIF($9, ''),
+				COALESCE($10::jsonb, '{}'::jsonb), $11
+			)
+			ON CONFLICT (company_id, key) DO UPDATE SET
+				name = EXCLUDED.name,
+				type = EXCLUDED.type,
+				group_id = EXCLUDED.group_id,
+				is_required = EXCLUDED.is_required,
+				description = EXCLUDED.description,
+				default_value = EXCLUDED.default_value,
+				validation = EXCLUDED.validation,
+				updated_at = now()`,
+			newID, cid, name, key, typ, gid, required == 1, desc, defVal,
+			jsonOrNull(validation), isSystem == 1)
+		if err != nil {
+			log.Printf("standard_field %s: %v", legacyID, err)
+			report["standard_fields_skipped"]++
+			continue
+		}
+		report["standard_fields"]++
+	}
+}
+
+func migrateStructuredDescriptionFields(
+	ctx context.Context,
+	mysqlDB *sql.DB,
+	pg *pgxpool.Pool,
+	companyMap map[string]string,
+	allow map[string]bool,
+	report map[string]int,
+	dryRun bool,
+) {
+	if !mysqlTableExists(ctx, mysqlDB, "structured_description_fields") {
+		log.Printf("structured_description_fields skipped: table missing")
+		return
+	}
+	clause, args := mysqlCompanyFilter("company_id", allow)
+	q := `SELECT id, company_id, field_key, COALESCE(type, 'text')
+		FROM structured_description_fields
+		WHERE company_id IS NOT NULL AND company_id <> ''` + clause
+	rows, err := mysqlDB.QueryContext(ctx, q, args...)
+	if err != nil {
+		log.Printf("structured_description_fields skipped: %v", err)
+		return
+	}
+	defer rows.Close()
+	for rows.Next() {
+		var legacyID, companyLegacy, fieldKey, typ string
+		if err := rows.Scan(&legacyID, &companyLegacy, &fieldKey, &typ); err != nil {
+			report["structured_description_fields_skipped"]++
+			continue
+		}
+		cid, ok := companyMap[companyLegacy]
+		if !ok {
+			report["structured_description_fields_skipped"]++
+			continue
+		}
+		newID := uuid.New()
+		if parsed, err := uuid.Parse(legacyID); err == nil {
+			newID = parsed
+		}
+		if dryRun {
+			report["structured_description_fields"]++
+			continue
+		}
+		_, err = pg.Exec(ctx, `
+			INSERT INTO structured_description_fields (id, company_id, field_key, type)
+			VALUES ($1, $2, $3, $4)
+			ON CONFLICT (company_id, field_key) DO UPDATE SET
+				type = EXCLUDED.type, updated_at = now()`,
+			newID, cid, fieldKey, typ)
+		if err != nil {
+			log.Printf("structured_description_field %s: %v", legacyID, err)
+			report["structured_description_fields_skipped"]++
+			continue
+		}
+		report["structured_description_fields"]++
+	}
+}
+
+func migrateFeedTags(
+	ctx context.Context,
+	mysqlDB *sql.DB,
+	pg *pgxpool.Pool,
+	companyMap, feedMap map[string]string,
+	allow map[string]bool,
+	report map[string]int,
+	dryRun bool,
+) {
+	if !mysqlTableExists(ctx, mysqlDB, "feed_tags") {
+		log.Printf("feed_tags skipped: table missing")
+		return
+	}
+	tagMap := map[string]string{}
+	clause, args := mysqlCompanyFilter("company_id", allow)
+	q := `SELECT id, company_id, name, COALESCE(color, '#888888')
+		FROM feed_tags WHERE company_id IS NOT NULL AND company_id <> ''` + clause
+	rows, err := mysqlDB.QueryContext(ctx, q, args...)
+	if err != nil {
+		log.Printf("feed_tags skipped: %v", err)
+		return
+	}
+	defer rows.Close()
+	for rows.Next() {
+		var legacyID int64
+		var companyLegacy, name, color string
+		if err := rows.Scan(&legacyID, &companyLegacy, &name, &color); err != nil {
+			report["feed_tags_skipped"]++
+			continue
+		}
+		cid, ok := companyMap[companyLegacy]
+		if !ok {
+			report["feed_tags_skipped"]++
+			continue
+		}
+		newID := uuid.New()
+		tagMap[strconv.FormatInt(legacyID, 10)] = newID.String()
+		if dryRun {
+			report["feed_tags"]++
+			continue
+		}
+		_, err = pg.Exec(ctx, `
+			INSERT INTO feed_tags (id, company_id, name, color)
+			VALUES ($1, $2, $3, $4)
+			ON CONFLICT (company_id, name) DO UPDATE SET color = EXCLUDED.color`, newID, cid, name, color)
+		if err != nil {
+			var existing uuid.UUID
+			if err2 := pg.QueryRow(ctx, `SELECT id FROM feed_tags WHERE company_id = $1 AND name = $2`, cid, name).Scan(&existing); err2 == nil {
+				tagMap[strconv.FormatInt(legacyID, 10)] = existing.String()
+				report["feed_tags"]++
+				continue
+			}
+			log.Printf("feed_tag %d: %v", legacyID, err)
+			report["feed_tags_skipped"]++
+			continue
+		}
+		var existing uuid.UUID
+		_ = pg.QueryRow(ctx, `SELECT id FROM feed_tags WHERE company_id = $1 AND name = $2`, cid, name).Scan(&existing)
+		if existing != uuid.Nil {
+			tagMap[strconv.FormatInt(legacyID, 10)] = existing.String()
+		}
+		report["feed_tags"]++
+	}
+
+	if !mysqlTableExists(ctx, mysqlDB, "feed_tag_mappings") || len(tagMap) == 0 {
+		return
+	}
+	mrows, err := mysqlDB.QueryContext(ctx, `SELECT feed_id, tag_id FROM feed_tag_mappings`)
+	if err != nil {
+		log.Printf("feed_tag_mappings skipped: %v", err)
+		return
+	}
+	defer mrows.Close()
+	for mrows.Next() {
+		var feedLegacy, tagLegacy int64
+		if err := mrows.Scan(&feedLegacy, &tagLegacy); err != nil {
+			report["feed_tag_mappings_skipped"]++
+			continue
+		}
+		fid, okF := feedMap[strconv.FormatInt(feedLegacy, 10)]
+		tid, okT := tagMap[strconv.FormatInt(tagLegacy, 10)]
+		if !okF || !okT {
+			report["feed_tag_mappings_skipped"]++
+			continue
+		}
+		if dryRun {
+			report["feed_tag_mappings"]++
+			continue
+		}
+		_, err = pg.Exec(ctx, `
+			INSERT INTO feed_tag_mappings (feed_id, tag_id)
+			VALUES ($1, $2) ON CONFLICT DO NOTHING`, fid, tid)
+		if err != nil {
+			report["feed_tag_mappings_skipped"]++
+			continue
+		}
+		report["feed_tag_mappings"]++
+	}
+}
+
+func migrateWooConfigs(
+	ctx context.Context,
+	mysqlDB *sql.DB,
+	pg *pgxpool.Pool,
+	companyMap map[string]string,
+	allow map[string]bool,
+	report map[string]int,
+	dryRun bool,
+) {
+	// Legacy Woo settings live as per-company custom_fields named wc_*.
+	if !mysqlTableExists(ctx, mysqlDB, "custom_fields") || !mysqlTableExists(ctx, mysqlDB, "feed_custom_field_values") {
+		log.Printf("woocommerce_configs skipped: custom_fields tables missing")
+		report["woocommerce_configs_note"] = 1
+		return
+	}
+	clause, args := mysqlCompanyFilter("cf.company_id", allow)
+	q := `
+		SELECT cf.company_id, cf.name, COALESCE(fcfv.value, '')
+		FROM custom_fields cf
+		JOIN feed_custom_field_values fcfv ON fcfv.custom_field_id = cf.id
+		WHERE cf.name LIKE 'wc_%'` + clause
+	rows, err := mysqlDB.QueryContext(ctx, q, args...)
+	if err != nil {
+		log.Printf("woocommerce_configs skipped: %v", err)
+		return
+	}
+	defer rows.Close()
+	byCompany := map[string]map[string]string{}
+	for rows.Next() {
+		var companyLegacy, name, value string
+		if err := rows.Scan(&companyLegacy, &name, &value); err != nil {
+			continue
+		}
+		if _, ok := companyMap[companyLegacy]; !ok {
+			continue
+		}
+		if byCompany[companyLegacy] == nil {
+			byCompany[companyLegacy] = map[string]string{}
+		}
+		byCompany[companyLegacy][name] = value
+	}
+	if len(byCompany) == 0 {
+		log.Printf("woocommerce_configs: no wc_* custom fields found (ok)")
+		report["woocommerce_configs"] = 0
+		return
+	}
+	for legacyCID, fields := range byCompany {
+		cid := companyMap[legacyCID]
+		enabled := strings.EqualFold(fields["wc_enabled"], "true") || fields["wc_enabled"] == "1"
+		storeURL := firstNonEmpty(fields["wc_store_url"], fields["wc_url"], fields["wc_store"])
+		consumerKey := firstNonEmpty(fields["wc_consumer_key"], fields["wc_key"])
+		consumerSecret := firstNonEmpty(fields["wc_consumer_secret"], fields["wc_secret"])
+		syncOpts, _ := json.Marshal(fields)
+		if dryRun {
+			report["woocommerce_configs"]++
+			continue
+		}
+		_, err = pg.Exec(ctx, `
+			INSERT INTO woocommerce_configs (
+				company_id, store_url, consumer_key, consumer_secret, is_enabled, sync_options
+			) VALUES ($1, $2, $3, $4, $5, $6::jsonb)
+			ON CONFLICT (company_id) DO UPDATE SET
+				store_url = EXCLUDED.store_url,
+				consumer_key = EXCLUDED.consumer_key,
+				consumer_secret = EXCLUDED.consumer_secret,
+				is_enabled = EXCLUDED.is_enabled,
+				sync_options = EXCLUDED.sync_options,
+				updated_at = now()`,
+			cid, storeURL, consumerKey, consumerSecret, enabled, string(syncOpts))
+		if err != nil {
+			log.Printf("woocommerce_configs %s: %v", legacyCID, err)
+			report["woocommerce_configs_skipped"]++
+			continue
+		}
+		report["woocommerce_configs"]++
+	}
+}
+
+// migrateUsageIntoSettings folds latest usage_metrics into company_settings.settings._legacy_usage.
+// v2 has no usage_metrics table; this preserves a portable snapshot without N+1.
+func migrateUsageIntoSettings(
+	ctx context.Context,
+	mysqlDB *sql.DB,
+	pg *pgxpool.Pool,
+	companyMap map[string]string,
+	allow map[string]bool,
+	report map[string]int,
+	dryRun bool,
+) {
+	if !mysqlTableExists(ctx, mysqlDB, "usage_metrics") {
+		log.Printf("usage_metrics skipped: table missing")
+		return
+	}
+	clause, args := mysqlCompanyFilter("company_id", allow)
+	q := `
+		SELECT company_id,
+			SUM(COALESCE(credits_used, 0)),
+			MAX(COALESCE(total_products, 0)),
+			COUNT(*)
+		FROM usage_metrics
+		WHERE company_id IS NOT NULL AND company_id <> ''` + clause + `
+		GROUP BY company_id`
+	rows, err := mysqlDB.QueryContext(ctx, q, args...)
+	if err != nil {
+		log.Printf("usage_metrics skipped: %v", err)
+		return
+	}
+	defer rows.Close()
+
+	type snap struct {
+		CreditsUsed   float64 `json:"credits_used_sum"`
+		MaxProducts   int     `json:"max_total_products"`
+		MetricDays    int     `json:"metric_days"`
+	}
+	batch := make([][]any, 0)
+	for rows.Next() {
+		var companyLegacy string
+		var credits float64
+		var maxProducts, days int
+		if err := rows.Scan(&companyLegacy, &credits, &maxProducts, &days); err != nil {
+			report["usage_metrics_skipped"]++
+			continue
+		}
+		cid, ok := companyMap[companyLegacy]
+		if !ok {
+			report["usage_metrics_skipped"]++
+			continue
+		}
+		payload, _ := json.Marshal(map[string]any{
+			"_legacy_usage": snap{CreditsUsed: credits, MaxProducts: maxProducts, MetricDays: days},
+		})
+		if dryRun {
+			report["usage_metrics"]++
+			continue
+		}
+		batch = append(batch, []any{cid, string(payload)})
+		report["usage_metrics"]++
+	}
+	if dryRun || len(batch) == 0 {
+		return
+	}
+	tx, err := pg.Begin(ctx)
+	if err != nil {
+		log.Printf("usage_metrics tx: %v", err)
+		return
+	}
+	defer tx.Rollback(ctx)
+	b := &pgx.Batch{}
+	for _, row := range batch {
+		b.Queue(`
+			INSERT INTO company_settings (company_id, settings, updated_at)
+			VALUES ($1, $2::jsonb, now())
+			ON CONFLICT (company_id) DO UPDATE SET
+				settings = company_settings.settings || EXCLUDED.settings,
+				updated_at = now()`, row...)
+	}
+	br := tx.SendBatch(ctx, b)
+	if err := br.Close(); err != nil {
+		log.Printf("usage_metrics batch: %v", err)
+		return
+	}
+	if err := tx.Commit(ctx); err != nil {
+		log.Printf("usage_metrics commit: %v", err)
+	}
+
+	// usage_limits → settings._legacy_usage_limits when present
+	if mysqlTableExists(ctx, mysqlDB, "usage_limits") {
+		lq := `SELECT company_id, tokens_per_minute, requests_per_minute, tokens_per_day, cost_limit, COALESCE(is_active, 1)
+			FROM usage_limits WHERE company_id IS NOT NULL AND company_id <> ''`
+		lc, la := mysqlCompanyFilter("company_id", allow)
+		lrows, err := mysqlDB.QueryContext(ctx, lq+lc, la...)
+		if err == nil {
+			defer lrows.Close()
+			for lrows.Next() {
+				var companyLegacy string
+				var tpm, rpm, tpd int
+				var costLimit sql.NullInt64
+				var active int
+				if err := lrows.Scan(&companyLegacy, &tpm, &rpm, &tpd, &costLimit, &active); err != nil {
+					continue
+				}
+				cid, ok := companyMap[companyLegacy]
+				if !ok {
+					continue
+				}
+				lim := map[string]any{
+					"tokens_per_minute":   tpm,
+					"requests_per_minute": rpm,
+					"tokens_per_day":      tpd,
+					"is_active":           active == 1,
+				}
+				if costLimit.Valid {
+					lim["cost_limit"] = costLimit.Int64
+				}
+				payload, _ := json.Marshal(map[string]any{"_legacy_usage_limits": lim})
+				_, _ = pg.Exec(ctx, `
+					INSERT INTO company_settings (company_id, settings, updated_at)
+					VALUES ($1, $2::jsonb, now())
+					ON CONFLICT (company_id) DO UPDATE SET
+						settings = company_settings.settings || EXCLUDED.settings,
+						updated_at = now()`, cid, string(payload))
+				report["usage_limits"]++
+			}
+		}
+	}
+}
+
+func firstNonEmpty(vals ...string) string {
+	for _, v := range vals {
+		if strings.TrimSpace(v) != "" {
+			return strings.TrimSpace(v)
+		}
+	}
+	return ""
+}

apps/api/cmd/migrator/idmap.go

@@ -0,0 +1,173 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/google/uuid"
+)
+
+// IDMapDocument matches docs/schema-map.md (versioned unified ID map for cutover rehearsal).
+type IDMapDocument struct {
+	Version     int               `json:"version"`
+	GeneratedAt string            `json:"generated_at"`
+	Source      string            `json:"source"`
+	Target      string            `json:"target"`
+	Users       map[string]string `json:"users"`
+	Companies   map[string]string `json:"companies"`
+	Categories  map[string]string `json:"categories,omitempty"`
+	Attributes  map[string]string `json:"attributes,omitempty"`
+	Feeds       map[string]string `json:"feeds,omitempty"`
+	RawProducts map[string]string `json:"raw_products,omitempty"`
+	Files       map[string]string `json:"files,omitempty"`
+	Meta        IDMapMeta         `json:"meta"`
+}
+
+type IDMapMeta struct {
+	UserCount    int            `json:"user_count"`
+	CompanyCount int            `json:"company_count"`
+	DryRun       bool           `json:"dry_run"`
+	Report       map[string]int `json:"report,omitempty"`
+}
+
+func copyMap(dst *map[string]string, src map[string]string) {
+	if src == nil {
+		return
+	}
+	if *dst == nil {
+		*dst = map[string]string{}
+	}
+	for k, v := range src {
+		(*dst)[k] = v
+	}
+}
+
+// AttachEntityMaps merges optional catalog/feed entity remaps into the document.
+func (d *IDMapDocument) AttachEntityMaps(
+	categories, attributes, feeds, rawProducts, files map[string]string,
+	report map[string]int,
+) {
+	if d == nil {
+		return
+	}
+	copyMap(&d.Categories, categories)
+	copyMap(&d.Attributes, attributes)
+	copyMap(&d.Feeds, feeds)
+	copyMap(&d.RawProducts, rawProducts)
+	copyMap(&d.Files, files)
+	d.Meta.UserCount = len(d.Users)
+	d.Meta.CompanyCount = len(d.Companies)
+	if report != nil {
+		d.Meta.Report = report
+	}
+}
+
+func NewIDMapDocument(users, companies map[string]string, dryRun bool) IDMapDocument {
+	if users == nil {
+		users = map[string]string{}
+	}
+	if companies == nil {
+		companies = map[string]string{}
+	}
+	return IDMapDocument{
+		Version:     1,
+		GeneratedAt: time.Now().UTC().Format(time.RFC3339),
+		Source:      "mysql",
+		Target:      "postgres",
+		Users:       users,
+		Companies:   companies,
+		Meta: IDMapMeta{
+			UserCount:    len(users),
+			CompanyCount: len(companies),
+			DryRun:       dryRun,
+		},
+	}
+}
+
+func (d IDMapDocument) Validate() error {
+	if d.Version != 1 {
+		return fmt.Errorf("unsupported id map version %d", d.Version)
+	}
+	for legacy, id := range d.Users {
+		if legacy == "" {
+			return fmt.Errorf("empty user legacy id")
+		}
+		if _, err := uuid.Parse(id); err != nil {
+			return fmt.Errorf("user %q maps to invalid uuid %q", legacy, id)
+		}
+	}
+	for legacy, id := range d.Companies {
+		if legacy == "" {
+			return fmt.Errorf("empty company legacy id")
+		}
+		if _, err := uuid.Parse(id); err != nil {
+			return fmt.Errorf("company %q maps to invalid uuid %q", legacy, id)
+		}
+	}
+	return nil
+}
+
+func (d IDMapDocument) ResolveUser(legacy string) (uuid.UUID, bool) {
+	raw, ok := d.Users[legacy]
+	if !ok {
+		return uuid.Nil, false
+	}
+	id, err := uuid.Parse(raw)
+	if err != nil {
+		return uuid.Nil, false
+	}
+	return id, true
+}
+
+func (d IDMapDocument) ResolveCompany(legacy string) (uuid.UUID, bool) {
+	raw, ok := d.Companies[legacy]
+	if !ok {
+		return uuid.Nil, false
+	}
+	id, err := uuid.Parse(raw)
+	if err != nil {
+		return uuid.Nil, false
+	}
+	return id, true
+}
+
+func WriteIDMap(path string, d IDMapDocument) error {
+	if err := d.Validate(); err != nil {
+		return err
+	}
+	b, err := json.MarshalIndent(d, "", "  ")
+	if err != nil {
+		return err
+	}
+	return os.WriteFile(path, b, 0o644)
+}
+
+func ReadIDMap(path string) (IDMapDocument, error) {
+	b, err := os.ReadFile(path)
+	if err != nil {
+		return IDMapDocument{}, err
+	}
+	var d IDMapDocument
+	if err := json.Unmarshal(b, &d); err != nil {
+		return IDMapDocument{}, err
+	}
+	if err := d.Validate(); err != nil {
+		return IDMapDocument{}, err
+	}
+	return d, nil
+}
+
+func WriteIDMapDir(dir string, users, companies map[string]string, dryRun bool) (string, error) {
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		return "", err
+	}
+	path := filepath.Join(dir, "id-map.json")
+	doc := NewIDMapDocument(users, companies, dryRun)
+	if err := WriteIDMap(path, doc); err != nil {
+		return "", err
+	}
+	return path, nil
+}

apps/api/cmd/migrator/idmap_test.go

@@ -0,0 +1,104 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/google/uuid"
+)
+
+func TestIDMapRoundTripFixture(t *testing.T) {
+	t.Parallel()
+	dir := t.TempDir()
+	users := map[string]string{
+		"user_2abcClerkId": "550e8400-e29b-41d4-a716-446655440000",
+	}
+	companies := map[string]string{
+		"org_or_legacy_company_text_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
+	}
+	path, err := WriteIDMapDir(dir, users, companies, true)
+	if err != nil {
+		t.Fatalf("WriteIDMapDir: %v", err)
+	}
+	if filepath.Base(path) != "id-map.json" {
+		t.Fatalf("unexpected path %s", path)
+	}
+
+	doc, err := ReadIDMap(path)
+	if err != nil {
+		t.Fatalf("ReadIDMap: %v", err)
+	}
+	if doc.Version != 1 || !doc.Meta.DryRun {
+		t.Fatalf("meta %#v", doc.Meta)
+	}
+	if doc.Meta.UserCount != 1 || doc.Meta.CompanyCount != 1 {
+		t.Fatalf("counts user=%d company=%d", doc.Meta.UserCount, doc.Meta.CompanyCount)
+	}
+
+	uid, ok := doc.ResolveUser("user_2abcClerkId")
+	if !ok || uid.String() != "550e8400-e29b-41d4-a716-446655440000" {
+		t.Fatalf("ResolveUser = %v ok=%v", uid, ok)
+	}
+	cid, ok := doc.ResolveCompany("org_or_legacy_company_text_id")
+	if !ok || cid.String() != "6ba7b810-9dad-11d1-80b4-00c04fd430c8" {
+		t.Fatalf("ResolveCompany = %v ok=%v", cid, ok)
+	}
+	if _, ok := doc.ResolveUser("missing"); ok {
+		t.Fatal("expected missing user")
+	}
+}
+
+func TestIDMapValidateRejectsBadUUID(t *testing.T) {
+	t.Parallel()
+	doc := NewIDMapDocument(map[string]string{"u1": "not-a-uuid"}, nil, false)
+	if err := doc.Validate(); err == nil {
+		t.Fatal("expected validation error")
+	}
+}
+
+func TestIDMapValidateRejectsEmptyLegacy(t *testing.T) {
+	t.Parallel()
+	doc := NewIDMapDocument(map[string]string{"": uuid.New().String()}, nil, false)
+	if err := doc.Validate(); err == nil {
+		t.Fatal("expected empty legacy error")
+	}
+}
+
+func TestIDMapWriteRejectsInvalid(t *testing.T) {
+	t.Parallel()
+	path := filepath.Join(t.TempDir(), "bad.json")
+	err := WriteIDMap(path, IDMapDocument{Version: 2})
+	if err == nil {
+		t.Fatal("expected write validation error")
+	}
+	if _, err := os.Stat(path); !os.IsNotExist(err) {
+		t.Fatalf("file should not exist, stat err=%v", err)
+	}
+}
+
+func TestRemapOrphanDetectionFixture(t *testing.T) {
+	t.Parallel()
+	// Membership rows whose company/user legacy IDs are absent from the map are orphans.
+	companies := map[string]string{"co_a": uuid.New().String()}
+	users := map[string]string{"user_a": uuid.New().String()}
+	doc := NewIDMapDocument(users, companies, false)
+
+	type membership struct{ CompanyLegacy, UserLegacy string }
+	rows := []membership{
+		{"co_a", "user_a"},
+		{"co_missing", "user_a"},
+		{"co_a", "user_missing"},
+	}
+	orphans := 0
+	for _, m := range rows {
+		_, okC := doc.ResolveCompany(m.CompanyLegacy)
+		_, okU := doc.ResolveUser(m.UserLegacy)
+		if !okC || !okU {
+			orphans++
+		}
+	}
+	if orphans != 2 {
+		t.Fatalf("orphans = %d, want 2", orphans)
+	}
+}

apps/api/cmd/migrator/jobs.go

@@ -0,0 +1,496 @@
+package main
+
+import (
+	"context"
+	"database/sql"
+	"log"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// migrateJobsDomain imports legacy processing_jobs (+ best-effort job products) and tasks.
+// Job rows are tagged ai_provider_mode='migrated' so retention cleanup preserves history.
+func migrateJobsDomain(
+	ctx context.Context,
+	mysqlDB *sql.DB,
+	pg *pgxpool.Pool,
+	companyMap, userMap, rawMap map[string]string,
+	allow map[string]bool,
+	domains domainSet,
+	report map[string]int,
+	dryRun bool,
+) {
+	if !domains.has("jobs") {
+		return
+	}
+	migrateProcessingJobs(ctx, mysqlDB, pg, companyMap, userMap, allow, report, dryRun)
+	migrateProcessingJobProducts(ctx, mysqlDB, pg, rawMap, allow, report, dryRun)
+	migrateLegacyTasks(ctx, mysqlDB, pg, companyMap, userMap, allow, report, dryRun)
+}
+
+func migrateProcessingJobs(
+	ctx context.Context,
+	mysqlDB *sql.DB,
+	pg *pgxpool.Pool,
+	companyMap, userMap map[string]string,
+	allow map[string]bool,
+	report map[string]int,
+	dryRun bool,
+) {
+	if !mysqlTableExists(ctx, mysqlDB, "processing_jobs") {
+		log.Printf("processing_jobs skipped: table missing")
+		return
+	}
+	q := mysqlSelectList(
+		"id",
+		"company_id",
+		mysqlCol(ctx, mysqlDB, "processing_jobs", "user_id", "NULL"),
+		mysqlCoalesce(ctx, mysqlDB, "processing_jobs", "status", "'pending'"),
+		mysqlCoalesce(ctx, mysqlDB, "processing_jobs", "total_products", "0"),
+		mysqlCoalesce(ctx, mysqlDB, "processing_jobs", "processed_products", "0"),
+		mysqlCol(ctx, mysqlDB, "processing_jobs", "error", "NULL"),
+		mysqlCoalesce(ctx, mysqlDB, "processing_jobs", "processing_type", "'full'"),
+		mysqlCoalesce(ctx, mysqlDB, "processing_jobs", "priority", "0"),
+		mysqlCoalesce(ctx, mysqlDB, "processing_jobs", "estimated_tokens", "0"),
+		mysqlCol(ctx, mysqlDB, "processing_jobs", "started_at", "NULL"),
+		mysqlCol(ctx, mysqlDB, "processing_jobs", "completed_at", "NULL"),
+		mysqlCoalesce(ctx, mysqlDB, "processing_jobs", "created_at", "NOW()"),
+		mysqlCoalesce(ctx, mysqlDB, "processing_jobs", "updated_at", "NOW()"),
+	) + " FROM processing_jobs WHERE 1=1"
+	clause, cargs := mysqlCompanyFilter("company_id", allow)
+	q += clause
+	rows, err := mysqlDB.QueryContext(ctx, q, cargs...)
+	if err != nil {
+		log.Printf("processing_jobs skipped: %v", err)
+		return
+	}
+	defer rows.Close()
+
+	for rows.Next() {
+		var (
+			legacyID, companyLegacy string
+			userLegacy              sql.NullString
+			status, processingType  string
+			errText                 sql.NullString
+			totalProducts           any
+			processedProducts       any
+			priority                any
+			estimatedTokens         any
+			startedAt, completedAt  sql.NullTime
+			createdAt, updatedAt    time.Time
+		)
+		if err := rows.Scan(
+			&legacyID, &companyLegacy, &userLegacy, &status, &totalProducts, &processedProducts,
+			&errText, &processingType, &priority, &estimatedTokens,
+			&startedAt, &completedAt, &createdAt, &updatedAt,
+		); err != nil {
+			report["processing_jobs_skipped"]++
+			continue
+		}
+		cid, ok := companyMap[companyLegacy]
+		if !ok {
+			report["processing_jobs_skipped"]++
+			continue
+		}
+		jobID, err := uuid.Parse(strings.TrimSpace(legacyID))
+		if err != nil {
+			// Legacy dump mixes UUID and numeric string PKs — keep remaps stable.
+			jobID = uuid.NewSHA1(uuid.NameSpaceOID, []byte("processing_job:"+strings.TrimSpace(legacyID)))
+		}
+		var userID *uuid.UUID
+		if userLegacy.Valid && strings.TrimSpace(userLegacy.String) != "" {
+			if mapped, ok := userMap[userLegacy.String]; ok {
+				if parsed, err := uuid.Parse(mapped); err == nil {
+					if !dryRun {
+						var exists bool
+						_ = pg.QueryRow(ctx, `SELECT EXISTS(SELECT 1 FROM users WHERE id = $1)`, parsed).Scan(&exists)
+						if exists {
+							userID = &parsed
+						} else {
+							report["processing_jobs_user_missing"]++
+						}
+					} else {
+						userID = &parsed
+					}
+				}
+			} else {
+				report["processing_jobs_user_unmapped"]++
+			}
+		}
+		normStatus := normalizeProcessingJobStatus(status)
+		ptype := strings.TrimSpace(processingType)
+		if ptype == "" {
+			ptype = "full"
+		}
+		var errPtr *string
+		if errText.Valid && strings.TrimSpace(errText.String) != "" {
+			v := errText.String
+			errPtr = &v
+		}
+		var startedPtr, completedPtr *time.Time
+		if startedAt.Valid {
+			t := startedAt.Time.UTC()
+			startedPtr = &t
+		}
+		if completedAt.Valid {
+			t := completedAt.Time.UTC()
+			completedPtr = &t
+		}
+		if dryRun {
+			report["processing_jobs"]++
+			continue
+		}
+		_, err = pg.Exec(ctx, `
+			INSERT INTO processing_jobs (
+				id, company_id, user_id, status, total_products, processed_products,
+				error, processing_type, priority, estimated_tokens,
+				started_at, completed_at, created_at, updated_at,
+				current_step, step_progress, ai_provider_mode
+			) VALUES (
+				$1, $2, $3, $4, $5, $6,
+				$7, $8, $9, $10,
+				$11, $12, $13, $14,
+				'', '[]'::jsonb, 'migrated'
+			)
+			ON CONFLICT (id) DO UPDATE SET
+				company_id = EXCLUDED.company_id,
+				user_id = EXCLUDED.user_id,
+				status = EXCLUDED.status,
+				total_products = EXCLUDED.total_products,
+				processed_products = EXCLUDED.processed_products,
+				error = EXCLUDED.error,
+				processing_type = EXCLUDED.processing_type,
+				priority = EXCLUDED.priority,
+				estimated_tokens = EXCLUDED.estimated_tokens,
+				started_at = EXCLUDED.started_at,
+				completed_at = EXCLUDED.completed_at,
+				created_at = EXCLUDED.created_at,
+				updated_at = EXCLUDED.updated_at,
+				ai_provider_mode = 'migrated'`,
+			jobID, cid, userID, normStatus,
+			scanIntish(totalProducts), scanIntish(processedProducts),
+			errPtr, ptype, scanIntish(priority), scanIntish(estimatedTokens),
+			startedPtr, completedPtr, createdAt.UTC(), updatedAt.UTC(),
+		)
+		if err != nil {
+			log.Printf("processing_job %s: %v", legacyID, err)
+			report["processing_jobs_skipped"]++
+			continue
+		}
+		report["processing_jobs"]++
+	}
+	if err := rows.Err(); err != nil {
+		log.Printf("processing_jobs rows: %v", err)
+	}
+}
+
+func migrateProcessingJobProducts(
+	ctx context.Context,
+	mysqlDB *sql.DB,
+	pg *pgxpool.Pool,
+	rawMap map[string]string,
+	allow map[string]bool,
+	report map[string]int,
+	dryRun bool,
+) {
+	if !mysqlTableExists(ctx, mysqlDB, "processing_job_products") {
+		return
+	}
+	if !mysqlTableExists(ctx, mysqlDB, "processing_jobs") {
+		return
+	}
+	q := `
+		SELECT pjp.id, pjp.job_id, pjp.raw_product_id, pjp.status, pjp.error,
+			pjp.processed_product_id, pjp.created_at, pjp.updated_at
+		FROM processing_job_products pjp
+		JOIN processing_jobs pj ON pj.id = pjp.job_id
+		WHERE 1=1`
+	clause, cargs := mysqlCompanyFilter("pj.company_id", allow)
+	q += clause
+	rows, err := mysqlDB.QueryContext(ctx, q, cargs...)
+	if err != nil {
+		log.Printf("processing_job_products skipped: %v", err)
+		return
+	}
+	defer rows.Close()
+
+	for rows.Next() {
+		var (
+			legacyProdID                          int64
+			jobLegacy                             string
+			rawLegacy                             any
+			status                                string
+			errText                               sql.NullString
+			processedLegacy                       sql.NullInt64
+			createdAt, updatedAt                  time.Time
+		)
+		if err := rows.Scan(
+			&legacyProdID, &jobLegacy, &rawLegacy, &status, &errText,
+			&processedLegacy, &createdAt, &updatedAt,
+		); err != nil {
+			report["processing_job_products_skipped"]++
+			continue
+		}
+		jobID, err := uuid.Parse(strings.TrimSpace(jobLegacy))
+		if err != nil {
+			jobID = uuid.NewSHA1(uuid.NameSpaceOID, []byte("processing_job:"+strings.TrimSpace(jobLegacy)))
+		}
+		rawKey := strings.TrimSpace(stringifyAnyID(rawLegacy))
+		rawUUIDStr, ok := rawMap[rawKey]
+		if !ok {
+			report["processing_job_products_skipped"]++
+			continue
+		}
+		rawUUID, err := uuid.Parse(rawUUIDStr)
+		if err != nil {
+			report["processing_job_products_skipped"]++
+			continue
+		}
+		if dryRun {
+			report["processing_job_products"]++
+			continue
+		}
+		// Only attach when the remapped raw product still exists (GTIN dedupe may drop some).
+		var exists bool
+		if err := pg.QueryRow(ctx, `SELECT EXISTS(SELECT 1 FROM raw_products WHERE id = $1)`, rawUUID).Scan(&exists); err != nil || !exists {
+			report["processing_job_products_skipped"]++
+			continue
+		}
+		var jobExists bool
+		if err := pg.QueryRow(ctx, `SELECT EXISTS(SELECT 1 FROM processing_jobs WHERE id = $1)`, jobID).Scan(&jobExists); err != nil || !jobExists {
+			report["processing_job_products_skipped"]++
+			continue
+		}
+		var errPtr *string
+		if errText.Valid && strings.TrimSpace(errText.String) != "" {
+			v := errText.String
+			errPtr = &v
+		}
+		// Stable UUID from legacy int so resume is idempotent.
+		prodID := uuid.NewSHA1(uuid.NameSpaceOID, []byte("pjp:"+strconv.FormatInt(legacyProdID, 10)))
+		_, err = pg.Exec(ctx, `
+			INSERT INTO processing_job_products (
+				id, job_id, raw_product_id, status, error, processed_product_id, created_at, updated_at
+			) VALUES ($1, $2, $3, $4, $5, NULL, $6, $7)
+			ON CONFLICT (id) DO UPDATE SET
+				status = EXCLUDED.status,
+				error = EXCLUDED.error,
+				updated_at = EXCLUDED.updated_at`,
+			prodID, jobID, rawUUID, normalizeJobProductStatus(status), errPtr,
+			createdAt.UTC(), updatedAt.UTC(),
+		)
+		if err != nil {
+			report["processing_job_products_skipped"]++
+			continue
+		}
+		report["processing_job_products"]++
+	}
+	if err := rows.Err(); err != nil {
+		log.Printf("processing_job_products rows: %v", err)
+	}
+}
+
+func migrateLegacyTasks(
+	ctx context.Context,
+	mysqlDB *sql.DB,
+	pg *pgxpool.Pool,
+	companyMap, userMap map[string]string,
+	allow map[string]bool,
+	report map[string]int,
+	dryRun bool,
+) {
+	if !mysqlTableExists(ctx, mysqlDB, "tasks") {
+		return
+	}
+	q := mysqlSelectList(
+		"id",
+		mysqlCol(ctx, mysqlDB, "tasks", "company_id", "NULL"),
+		mysqlCol(ctx, mysqlDB, "tasks", "user_id", "NULL"),
+		mysqlCoalesce(ctx, mysqlDB, "tasks", "task_name", "''"),
+		mysqlCoalesce(ctx, mysqlDB, "tasks", "status", "'pending'"),
+		mysqlCol(ctx, mysqlDB, "tasks", "start_time", "NULL"),
+		mysqlCol(ctx, mysqlDB, "tasks", "end_time", "NULL"),
+		mysqlCol(ctx, mysqlDB, "tasks", "log", "NULL"),
+		mysqlCoalesce(ctx, mysqlDB, "tasks", "processing_products", "0"),
+		mysqlCoalesce(ctx, mysqlDB, "tasks", "processed_products", "0"),
+		mysqlCoalesce(ctx, mysqlDB, "tasks", "total_products", "0"),
+		mysqlCol(ctx, mysqlDB, "tasks", "error_products", "NULL"),
+		mysqlCol(ctx, mysqlDB, "tasks", "product_ids", "NULL"),
+		mysqlCoalesce(ctx, mysqlDB, "tasks", "created_at", "NOW()"),
+		mysqlCoalesce(ctx, mysqlDB, "tasks", "updated_at", "NOW()"),
+	) + " FROM tasks WHERE 1=1"
+	clause, cargs := mysqlCompanyFilter("company_id", allow)
+	q += clause
+	rows, err := mysqlDB.QueryContext(ctx, q, cargs...)
+	if err != nil {
+		log.Printf("tasks skipped: %v", err)
+		return
+	}
+	defer rows.Close()
+
+	for rows.Next() {
+		var (
+			legacyID                                      int64
+			companyLegacy, userLegacy                     sql.NullString
+			taskName, status                              string
+			startTime, endTime                            sql.NullTime
+			logText                                       sql.NullString
+			processingProducts, processedProducts, totalP any
+			errorProducts, productIDs                     sql.NullString
+			createdAt, updatedAt                          time.Time
+		)
+		if err := rows.Scan(
+			&legacyID, &companyLegacy, &userLegacy, &taskName, &status,
+			&startTime, &endTime, &logText,
+			&processingProducts, &processedProducts, &totalP,
+			&errorProducts, &productIDs, &createdAt, &updatedAt,
+		); err != nil {
+			report["tasks_skipped"]++
+			continue
+		}
+		if !companyLegacy.Valid || strings.TrimSpace(companyLegacy.String) == "" {
+			report["tasks_skipped"]++
+			continue
+		}
+		cid, ok := companyMap[companyLegacy.String]
+		if !ok {
+			report["tasks_skipped"]++
+			continue
+		}
+		var userID *uuid.UUID
+		if userLegacy.Valid && strings.TrimSpace(userLegacy.String) != "" {
+			if mapped, ok := userMap[userLegacy.String]; ok {
+				if parsed, err := uuid.Parse(mapped); err == nil {
+					if !dryRun {
+						var exists bool
+						_ = pg.QueryRow(ctx, `SELECT EXISTS(SELECT 1 FROM users WHERE id = $1)`, parsed).Scan(&exists)
+						if exists {
+							userID = &parsed
+						}
+					} else {
+						userID = &parsed
+					}
+				}
+			}
+		}
+		taskID := uuid.NewSHA1(uuid.NameSpaceOID, []byte("task:"+strconv.FormatInt(legacyID, 10)))
+		var startPtr, endPtr *time.Time
+		if startTime.Valid {
+			t := startTime.Time.UTC()
+			startPtr = &t
+		}
+		if endTime.Valid {
+			t := endTime.Time.UTC()
+			endPtr = &t
+		}
+		var logPtr *string
+		if logText.Valid {
+			v := logText.String
+			logPtr = &v
+		}
+		errJSON := nullJSON(errorProducts)
+		prodJSON := nullJSON(productIDs)
+		if dryRun {
+			report["tasks"]++
+			continue
+		}
+		_, err = pg.Exec(ctx, `
+			INSERT INTO tasks (
+				id, company_id, user_id, task_name, status, start_time, end_time, log,
+				processing_products, processed_products, total_products,
+				error_products, product_ids, created_at, updated_at
+			) VALUES (
+				$1, $2, $3, $4, $5, $6, $7, $8,
+				$9, $10, $11,
+				$12::jsonb, $13::jsonb, $14, $15
+			)
+			ON CONFLICT (id) DO UPDATE SET
+				status = EXCLUDED.status,
+				end_time = EXCLUDED.end_time,
+				log = EXCLUDED.log,
+				processed_products = EXCLUDED.processed_products,
+				updated_at = EXCLUDED.updated_at`,
+			taskID, cid, userID, taskName, strings.TrimSpace(status),
+			startPtr, endPtr, logPtr,
+			scanIntish(processingProducts), scanIntish(processedProducts), scanIntish(totalP),
+			errJSON, prodJSON, createdAt.UTC(), updatedAt.UTC(),
+		)
+		if err != nil {
+			log.Printf("task %d: %v", legacyID, err)
+			report["tasks_skipped"]++
+			continue
+		}
+		report["tasks"]++
+	}
+	if err := rows.Err(); err != nil {
+		log.Printf("tasks rows: %v", err)
+	}
+}
+
+func normalizeProcessingJobStatus(raw string) string {
+	switch strings.ToLower(strings.TrimSpace(raw)) {
+	case "completed", "success", "done":
+		return "completed"
+	case "failed", "error":
+		return "failed"
+	case "cancelled", "canceled", "skipped":
+		return "cancelled"
+	case "running", "processing":
+		return "running"
+	case "pending", "queued":
+		return "pending"
+	default:
+		return "failed"
+	}
+}
+
+func normalizeJobProductStatus(raw string) string {
+	switch strings.ToLower(strings.TrimSpace(raw)) {
+	case "processed", "completed", "success", "done":
+		return "processed"
+	case "failed", "error":
+		return "failed"
+	case "cancelled", "canceled", "skipped":
+		return "cancelled"
+	case "processing", "running":
+		return "processing"
+	case "pending", "queued":
+		return "pending"
+	default:
+		return "failed"
+	}
+}
+
+func stringifyAnyID(v any) string {
+	switch x := v.(type) {
+	case nil:
+		return ""
+	case int64:
+		return strconv.FormatInt(x, 10)
+	case int32:
+		return strconv.FormatInt(int64(x), 10)
+	case float64:
+		return strconv.FormatInt(int64(x), 10)
+	case []byte:
+		return strings.TrimSpace(string(x))
+	case string:
+		return strings.TrimSpace(x)
+	default:
+		n := scanIntish(v)
+		if n != 0 {
+			return strconv.Itoa(n)
+		}
+		return ""
+	}
+}
+
+func nullJSON(ns sql.NullString) any {
+	if !ns.Valid || strings.TrimSpace(ns.String) == "" {
+		return nil
+	}
+	return strings.TrimSpace(ns.String)
+}

apps/api/cmd/migrator/legacy_emails.go

@@ -0,0 +1,599 @@
+package main
+
+import (
+	"context"
+	"encoding/csv"
+	"encoding/json"
+	"fmt"
+	"log"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/descrybe/descrybe-v2/apps/api/internal/auth"
+	"github.com/descrybe/descrybe-v2/apps/api/internal/billing"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+const legacyEmailSuffix = "@legacy.local"
+
+// legacyEmailRow is one Postgres user still on a synthetic Clerk-missing address.
+type legacyEmailRow struct {
+	ID               string   `json:"id"`
+	Email            string   `json:"email"`
+	Name             string   `json:"name,omitempty"`
+	LegacyUserID     string   `json:"legacy_user_id,omitempty"`
+	Companies        []string `json:"companies,omitempty"`
+	A1Member         bool     `json:"a1_member"`
+	LegacyCompanyIDs []string `json:"legacy_company_ids,omitempty"`
+}
+
+type legacyEmailInventory struct {
+	Version     int              `json:"version"`
+	GeneratedAt string           `json:"generated_at"`
+	Count       int              `json:"count"`
+	A1Members   int              `json:"a1_members"`
+	Note        string           `json:"note"`
+	Users       []legacyEmailRow `json:"users"`
+	// Emails is a Clerk-id → email stub map for operators to fill (or overwrite from a Clerk export).
+	Emails map[string]string `json:"emails"`
+}
+
+type emailPatchSkip struct {
+	LegacyID string `json:"legacy_id,omitempty"`
+	UserID   string `json:"user_id,omitempty"`
+	Email    string `json:"email,omitempty"`
+	Reason   string `json:"reason"`
+}
+
+type emailPatchAction struct {
+	UserID    string `json:"user_id"`
+	LegacyID  string `json:"legacy_id"`
+	FromEmail string `json:"from_email"`
+	ToEmail   string `json:"to_email"`
+	A1Member  bool   `json:"a1_member"`
+	Name      string `json:"name,omitempty"`
+}
+
+type emailPatchPlan struct {
+	Apply []emailPatchAction `json:"apply"`
+	Skips []emailPatchSkip   `json:"skips"`
+}
+
+func runLegacyEmailTools(postgresURL, mapsDir, emailsFile, emailsOut string, listOnly, exportOnly, patch bool, dryRun, confirm bool) {
+	if postgresURL == "" {
+		log.Fatal("-postgres / DATABASE_URL is required for legacy-email tooling")
+	}
+	if !listOnly && !exportOnly && !patch {
+		log.Fatal("pass -list-legacy-emails and/or -export-legacy-emails and/or -patch-emails")
+	}
+	if patch && strings.TrimSpace(emailsFile) == "" {
+		log.Fatal("-emails-file is required with -patch-emails (Clerk export or emails map JSON/CSV)")
+	}
+	if err := guardLiveMutation(patch, dryRun, confirm, "-patch-emails"); err != nil {
+		log.Fatal(err)
+	}
+
+	ctx := context.Background()
+	pg, err := pgxpool.New(ctx, postgresURL)
+	if err != nil {
+		log.Fatalf("postgres: %v", err)
+	}
+	defer pg.Close()
+
+	rows, err := listSyntheticLegacyEmails(ctx, pg)
+	if err != nil {
+		log.Fatalf("list @legacy.local users: %v", err)
+	}
+	fmt.Printf("legacy_local_users: %d\n", len(rows))
+	a1 := 0
+	for _, r := range rows {
+		if r.A1Member {
+			a1++
+		}
+	}
+	fmt.Printf("a1_members_among_them: %d\n", a1)
+
+	if listOnly || (!exportOnly && !patch) {
+		for _, r := range rows {
+			a1Flag := ""
+			if r.A1Member {
+				a1Flag = "\ta1"
+			}
+			co := strings.Join(r.Companies, ",")
+			fmt.Printf("  %s\t%s\t%s\t%s%s\n", r.ID, r.LegacyUserID, r.Email, co, a1Flag)
+		}
+		fmt.Printf("listed=%d\n", len(rows))
+	}
+
+	if exportOnly {
+		outPath := strings.TrimSpace(emailsOut)
+		if outPath == "" {
+			if strings.TrimSpace(mapsDir) == "" {
+				mapsDir = "maps"
+			}
+			outPath = filepath.Join(mapsDir, "legacy-emails.json")
+		}
+		if err := writeLegacyEmailInventory(outPath, rows); err != nil {
+			log.Fatalf("export legacy emails: %v", err)
+		}
+		fmt.Printf("exported=%d path=%s\n", len(rows), outPath)
+	}
+
+	if !patch {
+		return
+	}
+
+	byLegacy, err := loadEmailPatchMap(emailsFile)
+	if err != nil {
+		log.Fatalf("load -emails-file: %v", err)
+	}
+	occupied, err := loadOccupiedEmails(ctx, pg)
+	if err != nil {
+		log.Fatalf("load occupied emails: %v", err)
+	}
+	plan := planEmailPatches(rows, byLegacy, occupied)
+	fmt.Printf("patch_candidates: %d  skips: %d  dry_run=%v\n", len(plan.Apply), len(plan.Skips), dryRun)
+	for _, s := range plan.Skips {
+		fmt.Printf("skip\t%s\t%s\t%s\t%s\n", s.UserID, s.LegacyID, s.Email, s.Reason)
+	}
+	applied := 0
+	for _, a := range plan.Apply {
+		if a.A1Member {
+			fmt.Printf("skip\t%s\t%s\t%s\ta1_member\n", a.UserID, a.LegacyID, a.FromEmail)
+			continue
+		}
+		if dryRun {
+			fmt.Printf("dry-run: would patch %s (%s) %s -> %s\n", a.UserID, a.LegacyID, a.FromEmail, a.ToEmail)
+			applied++
+			continue
+		}
+		ok, err := applyEmailPatch(ctx, pg, a)
+		if err != nil {
+			log.Printf("patch %s: %v", a.UserID, err)
+			continue
+		}
+		if !ok {
+			fmt.Printf("skip\t%s\t%s\t%s\tcurrent_email_no_longer_synthetic\n", a.UserID, a.LegacyID, a.FromEmail)
+			continue
+		}
+		fmt.Printf("patched\t%s\t%s\t%s -> %s\n", a.UserID, a.LegacyID, a.FromEmail, a.ToEmail)
+		applied++
+	}
+	fmt.Printf("applied=%d skipped=%d dry_run=%v\n", applied, len(plan.Skips), dryRun)
+}
+
+func listSyntheticLegacyEmails(ctx context.Context, pg *pgxpool.Pool) ([]legacyEmailRow, error) {
+	q := `
+		SELECT u.id::text,
+		       u.email,
+		       COALESCE(u.name, ''),
+		       COALESCE(u.legacy_user_id, ''),
+		       COALESCE(string_agg(DISTINCT c.name, ', ' ORDER BY c.name), ''),
+		       COALESCE(string_agg(DISTINCT COALESCE(c.legacy_company_id, ''), ','), '')
+		FROM users u
+		LEFT JOIN memberships m ON m.user_id = u.id AND m.status = 'active'
+		LEFT JOIN companies c ON c.id = m.company_id
+		WHERE lower(u.email) LIKE '%@legacy.local'
+		GROUP BY u.id
+		ORDER BY u.email`
+	rows, err := pg.Query(ctx, q)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var out []legacyEmailRow
+	for rows.Next() {
+		var r legacyEmailRow
+		var companiesCSV, legacyIDsCSV string
+		if err := rows.Scan(&r.ID, &r.Email, &r.Name, &r.LegacyUserID, &companiesCSV, &legacyIDsCSV); err != nil {
+			return nil, err
+		}
+		r.Companies = splitCSVNonEmpty(companiesCSV)
+		r.LegacyCompanyIDs = splitCSVNonEmpty(legacyIDsCSV)
+		r.A1Member = rowIsA1Member(r)
+		if r.LegacyUserID == "" {
+			r.LegacyUserID = legacyIDFromSyntheticEmail(r.Email)
+		}
+		out = append(out, r)
+	}
+	return out, rows.Err()
+}
+
+func rowIsA1Member(r legacyEmailRow) bool {
+	for _, id := range r.LegacyCompanyIDs {
+		if billing.IsA1CohortCompany(id, "") {
+			return true
+		}
+	}
+	for _, name := range r.Companies {
+		if strings.EqualFold(strings.TrimSpace(name), "A1 Slovenija") ||
+			strings.EqualFold(strings.TrimSpace(name), "A1") {
+			return true
+		}
+	}
+	return false
+}
+
+func splitCSVNonEmpty(s string) []string {
+	s = strings.TrimSpace(s)
+	if s == "" {
+		return nil
+	}
+	parts := strings.Split(s, ",")
+	out := make([]string, 0, len(parts))
+	for _, p := range parts {
+		p = strings.TrimSpace(p)
+		if p != "" {
+			out = append(out, p)
+		}
+	}
+	return out
+}
+
+func writeLegacyEmailInventory(path string, rows []legacyEmailRow) error {
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		return err
+	}
+	a1 := 0
+	emails := map[string]string{}
+	for _, r := range rows {
+		if r.A1Member {
+			a1++
+		}
+		key := strings.TrimSpace(r.LegacyUserID)
+		if key == "" {
+			key = legacyIDFromSyntheticEmail(r.Email)
+		}
+		if key != "" {
+			emails[key] = ""
+		}
+	}
+	inv := legacyEmailInventory{
+		Version:     1,
+		GeneratedAt: time.Now().UTC().Format(time.RFC3339),
+		Count:       len(rows),
+		A1Members:   a1,
+		Note:        "Fill emails{} from a Clerk user export (id → primary email), then: go run ./cmd/migrator -patch-emails -emails-file <path> -postgres $DATABASE_URL -dry-run (live apply needs -confirm). Never commit secrets. Patch only updates rows that still end with @legacy.local — A1 members and real live emails are never overwritten.",
+		Users:       rows,
+		Emails:      emails,
+	}
+	raw, err := json.MarshalIndent(inv, "", "  ")
+	if err != nil {
+		return err
+	}
+	return os.WriteFile(path, append(raw, '\n'), 0o600)
+}
+
+func loadOccupiedEmails(ctx context.Context, pg *pgxpool.Pool) (map[string]string, error) {
+	rows, err := pg.Query(ctx, `SELECT id::text, lower(email) FROM users WHERE email IS NOT NULL AND trim(email) <> ''`)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	out := map[string]string{}
+	for rows.Next() {
+		var id, email string
+		if err := rows.Scan(&id, &email); err != nil {
+			return nil, err
+		}
+		out[strings.ToLower(strings.TrimSpace(email))] = id
+	}
+	return out, rows.Err()
+}
+
+func loadEmailPatchMap(path string) (map[string]string, error) {
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return nil, err
+	}
+	ext := strings.ToLower(filepath.Ext(path))
+	if ext == ".csv" {
+		return parseEmailPatchCSV(raw)
+	}
+	return parseEmailPatchJSON(raw)
+}
+
+func parseEmailPatchJSON(raw []byte) (map[string]string, error) {
+	trimmed := strings.TrimSpace(string(raw))
+	if trimmed == "" {
+		return nil, fmt.Errorf("empty emails file")
+	}
+
+	// Object map: {"user_xxx":"a@b.com"} or inventory {"emails":{...},"users":[...]}
+	var obj map[string]json.RawMessage
+	if err := json.Unmarshal(raw, &obj); err == nil {
+		if emailsRaw, ok := obj["emails"]; ok {
+			var emails map[string]string
+			if err := json.Unmarshal(emailsRaw, &emails); err != nil {
+				return nil, fmt.Errorf("emails object: %w", err)
+			}
+			return normalizeEmailPatchMap(emails), nil
+		}
+		if usersRaw, ok := obj["users"]; ok {
+			m, err := parseEmailPatchArray(usersRaw)
+			if err == nil && len(m) > 0 {
+				return m, nil
+			}
+		}
+		// Flat string map (all values JSON strings).
+		var flat map[string]string
+		if err := json.Unmarshal(raw, &flat); err == nil {
+			// Reject inventory-shaped objects that decoded poorly (version etc.).
+			if _, hasVersion := flat["version"]; !hasVersion && len(flat) > 0 {
+				return normalizeEmailPatchMap(flat), nil
+			}
+		}
+	}
+
+	var arr []json.RawMessage
+	if err := json.Unmarshal(raw, &arr); err == nil {
+		return parseEmailPatchArray(raw)
+	}
+	return nil, fmt.Errorf("unsupported emails JSON (want map, {emails:{}}, {users:[]}, or array)")
+}
+
+func parseEmailPatchArray(raw []byte) (map[string]string, error) {
+	var rows []map[string]any
+	if err := json.Unmarshal(raw, &rows); err != nil {
+		return nil, err
+	}
+	out := map[string]string{}
+	for _, row := range rows {
+		id := firstString(row, "id", "legacy_user_id", "user_id", "clerk_id")
+		email := firstString(row, "email", "primary_email_address", "primary_email", "real_email")
+		if email == "" {
+			if addrs, ok := row["email_addresses"].([]any); ok {
+				email = primaryFromClerkEmailAddresses(addrs)
+			}
+		}
+		id = strings.TrimSpace(id)
+		email = strings.ToLower(strings.TrimSpace(email))
+		if id == "" || email == "" {
+			continue
+		}
+		out[id] = email
+	}
+	return normalizeEmailPatchMap(out), nil
+}
+
+func primaryFromClerkEmailAddresses(addrs []any) string {
+	for _, a := range addrs {
+		m, ok := a.(map[string]any)
+		if !ok {
+			continue
+		}
+		email := firstString(m, "email_address", "email")
+		if email == "" {
+			continue
+		}
+		if primary, _ := m["primary"].(bool); primary {
+			return email
+		}
+	}
+	for _, a := range addrs {
+		m, ok := a.(map[string]any)
+		if !ok {
+			continue
+		}
+		if email := firstString(m, "email_address", "email"); email != "" {
+			return email
+		}
+	}
+	return ""
+}
+
+func firstString(m map[string]any, keys ...string) string {
+	for _, k := range keys {
+		if v, ok := m[k]; ok {
+			switch t := v.(type) {
+			case string:
+				if strings.TrimSpace(t) != "" {
+					return t
+				}
+			}
+		}
+	}
+	return ""
+}
+
+func parseEmailPatchCSV(raw []byte) (map[string]string, error) {
+	r := csv.NewReader(strings.NewReader(string(raw)))
+	r.TrimLeadingSpace = true
+	records, err := r.ReadAll()
+	if err != nil {
+		return nil, err
+	}
+	if len(records) == 0 {
+		return nil, fmt.Errorf("empty CSV")
+	}
+	header := records[0]
+	idIdx, emailIdx := -1, -1
+	for i, h := range header {
+		switch strings.ToLower(strings.TrimSpace(h)) {
+		case "id", "legacy_user_id", "user_id", "clerk_id":
+			if idIdx < 0 {
+				idIdx = i
+			}
+		case "email", "primary_email_address", "primary_email", "real_email":
+			if emailIdx < 0 {
+				emailIdx = i
+			}
+		}
+	}
+	if idIdx < 0 || emailIdx < 0 {
+		return nil, fmt.Errorf("CSV needs id/legacy_user_id and email/primary_email_address columns")
+	}
+	out := map[string]string{}
+	for _, rec := range records[1:] {
+		if idIdx >= len(rec) || emailIdx >= len(rec) {
+			continue
+		}
+		id := strings.TrimSpace(rec[idIdx])
+		email := strings.ToLower(strings.TrimSpace(rec[emailIdx]))
+		if id == "" || email == "" {
+			continue
+		}
+		out[id] = email
+	}
+	return normalizeEmailPatchMap(out), nil
+}
+
+func normalizeEmailPatchMap(in map[string]string) map[string]string {
+	out := map[string]string{}
+	for k, v := range in {
+		k = strings.TrimSpace(k)
+		v = strings.ToLower(strings.TrimSpace(v))
+		if k == "" || v == "" {
+			continue
+		}
+		out[k] = v
+	}
+	return out
+}
+
+func legacyIDFromSyntheticEmail(email string) string {
+	email = strings.ToLower(strings.TrimSpace(email))
+	if !strings.HasSuffix(email, legacyEmailSuffix) {
+		return ""
+	}
+	return strings.TrimSuffix(email, legacyEmailSuffix)
+}
+
+// planEmailPatches builds apply/skip lists. Safety: only synthetic current emails;
+// never overwrite a real (non-@legacy.local) address; never mutate A1 members
+// (even with -confirm / dry-run apply lists).
+func planEmailPatches(rows []legacyEmailRow, byLegacy map[string]string, occupied map[string]string) emailPatchPlan {
+	plan := emailPatchPlan{}
+	if len(byLegacy) == 0 {
+		plan.Skips = append(plan.Skips, emailPatchSkip{Reason: "empty_patch_map"})
+		return plan
+	}
+
+	matchedLegacy := map[string]bool{}
+	for _, row := range rows {
+		if row.A1Member {
+			legacyID := strings.TrimSpace(row.LegacyUserID)
+			if legacyID == "" {
+				legacyID = legacyIDFromSyntheticEmail(row.Email)
+			}
+			if legacyID != "" {
+				matchedLegacy[legacyID] = true
+			}
+			plan.Skips = append(plan.Skips, emailPatchSkip{
+				UserID:   row.ID,
+				LegacyID: legacyID,
+				Email:    row.Email,
+				Reason:   "a1_member",
+			})
+			continue
+		}
+		if !auth.IsSyntheticLegacyEmail(row.Email) {
+			plan.Skips = append(plan.Skips, emailPatchSkip{
+				UserID:   row.ID,
+				LegacyID: row.LegacyUserID,
+				Email:    row.Email,
+				Reason:   "current_email_not_synthetic",
+			})
+			continue
+		}
+		legacyID := strings.TrimSpace(row.LegacyUserID)
+		if legacyID == "" {
+			legacyID = legacyIDFromSyntheticEmail(row.Email)
+		}
+		to, ok := byLegacy[legacyID]
+		if !ok {
+			plan.Skips = append(plan.Skips, emailPatchSkip{
+				UserID:   row.ID,
+				LegacyID: legacyID,
+				Email:    row.Email,
+				Reason:   "no_mapping_in_emails_file",
+			})
+			continue
+		}
+		matchedLegacy[legacyID] = true
+		to = strings.ToLower(strings.TrimSpace(to))
+		if to == "" || strings.EqualFold(to, "replace_me@example.com") {
+			plan.Skips = append(plan.Skips, emailPatchSkip{
+				UserID:   row.ID,
+				LegacyID: legacyID,
+				Email:    row.Email,
+				Reason:   "empty_or_placeholder_target",
+			})
+			continue
+		}
+		if auth.IsSyntheticLegacyEmail(to) {
+			plan.Skips = append(plan.Skips, emailPatchSkip{
+				UserID:   row.ID,
+				LegacyID: legacyID,
+				Email:    row.Email,
+				Reason:   "target_still_synthetic",
+			})
+			continue
+		}
+		if !strings.Contains(to, "@") {
+			plan.Skips = append(plan.Skips, emailPatchSkip{
+				UserID:   row.ID,
+				LegacyID: legacyID,
+				Email:    row.Email,
+				Reason:   "target_invalid_email",
+			})
+			continue
+		}
+		if strings.EqualFold(to, row.Email) {
+			plan.Skips = append(plan.Skips, emailPatchSkip{
+				UserID:   row.ID,
+				LegacyID: legacyID,
+				Email:    row.Email,
+				Reason:   "unchanged",
+			})
+			continue
+		}
+		if owner, taken := occupied[to]; taken && owner != row.ID {
+			plan.Skips = append(plan.Skips, emailPatchSkip{
+				UserID:   row.ID,
+				LegacyID: legacyID,
+				Email:    row.Email,
+				Reason:   "target_email_owned_by_" + owner,
+			})
+			continue
+		}
+		plan.Apply = append(plan.Apply, emailPatchAction{
+			UserID:    row.ID,
+			LegacyID:  legacyID,
+			FromEmail: row.Email,
+			ToEmail:   to,
+			A1Member:  row.A1Member,
+			Name:      row.Name,
+		})
+	}
+
+	for legacyID, email := range byLegacy {
+		if matchedLegacy[legacyID] {
+			continue
+		}
+		plan.Skips = append(plan.Skips, emailPatchSkip{
+			LegacyID: legacyID,
+			Email:    email,
+			Reason:   "no_synthetic_user_for_legacy_id",
+		})
+	}
+	return plan
+}
+
+func applyEmailPatch(ctx context.Context, pg *pgxpool.Pool, a emailPatchAction) (bool, error) {
+	// Defense in depth: SQL only updates rows that are still @legacy.local.
+	tag, err := pg.Exec(ctx, `
+		UPDATE users
+		SET email = $2, updated_at = now()
+		WHERE id = $1::uuid
+		  AND lower(email) LIKE '%@legacy.local'
+		  AND lower(email) = lower($3)`,
+		a.UserID, a.ToEmail, a.FromEmail)
+	if err != nil {
+		return false, err
+	}
+	return tag.RowsAffected() > 0, nil
+}

apps/api/cmd/migrator/legacy_emails_test.go

@@ -0,0 +1,152 @@
+package main
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/descrybe/descrybe-v2/apps/api/internal/billing"
+)
+
+func TestLegacyIDFromSyntheticEmail(t *testing.T) {
+	t.Parallel()
+	if got := legacyIDFromSyntheticEmail("user_abc@legacy.local"); got != "user_abc" {
+		t.Fatalf("got %q", got)
+	}
+	if got := legacyIDFromSyntheticEmail("  User_ABC@Legacy.Local "); got != "user_abc" {
+		t.Fatalf("got %q", got)
+	}
+	if got := legacyIDFromSyntheticEmail("real@example.com"); got != "" {
+		t.Fatalf("want empty, got %q", got)
+	}
+}
+
+func TestParseEmailPatchJSONMap(t *testing.T) {
+	t.Parallel()
+	m, err := parseEmailPatchJSON([]byte(`{"user_1":"A@Example.COM","user_2":""}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if m["user_1"] != "a@example.com" {
+		t.Fatalf("got %#v", m)
+	}
+	if _, ok := m["user_2"]; ok {
+		t.Fatal("empty emails must be dropped")
+	}
+}
+
+func TestParseEmailPatchJSONInventoryEmails(t *testing.T) {
+	t.Parallel()
+	raw := []byte(`{
+	  "version": 1,
+	  "emails": {"user_x":"x@example.com"},
+	  "users": [{"legacy_user_id":"user_x","email":"user_x@legacy.local"}]
+	}`)
+	m, err := parseEmailPatchJSON(raw)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if m["user_x"] != "x@example.com" {
+		t.Fatalf("got %#v", m)
+	}
+}
+
+func TestParseEmailPatchJSONArrayClerkish(t *testing.T) {
+	t.Parallel()
+	raw := []byte(`[
+	  {"id":"user_a","primary_email_address":"a@ex.com"},
+	  {"id":"user_b","email_addresses":[{"email_address":"b@ex.com","primary":true}]}
+	]`)
+	m, err := parseEmailPatchJSON(raw)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if m["user_a"] != "a@ex.com" || m["user_b"] != "b@ex.com" {
+		t.Fatalf("got %#v", m)
+	}
+}
+
+func TestParseEmailPatchCSV(t *testing.T) {
+	t.Parallel()
+	m, err := parseEmailPatchCSV([]byte("id,primary_email_address\nuser_c,C@Ex.COM\n"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if m["user_c"] != "c@ex.com" {
+		t.Fatalf("got %#v", m)
+	}
+}
+
+func TestPlanEmailPatchesSafety(t *testing.T) {
+	t.Parallel()
+	rows := []legacyEmailRow{
+		{ID: "u1", Email: "user_1@legacy.local", LegacyUserID: "user_1", A1Member: true},
+		{ID: "u2", Email: "a1-primary@descrybe.local", LegacyUserID: "user_live", A1Member: true},
+		{ID: "u3", Email: "user_3@legacy.local", LegacyUserID: "user_3"},
+		{ID: "u4", Email: "user_4@legacy.local", LegacyUserID: "user_4"},
+		{ID: "u5", Email: "user_5@legacy.local", LegacyUserID: "user_5"},
+	}
+	byLegacy := map[string]string{
+		"user_1":       "real1@example.com",
+		"user_live":    "should-not-apply@example.com",
+		"user_3":       "user_3@legacy.local",
+		"user_4":       "taken@example.com",
+		"user_5":       "real5@example.com",
+		"user_missing": "ghost@example.com",
+	}
+	occupied := map[string]string{
+		"user_1@legacy.local":       "u1",
+		"a1-primary@descrybe.local": "u2",
+		"user_3@legacy.local":       "u3",
+		"user_4@legacy.local":       "u4",
+		"user_5@legacy.local":       "u5",
+		"taken@example.com":         "other",
+	}
+	plan := planEmailPatches(rows, byLegacy, occupied)
+	if len(plan.Apply) != 1 || plan.Apply[0].UserID != "u5" || plan.Apply[0].ToEmail != "real5@example.com" {
+		t.Fatalf("apply=%#v", plan.Apply)
+	}
+	if plan.Apply[0].A1Member {
+		t.Fatal("apply list must never include a1_member=true")
+	}
+	reasons := map[string]bool{}
+	for _, s := range plan.Skips {
+		reasons[s.Reason] = true
+		if s.UserID == "u1" && s.Reason != "a1_member" {
+			t.Fatalf("A1 synthetic email must skip as a1_member, skip=%#v", s)
+		}
+		if s.UserID == "u2" && s.Reason != "a1_member" {
+			t.Fatalf("live A1 email must skip as a1_member, skip=%#v", s)
+		}
+	}
+	for _, want := range []string{
+		"a1_member",
+		"target_still_synthetic",
+		"target_email_owned_by_other",
+		"no_synthetic_user_for_legacy_id",
+	} {
+		if !reasons[want] {
+			t.Fatalf("missing skip reason %q in %#v", want, plan.Skips)
+		}
+	}
+}
+
+func TestPlanEmailPatchesEmptyMap(t *testing.T) {
+	t.Parallel()
+	plan := planEmailPatches(nil, nil, nil)
+	if len(plan.Skips) != 1 || !strings.Contains(plan.Skips[0].Reason, "empty") {
+		t.Fatalf("got %#v", plan.Skips)
+	}
+}
+
+func TestRowIsA1Member(t *testing.T) {
+	t.Parallel()
+	if !rowIsA1Member(legacyEmailRow{LegacyCompanyIDs: []string{billing.A1LegacyCompanyID}}) {
+		t.Fatal("expected A1 by legacy company id")
+	}
+	if !rowIsA1Member(legacyEmailRow{Companies: []string{"A1 Slovenija"}}) {
+		t.Fatal("expected A1 by name")
+	}
+	if rowIsA1Member(legacyEmailRow{Companies: []string{"Acme"}}) {
+		t.Fatal("Acme is not A1")
+	}
+}

apps/api/cmd/migrator/membership_role_repair.go

@@ -0,0 +1,239 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"strings"
+
+	"github.com/descrybe/descrybe-v2/apps/api/internal/billing"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// memberMembershipRow is one active membership with role=member (cutover promote candidate).
+type memberMembershipRow struct {
+	UserID          string
+	Email           string
+	CompanyID       string
+	CompanyName     string
+	LegacyCompanyID string
+	Role            string
+	Status          string
+	IsPlatformAdmin bool
+	MustSetPassword bool
+}
+
+// runMembershipRoleRepair lists and/or promotes active memberships from role=member
+// to company admin (role=admin). Postgres-only post-load operator tooling.
+// Live writes require confirm=true (no blind promotes). Prefer -dry-run first.
+// Unscoped promote (no email/user-id/company-id) is refused.
+// NEVER promotes A1 cohort memberships (a1=true) — dry-run and live both skip them.
+func runMembershipRoleRepair(
+	postgresURL, email, userID, companyID string,
+	listOnly, promote bool,
+	dryRun, confirm bool,
+) {
+	if postgresURL == "" {
+		log.Fatal("-postgres / DATABASE_URL is required for membership role tooling")
+	}
+	if !listOnly && !promote {
+		log.Fatal("pass -list-member-memberships and/or -promote-company-admins")
+	}
+	if err := validatePromoteTargets(promote, email, userID, companyID); err != nil {
+		log.Fatal(err)
+	}
+	if err := guardLiveMutation(promote, dryRun, confirm, "-promote-company-admins"); err != nil {
+		log.Fatal(err)
+	}
+
+	ctx := context.Background()
+	pg, err := pgxpool.New(ctx, postgresURL)
+	if err != nil {
+		log.Fatalf("postgres: %v", err)
+	}
+	defer pg.Close()
+
+	rows, err := listMemberMemberships(ctx, pg, email, userID, companyID)
+	if err != nil {
+		log.Fatalf("list member memberships: %v", err)
+	}
+	fmt.Printf("active_member_memberships: %d\n", len(rows))
+
+	listed := 0
+	promoted := 0
+	skipped := 0
+	a1Candidates := 0
+	a1Skipped := 0
+
+	for _, m := range rows {
+		listed++
+		a1 := billing.IsA1CohortCompany(m.LegacyCompanyID, m.CompanyName)
+		if a1 {
+			a1Candidates++
+		}
+		if listOnly || !promote {
+			fmt.Printf("  %s\t%s\t%s\t%s\ta1=%v\tplatform_admin=%v\tmust_set_password=%v\n",
+				m.UserID, m.Email, m.CompanyID, m.CompanyName, a1, m.IsPlatformAdmin, m.MustSetPassword)
+		}
+		mutate, skipReason := decideMembershipPromote(promote, a1)
+		if !mutate {
+			if promote && skipReason != "" {
+				fmt.Printf("skip\t%s\t%s\t%s\t%s\t%s\n",
+					m.UserID, m.Email, m.CompanyID, m.CompanyName, skipReason)
+				skipped++
+				if skipReason == "a1_cohort" {
+					a1Skipped++
+				}
+			}
+			continue
+		}
+		if dryRun {
+			fmt.Printf("dry-run: would promote user %s (%s) on company %s (%s) member→admin a1=false\n",
+				m.UserID, m.Email, m.CompanyID, m.CompanyName)
+			promoted++
+			continue
+		}
+		ok, err := promoteMembershipToAdmin(ctx, pg, m.CompanyID, m.UserID)
+		if err != nil {
+			log.Printf("promote user %s company %s: %v", m.UserID, m.CompanyID, err)
+			skipped++
+			continue
+		}
+		if !ok {
+			skipped++
+			continue
+		}
+		fmt.Printf("promoted user %s (%s) on company %s (%s) member→admin a1=false\n",
+			m.UserID, m.Email, m.CompanyID, m.CompanyName)
+		promoted++
+	}
+
+	if promote {
+		fmt.Printf("listed=%d promoted=%d skipped=%d a1_candidates=%d a1_skipped=%d dry_run=%v\n",
+			listed, promoted, skipped, a1Candidates, a1Skipped, dryRun)
+	} else {
+		fmt.Printf("listed=%d a1_candidates=%d\n", listed, a1Candidates)
+	}
+}
+
+// decideMembershipPromote is the promote gate used by dry-run and -confirm.
+// A1 cohort rows always skip (never member→admin), even when confirm=true.
+func decideMembershipPromote(promote, a1 bool) (mutate bool, skipReason string) {
+	if !promote {
+		return false, ""
+	}
+	if a1 {
+		return false, "a1_cohort"
+	}
+	return true, ""
+}
+
+// validatePromoteTargets refuses unscoped live/dry promote of every member membership.
+// At least one of -email, -user-id, or -company-id is required. A1 rows are always skipped at promote time.
+func validatePromoteTargets(promote bool, email, userID, companyID string) error {
+	if !promote {
+		return nil
+	}
+	if strings.TrimSpace(email) == "" && strings.TrimSpace(userID) == "" && strings.TrimSpace(companyID) == "" {
+		return fmt.Errorf("-promote-company-admins requires -email, -user-id, or -company-id (refusing unscoped promote; A1 rows are always skipped)")
+	}
+	return nil
+}
+
+// guardLiveMutation refuses mutating ops unless -confirm is set.
+// -dry-run always previews without writes (confirm is ignored).
+func guardLiveMutation(mutate, dryRun, confirm bool, flagHint string) error {
+	if !mutate || dryRun {
+		return nil
+	}
+	if !confirm {
+		if strings.TrimSpace(flagHint) == "" {
+			flagHint = "the mutating flag"
+		}
+		return fmt.Errorf("refusing live write: pass -dry-run to preview, or -confirm with %s (no blind live writes)", flagHint)
+	}
+	return nil
+}
+
+func listMemberMemberships(
+	ctx context.Context,
+	pg *pgxpool.Pool,
+	email, userID, companyID string,
+) ([]memberMembershipRow, error) {
+	q := `
+		SELECT u.id::text,
+		       u.email,
+		       c.id::text,
+		       c.name,
+		       COALESCE(c.legacy_company_id, ''),
+		       m.role,
+		       m.status,
+		       u.is_platform_admin,
+		       u.must_set_password
+		FROM memberships m
+		JOIN users u ON u.id = m.user_id
+		JOIN companies c ON c.id = m.company_id
+		WHERE m.status = 'active'
+		  AND m.role = 'member'`
+	args := make([]any, 0, 3)
+	argN := 1
+	if e := strings.TrimSpace(email); e != "" {
+		q += fmt.Sprintf(" AND lower(u.email) = lower($%d)", argN)
+		args = append(args, e)
+		argN++
+	}
+	if uid := strings.TrimSpace(userID); uid != "" {
+		q += fmt.Sprintf(" AND m.user_id = $%d::uuid", argN)
+		args = append(args, uid)
+		argN++
+	}
+	if cid := strings.TrimSpace(companyID); cid != "" {
+		q += fmt.Sprintf(" AND m.company_id = $%d::uuid", argN)
+		args = append(args, cid)
+		argN++
+	}
+	q += `
+		ORDER BY c.name, u.email`
+
+	rows, err := pg.Query(ctx, q, args...)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var out []memberMembershipRow
+	for rows.Next() {
+		var m memberMembershipRow
+		if err := rows.Scan(
+			&m.UserID,
+			&m.Email,
+			&m.CompanyID,
+			&m.CompanyName,
+			&m.LegacyCompanyID,
+			&m.Role,
+			&m.Status,
+			&m.IsPlatformAdmin,
+			&m.MustSetPassword,
+		); err != nil {
+			return nil, err
+		}
+		out = append(out, m)
+	}
+	return out, rows.Err()
+}
+
+// promoteMembershipToAdmin sets an active member membership to admin.
+// Returns ok=false when no matching row was updated (already admin, inactive, or missing).
+func promoteMembershipToAdmin(ctx context.Context, pg *pgxpool.Pool, companyID, userID string) (bool, error) {
+	tag, err := pg.Exec(ctx, `
+		UPDATE memberships
+		SET role = 'admin', updated_at = now()
+		WHERE company_id = $1::uuid
+		  AND user_id = $2::uuid
+		  AND status = 'active'
+		  AND role = 'member'`, companyID, userID)
+	if err != nil {
+		return false, err
+	}
+	return tag.RowsAffected() > 0, nil
+}

apps/api/cmd/migrator/membership_role_repair_test.go

@@ -0,0 +1,74 @@
+package main
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestDecideMembershipPromoteSkipsA1(t *testing.T) {
+	t.Parallel()
+	mutate, reason := decideMembershipPromote(true, true)
+	if mutate || reason != "a1_cohort" {
+		t.Fatalf("a1=true must never promote (even with -confirm): mutate=%v reason=%q", mutate, reason)
+	}
+	mutate, reason = decideMembershipPromote(true, false)
+	if !mutate || reason != "" {
+		t.Fatalf("non-A1 should promote: mutate=%v reason=%q", mutate, reason)
+	}
+	mutate, reason = decideMembershipPromote(false, true)
+	if mutate || reason != "" {
+		t.Fatalf("list-only: mutate=%v reason=%q", mutate, reason)
+	}
+}
+
+func TestValidatePromoteTargets(t *testing.T) {
+	t.Parallel()
+	if err := validatePromoteTargets(false, "", "", ""); err != nil {
+		t.Fatalf("list-only: %v", err)
+	}
+	if err := validatePromoteTargets(true, "a@b.c", "", ""); err != nil {
+		t.Fatalf("email: %v", err)
+	}
+	if err := validatePromoteTargets(true, "", "11111111-1111-1111-1111-111111111111", ""); err != nil {
+		t.Fatalf("user-id: %v", err)
+	}
+	if err := validatePromoteTargets(true, "", "", "22222222-2222-2222-2222-222222222222"); err != nil {
+		t.Fatalf("company-id alone: %v", err)
+	}
+	err := validatePromoteTargets(true, "", "", "")
+	if err == nil || !strings.Contains(err.Error(), "requires -email, -user-id, or -company-id") {
+		t.Fatalf("expected unscoped refuse, got %v", err)
+	}
+	err = validatePromoteTargets(true, "  ", "  ", "  ")
+	if err == nil || !strings.Contains(err.Error(), "requires -email, -user-id, or -company-id") {
+		t.Fatalf("expected blank refuse, got %v", err)
+	}
+}
+
+func TestGuardLiveMutation(t *testing.T) {
+	t.Parallel()
+	if err := guardLiveMutation(false, false, false, "-promote-company-admins"); err != nil {
+		t.Fatalf("list-only: %v", err)
+	}
+	if err := guardLiveMutation(true, true, false, "-promote-company-admins"); err != nil {
+		t.Fatalf("dry-run: %v", err)
+	}
+	if err := guardLiveMutation(true, false, true, "-promote-company-admins"); err != nil {
+		t.Fatalf("confirm: %v", err)
+	}
+	err := guardLiveMutation(true, false, false, "-promote-company-admins")
+	if err == nil || !strings.Contains(err.Error(), "no blind live writes") {
+		t.Fatalf("expected blind-write refusal, got %v", err)
+	}
+	if !strings.Contains(err.Error(), "-promote-company-admins") {
+		t.Fatalf("expected flag hint in error, got %v", err)
+	}
+}
+
+func TestGuardLiveAssignDelegates(t *testing.T) {
+	t.Parallel()
+	err := guardLiveAssign(true, false, false)
+	if err == nil || !strings.Contains(err.Error(), "-assign-missing-plans") {
+		t.Fatalf("expected assign hint, got %v", err)
+	}
+}

apps/api/cmd/migrator/migrator_test.go

@@ -0,0 +1,42 @@
+package main
+
+import (
+	"testing"
+)
+
+func TestLoadFixture(t *testing.T) {
+	fx, err := loadFixture("testdata/fixture.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(fx.Companies) != 1 || len(fx.Users) != 2 {
+		t.Fatalf("unexpected fixture sizes: companies=%d users=%d", len(fx.Companies), len(fx.Users))
+	}
+	if len(fx.AdminUsers) != 1 {
+		t.Fatalf("expected admin_users")
+	}
+	if len(fx.XMLFeeds) != 1 || len(fx.XMLFeeds[0].FieldMappings) == 0 {
+		t.Fatalf("expected feed mappings in fixture")
+	}
+}
+
+func TestEnsureJSON(t *testing.T) {
+	if string(ensureJSON(nil)) != "{}" {
+		t.Fatalf("nil -> {}")
+	}
+	if string(ensureJSON([]byte("not-json"))) != "{}" {
+		t.Fatalf("invalid -> {}")
+	}
+	in := []byte(`{"a":1}`)
+	if string(ensureJSON(in)) != `{"a":1}` {
+		t.Fatalf("valid passthrough")
+	}
+}
+
+func TestAttachEntityMaps(t *testing.T) {
+	doc := NewIDMapDocument(map[string]string{"u1": "550e8400-e29b-41d4-a716-446655440000"}, map[string]string{"c1": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"}, true)
+	doc.AttachEntityMaps(nil, nil, map[string]string{"10": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"}, nil, nil, map[string]int{"feeds": 1})
+	if len(doc.Feeds) != 1 || doc.Meta.Report["feeds"] != 1 {
+		t.Fatalf("attach failed: %#v", doc)
+	}
+}

apps/api/cmd/migrator/mysqlmeta.go

@@ -0,0 +1,76 @@
+package main
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+	"strings"
+)
+
+// mysqlCol returns a quoted column name if present, otherwise a SQL literal/expression fallback.
+func mysqlCol(ctx context.Context, db *sql.DB, table, column, fallbackExpr string) string {
+	if mysqlColumnExists(ctx, db, table, column) {
+		q, err := quoteMySQLIdent(column)
+		if err != nil {
+			return fallbackExpr
+		}
+		return q
+	}
+	return fallbackExpr
+}
+
+// mysqlCoalesce returns COALESCE(column, fallback) when column exists, else fallback alone.
+func mysqlCoalesce(ctx context.Context, db *sql.DB, table, column, fallbackExpr string) string {
+	if mysqlColumnExists(ctx, db, table, column) {
+		q, err := quoteMySQLIdent(column)
+		if err != nil {
+			return fallbackExpr
+		}
+		return fmt.Sprintf("COALESCE(%s, %s)", q, fallbackExpr)
+	}
+	return fallbackExpr
+}
+
+// mysqlSelectList builds "SELECT a, b, ..." from expressions (already resolved).
+func mysqlSelectList(exprs ...string) string {
+	return "SELECT " + strings.Join(exprs, ", ")
+}
+
+// scanIntish scans MySQL INT/DECIMAL/string numeric values into an int.
+func scanIntish(v any) int {
+	switch x := v.(type) {
+	case int64:
+		return int(x)
+	case int32:
+		return int(x)
+	case float64:
+		return int(x)
+	case []byte:
+		var n float64
+		if _, err := fmt.Sscanf(string(x), "%f", &n); err == nil {
+			return int(n)
+		}
+	case string:
+		var n float64
+		if _, err := fmt.Sscanf(x, "%f", &n); err == nil {
+			return int(n)
+		}
+	}
+	return 0
+}
+
+// queryFirstOK tries queries in order until one succeeds (for column-shape fallbacks).
+func queryFirstOK(ctx context.Context, db *sql.DB, queries ...string) (*sql.Rows, error) {
+	var last error
+	for _, q := range queries {
+		rows, err := db.QueryContext(ctx, q)
+		if err == nil {
+			return rows, nil
+		}
+		last = err
+	}
+	if last == nil {
+		return nil, fmt.Errorf("no queries provided")
+	}
+	return nil, last
+}

apps/api/cmd/migrator/mysqlmeta_test.go

@@ -0,0 +1,41 @@
+package main
+
+import "testing"
+
+func TestScanIntish(t *testing.T) {
+	cases := []struct {
+		in   any
+		want int
+	}{
+		{int64(42), 42},
+		{float64(3.9), 3},
+		{[]byte("12.50"), 12},
+		{"7", 7},
+		{nil, 0},
+	}
+	for _, tc := range cases {
+		if got := scanIntish(tc.in); got != tc.want {
+			t.Fatalf("scanIntish(%v)=%d want %d", tc.in, got, tc.want)
+		}
+	}
+}
+
+func TestSummarizeOrphans(t *testing.T) {
+	s := summarizeOrphans([]OrphanFinding{
+		{Check: "a", Pass: true},
+		{Check: "b", Pass: false},
+		{Check: "platform_admins", Pass: true, Count: 2},
+		{Check: "skipped_dry_run", Pass: true},
+	})
+	if s.Passed != 3 || s.Failed != 1 || s.Total != 4 {
+		t.Fatalf("summary %#v", s)
+	}
+}
+
+func TestMysqlSelectList(t *testing.T) {
+	got := mysqlSelectList("id", "COALESCE(name, id)", "'en'")
+	want := "SELECT id, COALESCE(name, id), 'en'"
+	if got != want {
+		t.Fatalf("got %q", got)
+	}
+}

apps/api/cmd/migrator/postimport.go

@@ -0,0 +1,176 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/descrybe/descrybe-v2/apps/api/internal/auth"
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// SetPasswordHook is a one-time accept-invite style token for a migrated user.
+// SMTP delivery is owned by mailhooks / WS7 — this only prepares durable invite rows + a local artifact.
+type SetPasswordHook struct {
+	UserID    uuid.UUID `json:"user_id"`
+	Email     string    `json:"email"`
+	CompanyID uuid.UUID `json:"company_id"`
+	Role      string    `json:"role"`
+	Token     string    `json:"token"`
+	URL       string    `json:"url"`
+	ExpiresAt time.Time `json:"expires_at"`
+	InviteID  uuid.UUID `json:"invite_id,omitempty"`
+}
+
+func webOrigin() string {
+	o := strings.TrimSpace(os.Getenv("WEB_ORIGIN"))
+	if o == "" {
+		o = "http://localhost:5174"
+	}
+	return strings.TrimRight(o, "/")
+}
+
+func setPasswordInviteURL(token string) string {
+	return webOrigin() + "/accept-invite?token=" + url.QueryEscape(token)
+}
+
+// prepareSetPasswordHooks creates invites for active users with must_set_password=true.
+// Tokens are returned once for the artifact (do not commit). AcceptInvite sets password
+// only when must_set_password is still true (existing accounts with a password must verify it).
+func prepareSetPasswordHooks(
+	ctx context.Context,
+	pg *pgxpool.Pool,
+	ttl time.Duration,
+	dryRun bool,
+	report map[string]int,
+) ([]SetPasswordHook, error) {
+	if dryRun {
+		report["set_password_hooks_skipped_dry_run"]++
+		return nil, nil
+	}
+	if ttl <= 0 {
+		ttl = 7 * 24 * time.Hour
+	}
+
+	rows, err := pg.Query(ctx, `
+		SELECT u.id, u.email, m.company_id, m.role
+		FROM users u
+		JOIN memberships m ON m.user_id = u.id AND m.status = 'active'
+		WHERE u.must_set_password = true AND u.is_active = true
+		ORDER BY u.email, m.created_at
+	`)
+	if err != nil {
+		return nil, fmt.Errorf("list must_set_password users: %w", err)
+	}
+	defer rows.Close()
+
+	seen := map[uuid.UUID]bool{}
+	var hooks []SetPasswordHook
+	expires := time.Now().UTC().Add(ttl)
+
+	for rows.Next() {
+		var h SetPasswordHook
+		if err := rows.Scan(&h.UserID, &h.Email, &h.CompanyID, &h.Role); err != nil {
+			return nil, err
+		}
+		if seen[h.UserID] {
+			continue
+		}
+		seen[h.UserID] = true
+		if auth.IsSyntheticLegacyEmail(h.Email) {
+			report["set_password_hooks_skipped_synthetic"]++
+			continue
+		}
+		if h.Role == "" {
+			h.Role = "member"
+		}
+		token, err := auth.RandomToken(24)
+		if err != nil {
+			return nil, err
+		}
+		h.Token = token
+		h.ExpiresAt = expires
+		h.URL = setPasswordInviteURL(h.Token)
+
+		// Expire prior unaccepted invites for this email+company so re-issue is safe.
+		_, _ = pg.Exec(ctx, `
+			UPDATE invites
+			SET expires_at = least(expires_at, now())
+			WHERE company_id = $1 AND lower(email) = lower($2) AND accepted_at IS NULL`,
+			h.CompanyID, h.Email)
+
+		err = pg.QueryRow(ctx, `
+			INSERT INTO invites (company_id, email, role, token, expires_at)
+			VALUES ($1, lower($2), $3, $4, $5)
+			RETURNING id`,
+			h.CompanyID, h.Email, h.Role, auth.HashInviteToken(h.Token), h.ExpiresAt,
+		).Scan(&h.InviteID)
+		if err != nil {
+			log.Printf("set-password invite for user_id=%s: %v", h.UserID, err)
+			report["set_password_hooks_skipped"]++
+			continue
+		}
+		hooks = append(hooks, h)
+		report["set_password_hooks"]++
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return hooks, nil
+}
+
+func writeSetPasswordArtifacts(mapsDir string, hooks []SetPasswordHook) error {
+	if len(hooks) == 0 {
+		return nil
+	}
+	if err := os.MkdirAll(mapsDir, 0o755); err != nil {
+		return err
+	}
+	// Canonical mailhooks path + operator-friendly alias with URLs.
+	hookPath := filepath.Join(mapsDir, "set-password-hooks.json")
+	invitePath := filepath.Join(mapsDir, "password_invites.json")
+	if err := writeJSON(hookPath, hooks); err != nil {
+		return err
+	}
+	if err := writeJSON(invitePath, hooks); err != nil {
+		return err
+	}
+	fmt.Printf("wrote %d set-password invites to %s and %s (do not commit)\n", len(hooks), invitePath, hookPath)
+	fmt.Println("=== Set-password invite URLs ===")
+	for _, h := range hooks {
+		fmt.Printf("%s\t%s\n", h.Email, h.URL)
+	}
+	return nil
+}
+
+// setPasswordByEmail is a local/dev bootstrap: force a password for one migrated user.
+func setPasswordByEmail(ctx context.Context, pg *pgxpool.Pool, emailPass string) error {
+	parts := strings.SplitN(emailPass, ":", 2)
+	if len(parts) != 2 || strings.TrimSpace(parts[0]) == "" || parts[1] == "" {
+		return fmt.Errorf("-set-password expects email:password")
+	}
+	email := strings.ToLower(strings.TrimSpace(parts[0]))
+	password := parts[1]
+	hash, err := auth.HashPassword(password)
+	if err != nil {
+		return err
+	}
+	ct, err := pg.Exec(ctx, `
+		UPDATE users
+		SET password_hash = $2, must_set_password = false, updated_at = now()
+		WHERE lower(email) = $1`, email, hash)
+	if err != nil {
+		return err
+	}
+	if ct.RowsAffected() == 0 {
+		return fmt.Errorf("no user with email %s", email)
+	}
+	fmt.Printf("set password for %s (must_set_password=false)\n", email)
+	return nil
+}

apps/api/cmd/migrator/postimport_test.go

@@ -0,0 +1,34 @@
+package main
+
+import (
+	"context"
+	"os"
+	"strings"
+	"testing"
+)
+
+func TestSetPasswordInviteURL(t *testing.T) {
+	t.Setenv("WEB_ORIGIN", "https://app.example.com/")
+	got := setPasswordInviteURL("tok+1")
+	wantPrefix := "https://app.example.com/accept-invite?token="
+	if !strings.HasPrefix(got, wantPrefix) {
+		t.Fatalf("got %q", got)
+	}
+	if !strings.Contains(got, "tok%2B1") && !strings.Contains(got, "tok+1") {
+		t.Fatalf("token not in URL: %q", got)
+	}
+}
+
+func TestSetPasswordByEmailParse(t *testing.T) {
+	err := setPasswordByEmail(context.TODO(), nil, "bad")
+	if err == nil || !strings.Contains(err.Error(), "email:password") {
+		t.Fatalf("expected parse error, got %v", err)
+	}
+}
+
+func TestWebOriginDefault(t *testing.T) {
+	os.Unsetenv("WEB_ORIGIN")
+	if webOrigin() != "http://localhost:5174" {
+		t.Fatalf("default origin")
+	}
+}

apps/api/cmd/migrator/report.go

@@ -0,0 +1,296 @@
+package main
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+	"log"
+	"sort"
+	"strings"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// CountPair is one MySQL vs Postgres table count comparison.
+type CountPair struct {
+	Entity   string `json:"entity"`
+	MySQL    int64  `json:"mysql"`
+	Postgres int64  `json:"postgres"`
+	Delta    int64  `json:"delta"`
+	Note     string `json:"note,omitempty"`
+}
+
+// OrphanFinding is a remapped FK that does not resolve in Postgres.
+type OrphanFinding struct {
+	Check  string `json:"check"`
+	Count  int64  `json:"count"`
+	Sample string `json:"sample,omitempty"`
+	Pass   bool   `json:"pass"`
+}
+
+// ValidationReport is written next to the ID map for cutover verification.
+type ValidationReport struct {
+	Mode           string           `json:"mode"`
+	Counts         []CountPair      `json:"counts"`
+	PostgresCounts map[string]int64 `json:"postgres_counts,omitempty"`
+	Orphans        []OrphanFinding  `json:"orphans"`
+	OrphanSummary  OrphanSummary    `json:"orphan_summary"`
+	OK             bool             `json:"ok"`
+}
+
+// OrphanSummary is a compact end-of-run pass/fail tally.
+type OrphanSummary struct {
+	Passed int `json:"passed"`
+	Failed int `json:"failed"`
+	Total  int `json:"total"`
+}
+
+func mysqlCount(ctx context.Context, db *sql.DB, table string) (int64, error) {
+	quoted, err := quoteMySQLIdent(table)
+	if err != nil {
+		return -1, err
+	}
+	if !mysqlTableExists(ctx, db, table) {
+		return -1, fmt.Errorf("missing")
+	}
+	var n int64
+	err = db.QueryRowContext(ctx, "SELECT COUNT(*) FROM "+quoted).Scan(&n)
+	return n, err
+}
+
+func pgCount(ctx context.Context, pg *pgxpool.Pool, table string) (int64, error) {
+	quoted, err := quotePGIdent(table)
+	if err != nil {
+		return -1, err
+	}
+	var n int64
+	err = pg.QueryRow(ctx, "SELECT COUNT(*) FROM "+quoted).Scan(&n)
+	return n, err
+}
+
+// pgVerificationTables are Postgres targets printed at end-of-run.
+var pgVerificationTables = []string{
+	"companies",
+	"users",
+	"memberships",
+	"plans",
+	"company_plans",
+	"credit_balances",
+	"categories",
+	"attributes",
+	"category_attributes",
+	"custom_variables",
+	"input_feeds",
+	"feed_mappings",
+	"export_feeds",
+	"raw_products",
+	"processed_products",
+	"files",
+}
+
+func collectPostgresCounts(ctx context.Context, pg *pgxpool.Pool, dryRun bool) map[string]int64 {
+	out := map[string]int64{}
+	if dryRun || pg == nil {
+		return out
+	}
+	for _, t := range pgVerificationTables {
+		if n, err := pgCount(ctx, pg, t); err == nil {
+			out[t] = n
+		} else {
+			out[t] = -1
+		}
+	}
+	return out
+}
+
+// buildCountReport compares allowlisted MySQL source tables to Postgres targets.
+func buildCountReport(ctx context.Context, mysqlDB *sql.DB, pg *pgxpool.Pool, dryRun bool) []CountPair {
+	pairs := []struct{ mysql, postgres, note string }{
+		{"companies", "companies", ""},
+		{"profiles", "memberships", "profiles → memberships"},
+		{"users", "users", "no password_hash imported"},
+		{"admin_users", "", "folded into users.is_platform_admin"},
+		{"plans", "plans", ""},
+		{"company_plans", "company_plans", ""},
+		{"credit_balances", "credit_balances", ""},
+		{"categories", "categories", ""},
+		{"attributes", "attributes", ""},
+		{"category_attributes", "category_attributes", ""},
+		{"custom_variables", "custom_variables", "label/example → value"},
+		{"xml_feeds", "input_feeds", "xml_feeds → input_feeds"},
+		{"raw_products", "raw_products", ""},
+		{"processed_products", "processed_products", ""},
+		{"export_feeds", "export_feeds", ""},
+		{"files", "files", "metadata only; blobs not copied"},
+		{"company_settings", "company_settings", "partial: language + merge_products only"},
+		{"api_keys", "", "not migrated; clients must create new keys"},
+		{"processing_jobs", "processing_jobs", "migrated when domain jobs enabled (ai_provider_mode=migrated)"},
+	}
+
+	out := make([]CountPair, 0, len(pairs))
+	for _, p := range pairs {
+		cp := CountPair{Entity: p.mysql, Note: p.note, MySQL: -1, Postgres: -1}
+		if n, err := mysqlCount(ctx, mysqlDB, p.mysql); err == nil {
+			cp.MySQL = n
+		} else {
+			cp.Note = strings.TrimSpace(cp.Note + " mysql_missing")
+		}
+		if p.postgres != "" && !dryRun {
+			if n, err := pgCount(ctx, pg, p.postgres); err == nil {
+				cp.Postgres = n
+				if cp.MySQL >= 0 {
+					cp.Delta = cp.Postgres - cp.MySQL
+				}
+			} else {
+				cp.Note = strings.TrimSpace(cp.Note + " pg_error")
+			}
+		}
+		out = append(out, cp)
+	}
+	return out
+}
+
+// checkOrphanFKs runs Postgres-side orphan queries after a live load.
+// Dry-run skips (no writes to validate).
+func checkOrphanFKs(ctx context.Context, pg *pgxpool.Pool, dryRun bool) []OrphanFinding {
+	if dryRun {
+		return []OrphanFinding{{
+			Check:  "skipped_dry_run",
+			Pass:   true,
+			Sample: "orphan FK checks require a live Postgres load",
+		}}
+	}
+
+	checks := []struct {
+		name string
+		sql  string
+	}{
+		{"memberships_missing_user", `SELECT COUNT(*) FROM memberships m LEFT JOIN users u ON u.id = m.user_id WHERE u.id IS NULL`},
+		{"memberships_missing_company", `SELECT COUNT(*) FROM memberships m LEFT JOIN companies c ON c.id = m.company_id WHERE c.id IS NULL`},
+		{"categories_missing_company", `SELECT COUNT(*) FROM categories x LEFT JOIN companies c ON c.id = x.company_id WHERE c.id IS NULL`},
+		{"attributes_missing_company", `SELECT COUNT(*) FROM attributes x LEFT JOIN companies c ON c.id = x.company_id WHERE c.id IS NULL`},
+		{"custom_variables_missing_company", `SELECT COUNT(*) FROM custom_variables x LEFT JOIN companies c ON c.id = x.company_id WHERE c.id IS NULL`},
+		{"raw_products_missing_company", `SELECT COUNT(*) FROM raw_products r LEFT JOIN companies c ON c.id = r.company_id WHERE c.id IS NULL`},
+		{"raw_products_missing_feed", `SELECT COUNT(*) FROM raw_products r LEFT JOIN input_feeds f ON f.id = r.feed_id WHERE r.feed_id IS NOT NULL AND f.id IS NULL`},
+		{"processed_missing_company", `SELECT COUNT(*) FROM processed_products p LEFT JOIN companies c ON c.id = p.company_id WHERE c.id IS NULL`},
+		{"processed_missing_raw", `SELECT COUNT(*) FROM processed_products p LEFT JOIN raw_products r ON r.id = p.raw_product_id WHERE p.raw_product_id IS NOT NULL AND r.id IS NULL`},
+		{"processed_missing_feed", `SELECT COUNT(*) FROM processed_products p LEFT JOIN input_feeds f ON f.id = p.feed_id WHERE p.feed_id IS NOT NULL AND f.id IS NULL`},
+		{"export_feeds_missing_company", `SELECT COUNT(*) FROM export_feeds e LEFT JOIN companies c ON c.id = e.company_id WHERE c.id IS NULL`},
+		{"export_feeds_missing_source", `SELECT COUNT(*) FROM export_feeds e LEFT JOIN input_feeds f ON f.id = e.source_feed_id WHERE e.source_feed_id IS NOT NULL AND f.id IS NULL`},
+		{"feed_mappings_missing_feed", `SELECT COUNT(*) FROM feed_mappings m LEFT JOIN input_feeds f ON f.id = m.feed_id WHERE f.id IS NULL`},
+		{"files_missing_company", `SELECT COUNT(*) FROM files f LEFT JOIN companies c ON c.id = f.company_id WHERE c.id IS NULL`},
+		{"company_plans_missing_plan", `SELECT COUNT(*) FROM company_plans cp LEFT JOIN plans p ON p.id = cp.plan_id WHERE p.id IS NULL`},
+		{"companies_without_active_plan", `SELECT COUNT(*) FROM companies c WHERE NOT EXISTS (SELECT 1 FROM company_plans cp WHERE cp.company_id = c.id AND cp.is_active = true)`},
+		{"platform_admins", `SELECT COUNT(*) FROM users WHERE is_platform_admin = true`},
+	}
+
+	out := make([]OrphanFinding, 0, len(checks))
+	for _, c := range checks {
+		var n int64
+		err := pg.QueryRow(ctx, c.sql).Scan(&n)
+		f := OrphanFinding{Check: c.name, Count: n, Pass: err == nil}
+		if err != nil {
+			f.Pass = false
+			f.Sample = err.Error()
+		} else if c.name == "platform_admins" {
+			// Informational — not an orphan.
+			f.Pass = true
+		} else if c.name == "companies_without_active_plan" {
+			// Informational cutover signal (use -list-companies-without-plans / -assign-missing-plans).
+			f.Pass = true
+			if n > 0 {
+				f.Sample = fmt.Sprintf("%d companies lack an active plan", n)
+			}
+		} else {
+			f.Pass = n == 0
+		}
+		out = append(out, f)
+	}
+	return out
+}
+
+func summarizeOrphans(orphans []OrphanFinding) OrphanSummary {
+	s := OrphanSummary{Total: len(orphans)}
+	for _, o := range orphans {
+		if o.Check == "skipped_dry_run" || o.Check == "skipped_fixture" || o.Check == "platform_admins" || o.Check == "companies_without_active_plan" {
+			s.Passed++
+			continue
+		}
+		if o.Pass {
+			s.Passed++
+		} else {
+			s.Failed++
+		}
+	}
+	return s
+}
+
+func printValidation(v ValidationReport) {
+	fmt.Println("=== Validation report ===")
+	fmt.Printf("mode: %s ok=%v\n", v.Mode, v.OK)
+
+	fmt.Println("-- mysql vs postgres counts --")
+	for _, c := range v.Counts {
+		fmt.Printf("%s mysql=%d postgres=%d delta=%d %s\n", c.Entity, c.MySQL, c.Postgres, c.Delta, c.Note)
+	}
+
+	if len(v.PostgresCounts) > 0 {
+		fmt.Println("-- postgres table counts --")
+		keys := make([]string, 0, len(v.PostgresCounts))
+		for k := range v.PostgresCounts {
+			keys = append(keys, k)
+		}
+		sort.Strings(keys)
+		for _, k := range keys {
+			fmt.Printf("%s: %d\n", k, v.PostgresCounts[k])
+		}
+	}
+
+	fmt.Println("-- orphans --")
+	names := make([]string, 0, len(v.Orphans))
+	byName := map[string]OrphanFinding{}
+	for _, o := range v.Orphans {
+		names = append(names, o.Check)
+		byName[o.Check] = o
+	}
+	sort.Strings(names)
+	for _, name := range names {
+		o := byName[name]
+		status := "PASS"
+		if !o.Pass {
+			status = "FAIL"
+		}
+		fmt.Printf("%s %s count=%d %s\n", status, o.Check, o.Count, o.Sample)
+	}
+	fmt.Printf("-- orphan summary -- passed=%d failed=%d total=%d\n",
+		v.OrphanSummary.Passed, v.OrphanSummary.Failed, v.OrphanSummary.Total)
+}
+
+func runValidation(
+	ctx context.Context,
+	mysqlDB *sql.DB,
+	pg *pgxpool.Pool,
+	dryRun bool,
+) ValidationReport {
+	mode := "live"
+	if dryRun {
+		mode = "dry-run"
+	}
+	counts := buildCountReport(ctx, mysqlDB, pg, dryRun)
+	pgCounts := collectPostgresCounts(ctx, pg, dryRun)
+	orphans := checkOrphanFKs(ctx, pg, dryRun)
+	summary := summarizeOrphans(orphans)
+	ok := summary.Failed == 0
+	v := ValidationReport{
+		Mode:           mode,
+		Counts:         counts,
+		PostgresCounts: pgCounts,
+		Orphans:        orphans,
+		OrphanSummary:  summary,
+		OK:             ok,
+	}
+	if !ok {
+		log.Printf("validation: orphan FK failures present — inspect report before DNS cutover")
+	}
+	return v
+}

apps/api/cmd/migrator/sqlident.go

@@ -0,0 +1,53 @@
+package main
+
+import (
+	"fmt"
+	"regexp"
+	"strings"
+)
+
+// SQL identifiers in this migrator are always static allowlisted names or
+// programmer-supplied column paths — never end-user free text. Still quote
+// and validate before interpolating into DDL/DML to fail closed on mistakes.
+
+var sqlIdentSegment = regexp.MustCompile(`^[A-Za-z_][A-Za-z0-9_]*$`)
+
+func quoteMySQLIdent(ident string) (string, error) {
+	if !sqlIdentSegment.MatchString(ident) {
+		return "", fmt.Errorf("invalid MySQL identifier %q", ident)
+	}
+	return "`" + strings.ReplaceAll(ident, "`", "``") + "`", nil
+}
+
+// quoteMySQLIdentPath quotes dotted paths such as company_id or cf.company_id.
+func quoteMySQLIdentPath(path string) (string, error) {
+	path = strings.TrimSpace(path)
+	if path == "" {
+		return "", fmt.Errorf("empty MySQL identifier path")
+	}
+	parts := strings.Split(path, ".")
+	out := make([]string, len(parts))
+	for i, part := range parts {
+		q, err := quoteMySQLIdent(part)
+		if err != nil {
+			return "", err
+		}
+		out[i] = q
+	}
+	return strings.Join(out, "."), nil
+}
+
+func mustQuoteMySQLIdent(ident string) string {
+	q, err := quoteMySQLIdent(ident)
+	if err != nil {
+		panic(err)
+	}
+	return q
+}
+
+func quotePGIdent(ident string) (string, error) {
+	if !sqlIdentSegment.MatchString(ident) {
+		return "", fmt.Errorf("invalid Postgres identifier %q", ident)
+	}
+	return `"` + strings.ReplaceAll(ident, `"`, `""`) + `"`, nil
+}

apps/api/cmd/migrator/sqlident_test.go

@@ -0,0 +1,42 @@
+package main
+
+import "testing"
+
+func TestQuoteMySQLIdent(t *testing.T) {
+	got, err := quoteMySQLIdent("order")
+	if err != nil || got != "`order`" {
+		t.Fatalf("order: got %q err=%v", got, err)
+	}
+	if _, err := quoteMySQLIdent("users; DROP TABLE x"); err == nil {
+		t.Fatal("expected reject for injection payload")
+	}
+	if _, err := quoteMySQLIdent("a-b"); err == nil {
+		t.Fatal("expected reject for hyphen")
+	}
+}
+
+func TestQuoteMySQLIdentPath(t *testing.T) {
+	got, err := quoteMySQLIdentPath("cf.company_id")
+	if err != nil || got != "`cf`.`company_id`" {
+		t.Fatalf("path: got %q err=%v", got, err)
+	}
+	if _, err := quoteMySQLIdentPath("cf.company_id;--"); err == nil {
+		t.Fatal("expected reject")
+	}
+}
+
+func TestQuotePGIdent(t *testing.T) {
+	got, err := quotePGIdent("companies")
+	if err != nil || got != `"companies"` {
+		t.Fatalf("got %q err=%v", got, err)
+	}
+	if _, err := quotePGIdent(`companies" OR 1=1`); err == nil {
+		t.Fatal("expected reject")
+	}
+}
+
+func TestMustQuoteMySQLIdent(t *testing.T) {
+	if got := mustQuoteMySQLIdent("key"); got != "`key`" {
+		t.Fatalf("got %q", got)
+	}
+}

apps/api/cmd/migrator/testdata/fixture.json

@@ -0,0 +1,30 @@
+{
+  "companies": [
+    {"id": "co_legacy_1", "name": "Acme Feeds", "language": "en"}
+  ],
+  "users": [
+    {"id": "user_clerk_admin", "email": "admin@example.com", "name": "Admin", "active": true},
+    {"id": "user_clerk_member", "email": "member@example.com", "name": "Member", "active": true}
+  ],
+  "admin_users": [
+    {"user_id": "user_clerk_admin", "email": "admin@example.com"}
+  ],
+  "profiles": [
+    {"company_id": "co_legacy_1", "user_id": "user_clerk_admin", "role": "admin", "status": "active"},
+    {"company_id": "co_legacy_1", "user_id": "user_clerk_member", "role": "member", "status": "active"}
+  ],
+  "xml_feeds": [
+    {
+      "id": 101,
+      "company_id": "co_legacy_1",
+      "name": "Demo XML",
+      "field_mappings": {
+        "title": {"xpath": "/item/title", "fieldName": "title", "originalName": "title", "isRequired": true}
+      }
+    }
+  ],
+  "files": [
+    {"id": 1, "company_id": "co_legacy_1", "file_name": "upload.csv"}
+  ],
+  "raw_products_count": 3
+}

apps/api/cmd/mock-llm/main.go

@@ -0,0 +1,234 @@
+// Command mock-llm serves a tiny OpenAI-compatible Chat Completions API for
+// local/CI processing proofs. It reuses processing.HeuristicCompleter so
+// enhance JSON shapes match the offline fallback, while exercising the real
+// OpenAIClient HTTP path (no production API keys).
+//
+// Usage:
+//
+//	go run ./cmd/mock-llm -addr 127.0.0.1:18767
+//	go run ./cmd/mock-llm -addr 127.0.0.1:18767 -key local-test -model mock-llm
+//
+// Then point platform env (or /integrations/ai) at:
+//
+//	OPENAI_API_KEY=local-test
+//	OPENAI_BASE_URL=http://127.0.0.1:18767/v1
+//	OPENAI_MODEL=mock-llm
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"flag"
+	"io"
+	"log"
+	"net/http"
+	"os"
+	"strings"
+	"sync/atomic"
+	"time"
+
+	"github.com/descrybe/descrybe-v2/apps/api/internal/processing"
+)
+
+type server struct {
+	apiKey string
+	model  string
+	logReq atomic.Int64
+}
+
+type chatRequest struct {
+	Model       string `json:"model"`
+	Messages    []struct {
+		Role    string `json:"role"`
+		Content string `json:"content"`
+	} `json:"messages"`
+	Temperature float64 `json:"temperature"`
+	MaxTokens   int     `json:"max_tokens"`
+}
+
+func main() {
+	addr := flag.String("addr", "127.0.0.1:18767", "listen address")
+	key := flag.String("key", envOr("MOCK_LLM_API_KEY", "local-test"), "Bearer API key (non-empty placeholder)")
+	model := flag.String("model", envOr("MOCK_LLM_MODEL", "mock-llm"), "model id returned by /v1/models")
+	flag.Parse()
+
+	s := &server{
+		apiKey: strings.TrimSpace(*key),
+		model:  strings.TrimSpace(*model),
+	}
+	if s.apiKey == "" {
+		log.Fatal("mock-llm: API key must be non-empty (Descrybe Completer.Enabled requires it)")
+	}
+	if s.model == "" {
+		s.model = "mock-llm"
+	}
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("/healthz", s.handleHealth)
+	mux.HandleFunc("/v1/models", s.handleModels)
+	mux.HandleFunc("/v1/chat/completions", s.handleChatCompletions)
+	mux.HandleFunc("/v1/embeddings", s.handleEmbeddings)
+
+	log.Printf("mock-llm listening on http://%s", *addr)
+	log.Printf("OpenAI base: http://%s/v1  model=%s  key=<redacted>", *addr, s.model)
+	log.Printf("Wire: OPENAI_BASE_URL=http://%s/v1 OPENAI_API_KEY=<redacted> OPENAI_MODEL=%s", *addr, s.model)
+	if err := http.ListenAndServe(*addr, mux); err != nil {
+		log.Fatal(err)
+	}
+}
+
+func envOr(k, def string) string {
+	if v := strings.TrimSpace(os.Getenv(k)); v != "" {
+		return v
+	}
+	return def
+}
+
+func (s *server) handleHealth(w http.ResponseWriter, _ *http.Request) {
+	writeJSON(w, http.StatusOK, map[string]any{
+		"status":  "ok",
+		"service": "mock-llm",
+		"model":   s.model,
+	})
+}
+
+func (s *server) authOK(r *http.Request) bool {
+	h := r.Header.Get("Authorization")
+	if !strings.HasPrefix(h, "Bearer ") {
+		return false
+	}
+	token := strings.TrimSpace(strings.TrimPrefix(h, "Bearer "))
+	return token == s.apiKey
+}
+
+func (s *server) handleModels(w http.ResponseWriter, r *http.Request) {
+	s.logReq.Add(1)
+	if r.Method != http.MethodGet {
+		http.Error(w, `{"error":{"message":"method not allowed"}}`, http.StatusMethodNotAllowed)
+		return
+	}
+	if !s.authOK(r) {
+		http.Error(w, `{"error":{"message":"unauthorized"}}`, http.StatusUnauthorized)
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{
+		"object": "list",
+		"data": []map[string]any{
+			{"id": s.model, "object": "model", "owned_by": "descrybe-mock"},
+		},
+	})
+}
+
+func (s *server) handleChatCompletions(w http.ResponseWriter, r *http.Request) {
+	s.logReq.Add(1)
+	if r.Method != http.MethodPost {
+		http.Error(w, `{"error":{"message":"method not allowed"}}`, http.StatusMethodNotAllowed)
+		return
+	}
+	if !s.authOK(r) {
+		http.Error(w, `{"error":{"message":"unauthorized"}}`, http.StatusUnauthorized)
+		return
+	}
+	body, err := io.ReadAll(io.LimitReader(r.Body, 2<<20))
+	if err != nil {
+		http.Error(w, `{"error":{"message":"read body"}}`, http.StatusBadRequest)
+		return
+	}
+	var req chatRequest
+	if err := json.Unmarshal(body, &req); err != nil {
+		http.Error(w, `{"error":{"message":"invalid json"}}`, http.StatusBadRequest)
+		return
+	}
+	system, user := splitMessages(req.Messages)
+	comp, err := processing.HeuristicCompleter{}.Complete(context.Background(), system, user)
+	if err != nil {
+		http.Error(w, `{"error":{"message":"completer failed"}}`, http.StatusInternalServerError)
+		return
+	}
+	model := strings.TrimSpace(req.Model)
+	if model == "" {
+		model = s.model
+	}
+	promptTokens := estimateTokens(system) + estimateTokens(user)
+	completionTokens := estimateTokens(comp.Text)
+	writeJSON(w, http.StatusOK, map[string]any{
+		"id":      "chatcmpl-mock",
+		"object":  "chat.completion",
+		"created": time.Now().Unix(),
+		"model":   model,
+		"choices": []map[string]any{
+			{
+				"index": 0,
+				"message": map[string]any{
+					"role":    "assistant",
+					"content": comp.Text,
+				},
+				"finish_reason": "stop",
+			},
+		},
+		"usage": map[string]any{
+			"prompt_tokens":     promptTokens,
+			"completion_tokens": completionTokens,
+			"total_tokens":      promptTokens + completionTokens,
+		},
+	})
+}
+
+func (s *server) handleEmbeddings(w http.ResponseWriter, r *http.Request) {
+	s.logReq.Add(1)
+	if r.Method != http.MethodPost {
+		http.Error(w, `{"error":{"message":"method not allowed"}}`, http.StatusMethodNotAllowed)
+		return
+	}
+	if !s.authOK(r) {
+		http.Error(w, `{"error":{"message":"unauthorized"}}`, http.StatusUnauthorized)
+		return
+	}
+	// Tiny fixed vector — enough for platform role probe / CI smoke.
+	writeJSON(w, http.StatusOK, map[string]any{
+		"object": "list",
+		"model":  s.model + "-embed",
+		"data": []map[string]any{
+			{"object": "embedding", "index": 0, "embedding": []float32{0.01, 0.02, 0.03, 0.04}},
+		},
+		"usage": map[string]any{"prompt_tokens": 1, "total_tokens": 1},
+	})
+}
+
+func splitMessages(msgs []struct {
+	Role    string `json:"role"`
+	Content string `json:"content"`
+}) (system, user string) {
+	var users []string
+	for _, m := range msgs {
+		switch strings.ToLower(strings.TrimSpace(m.Role)) {
+		case "system":
+			if system == "" {
+				system = m.Content
+			} else {
+				system += "\n" + m.Content
+			}
+		case "user":
+			users = append(users, m.Content)
+		case "assistant":
+			// ignore prior assistant turns in this stub
+		}
+	}
+	return system, strings.Join(users, "\n")
+}
+
+func estimateTokens(s string) int {
+	n := len(strings.Fields(s))
+	if n < 1 && strings.TrimSpace(s) != "" {
+		return 1
+	}
+	return n
+}
+
+func writeJSON(w http.ResponseWriter, status int, v any) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	if err := json.NewEncoder(w).Encode(v); err != nil {
+		log.Printf("encode: %v", err)
+	}
+}

apps/api/cmd/mock-llm/main_test.go

@@ -0,0 +1,169 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/descrybe/descrybe-v2/apps/api/internal/processing"
+)
+
+func testServer(t *testing.T) *httptest.Server {
+	t.Helper()
+	s := &server{apiKey: "local-test", model: "mock-llm"}
+	mux := http.NewServeMux()
+	mux.HandleFunc("/healthz", s.handleHealth)
+	mux.HandleFunc("/v1/models", s.handleModels)
+	mux.HandleFunc("/v1/chat/completions", s.handleChatCompletions)
+	mux.HandleFunc("/v1/embeddings", s.handleEmbeddings)
+	srv := httptest.NewServer(mux)
+	t.Cleanup(srv.Close)
+	return srv
+}
+
+func TestMockLLM_healthAndModels(t *testing.T) {
+	t.Parallel()
+	srv := testServer(t)
+
+	res, err := http.Get(srv.URL + "/healthz")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer res.Body.Close()
+	if res.StatusCode != http.StatusOK {
+		t.Fatalf("health status=%d", res.StatusCode)
+	}
+
+	req, err := http.NewRequest(http.MethodGet, srv.URL+"/v1/models", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	req.Header.Set("Authorization", "Bearer local-test")
+	res2, err := http.DefaultClient.Do(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer res2.Body.Close()
+	if res2.StatusCode != http.StatusOK {
+		t.Fatalf("models status=%d", res2.StatusCode)
+	}
+	var body map[string]any
+	if err := json.NewDecoder(res2.Body).Decode(&body); err != nil {
+		t.Fatal(err)
+	}
+	data, _ := body["data"].([]any)
+	if len(data) < 1 {
+		t.Fatalf("models empty: %#v", body)
+	}
+}
+
+func TestMockLLM_chatCompletionsEnhanceJSON(t *testing.T) {
+	t.Parallel()
+	srv := testServer(t)
+
+	payload := map[string]any{
+		"model": "mock-llm",
+		"messages": []map[string]string{
+			{"role": "system", "content": `Return JSON with "name" and "description" for titles and descriptions.`},
+			{"role": "user", "content": "current name: Red Runner\ncurrent description: A fine shoe.\nattributes:"},
+		},
+		"temperature": 0.2,
+		"max_tokens":  350,
+	}
+	raw, err := json.Marshal(payload)
+	if err != nil {
+		t.Fatal(err)
+	}
+	req, err := http.NewRequest(http.MethodPost, srv.URL+"/v1/chat/completions", bytes.NewReader(raw))
+	if err != nil {
+		t.Fatal(err)
+	}
+	req.Header.Set("Authorization", "Bearer local-test")
+	req.Header.Set("Content-Type", "application/json")
+	res, err := http.DefaultClient.Do(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer res.Body.Close()
+	body, err := io.ReadAll(res.Body)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.StatusCode != http.StatusOK {
+		t.Fatalf("status=%d body=%s", res.StatusCode, body)
+	}
+	var parsed struct {
+		Model   string `json:"model"`
+		Choices []struct {
+			Message struct {
+				Content string `json:"content"`
+			} `json:"message"`
+		} `json:"choices"`
+	}
+	if err := json.Unmarshal(body, &parsed); err != nil {
+		t.Fatal(err)
+	}
+	if parsed.Model != "mock-llm" {
+		t.Fatalf("model=%q", parsed.Model)
+	}
+	if len(parsed.Choices) < 1 {
+		t.Fatal("no choices")
+	}
+	content := parsed.Choices[0].Message.Content
+	var obj map[string]any
+	if err := json.Unmarshal([]byte(content), &obj); err != nil {
+		t.Fatalf("content not JSON: %q err=%v", content, err)
+	}
+	if name, _ := obj["name"].(string); name == "" {
+		t.Fatalf("missing name in %#v", obj)
+	}
+	if desc, _ := obj["description"].(string); desc == "" {
+		t.Fatalf("missing description in %#v", obj)
+	}
+}
+
+func TestMockLLM_OpenAIClientRoundTrip(t *testing.T) {
+	t.Parallel()
+	srv := testServer(t)
+
+	client := processing.NewOpenAIClient("local-test", srv.URL+"/v1", "mock-llm", 0, 1)
+	if !client.Enabled() {
+		t.Fatal("expected Enabled")
+	}
+	comp, err := client.Complete(context.Background(),
+		`Return JSON with "name" and titles and descriptions.`,
+		"current name: Mock Widget\ncurrent description: Tiny fixture.\nattributes:",
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(comp.Text, "name") {
+		t.Fatalf("unexpected text=%q", comp.Text)
+	}
+	if comp.TotalTokens < 1 {
+		t.Fatalf("tokens=%d", comp.TotalTokens)
+	}
+}
+
+func TestMockLLM_rejectsBadAuth(t *testing.T) {
+	t.Parallel()
+	srv := testServer(t)
+	req, err := http.NewRequest(http.MethodGet, srv.URL+"/v1/models", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	req.Header.Set("Authorization", "Bearer wrong")
+	res, err := http.DefaultClient.Do(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer res.Body.Close()
+	if res.StatusCode != http.StatusUnauthorized {
+		t.Fatalf("status=%d", res.StatusCode)
+	}
+}

apps/api/cmd/mock-woo/main.go

@@ -0,0 +1,330 @@
+// Command mock-woo serves minimal WooCommerce REST API v3 fixtures for local
+// live sync proofs (Test Connection, product batch push, orders/reviews pull).
+//
+// Usage:
+//
+//	go run ./cmd/mock-woo -addr 127.0.0.1:19090
+//	go run ./cmd/mock-woo -addr 127.0.0.1:19090 -key ck_mock -secret cs_mock
+package main
+
+import (
+	"encoding/base64"
+	"encoding/json"
+	"flag"
+	"io"
+	"log"
+	"net/http"
+	"os"
+	"strconv"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"time"
+)
+
+const apiPrefix = "/wp-json/wc/v3"
+
+type server struct {
+	key    string
+	secret string
+	mu     sync.Mutex
+	nextID atomic.Int64
+	bySKU  map[string]product
+	logReq atomic.Int64
+}
+
+type product struct {
+	ID   int    `json:"id"`
+	SKU  string `json:"sku"`
+	Name string `json:"name"`
+}
+
+type orderBilling struct {
+	Email     string `json:"email"`
+	FirstName string `json:"first_name"`
+	LastName  string `json:"last_name"`
+}
+
+type orderLine struct {
+	ID        int    `json:"id"`
+	Name      string `json:"name"`
+	ProductID int    `json:"product_id"`
+	Quantity  int    `json:"quantity"`
+	Total     string `json:"total"`
+	SKU       string `json:"sku"`
+	MetaData  []any  `json:"meta_data"`
+}
+
+type order struct {
+	ID             int          `json:"id"`
+	Status         string       `json:"status"`
+	Currency       string       `json:"currency"`
+	Total          string       `json:"total"`
+	CustomerID     int          `json:"customer_id"`
+	DateCreated    string       `json:"date_created"`
+	DateCreatedGMT string       `json:"date_created_gmt"`
+	Billing        orderBilling `json:"billing"`
+	LineItems      []orderLine  `json:"line_items"`
+}
+
+type review struct {
+	ID             int    `json:"id"`
+	ProductID      int    `json:"product_id"`
+	Status         string `json:"status"`
+	Reviewer       string `json:"reviewer"`
+	ReviewerEmail  string `json:"reviewer_email"`
+	Review         string `json:"review"`
+	Rating         int    `json:"rating"`
+	DateCreated    string `json:"date_created"`
+	DateCreatedGMT string `json:"date_created_gmt"`
+	ProductName    string `json:"product_name"`
+}
+
+func main() {
+	addr := flag.String("addr", "127.0.0.1:19090", "listen address")
+	key := flag.String("key", envOr("MOCK_WOO_KEY", "ck_mock_local"), "consumer key")
+	secret := flag.String("secret", envOr("MOCK_WOO_SECRET", "cs_mock_local"), "consumer secret")
+	flag.Parse()
+
+	s := &server{
+		key:    strings.TrimSpace(*key),
+		secret: strings.TrimSpace(*secret),
+		bySKU:  map[string]product{},
+	}
+	s.nextID.Store(1000)
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("/", s.handle)
+	mux.HandleFunc("/healthz", func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"status":"ok","service":"mock-woo"}`))
+	})
+
+	log.Printf("mock-woo listening on http://%s  key=%s", *addr, s.key)
+	log.Printf("WC base: http://%s%s", *addr, apiPrefix)
+	if err := http.ListenAndServe(*addr, mux); err != nil {
+		log.Fatal(err)
+	}
+}
+
+func envOr(k, def string) string {
+	if v := strings.TrimSpace(os.Getenv(k)); v != "" {
+		return v
+	}
+	return def
+}
+
+func (s *server) handle(w http.ResponseWriter, r *http.Request) {
+	s.logReq.Add(1)
+	if !strings.HasPrefix(r.URL.Path, apiPrefix) {
+		http.NotFound(w, r)
+		return
+	}
+	if !s.authOK(r) {
+		w.Header().Set("WWW-Authenticate", `Basic realm="WooCommerce"`)
+		http.Error(w, `{"code":"woocommerce_rest_cannot_view","message":"unauthorized"}`, http.StatusUnauthorized)
+		return
+	}
+	path := strings.TrimPrefix(r.URL.Path, apiPrefix)
+	path = strings.TrimSuffix(path, "/")
+	switch {
+	case r.Method == http.MethodGet && path == "/products":
+		s.handleListProducts(w, r)
+	case r.Method == http.MethodPost && path == "/products/batch":
+		s.handleBatchProducts(w, r)
+	case r.Method == http.MethodGet && path == "/products/categories":
+		s.writeJSON(w, []map[string]any{
+			{"id": 10, "name": "Demo Electronics", "slug": "demo-electronics"},
+			{"id": 11, "name": "Accessories", "slug": "accessories"},
+		})
+	case r.Method == http.MethodGet && path == "/products/attributes":
+		s.writeJSON(w, []map[string]any{
+			{"id": 20, "name": "Color", "slug": "pa_color"},
+			{"id": 21, "name": "Size", "slug": "pa_size"},
+		})
+	case r.Method == http.MethodGet && path == "/orders":
+		s.handleOrders(w, r)
+	case r.Method == http.MethodGet && path == "/products/reviews":
+		s.handleReviews(w, r)
+	default:
+		http.Error(w, `{"code":"rest_no_route","message":"no route"}`, http.StatusNotFound)
+	}
+}
+
+func (s *server) authOK(r *http.Request) bool {
+	h := r.Header.Get("Authorization")
+	if !strings.HasPrefix(h, "Basic ") {
+		return false
+	}
+	raw, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(h, "Basic "))
+	if err != nil {
+		return false
+	}
+	parts := strings.SplitN(string(raw), ":", 2)
+	if len(parts) != 2 {
+		return false
+	}
+	return parts[0] == s.key && parts[1] == s.secret
+}
+
+func (s *server) handleListProducts(w http.ResponseWriter, r *http.Request) {
+	sku := strings.TrimSpace(r.URL.Query().Get("sku"))
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	out := make([]product, 0)
+	if sku != "" {
+		if p, ok := s.bySKU[sku]; ok {
+			out = append(out, p)
+		}
+	} else {
+		for _, p := range s.bySKU {
+			out = append(out, p)
+			if len(out) >= 1 {
+				break
+			}
+		}
+	}
+	s.writeJSON(w, out)
+}
+
+func (s *server) handleBatchProducts(w http.ResponseWriter, r *http.Request) {
+	body, err := io.ReadAll(io.LimitReader(r.Body, 8<<20))
+	if err != nil {
+		http.Error(w, `{"message":"read body"}`, http.StatusBadRequest)
+		return
+	}
+	var req struct {
+		Create []map[string]any `json:"create"`
+		Update []map[string]any `json:"update"`
+	}
+	if err := json.Unmarshal(body, &req); err != nil {
+		http.Error(w, `{"message":"invalid json"}`, http.StatusBadRequest)
+		return
+	}
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	created := make([]product, 0, len(req.Create))
+	updated := make([]product, 0, len(req.Update))
+	for _, item := range req.Create {
+		p := s.upsertFromPayload(item, 0)
+		created = append(created, p)
+	}
+	for _, item := range req.Update {
+		id := intFromAny(item["id"])
+		p := s.upsertFromPayload(item, id)
+		updated = append(updated, p)
+	}
+	s.writeJSON(w, map[string]any{"create": created, "update": updated})
+}
+
+func (s *server) upsertFromPayload(item map[string]any, preferID int) product {
+	sku, _ := item["sku"].(string)
+	name, _ := item["name"].(string)
+	if name == "" {
+		name = "Product"
+	}
+	id := preferID
+	if id <= 0 {
+		if existing, ok := s.bySKU[sku]; ok && sku != "" {
+			id = existing.ID
+		} else {
+			id = int(s.nextID.Add(1))
+		}
+	}
+	p := product{ID: id, SKU: sku, Name: name}
+	if sku != "" {
+		s.bySKU[sku] = p
+	}
+	return p
+}
+
+func (s *server) handleOrders(w http.ResponseWriter, r *http.Request) {
+	page, _ := strconv.Atoi(r.URL.Query().Get("page"))
+	if page <= 0 {
+		page = 1
+	}
+	if page > 1 {
+		s.writeJSON(w, []order{})
+		return
+	}
+	now := time.Now().UTC().Format("2006-01-02T15:04:05")
+	orders := []order{
+		{
+			ID: 5001, Status: "completed", Currency: "EUR", Total: "499.00", CustomerID: 1,
+			DateCreated: now, DateCreatedGMT: now,
+			Billing: orderBilling{Email: "anna.buyer@example.com", FirstName: "Anna", LastName: "Buyer"},
+			LineItems: []orderLine{{
+				ID: 1, Name: "Mock 4K TV", ProductID: 90001, Quantity: 1, Total: "499.00", SKU: "MOCK-WOO-TV",
+				MetaData: []any{map[string]any{"key": "categories", "value": []any{"Demo Electronics"}}},
+			}},
+		},
+		{
+			ID: 5002, Status: "completed", Currency: "EUR", Total: "149.00", CustomerID: 2,
+			DateCreated: now, DateCreatedGMT: now,
+			Billing: orderBilling{Email: "ben.buyer@example.com", FirstName: "Ben", LastName: "Buyer"},
+			LineItems: []orderLine{{
+				ID: 2, Name: "Mock Soundbar", ProductID: 90002, Quantity: 1, Total: "149.00", SKU: "MOCK-WOO-SOUND",
+				MetaData: []any{map[string]any{"key": "categories", "value": []any{"Demo Electronics"}}},
+			}},
+		},
+		{
+			ID: 5003, Status: "processing", Currency: "EUR", Total: "29.00", CustomerID: 3,
+			DateCreated: now, DateCreatedGMT: now,
+			Billing: orderBilling{Email: "cara.buyer@example.com", FirstName: "Cara", LastName: "Buyer"},
+			LineItems: []orderLine{{
+				ID: 3, Name: "Mock Cable", ProductID: 90010, Quantity: 1, Total: "29.00", SKU: "MOCK-WOO-CABLE",
+				MetaData: []any{map[string]any{"key": "categories", "value": []any{"Accessories"}}},
+			}},
+		},
+	}
+	s.writeJSON(w, orders)
+}
+
+func (s *server) handleReviews(w http.ResponseWriter, r *http.Request) {
+	page, _ := strconv.Atoi(r.URL.Query().Get("page"))
+	if page <= 0 {
+		page = 1
+	}
+	if page > 1 {
+		s.writeJSON(w, []review{})
+		return
+	}
+	now := time.Now().UTC().Format("2006-01-02T15:04:05")
+	s.writeJSON(w, []review{
+		{
+			ID: 7001, ProductID: 90001, Status: "approved", Reviewer: "Anna Buyer",
+			ReviewerEmail: "anna.buyer@example.com", Review: "Great mock TV.", Rating: 5,
+			DateCreated: now, DateCreatedGMT: now, ProductName: "Mock 4K TV",
+		},
+		{
+			ID: 7002, ProductID: 90002, Status: "approved", Reviewer: "Ben Buyer",
+			ReviewerEmail: "ben.buyer@example.com", Review: "Solid soundbar for demos.", Rating: 4,
+			DateCreated: now, DateCreatedGMT: now, ProductName: "Mock Soundbar",
+		},
+	})
+}
+
+func (s *server) writeJSON(w http.ResponseWriter, v any) {
+	w.Header().Set("Content-Type", "application/json")
+	enc := json.NewEncoder(w)
+	if err := enc.Encode(v); err != nil {
+		log.Printf("encode: %v", err)
+	}
+}
+
+func intFromAny(v any) int {
+	switch t := v.(type) {
+	case float64:
+		return int(t)
+	case int:
+		return t
+	case json.Number:
+		i, _ := t.Int64()
+		return int(i)
+	case string:
+		i, _ := strconv.Atoi(t)
+		return i
+	default:
+		return 0
+	}
+}

apps/api/cmd/seed-a1-reset-processing/main.go

@@ -0,0 +1,184 @@
+package main
+
+// Command seed-a1-reset-processing returns the A1 Slovenija tenant to a fresh
+// processing state without wiping catalog inputs.
+//
+// Deletes/cancels processing jobs and job-product links, deletes processed_products,
+// and sets all raw_products to unprocessed. Retains feeds, mappings, raw/mapped
+// product payloads, attributes, categories, standard fields, and export feeds.
+//
+// Idempotent and company-scoped. Run AFTER seed-a1 reimport — do not bake into
+// the main seed path.
+//
+// Usage:
+//
+//	go run ./cmd/seed-a1-reset-processing
+//	go run ./cmd/seed-a1-reset-processing -company 604f23a8-b66e-4b21-8b45-0d72b68f4790
+//	go run ./cmd/seed-a1-reset-processing -dry-run
+//
+// DATABASE_URL / -postgres required.
+import (
+	"context"
+	"flag"
+	"fmt"
+	"log"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+const defaultA1CompanyID = "604f23a8-b66e-4b21-8b45-0d72b68f4790"
+
+type counts struct {
+	Raw          int64
+	Processed    int64
+	Unprocessed  int64
+	Jobs         int64
+	JobProducts  int64
+	FeedSyncJobs int64
+}
+
+func main() {
+	postgresURL := flag.String("postgres", os.Getenv("DATABASE_URL"), "Postgres URL (DATABASE_URL)")
+	company := flag.String("company", defaultA1CompanyID, "Postgres companies.id (default A1 Slovenija)")
+	byName := flag.String("name", "", "Resolve company by name (e.g. \"A1 Slovenija\") when -company omitted/wrong")
+	dryRun := flag.Bool("dry-run", false, "print before counts only; do not mutate")
+	flag.Parse()
+
+	if strings.TrimSpace(*postgresURL) == "" {
+		log.Fatal("-postgres / DATABASE_URL is required")
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Minute)
+	defer cancel()
+
+	pg, err := pgxpool.New(ctx, *postgresURL)
+	if err != nil {
+		log.Fatalf("postgres: %v", err)
+	}
+	defer pg.Close()
+
+	companyID, err := resolveCompany(ctx, pg, *company, *byName)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	before, err := loadCounts(ctx, pg, companyID)
+	if err != nil {
+		log.Fatalf("counts: %v", err)
+	}
+	log.Printf("company %s before: raw=%d processed=%d unprocessed=%d jobs=%d job_products=%d feed_sync_jobs=%d",
+		companyID, before.Raw, before.Processed, before.Unprocessed, before.Jobs, before.JobProducts, before.FeedSyncJobs)
+
+	if *dryRun {
+		log.Printf("dry-run: no changes")
+		return
+	}
+
+	if err := resetProcessing(ctx, pg, companyID); err != nil {
+		log.Fatalf("reset: %v", err)
+	}
+
+	after, err := loadCounts(ctx, pg, companyID)
+	if err != nil {
+		log.Fatalf("counts after: %v", err)
+	}
+	log.Printf("company %s after:  raw=%d processed=%d unprocessed=%d jobs=%d job_products=%d feed_sync_jobs=%d",
+		companyID, after.Raw, after.Processed, after.Unprocessed, after.Jobs, after.JobProducts, after.FeedSyncJobs)
+	if after.Processed != 0 || after.Jobs != 0 || after.JobProducts != 0 {
+		log.Fatalf("expected processed=0 jobs=0 job_products=0; got processed=%d jobs=%d job_products=%d",
+			after.Processed, after.Jobs, after.JobProducts)
+	}
+	if after.Raw != before.Raw {
+		log.Fatalf("raw catalog changed (%d → %d) — abort expectation failed", before.Raw, after.Raw)
+	}
+	if after.Unprocessed != after.Raw {
+		log.Fatalf("expected all raw unprocessed (%d), got %d", after.Raw, after.Unprocessed)
+	}
+	log.Printf("ok: catalog retained, processing state cleared")
+}
+
+func resolveCompany(ctx context.Context, pg *pgxpool.Pool, companyFlag, nameFlag string) (uuid.UUID, error) {
+	nameFlag = strings.TrimSpace(nameFlag)
+	if nameFlag != "" {
+		var id uuid.UUID
+		err := pg.QueryRow(ctx, `
+			SELECT id FROM companies
+			WHERE lower(name) = lower($1)
+			ORDER BY created_at ASC LIMIT 1`, nameFlag).Scan(&id)
+		if err != nil {
+			return uuid.Nil, fmt.Errorf("resolve -name %q: %w", nameFlag, err)
+		}
+		return id, nil
+	}
+	id, err := uuid.Parse(strings.TrimSpace(companyFlag))
+	if err != nil {
+		return uuid.Nil, fmt.Errorf("-company: %w", err)
+	}
+	var name string
+	err = pg.QueryRow(ctx, `SELECT name FROM companies WHERE id = $1`, id).Scan(&name)
+	if err != nil {
+		return uuid.Nil, fmt.Errorf("company %s not found: %w", id, err)
+	}
+	log.Printf("resolved company %s (%s)", id, name)
+	return id, nil
+}
+
+func loadCounts(ctx context.Context, pg *pgxpool.Pool, companyID uuid.UUID) (counts, error) {
+	var c counts
+	err := pg.QueryRow(ctx, `
+		SELECT
+			(SELECT count(*) FROM raw_products WHERE company_id = $1),
+			(SELECT count(*) FROM processed_products WHERE company_id = $1),
+			(SELECT count(*) FROM raw_products WHERE company_id = $1 AND processing_status = 'unprocessed' AND is_processed = false),
+			(SELECT count(*) FROM processing_jobs WHERE company_id = $1),
+			(SELECT count(*) FROM processing_job_products pjp
+				JOIN processing_jobs pj ON pj.id = pjp.job_id WHERE pj.company_id = $1),
+			(SELECT count(*) FROM feed_sync_jobs WHERE company_id = $1)
+	`, companyID).Scan(&c.Raw, &c.Processed, &c.Unprocessed, &c.Jobs, &c.JobProducts, &c.FeedSyncJobs)
+	return c, err
+}
+
+func resetProcessing(ctx context.Context, pg *pgxpool.Pool, companyID uuid.UUID) error {
+	tx, err := pg.Begin(ctx)
+	if err != nil {
+		return err
+	}
+	defer tx.Rollback(ctx)
+
+	// Job products before jobs (FK).
+	if _, err := tx.Exec(ctx, `
+		DELETE FROM processing_job_products
+		WHERE job_id IN (SELECT id FROM processing_jobs WHERE company_id = $1)`, companyID); err != nil {
+		return fmt.Errorf("delete job products: %w", err)
+	}
+	if _, err := tx.Exec(ctx, `
+		DELETE FROM processing_jobs WHERE company_id = $1`, companyID); err != nil {
+		return fmt.Errorf("delete jobs: %w", err)
+	}
+	// Ephemeral sync job rows (optional clutter); raw.sync_job_id SET NULL on delete.
+	if _, err := tx.Exec(ctx, `
+		DELETE FROM feed_sync_jobs WHERE company_id = $1`, companyID); err != nil {
+		return fmt.Errorf("delete feed sync jobs: %w", err)
+	}
+	if _, err := tx.Exec(ctx, `
+		DELETE FROM processed_products WHERE company_id = $1`, companyID); err != nil {
+		return fmt.Errorf("delete processed: %w", err)
+	}
+	ct, err := tx.Exec(ctx, `
+		UPDATE raw_products
+		SET is_processed = false,
+			processing_status = 'unprocessed',
+			updated_at = now()
+		WHERE company_id = $1
+		  AND (is_processed = true OR processing_status <> 'unprocessed')`, companyID)
+	if err != nil {
+		return fmt.Errorf("reset raw: %w", err)
+	}
+	log.Printf("raw rows reset to unprocessed: %d", ct.RowsAffected())
+
+	return tx.Commit(ctx)
+}

apps/api/cmd/seed-a1/category_backfill.go

@@ -0,0 +1,262 @@
+package main
+
+import (
+	"bufio"
+	"context"
+	"fmt"
+	"io"
+	"log"
+	"os"
+	"strings"
+
+	"github.com/descrybe/descrybe-v2/apps/api/internal/billing"
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// Classic A1 Postman / Elkotex fixture EANs — must never live on Platform Demo.
+var a1FixtureEANs = []string{
+	"5905575903198",
+	"6970995789942",
+}
+
+type categoryBackfillResult struct {
+	ProcessedUpdated    int64
+	ProcessedInserted   int64
+	MappedUpdated       int64
+	DumpPairs           int
+	PurgedOtherRaw      int64
+	PurgedOtherPP       int64
+	ProcessedWithCat    int
+	ProcessedWithoutCat int
+	MappedWithCat       int
+	MappedWithoutCat    int
+}
+
+// backfillMappedCategoriesFromProcessed copies processed_products.category into
+// raw_products.mapped_data.category for A1 only. Legacy dumps store category on
+// processed rows (unique_id codes); feed mappings never mapped a category field,
+// so re-processing without this backfill yields Uncategorized / grey C coverage.
+func backfillMappedCategoriesFromProcessed(ctx context.Context, pg *pgxpool.Pool, companyID uuid.UUID) (int64, error) {
+	ct, err := pg.Exec(ctx, `
+		UPDATE raw_products r
+		SET mapped_data = jsonb_set(
+			COALESCE(r.mapped_data, '{}'::jsonb),
+			'{category}',
+			to_jsonb(p.category),
+			true
+		),
+		updated_at = now()
+		FROM processed_products p
+		WHERE p.raw_product_id = r.id
+		  AND p.company_id = $1
+		  AND r.company_id = $1
+		  AND COALESCE(NULLIF(trim(p.category), ''), '') <> ''
+		  AND lower(trim(p.category)) <> 'none'
+		  AND COALESCE(NULLIF(trim(r.mapped_data->>'category'), ''), '') = ''`, companyID)
+	if err != nil {
+		return 0, fmt.Errorf("backfill mapped category: %w", err)
+	}
+	return ct.RowsAffected(), nil
+}
+
+// backfillCategoriesFromMySQLDump streams dump processed_products for the A1
+// legacy company and writes product_id (GTIN) → category onto A1 Postgres
+// mapped_data.category (and updates any existing processed_products.category).
+// It does not insert processed rows — A1 demo seed stays at processed=0.
+func backfillCategoriesFromMySQLDump(ctx context.Context, pg *pgxpool.Pool, companyID uuid.UUID, dumpPath string) (categoryBackfillResult, error) {
+	var out categoryBackfillResult
+	legacyCompany := billing.A1LegacyCompanyID
+	var legacy string
+	_ = pg.QueryRow(ctx, `SELECT COALESCE(legacy_company_id::text, '') FROM companies WHERE id = $1`, companyID).Scan(&legacy)
+	if legacy != "" {
+		legacyCompany = legacy
+	}
+
+	f, err := os.Open(dumpPath)
+	if err != nil {
+		return out, fmt.Errorf("open mysql dump: %w", err)
+	}
+	defer f.Close()
+
+	byGTIN, err := scanA1ProcessedCategories(f, legacyCompany)
+	if err != nil {
+		return out, err
+	}
+	out.DumpPairs = len(byGTIN)
+	if len(byGTIN) == 0 {
+		return out, fmt.Errorf("no A1 processed_products categories for legacy %s in dump", legacyCompany)
+	}
+	log.Printf("dump: %d A1 gtin→category pairs", len(byGTIN))
+
+	gtins := make([]string, 0, len(byGTIN))
+	cats := make([]string, 0, len(byGTIN))
+	for g, c := range byGTIN {
+		gtins = append(gtins, g)
+		cats = append(cats, c)
+	}
+
+	ct, err := pg.Exec(ctx, `
+		UPDATE processed_products p
+		SET category = v.category,
+			updated_at = now()
+		FROM unnest($2::text[], $3::text[]) AS v(gtin, category)
+		WHERE p.company_id = $1
+		  AND p.product_id = v.gtin
+		  AND COALESCE(NULLIF(trim(v.category), ''), '') <> ''
+		  AND (
+			COALESCE(NULLIF(trim(p.category), ''), '') = ''
+			OR lower(trim(p.category)) = 'none'
+			OR p.category IS DISTINCT FROM v.category
+		  )`, companyID, gtins, cats)
+	if err != nil {
+		return out, fmt.Errorf("update processed category from dump: %w", err)
+	}
+	out.ProcessedUpdated = ct.RowsAffected()
+
+	// A1 demo seed keeps processed=0. Do not INSERT processed rows from the dump —
+	// only refresh mapped_data.category (and any existing processed rows if present).
+	ct, err = pg.Exec(ctx, `
+		UPDATE raw_products r
+		SET mapped_data = jsonb_set(
+			COALESCE(r.mapped_data, '{}'::jsonb),
+			'{category}',
+			to_jsonb(v.category),
+			true
+		),
+		updated_at = now()
+		FROM unnest($2::text[], $3::text[]) AS v(gtin, category)
+		WHERE r.company_id = $1
+			AND r.gtin = v.gtin
+			AND COALESCE(NULLIF(trim(v.category), ''), '') <> ''
+			AND (
+				COALESCE(NULLIF(trim(r.mapped_data->>'category'), ''), '') = ''
+				OR r.mapped_data->>'category' IS DISTINCT FROM v.category
+			)`, companyID, gtins, cats)
+	if err != nil {
+		return out, fmt.Errorf("update mapped category from dump: %w", err)
+	}
+	out.MappedUpdated = ct.RowsAffected()
+
+	n, err := backfillMappedCategoriesFromProcessed(ctx, pg, companyID)
+	if err != nil {
+		return out, err
+	}
+	out.MappedUpdated += n
+	if err := fillCategoryCoverage(ctx, pg, companyID, &out); err != nil {
+		return out, err
+	}
+	return out, nil
+}
+
+func fillCategoryCoverage(ctx context.Context, pg *pgxpool.Pool, companyID uuid.UUID, out *categoryBackfillResult) error {
+	err := pg.QueryRow(ctx, `
+		SELECT
+			COUNT(*) FILTER (
+				WHERE COALESCE(NULLIF(trim(category), ''), '') <> ''
+					AND lower(trim(category)) <> 'none'
+			),
+			COUNT(*) FILTER (
+				WHERE COALESCE(NULLIF(trim(category), ''), '') = ''
+					OR lower(trim(category)) = 'none'
+			)
+		FROM processed_products
+		WHERE company_id = $1`, companyID).Scan(&out.ProcessedWithCat, &out.ProcessedWithoutCat)
+	if err != nil {
+		return fmt.Errorf("count processed categories: %w", err)
+	}
+	err = pg.QueryRow(ctx, `
+		SELECT
+			COUNT(*) FILTER (
+				WHERE COALESCE(NULLIF(trim(mapped_data->>'category'), ''), '') <> ''
+			),
+			COUNT(*) FILTER (
+				WHERE COALESCE(NULLIF(trim(mapped_data->>'category'), ''), '') = ''
+			)
+		FROM raw_products
+		WHERE company_id = $1`, companyID).Scan(&out.MappedWithCat, &out.MappedWithoutCat)
+	if err != nil {
+		return fmt.Errorf("count mapped categories: %w", err)
+	}
+	return nil
+}
+
+// purgeA1FixtureEANsFromOtherTenants deletes the Postman Elkotex fixture EANs
+// from every company except A1 (Platform Demo must not mirror A1 fixtures).
+func purgeA1FixtureEANsFromOtherTenants(ctx context.Context, pg *pgxpool.Pool, a1CompanyID uuid.UUID) (rawN, ppN int64, err error) {
+	ct, err := pg.Exec(ctx, `
+		DELETE FROM processing_job_products pjp
+		WHERE pjp.raw_product_id IN (
+			SELECT id FROM raw_products
+			WHERE company_id <> $1 AND gtin = ANY($2::text[])
+		)
+		OR pjp.processed_product_id IN (
+			SELECT id FROM processed_products
+			WHERE company_id <> $1 AND product_id = ANY($2::text[])
+		)`, a1CompanyID, a1FixtureEANs)
+	if err != nil {
+		return 0, 0, fmt.Errorf("purge fixture job products: %w", err)
+	}
+	_ = ct
+
+	ct, err = pg.Exec(ctx, `
+		DELETE FROM processed_products
+		WHERE company_id <> $1 AND product_id = ANY($2::text[])`, a1CompanyID, a1FixtureEANs)
+	if err != nil {
+		return 0, 0, fmt.Errorf("purge fixture processed: %w", err)
+	}
+	ppN = ct.RowsAffected()
+
+	ct, err = pg.Exec(ctx, `
+		DELETE FROM raw_products
+		WHERE company_id <> $1 AND gtin = ANY($2::text[])`, a1CompanyID, a1FixtureEANs)
+	if err != nil {
+		return 0, 0, fmt.Errorf("purge fixture raw: %w", err)
+	}
+	rawN = ct.RowsAffected()
+	return rawN, ppN, nil
+}
+
+func scanA1ProcessedCategories(r io.Reader, legacyCompany string) (map[string]string, error) {
+	br := bufio.NewReaderSize(r, 1<<20)
+	inTable := false
+	out := make(map[string]string, 4096)
+	for {
+		line, err := br.ReadString('\n')
+		if len(line) > 0 {
+			trimmed := strings.TrimSpace(line)
+			if strings.HasPrefix(trimmed, "INSERT INTO `processed_products`") ||
+				strings.HasPrefix(trimmed, "INSERT INTO processed_products") {
+				inTable = true
+			} else if inTable && strings.HasPrefix(trimmed, "CREATE TABLE") {
+				break
+			} else if inTable && strings.HasPrefix(trimmed, "INSERT INTO `") &&
+				!strings.Contains(trimmed, "processed_products") {
+				break
+			} else if inTable && looksLikeTupleLine(line) && strings.Contains(line, legacyCompany) {
+				fields := parseMySQLTupleFieldsN(line, 6)
+				if len(fields) >= 5 {
+					gtin := strings.TrimSpace(fields[2])
+					cat := strings.TrimSpace(fields[4])
+					if gtin != "" && cat != "" && !strings.EqualFold(cat, "NULL") {
+						out[gtin] = cat
+					}
+				}
+			}
+		}
+		if err == io.EOF {
+			break
+		}
+		if err != nil {
+			return nil, err
+		}
+	}
+	return out, nil
+}
+
+func logCategoryBackfillResult(res categoryBackfillResult, source string) {
+	log.Printf("category backfill (%s): dump_pairs=%d processed_updated=%d processed_inserted=%d mapped_updated=%d purged_other_raw=%d purged_other_pp=%d",
+		source, res.DumpPairs, res.ProcessedUpdated, res.ProcessedInserted, res.MappedUpdated, res.PurgedOtherRaw, res.PurgedOtherPP)
+	log.Printf("A1 coverage: processed with_cat=%d without_cat=%d | raw mapped with_cat=%d without_cat=%d",
+		res.ProcessedWithCat, res.ProcessedWithoutCat, res.MappedWithCat, res.MappedWithoutCat)
+}

apps/api/cmd/seed-a1/category_backfill_test.go

@@ -0,0 +1,50 @@
+package main
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestScanA1ProcessedCategories(t *testing.T) {
+	const legacy = "97e1a309-3d23-4aa2-b518-8e8d7afdfec7"
+	dump := strings.Join([]string{
+		"INSERT INTO `processed_products` (`id`, `user_id`, `product_id`, `name`, `category`, `description`, `processed_description`, `attributes`, `processed_attributes`, `status`, `gpt_response`, `total_tokens`, `created_at`, `updated_at`, `feed_id`, `company_id`, `raw_product_id`) VALUES",
+		"(1,\t'user_x',\t'6970995789942',\t'Roborock',\t'46',\tNULL,\tNULL,\tNULL,\tNULL,\t'completed',\tNULL,\t0,\t'2026-01-01 00:00:00',\t'2026-01-01 00:00:00',\t41,\t'" + legacy + "',\t1),",
+		"(2,\t'user_x',\t'5905575903198',\t'Adler',\t'120',\tNULL,\tNULL,\tNULL,\tNULL,\t'completed',\tNULL,\t0,\t'2026-01-01 00:00:00',\t'2026-01-01 00:00:00',\t41,\t'" + legacy + "',\t2),",
+		"(3,\t'user_y',\t'111',\t'Other',\t'999',\tNULL,\tNULL,\tNULL,\tNULL,\t'completed',\tNULL,\t0,\t'2026-01-01 00:00:00',\t'2026-01-01 00:00:00',\t1,\t'other-company',\t3);",
+		"CREATE TABLE `processing_job_products` (",
+	}, "\n")
+
+	got, err := scanA1ProcessedCategories(strings.NewReader(dump), legacy)
+	if err != nil {
+		t.Fatalf("scan: %v", err)
+	}
+	if got["6970995789942"] != "46" {
+		t.Fatalf("roborock category=%q want 46", got["6970995789942"])
+	}
+	if got["5905575903198"] != "120" {
+		t.Fatalf("adler category=%q want 120", got["5905575903198"])
+	}
+	if _, ok := got["111"]; ok {
+		t.Fatalf("other-company product leaked into A1 map")
+	}
+	if len(got) != 2 {
+		t.Fatalf("len=%d want 2", len(got))
+	}
+}
+
+func TestA1FixtureEANs(t *testing.T) {
+	if len(a1FixtureEANs) != 2 {
+		t.Fatalf("fixture EANs=%d want 2", len(a1FixtureEANs))
+	}
+	seen := map[string]bool{}
+	for _, e := range a1FixtureEANs {
+		if e == "" || seen[e] {
+			t.Fatalf("bad fixture EAN %q", e)
+		}
+		seen[e] = true
+	}
+	if !seen["6970995789942"] || !seen["5905575903198"] {
+		t.Fatalf("missing Postman fixture EANs: %#v", a1FixtureEANs)
+	}
+}

apps/api/cmd/seed-a1/category_prompts.go

@@ -0,0 +1,237 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"log"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+	"unicode"
+
+	"github.com/descrybe/descrybe-v2/apps/api/internal/security"
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// MaxCategoryPromptRunes bounds stored category.prompt (aligned with campaign prompts).
+const MaxCategoryPromptRunes = security.MaxCampaignPromptRunes
+
+// categoryPromptsFile is the committed A1 overlay of legacy Name → Prompt pairs.
+type categoryPromptsFile struct {
+	Version int                   `json:"version"`
+	Source  string                `json:"source"`
+	Entries []categoryPromptEntry `json:"entries"`
+}
+
+type categoryPromptEntry struct {
+	Name   string `json:"name"`
+	Prompt string `json:"prompt"`
+}
+
+var (
+	// Legacy v1 placeholders → v2 {{variables}} used by aiprompts.Render.
+	reLegacyDesc = regexp.MustCompile(`(?i)\{\s*""?\s*OPIS\s+IZDELKA\s*""?\s*\}`)
+	reLegacyName = regexp.MustCompile(`(?i)\{\s*""?\s*STARO\s+IME\s+IZDELKA\s*""?\s*\}`)
+)
+
+func defaultCategoryPromptsPath(archivePath string) string {
+	if strings.TrimSpace(archivePath) != "" {
+		return filepath.Join(filepath.Dir(archivePath), "a1-category-prompts.json")
+	}
+	return filepath.Join("..", "..", "scripts", "seed", "a1-category-prompts.json")
+}
+
+func loadCategoryPromptsFile(path string) (categoryPromptsFile, error) {
+	path = filepath.Clean(strings.TrimSpace(path))
+	if path == "" || path == "." {
+		return categoryPromptsFile{}, fmt.Errorf("category prompts path is empty")
+	}
+	// Allowlist the committed seed filename (blocks accidental reads of unrelated dumps).
+	if filepath.Base(path) != "a1-category-prompts.json" {
+		return categoryPromptsFile{}, fmt.Errorf("refusing unexpected category prompts file name %q", filepath.Base(path))
+	}
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return categoryPromptsFile{}, fmt.Errorf("read category prompts: %w", err)
+	}
+	if len(raw) > 8<<20 {
+		return categoryPromptsFile{}, fmt.Errorf("category prompts file too large (%d bytes)", len(raw))
+	}
+	var f categoryPromptsFile
+	if err := json.Unmarshal(raw, &f); err != nil {
+		return categoryPromptsFile{}, fmt.Errorf("parse category prompts JSON: %w", err)
+	}
+	if len(f.Entries) == 0 {
+		return categoryPromptsFile{}, fmt.Errorf("category prompts file has no entries")
+	}
+	if len(f.Entries) > 5000 {
+		return categoryPromptsFile{}, fmt.Errorf("category prompts file has too many entries (%d)", len(f.Entries))
+	}
+	return f, nil
+}
+
+// modernizeLegacyPromptPlaceholders rewrites v1 {""OPIS IZDELKA""} tokens to {{description}} / {{name}}.
+func modernizeLegacyPromptPlaceholders(prompt string) string {
+	prompt = reLegacyDesc.ReplaceAllString(prompt, "{{description}}")
+	prompt = reLegacyName.ReplaceAllString(prompt, "{{name}}")
+	return prompt
+}
+
+func prepareCategoryPrompt(prompt string) string {
+	prompt = modernizeLegacyPromptPlaceholders(prompt)
+	return security.SanitizePrompt(prompt, MaxCategoryPromptRunes)
+}
+
+// normalizeCategoryName keys categories for matching (case/space/diacritic tolerant).
+func normalizeCategoryName(s string) string {
+	s = strings.TrimSpace(s)
+	if s == "" {
+		return ""
+	}
+	s = strings.ToLower(s)
+	var b strings.Builder
+	b.Grow(len(s))
+	prevSpace := false
+	for _, r := range s {
+		r = foldSloveneRune(r)
+		if unicode.IsSpace(r) {
+			if prevSpace || b.Len() == 0 {
+				continue
+			}
+			b.WriteByte(' ')
+			prevSpace = true
+			continue
+		}
+		prevSpace = false
+		if unicode.IsLetter(r) || unicode.IsDigit(r) || r == '-' || r == '/' || r == '&' || r == '+' {
+			b.WriteRune(r)
+			continue
+		}
+		// Drop punctuation noise from names.
+	}
+	return strings.TrimSpace(b.String())
+}
+
+func foldSloveneRune(r rune) rune {
+	switch r {
+	case 'č', 'ć':
+		return 'c'
+	case 'š':
+		return 's'
+	case 'ž':
+		return 'z'
+	case 'đ':
+		return 'd'
+	default:
+		return r
+	}
+}
+
+type categoryPromptApplyResult struct {
+	Updated   int
+	Unmatched []string
+	Skipped   int // empty prompt after sanitize
+}
+
+func applyCategoryPrompts(ctx context.Context, pg *pgxpool.Pool, companyID uuid.UUID, promptsPath string) (categoryPromptApplyResult, error) {
+	var out categoryPromptApplyResult
+	file, err := loadCategoryPromptsFile(promptsPath)
+	if err != nil {
+		return out, err
+	}
+
+	byNorm := make(map[string]string, len(file.Entries))
+	for _, e := range file.Entries {
+		name := strings.TrimSpace(e.Name)
+		prompt := prepareCategoryPrompt(e.Prompt)
+		if name == "" || prompt == "" {
+			out.Skipped++
+			continue
+		}
+		key := normalizeCategoryName(name)
+		if key == "" {
+			out.Skipped++
+			continue
+		}
+		byNorm[key] = prompt
+	}
+	if len(byNorm) == 0 {
+		return out, fmt.Errorf("no usable category prompts in %s", promptsPath)
+	}
+
+	rows, err := pg.Query(ctx, `
+		SELECT id, name
+		FROM categories
+		WHERE company_id = $1`, companyID)
+	if err != nil {
+		return out, fmt.Errorf("list categories: %w", err)
+	}
+	defer rows.Close()
+
+	ids := make([]uuid.UUID, 0, len(byNorm))
+	prompts := make([]string, 0, len(byNorm))
+	matchedKeys := make(map[string]struct{}, len(byNorm))
+
+	for rows.Next() {
+		var id uuid.UUID
+		var name string
+		if err := rows.Scan(&id, &name); err != nil {
+			return out, err
+		}
+		key := normalizeCategoryName(name)
+		prompt, ok := byNorm[key]
+		if !ok {
+			continue
+		}
+		matchedKeys[key] = struct{}{}
+		ids = append(ids, id)
+		prompts = append(prompts, prompt)
+	}
+	if err := rows.Err(); err != nil {
+		return out, err
+	}
+
+	for key := range byNorm {
+		if _, ok := matchedKeys[key]; !ok {
+			out.Unmatched = append(out.Unmatched, key)
+		}
+	}
+	sort.Strings(out.Unmatched)
+
+	if len(ids) == 0 {
+		return out, fmt.Errorf("no A1 categories matched any of %d seed prompts (check names)", len(byNorm))
+	}
+
+	// Single parameterized batch update — company_id gate prevents cross-tenant writes.
+	// ASSUMPTION: A1 seed company content language is Slovenian ("sl").
+	tag, err := pg.Exec(ctx, `
+		UPDATE categories AS c
+		SET prompt = jsonb_build_object('sl', v.prompt), updated_at = now()
+		FROM (
+			SELECT * FROM unnest($1::uuid[], $2::text[]) AS t(id, prompt)
+		) AS v
+		WHERE c.id = v.id AND c.company_id = $3`, ids, prompts, companyID)
+	if err != nil {
+		return out, fmt.Errorf("update category prompts: %w", err)
+	}
+	out.Updated = int(tag.RowsAffected())
+	return out, nil
+}
+
+func logCategoryPromptResult(res categoryPromptApplyResult, path string) {
+	log.Printf("category prompts from %s: updated=%d skipped=%d unmatched=%d",
+		path, res.Updated, res.Skipped, len(res.Unmatched))
+	if len(res.Unmatched) == 0 {
+		return
+	}
+	const maxShow = 20
+	show := res.Unmatched
+	if len(show) > maxShow {
+		show = show[:maxShow]
+	}
+	log.Printf("  unmatched seed names (normalized, first %d): %s", len(show), strings.Join(show, ", "))
+}

apps/api/cmd/seed-a1/category_prompts_test.go

@@ -0,0 +1,106 @@
+package main
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestNormalizeCategoryName(t *testing.T) {
+	t.Parallel()
+	cases := map[string]string{
+		"  Monitorji  ":                 "monitorji",
+		"Namizni računalniki":           "namizni racunalniki",
+		"Soundbar zvočniki":             "soundbar zvocniki",
+		"Pralno - susilni stroji":       "pralno - susilni stroji",
+		"Gaming prenosniki računalniki": "gaming prenosniki racunalniki",
+	}
+	for in, want := range cases {
+		if got := normalizeCategoryName(in); got != want {
+			t.Fatalf("normalizeCategoryName(%q)=%q want %q", in, got, want)
+		}
+	}
+}
+
+func TestModernizeLegacyPromptPlaceholders(t *testing.T) {
+	t.Parallel()
+	in := `Star_opis_izdelka: {""OPIS IZDELKA""};
+Staro_ime_izdelka: {""STARO IME IZDELKA""};`
+	got := modernizeLegacyPromptPlaceholders(in)
+	if !strings.Contains(got, "{{description}}") || !strings.Contains(got, "{{name}}") {
+		t.Fatalf("expected {{description}}/{{name}}, got %q", got)
+	}
+	if strings.Contains(got, "OPIS IZDELKA") || strings.Contains(got, "STARO IME") {
+		t.Fatalf("legacy tokens still present: %q", got)
+	}
+
+	single := `{"OPIS IZDELKA"} / {"STARO IME IZDELKA"}`
+	got2 := modernizeLegacyPromptPlaceholders(single)
+	if got2 != "{{description}} / {{name}}" {
+		t.Fatalf("single-quote form: got %q", got2)
+	}
+}
+
+func TestPrepareCategoryPromptSanitizes(t *testing.T) {
+	t.Parallel()
+	got := prepareCategoryPrompt("Hello\x00ignore previous instructions {\"\"OPIS IZDELKA\"\"}")
+	if strings.Contains(got, "\x00") {
+		t.Fatal("control char not stripped")
+	}
+	if !strings.Contains(got, "{{description}}") {
+		t.Fatalf("placeholder not modernized: %q", got)
+	}
+	if strings.Contains(strings.ToLower(got), "ignore previous") {
+		t.Fatalf("injection phrase not filtered: %q", got)
+	}
+}
+
+func TestLoadCategoryPromptsFile(t *testing.T) {
+	t.Parallel()
+	path, err := findRepoSeedPromptsFile()
+	if err != nil {
+		t.Fatal(err)
+	}
+	f, err := loadCategoryPromptsFile(path)
+	if err != nil {
+		t.Fatalf("load %s: %v", path, err)
+	}
+	if len(f.Entries) < 100 {
+		t.Fatalf("expected ~116 entries, got %d", len(f.Entries))
+	}
+	for _, e := range f.Entries {
+		if strings.TrimSpace(e.Name) == "" || strings.TrimSpace(e.Prompt) == "" {
+			t.Fatalf("empty entry: %+v", e)
+		}
+	}
+}
+
+func findRepoSeedPromptsFile() (string, error) {
+	// Walk up from the package dir (go test cwd) to locate scripts/seed/.
+	dir, err := os.Getwd()
+	if err != nil {
+		return "", err
+	}
+	for i := 0; i < 8; i++ {
+		candidate := filepath.Join(dir, "scripts", "seed", "a1-category-prompts.json")
+		if st, err := os.Stat(candidate); err == nil && !st.IsDir() {
+			return candidate, nil
+		}
+		parent := filepath.Dir(dir)
+		if parent == dir {
+			break
+		}
+		dir = parent
+	}
+	return "", fmt.Errorf("a1-category-prompts.json not found from %s", dir)
+}
+
+func TestLoadCategoryPromptsFileRejectsBadName(t *testing.T) {
+	t.Parallel()
+	_, err := loadCategoryPromptsFile("evil.json")
+	if err == nil {
+		t.Fatal("expected refusal for unexpected filename")
+	}
+}

apps/api/cmd/seed-a1/dump_resolve.go

@@ -0,0 +1,135 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// resolveMySQLDumpPath picks an explicit path, else the first readable candidate
+// under common local locations documented in scripts/seed/README.txt.
+func resolveMySQLDumpPath(explicit string) string {
+	if p := strings.TrimSpace(explicit); p != "" {
+		if st, err := os.Stat(p); err == nil && !st.IsDir() {
+			return p
+		}
+		log.Printf("warning: mysql dump not found at %q — trying auto-detect", p)
+	}
+	for _, c := range mysqlDumpCandidates() {
+		if strings.TrimSpace(explicit) != "" && filepath.Clean(c) == filepath.Clean(strings.TrimSpace(explicit)) {
+			continue
+		}
+		if st, err := os.Stat(c); err == nil && !st.IsDir() {
+			return c
+		}
+	}
+	return ""
+}
+
+func mysqlDumpCandidates() []string {
+	var out []string
+	if v := strings.TrimSpace(os.Getenv("SEED_A1_MYSQL_DUMP")); v != "" {
+		out = append(out, v)
+	}
+	home, _ := os.UserHomeDir()
+	names := []string{
+		"descrybe_new (1).sql",
+		"descrybe_new.sql",
+		"descrybe_new(1).sql",
+	}
+	if home != "" {
+		for _, n := range names {
+			out = append(out, filepath.Join(home, "Downloads", n))
+			out = append(out, filepath.Join(home, "downloads", n))
+		}
+	}
+	// Repo-relative guesses (cwd may be apps/api or repo root).
+	for _, n := range names {
+		out = append(out,
+			n,
+			filepath.Join("..", "..", n),
+			filepath.Join("scripts", "seed", n),
+			filepath.Join("..", "..", "scripts", "seed", n),
+		)
+	}
+	return out
+}
+
+type mappedCoverage struct {
+	Total      int
+	WithDesc   int
+	WithCat    int
+	WithAttrs  int
+	Processed  int
+	Jobs       int
+}
+
+func (c mappedCoverage) pct(n int) float64 {
+	if c.Total == 0 {
+		return 0
+	}
+	return 100 * float64(n) / float64(c.Total)
+}
+
+// feedAttrsSQL matches catalog.processedHasFeedAttributesSQL (mapped_data aliases).
+const feedAttrsSQL = `(
+	CASE jsonb_typeof(mapped_data->'specifications')
+		WHEN 'string' THEN length(trim(mapped_data->>'specifications')) > 0
+		WHEN 'object' THEN mapped_data->'specifications' <> '{}'::jsonb
+		WHEN 'array' THEN jsonb_array_length(mapped_data->'specifications') > 0
+		ELSE false
+	END
+	OR CASE jsonb_typeof(mapped_data->'specs')
+		WHEN 'string' THEN length(trim(mapped_data->>'specs')) > 0
+		WHEN 'object' THEN mapped_data->'specs' <> '{}'::jsonb
+		WHEN 'array' THEN jsonb_array_length(mapped_data->'specs') > 0
+		ELSE false
+	END
+	OR COALESCE(NULLIF(trim(mapped_data->>'eprel_id'), ''), '') <> ''
+	OR COALESCE(NULLIF(trim(mapped_data->>'eprel'), ''), '') <> ''
+	OR COALESCE(NULLIF(trim(mapped_data->>'netwidth'), ''), '') <> ''
+	OR COALESCE(NULLIF(trim(mapped_data->>'net_width'), ''), '') <> ''
+	OR COALESCE(NULLIF(trim(mapped_data->>'netheight'), ''), '') <> ''
+	OR COALESCE(NULLIF(trim(mapped_data->>'net_height'), ''), '') <> ''
+	OR COALESCE(NULLIF(trim(mapped_data->>'netdepth'), ''), '') <> ''
+	OR COALESCE(NULLIF(trim(mapped_data->>'net_depth'), ''), '') <> ''
+	OR COALESCE(NULLIF(trim(mapped_data->>'netmass'), ''), '') <> ''
+	OR COALESCE(NULLIF(trim(mapped_data->>'net_mass'), ''), '') <> ''
+	OR COALESCE(NULLIF(trim(mapped_data->>'warranty'), ''), '') <> ''
+	OR COALESCE(NULLIF(trim(mapped_data->>'productmodel'), ''), '') <> ''
+	OR COALESCE(NULLIF(trim(mapped_data->>'product_model'), ''), '') <> ''
+)`
+
+func measureMappedCoverage(ctx context.Context, pg *pgxpool.Pool, companyID uuid.UUID) (mappedCoverage, error) {
+	var c mappedCoverage
+	err := pg.QueryRow(ctx, fmt.Sprintf(`
+		SELECT
+			count(*)::int,
+			count(*) FILTER (WHERE COALESCE(NULLIF(trim(mapped_data->>'description'), ''), '') <> '')::int,
+			count(*) FILTER (
+				WHERE COALESCE(NULLIF(trim(mapped_data->>'category'), ''), '') <> ''
+				  AND lower(trim(mapped_data->>'category')) <> 'none'
+			)::int,
+			count(*) FILTER (WHERE %s)::int
+		FROM raw_products
+		WHERE company_id = $1`, feedAttrsSQL), companyID).Scan(
+		&c.Total, &c.WithDesc, &c.WithCat, &c.WithAttrs,
+	)
+	if err != nil {
+		return c, fmt.Errorf("measure mapped coverage: %w", err)
+	}
+	_ = pg.QueryRow(ctx, `SELECT count(*)::int FROM processed_products WHERE company_id = $1`, companyID).Scan(&c.Processed)
+	_ = pg.QueryRow(ctx, `SELECT count(*)::int FROM processing_jobs WHERE company_id = $1`, companyID).Scan(&c.Jobs)
+	return c, nil
+}
+
+func logMappedCoverage(c mappedCoverage, label string) {
+	log.Printf("A1 mapped coverage (%s): total=%d desc=%.1f%% (%d) category=%.1f%% (%d) feed_attrs=%.1f%% (%d) processed=%d jobs=%d",
+		label, c.Total, c.pct(c.WithDesc), c.WithDesc, c.pct(c.WithCat), c.WithCat, c.pct(c.WithAttrs), c.WithAttrs, c.Processed, c.Jobs)
+}

apps/api/cmd/seed-a1/dump_resolve_test.go

@@ -0,0 +1,77 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestResolveMySQLDumpPathExplicit(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "descrybe_new.sql")
+	if err := os.WriteFile(p, []byte("-- dump\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	got := resolveMySQLDumpPath(p)
+	if got != p {
+		t.Fatalf("got %q want %q", got, p)
+	}
+}
+
+func TestResolveMySQLDumpPathMissingExplicitFallsBack(t *testing.T) {
+	dir := t.TempDir()
+	want := filepath.Join(dir, "descrybe_new (1).sql")
+	if err := os.WriteFile(want, []byte("-- dump\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("SEED_A1_MYSQL_DUMP", want)
+	got := resolveMySQLDumpPath(filepath.Join(dir, "missing.sql"))
+	if got != want {
+		t.Fatalf("got %q want fallback %q", got, want)
+	}
+}
+
+func TestMysqlDumpCandidatesIncludeDownloadsName(t *testing.T) {
+	found := false
+	for _, c := range mysqlDumpCandidates() {
+		if filepath.Base(c) == "descrybe_new (1).sql" {
+			found = true
+			break
+		}
+	}
+	if !found {
+		t.Fatal("expected Downloads/descrybe_new (1).sql among candidates")
+	}
+}
+
+func TestMappedCoveragePct(t *testing.T) {
+	c := mappedCoverage{Total: 200, WithDesc: 100, WithCat: 50, WithAttrs: 200}
+	if c.pct(c.WithDesc) != 50 {
+		t.Fatalf("desc pct=%v want 50", c.pct(c.WithDesc))
+	}
+	if c.pct(c.WithCat) != 25 {
+		t.Fatalf("cat pct=%v want 25", c.pct(c.WithCat))
+	}
+	empty := mappedCoverage{}
+	if empty.pct(1) != 0 {
+		t.Fatalf("empty total should yield 0")
+	}
+}
+
+func TestScanA1ProcessedCategoriesKeepsDescriptionNullSafe(t *testing.T) {
+	// Dump original description/attributes are often NULL; category must still map.
+	const legacy = "97e1a309-3d23-4aa2-b518-8e8d7afdfec7"
+	dump := strings.Join([]string{
+		"INSERT INTO `processed_products` VALUES",
+		"(1,\t'u',\t'790069217715',\t'Name',\t'103',\tNULL,\t'<p>ai</p>',\tNULL,\tNULL,\t'completed',\tNULL,\t0,\t'2026-01-01 00:00:00',\t'2026-01-01 00:00:00',\t1,\t'" + legacy + "',\t1);",
+		"CREATE TABLE `x` (",
+	}, "\n")
+	got, err := scanA1ProcessedCategories(strings.NewReader(dump), legacy)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got["790069217715"] != "103" {
+		t.Fatalf("category=%q want 103", got["790069217715"])
+	}
+}

apps/api/cmd/seed-a1/main.go

@@ -0,0 +1,763 @@
+// Command seed-a1 exports or reimports the A1 Slovenija tenant (catalog, feeds,
+// mappings, raw products, settings) as a gzipped COPY archive.
+//
+// Source of truth for "correct mapped fields" is live Postgres (already migrated),
+// not the raw MySQL dump. Reimport wipes only the A1 company_id and preserves
+// other tenants. Processed products and processing jobs are intentionally NOT
+// part of npm run seed:a1 (skipped on import + cleared after). Use
+// -mode recover-jobs only when restoring legacy job history from a MySQL dump.
+//
+// After reimport, legacy per-category GPT prompts are overlaid from
+// scripts/seed/a1-category-prompts.json (Name→Prompt export), matched by
+// normalized category name, with v1 placeholders rewritten to {{name}} /
+// {{description}}. Use -skip-category-prompts to skip, or
+// -mode apply-category-prompts to overlay without a full wipe/reimport.
+//
+// Categories: dump/archive store assignment on processed_products.category
+// (category unique_id). Feed mappings do not map category. After reimport,
+// seed-a1 copies those codes into raw_products.mapped_data.category so the UI
+// coverage chip and later re-processing keep the assignment. Prefer
+// -mysql-dump / SEED_A1_MYSQL_DUMP; when unset, seed-a1 auto-detects common
+// dump paths (e.g. ~/Downloads/descrybe_new (1).sql). Dump backfill is
+// mapped-only — it does not create processed rows. Without a dump,
+// backfillMappedCategoriesFromProcessed is a no-op when processed was cleared
+// (archive mapped_data.category is still restored from COPY). Original
+// description + feed attributes live on raw_products.mapped_data and are
+// exported/imported as-is (skip-processed must not strip them). For a
+// polluted local DB without a full wipe, use -mode backfill-categories.
+// Fixture EANs are purged from non-A1 tenants automatically.
+//
+// Usage:
+//
+//	go run ./cmd/seed-a1 -mode export -file ../../scripts/seed/a1-demo-data.sql.gz
+//	go run ./cmd/seed-a1 -mode reimport -file ../../scripts/seed/a1-demo-data.sql.gz
+//	go run ./cmd/seed-a1 -mode apply-category-prompts -file ../../scripts/seed/a1-demo-data.sql.gz
+//	go run ./cmd/seed-a1 -mode recover-jobs -mysql-dump path/to/descrybe_new.sql
+//	go run ./cmd/seed-a1 -mode backfill-categories -mysql-dump path/to/descrybe_new.sql
+//
+// DATABASE_URL / -postgres required.
+// Day-to-day: `npm run seed:a1` (reimport + category prompts + mapped category backfill). Maintainer snapshot: `npm run seed:a1:export`.
+// recover-jobs is opt-in only and will reintroduce job history.
+package main
+
+import (
+	"bufio"
+	"context"
+	"flag"
+	"fmt"
+	"io"
+	"log"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"compress/gzip"
+
+	"github.com/descrybe/descrybe-v2/apps/api/internal/billing"
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgconn"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// Canonical Postgres id for the migrated A1 Slovenija tenant.
+const defaultA1CompanyID = "604f23a8-b66e-4b21-8b45-0d72b68f4790"
+
+const archiveMagic = "# seed-a1 v1"
+
+// tableSpec describes one archive section.
+// selectSQL must return columns matching cols (order matters for COPY).
+type tableSpec struct {
+	name      string
+	cols      string
+	selectSQL string // may use $1 = company uuid
+	scoped    bool   // true → DELETE WHERE company_id = $1 before load
+}
+
+func main() {
+	postgresURL := flag.String("postgres", os.Getenv("DATABASE_URL"), "Postgres URL (DATABASE_URL)")
+	mode := flag.String("mode", "reimport", "export | reimport | recover-jobs | apply-category-prompts | backfill-categories")
+	file := flag.String("file", "", "gzipped seed archive path (required for export/reimport)")
+	mysqlDump := flag.String("mysql-dump", os.Getenv("SEED_A1_MYSQL_DUMP"), "mysqldump path for recover-jobs / backfill-categories (or SEED_A1_MYSQL_DUMP)")
+	company := flag.String("company", defaultA1CompanyID, "Postgres companies.id for A1")
+	categoryPrompts := flag.String("category-prompts", "", "A1 category prompts JSON (default: sibling a1-category-prompts.json next to -file)")
+	skipCategoryPrompts := flag.Bool("skip-category-prompts", false, "skip overlay of legacy category prompts after reimport")
+	skipCategoryBackfill := flag.Bool("skip-category-backfill", false, "skip mapped_data.category backfill after reimport")
+	flag.Parse()
+
+	if strings.TrimSpace(*postgresURL) == "" {
+		log.Fatal("-postgres / DATABASE_URL is required")
+	}
+	companyID, err := uuid.Parse(strings.TrimSpace(*company))
+	if err != nil {
+		log.Fatalf("-company: %v", err)
+	}
+
+	modeVal := strings.ToLower(strings.TrimSpace(*mode))
+	if modeVal != "recover-jobs" && modeVal != "apply-category-prompts" && modeVal != "backfill-categories" && strings.TrimSpace(*file) == "" {
+		log.Fatal("-file is required (e.g. ../../scripts/seed/a1-demo-data.sql.gz)")
+	}
+	dumpPath := resolveMySQLDumpPath(*mysqlDump)
+	if dumpPath != "" && strings.TrimSpace(*mysqlDump) == "" {
+		log.Printf("auto-detected MySQL dump: %s", dumpPath)
+	}
+	if modeVal == "recover-jobs" && dumpPath == "" {
+		log.Fatal("-mysql-dump or SEED_A1_MYSQL_DUMP is required for recover-jobs (or place descrybe_new.sql in Downloads)")
+	}
+	if modeVal == "backfill-categories" && dumpPath == "" {
+		log.Fatal("-mysql-dump or SEED_A1_MYSQL_DUMP is required for backfill-categories (or place descrybe_new.sql in Downloads)")
+	}
+	promptsPath := strings.TrimSpace(*categoryPrompts)
+	if promptsPath == "" {
+		promptsPath = defaultCategoryPromptsPath(*file)
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Minute)
+	defer cancel()
+
+	pg, err := pgxpool.New(ctx, *postgresURL)
+	if err != nil {
+		log.Fatalf("postgres: %v", err)
+	}
+	defer pg.Close()
+
+	switch modeVal {
+	case "export":
+		if err := exportArchive(ctx, pg, companyID, *file); err != nil {
+			log.Fatalf("export: %v", err)
+		}
+		log.Printf("exported A1 company %s → %s", companyID, *file)
+	case "reimport", "import":
+		if err := reimportArchive(ctx, pg, companyID, *file); err != nil {
+			log.Fatalf("reimport: %v", err)
+		}
+		log.Printf("reimported A1 company %s from %s", companyID, *file)
+		if !*skipCategoryPrompts {
+			res, err := applyCategoryPrompts(ctx, pg, companyID, promptsPath)
+			if err != nil {
+				log.Fatalf("category prompts: %v", err)
+			}
+			logCategoryPromptResult(res, promptsPath)
+		}
+		if !*skipCategoryBackfill {
+			if dumpPath != "" {
+				res, err := backfillCategoriesFromMySQLDump(ctx, pg, companyID, dumpPath)
+				if err != nil {
+					log.Fatalf("category backfill: %v", err)
+				}
+				logCategoryBackfillResult(res, dumpPath)
+			} else {
+				n, err := backfillMappedCategoriesFromProcessed(ctx, pg, companyID)
+				if err != nil {
+					log.Fatalf("category backfill: %v", err)
+				}
+				log.Printf("mapped_data.category backfill from processed: updated=%d (A1 only; 0 if processed was cleared — place dump in Downloads or set SEED_A1_MYSQL_DUMP)", n)
+			}
+		}
+		rawN, ppN, err := purgeA1FixtureEANsFromOtherTenants(ctx, pg, companyID)
+		if err != nil {
+			log.Fatalf("purge demo fixtures: %v", err)
+		}
+		if rawN > 0 || ppN > 0 {
+			log.Printf("purged A1 fixture EANs from other tenants: raw=%d processed=%d", rawN, ppN)
+		}
+		if cov, err := measureMappedCoverage(ctx, pg, companyID); err != nil {
+			log.Printf("mapped coverage: %v", err)
+		} else {
+			logMappedCoverage(cov, "post-reimport")
+		}
+	case "apply-category-prompts":
+		res, err := applyCategoryPrompts(ctx, pg, companyID, promptsPath)
+		if err != nil {
+			log.Fatalf("category prompts: %v", err)
+		}
+		logCategoryPromptResult(res, promptsPath)
+	case "backfill-categories":
+		res, err := backfillCategoriesFromMySQLDump(ctx, pg, companyID, dumpPath)
+		if err != nil {
+			log.Fatalf("backfill-categories: %v", err)
+		}
+		rawN, ppN, err := purgeA1FixtureEANsFromOtherTenants(ctx, pg, companyID)
+		if err != nil {
+			log.Fatalf("purge demo fixtures: %v", err)
+		}
+		res.PurgedOtherRaw, res.PurgedOtherPP = rawN, ppN
+		logCategoryBackfillResult(res, dumpPath)
+	case "recover-jobs":
+		if err := recoverJobsFromMySQLDump(ctx, pg, companyID, dumpPath); err != nil {
+			log.Fatalf("recover-jobs: %v", err)
+		}
+		log.Printf("recovered A1 processing jobs into company %s from %s", companyID, dumpPath)
+	default:
+		log.Fatalf("unknown -mode %q (want export|reimport|recover-jobs|apply-category-prompts|backfill-categories)", *mode)
+	}
+}
+
+func tableSpecs(companyID uuid.UUID) []tableSpec {
+	_ = companyID // reserved; SELECT SQLs bind $1 at export time
+	return []tableSpec{
+		{
+			name:      "plans",
+			cols:      "id,name,description,monthly_credits,yearly_credits,max_products,is_custom,term,created_at,updated_at,features,is_legacy",
+			selectSQL: `SELECT p.id, p.name, p.description, p.monthly_credits, p.yearly_credits, p.max_products, p.is_custom, p.term, p.created_at, p.updated_at, p.features, p.is_legacy FROM plans p WHERE p.id IN (SELECT plan_id FROM company_plans WHERE company_id = $1)`,
+			scoped:    false,
+		},
+		{
+			name:      "companies",
+			cols:      "id,name,language,merge_products_by_gtin,legacy_company_id,created_at,updated_at,stripe_customer_id",
+			selectSQL: `SELECT id, name, language, merge_products_by_gtin, legacy_company_id, created_at, updated_at, stripe_customer_id FROM companies WHERE id = $1`,
+			scoped:    false,
+		},
+		{
+			name:      "users",
+			cols:      "id,email,name,password_hash,must_set_password,email_verified_at,is_platform_admin,is_active,legacy_user_id,last_login_at,created_at,updated_at,staff_role",
+			selectSQL: `SELECT u.id, u.email, u.name, u.password_hash, u.must_set_password, u.email_verified_at, u.is_platform_admin, u.is_active, u.legacy_user_id, u.last_login_at, u.created_at, u.updated_at, u.staff_role FROM users u WHERE u.id IN (SELECT user_id FROM memberships WHERE company_id = $1)`,
+			scoped:    false,
+		},
+		{
+			name:      "memberships",
+			cols:      "id,company_id,user_id,role,status,created_at,updated_at",
+			selectSQL: `SELECT id, company_id, user_id, role, status, created_at, updated_at FROM memberships WHERE company_id = $1`,
+			scoped:    true,
+		},
+		{
+			name:      "company_settings",
+			cols:      "company_id,settings,updated_at",
+			selectSQL: `SELECT company_id, settings, updated_at FROM company_settings WHERE company_id = $1`,
+			scoped:    true,
+		},
+		{
+			name:      "company_brand",
+			cols:      "company_id,voice_tone,dos,donts,primary_color,secondary_color,logo_url,preferred_terms,updated_at",
+			selectSQL: `SELECT company_id, voice_tone, dos, donts, primary_color, secondary_color, logo_url, preferred_terms, updated_at FROM company_brand WHERE company_id = $1`,
+			scoped:    true,
+		},
+		{
+			name:      "company_plans",
+			cols:      "id,company_id,plan_id,is_active,billing_cycle_start,next_billing_date,contract_start_date,contract_end_date,custom_monthly_credits,total_credits_allocated,custom_max_products,contract_reference,notes,is_trial,trial_ends_at,trial_credits,created_at,updated_at,stripe_subscription_id,stripe_price_id",
+			selectSQL: `SELECT id, company_id, plan_id, is_active, billing_cycle_start, next_billing_date, contract_start_date, contract_end_date, custom_monthly_credits, total_credits_allocated, custom_max_products, contract_reference, notes, is_trial, trial_ends_at, trial_credits, created_at, updated_at, stripe_subscription_id, stripe_price_id FROM company_plans WHERE company_id = $1`,
+			scoped:    true,
+		},
+		{
+			name:      "credit_balances",
+			cols:      "company_id,total_credits,used_credits,updated_at",
+			selectSQL: `SELECT company_id, total_credits, used_credits, updated_at FROM credit_balances WHERE company_id = $1`,
+			scoped:    true,
+		},
+		{
+			name:      "api_keys",
+			cols:      "id,company_id,user_id,name,key_hash,key_prefix,last_used_at,revoked_at,created_at,updated_at",
+			selectSQL: `SELECT id, company_id, user_id, name, key_hash, key_prefix, last_used_at, revoked_at, created_at, updated_at FROM api_keys WHERE company_id = $1`,
+			scoped:    true,
+		},
+		{
+			name:      "field_groups",
+			cols:      `id,company_id,name,description,"order",is_system,created_at,updated_at`,
+			selectSQL: `SELECT id, company_id, name, description, "order", is_system, created_at, updated_at FROM field_groups WHERE company_id = $1`,
+			scoped:    true,
+		},
+		{
+			name:      "standard_fields",
+			cols:      "id,company_id,name,key,type,group_id,is_required,description,default_value,validation,is_system,created_at,updated_at,enabled,unit,sort_order,mapping_hints",
+			selectSQL: `SELECT id, company_id, name, key, type, group_id, is_required, description, default_value, validation, is_system, created_at, updated_at, enabled, unit, sort_order, mapping_hints FROM standard_fields WHERE company_id = $1`,
+			scoped:    true,
+		},
+		{
+			name:      "structured_description_fields",
+			cols:      "id,company_id,field_key,type,created_at,updated_at",
+			selectSQL: `SELECT id, company_id, field_key, type, created_at, updated_at FROM structured_description_fields WHERE company_id = $1`,
+			scoped:    true,
+		},
+		{
+			name:      "attributes",
+			cols:      "id,company_id,attribute_key,name,value_type,unit,example,parent_key,created_at,updated_at",
+			selectSQL: `SELECT id, company_id, attribute_key, name, value_type, unit, example, parent_key, created_at, updated_at FROM attributes WHERE company_id = $1`,
+			scoped:    true,
+		},
+		{
+			name:      "categories",
+			cols:      "id,company_id,name,unique_id,parent_unique_id,path,level,position,is_active,description,prompt,metadata,config,title_template,description_template,created_at,updated_at",
+			selectSQL: `SELECT id, company_id, name, unique_id, parent_unique_id, path, level, position, is_active, description, prompt, metadata, config, title_template, description_template, created_at, updated_at FROM categories WHERE company_id = $1`,
+			scoped:    true,
+		},
+		{
+			name:      "category_attributes",
+			cols:      "id,company_id,category_unique_id,attribute_id,required,created_at,updated_at",
+			selectSQL: `SELECT id, company_id, category_unique_id, attribute_id, required, created_at, updated_at FROM category_attributes WHERE company_id = $1`,
+			scoped:    true,
+		},
+		{
+			name:      "custom_variables",
+			cols:      "id,company_id,name,value,description,created_at,updated_at",
+			selectSQL: `SELECT id, company_id, name, value, description, created_at, updated_at FROM custom_variables WHERE company_id = $1`,
+			scoped:    true,
+		},
+		{
+			name:      "input_feeds",
+			cols:      "id,company_id,name,url,feed_type,status,sync_interval_minutes,last_synced_at,auth_config,options,created_at,updated_at",
+			selectSQL: `SELECT id, company_id, name, url, feed_type, status, sync_interval_minutes, last_synced_at, auth_config, options, created_at, updated_at FROM input_feeds WHERE company_id = $1`,
+			scoped:    true,
+		},
+		{
+			name:      "feed_mappings",
+			cols:      "id,feed_id,company_id,version,mappings,is_active,created_at,updated_at",
+			selectSQL: `SELECT id, feed_id, company_id, version, mappings, is_active, created_at, updated_at FROM feed_mappings WHERE company_id = $1`,
+			scoped:    true,
+		},
+		{
+			name:      "feed_tags",
+			cols:      "id,company_id,name,color,created_at",
+			selectSQL: `SELECT id, company_id, name, color, created_at FROM feed_tags WHERE company_id = $1`,
+			scoped:    true,
+		},
+		{
+			name: "feed_tag_mappings",
+			cols: "feed_id,tag_id",
+			selectSQL: `SELECT ftm.feed_id, ftm.tag_id FROM feed_tag_mappings ftm
+				JOIN feed_tags ft ON ft.id = ftm.tag_id WHERE ft.company_id = $1`,
+			scoped: false, // wiped via cascading / explicit join delete
+		},
+		{
+			name:      "files",
+			cols:      "id,company_id,user_id,name,path,content_type,size_bytes,status,metadata,created_at,updated_at",
+			selectSQL: `SELECT id, company_id, user_id, name, path, content_type, size_bytes, status, metadata, created_at, updated_at FROM files WHERE company_id = $1`,
+			scoped:    true,
+		},
+		{
+			name: "raw_products",
+			cols: "id,company_id,gtin,feed_id,feed_ids,raw_data,mapped_data,sync_job_id,is_processed,processing_status,file_id,created_at,updated_at",
+			// sync_job_id points at ephemeral feed_sync_jobs (not archived) — export as NULL.
+			// A1 seed stays catalog-clean: never archive processing state on raw rows.
+			selectSQL: `SELECT id, company_id, gtin, feed_id, feed_ids, raw_data, mapped_data, NULL::uuid AS sync_job_id, false AS is_processed, 'unprocessed' AS processing_status, file_id, created_at, updated_at FROM raw_products WHERE company_id = $1`,
+			scoped:    true,
+		},
+		// processed_products / processing_jobs / processing_job_products are intentionally
+		// omitted from the A1 demo archive. Use -mode recover-jobs only when restoring
+		// legacy job history from a MySQL dump (not part of npm run seed:a1).
+		{
+			name:      "export_feeds",
+			cols:      "id,company_id,name,source_feed_id,format,public_token,template,filters,is_active,last_generated_at,created_at,updated_at",
+			selectSQL: `SELECT id, company_id, name, source_feed_id, format, public_token, template, filters, is_active, last_generated_at, created_at, updated_at FROM export_feeds WHERE company_id = $1`,
+			scoped:    true,
+		},
+		{
+			name:      "woocommerce_configs",
+			cols:      "company_id,store_url,consumer_key,consumer_secret,is_enabled,sync_options,last_synced_at,last_test_at,last_test_status,created_at,updated_at",
+			selectSQL: `SELECT company_id, store_url, consumer_key, consumer_secret, is_enabled, sync_options, last_synced_at, last_test_at, last_test_status, created_at, updated_at FROM woocommerce_configs WHERE company_id = $1`,
+			scoped:    true,
+		},
+	}
+}
+
+func exportTables(companyID uuid.UUID) []tableSpec {
+	return tableSpecs(companyID)
+}
+
+func exportArchive(ctx context.Context, pg *pgxpool.Pool, companyID uuid.UUID, outPath string) error {
+	var name, legacy string
+	err := pg.QueryRow(ctx, `
+		SELECT name, COALESCE(legacy_company_id::text, '')
+		FROM companies WHERE id = $1`, companyID).Scan(&name, &legacy)
+	if err != nil {
+		return fmt.Errorf("resolve company %s: %w (expected A1 Slovenija)", companyID, err)
+	}
+	if legacy != "" && !strings.EqualFold(legacy, billing.A1LegacyCompanyID) {
+		log.Printf("warning: legacy_company_id=%s (canonical MySQL A1 is %s)", legacy, billing.A1LegacyCompanyID)
+	}
+	log.Printf("exporting company %s (%q legacy=%s)", companyID, name, legacy)
+
+	if err := os.MkdirAll(filepath.Dir(outPath), 0o755); err != nil {
+		return err
+	}
+	tmp := outPath + ".tmp"
+	f, err := os.Create(tmp)
+	if err != nil {
+		return err
+	}
+	gz := gzip.NewWriter(f)
+	bw := bufio.NewWriterSize(gz, 1<<20)
+
+	write := func(s string) error {
+		_, err := bw.WriteString(s)
+		return err
+	}
+
+	if err := write(fmt.Sprintf("%s\n# company_id=%s\n# company_name=%s\n# legacy_company_id=%s\n# generated_at=%s\n",
+		archiveMagic, companyID, sanitizeHeader(name), legacy, time.Now().UTC().Format(time.RFC3339))); err != nil {
+		_ = f.Close()
+		_ = os.Remove(tmp)
+		return err
+	}
+
+	conn, err := pg.Acquire(ctx)
+	if err != nil {
+		_ = f.Close()
+		_ = os.Remove(tmp)
+		return err
+	}
+	defer conn.Release()
+
+	for _, t := range exportTables(companyID) {
+		log.Printf("  export %s…", t.name)
+		if err := write(fmt.Sprintf("BEGIN_TABLE %s\nCOLUMNS %s\n", t.name, t.cols)); err != nil {
+			_ = f.Close()
+			_ = os.Remove(tmp)
+			return err
+		}
+		// Bind company id into COPY subquery by substituting a validated uuid literal
+		// (companyID already parsed). ReplaceAll so multi-$1 SELECTs stay correct.
+		q := strings.ReplaceAll(t.selectSQL, "$1", "'"+companyID.String()+"'::uuid")
+		copySQL := fmt.Sprintf("COPY (%s) TO STDOUT", q)
+		tag, err := conn.Conn().PgConn().CopyTo(ctx, bw, copySQL)
+		if err != nil {
+			_ = f.Close()
+			_ = os.Remove(tmp)
+			return fmt.Errorf("copy %s: %w", t.name, err)
+		}
+		rows := tag.RowsAffected()
+		if err := write(fmt.Sprintf("END_TABLE %s rows=%d\n", t.name, rows)); err != nil {
+			_ = f.Close()
+			_ = os.Remove(tmp)
+			return err
+		}
+		log.Printf("    %s rows=%d", t.name, rows)
+	}
+
+	if err := bw.Flush(); err != nil {
+		_ = f.Close()
+		_ = os.Remove(tmp)
+		return err
+	}
+	if err := gz.Close(); err != nil {
+		_ = f.Close()
+		_ = os.Remove(tmp)
+		return err
+	}
+	if err := f.Close(); err != nil {
+		_ = os.Remove(tmp)
+		return err
+	}
+	return os.Rename(tmp, outPath)
+}
+
+func sanitizeHeader(s string) string {
+	return strings.Map(func(r rune) rune {
+		if r == '\n' || r == '\r' {
+			return -1
+		}
+		return r
+	}, s)
+}
+
+func wipeA1Tenant(ctx context.Context, tx pgx.Tx, companyID uuid.UUID) error {
+	// FK-safe deletes for A1 only. Users/plans/global rows are not deleted.
+	stmts := []string{
+		`DELETE FROM feed_tag_mappings WHERE tag_id IN (SELECT id FROM feed_tags WHERE company_id = $1)
+			OR feed_id IN (SELECT id FROM input_feeds WHERE company_id = $1)`,
+		// Jobs before products: job_products FK raw_products / processed_products.
+		`DELETE FROM processing_job_products WHERE job_id IN (SELECT id FROM processing_jobs WHERE company_id = $1)`,
+		`DELETE FROM processing_jobs WHERE company_id = $1`,
+		`DELETE FROM processed_products WHERE company_id = $1`,
+		`DELETE FROM raw_products WHERE company_id = $1`,
+		`DELETE FROM export_feeds WHERE company_id = $1`,
+		`DELETE FROM feed_mappings WHERE company_id = $1`,
+		`DELETE FROM feed_sync_jobs WHERE company_id = $1`,
+		`DELETE FROM input_feeds WHERE company_id = $1`,
+		`DELETE FROM category_attributes WHERE company_id = $1`,
+		`DELETE FROM categories WHERE company_id = $1`,
+		`DELETE FROM attributes WHERE company_id = $1`,
+		`DELETE FROM custom_variables WHERE company_id = $1`,
+		`DELETE FROM standard_fields WHERE company_id = $1`,
+		`DELETE FROM field_groups WHERE company_id = $1`,
+		`DELETE FROM structured_description_fields WHERE company_id = $1`,
+		`DELETE FROM feed_tags WHERE company_id = $1`,
+		`DELETE FROM files WHERE company_id = $1`,
+		`DELETE FROM schema_extraction_tasks WHERE company_id = $1`,
+		`DELETE FROM tasks WHERE company_id = $1`,
+		`DELETE FROM product_reviews WHERE company_id = $1`,
+		`DELETE FROM woo_order_items WHERE company_id = $1`,
+		`DELETE FROM woo_orders WHERE company_id = $1`,
+		`DELETE FROM woocommerce_configs WHERE company_id = $1`,
+		`DELETE FROM api_keys WHERE company_id = $1`,
+		`DELETE FROM company_plans WHERE company_id = $1`,
+		`DELETE FROM credit_balances WHERE company_id = $1`,
+		`DELETE FROM company_brand WHERE company_id = $1`,
+		`DELETE FROM company_settings WHERE company_id = $1`,
+		`DELETE FROM memberships WHERE company_id = $1`,
+		`DELETE FROM invites WHERE company_id = $1`,
+		`DELETE FROM billing_cycles WHERE company_id = $1`,
+	}
+	for _, q := range stmts {
+		if _, err := tx.Exec(ctx, q, companyID); err != nil {
+			return fmt.Errorf("wipe: %s: %w", q, err)
+		}
+	}
+	return nil
+}
+
+func reimportArchive(ctx context.Context, pg *pgxpool.Pool, companyID uuid.UUID, inPath string) error {
+	f, err := os.Open(inPath)
+	if err != nil {
+		return fmt.Errorf("open seed file: %w (expected committed scripts/seed/a1-demo-data.sql.gz; maintainers regenerate with npm run seed:a1:export)", err)
+	}
+	defer f.Close()
+
+	gz, err := gzip.NewReader(f)
+	if err != nil {
+		return fmt.Errorf("gzip: %w", err)
+	}
+	defer gz.Close()
+
+	sections, headerCompany, err := parseArchive(gz)
+	if err != nil {
+		return err
+	}
+	if headerCompany != "" && headerCompany != companyID.String() {
+		return fmt.Errorf("archive company_id=%s does not match -company=%s", headerCompany, companyID)
+	}
+
+	acq, err := pg.Acquire(ctx)
+	if err != nil {
+		return err
+	}
+	defer acq.Release()
+
+	tx, err := acq.Begin(ctx)
+	if err != nil {
+		return err
+	}
+	defer tx.Rollback(ctx)
+
+	log.Printf("wiping A1 tenant %s (other companies untouched)…", companyID)
+	if err := wipeA1Tenant(ctx, tx, companyID); err != nil {
+		return err
+	}
+
+	pgConn := acq.Conn().PgConn()
+
+	for _, sec := range sections {
+		if skipA1ProcessingSeedTable(sec.name) {
+			log.Printf("  skip %s (%d bytes) — A1 seed keeps zero processed/jobs", sec.name, len(sec.data))
+			continue
+		}
+		log.Printf("  load %s (%d bytes)…", sec.name, len(sec.data))
+		switch sec.name {
+		case "plans":
+			if err := upsertFromCopy(ctx, tx, pgConn, "plans", sec.cols, sec.data, `
+				INSERT INTO plans AS p (`+sec.cols+`)
+				SELECT `+sec.cols+` FROM tmp_seed_a1_plans
+				ON CONFLICT (id) DO UPDATE SET
+					name = EXCLUDED.name,
+					description = EXCLUDED.description,
+					monthly_credits = EXCLUDED.monthly_credits,
+					yearly_credits = EXCLUDED.yearly_credits,
+					max_products = EXCLUDED.max_products,
+					is_custom = EXCLUDED.is_custom,
+					term = EXCLUDED.term,
+					features = EXCLUDED.features,
+					is_legacy = EXCLUDED.is_legacy,
+					updated_at = EXCLUDED.updated_at`); err != nil {
+				return err
+			}
+		case "companies":
+			if err := upsertFromCopy(ctx, tx, pgConn, "companies", sec.cols, sec.data, `
+				INSERT INTO companies AS c (`+sec.cols+`)
+				SELECT `+sec.cols+` FROM tmp_seed_a1_companies
+				ON CONFLICT (id) DO UPDATE SET
+					name = EXCLUDED.name,
+					language = EXCLUDED.language,
+					merge_products_by_gtin = EXCLUDED.merge_products_by_gtin,
+					legacy_company_id = EXCLUDED.legacy_company_id,
+					stripe_customer_id = EXCLUDED.stripe_customer_id,
+					updated_at = EXCLUDED.updated_at`); err != nil {
+				return err
+			}
+		case "users":
+			if err := upsertFromCopy(ctx, tx, pgConn, "users", sec.cols, sec.data, `
+				INSERT INTO users AS u (`+sec.cols+`)
+				SELECT `+sec.cols+` FROM tmp_seed_a1_users
+				ON CONFLICT (id) DO UPDATE SET
+					email = EXCLUDED.email,
+					name = EXCLUDED.name,
+					password_hash = COALESCE(EXCLUDED.password_hash, u.password_hash),
+					must_set_password = EXCLUDED.must_set_password,
+					is_platform_admin = u.is_platform_admin OR EXCLUDED.is_platform_admin,
+					is_active = EXCLUDED.is_active,
+					staff_role = COALESCE(EXCLUDED.staff_role, u.staff_role),
+					updated_at = EXCLUDED.updated_at`); err != nil {
+				return err
+			}
+		case "feed_tag_mappings":
+			if err := copyInto(ctx, pgConn, "feed_tag_mappings", sec.cols, sec.data); err != nil {
+				return err
+			}
+		default:
+			if err := copyInto(ctx, pgConn, sec.name, sec.cols, sec.data); err != nil {
+				return err
+			}
+		}
+	}
+
+	if err := tx.Commit(ctx); err != nil {
+		return err
+	}
+
+	if err := clearA1ProcessingArtifacts(ctx, pg, companyID); err != nil {
+		return err
+	}
+
+	var rawN, procN, feedN, mapN, jobN, jobProdN int
+	_ = pg.QueryRow(ctx, `SELECT count(*) FROM raw_products WHERE company_id=$1`, companyID).Scan(&rawN)
+	_ = pg.QueryRow(ctx, `SELECT count(*) FROM processed_products WHERE company_id=$1`, companyID).Scan(&procN)
+	_ = pg.QueryRow(ctx, `SELECT count(*) FROM input_feeds WHERE company_id=$1`, companyID).Scan(&feedN)
+	_ = pg.QueryRow(ctx, `SELECT count(*) FROM feed_mappings WHERE company_id=$1`, companyID).Scan(&mapN)
+	_ = pg.QueryRow(ctx, `SELECT count(*) FROM processing_jobs WHERE company_id=$1`, companyID).Scan(&jobN)
+	_ = pg.QueryRow(ctx, `SELECT count(*) FROM processing_job_products WHERE job_id IN (SELECT id FROM processing_jobs WHERE company_id=$1)`, companyID).Scan(&jobProdN)
+	log.Printf("post-import counts: raw=%d processed=%d feeds=%d mappings=%d jobs=%d job_products=%d", rawN, procN, feedN, mapN, jobN, jobProdN)
+	return nil
+}
+
+// skipA1ProcessingSeedTable omits processed/job history from older archives so
+// npm run seed:a1 leaves A1 with a clean catalog (zero processed, zero jobs).
+func skipA1ProcessingSeedTable(name string) bool {
+	switch name {
+	case "processed_products", "processing_jobs", "processing_job_products", "tasks":
+		return true
+	default:
+		return false
+	}
+}
+
+// clearA1ProcessingArtifacts deletes A1 processed products, jobs, and tasks and
+// resets raw processing flags. Safe to run after reimport (other companies untouched).
+func clearA1ProcessingArtifacts(ctx context.Context, pg *pgxpool.Pool, companyID uuid.UUID) error {
+	tx, err := pg.Begin(ctx)
+	if err != nil {
+		return err
+	}
+	defer tx.Rollback(ctx)
+
+	stmts := []string{
+		`DELETE FROM processing_job_products WHERE job_id IN (SELECT id FROM processing_jobs WHERE company_id = $1)`,
+		`DELETE FROM processing_jobs WHERE company_id = $1`,
+		`DELETE FROM processed_products WHERE company_id = $1`,
+		`DELETE FROM tasks WHERE company_id = $1`,
+		`UPDATE raw_products
+		 SET processing_status = 'unprocessed', is_processed = false, updated_at = now()
+		 WHERE company_id = $1
+		   AND (COALESCE(processing_status, '') NOT IN ('', 'unprocessed') OR is_processed IS TRUE)`,
+	}
+	for _, q := range stmts {
+		if _, err := tx.Exec(ctx, q, companyID); err != nil {
+			return fmt.Errorf("clear processing artifacts: %w", err)
+		}
+	}
+	if err := tx.Commit(ctx); err != nil {
+		return err
+	}
+	log.Printf("A1 processing artifacts cleared for company %s (processed=0 jobs=0)", companyID)
+	return nil
+}
+
+type archiveSection struct {
+	name string
+	cols string
+	data []byte
+}
+
+func parseArchive(r io.Reader) ([]archiveSection, string, error) {
+	br := bufio.NewReaderSize(r, 1<<20)
+	var headerCompany string
+	var sections []archiveSection
+	var cur *archiveSection
+	var buf strings.Builder
+
+	flush := func() {
+		if cur == nil {
+			return
+		}
+		cur.data = []byte(buf.String())
+		sections = append(sections, *cur)
+		cur = nil
+		buf.Reset()
+	}
+
+	lineNo := 0
+	for {
+		line, err := br.ReadString('\n')
+		if len(line) > 0 {
+			lineNo++
+			trimmedRight := strings.TrimRight(line, "\r\n")
+			if cur == nil {
+				s := strings.TrimSpace(trimmedRight)
+				if lineNo == 1 && !strings.HasPrefix(s, "# seed-a1") {
+					return nil, "", fmt.Errorf("bad magic on line 1: %q", s)
+				}
+				if strings.HasPrefix(s, "# company_id=") {
+					headerCompany = strings.TrimPrefix(s, "# company_id=")
+				}
+				if strings.HasPrefix(s, "BEGIN_TABLE ") {
+					flush()
+					cur = &archiveSection{name: strings.TrimSpace(strings.TrimPrefix(s, "BEGIN_TABLE "))}
+					buf.Reset()
+				}
+				continue
+			}
+			// inside table
+			if strings.HasPrefix(trimmedRight, "COLUMNS ") && cur.cols == "" {
+				cur.cols = strings.TrimSpace(strings.TrimPrefix(trimmedRight, "COLUMNS "))
+				continue
+			}
+			if strings.HasPrefix(trimmedRight, "END_TABLE ") {
+				flush()
+				continue
+			}
+			buf.WriteString(line)
+			continue
+		}
+		if err == io.EOF {
+			break
+		}
+		if err != nil {
+			return nil, "", err
+		}
+	}
+	flush()
+	if len(sections) == 0 {
+		return nil, "", fmt.Errorf("archive contained no tables")
+	}
+	return sections, headerCompany, nil
+}
+
+func copyInto(ctx context.Context, pgConn *pgconn.PgConn, table, cols string, data []byte) error {
+	if len(strings.TrimSpace(string(data))) == 0 {
+		return nil
+	}
+	sql := fmt.Sprintf("COPY %s (%s) FROM STDIN", table, cols)
+	_, err := pgConn.CopyFrom(ctx, strings.NewReader(string(data)), sql)
+	if err != nil {
+		return fmt.Errorf("COPY %s: %w", table, err)
+	}
+	return nil
+}
+
+func upsertFromCopy(ctx context.Context, tx pgx.Tx, pgConn *pgconn.PgConn, table, cols string, data []byte, mergeSQL string) error {
+	tmp := "tmp_seed_a1_" + table
+	if _, err := tx.Exec(ctx, fmt.Sprintf(`DROP TABLE IF EXISTS %s`, tmp)); err != nil {
+		return err
+	}
+	if _, err := tx.Exec(ctx, fmt.Sprintf(`CREATE TEMP TABLE %s (LIKE %s INCLUDING DEFAULTS) ON COMMIT DROP`, tmp, table)); err != nil {
+		return err
+	}
+	if len(strings.TrimSpace(string(data))) > 0 {
+		sql := fmt.Sprintf("COPY %s (%s) FROM STDIN", tmp, cols)
+		if _, err := pgConn.CopyFrom(ctx, strings.NewReader(string(data)), sql); err != nil {
+			return fmt.Errorf("COPY temp %s: %w", table, err)
+		}
+	}
+	if _, err := tx.Exec(ctx, mergeSQL); err != nil {
+		return fmt.Errorf("merge %s: %w", table, err)
+	}
+	return nil
+}

apps/api/cmd/seed-a1/recover_jobs.go

@@ -0,0 +1,569 @@
+package main
+
+import (
+	"bufio"
+	"context"
+	"fmt"
+	"io"
+	"log"
+	"os"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/descrybe/descrybe-v2/apps/api/internal/billing"
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// recoverJobsFromMySQLDump streams a mysqldump and upserts every A1
+// processing_jobs (+ joinable processing_job_products) into live Postgres.
+//
+// Needed because live A1 often only retains a couple of recent jobs (retention
+// deletes non-migrated terminal rows after 30 days; jobs domain may never have
+// been imported). Export alone cannot invent history that is missing from PG.
+//
+// Job products resolve raw_product_id via dump GTIN → Postgres raw_products.
+func recoverJobsFromMySQLDump(ctx context.Context, pg *pgxpool.Pool, companyID uuid.UUID, dumpPath string) error {
+	legacyCompany := billing.A1LegacyCompanyID
+	var legacy string
+	_ = pg.QueryRow(ctx, `SELECT COALESCE(legacy_company_id::text, '') FROM companies WHERE id = $1`, companyID).Scan(&legacy)
+	if legacy != "" {
+		legacyCompany = legacy
+	}
+
+	fi, err := os.Stat(dumpPath)
+	if err != nil {
+		return fmt.Errorf("stat mysql dump %q: %w", dumpPath, err)
+	}
+	log.Printf("recover-jobs: dump=%s size=%d legacy_company=%s", dumpPath, fi.Size(), legacyCompany)
+
+	userByLegacy, err := loadUserLegacyMap(ctx, pg, companyID)
+	if err != nil {
+		return err
+	}
+
+	f, err := os.Open(dumpPath)
+	if err != nil {
+		return fmt.Errorf("open mysql dump: %w", err)
+	}
+	defer f.Close()
+
+	jobs, err := scanA1ProcessingJobs(f, legacyCompany)
+	if err != nil {
+		return err
+	}
+	if len(jobs) == 0 {
+		return fmt.Errorf("no processing_jobs for legacy company %s in dump", legacyCompany)
+	}
+	log.Printf("dump: %d A1 processing_jobs (incl. history)", len(jobs))
+
+	if _, err := f.Seek(0, io.SeekStart); err != nil {
+		return err
+	}
+	jobIDs := make(map[string]struct{}, len(jobs))
+	for _, j := range jobs {
+		jobIDs[j.id] = struct{}{}
+	}
+	pjpRows, rawLegacyIDs, err := scanA1JobProducts(f, jobIDs)
+	if err != nil {
+		return err
+	}
+	log.Printf("dump: %d A1 processing_job_products across %d raw ids", len(pjpRows), len(rawLegacyIDs))
+
+	if _, err := f.Seek(0, io.SeekStart); err != nil {
+		return err
+	}
+	gtinByLegacy, err := scanRawProductGTINs(f, rawLegacyIDs, legacyCompany)
+	if err != nil {
+		return err
+	}
+	log.Printf("dump: resolved %d/%d raw→gtin mappings", len(gtinByLegacy), len(rawLegacyIDs))
+
+	rawByGTIN, err := loadRawByGTIN(ctx, pg, companyID, gtinByLegacy)
+	if err != nil {
+		return err
+	}
+
+	var jobsUpserted, jobsSkipped int
+	for _, j := range jobs {
+		jobUUID, err := parseDumpJobID(j.id)
+		if err != nil {
+			jobsSkipped++
+			continue
+		}
+		var userID *uuid.UUID
+		if uid, ok := userByLegacy[j.userLegacy]; ok {
+			userID = &uid
+		}
+		status := normalizeProcessingJobStatus(j.status)
+		ptype := strings.TrimSpace(j.processingType)
+		if ptype == "" {
+			ptype = "full"
+		}
+		var errPtr *string
+		if j.errText != "" {
+			v := j.errText
+			errPtr = &v
+		}
+		_, err = pg.Exec(ctx, `
+			INSERT INTO processing_jobs (
+				id, company_id, user_id, status, total_products, processed_products,
+				error, processing_type, priority, estimated_tokens,
+				started_at, completed_at, created_at, updated_at,
+				current_step, step_progress, ai_provider_mode
+			) VALUES (
+				$1, $2, $3, $4, $5, $6,
+				$7, $8, $9, $10,
+				$11, $12, $13, $14,
+				'', '[]'::jsonb, 'migrated'
+			)
+			ON CONFLICT (id) DO UPDATE SET
+				company_id = EXCLUDED.company_id,
+				user_id = COALESCE(EXCLUDED.user_id, processing_jobs.user_id),
+				status = EXCLUDED.status,
+				total_products = EXCLUDED.total_products,
+				processed_products = EXCLUDED.processed_products,
+				error = EXCLUDED.error,
+				processing_type = EXCLUDED.processing_type,
+				priority = EXCLUDED.priority,
+				estimated_tokens = EXCLUDED.estimated_tokens,
+				started_at = EXCLUDED.started_at,
+				completed_at = EXCLUDED.completed_at,
+				created_at = EXCLUDED.created_at,
+				updated_at = EXCLUDED.updated_at,
+				ai_provider_mode = 'migrated'`,
+			jobUUID, companyID, userID, status,
+			j.totalProducts, j.processedProducts,
+			errPtr, ptype, j.priority, j.estimatedTokens,
+			j.startedAt, j.completedAt, j.createdAt, j.updatedAt,
+		)
+		if err != nil {
+			log.Printf("job %s: %v", j.id, err)
+			jobsSkipped++
+			continue
+		}
+		jobsUpserted++
+	}
+
+	var pjpUpserted, pjpSkipped int
+	for _, row := range pjpRows {
+		jobUUID, err := parseDumpJobID(row.jobID)
+		if err != nil {
+			pjpSkipped++
+			continue
+		}
+		gtin, ok := gtinByLegacy[row.rawLegacy]
+		if !ok || gtin == "" {
+			pjpSkipped++
+			continue
+		}
+		rawUUID, ok := rawByGTIN[gtin]
+		if !ok {
+			pjpSkipped++
+			continue
+		}
+		prodID := uuid.NewSHA1(uuid.NameSpaceOID, []byte("pjp:"+strconv.FormatInt(row.legacyID, 10)))
+		var errPtr *string
+		if row.errText != "" {
+			v := row.errText
+			errPtr = &v
+		}
+		_, err = pg.Exec(ctx, `
+			INSERT INTO processing_job_products (
+				id, job_id, raw_product_id, status, error, processed_product_id, created_at, updated_at
+			) VALUES ($1, $2, $3, $4, $5, NULL, $6, $7)
+			ON CONFLICT (id) DO UPDATE SET
+				status = EXCLUDED.status,
+				error = EXCLUDED.error,
+				raw_product_id = EXCLUDED.raw_product_id,
+				updated_at = EXCLUDED.updated_at`,
+			prodID, jobUUID, rawUUID, normalizeJobProductStatus(row.status), errPtr,
+			row.createdAt, row.updatedAt,
+		)
+		if err != nil {
+			pjpSkipped++
+			continue
+		}
+		pjpUpserted++
+	}
+
+	var liveJobs, livePJP int
+	_ = pg.QueryRow(ctx, `SELECT count(*) FROM processing_jobs WHERE company_id=$1`, companyID).Scan(&liveJobs)
+	_ = pg.QueryRow(ctx, `SELECT count(*) FROM processing_job_products WHERE job_id IN (SELECT id FROM processing_jobs WHERE company_id=$1)`, companyID).Scan(&livePJP)
+	log.Printf("recover-jobs done: jobs_upserted=%d skipped=%d pjp_upserted=%d skipped=%d live_jobs=%d live_job_products=%d",
+		jobsUpserted, jobsSkipped, pjpUpserted, pjpSkipped, liveJobs, livePJP)
+	return nil
+}
+
+type dumpJob struct {
+	id                               string
+	userLegacy                       string
+	status, processingType, errText  string
+	totalProducts, processedProducts int
+	priority, estimatedTokens        int
+	startedAt, completedAt           *time.Time
+	createdAt, updatedAt             time.Time
+}
+
+type dumpJobProduct struct {
+	legacyID             int64
+	jobID, rawLegacy     string
+	status, errText      string
+	createdAt, updatedAt time.Time
+}
+
+func loadUserLegacyMap(ctx context.Context, pg *pgxpool.Pool, companyID uuid.UUID) (map[string]uuid.UUID, error) {
+	rows, err := pg.Query(ctx, `
+		SELECT u.id, COALESCE(u.legacy_user_id, '')
+		FROM users u
+		JOIN memberships m ON m.user_id = u.id
+		WHERE m.company_id = $1 AND COALESCE(u.legacy_user_id, '') <> ''`, companyID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	out := map[string]uuid.UUID{}
+	for rows.Next() {
+		var id uuid.UUID
+		var legacy string
+		if err := rows.Scan(&id, &legacy); err != nil {
+			return nil, err
+		}
+		out[legacy] = id
+	}
+	return out, rows.Err()
+}
+
+func loadRawByGTIN(ctx context.Context, pg *pgxpool.Pool, companyID uuid.UUID, gtinByLegacy map[string]string) (map[string]uuid.UUID, error) {
+	uniq := make([]string, 0, len(gtinByLegacy))
+	seen := map[string]struct{}{}
+	for _, g := range gtinByLegacy {
+		g = strings.TrimSpace(g)
+		if g == "" {
+			continue
+		}
+		if _, ok := seen[g]; ok {
+			continue
+		}
+		seen[g] = struct{}{}
+		uniq = append(uniq, g)
+	}
+	out := map[string]uuid.UUID{}
+	if len(uniq) == 0 {
+		return out, nil
+	}
+	rows, err := pg.Query(ctx, `
+		SELECT gtin, id FROM raw_products
+		WHERE company_id = $1 AND gtin = ANY($2)`, companyID, uniq)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	for rows.Next() {
+		var gtin string
+		var id uuid.UUID
+		if err := rows.Scan(&gtin, &id); err != nil {
+			return nil, err
+		}
+		out[gtin] = id
+	}
+	return out, rows.Err()
+}
+
+func scanA1ProcessingJobs(r io.Reader, legacyCompany string) ([]dumpJob, error) {
+	br := bufio.NewReaderSize(r, 4<<20)
+	mode := false
+	var out []dumpJob
+	for {
+		line, err := br.ReadString('\n')
+		if strings.HasPrefix(line, "INSERT INTO `processing_jobs`") {
+			mode = true
+		} else if mode && dumpSectionEnded(line, "processing_jobs") {
+			mode = false
+		}
+		if mode && strings.Contains(line, "'"+legacyCompany+"'") {
+			fields := parseMySQLTupleFields(line)
+			// id, user_id, company_id, status, total, processed, error, started, completed, created, updated, type, priority, estimated
+			if len(fields) >= 14 && fields[2] == legacyCompany {
+				j := dumpJob{
+					id:                fields[0],
+					userLegacy:        nullish(fields[1]),
+					status:            fields[3],
+					totalProducts:     atoiDefault(fields[4], 0),
+					processedProducts: atoiDefault(fields[5], 0),
+					errText:           nullish(fields[6]),
+					startedAt:         parseDumpTimePtr(fields[7]),
+					completedAt:       parseDumpTimePtr(fields[8]),
+					createdAt:         parseDumpTime(fields[9]),
+					updatedAt:         parseDumpTime(fields[10]),
+					processingType:    nullish(fields[11]),
+					priority:          atoiDefault(fields[12], 0),
+					estimatedTokens:   atoiDefault(fields[13], 0),
+				}
+				if j.createdAt.IsZero() {
+					j.createdAt = time.Now().UTC()
+				}
+				if j.updatedAt.IsZero() {
+					j.updatedAt = j.createdAt
+				}
+				out = append(out, j)
+			}
+		}
+		if err == io.EOF {
+			break
+		}
+		if err != nil {
+			return nil, err
+		}
+	}
+	return out, nil
+}
+
+func scanA1JobProducts(r io.Reader, jobIDs map[string]struct{}) ([]dumpJobProduct, map[string]struct{}, error) {
+	br := bufio.NewReaderSize(r, 4<<20)
+	mode := false
+	var out []dumpJobProduct
+	rawIDs := map[string]struct{}{}
+	for {
+		line, err := br.ReadString('\n')
+		if strings.HasPrefix(line, "INSERT INTO `processing_job_products`") {
+			mode = true
+		} else if mode && dumpSectionEnded(line, "processing_job_products") {
+			mode = false
+		}
+		if mode && looksLikeTupleLine(line) {
+			fields := parseMySQLTupleFields(line)
+			// id, job_id, raw_product_id, status, error, processed_product_id, created, updated
+			if len(fields) >= 8 {
+				if _, ok := jobIDs[fields[1]]; ok {
+					legacyID, _ := strconv.ParseInt(fields[0], 10, 64)
+					row := dumpJobProduct{
+						legacyID:  legacyID,
+						jobID:     fields[1],
+						rawLegacy: fields[2],
+						status:    fields[3],
+						errText:   nullish(fields[4]),
+						createdAt: parseDumpTime(fields[6]),
+						updatedAt: parseDumpTime(fields[7]),
+					}
+					if row.createdAt.IsZero() {
+						row.createdAt = time.Now().UTC()
+					}
+					if row.updatedAt.IsZero() {
+						row.updatedAt = row.createdAt
+					}
+					out = append(out, row)
+					rawIDs[row.rawLegacy] = struct{}{}
+				}
+			}
+		}
+		if err == io.EOF {
+			break
+		}
+		if err != nil {
+			return nil, nil, err
+		}
+	}
+	return out, rawIDs, nil
+}
+
+func scanRawProductGTINs(r io.Reader, want map[string]struct{}, legacyCompany string) (map[string]string, error) {
+	br := bufio.NewReaderSize(r, 4<<20)
+	mode := false
+	out := map[string]string{}
+	remaining := len(want)
+	for remaining > 0 {
+		line, err := br.ReadString('\n')
+		if strings.HasPrefix(line, "INSERT INTO `raw_products`") {
+			mode = true
+		} else if mode && dumpSectionEnded(line, "raw_products") {
+			mode = false
+		}
+		if mode && looksLikeTupleLine(line) {
+			// Need id + gtin; company is field index 4 in this dump schema:
+			// id, gtin, feed_id, feed_ids, company_id, raw_data, ...
+			fields := parseMySQLTupleFieldsN(line, 5)
+			if len(fields) >= 5 {
+				id := fields[0]
+				if _, ok := want[id]; ok && fields[4] == legacyCompany {
+					gtin := strings.TrimSpace(nullish(fields[1]))
+					if gtin != "" {
+						out[id] = gtin
+						remaining--
+					}
+				}
+			}
+		}
+		if err == io.EOF {
+			break
+		}
+		if err != nil {
+			return nil, err
+		}
+	}
+	return out, nil
+}
+
+func dumpSectionEnded(line, table string) bool {
+	if strings.HasPrefix(line, "CREATE TABLE") || strings.HasPrefix(line, "UNLOCK TABLES") || strings.HasPrefix(line, "LOCK TABLES") {
+		return true
+	}
+	if strings.HasPrefix(line, "INSERT INTO `") && !strings.HasPrefix(line, "INSERT INTO `"+table+"`") {
+		return true
+	}
+	if strings.HasPrefix(line, "DROP TABLE") {
+		return true
+	}
+	return false
+}
+
+func looksLikeTupleLine(line string) bool {
+	s := strings.TrimLeft(line, " \t")
+	return strings.HasPrefix(s, "(")
+}
+
+func parseMySQLTupleFields(line string) []string {
+	return parseMySQLTupleFieldsN(line, 0)
+}
+
+// parseMySQLTupleFieldsN parses up to maxFields (0 = all) from the first (...) tuple on the line.
+func parseMySQLTupleFieldsN(line string, maxFields int) []string {
+	start := strings.Index(line, "(")
+	if start < 0 {
+		return nil
+	}
+	body := line[start+1:]
+	var out []string
+	for i := 0; i < len(body); {
+		if maxFields > 0 && len(out) >= maxFields {
+			break
+		}
+		for i < len(body) && (body[i] == ' ' || body[i] == '\t' || body[i] == ',') {
+			i++
+		}
+		if i >= len(body) || body[i] == ')' {
+			break
+		}
+		if body[i] == '\'' {
+			i++
+			var b strings.Builder
+			for i < len(body) {
+				ch := body[i]
+				if ch == '\\' && i+1 < len(body) {
+					b.WriteByte(body[i+1])
+					i += 2
+					continue
+				}
+				if ch == '\'' {
+					if i+1 < len(body) && body[i+1] == '\'' {
+						b.WriteByte('\'')
+						i += 2
+						continue
+					}
+					i++
+					break
+				}
+				b.WriteByte(ch)
+				i++
+			}
+			out = append(out, b.String())
+			continue
+		}
+		j := i
+		for j < len(body) && body[j] != ',' && body[j] != ')' {
+			j++
+		}
+		out = append(out, strings.TrimSpace(body[i:j]))
+		i = j
+	}
+	return out
+}
+
+func parseDumpJobID(raw string) (uuid.UUID, error) {
+	raw = strings.TrimSpace(raw)
+	if id, err := uuid.Parse(raw); err == nil {
+		return id, nil
+	}
+	// Legacy dump mixes UUID and numeric string PKs — keep remaps stable (migrator parity).
+	return uuid.NewSHA1(uuid.NameSpaceOID, []byte("processing_job:"+raw)), nil
+}
+
+func nullish(s string) string {
+	s = strings.TrimSpace(s)
+	if s == "" || strings.EqualFold(s, "NULL") {
+		return ""
+	}
+	return s
+}
+
+func atoiDefault(s string, def int) int {
+	s = nullish(s)
+	if s == "" {
+		return def
+	}
+	n, err := strconv.Atoi(s)
+	if err != nil {
+		return def
+	}
+	return n
+}
+
+func parseDumpTime(s string) time.Time {
+	s = nullish(s)
+	if s == "" {
+		return time.Time{}
+	}
+	for _, layout := range []string{
+		"2006-01-02 15:04:05",
+		time.RFC3339,
+		"2006-01-02 15:04:05.000",
+	} {
+		if t, err := time.ParseInLocation(layout, s, time.UTC); err == nil {
+			return t.UTC()
+		}
+	}
+	return time.Time{}
+}
+
+func parseDumpTimePtr(s string) *time.Time {
+	t := parseDumpTime(s)
+	if t.IsZero() {
+		return nil
+	}
+	return &t
+}
+
+func normalizeProcessingJobStatus(raw string) string {
+	switch strings.ToLower(strings.TrimSpace(raw)) {
+	case "completed", "success", "done":
+		return "completed"
+	case "failed", "error":
+		return "failed"
+	case "cancelled", "canceled", "skipped":
+		return "cancelled"
+	case "running", "processing":
+		return "running"
+	case "pending", "queued":
+		return "pending"
+	default:
+		return "failed"
+	}
+}
+
+func normalizeJobProductStatus(raw string) string {
+	switch strings.ToLower(strings.TrimSpace(raw)) {
+	case "processed", "completed", "success", "done":
+		return "processed"
+	case "failed", "error":
+		return "failed"
+	case "cancelled", "canceled", "skipped":
+		return "cancelled"
+	case "processing", "running":
+		return "processing"
+	case "pending", "queued":
+		return "pending"
+	default:
+		return "failed"
+	}
+}

apps/api/cmd/seed-a1/recover_jobs_test.go

@@ -0,0 +1,61 @@
+package main
+
+import (
+	"os"
+	"testing"
+)
+
+func TestScanA1ProcessingJobsSmoke(t *testing.T) {
+	dump := os.Getenv("SEED_A1_MYSQL_DUMP")
+	if dump == "" {
+		dump = `d:\Users\Green Eclipse\Downloads\descrybe_new.sql`
+	}
+	if _, err := os.Stat(dump); err != nil {
+		t.Skipf("mysql dump not available: %v", err)
+	}
+	f, err := os.Open(dump)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer f.Close()
+	jobs, err := scanA1ProcessingJobs(f, "97e1a309-3d23-4aa2-b518-8e8d7afdfec7")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(jobs) < 100 {
+		t.Fatalf("expected many A1 jobs, got %d", len(jobs))
+	}
+	has := false
+	for _, j := range jobs {
+		if j.id == "827f0b82-3214-4c1d-bf05-2455bbd66fc6" {
+			has = true
+			if j.status != "completed" || j.totalProducts != 1 {
+				t.Fatalf("target job unexpected status=%s total=%d", j.status, j.totalProducts)
+			}
+		}
+	}
+	if !has {
+		t.Fatal("missing target job 827f0b82-…")
+	}
+}
+
+func TestParseMySQLTupleFields(t *testing.T) {
+	fields := parseMySQLTupleFields("('827f0b82-3214-4c1d-bf05-2455bbd66fc6',\t'user_x',\t'97e1a309-3d23-4aa2-b518-8e8d7afdfec7',\t'completed',\t1,\t1,\tNULL,\t'2026-07-31 08:36:45',\t'2026-07-31 08:36:58',\t'2026-07-31 08:36:45',\t'2026-07-31 08:36:58',\t'full',\tNULL,\t7500),")
+	if len(fields) < 14 {
+		t.Fatalf("fields=%d %#v", len(fields), fields)
+	}
+	if fields[0] != "827f0b82-3214-4c1d-bf05-2455bbd66fc6" || fields[2] != "97e1a309-3d23-4aa2-b518-8e8d7afdfec7" {
+		t.Fatalf("unexpected fields %#v", fields)
+	}
+}
+
+func TestParseDumpJobID(t *testing.T) {
+	id, err := parseDumpJobID("827f0b82-3214-4c1d-bf05-2455bbd66fc6")
+	if err != nil || id.String() != "827f0b82-3214-4c1d-bf05-2455bbd66fc6" {
+		t.Fatalf("uuid parse: %v %s", err, id)
+	}
+	sha, err := parseDumpJobID("12345")
+	if err != nil || sha.String() == "12345" {
+		t.Fatalf("sha1 remap expected, got %v %s", err, sha)
+	}
+}

apps/api/cmd/seed-demo/fixture_isolation_test.go

@@ -0,0 +1,54 @@
+package main
+
+import (
+	"context"
+	"os"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/descrybe/descrybe-v2/apps/api/internal/billing"
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// Postman A1 Elkotex fixtures — must not appear on Platform Demo / other tenants.
+var postmanA1FixtureEANs = []string{"5905575903198", "6970995789942"}
+
+// Integration: Postman Elkotex fixture EANs must not appear outside A1.
+func TestA1FixtureEANsIsolatedFromDemo(t *testing.T) {
+	dsn := strings.TrimSpace(os.Getenv("DATABASE_URL"))
+	if dsn == "" {
+		t.Skip("DATABASE_URL not set")
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+	pg, err := pgxpool.New(ctx, dsn)
+	if err != nil {
+		t.Fatalf("postgres: %v", err)
+	}
+	defer pg.Close()
+
+	var a1ID uuid.UUID
+	err = pg.QueryRow(ctx, `
+		SELECT id FROM companies
+		WHERE legacy_company_id = $1 OR name = $2
+		ORDER BY (legacy_company_id = $1) DESC
+		LIMIT 1`, billing.A1LegacyCompanyID, a1CompanyName).Scan(&a1ID)
+	if err != nil {
+		t.Fatalf("resolve A1: %v (run migrate + seed-a1 first)", err)
+	}
+
+	var otherRaw, otherPP int
+	err = pg.QueryRow(ctx, `
+		SELECT
+			(SELECT COUNT(*) FROM raw_products WHERE company_id <> $1 AND gtin = ANY($2::text[])),
+			(SELECT COUNT(*) FROM processed_products WHERE company_id <> $1 AND product_id = ANY($2::text[]))`,
+		a1ID, postmanA1FixtureEANs).Scan(&otherRaw, &otherPP)
+	if err != nil {
+		t.Fatalf("count other-tenant fixtures: %v", err)
+	}
+	if otherRaw > 0 || otherPP > 0 {
+		t.Fatalf("A1 fixture EANs on non-A1 tenants: raw=%d processed=%d (run seed-a1 -mode backfill-categories or npm run seed:a1)", otherRaw, otherPP)
+	}
+}

apps/api/cmd/seed-demo/main.go

@@ -0,0 +1,759 @@
+// Command seed-demo upserts a local demo user with argon2id password,
+// platform-admin flag, and admin membership on a standalone Platform Demo
+// company only (never A1 / migrated customer tenants).
+// Assigns a custom full-feature "Platform Demo" plan for staff QA.
+//
+// Usage:
+//
+//	go run ./cmd/seed-demo -postgres "$DATABASE_URL"
+//	go run ./cmd/seed-demo -email demo@descrybe.local -password 'DemoPass123!'
+//	go run ./cmd/seed-demo -local-demo-name "Platform Demo"
+package main
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"log"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/descrybe/descrybe-v2/apps/api/internal/auth"
+	"github.com/descrybe/descrybe-v2/apps/api/internal/billing"
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// defaultDemoAPIKey is local/staging only. Documented in docs/demo-user.md.
+// Never reuse in production.
+const defaultDemoAPIKey = "dk_demo_local_descrybe_test_key_v1"
+
+const defaultLocalDemoName = "Platform Demo"
+const platformDemoPlanName = "Platform Demo"
+
+func main() {
+	postgresURL := flag.String("postgres", os.Getenv("DATABASE_URL"), "Postgres URL")
+	email := flag.String("email", "demo@descrybe.local", "Demo user email (canonical)")
+	alsoEmail := flag.String("also-email", "demo@descrybe.test", "Optional second demo email to upsert with the same password (empty to skip)")
+	password := flag.String("password", "DemoPass123!", "Demo user password")
+	name := flag.String("name", "Demo User", "Display name")
+	apiKeyFlag := flag.String("api-key", defaultDemoAPIKey, "Demo API key plaintext (hashed before store)")
+	localDemoName := flag.String("local-demo-name", defaultLocalDemoName, "Standalone demo sandbox company name (not A1)")
+	claimRichest := flag.Bool("claim-richest", false, "DANGEROUS: move richest non-A1 catalog onto the demo company (off by default)")
+	purgeSmokeEANs := flag.Bool("purge-smoke-eans", false, "Hard-delete process-smoke EANs (8700999...) from Platform Demo only; never A1 (no product soft-delete API)")
+	flag.Parse()
+
+	if strings.TrimSpace(*postgresURL) == "" {
+		log.Fatal("-postgres / DATABASE_URL is required")
+	}
+	emailNorm := strings.ToLower(strings.TrimSpace(*email))
+	if emailNorm == "" || *password == "" {
+		log.Fatal("-email and -password are required")
+	}
+	alsoEmailNorm := strings.ToLower(strings.TrimSpace(*alsoEmail))
+	if alsoEmailNorm == emailNorm {
+		alsoEmailNorm = ""
+	}
+	demoCompanyName := strings.TrimSpace(*localDemoName)
+	if demoCompanyName == "" {
+		log.Fatal("-local-demo-name is required")
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Minute)
+	defer cancel()
+
+	pg, err := pgxpool.New(ctx, *postgresURL)
+	if err != nil {
+		log.Fatalf("postgres: %v", err)
+	}
+	defer pg.Close()
+
+	hash, err := auth.HashPassword(*password)
+	if err != nil {
+		log.Fatalf("hash password: %v", err)
+	}
+
+	tx, err := pg.Begin(ctx)
+	if err != nil {
+		log.Fatalf("begin: %v", err)
+	}
+	defer tx.Rollback(ctx)
+
+	var userID uuid.UUID
+	err = tx.QueryRow(ctx, `
+		INSERT INTO users (
+			email, name, password_hash, must_set_password,
+			is_platform_admin, is_active, updated_at
+		) VALUES ($1, $2, $3, false, true, true, now())
+		ON CONFLICT (email) DO UPDATE SET
+			name = EXCLUDED.name,
+			password_hash = EXCLUDED.password_hash,
+			must_set_password = false,
+			is_platform_admin = true,
+			is_active = true,
+			updated_at = now()
+		RETURNING id`, emailNorm, strings.TrimSpace(*name), hash).Scan(&userID)
+	if err != nil {
+		log.Fatalf("upsert user: %v", err)
+	}
+
+	var alsoUserID uuid.UUID
+	if alsoEmailNorm != "" {
+		err = tx.QueryRow(ctx, `
+			INSERT INTO users (
+				email, name, password_hash, must_set_password,
+				is_platform_admin, is_active, updated_at
+			) VALUES ($1, $2, $3, false, true, true, now())
+			ON CONFLICT (email) DO UPDATE SET
+				name = EXCLUDED.name,
+				password_hash = EXCLUDED.password_hash,
+				must_set_password = false,
+				is_platform_admin = true,
+				is_active = true,
+				updated_at = now()
+			RETURNING id`, alsoEmailNorm, strings.TrimSpace(*name), hash).Scan(&alsoUserID)
+		if err != nil {
+			log.Fatalf("upsert also-email user: %v", err)
+		}
+	}
+
+	localDemoID, renameNote, err := ensureStandaloneDemoCompany(ctx, tx, demoCompanyName)
+	if err != nil {
+		log.Fatalf("ensure Platform Demo company: %v", err)
+	}
+
+	var claimNote string
+	if *claimRichest {
+		claimNote, err = claimRichestCatalog(ctx, tx, localDemoID, demoCompanyName)
+		if err != nil {
+			log.Fatalf("claim richest catalog: %v", err)
+		}
+	} else {
+		claimNote = "skipped (-claim-richest=false; demo sandbox stays isolated from A1)"
+	}
+
+	var smokePurgeNote string
+	if *purgeSmokeEANs {
+		rawN, ppN, purgeErr := purgeProcessSmokeEANsFromDemo(ctx, tx, localDemoID, demoCompanyName)
+		if purgeErr != nil {
+			log.Fatalf("purge process-smoke EANs: %v", purgeErr)
+		}
+		smokePurgeNote = fmt.Sprintf("purged process-smoke EANs (8700999...) from %s: raw=%d processed=%d", demoCompanyName, rawN, ppN)
+	} else {
+		smokePurgeNote = "skipped (-purge-smoke-eans=false; optional Demo cleanup - see scripts/cleanup-process-smoke-eans.sql)"
+	}
+
+	memberships, err := bindDemoUserToCompanyOnly(ctx, tx, userID, localDemoID)
+	if err != nil {
+		log.Fatalf("upsert demo memberships: %v", err)
+	}
+	var alsoMemberships int64
+	if alsoUserID != uuid.Nil {
+		alsoMemberships, err = bindDemoUserToCompanyOnly(ctx, tx, alsoUserID, localDemoID)
+		if err != nil {
+			log.Fatalf("upsert also-email memberships: %v", err)
+		}
+	}
+
+	// Demo API key + session land on the isolated Platform Demo tenant — not A1.
+	primaryCompanyID := localDemoID
+
+	const demoAPIKeyName = "Demo local API key"
+	demoAPIKey := strings.TrimSpace(*apiKeyFlag)
+	if demoAPIKey == "" {
+		demoAPIKey = defaultDemoAPIKey
+	}
+	if !strings.HasPrefix(demoAPIKey, "dk_") {
+		log.Fatal("demo API key must start with dk_")
+	}
+	keyHash := auth.HashAPIKey(demoAPIKey)
+	keyPrefix := demoAPIKey
+	if len(keyPrefix) > 10 {
+		keyPrefix = keyPrefix[:10]
+	}
+
+	_, err = tx.Exec(ctx, `
+		UPDATE api_keys SET revoked_at = now(), updated_at = now()
+		WHERE company_id = $1 AND name = $2 AND key_hash <> $3 AND revoked_at IS NULL`,
+		primaryCompanyID, demoAPIKeyName, keyHash)
+	if err != nil {
+		log.Fatalf("revoke old demo keys: %v", err)
+	}
+	_, err = tx.Exec(ctx, `
+		INSERT INTO api_keys (company_id, user_id, name, key_hash, key_prefix)
+		VALUES ($1, $2, $3, $4, $5)
+		ON CONFLICT (key_hash) DO UPDATE SET
+			company_id = EXCLUDED.company_id,
+			user_id = EXCLUDED.user_id,
+			name = EXCLUDED.name,
+			key_prefix = EXCLUDED.key_prefix,
+			revoked_at = NULL,
+			updated_at = now()`,
+		primaryCompanyID, userID, demoAPIKeyName, keyHash, keyPrefix)
+	if err != nil {
+		log.Fatalf("upsert demo api key: %v", err)
+	}
+
+	if err := tx.Commit(ctx); err != nil {
+		log.Fatalf("commit: %v", err)
+	}
+
+	billingSvc := &billing.Service{Pool: pg}
+	if err := billingSvc.EnsureDefaultPlans(ctx); err != nil {
+		log.Fatalf("EnsureDefaultPlans: %v", err)
+	}
+	// Guard: Enterprise seed must leave Free packaging intact for new signups.
+	var freeCredits int
+	var freeMax *int
+	err = pg.QueryRow(ctx, `
+		SELECT monthly_credits, max_products FROM plans WHERE lower(name) = 'free' ORDER BY id LIMIT 1`).
+		Scan(&freeCredits, &freeMax)
+	if err != nil {
+		log.Fatalf("Free plan missing after EnsureDefaultPlans: %v", err)
+	}
+	if freeCredits != 0 {
+		log.Fatalf("Free plan monthly_credits=%d want 0 (Enterprise seed regression)", freeCredits)
+	}
+	wantFreeMax := billing.PlanMaxProducts("Free")
+	if wantFreeMax == nil || freeMax == nil || *freeMax != *wantFreeMax {
+		got := "nil"
+		if freeMax != nil {
+			got = fmt.Sprintf("%d", *freeMax)
+		}
+		want := "nil"
+		if wantFreeMax != nil {
+			want = fmt.Sprintf("%d", *wantFreeMax)
+		}
+		log.Fatalf("Free plan max_products=%s want %s", got, want)
+	}
+	var planID int64
+	planAssignName := platformDemoPlanName
+	err = pg.QueryRow(ctx, `SELECT id FROM plans WHERE lower(name) = lower($1) ORDER BY id LIMIT 1`, platformDemoPlanName).Scan(&planID)
+	if err != nil {
+		if err != pgx.ErrNoRows {
+			log.Fatalf("lookup %s plan: %v", platformDemoPlanName, err)
+		}
+		desc := "Local staff sandbox — full product features, high credits, unlimited SKUs (not a Stripe product)"
+		err = pg.QueryRow(ctx, `
+			INSERT INTO plans (
+				name, description, monthly_credits, yearly_credits, max_products,
+				is_custom, is_legacy, term, features
+			) VALUES (
+				$1, $2, $3, NULL, NULL, true, false, 'monthly', '{}'::jsonb
+			) RETURNING id`,
+			platformDemoPlanName, desc, billing.EnterpriseUnlimitedCredits,
+		).Scan(&planID)
+		if err != nil {
+			log.Fatalf("create %s plan: %v", platformDemoPlanName, err)
+		}
+	} else {
+		_, err = pg.Exec(ctx, `
+			UPDATE plans SET
+				monthly_credits = $2,
+				yearly_credits = NULL,
+				max_products = NULL,
+				is_custom = true,
+				is_legacy = false,
+				term = 'monthly',
+				features = COALESCE(features, '{}'::jsonb),
+				updated_at = now()
+			WHERE id = $1`, planID, billing.EnterpriseUnlimitedCredits)
+		if err != nil {
+			log.Fatalf("refresh %s plan packaging: %v", platformDemoPlanName, err)
+		}
+	}
+
+	if err := billingSvc.AssignPlan(ctx, primaryCompanyID, planID, false, 0); err != nil {
+		log.Fatalf("AssignPlan %s %s: %v", planAssignName, primaryCompanyID, err)
+	}
+	// Keep a generous wallet for QA (AssignPlan already sets total from monthly_credits).
+	_, err = pg.Exec(ctx, `
+		UPDATE credit_balances SET total_credits = GREATEST(total_credits, $2), updated_at = now()
+		WHERE company_id = $1`, primaryCompanyID, billing.EnterpriseUnlimitedCredits)
+	if err != nil {
+		log.Fatalf("ensure demo wallet: %v", err)
+	}
+	// Platform Demo QA expects marketing (and related) master switches ON. Global
+	// platform_feature_gates can leave sections/features OFF from prior admin toggles;
+	// re-seed must restore the full-feature sandbox docs promise.
+	marketingGateFeatures := map[string]bool{
+		"marketing.brand_ai_apply":        true,
+		"marketing.brand_kit":             true,
+		"marketing.campaigns":             true,
+		"marketing.campaigns.create":      true,
+		"marketing.campaigns.generate_ai": true,
+		"marketing.campaigns.send":        true,
+		"marketing.content_calendar":      true,
+		"marketing.reviews":               true,
+		"marketing.seo":                   true,
+		"marketing.seo.ai_rewrite":        true,
+		"marketing.seo.template_fill":     true,
+		"capability.brand_ai_apply":       true,
+		"capability.campaign_ai":          true,
+		"capability.seo_ai_rewrite":       true,
+		"integrations.email":              true,
+		"integrations.email.test":         true,
+	}
+	if _, err := billingSvc.SetFeatureGates(ctx, map[string]bool{
+		"marketing":    true,
+		"integrations": true,
+	}, marketingGateFeatures, &userID); err != nil {
+		log.Fatalf("enable Platform Demo marketing feature gates: %v", err)
+	}
+
+	planName, monthly, maxProducts, isCustom, total, used, rem, err := loadCompanyPlanCredits(ctx, pg, primaryCompanyID)
+	if err != nil {
+		log.Fatalf("verify %s credits: %v", planAssignName, err)
+	}
+	if !strings.EqualFold(planName, platformDemoPlanName) {
+		log.Fatalf("plan verify failed: plan=%s want %s", planName, platformDemoPlanName)
+	}
+	if !isCustom {
+		log.Fatalf("plan verify failed: %s must be is_custom=true for full feature matrix", planName)
+	}
+	maxNote := "null (unlimited SKUs)"
+	if maxProducts != nil {
+		maxNote = fmt.Sprintf("%d", *maxProducts)
+	}
+	log.Printf("demo primary company %s → %s (monthly=%d max_products=%s is_custom=%v total=%d used=%d remaining=%d)",
+		primaryCompanyID, planName, monthly, maxNote, isCustom, total, used, rem)
+
+	type companyStats struct {
+		ID          uuid.UUID
+		Name        string
+		InputFeeds  int64
+		Products    int64
+		RawProducts int64
+		ExportFeeds int64
+		Categories  int64
+		Mappings    int64
+	}
+
+	rows, err := pg.Query(ctx, `
+		SELECT c.id, c.name,
+			(SELECT COUNT(*) FROM input_feeds f WHERE f.company_id = c.id),
+			(SELECT COUNT(*) FROM processed_products p WHERE p.company_id = c.id),
+			(SELECT COUNT(*) FROM raw_products rp WHERE rp.company_id = c.id),
+			(SELECT COUNT(*) FROM export_feeds ef WHERE ef.company_id = c.id),
+			(SELECT COUNT(*) FROM categories cat WHERE cat.company_id = c.id),
+			(SELECT COUNT(*) FROM feed_mappings fm
+				JOIN input_feeds f ON f.id = fm.feed_id WHERE f.company_id = c.id)
+		FROM companies c
+		JOIN memberships m ON m.company_id = c.id AND m.user_id = $1 AND m.status = 'active'
+		ORDER BY
+			CASE WHEN c.id = $2 THEN 0 ELSE 1 END,
+			(SELECT COUNT(*) FROM processed_products p WHERE p.company_id = c.id) DESC,
+			(SELECT COUNT(*) FROM input_feeds f WHERE f.company_id = c.id) DESC,
+			c.name`, userID, localDemoID)
+	if err != nil {
+		log.Fatalf("stats: %v", err)
+	}
+	defer rows.Close()
+
+	var companies []companyStats
+	for rows.Next() {
+		var c companyStats
+		if err := rows.Scan(&c.ID, &c.Name, &c.InputFeeds, &c.Products, &c.RawProducts, &c.ExportFeeds, &c.Categories, &c.Mappings); err != nil {
+			log.Fatalf("scan stats: %v", err)
+		}
+		companies = append(companies, c)
+	}
+	if err := rows.Err(); err != nil {
+		log.Fatalf("stats rows: %v", err)
+	}
+
+	fmt.Println("=== Descrybe v2 demo user ===")
+	fmt.Printf("email:              %s\n", emailNorm)
+	if alsoEmailNorm != "" {
+		fmt.Printf("also email:         %s (same password; memberships=%d)\n", alsoEmailNorm, alsoMemberships)
+	}
+	fmt.Printf("password:           %s\n", *password)
+	fmt.Printf("user_id:            %s\n", userID)
+	fmt.Printf("must_set_password:  false\n")
+	fmt.Printf("is_platform_admin:  true\n")
+	fmt.Printf("is_active:          true\n")
+	fmt.Printf("admin memberships:  %d\n", memberships)
+	fmt.Printf("demo company:       %s\n", renameNote)
+	fmt.Printf("claim richest:      %s\n", claimNote)
+	fmt.Printf("smoke EANs:         %s\n", smokePurgeNote)
+	fmt.Printf("plan:               %s (monthly_credits=%d max_products=%s is_custom=%v)\n",
+		planName, monthly, maxNote, isCustom)
+	fmt.Printf("credits:            total=%d used=%d remaining=%d\n", total, used, rem)
+	if len(companies) == 0 {
+		fmt.Println("WARNING: no companies found — migrate data first")
+		return
+	}
+
+	var localStats *companyStats
+	for i := range companies {
+		if companies[i].ID == localDemoID {
+			localStats = &companies[i]
+			break
+		}
+	}
+	if localStats == nil {
+		fmt.Printf("WARNING: %s missing from membership stats\n", demoCompanyName)
+	} else {
+		fmt.Println()
+		fmt.Printf("Primary company (%s):\n", demoCompanyName)
+		fmt.Printf("  name:          %s\n", localStats.Name)
+		fmt.Printf("  id:            %s\n", localStats.ID)
+		fmt.Printf("  input_feeds:   %d\n", localStats.InputFeeds)
+		fmt.Printf("  products:      %d\n", localStats.Products)
+		fmt.Printf("  raw_products:  %d\n", localStats.RawProducts)
+		fmt.Printf("  export_feeds:  %d\n", localStats.ExportFeeds)
+		fmt.Printf("  categories:    %d\n", localStats.Categories)
+		fmt.Printf("  mappings:      %d\n", localStats.Mappings)
+	}
+
+	fmt.Println()
+	fmt.Println("Feeds + mapping counts for Platform Demo:")
+	feedRows, err := pg.Query(ctx, `
+		SELECT f.name,
+			(SELECT COUNT(*) FROM feed_mappings fm WHERE fm.feed_id = f.id) AS mapping_count,
+			(SELECT COUNT(*) FROM feed_mappings fm WHERE fm.feed_id = f.id AND fm.company_id <> f.company_id) AS orphan_company_mismatch
+		FROM input_feeds f
+		WHERE f.company_id = $1
+		ORDER BY f.name`, localDemoID)
+	if err != nil {
+		log.Fatalf("feed list: %v", err)
+	}
+	defer feedRows.Close()
+	var totalMappings int64
+	var feedCount int
+	for feedRows.Next() {
+		var feedName string
+		var mappingCount, orphanMismatch int64
+		if err := feedRows.Scan(&feedName, &mappingCount, &orphanMismatch); err != nil {
+			log.Fatalf("scan feed: %v", err)
+		}
+		feedCount++
+		totalMappings += mappingCount
+		orphanNote := ""
+		if orphanMismatch > 0 {
+			orphanNote = fmt.Sprintf(" ⚠ %d mappings with company_id mismatch", orphanMismatch)
+		}
+		fmt.Printf("  %-20s  mappings=%d%s\n", feedName, mappingCount, orphanNote)
+	}
+	if err := feedRows.Err(); err != nil {
+		log.Fatalf("feed rows: %v", err)
+	}
+	fmt.Printf("  (%d feeds, %d total mapping rows)\n", feedCount, totalMappings)
+
+	fmt.Println()
+	fmt.Println("Demo API key (local only — stored as SHA-256 hash):")
+	fmt.Printf("  key:           %s\n", demoAPIKey)
+	fmt.Printf("  prefix:        %s\n", keyPrefix)
+	fmt.Printf("  company_id:    %s\n", primaryCompanyID)
+	fmt.Println("  header:        Authorization: Bearer <key>")
+	fmt.Println("                or X-API-Key: <key>")
+	fmt.Println()
+	fmt.Printf("%s on plan %s (wallet total=%d used=%d remaining=%d; full-feature sandbox).\n",
+		demoCompanyName, planName, total, used, rem)
+	fmt.Println("Demo users are members of Platform Demo only — not A1. Act for customers via Admin → Users → Switch to user.")
+	fmt.Println("Use POST /api/auth/select-company {\"company_id\":\"...\"} only for companies you belong to.")
+	fmt.Printf("Suggested primary for testing: %s (%s)\n", demoCompanyName, localDemoID)
+	fmt.Println()
+	fmt.Println("Re-run (idempotent):")
+	fmt.Println("  cd apps/api")
+	fmt.Println("  go run ./cmd/seed-demo -postgres $env:DATABASE_URL")
+}
+
+// bindDemoUserToCompanyOnly grants admin on the sandbox company and removes
+// memberships on every other company (including A1).
+func bindDemoUserToCompanyOnly(ctx context.Context, tx pgx.Tx, userID, companyID uuid.UUID) (int64, error) {
+	ct, err := tx.Exec(ctx, `
+		INSERT INTO memberships (company_id, user_id, role, status)
+		VALUES ($1, $2, 'admin', 'active')
+		ON CONFLICT (company_id, user_id) DO UPDATE
+		SET role = 'admin', status = 'active', updated_at = now()`, companyID, userID)
+	if err != nil {
+		return 0, err
+	}
+	_, err = tx.Exec(ctx, `
+		DELETE FROM memberships
+		WHERE user_id = $1 AND company_id <> $2`, userID, companyID)
+	if err != nil {
+		return 0, err
+	}
+	return ct.RowsAffected(), nil
+}
+
+// ensureStandaloneDemoCompany finds or creates a sandbox company that is never
+// the A1 migrated tenant (by legacy_company_id or dump name).
+func ensureStandaloneDemoCompany(ctx context.Context, tx pgx.Tx, name string) (uuid.UUID, string, error) {
+	name = strings.TrimSpace(name)
+	if name == "" {
+		name = defaultLocalDemoName
+	}
+	if strings.EqualFold(name, "A1 Slovenija") || strings.EqualFold(name, "A1") || strings.EqualFold(name, "Local Demo Co") {
+		return uuid.Nil, "", fmt.Errorf("demo company name %q collides with A1 tenant — use %q", name, defaultLocalDemoName)
+	}
+
+	var id uuid.UUID
+	err := tx.QueryRow(ctx, `
+		SELECT c.id
+		FROM companies c
+		WHERE c.name = $1
+		  AND COALESCE(c.legacy_company_id, '') <> $2
+		ORDER BY c.created_at ASC
+		LIMIT 1`, name, billing.A1LegacyCompanyID).Scan(&id)
+	if err == nil {
+		if err := ensureCompanySideTables(ctx, tx, id); err != nil {
+			return uuid.Nil, "", err
+		}
+		return id, fmt.Sprintf("kept existing %s (%s)", name, id), nil
+	}
+	if err != pgx.ErrNoRows {
+		return uuid.Nil, "", err
+	}
+
+	err = tx.QueryRow(ctx, `INSERT INTO companies (name) VALUES ($1) RETURNING id`, name).Scan(&id)
+	if err != nil {
+		return uuid.Nil, "", err
+	}
+	if err := ensureCompanySideTables(ctx, tx, id); err != nil {
+		return uuid.Nil, "", err
+	}
+	return id, fmt.Sprintf("created empty sandbox %s (%s)", name, id), nil
+}
+
+func ensureCompanySideTables(ctx context.Context, tx pgx.Tx, id uuid.UUID) error {
+	if _, err := tx.Exec(ctx, `INSERT INTO company_settings (company_id) VALUES ($1) ON CONFLICT DO NOTHING`, id); err != nil {
+		return err
+	}
+	if _, err := tx.Exec(ctx, `INSERT INTO credit_balances (company_id) VALUES ($1) ON CONFLICT DO NOTHING`, id); err != nil {
+		return err
+	}
+	return nil
+}
+
+func loadCompanyPlanCredits(ctx context.Context, pg *pgxpool.Pool, companyID uuid.UUID) (
+	planName string, monthly int, maxProducts *int, isCustom bool, total, used, remaining int, err error,
+) {
+	err = pg.QueryRow(ctx, `
+		SELECT p.name, p.monthly_credits, p.max_products, p.is_custom,
+			cb.total_credits, cb.used_credits
+		FROM company_plans cp
+		JOIN plans p ON p.id = cp.plan_id
+		JOIN credit_balances cb ON cb.company_id = cp.company_id
+		WHERE cp.company_id = $1 AND cp.is_active = true
+		ORDER BY cp.created_at DESC
+		LIMIT 1`, companyID).Scan(&planName, &monthly, &maxProducts, &isCustom, &total, &used)
+	if err != nil {
+		return "", 0, nil, false, 0, 0, 0, err
+	}
+	return planName, monthly, maxProducts, isCustom, total, used, total - used, nil
+}
+
+func richestCompany(ctx context.Context, tx pgx.Tx, exclude uuid.UUID) (uuid.UUID, string, error) {
+	var id uuid.UUID
+	var name string
+	err := tx.QueryRow(ctx, `
+		SELECT c.id, c.name
+		FROM companies c
+		WHERE ($1::uuid IS NULL OR c.id <> $1)
+		  AND COALESCE(c.legacy_company_id, '') <> $2
+		  AND lower(c.name) NOT IN ('a1 slovenija', 'a1', 'local demo co')
+		ORDER BY
+			(SELECT COUNT(*) FROM processed_products p WHERE p.company_id = c.id) DESC,
+			(SELECT COUNT(*) FROM input_feeds f WHERE f.company_id = c.id) DESC,
+			(SELECT COUNT(*) FROM raw_products rp WHERE rp.company_id = c.id) DESC,
+			c.name
+		LIMIT 1`, exclude, billing.A1LegacyCompanyID).Scan(&id, &name)
+	return id, name, err
+}
+
+func claimRichestCatalog(ctx context.Context, tx pgx.Tx, destID uuid.UUID, destName string) (string, error) {
+	srcID, srcName, err := richestCompany(ctx, tx, uuid.Nil)
+	if err != nil {
+		return "", fmt.Errorf("find richest: %w", err)
+	}
+	if srcID == destID {
+		return fmt.Sprintf("noop — %s already richest", destName), nil
+	}
+
+	// Clear dest catalog first (avoids company_id+gtin and attribute_key collisions
+	// when Local Demo Co already has a partial Janus feed).
+	if err := clearCompanyCatalog(ctx, tx, destID); err != nil {
+		return "", fmt.Errorf("clear %s catalog: %w", destName, err)
+	}
+
+	moved, err := moveCompanyCatalog(ctx, tx, srcID, destID)
+	if err != nil {
+		return "", fmt.Errorf("move %s → %s: %w", srcName, destName, err)
+	}
+
+	// Keep feed_mappings.company_id aligned with the feed (no orphans).
+	ct, err := tx.Exec(ctx, `
+		UPDATE feed_mappings fm
+		SET company_id = f.company_id
+		FROM input_feeds f
+		WHERE fm.feed_id = f.id AND fm.company_id <> f.company_id`)
+	if err != nil {
+		return "", fmt.Errorf("repair mapping company_id: %w", err)
+	}
+	repaired := ct.RowsAffected()
+
+	return fmt.Sprintf("moved from %s (%s): %s; repaired_mapping_company_id=%d",
+		srcName, srcID, moved, repaired), nil
+}
+
+func clearCompanyCatalog(ctx context.Context, tx pgx.Tx, companyID uuid.UUID) error {
+	// Order respects FKs. feed_tag_mappings / processing_job_products cascade or are job-scoped.
+	stmts := []string{
+		`DELETE FROM processed_products WHERE company_id = $1`,
+		`DELETE FROM raw_products WHERE company_id = $1`,
+		`DELETE FROM export_feeds WHERE company_id = $1`,
+		`DELETE FROM feed_mappings WHERE company_id = $1`,
+		`DELETE FROM feed_sync_jobs WHERE company_id = $1`,
+		`DELETE FROM input_feeds WHERE company_id = $1`,
+		`DELETE FROM category_attributes WHERE company_id = $1`,
+		`DELETE FROM categories WHERE company_id = $1`,
+		`DELETE FROM attributes WHERE company_id = $1`,
+		`DELETE FROM custom_variables WHERE company_id = $1`,
+		`DELETE FROM standard_fields WHERE company_id = $1`,
+		`DELETE FROM field_groups WHERE company_id = $1`,
+		`DELETE FROM structured_description_fields WHERE company_id = $1`,
+		`DELETE FROM feed_tags WHERE company_id = $1`,
+		`DELETE FROM files WHERE company_id = $1`,
+		`DELETE FROM processing_jobs WHERE company_id = $1`,
+		`DELETE FROM schema_extraction_tasks WHERE company_id = $1`,
+		`DELETE FROM tasks WHERE company_id = $1`,
+		`DELETE FROM product_reviews WHERE company_id = $1`,
+		`DELETE FROM woo_order_items WHERE company_id = $1`,
+		`DELETE FROM woo_orders WHERE company_id = $1`,
+	}
+	for _, q := range stmts {
+		if _, err := tx.Exec(ctx, q, companyID); err != nil {
+			return fmt.Errorf("%s: %w", q, err)
+		}
+	}
+	return nil
+}
+
+func moveCompanyCatalog(ctx context.Context, tx pgx.Tx, src, dest uuid.UUID) (string, error) {
+	type step struct {
+		label string
+		sql   string
+	}
+	// Move catalog + feed graph. Skip billing/memberships/api_keys/email marketing.
+	steps := []step{
+		{"input_feeds", `UPDATE input_feeds SET company_id = $2, updated_at = now() WHERE company_id = $1`},
+		{"feed_mappings", `UPDATE feed_mappings SET company_id = $2, updated_at = now() WHERE company_id = $1`},
+		{"feed_sync_jobs", `UPDATE feed_sync_jobs SET company_id = $2, updated_at = now() WHERE company_id = $1`},
+		{"raw_products", `UPDATE raw_products SET company_id = $2, updated_at = now() WHERE company_id = $1`},
+		{"processed_products", `UPDATE processed_products SET company_id = $2, updated_at = now() WHERE company_id = $1`},
+		{"categories", `UPDATE categories SET company_id = $2, updated_at = now() WHERE company_id = $1`},
+		{"attributes", `UPDATE attributes SET company_id = $2, updated_at = now() WHERE company_id = $1`},
+		{"category_attributes", `UPDATE category_attributes SET company_id = $2, updated_at = now() WHERE company_id = $1`},
+		{"export_feeds", `UPDATE export_feeds SET company_id = $2, updated_at = now() WHERE company_id = $1`},
+		{"custom_variables", `UPDATE custom_variables SET company_id = $2, updated_at = now() WHERE company_id = $1`},
+		{"files", `UPDATE files SET company_id = $2, updated_at = now() WHERE company_id = $1`},
+		{"feed_tags", `UPDATE feed_tags SET company_id = $2 WHERE company_id = $1`},
+		{"field_groups", `UPDATE field_groups SET company_id = $2, updated_at = now() WHERE company_id = $1`},
+		{"standard_fields", `UPDATE standard_fields SET company_id = $2, updated_at = now() WHERE company_id = $1`},
+		{"structured_description_fields", `UPDATE structured_description_fields SET company_id = $2, updated_at = now() WHERE company_id = $1`},
+		{"processing_jobs", `UPDATE processing_jobs SET company_id = $2, updated_at = now() WHERE company_id = $1`},
+		{"schema_extraction_tasks", `UPDATE schema_extraction_tasks SET company_id = $2, updated_at = now() WHERE company_id = $1`},
+		{"tasks", `UPDATE tasks SET company_id = $2, updated_at = now() WHERE company_id = $1`},
+		{"product_reviews", `UPDATE product_reviews SET company_id = $2, updated_at = now() WHERE company_id = $1`},
+		{"woo_orders", `UPDATE woo_orders SET company_id = $2, updated_at = now() WHERE company_id = $1`},
+		{"woo_order_items", `UPDATE woo_order_items SET company_id = $2, updated_at = now() WHERE company_id = $1`},
+	}
+
+	parts := make([]string, 0, len(steps)+2)
+	for _, s := range steps {
+		ct, err := tx.Exec(ctx, s.sql, src, dest)
+		if err != nil {
+			return "", fmt.Errorf("%s: %w", s.label, err)
+		}
+		parts = append(parts, fmt.Sprintf("%s=%d", s.label, ct.RowsAffected()))
+	}
+
+	// PK-per-company: move only when dest has no row.
+	ct, err := tx.Exec(ctx, `
+		UPDATE woocommerce_configs SET company_id = $2, updated_at = now()
+		WHERE company_id = $1
+		  AND NOT EXISTS (SELECT 1 FROM woocommerce_configs WHERE company_id = $2)`, src, dest)
+	if err != nil {
+		return "", fmt.Errorf("woocommerce_configs: %w", err)
+	}
+	parts = append(parts, fmt.Sprintf("woocommerce_configs=%d", ct.RowsAffected()))
+
+	ct, err = tx.Exec(ctx, `
+		UPDATE company_brand SET company_id = $2, updated_at = now()
+		WHERE company_id = $1
+		  AND NOT EXISTS (SELECT 1 FROM company_brand WHERE company_id = $2)`, src, dest)
+	if err != nil {
+		return "", fmt.Errorf("company_brand: %w", err)
+	}
+	parts = append(parts, fmt.Sprintf("company_brand=%d", ct.RowsAffected()))
+
+	return strings.Join(parts, ", "), nil
+}
+
+// processSmokeEANPrefix matches scripts/v1-process-smoke defaultSmokeEAN (8700999000001).
+const processSmokeEANPrefix = "8700999"
+
+// refuseA1SmokePurge blocks process-smoke cleanup when the target is (or looks like) A1.
+func refuseA1SmokePurge(legacyCompanyID, companyName string) error {
+	if billing.IsA1CohortCompany(legacyCompanyID, companyName) {
+		return fmt.Errorf("refusing process-smoke EAN purge on A1 cohort (legacy_company_id=%q)", legacyCompanyID)
+	}
+	switch strings.ToLower(strings.TrimSpace(companyName)) {
+	case "a1 slovenija", "a1", "local demo co":
+		return fmt.Errorf("refusing process-smoke EAN purge on A1 cohort alias %q", companyName)
+	}
+	return nil
+}
+
+// purgeProcessSmokeEANsFromDemo hard-deletes synthetic process-smoke EANs from the
+// Platform Demo company only. Products have no soft-delete API - this is the Demo path.
+func purgeProcessSmokeEANsFromDemo(ctx context.Context, tx pgx.Tx, companyID uuid.UUID, companyName string) (rawN, ppN int64, err error) {
+	var legacyCID *string
+	err = tx.QueryRow(ctx, `SELECT legacy_company_id FROM companies WHERE id = $1`, companyID).Scan(&legacyCID)
+	if err != nil {
+		return 0, 0, fmt.Errorf("load company for smoke purge: %w", err)
+	}
+	leg := ""
+	if legacyCID != nil {
+		leg = *legacyCID
+	}
+	if err := refuseA1SmokePurge(leg, companyName); err != nil {
+		return 0, 0, err
+	}
+
+	like := processSmokeEANPrefix + "%"
+
+	_, err = tx.Exec(ctx, `
+		DELETE FROM processing_job_products pjp
+		WHERE pjp.raw_product_id IN (
+			SELECT id FROM raw_products WHERE company_id = $1 AND gtin LIKE $2
+		)
+		OR pjp.processed_product_id IN (
+			SELECT id FROM processed_products WHERE company_id = $1 AND product_id LIKE $2
+		)`, companyID, like)
+	if err != nil {
+		return 0, 0, fmt.Errorf("purge smoke job products: %w", err)
+	}
+
+	ct, err := tx.Exec(ctx, `
+		DELETE FROM processed_products
+		WHERE company_id = $1 AND product_id LIKE $2`, companyID, like)
+	if err != nil {
+		return 0, 0, fmt.Errorf("purge smoke processed: %w", err)
+	}
+	ppN = ct.RowsAffected()
+
+	ct, err = tx.Exec(ctx, `
+		DELETE FROM raw_products
+		WHERE company_id = $1 AND gtin LIKE $2`, companyID, like)
+	if err != nil {
+		return 0, 0, fmt.Errorf("purge smoke raw: %w", err)
+	}
+	rawN = ct.RowsAffected()
+	return rawN, ppN, nil
+}

apps/api/cmd/seed-demo/ownership_test.go

@@ -0,0 +1,205 @@
+package main
+
+import (
+	"context"
+	"os"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/descrybe/descrybe-v2/apps/api/internal/billing"
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+const a1CompanyName = "A1 Slovenija"
+
+// Integration smoke: A1 Slovenija must own processed products after migrate + seed-demo.
+// Skips when DATABASE_URL is unset (CI without Postgres).
+func TestLocalDemoCoHasProducts(t *testing.T) {
+	dsn := strings.TrimSpace(os.Getenv("DATABASE_URL"))
+	if dsn == "" {
+		t.Skip("DATABASE_URL not set")
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+	pg, err := pgxpool.New(ctx, dsn)
+	if err != nil {
+		t.Fatalf("postgres: %v", err)
+	}
+	defer pg.Close()
+
+	var (
+		id       uuid.UUID
+		name     string
+		products int64
+	)
+	err = pg.QueryRow(ctx, `
+		SELECT c.id, c.name,
+			(SELECT COUNT(*) FROM processed_products p WHERE p.company_id = c.id)
+		FROM companies c
+		WHERE c.name = $1
+		   OR c.legacy_company_id = $2
+		ORDER BY (SELECT COUNT(*) FROM processed_products p WHERE p.company_id = c.id) DESC
+		LIMIT 1`, a1CompanyName, billing.A1LegacyCompanyID).Scan(&id, &name, &products)
+	if err != nil {
+		t.Fatalf("query A1 Slovenija: %v (run migrate + seed-demo first)", err)
+	}
+	if products <= 0 {
+		t.Fatalf("%s %s has %d products; want > 0", name, id, products)
+	}
+	t.Logf("%s id=%s products=%d", name, id, products)
+}
+
+// Integration smoke: A1 cohort keeps dump-faithful wallet (not fake demo 1M / Legacy rename).
+func TestLocalDemoCoLegacyCredits(t *testing.T) {
+	dsn := strings.TrimSpace(os.Getenv("DATABASE_URL"))
+	if dsn == "" {
+		t.Skip("DATABASE_URL not set")
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+	pg, err := pgxpool.New(ctx, dsn)
+	if err != nil {
+		t.Fatalf("postgres: %v", err)
+	}
+	defer pg.Close()
+
+	var (
+		companyName string
+		planName    string
+		monthly     int
+		maxProd     *int
+		isCustom    bool
+		isLegacy    bool
+		total       int
+		used        int
+	)
+	err = pg.QueryRow(ctx, `
+		SELECT c.name, p.name, p.monthly_credits, p.max_products, p.is_custom,
+			COALESCE(p.is_legacy, false),
+			cb.total_credits, cb.used_credits
+		FROM companies c
+		JOIN company_plans cp ON cp.company_id = c.id AND cp.is_active = true
+		JOIN plans p ON p.id = cp.plan_id
+		JOIN credit_balances cb ON cb.company_id = c.id
+		WHERE c.name = $1 OR c.legacy_company_id = $2
+		ORDER BY (SELECT COUNT(*) FROM processed_products pp WHERE pp.company_id = c.id) DESC
+		LIMIT 1`, a1CompanyName, billing.A1LegacyCompanyID).
+		Scan(&companyName, &planName, &monthly, &maxProd, &isCustom, &isLegacy, &total, &used)
+	if err != nil {
+		t.Fatalf("query A1 plan/wallet: %v (run migrate + seed-demo first)", err)
+	}
+	if !strings.EqualFold(companyName, a1CompanyName) {
+		t.Fatalf("company=%s want %s", companyName, a1CompanyName)
+	}
+	if !billing.IsLegacyPlan(planName, isLegacy) {
+		t.Fatalf("plan=%s is_legacy=%v want A1/Legacy cohort", planName, isLegacy)
+	}
+	if total == 1_000_000 && used == 0 {
+		t.Fatalf("wallet looks like fake demo pack total=%d used=%d; want dump credit_balances", total, used)
+	}
+	// Dump A1 was ~2500/216; allow local drift but reject empty or fake demo packs.
+	if total < 1000 {
+		t.Fatalf("total_credits=%d want >= 1000 (dump-shaped A1 wallet)", total)
+	}
+	if used < 0 {
+		t.Fatalf("used_credits=%d want >= 0", used)
+	}
+	if monthly == 1_000_000 {
+		t.Fatalf("plan monthly_credits inflated to demo 1M; dump A1 monthly was 0")
+	}
+	t.Logf("company=%s plan=%s monthly=%d total=%d used=%d remaining=%d is_legacy=%v is_custom=%v",
+		companyName, planName, monthly, total, used, total-used, isLegacy, isCustom)
+}
+
+// Integration smoke: demo users belong only to Platform Demo (not A1).
+func TestDemoUsersIsolatedFromA1(t *testing.T) {
+	dsn := strings.TrimSpace(os.Getenv("DATABASE_URL"))
+	if dsn == "" {
+		t.Skip("DATABASE_URL not set")
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+	pg, err := pgxpool.New(ctx, dsn)
+	if err != nil {
+		t.Fatalf("postgres: %v", err)
+	}
+	defer pg.Close()
+
+	rows, err := pg.Query(ctx, `
+		SELECT u.email, c.name, COALESCE(c.legacy_company_id, '')
+		FROM users u
+		JOIN memberships m ON m.user_id = u.id AND m.status = 'active'
+		JOIN companies c ON c.id = m.company_id
+		WHERE lower(u.email) IN ('demo@descrybe.local', 'demo@descrybe.test')
+		ORDER BY u.email, c.name`)
+	if err != nil {
+		t.Fatalf("query demo memberships: %v (run seed-demo first)", err)
+	}
+	defer rows.Close()
+
+	type mem struct {
+		email, company, legacy string
+	}
+	var found []mem
+	for rows.Next() {
+		var m mem
+		if err := rows.Scan(&m.email, &m.company, &m.legacy); err != nil {
+			t.Fatalf("scan: %v", err)
+		}
+		found = append(found, m)
+		if strings.EqualFold(m.legacy, billing.A1LegacyCompanyID) ||
+			strings.EqualFold(m.company, a1CompanyName) ||
+			strings.EqualFold(m.company, "Local Demo Co") {
+			t.Fatalf("demo %s still member of A1 tenant %q (legacy=%s)", m.email, m.company, m.legacy)
+		}
+		if !strings.EqualFold(m.company, "Platform Demo") && !strings.EqualFold(m.company, "Demo") {
+			t.Fatalf("demo %s company=%q want Platform Demo", m.email, m.company)
+		}
+	}
+	if err := rows.Err(); err != nil {
+		t.Fatalf("rows: %v", err)
+	}
+	if len(found) == 0 {
+		t.Fatal("no demo memberships found — run go run ./cmd/seed-demo")
+	}
+	t.Logf("demo memberships ok: %+v", found)
+}
+
+// Integration smoke: Free plan definition stays at 0 AI credits after A1 seed.
+func TestFreePlanUnaffectedByEnterpriseSeed(t *testing.T) {
+	dsn := strings.TrimSpace(os.Getenv("DATABASE_URL"))
+	if dsn == "" {
+		t.Skip("DATABASE_URL not set")
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+	pg, err := pgxpool.New(ctx, dsn)
+	if err != nil {
+		t.Fatalf("postgres: %v", err)
+	}
+	defer pg.Close()
+
+	var (
+		name    string
+		monthly int
+		maxProd *int
+		custom  bool
+	)
+	err = pg.QueryRow(ctx, `
+		SELECT name, monthly_credits, max_products, is_custom
+		FROM plans WHERE lower(name) = 'free' ORDER BY id LIMIT 1`).
+		Scan(&name, &monthly, &maxProd, &custom)
+	if err != nil {
+		t.Fatalf("query Free plan: %v", err)
+	}
+	if monthly != 0 {
+		t.Fatalf("Free monthly_credits=%d want 0", monthly)
+	}
+	wantMax := billing.PlanMaxProducts("Free")
+	if wantMax == nil || maxProd == nil || *maxProd != *wantMax {
+		t.Fatalf("Free max_products=%v want %v", maxProd, wantMax)
+	}
+	t.Logf("Free plan ok name=%s monthly=%d max_products=%d", name, monthly, *maxProd)
+}

apps/api/cmd/seed-demo/smoke_ean_purge_test.go

@@ -0,0 +1,27 @@
+package main
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/descrybe/descrybe-v2/apps/api/internal/billing"
+)
+
+func TestRefuseA1SmokePurge(t *testing.T) {
+	t.Parallel()
+
+	if err := refuseA1SmokePurge(billing.A1LegacyCompanyID, "Platform Demo"); err == nil {
+		t.Fatal("want refuse when legacy_company_id is A1")
+	}
+	for _, name := range []string{"A1 Slovenija", "A1", "Local Demo Co", " a1 slovenija "} {
+		if err := refuseA1SmokePurge("", name); err == nil {
+			t.Fatalf("want refuse for A1 alias %q", name)
+		}
+	}
+	if err := refuseA1SmokePurge("", "Platform Demo"); err != nil {
+		t.Fatalf("Platform Demo must be allowed: %v", err)
+	}
+	if !strings.HasPrefix(processSmokeEANPrefix, "8700999") {
+		t.Fatalf("processSmokeEANPrefix=%q want 8700999…", processSmokeEANPrefix)
+	}
+}

apps/api/cmd/seed-guide-personas/main.go

@@ -0,0 +1,87 @@
+// Seed isolated "new user" personas for guided-assistant QA.
+//
+//	cd apps/api
+//	go run ./cmd/seed-guide-personas -postgres "$env:DATABASE_URL"
+//
+// Password defaults to DemoPass123! (same as docs/demo-user.md).
+package main
+
+import (
+	"context"
+	"errors"
+	"flag"
+	"fmt"
+	"log"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/descrybe/descrybe-v2/apps/api/internal/auth"
+	"github.com/descrybe/descrybe-v2/apps/api/internal/billing"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+type persona struct {
+	Email       string
+	Name        string
+	CompanyName string
+}
+
+var personas = []persona{
+	{"guide-feed-url@descrybe.local", "Guide Feed URL", "Guide · Feed URL"},
+	{"guide-upload-csv@descrybe.local", "Guide Upload CSV", "Guide · Upload CSV"},
+	{"guide-shopify@descrybe.local", "Guide Shopify", "Guide · Shopify"},
+	{"guide-woocommerce@descrybe.local", "Guide WooCommerce", "Guide · WooCommerce"},
+	{"guide-mapping@descrybe.local", "Guide Mapping", "Guide · Mapping"},
+	{"guide-process@descrybe.local", "Guide Process", "Guide · Process"},
+	{"guide-api@descrybe.local", "Guide API Keys", "Guide · API Keys"},
+	{"guide-support@descrybe.local", "Guide Support", "Guide · Support"},
+	{"guide-attributes@descrybe.local", "Guide Attributes", "Guide · Attributes"},
+}
+
+func main() {
+	postgresURL := flag.String("postgres", os.Getenv("DATABASE_URL"), "Postgres URL")
+	password := flag.String("password", "DemoPass123!", "Password for all guide personas")
+	flag.Parse()
+	if strings.TrimSpace(*postgresURL) == "" {
+		log.Fatal("-postgres / DATABASE_URL is required")
+	}
+	if strings.TrimSpace(*password) == "" {
+		log.Fatal("-password is required")
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+	defer cancel()
+
+	pg, err := pgxpool.New(ctx, *postgresURL)
+	if err != nil {
+		log.Fatalf("postgres: %v", err)
+	}
+	defer pg.Close()
+
+	authSvc := &auth.Service{Pool: pg}
+	billingSvc := &billing.Service{Pool: pg}
+
+	fmt.Println("Seeding guide assistant personas…")
+	for _, p := range personas {
+		email := strings.ToLower(strings.TrimSpace(p.Email))
+		res, err := authSvc.Register(ctx, auth.RegisterInput{
+			Email:       email,
+			Password:    *password,
+			Name:        p.Name,
+			CompanyName: p.CompanyName,
+		})
+		if err != nil {
+			if errors.Is(err, auth.ErrUserExists) {
+				fmt.Printf("  exists  %s (company unchanged)\n", email)
+				continue
+			}
+			log.Fatalf("%s: %v", email, err)
+		}
+		if err := billingSvc.ProvisionFreePlan(ctx, res.CompanyID); err != nil {
+			log.Fatalf("provision plan for %s: %v", email, err)
+		}
+		fmt.Printf("  created %s → company %s (%s)\n", email, p.CompanyName, res.CompanyID)
+	}
+	fmt.Println("Done. Login at /login with DemoPass123! (or -password).")
+}

apps/api/cmd/seed-support-kb/content/tech-admin-capabilities-diagnostics.md

@@ -0,0 +1,45 @@
+# Admin capabilities and diagnostics
+
+Platform admins use /admin/* (session + RequirePlatformAdmin). Support desk staff get ticket routes only (RequireSupportDesk).
+
+## Useful admin APIs
+
+| Path | Purpose |
+|------|---------|
+| GET /api/admin/diagnostics | Health: DB, queue, cache, storage, mail; config sanity (booleans only); recent job/AI failures |
+| GET /api/admin/analytics | Operational metrics dashboard data |
+| GET /api/admin/readiness | Cutover hypercare: must_set_password, companies without admin/plan |
+| GET /api/admin/jobs | Recent processing_jobs |
+| POST /api/admin/jobs/stuck-cleanup | Stuck running jobs cleanup |
+| GET/PUT /api/admin/settings | Platform settings (secrets masked on GET) |
+| GET/POST /api/admin/support/kb/articles | Support Knowledge CRUD |
+| GET/PUT /api/admin/support/auto-config | FAQ + AI auto-reply switchboard |
+| Users / companies / plans / credits | Org + billing admin |
+
+UI: /admin/support/knowledge; diagnostics and analytics under the admin shell.
+
+## Diagnose a stuck process
+
+```mermaid
+flowchart TD
+  A[Job stuck or failed] --> B{Worker running?}
+  B -->|No| C["Start: go run ./cmd/worker"]
+  B -->|Yes| D["GET /api/admin/diagnostics"]
+  D --> E{queue.failed or stuck_running?}
+  E -->|Yes| F["GET /api/admin/jobs + stuck-cleanup"]
+  E -->|No| G["Check /readyz + company credits"]
+  F --> H["Retry job or re-POST /products/process"]
+```
+
+### Checklist
+
+1. GET /healthz (liveness) and GET /readyz (Postgres + maintenance/read_only flags).  
+2. GET /api/admin/diagnostics — overall ok|degraded|fail; never expect secrets in the payload.  
+3. Confirm **worker** process is up (API alone does not drain processing).  
+4. Filter recent failures: ?status=failed&failures_limit=25.  
+5. Support auto AI: ticket auto_reply_status, /admin/support inbox flag=needs_human, AI role support under /admin/settings.  
+6. Cutover: GET /api/admin/readiness before DNS switch.
+
+Diagnostics intentionally excludes marketing charts — use analytics for trends, diagnostics for troubleshooting.
+
+Sources: apps/api/internal/httpapi/admin_diagnostics_handlers.go, server.go admin routes.

apps/api/cmd/seed-support-kb/content/tech-api-v1-postman-a1.md

@@ -0,0 +1,58 @@
+# Public API and Postman A1
+
+Base URL (local): http://127.0.0.1:28471  
+Auth: Authorization Bearer api_key or X-API-Key  
+OpenAPI: GET /api/v1/openapi.yaml (no key). Health: GET /api/v1/health or GET /healthz.
+
+## Core /api/v1 groups (API key)
+
+| Group | Examples |
+|-------|----------|
+| Products | GET /products, GET /products/{id}, PATCH /products/{id}, POST /products/process, GET /products/process/{id} |
+| Feeds | GET/POST /feeds, POST /feeds/{id}/sync, mappings, extract-schema |
+| Categories / attributes | CRUD under /categories, /attributes |
+| Export | /export-feeds plus generate / export-products |
+| Process jobs | POST /process, list/get/cancel/retry |
+| Marketing calendar | /marketing/calendar (legacy /campaigns aliases) |
+
+Mounted in apps/api/internal/httpapi/v1.go via mountV1.
+
+## A1 two-EAN Postman flow
+
+Collection: docs/postman/Descrybe-v2-A1-two-EANs.postman_collection.json  
+Prerequisite: npm run seed:a1 (restores processing jobs so poll works).
+
+```mermaid
+sequenceDiagram
+  participant P as Postman
+  participant API as /api/v1
+  participant W as worker
+  P->>API: GET /health
+  P->>API: GET /feeds
+  P->>API: GET /products?feed_id=
+  P->>API: POST /products/process (2 EANs)
+  API-->>P: data.process_id
+  loop until done
+    P->>API: GET /products/process/{processId}
+  end
+  Note over W: Worker claims processing_jobs
+  P->>API: GET /products?search=EAN
+  P->>API: GET /export-feeds
+  P->>API: GET /api/public/export-feeds/{token}.csv
+```
+
+### Steps (collection order)
+
+0. Health (no auth)  
+1. List feeds (find Elkotex)  
+2. List products on feed  
+3. **Process two EANs** — processing_type full — copy data.process_id into processId  
+4. Poll process status  
+5–6. Search results by EAN  
+7. Get product by UUID  
+8. List export feeds  
+9. Public CSV (no API key)
+
+Demo API key and feed/EAN vars live in the Postman collection (local demo only). Full surface: docs/postman/Descrybe-v2-Demo-A1-all-v1.postman_collection.json.
+
+Rate limits: process/sync/export POSTs are capped per company (RateLimitV1Process). Prefer enqueue + worker under load.

apps/api/cmd/seed-support-kb/content/tech-architecture-overview.md

@@ -0,0 +1,46 @@
+# Architecture overview
+
+Descrybe v2 is a **Go chi API + SvelteKit web + PostgreSQL** rewrite (no Clerk).
+
+## Runtime processes
+
+| Process | Role |
+|---------|------|
+| apps/api/cmd/api | HTTP API (sessions, CSRF, public /api/v1, admin) |
+| apps/api/cmd/worker | Processing jobs, Woo/Shopify claim, support AI auto jobs, billing cycles |
+| apps/web | SvelteKit 2 / Svelte 5 UI (Vite proxies /api to API) |
+| PostgreSQL 16 | System of record (goose migrations under apps/api/sql/schema) |
+
+`npm run dev` starts API + web. **Worker is separate** — without it, process jobs and many background syncs stall.
+
+## Component diagram
+
+```mermaid
+flowchart LR
+  Browser["Browser :28472"] --> Web["SvelteKit apps/web"]
+  Web -->|"/api proxy"| API["Go chi API :28471"]
+  API --> PG[(PostgreSQL)]
+  Worker["cmd/worker"] --> PG
+  API -->|"NOTIFY processing_jobs"| Worker
+  Worker -->|"ClaimNext SKIP LOCKED"| PG
+  Ext["OpenAI / Woo / Shopify / Stripe / SMTP"] -.-> API
+  Ext -.-> Worker
+```
+
+## Auth surfaces
+
+- **Dashboard session:** cookie + CSRF (X-CSRF-Token) under /api/*
+- **Public API key:** Bearer or X-API-Key under /api/v1 (no CSRF)
+- **Public tokens:** /api/public/* (export feeds CSV/XML, unsubscribe, brand logos)
+- **Platform admin:** /api/admin/* after RequirePlatformAdmin (support desk subset for support_staff)
+
+## Key packages
+
+- internal/httpapi — routes + middleware
+- internal/processing — product description jobs
+- internal/feeds / woocommerce / shopify — ingest and connectors
+- internal/support — tickets, KB, FAQ/AI auto-reply
+- internal/billing — plans, credits, Stripe
+- internal/jobs — enqueue processing (Postgres pending + NOTIFY; River client deferred)
+
+Sources: README.md, apps/api/internal/httpapi/server.go, apps/api/cmd/worker/main.go.

apps/api/cmd/seed-support-kb/content/tech-configuration-env.md

@@ -0,0 +1,37 @@
+# Configuration and bootstrap environment
+
+**One root .env** — copy from .env.example. Do **not** create apps/api/.env. Product secrets belong in the dashboard after login.
+
+## Required bootstrap (names only — never paste real secrets)
+
+| Variable | Purpose |
+|----------|---------|
+| DATABASE_URL | Postgres (local compose often host port 5433) |
+| APP_ENV | development / staging / production |
+| HTTP_ADDR | API listen (dev commonly :28471) |
+| WEB_ORIGIN | Browser origin for CORS/cookies (:28472 local) |
+| PUBLIC_API_URL | Public API origin for the web app |
+| SESSION_SECURE | Cookie Secure; must be true in production |
+| TOKEN_SIGNING_SECRET | Session/invite HMAC (openssl rand -hex 32) |
+| APP_ENCRYPTION_KEY | At-rest encryption for BYOK/store secrets (preferred) |
+
+## Optional bootstrap (safe to override)
+
+TRUSTED_PROXIES (comma CIDRs/IPs of hop-1 reverse proxies only — enables TrustedRealIP rewrite of RemoteAddr for rate limits; empty = ignore X-Forwarded-For), RATE_LIMIT_REPLICAS (optional; divides HTTP middleware RPM caps when N>1 — still per-process; edge still required for hard global RPM; does not affect lockout/StartLimiter/AI/email), SESSION_COOKIE_NAME, CSRF_COOKIE_NAME, PUBLIC_CSRF_COOKIE_NAME, SESSION_IDLE_HOURS, UPLOAD_DIR, MAINTENANCE_MODE, READ_ONLY_MODE, CREDENTIALS_ENCRYPTION_KEY (legacy alias for APP_ENCRYPTION_KEY), DOTENV_PATH.
+
+## Prefer dashboard (not root .env)
+
+| Area | UI |
+|------|-----|
+| Stripe, EPREL kill-switch, feed private-URL allowlist | /admin/settings |
+| Tenant AI | /integrations/ai |
+| Marketing email | /integrations/email |
+| Stores | /stores |
+
+Optional process-env fallbacks still accepted by some resolvers (OPENAI_*, SMTP_*, EPREL_*, FEED_URL_PRIVATE_ALLOWLIST) — prefer UI for day-to-day.
+
+Production fail-closed (APP_ENV=production): SESSION_SECURE=true, https WEB_ORIGIN, APP_ENCRYPTION_KEY, TOKEN_SIGNING_SECRET, STRIPE_MOCK=false.
+
+Never commit real secrets. Diagnostics exposes **presence flags** only (*_set), never values.
+
+Source: root .env.example, README.md Environment section, docs/ops-runtime.md.

apps/api/cmd/seed-support-kb/content/tech-jobs-queues-integrations.md

@@ -0,0 +1,60 @@
+# Jobs, queues, and integrations
+
+## Processing queue
+
+ASSUMPTION in code: full River client is deferred. Production MVP uses **Postgres processing_jobs** with FOR UPDATE SKIP LOCKED + pg_notify('processing_jobs').
+
+- Enqueue: internal/jobs.Queue.EnqueueProcessingJob
+- Workers: internal/processing.JobSlots.Fill → ClaimNext (count from config / ClampProcessingWorkers)
+- Process starts also hit HTTP rate limits (RPM per company)
+
+## Worker loop (what runs)
+
+From apps/api/cmd/worker:
+
+1. Fill processing job slots  
+2. ProcessPendingAutoJobs (support AI fallback)  
+3. WooCommerce / Shopify ClaimNextPendingJob + sync  
+4. Periodic: EnqueueDueScheduled (stores), RunDueBillingCycles
+
+API also runs a light RunAutoJobsLoop for support AI — keep **worker** in production.
+
+```mermaid
+flowchart TB
+  subgraph ingest [Ingest]
+    FeedURL[Feed URL / CSV]
+    Woo[WooCommerce]
+    Shop[Shopify]
+  end
+  subgraph core [Core]
+    Jobs[(processing_jobs)]
+    Worker[cmd/worker]
+    Catalog[(products)]
+  end
+  subgraph out [Outbound]
+    Export[export feeds CSV/XML]
+    StorePush[Woo/Shopify push]
+  end
+  FeedURL --> Catalog
+  Woo --> Catalog
+  Shop --> Catalog
+  Catalog --> Jobs
+  Jobs --> Worker
+  Worker --> Catalog
+  Catalog --> Export
+  Worker --> StorePush
+```
+
+## Integrations (where configured)
+
+| Integration | Preferred config | Notes |
+|-------------|------------------|-------|
+| AI (BYOK / OpenAI-compatible) | Tenant /integrations/ai | Encrypted with APP_ENCRYPTION_KEY; optional process OPENAI_* fallback |
+| Marketing email | /integrations/email | Separate from platform invite SMTP |
+| Woo / Shopify / feeds | /stores | Woo secrets at rest; Shopify Admin domain SSRF-hardened |
+| Stripe / EPREL / feed private-URL allowlist | /admin/settings | Env fallbacks exist; prefer UI |
+| Platform invite SMTP | Process SMTP_* | See docs/ops-runtime.md |
+
+Support AI auto-reply jobs: table support_auto_jobs → TryAutoReplyLLM after FAQ miss.
+
+Sources: apps/api/internal/jobs/river.go, apps/api/cmd/worker/main.go, docs/ops-runtime.md.

apps/api/cmd/seed-support-kb/content/tech-security-ops-runbook.md

@@ -0,0 +1,42 @@
+# Security and operational runbook
+
+Grounded in docs/security-notes.md and docs/ops-runtime.md.
+
+## Controls in place
+
+| Area | Control |
+|------|---------|
+| CSRF | Double-submit cookie + X-CSRF-Token on dashboard /api/* (skipped for /api/v1, /api/public/*, webhooks) |
+| Sessions | scs + Postgres store; HttpOnly; idle SESSION_IDLE_HOURS (default 24); absolute 7d |
+| CORS | Allowlist = WEB_ORIGIN only; credentials allowed |
+| SSRF | Feed + Woo URL checks; Shopify *.myshopify.com; optional FEED_URL_PRIVATE_ALLOWLIST / settings allowlist |
+| Uploads | CSV/logo size + type caps under UPLOAD_DIR/{company_id}/ |
+| AuthZ | Session company context; API key company binding; admin vs support_staff |
+| Rate limits | Auth POSTs / IP; process/sync/export / company (in-process — not cluster-global) |
+
+## Ops runbook
+
+```mermaid
+flowchart LR
+  Deploy --> Migrate["scripts/migrate.ps1 / goose up"]
+  Migrate --> API[cmd/api]
+  Migrate --> Worker[cmd/worker]
+  API --> Probes["/healthz /readyz"]
+  Worker --> Probes
+  Probes --> Hypercare["/api/admin/readiness + diagnostics"]
+```
+
+1. **Bring up:** Docker Postgres → migrate → API + **worker** → web.  
+2. **Probes:** /healthz no DB; /readyz pings Postgres and reports maintenance/read_only.  
+3. **Maintenance:** MAINTENANCE_MODE / READ_ONLY_MODE — keep probes green during cutover rehearsal.  
+4. **Mail:** Platform invites need SMTP_ENABLED + host/from; tenant marketing mail is separate.  
+5. **Credentials:** Set APP_ENCRYPTION_KEY before storing production Woo/AI secrets; rotating without re-save breaks ciphertext.  
+6. **Stuck jobs:** diagnostics → stuck-cleanup → retry; ensure worker is running.  
+7. **Support auto-reply:** default off (enabled=false); publish KB + raise threshold before enabling FAQ; AI needs support role configured.  
+8. **Never log:** Stripe/OpenAI/SMTP/Woo/Shopify/EPREL secrets.
+
+## Known residual risks (honest)
+
+In-process rate limits do not cluster; broad private feed allowlists re-enable SSRF; public export tokens rely on entropy; demo API keys are local-only.
+
+For cutover blockers and SMTP verification, see docs/ops-runtime.md and docs/production-checklist.md.

apps/api/cmd/seed-support-kb/main.go

@@ -0,0 +1,213 @@
+// Command seed-support-kb upserts platform Support Knowledge articles from JSON.
+//
+// Targets table support_kb_articles (migration 032). Idempotent on slug.
+//
+// Usage (from apps/api, DATABASE_URL set or passed):
+//
+//	go run ./cmd/seed-support-kb -postgres "$DATABASE_URL"
+//	go run ./cmd/seed-support-kb -file ../../scripts/seed/support-kb-articles.json
+//	go run ./cmd/seed-support-kb -file ../../scripts/seed/support-kb-articles-tech.json
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"flag"
+	"fmt"
+	"log"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+	"unicode"
+	"unicode/utf8"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+const (
+	maxSlugLen      = 120
+	maxTitleLen     = 200
+	maxBodyLen      = 20000
+	maxKeywordLen   = 64
+	maxKeywords     = 40
+	maxIntents      = 20
+	maxCatSlugs     = 20
+)
+
+type seedFile struct {
+	Version  int           `json:"version"`
+	Articles []seedArticle `json:"articles"`
+}
+
+type seedArticle struct {
+	Slug            string   `json:"slug"`
+	Title           string   `json:"title"`
+	BodyMD          string   `json:"body_md"`
+	CategorySlugs   []string `json:"category_slugs"`
+	Keywords        []string `json:"keywords"`
+	IntentKeys      []string `json:"intent_keys"`
+	IsPublished     bool     `json:"is_published"`
+	PriorityWeight  int      `json:"priority_weight"`
+}
+
+func main() {
+	postgresURL := flag.String("postgres", os.Getenv("DATABASE_URL"), "Postgres URL")
+	filePath := flag.String("file", "", "Path to support-kb-articles.json (default: repo scripts/seed/...)")
+	flag.Parse()
+
+	if strings.TrimSpace(*postgresURL) == "" {
+		log.Fatal("-postgres / DATABASE_URL is required")
+	}
+
+	path := strings.TrimSpace(*filePath)
+	if path == "" {
+		path = defaultArticlesPath()
+	}
+
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		log.Fatalf("read %s: %v", path, err)
+	}
+	var sf seedFile
+	if err := json.Unmarshal(raw, &sf); err != nil {
+		log.Fatalf("parse json: %v", err)
+	}
+	if len(sf.Articles) == 0 {
+		log.Fatal("no articles in seed file")
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
+	defer cancel()
+
+	pool, err := pgxpool.New(ctx, *postgresURL)
+	if err != nil {
+		log.Fatalf("postgres: %v", err)
+	}
+	defer pool.Close()
+
+	var tableOK bool
+	if err := pool.QueryRow(ctx, `
+		SELECT EXISTS (
+			SELECT 1 FROM information_schema.tables
+			WHERE table_schema = 'public' AND table_name = 'support_kb_articles'
+		)`).Scan(&tableOK); err != nil {
+		log.Fatalf("check table: %v", err)
+	}
+	if !tableOK {
+		log.Fatal("support_kb_articles missing — run goose migrations through 032_support_kb_auto_reply first")
+	}
+
+	upserted := 0
+	for i, a := range sf.Articles {
+		slug, err := normalizeSlug(a.Slug)
+		if err != nil {
+			log.Fatalf("article[%d] slug: %v", i, err)
+		}
+		title := clipRunes(strings.TrimSpace(a.Title), maxTitleLen)
+		body := clipRunes(strings.TrimSpace(a.BodyMD), maxBodyLen)
+		if title == "" || body == "" {
+			log.Fatalf("article[%d] (%s): title and body_md are required", i, slug)
+		}
+		cats := normalizeList(a.CategorySlugs, maxKeywordLen, maxCatSlugs)
+		keywords := normalizeList(a.Keywords, maxKeywordLen, maxKeywords)
+		intents := normalizeList(a.IntentKeys, maxKeywordLen, maxIntents)
+
+		tag, err := pool.Exec(ctx, `
+			INSERT INTO support_kb_articles (
+				slug, title, body_md, category_slugs, keywords, intent_keys,
+				is_published, priority_weight, updated_at
+			) VALUES ($1,$2,$3,$4,$5,$6,$7,$8, now())
+			ON CONFLICT (slug) DO UPDATE SET
+				title = EXCLUDED.title,
+				body_md = EXCLUDED.body_md,
+				category_slugs = EXCLUDED.category_slugs,
+				keywords = EXCLUDED.keywords,
+				intent_keys = EXCLUDED.intent_keys,
+				is_published = EXCLUDED.is_published,
+				priority_weight = EXCLUDED.priority_weight,
+				updated_at = now()`,
+			slug, title, body, cats, keywords, intents, a.IsPublished, a.PriorityWeight)
+		if err != nil {
+			log.Fatalf("upsert %s: %v", slug, err)
+		}
+		if tag.RowsAffected() > 0 {
+			upserted++
+			fmt.Printf("upserted %s (%s)\n", slug, title)
+		}
+	}
+
+	var published, total int64
+	_ = pool.QueryRow(ctx, `SELECT count(*) FROM support_kb_articles`).Scan(&total)
+	_ = pool.QueryRow(ctx, `SELECT count(*) FROM support_kb_articles WHERE is_published`).Scan(&published)
+	fmt.Printf("done: %d articles from file; table total=%d published=%d\n", upserted, total, published)
+}
+
+func defaultArticlesPath() string {
+	// Prefer repo-relative path when run from apps/api.
+	candidates := []string{
+		filepath.Join("..", "..", "scripts", "seed", "support-kb-articles.json"),
+		filepath.Join("scripts", "seed", "support-kb-articles.json"),
+	}
+	if wd, err := os.Getwd(); err == nil {
+		candidates = append(candidates,
+			filepath.Join(wd, "scripts", "seed", "support-kb-articles.json"),
+			filepath.Join(wd, "..", "..", "scripts", "seed", "support-kb-articles.json"),
+		)
+	}
+	for _, c := range candidates {
+		if st, err := os.Stat(c); err == nil && !st.IsDir() {
+			return c
+		}
+	}
+	return candidates[0]
+}
+
+func normalizeSlug(s string) (string, error) {
+	s = strings.ToLower(strings.TrimSpace(s))
+	s = strings.ReplaceAll(s, " ", "-")
+	if s == "" {
+		return "", fmt.Errorf("empty slug")
+	}
+	if utf8.RuneCountInString(s) > maxSlugLen {
+		return "", fmt.Errorf("slug too long")
+	}
+	for _, r := range s {
+		if unicode.IsLetter(r) || unicode.IsDigit(r) || r == '-' || r == '_' {
+			continue
+		}
+		return "", fmt.Errorf("invalid slug char %q", r)
+	}
+	return s, nil
+}
+
+func normalizeList(in []string, maxItem, maxCount int) []string {
+	seen := make(map[string]struct{}, len(in))
+	out := make([]string, 0, len(in))
+	for _, raw := range in {
+		s := strings.ToLower(strings.TrimSpace(raw))
+		if s == "" {
+			continue
+		}
+		s = clipRunes(s, maxItem)
+		if _, ok := seen[s]; ok {
+			continue
+		}
+		seen[s] = struct{}{}
+		out = append(out, s)
+		if len(out) >= maxCount {
+			break
+		}
+	}
+	if out == nil {
+		return []string{}
+	}
+	return out
+}
+
+func clipRunes(s string, max int) string {
+	if max <= 0 || utf8.RuneCountInString(s) <= max {
+		return s
+	}
+	return string([]rune(s)[:max])
+}

apps/api/cmd/seed-woo-demo/main.go

@@ -0,0 +1,546 @@
+// Command seed-woo-demo inserts sample WooCommerce orders, line items, reviews,
+// and a draft campaign so UI + audience targeting work without a live store.
+//
+// When WOO_STORE_URL + WOO_CONSUMER_KEY + WOO_CONSUMER_SECRET are set (or -live),
+// also upserts woocommerce_configs and optionally tests the REST connection.
+//
+// Usage:
+//
+//	go run ./cmd/seed-woo-demo -postgres "$DATABASE_URL"
+//	go run ./cmd/seed-woo-demo -company "A1 Slovenija"
+//	go run ./cmd/seed-woo-demo -live   # require WOO_* and test connection
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"flag"
+	"fmt"
+	"log"
+	"net/http"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/descrybe/descrybe-v2/apps/api/internal/woocommerce"
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+const (
+	demoCategoryName = "Demo Electronics"
+	demoCategoryUID  = "demo-electronics"
+	demoSKUPrefix    = "DEMO-WOO-"
+)
+
+type demoProduct struct {
+	SKU      string
+	Name     string
+	Category string
+	Price    string
+	WCID     int64
+}
+
+type demoCustomer struct {
+	Email string
+	Name  string
+}
+
+func main() {
+	postgresURL := flag.String("postgres", os.Getenv("DATABASE_URL"), "Postgres URL")
+	companyName := flag.String("company", "A1 Slovenija", "Target company name")
+	live := flag.Bool("live", false, "Require WOO_* env and test REST connection after seeding")
+	flag.Parse()
+
+	if strings.TrimSpace(*postgresURL) == "" {
+		log.Fatal("-postgres / DATABASE_URL is required")
+	}
+	companyNameNorm := strings.TrimSpace(*companyName)
+	if companyNameNorm == "" {
+		log.Fatal("-company is required")
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
+	defer cancel()
+
+	pg, err := pgxpool.New(ctx, *postgresURL)
+	if err != nil {
+		log.Fatalf("postgres: %v", err)
+	}
+	defer pg.Close()
+
+	companyID, err := resolveCompany(ctx, pg, companyNameNorm)
+	if err != nil {
+		log.Fatalf("company: %v", err)
+	}
+
+	tx, err := pg.Begin(ctx)
+	if err != nil {
+		log.Fatalf("begin: %v", err)
+	}
+	defer tx.Rollback(ctx)
+
+	categoryID, err := ensureDemoCategory(ctx, tx, companyID)
+	if err != nil {
+		log.Fatalf("category: %v", err)
+	}
+
+	products := []demoProduct{
+		{SKU: demoSKUPrefix + "TV-50", Name: "Demo 4K TV 50\"", Category: demoCategoryUID, Price: "499.00", WCID: 90001},
+		{SKU: demoSKUPrefix + "SOUND", Name: "Demo Soundbar", Category: demoCategoryUID, Price: "149.00", WCID: 90002},
+		{SKU: demoSKUPrefix + "HEAD", Name: "Demo Wireless Headphones", Category: demoCategoryUID, Price: "89.00", WCID: 90003},
+	}
+	if err := seedDemoProducts(ctx, tx, companyID, products); err != nil {
+		log.Fatalf("products: %v", err)
+	}
+
+	customers := []demoCustomer{
+		{Email: "anna.buyer@example.com", Name: "Anna Buyer"},
+		{Email: "ben.buyer@example.com", Name: "Ben Buyer"},
+		{Email: "cara.buyer@example.com", Name: "Cara Buyer"},
+		{Email: "dan.other@example.com", Name: "Dan Other"},
+	}
+	orderCount, itemCount, err := seedDemoOrders(ctx, tx, companyID, products, customers)
+	if err != nil {
+		log.Fatalf("orders: %v", err)
+	}
+	reviewCount, err := seedDemoReviews(ctx, tx, companyID, products, customers)
+	if err != nil {
+		log.Fatalf("reviews: %v", err)
+	}
+
+	encKey := woocommerce.DeriveKey(
+		os.Getenv("CREDENTIALS_ENCRYPTION_KEY"),
+		os.Getenv("TOKEN_SIGNING_SECRET")+"|"+*postgresURL,
+	)
+	storeURL, key, secret, fromEnv := wooCredsFromEnv()
+	if err := upsertWooConfig(ctx, tx, companyID, encKey, storeURL, key, secret, fromEnv); err != nil {
+		log.Fatalf("woocommerce_configs: %v", err)
+	}
+
+	campaignID, err := seedDemoCampaign(ctx, tx, companyID, categoryID)
+	if err != nil {
+		log.Fatalf("campaign: %v", err)
+	}
+
+	if err := tx.Commit(ctx); err != nil {
+		log.Fatalf("commit: %v", err)
+	}
+
+	woo := &woocommerce.Service{Pool: pg}
+	audience, err := woo.AudienceBoughtCategories(ctx, companyID, demoCategoryName, "", 100)
+	if err != nil {
+		log.Fatalf("audience check: %v", err)
+	}
+
+	fmt.Println("=== Descrybe v2 WooCommerce demo seed ===")
+	fmt.Printf("company:            %s (%s)\n", companyNameNorm, companyID)
+	fmt.Printf("category:           %s (%s)\n", demoCategoryName, categoryID)
+	fmt.Printf("demo products:      %d (SKU prefix %s)\n", len(products), demoSKUPrefix)
+	fmt.Printf("orders upserted:    %d\n", orderCount)
+	fmt.Printf("order items:        %d\n", itemCount)
+	fmt.Printf("reviews upserted:   %d\n", reviewCount)
+	fmt.Printf("audience (%s): %d customers\n", demoCategoryName, audience.Total)
+	for _, c := range audience.Customers {
+		fmt.Printf("  - %s <%s>\n", c.Name, c.Email)
+	}
+	fmt.Printf("draft campaign:     %s\n", campaignID)
+	fmt.Printf("config store_url:   %s\n", storeURL)
+	if fromEnv {
+		fmt.Println("credentials:        from WOO_* env (encrypted at rest)")
+	} else {
+		fmt.Println("credentials:        demo placeholders (no live REST)")
+	}
+	fmt.Println()
+	fmt.Println("Next:")
+	fmt.Println("  1. Open /woocommerce — Orders & Reviews tabs should list seeded rows")
+	fmt.Println("  2. POST /api/woocommerce/audience {\"bought_category\":\"Demo Electronics\"}")
+	fmt.Println("  3. Open /campaigns — draft \"Woo demo — purchased electronics\" uses purchased audience")
+	fmt.Println("  4. Live store: set WOO_STORE_URL / WOO_CONSUMER_KEY / WOO_CONSUMER_SECRET then re-run with -live")
+
+	if *live || (fromEnv && flag.Lookup("live").Value.String() == "true") {
+		// handled below when -live
+	}
+	if *live {
+		if !fromEnv {
+			log.Fatal("-live requires WOO_STORE_URL, WOO_CONSUMER_KEY, WOO_CONSUMER_SECRET")
+		}
+		client := woocommerce.NewClient(storeURL, key, secret, &http.Client{Timeout: 20 * time.Second})
+		if err := client.TestConnection(ctx); err != nil {
+			log.Fatalf("live Woo test failed: %v", err)
+		}
+		fmt.Println("live Woo test:      OK")
+	} else if fromEnv {
+		client := woocommerce.NewClient(storeURL, key, secret, &http.Client{Timeout: 20 * time.Second})
+		if err := client.TestConnection(ctx); err != nil {
+			fmt.Printf("live Woo test:      skipped/failed (%v) — demo DB seed still applied\n", err)
+		} else {
+			fmt.Println("live Woo test:      OK (WOO_* present)")
+		}
+	}
+}
+
+func resolveCompany(ctx context.Context, pg *pgxpool.Pool, name string) (uuid.UUID, error) {
+	var id uuid.UUID
+	err := pg.QueryRow(ctx, `
+		SELECT id FROM companies WHERE name = $1 ORDER BY updated_at DESC LIMIT 1`, name).Scan(&id)
+	if err != nil {
+		return uuid.Nil, fmt.Errorf("%q: %w", name, err)
+	}
+	return id, nil
+}
+
+func ensureDemoCategory(ctx context.Context, tx pgx.Tx, companyID uuid.UUID) (uuid.UUID, error) {
+	var id uuid.UUID
+	err := tx.QueryRow(ctx, `
+		INSERT INTO categories (company_id, name, unique_id, path, level, position, is_active, updated_at)
+		VALUES ($1, $2, $3, $2, 0, 0, true, now())
+		ON CONFLICT (company_id, unique_id) DO UPDATE SET
+			name = EXCLUDED.name,
+			is_active = true,
+			updated_at = now()
+		RETURNING id`, companyID, demoCategoryName, demoCategoryUID).Scan(&id)
+	return id, err
+}
+
+func seedDemoProducts(ctx context.Context, tx pgx.Tx, companyID uuid.UUID, products []demoProduct) error {
+	for _, p := range products {
+		mapped, _ := json.Marshal(map[string]any{
+			"sku":           p.SKU,
+			"price":         p.Price,
+			"regular_price": p.Price,
+			"images":        []string{},
+			"source":        "seed-woo-demo",
+		})
+		attrs, _ := json.Marshal(map[string]any{"Brand": "Descrybe Demo"})
+		_, err := tx.Exec(ctx, `
+			INSERT INTO processed_products (
+				company_id, product_id, name, category, description, processed_name, processed_description,
+				attributes, processed_attributes, status, updated_at
+			) VALUES (
+				$1, $2, $3, $4, $5, $3, $5, $6::jsonb, $6::jsonb, 'completed', now()
+			)
+			ON CONFLICT DO NOTHING`,
+			companyID, p.SKU, p.Name, p.Category,
+			"Seeded demo product for WooCommerce integration testing.", attrs)
+		if err != nil {
+			// processed_products may lack a unique on product_id; fall back to upsert-by-lookup.
+			var existing uuid.UUID
+			qerr := tx.QueryRow(ctx, `
+				SELECT id FROM processed_products
+				WHERE company_id = $1 AND product_id = $2 LIMIT 1`, companyID, p.SKU).Scan(&existing)
+			if qerr == nil {
+				_, err = tx.Exec(ctx, `
+					UPDATE processed_products SET
+						name = $3, category = $4, description = $5, processed_name = $3,
+						processed_description = $5, attributes = $6::jsonb, processed_attributes = $6::jsonb,
+						status = 'completed', updated_at = now()
+					WHERE id = $2 AND company_id = $1`,
+					companyID, existing, p.Name, p.Category,
+					"Seeded demo product for WooCommerce integration testing.", attrs)
+				if err != nil {
+					return err
+				}
+			} else if qerr == pgx.ErrNoRows {
+				_, err = tx.Exec(ctx, `
+					INSERT INTO processed_products (
+						company_id, product_id, name, category, description, processed_name, processed_description,
+						attributes, processed_attributes, status, updated_at
+					) VALUES (
+						$1, $2, $3, $4, $5, $3, $5, $6::jsonb, $6::jsonb, 'completed', now()
+					)`,
+					companyID, p.SKU, p.Name, p.Category,
+					"Seeded demo product for WooCommerce integration testing.", attrs)
+				if err != nil {
+					return err
+				}
+			} else {
+				return qerr
+			}
+		}
+		_ = mapped
+	}
+	return nil
+}
+
+func seedDemoOrders(ctx context.Context, tx pgx.Tx, companyID uuid.UUID, products []demoProduct, customers []demoCustomer) (int, int, error) {
+	type line struct {
+		product demoProduct
+		qty     int
+		cats    []string
+	}
+	type orderSpec struct {
+		externalID int64
+		status     string
+		customer   demoCustomer
+		total      string
+		lines      []line
+		daysAgo    int
+	}
+
+	specs := []orderSpec{
+		{
+			externalID: 88001, status: "completed", customer: customers[0], total: "648.00", daysAgo: 12,
+			lines: []line{
+				{product: products[0], qty: 1, cats: []string{demoCategoryName}},
+				{product: products[1], qty: 1, cats: []string{demoCategoryName}},
+			},
+		},
+		{
+			externalID: 88002, status: "processing", customer: customers[1], total: "89.00", daysAgo: 5,
+			lines: []line{{product: products[2], qty: 1, cats: []string{demoCategoryName}}},
+		},
+		{
+			externalID: 88003, status: "completed", customer: customers[2], total: "499.00", daysAgo: 3,
+			lines: []line{{product: products[0], qty: 1, cats: []string{demoCategoryName}}},
+		},
+		{
+			externalID: 88004, status: "completed", customer: customers[3], total: "29.00", daysAgo: 8,
+			lines: []line{{
+				product: demoProduct{SKU: "OTHER-SKU-1", Name: "Demo Cable Pack", Price: "29.00", WCID: 90100},
+				qty:     1,
+				cats:    []string{"Accessories"},
+			}},
+		},
+	}
+
+	orders := 0
+	items := 0
+	for _, spec := range specs {
+		payload, _ := json.Marshal(map[string]any{
+			"id":           spec.externalID,
+			"status":       spec.status,
+			"currency":     "EUR",
+			"total":        spec.total,
+			"billing":      map[string]any{"email": spec.customer.Email, "first_name": strings.Split(spec.customer.Name, " ")[0]},
+			"line_items":   len(spec.lines),
+			"seed":         "seed-woo-demo",
+		})
+		orderedAt := time.Now().UTC().Add(-time.Duration(spec.daysAgo) * 24 * time.Hour)
+		var orderID uuid.UUID
+		err := tx.QueryRow(ctx, `
+			INSERT INTO woo_orders (
+				company_id, external_id, status, currency, total, customer_email, customer_name,
+				ordered_at, payload, synced_at, updated_at
+			) VALUES (
+				$1, $2, $3, 'EUR', $4::numeric, $5, $6, $7, $8::jsonb, now(), now()
+			)
+			ON CONFLICT (company_id, external_id) DO UPDATE SET
+				status = EXCLUDED.status,
+				total = EXCLUDED.total,
+				customer_email = EXCLUDED.customer_email,
+				customer_name = EXCLUDED.customer_name,
+				ordered_at = EXCLUDED.ordered_at,
+				payload = EXCLUDED.payload,
+				synced_at = now(),
+				updated_at = now()
+			RETURNING id`,
+			companyID, spec.externalID, spec.status, spec.total,
+			strings.ToLower(spec.customer.Email), spec.customer.Name, orderedAt, payload,
+		).Scan(&orderID)
+		if err != nil {
+			return orders, items, err
+		}
+		orders++
+
+		if _, err := tx.Exec(ctx, `DELETE FROM woo_order_items WHERE company_id = $1 AND order_id = $2`, companyID, orderID); err != nil {
+			return orders, items, err
+		}
+		for i, ln := range spec.lines {
+			catsRaw, _ := json.Marshal(ln.cats)
+			itemPayload, _ := json.Marshal(map[string]any{
+				"id":         int64(spec.externalID*10 + int64(i+1)),
+				"product_id": ln.product.WCID,
+				"sku":        ln.product.SKU,
+				"name":       ln.product.Name,
+				"quantity":   ln.qty,
+				"total":      ln.product.Price,
+				"categories": ln.cats,
+			})
+			_, err := tx.Exec(ctx, `
+				INSERT INTO woo_order_items (
+					company_id, order_id, external_id, product_id, sku, name, quantity, total, categories, payload, updated_at
+				) VALUES (
+					$1, $2, $3, $4, $5, $6, $7, $8::numeric, $9::jsonb, $10::jsonb, now()
+				)`,
+				companyID, orderID, spec.externalID*10+int64(i+1), ln.product.WCID,
+				ln.product.SKU, ln.product.Name, ln.qty, ln.product.Price, catsRaw, itemPayload,
+			)
+			if err != nil {
+				return orders, items, err
+			}
+			items++
+		}
+	}
+	return orders, items, nil
+}
+
+func seedDemoReviews(ctx context.Context, tx pgx.Tx, companyID uuid.UUID, products []demoProduct, customers []demoCustomer) (int, error) {
+	type rev struct {
+		externalID int64
+		product    demoProduct
+		customer   demoCustomer
+		rating     int
+		status     string
+		body       string
+		daysAgo    int
+	}
+	specs := []rev{
+		{88011, products[0], customers[0], 5, "approved", "Picture quality is excellent for the price.", 10},
+		{88012, products[2], customers[1], 4, "approved", "Comfortable and clear sound.", 4},
+		{88013, products[1], customers[2], 3, "hold", "Good bass, wish the remote was better.", 2},
+	}
+	n := 0
+	for _, r := range specs {
+		payload, _ := json.Marshal(map[string]any{
+			"id": r.externalID, "product_id": r.product.WCID, "rating": r.rating, "seed": "seed-woo-demo",
+		})
+		reviewedAt := time.Now().UTC().Add(-time.Duration(r.daysAgo) * 24 * time.Hour)
+		_, err := tx.Exec(ctx, `
+			INSERT INTO product_reviews (
+				company_id, external_id, product_id, product_name, status, reviewer, reviewer_email,
+				rating, review, reviewed_at, payload, synced_at, updated_at
+			) VALUES (
+				$1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11::jsonb, now(), now()
+			)
+			ON CONFLICT (company_id, external_id) DO UPDATE SET
+				product_id = EXCLUDED.product_id,
+				product_name = EXCLUDED.product_name,
+				status = EXCLUDED.status,
+				reviewer = EXCLUDED.reviewer,
+				reviewer_email = EXCLUDED.reviewer_email,
+				rating = EXCLUDED.rating,
+				review = EXCLUDED.review,
+				reviewed_at = EXCLUDED.reviewed_at,
+				payload = EXCLUDED.payload,
+				synced_at = now(),
+				updated_at = now()`,
+			companyID, r.externalID, r.product.WCID, r.product.Name, r.status,
+			r.customer.Name, strings.ToLower(r.customer.Email), r.rating, r.body, reviewedAt, payload,
+		)
+		if err != nil {
+			return n, err
+		}
+		n++
+	}
+	return n, nil
+}
+
+func wooCredsFromEnv() (storeURL, key, secret string, ok bool) {
+	storeURL = strings.TrimSpace(os.Getenv("WOO_STORE_URL"))
+	if storeURL == "" {
+		storeURL = strings.TrimSpace(os.Getenv("WOOCOMMERCE_STORE_URL"))
+	}
+	key = strings.TrimSpace(os.Getenv("WOO_CONSUMER_KEY"))
+	if key == "" {
+		key = strings.TrimSpace(os.Getenv("WOOCOMMERCE_CONSUMER_KEY"))
+	}
+	secret = strings.TrimSpace(os.Getenv("WOO_CONSUMER_SECRET"))
+	if secret == "" {
+		secret = strings.TrimSpace(os.Getenv("WOOCOMMERCE_CONSUMER_SECRET"))
+	}
+	if storeURL != "" && key != "" && secret != "" {
+		return storeURL, key, secret, true
+	}
+	return "https://demo.woocommerce.local", "ck_demo_placeholder", "cs_demo_placeholder", false
+}
+
+func upsertWooConfig(ctx context.Context, tx pgx.Tx, companyID uuid.UUID, encKey []byte, storeURL, key, secret string, live bool) error {
+	normalized, err := woocommerce.NormalizeStoreURL(storeURL)
+	if err != nil {
+		if errors.Is(err, woocommerce.ErrBlockedStoreURL) || live {
+			return err
+		}
+		// Offline demo placeholder only (never a private/metadata IP).
+		normalized = "https://demo.woocommerce.local"
+	}
+	keyEnc, err := woocommerce.EncryptSecret(encKey, key)
+	if err != nil {
+		return err
+	}
+	secretEnc, err := woocommerce.EncryptSecret(encKey, secret)
+	if err != nil {
+		return err
+	}
+	now := time.Now().UTC()
+	opt := woocommerce.SyncOptions{
+		MatchStrategy:         "sku",
+		LastSyncStatus:        "success",
+		LastOrdersSyncStatus:  "success",
+		LastReviewsSyncStatus: "success",
+		LastOrdersSyncedAt:    &now,
+		LastReviewsSyncedAt:   &now,
+		ProductIDs:            map[string]int{},
+		CategoryMappings:      map[string]woocommerce.CategoryMap{},
+		AttributeMappings:     map[string]woocommerce.AttributeMap{},
+	}
+	raw, err := json.Marshal(opt)
+	if err != nil {
+		return err
+	}
+	enabled := live
+	testStatus := "demo"
+	if live {
+		testStatus = "ok"
+	}
+	_, err = tx.Exec(ctx, `
+		INSERT INTO woocommerce_configs (
+			company_id, store_url, consumer_key, consumer_secret, is_enabled, sync_options,
+			last_synced_at, last_test_at, last_test_status, updated_at
+		) VALUES (
+			$1, $2, $3, $4, $5, $6::jsonb, now(), now(), $7, now()
+		)
+		ON CONFLICT (company_id) DO UPDATE SET
+			store_url = EXCLUDED.store_url,
+			consumer_key = EXCLUDED.consumer_key,
+			consumer_secret = EXCLUDED.consumer_secret,
+			is_enabled = EXCLUDED.is_enabled,
+			sync_options = EXCLUDED.sync_options,
+			last_synced_at = EXCLUDED.last_synced_at,
+			last_test_at = EXCLUDED.last_test_at,
+			last_test_status = EXCLUDED.last_test_status,
+			updated_at = now()`,
+		companyID, normalized, keyEnc, secretEnc, enabled, raw, testStatus)
+	return err
+}
+
+func seedDemoCampaign(ctx context.Context, tx pgx.Tx, companyID, categoryID uuid.UUID) (uuid.UUID, error) {
+	af, _ := json.Marshal(map[string]any{
+		"type":             "purchased",
+		"category_ids":     []string{categoryID.String()},
+		"bought_category":  demoCategoryName,
+		"bought_categories": []string{demoCategoryName},
+	})
+	name := "Woo demo — purchased electronics"
+	var id uuid.UUID
+	err := tx.QueryRow(ctx, `
+		SELECT id FROM email_campaigns
+		WHERE company_id = $1 AND name = $2
+		ORDER BY created_at DESC LIMIT 1`, companyID, name).Scan(&id)
+	if err == nil {
+		_, err = tx.Exec(ctx, `
+			UPDATE email_campaigns SET
+				category_ids = ARRAY[$2]::uuid[],
+				audience_filter = $3::jsonb,
+				status = 'draft',
+				updated_at = now()
+			WHERE id = $4 AND company_id = $1`,
+			companyID, categoryID, af, id)
+		return id, err
+	}
+	if err != pgx.ErrNoRows {
+		return uuid.Nil, err
+	}
+	err = tx.QueryRow(ctx, `
+		INSERT INTO email_campaigns (
+			company_id, name, template_key, status, category_ids, product_ids,
+			prompt, use_default_prompt, audience_filter, updated_at
+		) VALUES (
+			$1, $2, 'black_friday', 'draft', ARRAY[$3]::uuid[], ARRAY[]::uuid[],
+			'Highlight Demo Electronics for past buyers.', true, $4::jsonb, now()
+		)
+		RETURNING id`, companyID, name, categoryID, af).Scan(&id)
+	return id, err
+}

apps/api/cmd/sync-plans/main.go

@@ -0,0 +1,65 @@
+// Command sync-plans upserts public Free→Enterprise ladder meters into Postgres.
+// Usage (from apps/api):
+//
+//	go run ./cmd/sync-plans -postgres "$DATABASE_URL"
+package main
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/descrybe/descrybe-v2/apps/api/internal/billing"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+func main() {
+	pg := flag.String("postgres", os.Getenv("DATABASE_URL"), "Postgres DATABASE_URL")
+	flag.Parse()
+	if strings.TrimSpace(*pg) == "" {
+		fmt.Fprintln(os.Stderr, "DATABASE_URL or -postgres required")
+		os.Exit(1)
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+	pool, err := pgxpool.New(ctx, *pg)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "connect: %v\n", err)
+		os.Exit(1)
+	}
+	defer pool.Close()
+	svc := &billing.Service{Pool: pool}
+	if err := svc.EnsureDefaultPlans(ctx); err != nil {
+		fmt.Fprintf(os.Stderr, "EnsureDefaultPlans: %v\n", err)
+		os.Exit(1)
+	}
+	rows, err := pool.Query(ctx, `
+		SELECT name, monthly_credits, COALESCE(max_products::text, 'unlimited')
+		FROM plans
+		WHERE lower(name) IN ('free','starter','plus','growth','business','scale','enterprise')
+		ORDER BY CASE lower(name)
+			WHEN 'free' THEN 0 WHEN 'starter' THEN 1 WHEN 'plus' THEN 2 WHEN 'growth' THEN 3
+			WHEN 'business' THEN 4 WHEN 'scale' THEN 5 WHEN 'enterprise' THEN 6 ELSE 9 END`)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "list: %v\n", err)
+		os.Exit(1)
+	}
+	defer rows.Close()
+	fmt.Println("Public plans synced:")
+	for rows.Next() {
+		var name, maxP string
+		var credits int
+		if err := rows.Scan(&name, &credits, &maxP); err != nil {
+			fmt.Fprintf(os.Stderr, "scan: %v\n", err)
+			os.Exit(1)
+		}
+		fmt.Printf("  %-12s credits=%-8d max_products=%s\n", name, credits, maxP)
+	}
+	if err := rows.Err(); err != nil {
+		fmt.Fprintf(os.Stderr, "rows: %v\n", err)
+		os.Exit(1)
+	}
+}

apps/api/cmd/sync-stripe-packs/main.go

@@ -0,0 +1,90 @@
+// Command sync-stripe-packs ensures each DefaultCreditPack exists in Stripe as a
+// Product + one-time Price, then prints Price IDs (and optionally writes them to
+// platform settings when -write-settings is set).
+//
+//	go run ./cmd/sync-stripe-packs
+//	go run ./cmd/sync-stripe-packs -write-settings
+package main
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/descrybe/descrybe-v2/apps/api/internal/billing"
+	"github.com/descrybe/descrybe-v2/apps/api/internal/platformsettings"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+func main() {
+	pg := flag.String("postgres", os.Getenv("DATABASE_URL"), "Postgres DATABASE_URL")
+	writeSettings := flag.Bool("write-settings", false, "Upsert stripe.price.pack.* into platform settings")
+	flag.Parse()
+
+	secret := strings.TrimSpace(os.Getenv("STRIPE_SECRET_KEY"))
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+	defer cancel()
+
+	var pool *pgxpool.Pool
+	var plat *platformsettings.Service
+	if strings.TrimSpace(*pg) != "" {
+		var err error
+		pool, err = pgxpool.New(ctx, *pg)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "connect: %v\n", err)
+			os.Exit(1)
+		}
+		defer pool.Close()
+		plat = &platformsettings.Service{Pool: pool}
+		if resolved, err := plat.ResolveStripe(ctx, billing.StripeConfig{SecretKey: secret}); err == nil {
+			if strings.TrimSpace(resolved.SecretKey) != "" {
+				secret = resolved.SecretKey
+			}
+		}
+	}
+	if secret == "" {
+		fmt.Fprintln(os.Stderr, "STRIPE_SECRET_KEY (or stripe.secret_key in admin settings) required")
+		os.Exit(1)
+	}
+
+	svc := &billing.StripeService{
+		Pool: pool,
+		Cfg:  billing.StripeConfig{SecretKey: secret},
+	}
+	results, err := svc.SyncCreditPackProducts(ctx)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "sync: %v\n", err)
+		os.Exit(1)
+	}
+
+	fmt.Println("Stripe credit packs (one-time products):")
+	for _, r := range results {
+		flag := "ok"
+		if r.Created {
+			flag = "created/updated"
+		}
+		fmt.Printf("  %-8s  $%-5d  credits=%-6d  price=%s  product=%s  (%s)\n",
+			r.PackID, r.PriceUSD, r.Credits, r.PriceID, r.ProductID, flag)
+		if *writeSettings {
+			if plat == nil {
+				fmt.Fprintln(os.Stderr, "-write-settings requires DATABASE_URL")
+				os.Exit(1)
+			}
+			key := billing.CreditPackSettingsKey(r.PackID)
+			if err := plat.SetKV(ctx, key, r.PriceID); err != nil {
+				fmt.Fprintf(os.Stderr, "write %s: %v\n", key, err)
+				os.Exit(1)
+			}
+			fmt.Printf("    wrote %s\n", key)
+		} else {
+			fmt.Printf("    settings key: %s\n", billing.CreditPackSettingsKey(r.PackID))
+			fmt.Printf("    env fallback: %s=%s\n", billing.CreditPackEnvVar(r.PackID), r.PriceID)
+		}
+	}
+	if !*writeSettings {
+		fmt.Println("\nRe-run with -write-settings to store Price IDs in platform settings.")
+	}
+}

apps/api/cmd/worker/main.go

@@ -0,0 +1,370 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"log"
+	"net/http"
+	"os"
+	"os/signal"
+	"strings"
+	"syscall"
+	"time"
+
+	"github.com/descrybe/descrybe-v2/apps/api/internal/aiprompts"
+	"github.com/descrybe/descrybe-v2/apps/api/internal/aiprovider"
+	"github.com/descrybe/descrybe-v2/apps/api/internal/billing"
+	"github.com/descrybe/descrybe-v2/apps/api/internal/config"
+	"github.com/descrybe/descrybe-v2/apps/api/internal/db"
+	"github.com/descrybe/descrybe-v2/apps/api/internal/feeds"
+	"github.com/descrybe/descrybe-v2/apps/api/internal/jobs"
+	"github.com/descrybe/descrybe-v2/apps/api/internal/logredact"
+	"github.com/descrybe/descrybe-v2/apps/api/internal/metrics"
+	"github.com/descrybe/descrybe-v2/apps/api/internal/platformsettings"
+	"github.com/descrybe/descrybe-v2/apps/api/internal/processing"
+	"github.com/descrybe/descrybe-v2/apps/api/internal/shopify"
+	"github.com/descrybe/descrybe-v2/apps/api/internal/support"
+	"github.com/descrybe/descrybe-v2/apps/api/internal/woocommerce"
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5"
+)
+
+func main() {
+	log.SetOutput(logredact.Writer(os.Stderr))
+	cfg, err := config.Load()
+	if err != nil {
+		log.Fatalf("config: %v", err)
+	}
+	ctx, cancel := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+	defer cancel()
+
+	pool, err := db.NewPool(ctx, cfg.DatabaseURL, db.PoolOptions{
+		MaxConns:              int32(cfg.DBMaxConns),
+		MinConns:              int32(cfg.DBMinConns),
+		MaxConnLifetime:       cfg.DBMaxConnLifetime,
+		MaxConnLifetimeJitter: cfg.DBMaxConnLifetimeJitter,
+		MaxConnIdleTime:       cfg.DBMaxConnIdleTime,
+		HealthCheckPeriod:     cfg.DBHealthCheckPeriod,
+		StatementTimeout:      cfg.DBStatementTimeout,
+	})
+	if err != nil {
+		log.Fatalf("db: %v", err)
+	}
+	defer pool.Close()
+
+	if addr := strings.TrimSpace(os.Getenv("METRICS_ADDR")); addr != "" {
+		go func() {
+			mux := http.NewServeMux()
+			mux.Handle("/metrics", metrics.Gate(cfg.IsProduction(), cfg.MetricsPublic)(metrics.Handler()))
+			log.Printf("metrics listening on %s", addr)
+			if err := http.ListenAndServe(addr, mux); err != nil {
+				log.Printf("metrics server: %v", err)
+			}
+		}()
+	}
+
+	platSettings := platformsettings.NewService(pool, platformsettings.EnvConfig{
+		AppEncryptionKey:         cfg.AppEncryptionKey,
+		CredentialsEncryptionKey: cfg.CredentialsEncryptionKey,
+		TokenSigningSecret:       cfg.TokenSigningSecret,
+		DatabaseURL:              cfg.DatabaseURL,
+		OpenAIAPIKey:             cfg.OpenAIAPIKey,
+		OpenAIBaseURL:            cfg.OpenAIBaseURL,
+		OpenAIModel:              cfg.OpenAIModel,
+		OpenAIEmbeddingAPIKey:    cfg.OpenAIEmbeddingAPIKey,
+		OpenAIEmbeddingBaseURL:   cfg.OpenAIEmbeddingBaseURL,
+		OpenAIEmbeddingModel:     cfg.OpenAIEmbeddingModel,
+		EPRELEnabled:             cfg.EPRELEnabled,
+		EPRELBaseURL:             cfg.EPRELBaseURL,
+		EPRELTimeout:             cfg.EPRELTimeout,
+		EPRELFicheLanguage:       cfg.EPRELFicheLanguage,
+		EPRELAPIKey:              cfg.EPRELAPIKey,
+		PineconeAPIKey:           cfg.PineconeAPIKey,
+		PineconeHost:             cfg.PineconeHost,
+		PineconeNamespace:        cfg.PineconeNamespace,
+	})
+	aiSvc := aiprovider.NewService(pool, aiprovider.EnvConfig{
+		AppEncryptionKey:         cfg.AppEncryptionKey,
+		CredentialsEncryptionKey: cfg.CredentialsEncryptionKey,
+		TokenSigningSecret:       cfg.TokenSigningSecret,
+		DatabaseURL:              cfg.DatabaseURL,
+		OpenAIAPIKey:             cfg.OpenAIAPIKey,
+		OpenAIBaseURL:            cfg.OpenAIBaseURL,
+		OpenAIModel:              cfg.OpenAIModel,
+		ProcessingRPM:            cfg.ProcessingRPM,
+		ProcessingMaxRetries:     cfg.ProcessingMaxRetries,
+	})
+	aiSvc.Platform = platSettings
+
+	pipeline := processing.NewPipeline(pool)
+	pipeline.BatchSize = cfg.ProcessingBatchSize
+	pipeline.AI = aiSvc
+	pipeline.Prompts = aiprompts.NewService(pool)
+
+	// OpenAI resolved per job via aiSvc → platformsettings.ResolveOpenAI (no boot snapshot).
+	if oi, rerr := platSettings.ResolveOpenAI(ctx); rerr != nil {
+		log.Printf("worker: platform OpenAI resolve failed: %v (AI enhance skipped until admin settings or BYOK)", rerr)
+	} else if strings.TrimSpace(oi.APIKey) != "" {
+		log.Printf("worker: OpenAI configured source=%s base=%s model=%s rpm=%d (resolved per job; company BYOK preferred when set)", oi.Source, oi.BaseURL, oi.Model, cfg.ProcessingRPM)
+	} else {
+		log.Println("worker: platform OpenAI unset - configure in admin settings or company BYOK; AI enhance skipped until then")
+	}
+
+	vector := processing.VectorCategorizer(&platformsettings.DynamicPinecone{Settings: platSettings})
+	if pc, rerr := platSettings.ResolvePinecone(ctx); rerr != nil {
+		log.Printf("worker: platform Pinecone resolve failed: %v (vector categorize skipped until admin settings)", rerr)
+	} else if pc.Configured() {
+		if emb, eerr := platSettings.ResolveEmbedder(ctx); eerr != nil {
+			log.Printf("worker: vectorization AI resolve failed: %v (Pinecone text-query mode)", eerr)
+		} else if emb != nil {
+			log.Println("worker: Pinecone vector categorizer ready (embeddings via admin AI role vectorization / env)")
+		} else {
+			log.Println("worker: Pinecone vector categorizer ready (text query; set ai_configs.vectorization or OPENAI_EMBEDDING_* for explicit embeddings)")
+		}
+	} else {
+		log.Println("worker: Pinecone unset - configure in /admin/settings; vector categorize skipped until then")
+	}
+
+	var eprelClient processing.EPRELEnricher = &platformsettings.DynamicEPREL{Settings: platSettings}
+	if cfg.EPRELEnabled {
+		log.Printf("worker: EPREL enricher ready (env enabled=%v; admin settings can override)", cfg.EPRELEnabled)
+	} else {
+		log.Println("worker: EPREL enricher uses platform settings / env (default disabled)")
+	}
+
+	pipeline.Engine = &processing.Engine{
+		Vector:       vector,
+		EPREL:        eprelClient,
+		ProviderMode: processing.AIProviderInternal,
+	}
+
+	wooKeyMaterial := cfg.CredentialsEncryptionKey
+	if wooKeyMaterial == "" {
+		wooKeyMaterial = cfg.TokenSigningSecret
+	}
+	shopKeyMaterial := cfg.AppEncryptionKey
+	if shopKeyMaterial == "" {
+		shopKeyMaterial = wooKeyMaterial
+	}
+	woo := woocommerce.NewService(pool, woocommerce.DeriveKey(wooKeyMaterial, cfg.DatabaseURL))
+	shop := shopify.NewService(pool, shopify.DeriveKey(shopKeyMaterial, cfg.DatabaseURL))
+	feedSvc := &feeds.Service{Pool: pool, UploadDir: cfg.UploadDir}
+	billingSvc := &billing.Service{Pool: pool}
+	_ = billingSvc.EnsureDefaultCosts(ctx)
+	supportSvc := support.NewService(pool)
+	supportSvc.SupportAI = support.NewCompleterSupportAI(aiSvc)
+	supportSvc.AIRateLimiter = support.NewAIRateLimiter(0, 0)
+	jobSlots := processing.NewJobSlots(processing.DefaultProcessingWorkers)
+	syncSlots := jobs.NewSyncSlots(jobs.DefaultSyncWorkers)
+	log.Printf("worker started - processing workers=%d sync workers=%d poll=%s LISTEN=%s,%s (ClaimNext SKIP LOCKED) + feed sync claim + support AI auto + woo/shopify claim + scheduled enqueue + billing cycles", jobSlots.Workers, syncSlots.Workers, cfg.ProcessingPollInterval, jobs.ChannelProcessingJobs, jobs.ChannelFeedSyncJobs)
+
+	if err := jobs.TouchHeartbeat(ctx, pool, jobs.ProcessingWorkerID); err != nil {
+		log.Printf("worker heartbeat bootstrap: %v", err)
+	}
+
+	wake := make(chan struct{}, 1)
+	go func() {
+		if err := jobs.ListenWake(ctx, pool, wake, jobs.ChannelProcessingJobs, jobs.ChannelFeedSyncJobs); err != nil && !errors.Is(err, context.Canceled) {
+			log.Printf("worker listen wake stopped: %v", err)
+		}
+	}()
+
+	ticker := time.NewTicker(cfg.ProcessingPollInterval)
+	defer ticker.Stop()
+	opsTicker := time.NewTicker(15 * time.Minute)
+	defer opsTicker.Stop()
+
+	markJobFailed := func(jobID uuid.UUID, jobErr error) {
+		if jobErr == nil {
+			log.Printf("job %s finished", jobID)
+			return
+		}
+		if errors.Is(jobErr, context.Canceled) || errors.Is(jobErr, context.DeadlineExceeded) || ctx.Err() != nil {
+			log.Printf("job %s interrupted: %v", jobID, processing.TruncateError(jobErr))
+			return
+		}
+		log.Printf("job %s failed: %v", jobID, processing.TruncateError(jobErr))
+		markCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+		defer cancel()
+		_, execErr := pool.Exec(markCtx, `
+			UPDATE processing_jobs
+			SET status = 'failed', error = $2, completed_at = now(), updated_at = now()
+			WHERE id = $1 AND status = 'running'`,
+			jobID, processing.TruncateError(jobErr))
+		if execErr != nil {
+			log.Printf("job %s mark failed: %v", jobID, execErr)
+		}
+	}
+
+	runOnce := func() {
+		if err := jobs.TouchHeartbeat(ctx, pool, jobs.ProcessingWorkerID); err != nil {
+			log.Printf("worker heartbeat: %v", err)
+		}
+		if cfg.MaintenanceMode || cfg.ReadOnlyMode {
+			return
+		}
+		if n, err := supportSvc.ProcessPendingAutoJobs(ctx, 3); err != nil {
+			log.Printf("support auto AI jobs: %v", err)
+		} else if n > 0 {
+			log.Printf("support auto AI jobs processed=%d", n)
+		}
+		if _, err := jobSlots.Fill(ctx, pipeline.ClaimNext, func(jobCtx context.Context, jobID uuid.UUID) error {
+			log.Printf("processing job %s", jobID)
+			return pipeline.ProcessJob(jobCtx, jobID)
+		}, markJobFailed); err != nil && !errors.Is(err, pgx.ErrNoRows) {
+			log.Printf("claim error: %v", err)
+		}
+
+		if n, autoErr := supportSvc.ProcessPendingAutoJobs(ctx, 3); autoErr != nil {
+			log.Printf("support auto AI jobs: %v", autoErr)
+		} else if n > 0 {
+			log.Printf("support auto AI jobs processed=%d", n)
+		}
+
+		var syncJobID, syncCompanyID, syncFeedID uuid.UUID
+		if started, err := syncSlots.TryStart(func() error {
+			var e error
+			syncJobID, syncCompanyID, syncFeedID, e = feedSvc.ClaimNextPendingSyncJob(ctx)
+			return e
+		}, func() {
+			log.Printf("feed sync job %s feed %s company %s", syncJobID, syncFeedID, syncCompanyID)
+			start := time.Now()
+			syncErr := feedSvc.ProcessSyncJob(ctx, syncCompanyID, syncFeedID, syncJobID)
+			metrics.ObserveSync("feed", syncErr, time.Since(start))
+			if syncErr != nil {
+				log.Printf("feed sync job %s failed: %v", syncJobID, syncErr)
+			} else {
+				log.Printf("feed sync job %s done", syncJobID)
+			}
+		}); err != nil && !errors.Is(err, pgx.ErrNoRows) {
+			log.Printf("feed sync claim error: %v", err)
+		} else if started {
+			return
+		}
+
+		var wooCompanyID uuid.UUID
+		var wooKind string
+		if started, err := syncSlots.TryStart(func() error {
+			var e error
+			wooCompanyID, wooKind, e = woo.ClaimNextPendingJob(ctx)
+			return e
+		}, func() {
+			log.Printf("woocommerce %s sync company %s", wooKind, wooCompanyID)
+			start := time.Now()
+			switch wooKind {
+			case "orders":
+				summary, err := woo.SyncOrders(ctx, wooCompanyID)
+				metrics.ObserveSync("woocommerce_orders", err, time.Since(start))
+				if err != nil {
+					log.Printf("woocommerce orders sync %s failed: %v", wooCompanyID, err)
+					return
+				}
+				log.Printf("woocommerce orders sync %s done pages=%d fetched=%d upserted=%d items=%d failed=%d",
+					wooCompanyID, summary.Pages, summary.Fetched, summary.Upserted, summary.ItemsSaved, summary.Failed)
+			case "reviews":
+				summary, err := woo.SyncReviews(ctx, wooCompanyID)
+				metrics.ObserveSync("woocommerce_reviews", err, time.Since(start))
+				if err != nil {
+					log.Printf("woocommerce reviews sync %s failed: %v", wooCompanyID, err)
+					return
+				}
+				log.Printf("woocommerce reviews sync %s done pages=%d fetched=%d upserted=%d failed=%d",
+					wooCompanyID, summary.Pages, summary.Fetched, summary.Upserted, summary.Failed)
+			default:
+				summary, err := woo.SyncCompany(ctx, wooCompanyID)
+				metrics.ObserveSync("woocommerce", err, time.Since(start))
+				if err != nil {
+					log.Printf("woocommerce sync %s failed: %v", wooCompanyID, err)
+					return
+				}
+				log.Printf("woocommerce sync %s done total=%d created=%d updated=%d failed=%d",
+					wooCompanyID, summary.Total, summary.Created, summary.Updated, summary.Failed)
+			}
+		}); err != nil && !errors.Is(err, pgx.ErrNoRows) {
+			log.Printf("woo claim error: %v", err)
+		} else if started {
+			return
+		}
+
+		var shopCompanyID uuid.UUID
+		var shopKind string
+		if _, err := syncSlots.TryStart(func() error {
+			var e error
+			shopCompanyID, shopKind, e = shop.ClaimNextPendingJob(ctx)
+			return e
+		}, func() {
+			log.Printf("shopify %s sync company %s", shopKind, shopCompanyID)
+			start := time.Now()
+			switch shopKind {
+			case "orders":
+				summary, err := shop.SyncOrders(ctx, shopCompanyID)
+				metrics.ObserveSync("shopify_orders", err, time.Since(start))
+				if err != nil {
+					log.Printf("shopify orders sync %s failed: %v", shopCompanyID, err)
+					return
+				}
+				log.Printf("shopify orders sync %s done pages=%d fetched=%d upserted=%d items=%d failed=%d",
+					shopCompanyID, summary.Pages, summary.Fetched, summary.Upserted, summary.ItemsSaved, summary.Failed)
+			default:
+				summary, err := shop.SyncCompany(ctx, shopCompanyID)
+				metrics.ObserveSync("shopify", err, time.Since(start))
+				if err != nil {
+					log.Printf("shopify sync %s failed: %v", shopCompanyID, err)
+					return
+				}
+				log.Printf("shopify sync %s done total=%d created=%d updated=%d failed=%d dry=%v",
+					shopCompanyID, summary.Total, summary.Created, summary.Updated, summary.Failed, summary.DryRun)
+			}
+		}); err != nil && !errors.Is(err, pgx.ErrNoRows) {
+			log.Printf("shopify claim error: %v", err)
+		}
+	}
+
+	for {
+		select {
+		case <-ctx.Done():
+			log.Println("worker shutting down")
+			jobSlots.Wait()
+			syncSlots.Wait()
+			return
+		case <-opsTicker.C:
+			if cfg.MaintenanceMode || cfg.ReadOnlyMode {
+				continue
+			}
+			if res, err := billingSvc.RunDueBillingCycles(ctx); err != nil {
+				log.Printf("billing cycles processed=%d failed=%d: %v", res.Processed, res.Failed, err)
+			} else if res.Processed > 0 {
+				log.Printf("billing cycles processed=%d", res.Processed)
+			}
+			if n, err := woo.EnqueueDueScheduled(ctx, 6*time.Hour); err != nil {
+				log.Printf("woo schedule enqueue: %v", err)
+			} else if n > 0 {
+				log.Printf("woo schedule enqueued=%d", n)
+			}
+			if n, err := shop.EnqueueDueScheduled(ctx, 6*time.Hour); err != nil {
+				log.Printf("shopify schedule enqueue: %v", err)
+			} else if n > 0 {
+				log.Printf("shopify schedule enqueued=%d", n)
+			}
+			if res, err := processing.CleanupStuck(ctx, pool); err != nil {
+				log.Printf("stuck job cleanup: %v", err)
+			} else if res.JobsMarkedFailed > 0 || res.ProductsReset > 0 || res.SyncJobsMarkedFailed > 0 {
+				log.Printf("stuck cleanup jobs_failed=%d products_reset=%d sync_jobs_failed=%d", res.JobsMarkedFailed, res.ProductsReset, res.SyncJobsMarkedFailed)
+			}
+			if res, err := processing.CleanupExpired(ctx, pool); err != nil {
+				log.Printf("expired job cleanup: %v", err)
+			} else if res.JobsDeleted > 0 {
+				log.Printf("retention cleanup jobs_deleted=%d", res.JobsDeleted)
+			}
+			if res, err := processing.CleanupExpiredSyncJobs(ctx, pool); err != nil {
+				log.Printf("expired sync cleanup: %v", err)
+			} else if res.SyncJobsDeleted > 0 {
+				log.Printf("retention cleanup sync_jobs_deleted=%d", res.SyncJobsDeleted)
+			}
+		case <-ticker.C:
+			runOnce()
+		case <-wake:
+			runOnce()
+		}
+	}
+}

apps/api/go.mod

@@ -0,0 +1,29 @@
+module github.com/descrybe/descrybe-v2/apps/api
+
+go 1.25.0
+
+require (
+	github.com/alexedwards/scs/pgxstore v0.0.0-20251002162104-209de6e426de
+	github.com/alexedwards/scs/v2 v2.9.0
+	github.com/go-chi/chi/v5 v5.3.1
+	github.com/go-chi/cors v1.2.2
+	github.com/go-sql-driver/mysql v1.10.0
+	github.com/google/uuid v1.6.0
+	github.com/jackc/pgx/v5 v5.10.0
+	github.com/microcosm-cc/bluemonday v1.0.27
+	golang.org/x/crypto v0.54.0
+	gopkg.in/yaml.v3 v3.0.1
+)
+
+require (
+	filippo.io/edwards25519 v1.2.0 // indirect
+	github.com/aymerick/douceur v0.2.0 // indirect
+	github.com/gorilla/css v1.0.1 // indirect
+	github.com/jackc/pgpassfile v1.0.0 // indirect
+	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
+	github.com/jackc/puddle/v2 v2.2.2 // indirect
+	golang.org/x/net v0.57.0 // indirect
+	golang.org/x/sync v0.22.0 // indirect
+	golang.org/x/sys v0.47.0 // indirect
+	golang.org/x/text v0.40.0 // indirect
+)

apps/api/go.sum

@@ -0,0 +1,113 @@
+filippo.io/edwards25519 v1.2.0 h1:crnVqOiS4jqYleHd9vaKZ+HKtHfllngJIiOpNpoJsjo=
+filippo.io/edwards25519 v1.2.0/go.mod h1:xzAOLCNug/yB62zG1bQ8uziwrIqIuxhctzJT18Q77mc=
+github.com/alexedwards/scs/pgxstore v0.0.0-20251002162104-209de6e426de h1:wNJVpr0ag/BL2nRGBIESdLe1qoljXIolF/qPi1gleRA=
+github.com/alexedwards/scs/pgxstore v0.0.0-20251002162104-209de6e426de/go.mod h1:hwveArYcjyOK66EViVgVU5Iqj7zyEsWjKXMQhDJrTLI=
+github.com/alexedwards/scs/v2 v2.9.0 h1:xa05mVpwTBm1iLeTMNFfAWpKUm4fXAW7CeAViqBVS90=
+github.com/alexedwards/scs/v2 v2.9.0/go.mod h1:ToaROZxyKukJKT/xLcVQAChi5k6+Pn1Gvmdl7h3RRj8=
+github.com/aymerick/douceur v0.2.0 h1:Mv+mAeH1Q+n9Fr+oyamOlAkUNPWPlA8PPGR0QAaYuPk=
+github.com/aymerick/douceur v0.2.0/go.mod h1:wlT5vV2O3h55X9m7iVYN0TBM0NH/MmbLnd30/FjWUq4=
+github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/go-chi/chi/v5 v5.3.1 h1:3j4HZLGZQ3JpMCrPJF/Jl3mYJfWLKBfNJ6quurUGCf8=
+github.com/go-chi/chi/v5 v5.3.1/go.mod h1:R+tYY2hNuVUUjxoPtqUdgBqevM9s9njzkTLutVsOCto=
+github.com/go-chi/cors v1.2.2 h1:Jmey33TE+b+rB7fT8MUy1u0I4L+NARQlK6LhzKPSyQE=
+github.com/go-chi/cors v1.2.2/go.mod h1:sSbTewc+6wYHBBCW7ytsFSn836hqM7JxpglAy2Vzc58=
+github.com/go-sql-driver/mysql v1.10.0 h1:Q+1LV8DkHJvSYAdR83XzuhDaTykuDx0l6fkXxoWCWfw=
+github.com/go-sql-driver/mysql v1.10.0/go.mod h1:M+cqaI7+xxXGG9swrdeUIoPG3Y3KCkF0pZej+SK+nWk=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/gorilla/css v1.0.1 h1:ntNaBIghp6JmvWnxbZKANoLyuXTPZ4cAMlo6RyhlbO8=
+github.com/gorilla/css v1.0.1/go.mod h1:BvnYkspnSzMmwRK+b8/xgNPLiIuNZr6vbZBTPQ2A3b0=
+github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
+github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
+github.com/jackc/pgservicefile v0.0.0-20221227161230-091c0ba34f0a/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
+github.com/jackc/pgx/v5 v5.5.4/go.mod h1:ez9gk+OAat140fv9ErkZDYFWmXLfV+++K0uAOiwgm1A=
+github.com/jackc/pgx/v5 v5.10.0 h1:VhSvgU2jSli8o3AqIEOTJr7rZwAEUVo4E4XhR94Zfr0=
+github.com/jackc/pgx/v5 v5.10.0/go.mod h1:mal1tBGAFfLHvZzaYh77YS/eC6IX9OWbRV1QIIM0Jn4=
+github.com/jackc/puddle/v2 v2.2.1/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
+github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
+github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
+github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
+github.com/kr/pretty v0.2.1/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI=
+github.com/kr/pretty v0.3.0 h1:WgNl7dwNpEZ6jJ9k1snq4pZsg7DOEN8hP9Xw0Tsjwk0=
+github.com/kr/pretty v0.3.0/go.mod h1:640gp4NfQd8pI5XOwp5fnNeVWj67G7CFk/SaSQn7NBk=
+github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
+github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/microcosm-cc/bluemonday v1.0.27 h1:MpEUotklkwCSLeH+Qdx1VJgNqLlpY2KXwXFM08ygZfk=
+github.com/microcosm-cc/bluemonday v1.0.27/go.mod h1:jFi9vgW+H7c3V0lb6nR74Ib/DIB5OBs92Dimizgw2cA=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/rogpeppe/go-internal v1.6.1 h1:/FiVV8dS/e+YqF2JvO3yXRFbBLTIuSDkuC7aBOAvL+k=
+github.com/rogpeppe/go-internal v1.6.1/go.mod h1:xXDCJY+GAPziupqXw64V24skbSoqbTEfhy4qGm1nDQc=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
+github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
+github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
+github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
+golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
+golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
+golang.org/x/crypto v0.17.0/go.mod h1:gCAAfMLgwOJRpTjQ2zCCt2OcSfYMTeZVSRtQlPC7Nq4=
+golang.org/x/crypto v0.54.0 h1:YLIA59K4fiNzHzjnZt2tUJQjQtUWfWbeHBqKtk3eScw=
+golang.org/x/crypto v0.54.0/go.mod h1:KWL8ny2AZdGR2cWmzeHrp2azQPGogOv+HeQaVEXC2dk=
+golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
+golang.org/x/mod v0.8.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
+golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
+golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
+golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug+ECip1KBveYUHfp+8e9klMJ9c=
+golang.org/x/net v0.6.0/go.mod h1:2Tu9+aMcznHK/AK1HMvgo6xiTLG5rD5rZLDS+rp2Bjs=
+golang.org/x/net v0.10.0/go.mod h1:0qNGK6F8kojg2nk9dLZ2mShWaEBan6FAoqfSigmmuDg=
+golang.org/x/net v0.57.0 h1:K5+3DljvIuDG9/Jv9rvyMywYNFCQ9RSUY6OOTTkT+tE=
+golang.org/x/net v0.57.0/go.mod h1:KpXc8iv+r3XplLAG/f7Jsf9RPszJzdR0f58q9vGOuEU=
+golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.1.0/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
+golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.8.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.15.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
+golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
+golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
+golang.org/x/term v0.5.0/go.mod h1:jMB1sMXY+tzblOD4FWmEbocvup2/aLOaQEp7JmGp78k=
+golang.org/x/term v0.8.0/go.mod h1:xPskH00ivmX89bAKVGSKKtLOWNx2+17Eiy94tnKShWo=
+golang.org/x/term v0.15.0/go.mod h1:BDl952bC7+uMoWR75FIrCDx79TPU9oHkTZ9yRbYOrX0=
+golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
+golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
+golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
+golang.org/x/text v0.7.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8=
+golang.org/x/text v0.9.0/go.mod h1:e1OnstbJyHTd6l/uOt8jFFHp6TRDWZR/bV3emEE/zU8=
+golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
+golang.org/x/text v0.40.0 h1:Ub2Z6/xjgF1WrYQz2nuITOEegKFtiIy+rieRJ5lHZKs=
+golang.org/x/text v0.40.0/go.mod h1:hpnzDAfGV753zIKo+wk3u1bVKCGPbrnF7+7LBF/UHVY=
+golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
+golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
+golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc=
+golang.org/x/tools v0.6.0/go.mod h1:Xwgl3UAJ/d3gWutnCtw505GrjyAbvKui8lOU390QaIU=
+golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
+gopkg.in/errgo.v2 v2.1.0/go.mod h1:hNsd1EY+bozCKY1Ytp96fpM3vjJbqLJn88ws8XvfDNI=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

apps/api/internal/aiprompts/errors.go

@@ -0,0 +1,27 @@
+package aiprompts
+
+import "errors"
+
+var (
+	ErrInvalidKey   = errors.New("invalid prompt key")
+	ErrInvalidInput = errors.New("invalid prompt input")
+)
+
+// ClientError maps known client errors to safe API messages.
+func ClientError(err error) (msg string, ok bool) {
+	switch {
+	case errors.Is(err, ErrInvalidKey):
+		return "invalid prompt key", true
+	case errors.Is(err, ErrInvalidInput):
+		return "invalid prompt templates", true
+	default:
+		// Wrapped ErrInvalidKey / ErrInvalidInput from fmt.Errorf("%w: …")
+		if errors.Is(err, ErrInvalidKey) {
+			return err.Error(), true
+		}
+		if errors.Is(err, ErrInvalidInput) {
+			return err.Error(), true
+		}
+		return "", false
+	}
+}

apps/api/internal/aiprompts/kinds.go

@@ -0,0 +1,129 @@
+package aiprompts
+
+// Prompt keys stored in ai_prompt_templates.prompt_key.
+const (
+	KeyProductEnhance = "product_enhance"
+	KeySEOMeta        = "seo_meta"
+	KeyCampaignEmail  = "campaign_email"
+)
+
+// MaxSystemRunes / MaxUserRunes bound stored templates (prompt-injection surface).
+const (
+	MaxSystemRunes = 6000
+	MaxUserRunes   = 4000
+)
+
+// Variable describes a placeholder tenants can insert into templates.
+type Variable struct {
+	Name        string `json:"name"`
+	Label       string `json:"label"`
+	Description string `json:"description"`
+	Keys        []string `json:"keys"` // prompt_key values that support this variable
+}
+
+// Catalog of supported {{variables}} (only these are substituted; unknown tokens stay literal).
+var VariableCatalog = []Variable{
+	{Name: "name", Label: "Product name", Description: "Current product title", Keys: []string{KeyProductEnhance, KeySEOMeta}},
+	{Name: "description", Label: "Description", Description: "Current product description", Keys: []string{KeyProductEnhance, KeySEOMeta}},
+	{Name: "category", Label: "Category", Description: "Resolved category name", Keys: []string{KeyProductEnhance, KeySEOMeta}},
+	{Name: "attrs", Label: "Attributes", Description: "Compact JSON of product attributes", Keys: []string{KeyProductEnhance}},
+	{Name: "gtin", Label: "GTIN", Description: "Product GTIN / barcode when present", Keys: []string{KeyProductEnhance}},
+	{Name: "brand", Label: "Brand name", Description: "Company or product brand label", Keys: []string{KeySEOMeta, KeyCampaignEmail}},
+	{Name: "brand_voice", Label: "Brand voice", Description: "Brand kit tone / dos / don'ts block", Keys: []string{KeyProductEnhance, KeySEOMeta, KeyCampaignEmail}},
+	{Name: "language", Label: "Content language", Description: "Company content language (English display name)", Keys: []string{KeyProductEnhance, KeySEOMeta, KeyCampaignEmail}},
+	{Name: "campaign_prompt", Label: "Campaign brief", Description: "Per-campaign user brief or template default", Keys: []string{KeyCampaignEmail}},
+	{Name: "products", Label: "Product list", Description: "Plain-text product snippets for the campaign", Keys: []string{KeyCampaignEmail}},
+	{Name: "template_key", Label: "Template key", Description: "Campaign template id (christmas, custom, …)", Keys: []string{KeyCampaignEmail}},
+}
+
+// DefaultTemplate is the built-in prompt when the company has no custom row or disabled it.
+type DefaultTemplate struct {
+	Key            string `json:"key"`
+	Label          string `json:"label"`
+	Description    string `json:"description"`
+	SystemTemplate string `json:"system_template"`
+	UserTemplate   string `json:"user_template"`
+}
+
+// BuiltInDefaults match the previous hardcoded system prompts, with structured user templates.
+var BuiltInDefaults = []DefaultTemplate{
+	{
+		Key:         KeyProductEnhance,
+		Label:       "Product title & description",
+		Description: "Used when processing products (AI enhance step).",
+		SystemTemplate: `Retail product copywriter.
+Rules:
+- Reply with ONLY JSON (no markdown)
+- Schema: {"name":"string","description":"string"}
+- name: short retail title
+- description: 1-2 factual sentences
+- Write name and description in {{language}}
+Example:
+{"name":"Acme Widget Pro","description":"Durable widget for everyday use. Clear specs, ready to ship."}
+{{brand_voice}}`,
+		UserTemplate: `Category: {{category}}
+Name: {{name}}
+Desc: {{description}}
+Attrs: {{attrs}}`,
+	},
+	{
+		Key:         KeySEOMeta,
+		Label:       "SEO meta title & description",
+		Description: "Used when applying AI SEO meta to a product.",
+		SystemTemplate: `SEO meta writer for ecommerce.
+Rules:
+- Reply with ONLY JSON (no markdown)
+- Schema: {"meta_title":"string","meta_description":"string"}
+- meta_title: 50-60 chars, product + benefit
+- meta_description: 120-155 chars, factual
+- Write meta_title and meta_description in {{language}}
+Example:
+{"meta_title":"Acme Widget Pro | Durable Daily Use","meta_description":"Shop Acme Widget Pro for reliable everyday performance. Clear specs and fast delivery."}
+{{brand_voice}}`,
+		UserTemplate: `Name: {{name}}
+Category: {{category}}
+Desc: {{description}}`,
+	},
+	{
+		Key:         KeyCampaignEmail,
+		Label:       "Campaign email",
+		Description: "Used when generating marketing emails with AI.",
+		SystemTemplate: `Marketing email writer.
+Rules:
+- Reply with ONLY JSON (no markdown)
+- Schema: {"subject":"string","html_body":"string","plain_body":"string"}
+- subject: short
+- html_body: simple HTML (<p>, <ul>, <a> only)
+- plain_body: plain text mirror
+- Write subject, html_body, and plain_body in {{language}}
+Example:
+{"subject":"Holiday picks from Acme","html_body":"<p>Season's greetings.</p><ul><li>Widget Pro</li></ul><p><a href=\"#\">Shop now</a></p>","plain_body":"Season's greetings.\n- Widget Pro\nShop now"}
+{{brand_voice}}`,
+		UserTemplate: `{{campaign_prompt}}
+
+Products:
+{{products}}
+Brand: {{brand}}
+Template: {{template_key}}`,
+	},
+}
+
+// ValidPromptKey reports whether key is a known prompt_key.
+func ValidPromptKey(key string) bool {
+	switch key {
+	case KeyProductEnhance, KeySEOMeta, KeyCampaignEmail:
+		return true
+	default:
+		return false
+	}
+}
+
+// DefaultFor returns the built-in default for key, or empty if unknown.
+func DefaultFor(key string) (DefaultTemplate, bool) {
+	for _, d := range BuiltInDefaults {
+		if d.Key == key {
+			return d, true
+		}
+	}
+	return DefaultTemplate{}, false
+}

apps/api/internal/aiprompts/render.go

@@ -0,0 +1,61 @@
+package aiprompts
+
+import (
+	"regexp"
+	"strings"
+
+	"github.com/descrybe/descrybe-v2/apps/api/internal/security"
+)
+
+// varToken matches {{name}} with optional whitespace. Only [a-z0-9_]+ names.
+var varToken = regexp.MustCompile(`\{\{\s*([a-z][a-z0-9_]*)\s*\}\}`)
+
+// Vars is the substitution map for Render (keys without braces).
+type Vars map[string]string
+
+// Render replaces {{var}} tokens. Unknown variables become empty string (safe, deterministic).
+// Templates are sanitized before render; values should already be sanitized by callers.
+func Render(template string, vars Vars) string {
+	template = strings.TrimSpace(template)
+	if template == "" {
+		return ""
+	}
+	return varToken.ReplaceAllStringFunc(template, func(match string) string {
+		sub := varToken.FindStringSubmatch(match)
+		if len(sub) < 2 {
+			return ""
+		}
+		name := sub[1]
+		if vars == nil {
+			return ""
+		}
+		return vars[name]
+	})
+}
+
+// SanitizeTemplate cleans and bounds a stored prompt template.
+func SanitizeTemplate(s string, maxRunes int) string {
+	return security.SanitizePrompt(s, maxRunes)
+}
+
+// ExtractVariables returns unique variable names found in template (sorted order of first appearance).
+func ExtractVariables(template string) []string {
+	matches := varToken.FindAllStringSubmatch(template, -1)
+	if len(matches) == 0 {
+		return nil
+	}
+	seen := map[string]struct{}{}
+	out := make([]string, 0, len(matches))
+	for _, m := range matches {
+		if len(m) < 2 {
+			continue
+		}
+		name := m[1]
+		if _, ok := seen[name]; ok {
+			continue
+		}
+		seen[name] = struct{}{}
+		out = append(out, name)
+	}
+	return out
+}

apps/api/internal/aiprompts/render_test.go

@@ -0,0 +1,49 @@
+package aiprompts
+
+import "testing"
+
+func TestRender_replacesKnownVars(t *testing.T) {
+	t.Parallel()
+	got := Render("Hello {{name}} in {{category}}", Vars{
+		"name":     "Widget",
+		"category": "Tools",
+	})
+	want := "Hello Widget in Tools"
+	if got != want {
+		t.Fatalf("got %q want %q", got, want)
+	}
+}
+
+func TestRender_unknownVarEmpty(t *testing.T) {
+	t.Parallel()
+	got := Render("X={{missing}}Y", Vars{"name": "a"})
+	if got != "X=Y" {
+		t.Fatalf("got %q", got)
+	}
+}
+
+func TestRender_whitespaceInBraces(t *testing.T) {
+	t.Parallel()
+	got := Render("{{ name }}", Vars{"name": "ok"})
+	if got != "ok" {
+		t.Fatalf("got %q", got)
+	}
+}
+
+func TestExtractVariables(t *testing.T) {
+	t.Parallel()
+	got := ExtractVariables("{{name}} and {{name}} then {{brand_voice}}")
+	if len(got) != 2 || got[0] != "name" || got[1] != "brand_voice" {
+		t.Fatalf("got %#v", got)
+	}
+}
+
+func TestValidPromptKey(t *testing.T) {
+	t.Parallel()
+	if !ValidPromptKey(KeyProductEnhance) {
+		t.Fatal("expected product_enhance valid")
+	}
+	if ValidPromptKey("nope") {
+		t.Fatal("expected nope invalid")
+	}
+}

apps/api/internal/aiprompts/service.go

@@ -0,0 +1,238 @@
+package aiprompts
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/descrybe/descrybe-v2/apps/api/internal/company"
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// Service loads and stores per-company AI prompt templates.
+type Service struct {
+	Pool *pgxpool.Pool
+}
+
+func NewService(pool *pgxpool.Pool) *Service {
+	return &Service{Pool: pool}
+}
+
+type stored struct {
+	key            string
+	language       string
+	systemTemplate string
+	userTemplate   string
+	isEnabled      bool
+	updatedAt      time.Time
+}
+
+// GetBundle returns all prompt keys with effective templates for language + variable catalog.
+func (s *Service) GetBundle(ctx context.Context, companyID uuid.UUID, language string) (Bundle, error) {
+	lang, err := company.ParseLanguage(language, true)
+	if err != nil {
+		lang = company.LoadLanguage(ctx, s.Pool, companyID)
+	}
+	contentLangs := company.LoadContentLanguages(ctx, s.Pool, companyID)
+	storedRows, err := s.loadAll(ctx, companyID)
+	if err != nil {
+		return Bundle{}, err
+	}
+	byKeyLang := map[string]stored{}
+	customLangs := map[string][]string{}
+	for _, st := range storedRows {
+		byKeyLang[st.key+"\x00"+st.language] = st
+		customLangs[st.key] = appendUnique(customLangs[st.key], st.language)
+	}
+	out := make([]Template, 0, len(BuiltInDefaults))
+	for _, def := range BuiltInDefaults {
+		t := Template{
+			Key:         def.Key,
+			Language:    lang,
+			Label:       def.Label,
+			Description: def.Description,
+			IsDefault:   true,
+			IsCustom:    false,
+			IsEnabled:   true,
+		}
+		if st, ok := byKeyLang[def.Key+"\x00"+lang]; ok {
+			t.IsCustom = true
+			t.IsDefault = false
+			t.IsEnabled = st.isEnabled
+			t.UpdatedAt = st.updatedAt
+			if st.isEnabled {
+				t.SystemTemplate = st.systemTemplate
+				t.UserTemplate = st.userTemplate
+			} else {
+				t.SystemTemplate = def.SystemTemplate
+				t.UserTemplate = def.UserTemplate
+				t.IsDefault = true
+			}
+		} else {
+			t.SystemTemplate = def.SystemTemplate
+			t.UserTemplate = def.UserTemplate
+		}
+		out = append(out, t)
+	}
+	return Bundle{
+		Language:         lang,
+		Prompts:          out,
+		Variables:        VariableCatalog,
+		CustomLanguages:  customLangs,
+		ContentLanguages: contentLangs,
+	}, nil
+}
+
+// Resolve returns the effective templates for one key + language
+// (custom if enabled for lang, else built-in). No cross-language company fallback.
+func (s *Service) Resolve(ctx context.Context, companyID uuid.UUID, key, language string) (Resolved, error) {
+	if !ValidPromptKey(key) {
+		return Resolved{}, ErrInvalidKey
+	}
+	def, ok := DefaultFor(key)
+	if !ok {
+		return Resolved{}, ErrInvalidKey
+	}
+	lang, err := company.ParseLanguage(language, true)
+	if err != nil {
+		lang = company.DefaultLanguage
+	}
+	st, err := s.loadOne(ctx, companyID, key, lang)
+	if err != nil && !errors.Is(err, pgx.ErrNoRows) {
+		return Resolved{}, err
+	}
+	if err == nil && st.isEnabled {
+		sys := strings.TrimSpace(st.systemTemplate)
+		user := strings.TrimSpace(st.userTemplate)
+		if sys == "" {
+			sys = def.SystemTemplate
+		}
+		if user == "" {
+			user = def.UserTemplate
+		}
+		return Resolved{
+			Key:            key,
+			Language:       lang,
+			SystemTemplate: sys,
+			UserTemplate:   user,
+			IsCustom:       true,
+		}, nil
+	}
+	return Resolved{
+		Key:            key,
+		Language:       lang,
+		SystemTemplate: def.SystemTemplate,
+		UserTemplate:   def.UserTemplate,
+		IsCustom:       false,
+	}, nil
+}
+
+// Update applies prompt updates (upsert or reset). Empty prompts list is a no-op.
+func (s *Service) Update(ctx context.Context, companyID uuid.UUID, in UpdateInput) (Bundle, error) {
+	defaultLang := strings.TrimSpace(in.Language)
+	if defaultLang == "" {
+		defaultLang = company.LoadLanguage(ctx, s.Pool, companyID)
+	}
+	if len(in.Prompts) == 0 {
+		return s.GetBundle(ctx, companyID, defaultLang)
+	}
+	tx, err := s.Pool.Begin(ctx)
+	if err != nil {
+		return Bundle{}, err
+	}
+	defer tx.Rollback(ctx)
+	lastLang := defaultLang
+	for _, item := range in.Prompts {
+		key := strings.TrimSpace(strings.ToLower(item.Key))
+		if !ValidPromptKey(key) {
+			return Bundle{}, fmt.Errorf("%w: %s", ErrInvalidKey, item.Key)
+		}
+		langRaw := strings.TrimSpace(item.Language)
+		if langRaw == "" {
+			langRaw = defaultLang
+		}
+		lang, err := company.ParseLanguage(langRaw, false)
+		if err != nil {
+			return Bundle{}, fmt.Errorf("%w: language %q", ErrInvalidInput, langRaw)
+		}
+		lastLang = lang
+		if item.Reset {
+			_, err := tx.Exec(ctx, `
+				DELETE FROM ai_prompt_templates
+				WHERE company_id = $1 AND prompt_key = $2 AND language = $3`,
+				companyID, key, lang)
+			if err != nil {
+				return Bundle{}, err
+			}
+			continue
+		}
+		sys := SanitizeTemplate(item.SystemTemplate, MaxSystemRunes)
+		user := SanitizeTemplate(item.UserTemplate, MaxUserRunes)
+		if sys == "" && user == "" {
+			return Bundle{}, fmt.Errorf("%w: empty templates for %s", ErrInvalidInput, key)
+		}
+		enabled := true
+		if item.IsEnabled != nil {
+			enabled = *item.IsEnabled
+		}
+		_, err = tx.Exec(ctx, `
+			INSERT INTO ai_prompt_templates (
+				company_id, prompt_key, language, system_template, user_template, is_enabled, updated_at
+			) VALUES ($1,$2,$3,$4,$5,$6, now())
+			ON CONFLICT (company_id, prompt_key, language) DO UPDATE SET
+				system_template = EXCLUDED.system_template,
+				user_template = EXCLUDED.user_template,
+				is_enabled = EXCLUDED.is_enabled,
+				updated_at = now()`,
+			companyID, key, lang, sys, user, enabled)
+		if err != nil {
+			return Bundle{}, err
+		}
+	}
+	if err := tx.Commit(ctx); err != nil {
+		return Bundle{}, err
+	}
+	return s.GetBundle(ctx, companyID, lastLang)
+}
+
+func (s *Service) loadAll(ctx context.Context, companyID uuid.UUID) ([]stored, error) {
+	rows, err := s.Pool.Query(ctx, `
+		SELECT prompt_key, language, system_template, user_template, is_enabled, updated_at
+		FROM ai_prompt_templates WHERE company_id = $1`, companyID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []stored
+	for rows.Next() {
+		var st stored
+		if err := rows.Scan(&st.key, &st.language, &st.systemTemplate, &st.userTemplate, &st.isEnabled, &st.updatedAt); err != nil {
+			return nil, err
+		}
+		out = append(out, st)
+	}
+	return out, rows.Err()
+}
+
+func (s *Service) loadOne(ctx context.Context, companyID uuid.UUID, key, language string) (stored, error) {
+	var st stored
+	err := s.Pool.QueryRow(ctx, `
+		SELECT prompt_key, language, system_template, user_template, is_enabled, updated_at
+		FROM ai_prompt_templates
+		WHERE company_id = $1 AND prompt_key = $2 AND language = $3`,
+		companyID, key, language).Scan(&st.key, &st.language, &st.systemTemplate, &st.userTemplate, &st.isEnabled, &st.updatedAt)
+	return st, err
+}
+
+func appendUnique(list []string, v string) []string {
+	for _, x := range list {
+		if x == v {
+			return list
+		}
+	}
+	return append(list, v)
+}

apps/api/internal/aiprompts/types.go

@@ -0,0 +1,51 @@
+package aiprompts
+
+import "time"
+
+// Template is one company's prompt for a feature key (+ language) (API / storage shape).
+type Template struct {
+	Key            string    `json:"key"`
+	Language       string    `json:"language,omitempty"`
+	Label          string    `json:"label,omitempty"`
+	Description    string    `json:"description,omitempty"`
+	SystemTemplate string    `json:"system_template"`
+	UserTemplate   string    `json:"user_template"`
+	IsEnabled      bool      `json:"is_enabled"`
+	IsCustom       bool      `json:"is_custom"`
+	IsDefault      bool      `json:"is_default"`
+	UpdatedAt      time.Time `json:"updated_at,omitempty"`
+}
+
+// UpdateItem is one prompt in a PUT body.
+type UpdateItem struct {
+	Key            string `json:"key"`
+	Language       string `json:"language,omitempty"`
+	SystemTemplate string `json:"system_template"`
+	UserTemplate   string `json:"user_template"`
+	IsEnabled      *bool  `json:"is_enabled,omitempty"`
+	Reset          bool   `json:"reset,omitempty"` // delete custom row → fall back to built-in
+}
+
+// UpdateInput is the PUT /integrations/ai/prompts body.
+type UpdateInput struct {
+	Language string       `json:"language,omitempty"` // default language for items missing Language
+	Prompts  []UpdateItem `json:"prompts"`
+}
+
+// Resolved is the effective system+user templates after defaults / custom merge.
+type Resolved struct {
+	Key            string
+	Language       string
+	SystemTemplate string
+	UserTemplate   string
+	IsCustom       bool
+}
+
+// Bundle is the GET response for the prompts UI.
+type Bundle struct {
+	Language         string              `json:"language"`
+	Prompts          []Template          `json:"prompts"`
+	Variables        []Variable          `json:"variables"`
+	CustomLanguages  map[string][]string `json:"custom_languages"` // key → langs with overrides
+	ContentLanguages []string            `json:"content_languages,omitempty"`
+}

apps/api/internal/aiprovider/catalog.go

@@ -0,0 +1,148 @@
+package aiprovider
+
+import "strings"
+
+// Mode values stored on ai_providers.mode (UI / API).
+const (
+	ModeInternal = "internal"
+	ModePopular  = "popular"
+	ModeCustom   = "custom"
+)
+
+// ModeInternalLabel is the analytics / job recording value when using platform OpenAI (admin settings or env fallback).
+const ModeInternalLabel = "internal"
+
+// ModeCustomLabel is the analytics value for custom OpenAI-compatible endpoints.
+const ModeCustomLabel = "custom"
+
+// PopularProvider is a curated OpenAI-compatible catalog entry.
+type PopularProvider struct {
+	Name         string   `json:"name"`
+	Label        string   `json:"label"`
+	BaseURL      string   `json:"base_url"`
+	DefaultModel string   `json:"default_model"`
+	Models       []string `json:"models"`
+}
+
+// PopularCatalog lists OpenAI-compatible providers tenants can pick by API key only.
+var PopularCatalog = []PopularProvider{
+	{
+		Name:         "openai",
+		Label:        "OpenAI",
+		BaseURL:      "https://api.openai.com/v1",
+		DefaultModel: "gpt-4o-mini",
+		Models:       []string{"gpt-4o-mini", "gpt-4o", "gpt-4.1-mini", "gpt-4.1"},
+	},
+	{
+		Name:         "google",
+		Label:        "Google (Gemini OpenAI compat)",
+		BaseURL:      "https://generativelanguage.googleapis.com/v1beta/openai",
+		DefaultModel: "gemini-2.0-flash",
+		Models:       []string{"gemini-2.0-flash", "gemini-2.5-flash", "gemini-2.0-flash-lite"},
+	},
+	{
+		Name:         "groq",
+		Label:        "Groq",
+		BaseURL:      "https://api.groq.com/openai/v1",
+		DefaultModel: "llama-3.3-70b-versatile",
+		Models:       []string{"llama-3.3-70b-versatile", "llama-3.1-8b-instant", "mixtral-8x7b-32768"},
+	},
+	{
+		Name:         "mistral",
+		Label:        "Mistral",
+		BaseURL:      "https://api.mistral.ai/v1",
+		DefaultModel: "mistral-small-latest",
+		Models:       []string{"mistral-small-latest", "mistral-medium-latest", "mistral-large-latest"},
+	},
+	{
+		Name:         "deepseek",
+		Label:        "DeepSeek",
+		BaseURL:      "https://api.deepseek.com/v1",
+		DefaultModel: "deepseek-chat",
+		Models:       []string{"deepseek-chat", "deepseek-reasoner"},
+	},
+	{
+		Name:         "openrouter",
+		Label:        "OpenRouter",
+		BaseURL:      "https://openrouter.ai/api/v1",
+		DefaultModel: "openai/gpt-4o-mini",
+		Models:       []string{"openai/gpt-4o-mini", "anthropic/claude-sonnet-4", "google/gemini-2.0-flash-001"},
+	},
+}
+
+func FindPopular(name string) (PopularProvider, bool) {
+	name = strings.ToLower(strings.TrimSpace(name))
+	for _, p := range PopularCatalog {
+		if p.Name == name {
+			return p, true
+		}
+	}
+	return PopularProvider{}, false
+}
+
+// AnalyticsMode returns the recorded provider mode for jobs/products.
+// Contract for analytics: "internal" | "popular:<name>" | "custom"
+func AnalyticsMode(mode, popularName string) string {
+	switch strings.ToLower(strings.TrimSpace(mode)) {
+	case ModePopular:
+		name := strings.ToLower(strings.TrimSpace(popularName))
+		if name == "" {
+			name = "unknown"
+		}
+		return "popular:" + name
+	case ModeCustom:
+		return ModeCustomLabel
+	default:
+		return ModeInternalLabel
+	}
+}
+
+// AnalyticsClass maps a stored ai_provider_mode value to a rollup class.
+// Returns: internal | popular | custom | unknown
+func AnalyticsClass(modeLabel string) string {
+	m := strings.ToLower(strings.TrimSpace(modeLabel))
+	switch {
+	case m == "" || m == "unknown":
+		return "unknown"
+	case m == ModeInternalLabel || m == ModeInternal:
+		return ModeInternal
+	case m == ModeCustomLabel || m == ModeCustom:
+		return ModeCustom
+	case strings.HasPrefix(m, "popular:"):
+		return ModePopular
+	default:
+		return "unknown"
+	}
+}
+
+// NormalizeAnalyticsMode coerces free-form labels into the analytics contract.
+func NormalizeAnalyticsMode(modeLabel string) string {
+	m := strings.ToLower(strings.TrimSpace(modeLabel))
+	switch {
+	case m == "" || m == "unknown":
+		return "unknown"
+	case m == ModeInternalLabel || m == ModeInternal:
+		return ModeInternalLabel
+	case m == ModeCustomLabel || m == ModeCustom:
+		return ModeCustomLabel
+	case strings.HasPrefix(m, "popular:"):
+		name := strings.TrimSpace(strings.TrimPrefix(m, "popular:"))
+		if name == "" {
+			name = "unknown"
+		}
+		return "popular:" + name
+	default:
+		return "unknown"
+	}
+}
+
+func normalizeMode(mode string) string {
+	switch strings.ToLower(strings.TrimSpace(mode)) {
+	case ModePopular:
+		return ModePopular
+	case ModeCustom:
+		return ModeCustom
+	default:
+		return ModeInternal
+	}
+}

apps/api/internal/aiprovider/catalog_test.go

@@ -0,0 +1,34 @@
+package aiprovider
+
+import "testing"
+
+func TestAnalyticsClass(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		in, want string
+	}{
+		{"", "unknown"},
+		{"unknown", "unknown"},
+		{"internal", "internal"},
+		{"custom", "custom"},
+		{"popular:openai", "popular"},
+		{"popular:groq", "popular"},
+		{"POPULAR:openai", "popular"},
+		{"weird", "unknown"},
+	}
+	for _, c := range cases {
+		if got := AnalyticsClass(c.in); got != c.want {
+			t.Fatalf("AnalyticsClass(%q)=%q want %q", c.in, got, c.want)
+		}
+	}
+}
+
+func TestNormalizeAnalyticsMode(t *testing.T) {
+	t.Parallel()
+	if got := NormalizeAnalyticsMode("popular:"); got != "popular:unknown" {
+		t.Fatalf("got %q", got)
+	}
+	if got := NormalizeAnalyticsMode("CUSTOM"); got != "custom" {
+		t.Fatalf("got %q", got)
+	}
+}

apps/api/internal/aiprovider/crypto.go

@@ -0,0 +1,120 @@
+package aiprovider
+
+import (
+	"crypto/aes"
+	"crypto/cipher"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/hex"
+	"errors"
+	"io"
+	"strings"
+
+	"github.com/descrybe/descrybe-v2/apps/api/internal/config"
+)
+
+const encPrefix = "enc:v1:"
+
+// DeriveKey builds a 32-byte AES key. Prefer APP_ENCRYPTION_KEY /
+// CREDENTIALS_ENCRYPTION_KEY; falls back to DATABASE_URL material (local/dev).
+// In production, explicitKey is required; empty returns nil (fail closed).
+func DeriveKey(explicitKey, fallbackMaterial string) []byte {
+	explicitKey = strings.TrimSpace(explicitKey)
+	if explicitKey != "" {
+		if b, err := decodeKeyMaterial(explicitKey); err == nil {
+			return b
+		}
+		sum := sha256.Sum256([]byte(explicitKey))
+		return sum[:]
+	}
+	if config.IsProductionEnv() {
+		return nil
+	}
+	sum := sha256.Sum256([]byte("descrybe-ai-v1|" + fallbackMaterial))
+	return sum[:]
+}
+
+func decodeKeyMaterial(s string) ([]byte, error) {
+	if b, err := base64.StdEncoding.DecodeString(s); err == nil && len(b) == 32 {
+		return b, nil
+	}
+	if b, err := base64.RawStdEncoding.DecodeString(s); err == nil && len(b) == 32 {
+		return b, nil
+	}
+	if b, err := hex.DecodeString(s); err == nil && len(b) == 32 {
+		return b, nil
+	}
+	return nil, errors.New("invalid key material")
+}
+
+func EncryptSecret(key []byte, plaintext string) (string, error) {
+	if plaintext == "" {
+		return "", nil
+	}
+	if len(key) != 32 {
+		return "", errors.New("encryption key must be 32 bytes")
+	}
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return "", err
+	}
+	gcm, err := cipher.NewGCM(block)
+	if err != nil {
+		return "", err
+	}
+	nonce := make([]byte, gcm.NonceSize())
+	if _, err := io.ReadFull(rand.Reader, nonce); err != nil {
+		return "", err
+	}
+	sealed := gcm.Seal(nonce, nonce, []byte(plaintext), nil)
+	return encPrefix + base64.RawStdEncoding.EncodeToString(sealed), nil
+}
+
+func DecryptSecret(key []byte, stored string) (string, error) {
+	if stored == "" {
+		return "", nil
+	}
+	if !strings.HasPrefix(stored, encPrefix) {
+		if config.IsProductionEnv() {
+			return "", errors.New("plaintext secrets are not allowed when APP_ENV=production")
+		}
+		return stored, nil
+	}
+	if len(key) != 32 {
+		return "", errors.New("encryption key must be 32 bytes")
+	}
+	raw, err := base64.RawStdEncoding.DecodeString(strings.TrimPrefix(stored, encPrefix))
+	if err != nil {
+		return "", err
+	}
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return "", err
+	}
+	gcm, err := cipher.NewGCM(block)
+	if err != nil {
+		return "", err
+	}
+	if len(raw) < gcm.NonceSize() {
+		return "", errors.New("ciphertext too short")
+	}
+	nonce, ciphertext := raw[:gcm.NonceSize()], raw[gcm.NonceSize():]
+	plain, err := gcm.Open(nil, nonce, ciphertext, nil)
+	if err != nil {
+		return "", err
+	}
+	return string(plain), nil
+}
+
+func last4(secret string) string {
+	secret = strings.TrimSpace(secret)
+	if secret == "" {
+		return ""
+	}
+	runes := []rune(secret)
+	if len(runes) <= 4 {
+		return string(runes)
+	}
+	return string(runes[len(runes)-4:])
+}

apps/api/internal/aiprovider/errors.go

@@ -0,0 +1,45 @@
+package aiprovider
+
+import (
+	"errors"
+
+	"github.com/descrybe/descrybe-v2/apps/api/internal/security"
+)
+
+// clientError is a validation message safe to return to API clients.
+type clientError struct {
+	msg string
+}
+
+func (e *clientError) Error() string { return e.msg }
+
+// ClientMsg marks a message as safe to expose in HTTP 4xx responses.
+func ClientMsg(msg string) error {
+	return &clientError{msg: msg}
+}
+
+// ClientError reports whether err is a known client-facing AI provider error.
+func ClientError(err error) (msg string, ok bool) {
+	if err == nil {
+		return "", false
+	}
+	var ce *clientError
+	if errors.As(err, &ce) {
+		return ce.msg, true
+	}
+	switch {
+	case errors.Is(err, ErrNotConfigured),
+		errors.Is(err, ErrInvalidMode),
+		errors.Is(err, ErrInvalidPopular),
+		errors.Is(err, ErrMissingAPIKey),
+		errors.Is(err, ErrMissingModel),
+		errors.Is(err, ErrMissingURL):
+		return err.Error(), true
+	case errors.Is(err, security.ErrInvalidURL),
+		errors.Is(err, security.ErrBlockedURL),
+		errors.Is(err, security.ErrBlockedHost):
+		return "invalid base_url", true
+	default:
+		return "", false
+	}
+}

apps/api/internal/aiprovider/platform_role_test.go

@@ -0,0 +1,110 @@
+package aiprovider
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/descrybe/descrybe-v2/apps/api/internal/platformsettings"
+)
+
+func TestTestPlatformRole_unknown(t *testing.T) {
+	t.Parallel()
+	svc := NewService(nil, EnvConfig{})
+	res, err := svc.TestPlatformRole(context.Background(), "nope")
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	if res["status"] != "failed" {
+		t.Fatalf("status=%v", res["status"])
+	}
+}
+
+func TestTestPlatformRole_skippedWhenUnset(t *testing.T) {
+	t.Parallel()
+	svc := NewService(nil, EnvConfig{})
+	svc.Platform = platformsettings.NewService(nil, platformsettings.EnvConfig{})
+	res, err := svc.TestPlatformRole(context.Background(), RoleSupport)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res["status"] != "skipped" {
+		t.Fatalf("status=%v message=%v", res["status"], res["message"])
+	}
+}
+
+func TestTestPlatformRole_chatProbeOK(t *testing.T) {
+	t.Parallel()
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/chat/completions" {
+			http.NotFound(w, r)
+			return
+		}
+		auth := r.Header.Get("Authorization")
+		if !strings.HasPrefix(auth, "Bearer sk-test-") {
+			http.Error(w, "unauthorized", http.StatusUnauthorized)
+			return
+		}
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"choices": []map[string]any{
+				{"message": map[string]any{"content": "ok"}},
+			},
+			"usage": map[string]any{"total_tokens": 1},
+		})
+	}))
+	t.Cleanup(srv.Close)
+
+	plat := platformsettings.NewService(nil, platformsettings.EnvConfig{
+		OpenAIAPIKey:  "sk-test-platform",
+		OpenAIBaseURL: srv.URL + "/v1",
+		OpenAIModel:   "test-model",
+	})
+	svc := NewService(nil, EnvConfig{})
+	svc.Platform = plat
+
+	res, err := svc.TestPlatformRole(context.Background(), RoleProcessing)
+	if err != nil {
+		t.Fatalf("err=%v res=%v", err, res)
+	}
+	if res["status"] != "ok" {
+		t.Fatalf("status=%v message=%v", res["status"], res["message"])
+	}
+	if msg, _ := res["message"].(string); strings.Contains(strings.ToLower(msg), "sk-") {
+		t.Fatalf("message must not leak key fragments: %q", msg)
+	}
+}
+
+func TestTestPlatformRole_embedProbeOK(t *testing.T) {
+	t.Parallel()
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/embeddings" {
+			http.NotFound(w, r)
+			return
+		}
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"data": []map[string]any{
+				{"embedding": []float32{0.1, 0.2}, "index": 0},
+			},
+		})
+	}))
+	t.Cleanup(srv.Close)
+
+	plat := platformsettings.NewService(nil, platformsettings.EnvConfig{
+		OpenAIEmbeddingAPIKey:  "sk-test-embed",
+		OpenAIEmbeddingBaseURL: srv.URL + "/v1",
+		OpenAIEmbeddingModel:   "text-embedding-3-small",
+	})
+	svc := NewService(nil, EnvConfig{})
+	svc.Platform = plat
+
+	res, err := svc.TestPlatformRole(context.Background(), RoleVectorization)
+	if err != nil {
+		t.Fatalf("err=%v res=%v", err, res)
+	}
+	if res["status"] != "ok" {
+		t.Fatalf("status=%v message=%v", res["status"], res["message"])
+	}
+}

apps/api/internal/aiprovider/resolve_platform_test.go

@@ -0,0 +1,63 @@
+package aiprovider
+
+import (
+	"context"
+	"testing"
+
+	"github.com/descrybe/descrybe-v2/apps/api/internal/platformsettings"
+)
+
+func TestResolvePlatformOpenAI_envOnly(t *testing.T) {
+	svc := &Service{
+		Env: EnvConfig{
+			OpenAIAPIKey:  "sk-env-fallback",
+			OpenAIBaseURL: "https://api.openai.com/v1",
+			OpenAIModel:   "gpt-4o-mini",
+		},
+	}
+	oi, err := svc.resolvePlatformOpenAI(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if oi.APIKey != "sk-env-fallback" || oi.Source != platformsettings.SourceEnv {
+		t.Fatalf("got key=%q source=%q", oi.APIKey, oi.Source)
+	}
+	ok, err := svc.platformConfigured(context.Background())
+	if err != nil || !ok {
+		t.Fatalf("configured=%v err=%v", ok, err)
+	}
+}
+
+func TestResolvePlatformOpenAI_unset(t *testing.T) {
+	svc := &Service{Env: EnvConfig{}}
+	oi, err := svc.resolvePlatformOpenAI(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if oi.APIKey != "" || oi.Source != platformsettings.SourceNone {
+		t.Fatalf("got key=%q source=%q", oi.APIKey, oi.Source)
+	}
+	ok, err := svc.platformConfigured(context.Background())
+	if err != nil || ok {
+		t.Fatalf("configured=%v err=%v", ok, err)
+	}
+}
+
+func TestResolvePlatformOpenAI_viaPlatformService(t *testing.T) {
+	plat := platformsettings.NewService(nil, platformsettings.EnvConfig{
+		OpenAIAPIKey:  "sk-from-plat-env",
+		OpenAIBaseURL: "http://127.0.0.1:8767/v1",
+		OpenAIModel:   "local-model",
+	})
+	svc := &Service{Platform: plat, Env: EnvConfig{OpenAIAPIKey: "sk-should-not-win"}}
+	oi, err := svc.resolvePlatformOpenAI(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if oi.APIKey != "sk-from-plat-env" {
+		t.Fatalf("key=%q", oi.APIKey)
+	}
+	if oi.Source != platformsettings.SourceEnv {
+		t.Fatalf("source=%q", oi.Source)
+	}
+}

apps/api/internal/aiprovider/roles.go

@@ -0,0 +1,180 @@
+package aiprovider
+
+import (
+	"context"
+	"strings"
+
+	"github.com/descrybe/descrybe-v2/apps/api/internal/processing"
+	"github.com/google/uuid"
+)
+
+// Role identifiers — keep in sync with platformsettings.AIRole* / processing.AIRole*.
+//
+// RoleSupport is a FUTURE config slot (platformsettings.ai_roles["support"]).
+// Resolving a Completer when the slot is configured is allowed for future
+// draft-assist UIs, but support.TryAutoReplyLLM must remain the only gate for
+// ticket auto-replies — and that stub currently refuses. Guided /docs Ask is
+// rule-based and must never use RoleSupport or RoleDocsAPI.
+const (
+	RoleProcessing    = processing.AIRoleProcessing
+	RoleVectorization = processing.AIRoleVectorization
+	RoleDocsAPI       = processing.AIRoleDocsAPI
+	RoleSupport       = processing.AIRoleSupport
+)
+
+// RoleEndpoint is a resolved OpenAI-compatible chat endpoint for one role.
+// Secrets are plaintext only in-process — never log or return to clients.
+type RoleEndpoint struct {
+	APIKey    string
+	BaseURL   string
+	Model     string
+	UsingBYOK bool
+	ModeLabel string
+}
+
+// RoleEndpointSource looks up admin-configured role bindings (platform / company).
+// ok=false means the role is unset — callers must fall back.
+type RoleEndpointSource interface {
+	LookupRole(ctx context.Context, companyID uuid.UUID, role string) (ep RoleEndpoint, ok bool, err error)
+}
+
+// ResolveCompleterForRole prefers an injected RoleEndpointSource binding when set;
+// otherwise uses company BYOK then platformsettings.ResolveAIConfig for the role
+// (processing falls back to legacy openai JSON + OPENAI_* env when unset).
+func (s *Service) ResolveCompleterForRole(ctx context.Context, companyID uuid.UUID, role string) (processing.Completer, string, bool, error) {
+	role = strings.TrimSpace(role)
+	if role == "" {
+		role = RoleProcessing
+	}
+
+	if s != nil && s.Roles != nil {
+		ep, ok, err := s.Roles.LookupRole(ctx, companyID, role)
+		if err != nil {
+			return nil, ModeInternalLabel, false, err
+		}
+		if ok && strings.TrimSpace(ep.APIKey) != "" && strings.TrimSpace(ep.Model) != "" {
+			return s.completerFromEndpoint(ep)
+		}
+	}
+
+	switch role {
+	case RoleProcessing:
+		// Full Resolve needs Pool for company BYOK; without Pool use platform/env only.
+		if s != nil && s.Pool != nil {
+			return s.ResolveCompleter(ctx, companyID)
+		}
+		return s.resolvePlatformRoleCompleter(ctx, RoleProcessing)
+	case RoleDocsAPI, RoleSupport:
+		return s.resolvePlatformRoleCompleter(ctx, role)
+	default:
+		// Vectorization uses embeddings clients — not chat Completer.
+		return nil, ModeInternalLabel, false, nil
+	}
+}
+
+// ResolveEmbedderForRole returns an OpenAI-compatible Embedder for the
+// vectorization role (platformsettings.AIRoleVectorization) with env fallback.
+// Non-vectorization roles return (nil, nil). Unset config returns (nil, nil).
+func (s *Service) ResolveEmbedderForRole(ctx context.Context, companyID uuid.UUID, role string) (processing.Embedder, error) {
+	role = strings.TrimSpace(role)
+	if role == "" {
+		role = RoleVectorization
+	}
+	if role != RoleVectorization {
+		return nil, nil
+	}
+	if s != nil && s.Roles != nil {
+		ep, ok, err := s.Roles.LookupRole(ctx, companyID, role)
+		if err != nil {
+			return nil, err
+		}
+		if ok && strings.TrimSpace(ep.APIKey) != "" {
+			model := strings.TrimSpace(ep.Model)
+			if model == "" {
+				model = "text-embedding-3-small"
+			}
+			rpm, retries := 0, 3
+			if s != nil {
+				rpm = s.Env.ProcessingRPM
+				retries = s.Env.ProcessingMaxRetries
+			}
+			client := processing.NewOpenAIClient(ep.APIKey, ep.BaseURL, model, rpm, retries)
+			if s.HTTPClient != nil {
+				client.HTTPClient = s.HTTPClient
+			}
+			return client, nil
+		}
+	}
+	if s != nil && s.Platform != nil {
+		return s.Platform.ResolveEmbedder(ctx)
+	}
+	return nil, nil
+}
+
+func (s *Service) resolvePlatformRoleCompleter(ctx context.Context, role string) (processing.Completer, string, bool, error) {
+	if s == nil {
+		return nil, ModeInternalLabel, false, nil
+	}
+	if s.Platform != nil {
+		cfg, err := s.Platform.ResolveAIConfig(ctx, role)
+		if err != nil {
+			return nil, ModeInternalLabel, false, err
+		}
+		if strings.TrimSpace(cfg.APIKey) != "" {
+			if role != RoleProcessing && !cfg.Enabled {
+				return nil, ModeInternalLabel, false, nil
+			}
+			model := strings.TrimSpace(cfg.Model)
+			if model == "" && role == RoleProcessing {
+				model = strings.TrimSpace(s.Env.OpenAIModel)
+			}
+			if model != "" {
+				return s.completerFromEndpoint(RoleEndpoint{
+					APIKey:    cfg.APIKey,
+					BaseURL:   cfg.BaseURL,
+					Model:     model,
+					UsingBYOK: false,
+					ModeLabel: ModeInternalLabel,
+				})
+			}
+		}
+		return nil, ModeInternalLabel, false, nil
+	}
+	if role == RoleProcessing {
+		key := strings.TrimSpace(s.Env.OpenAIAPIKey)
+		model := strings.TrimSpace(s.Env.OpenAIModel)
+		if key != "" && model != "" {
+			return s.completerFromEndpoint(RoleEndpoint{
+				APIKey:    key,
+				BaseURL:   strings.TrimSpace(s.Env.OpenAIBaseURL),
+				Model:     model,
+				UsingBYOK: false,
+				ModeLabel: ModeInternalLabel,
+			})
+		}
+	}
+	return nil, ModeInternalLabel, false, nil
+}
+
+func (s *Service) completerFromEndpoint(ep RoleEndpoint) (processing.Completer, string, bool, error) {
+	rpm := 0
+	retries := 0
+	if s != nil {
+		rpm = s.Env.ProcessingRPM
+		retries = s.Env.ProcessingMaxRetries
+	}
+	client := processing.NewOpenAIClient(ep.APIKey, ep.BaseURL, ep.Model, rpm, retries)
+	label := strings.TrimSpace(ep.ModeLabel)
+	if label == "" {
+		if ep.UsingBYOK {
+			label = ModeCustom
+		} else {
+			label = ModeInternalLabel
+		}
+	}
+	client.ModeLabel = label
+	if s != nil && s.HTTPClient != nil {
+		client.HTTPClient = s.HTTPClient
+	}
+	return client, label, ep.UsingBYOK, nil
+}

apps/api/internal/aiprovider/roles_test.go

@@ -0,0 +1,149 @@
+package aiprovider
+
+import (
+	"context"
+	"testing"
+
+	"github.com/descrybe/descrybe-v2/apps/api/internal/platformsettings"
+	"github.com/descrybe/descrybe-v2/apps/api/internal/processing"
+	"github.com/google/uuid"
+)
+
+type stubRoleSource struct {
+	ep  RoleEndpoint
+	ok  bool
+	err error
+}
+
+func (s stubRoleSource) LookupRole(_ context.Context, _ uuid.UUID, _ string) (RoleEndpoint, bool, error) {
+	return s.ep, s.ok, s.err
+}
+
+func TestResolveCompleterForRole_unsetFallsBackToEnv(t *testing.T) {
+	svc := &Service{
+		Env: EnvConfig{
+			OpenAIAPIKey:  "sk-env-fallback",
+			OpenAIBaseURL: "https://api.openai.com/v1",
+			OpenAIModel:   "gpt-4o-mini",
+		},
+	}
+	c, label, byok, err := svc.ResolveCompleterForRole(context.Background(), uuid.Nil, RoleProcessing)
+	if err != nil {
+		t.Fatal(err)
+	}
+	oc, ok := c.(*processing.OpenAIClient)
+	if !ok || oc == nil || !oc.Enabled() {
+		t.Fatalf("expected enabled OpenAIClient, got %T", c)
+	}
+	if label != ModeInternalLabel {
+		t.Fatalf("label=%q", label)
+	}
+	if byok {
+		t.Fatal("env fallback must not be BYOK")
+	}
+}
+
+func TestResolveCompleterForRole_usesRoleBindingWhenSet(t *testing.T) {
+	svc := &Service{
+		Env: EnvConfig{
+			OpenAIAPIKey: "sk-should-not-win",
+			OpenAIModel:  "env-model",
+		},
+		Roles: stubRoleSource{
+			ok: true,
+			ep: RoleEndpoint{
+				APIKey:    "sk-role-processing",
+				BaseURL:   "https://role.example/v1",
+				Model:     "role-model",
+				UsingBYOK: false,
+				ModeLabel: ModeInternalLabel,
+			},
+		},
+	}
+	c, label, byok, err := svc.ResolveCompleterForRole(context.Background(), uuid.New(), RoleProcessing)
+	if err != nil {
+		t.Fatal(err)
+	}
+	oc, ok := c.(*processing.OpenAIClient)
+	if !ok || oc == nil {
+		t.Fatalf("type=%T", c)
+	}
+	if oc.APIKey != "sk-role-processing" || oc.Model != "role-model" {
+		t.Fatalf("key=%q model=%q", oc.APIKey, oc.Model)
+	}
+	if label != ModeInternalLabel || byok {
+		t.Fatalf("label=%q byok=%v", label, byok)
+	}
+}
+
+func TestResolveCompleterForRole_platformProcessingRole(t *testing.T) {
+	plat := platformsettings.NewService(nil, platformsettings.EnvConfig{
+		OpenAIAPIKey:  "sk-plat-processing",
+		OpenAIBaseURL: "http://127.0.0.1:8767/v1",
+		OpenAIModel:   "plat-model",
+	})
+	svc := &Service{
+		Platform: plat,
+		Env:      EnvConfig{OpenAIAPIKey: "sk-should-not-win", OpenAIModel: "env-model"},
+	}
+	c, label, byok, err := svc.ResolveCompleterForRole(context.Background(), uuid.Nil, RoleProcessing)
+	if err != nil {
+		t.Fatal(err)
+	}
+	oc, ok := c.(*processing.OpenAIClient)
+	if !ok || oc == nil {
+		t.Fatalf("type=%T", c)
+	}
+	if oc.APIKey != "sk-plat-processing" || oc.Model != "plat-model" {
+		t.Fatalf("key=%q model=%q", oc.APIKey, oc.Model)
+	}
+	if label != ModeInternalLabel || byok {
+		t.Fatalf("label=%q byok=%v", label, byok)
+	}
+}
+
+func TestResolveCompleterForRole_vectorizationUnsetNoChatFallback(t *testing.T) {
+	svc := &Service{
+		Env: EnvConfig{OpenAIAPIKey: "sk-env", OpenAIModel: "m"},
+	}
+	c, _, _, err := svc.ResolveCompleterForRole(context.Background(), uuid.Nil, RoleVectorization)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if c != nil {
+		t.Fatal("vectorization must not fall back to chat completer")
+	}
+}
+
+func TestResolveEmbedderForRole_usesPlatformVectorization(t *testing.T) {
+	plat := platformsettings.NewService(nil, platformsettings.EnvConfig{
+		OpenAIAPIKey:           "sk-embed-env",
+		OpenAIBaseURL:          "http://127.0.0.1:8767/v1",
+		OpenAIEmbeddingModel:   "text-embedding-3-small",
+	})
+	svc := &Service{Platform: plat}
+	emb, err := svc.ResolveEmbedderForRole(context.Background(), uuid.Nil, RoleVectorization)
+	if err != nil {
+		t.Fatal(err)
+	}
+	oc, ok := emb.(*processing.OpenAIClient)
+	if !ok || oc == nil || !oc.Enabled() {
+		t.Fatalf("expected OpenAIClient embedder, got %T", emb)
+	}
+	if oc.APIKey != "sk-embed-env" || oc.Model != "text-embedding-3-small" {
+		t.Fatalf("key=%q model=%q", oc.APIKey, oc.Model)
+	}
+}
+
+func TestResolveCompleterForRole_supportUnsetNoEnvFallback(t *testing.T) {
+	svc := &Service{
+		Env: EnvConfig{OpenAIAPIKey: "sk-env", OpenAIModel: "m"},
+	}
+	c, _, _, err := svc.ResolveCompleterForRole(context.Background(), uuid.Nil, RoleSupport)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if c != nil {
+		t.Fatal("unset support must not fall back to processing/env completer")
+	}
+}

apps/api/internal/aiprovider/service.go

@@ -0,0 +1,443 @@
+package aiprovider
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/descrybe/descrybe-v2/apps/api/internal/platformsettings"
+	"github.com/descrybe/descrybe-v2/apps/api/internal/processing"
+	"github.com/descrybe/descrybe-v2/apps/api/internal/security"
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+var (
+	ErrNotConfigured  = errors.New("ai provider not configured")
+	ErrInvalidMode    = errors.New("mode must be internal, popular, or custom")
+	ErrInvalidPopular = errors.New("unknown popular provider")
+	ErrMissingAPIKey  = errors.New("api key required")
+	ErrMissingModel   = errors.New("model required")
+	ErrMissingURL     = errors.New("base url required for custom provider")
+)
+
+// aiProbeTimeout bounds admin/company connection tests so a hung provider cannot
+// hold the HTTP request for multi-retry OpenAI client durations.
+const aiProbeTimeout = 45 * time.Second
+
+type Service struct {
+	Pool       *pgxpool.Pool
+	Key        []byte
+	Env        EnvConfig
+	// Platform is optional; when set, platform OpenAI is loaded from admin
+	// settings (DB) with EnvConfig as bootstrap fallback.
+	Platform   *platformsettings.Service
+	// Roles is optional admin role-binding lookup (processing / embeddings / …).
+	// When nil or a role is unset, ResolveCompleterForRole falls back to Resolve.
+	Roles      RoleEndpointSource
+	HTTPClient *http.Client
+}
+
+func NewService(pool *pgxpool.Pool, env EnvConfig) *Service {
+	keyMaterial := firstNonEmpty(env.AppEncryptionKey, env.CredentialsEncryptionKey, env.TokenSigningSecret)
+	return &Service{
+		Pool: pool,
+		Key:  DeriveKey(keyMaterial, env.DatabaseURL),
+		Env:  env,
+		// HTTPClient is optional (tests). Production uses NewOpenAIClient's
+		// SafeHTTPClient so dial-time SSRF applies; leave nil here so platform
+		// OPENAI_BASE_URL loopback (local models) is not overwritten.
+	}
+}
+
+type stored struct {
+	mode, popularName, baseURL, model, keyEnc, last4 string
+	enabled                                          bool
+	lastTest                                         *time.Time
+	lastStatus                                       *string
+}
+
+func (s *Service) loadStored(ctx context.Context, companyID uuid.UUID) (stored, error) {
+	var st stored
+	err := s.Pool.QueryRow(ctx, `
+		SELECT mode, popular_name, base_url, model, api_key_enc, api_key_last4, is_enabled,
+		       last_test_at, last_test_status
+		FROM ai_providers WHERE company_id = $1`, companyID).Scan(
+		&st.mode, &st.popularName, &st.baseURL, &st.model, &st.keyEnc, &st.last4, &st.enabled,
+		&st.lastTest, &st.lastStatus,
+	)
+	return st, err
+}
+
+func (s *Service) GetConfig(ctx context.Context, companyID uuid.UUID) (PublicConfig, error) {
+	platformOK, err := s.platformConfigured(ctx)
+	if err != nil {
+		return PublicConfig{}, err
+	}
+	st, err := s.loadStored(ctx, companyID)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return PublicConfig{
+			Mode:             ModeInternal,
+			Configured:       false,
+			IsEnabled:        false,
+			ActiveModeLabel:  ModeInternalLabel,
+			PlatformFallback: platformOK,
+			PopularProviders: PopularCatalog,
+		}, nil
+	}
+	if err != nil {
+		return PublicConfig{}, err
+	}
+	hasKey := st.keyEnc != ""
+	masked := ""
+	if hasKey && st.last4 != "" {
+		masked = "••••" + st.last4
+	}
+	active := ModeInternalLabel
+	if st.enabled && hasKey && (st.mode == ModePopular || st.mode == ModeCustom) {
+		active = AnalyticsMode(st.mode, st.popularName)
+	}
+	return PublicConfig{
+		Mode:             normalizeMode(st.mode),
+		PopularName:      st.popularName,
+		BaseURL:          st.baseURL,
+		Model:            st.model,
+		IsEnabled:        st.enabled,
+		Configured:       true,
+		HasAPIKey:        hasKey,
+		APIKeyLast4:      st.last4,
+		APIKeyMasked:     masked,
+		LastTestAt:       st.lastTest,
+		LastTestStatus:   st.lastStatus,
+		ActiveModeLabel:  active,
+		PlatformFallback: platformOK,
+		PopularProviders: PopularCatalog,
+	}, nil
+}
+
+func (s *Service) UpdateConfig(ctx context.Context, companyID uuid.UUID, in UpdateInput) (PublicConfig, error) {
+	mode := normalizeMode(in.Mode)
+	if mode != ModeInternal && mode != ModePopular && mode != ModeCustom {
+		return PublicConfig{}, ErrInvalidMode
+	}
+
+	var existing stored
+	existing, err := s.loadStored(ctx, companyID)
+	if err != nil && !errors.Is(err, pgx.ErrNoRows) {
+		return PublicConfig{}, err
+	}
+	hasExisting := err == nil
+
+	keyEnc := ""
+	last4v := ""
+	if hasExisting {
+		keyEnc = existing.keyEnc
+		last4v = existing.last4
+	}
+	if in.ClearAPIKey {
+		keyEnc = ""
+		last4v = ""
+	} else if strings.TrimSpace(in.APIKey) != "" {
+		plain := strings.TrimSpace(in.APIKey)
+		enc, err := EncryptSecret(s.Key, plain)
+		if err != nil {
+			return PublicConfig{}, err
+		}
+		keyEnc = enc
+		last4v = last4(plain)
+	}
+
+	popularName := ""
+	baseURL := ""
+	model := strings.TrimSpace(in.Model)
+
+	switch mode {
+	case ModeInternal:
+		// Platform fallback; company key optional/cleared when switching away from BYOK.
+		if !in.IsEnabled {
+			keyEnc = ""
+			last4v = ""
+		}
+	case ModePopular:
+		pop, ok := FindPopular(in.PopularName)
+		if !ok {
+			return PublicConfig{}, ErrInvalidPopular
+		}
+		popularName = pop.Name
+		baseURL = pop.BaseURL
+		if model == "" {
+			model = pop.DefaultModel
+		}
+		if !modelAllowed(pop, model) {
+			return PublicConfig{}, ClientMsg(fmt.Sprintf("model %q is not in the %s catalog (or leave blank for default)", model, pop.Name))
+		}
+		if in.IsEnabled && keyEnc == "" {
+			return PublicConfig{}, ErrMissingAPIKey
+		}
+	case ModeCustom:
+		normalized, err := validateProviderBaseURL(in.BaseURL)
+		if err != nil {
+			return PublicConfig{}, err
+		}
+		baseURL = normalized
+		if model == "" {
+			return PublicConfig{}, ErrMissingModel
+		}
+		if in.IsEnabled && keyEnc == "" {
+			return PublicConfig{}, ErrMissingAPIKey
+		}
+	}
+
+	_, err = s.Pool.Exec(ctx, `
+		INSERT INTO ai_providers (
+			company_id, mode, popular_name, base_url, model, api_key_enc, api_key_last4, is_enabled, updated_at
+		) VALUES ($1,$2,$3,$4,$5,$6,$7,$8, now())
+		ON CONFLICT (company_id) DO UPDATE SET
+			mode = EXCLUDED.mode,
+			popular_name = EXCLUDED.popular_name,
+			base_url = EXCLUDED.base_url,
+			model = EXCLUDED.model,
+			api_key_enc = EXCLUDED.api_key_enc,
+			api_key_last4 = EXCLUDED.api_key_last4,
+			is_enabled = EXCLUDED.is_enabled,
+			updated_at = now()`,
+		companyID, mode, popularName, baseURL, model, keyEnc, last4v, in.IsEnabled && mode != ModeInternal)
+	if err != nil {
+		return PublicConfig{}, err
+	}
+	return s.GetConfig(ctx, companyID)
+}
+
+func modelAllowed(pop PopularProvider, model string) bool {
+	model = strings.TrimSpace(model)
+	if model == "" || model == pop.DefaultModel {
+		return true
+	}
+	for _, m := range pop.Models {
+		if m == model {
+			return true
+		}
+	}
+	// Allow unknown model strings for popular providers (API may add models faster than catalog).
+	return true
+}
+
+func validateProviderBaseURL(raw string) (string, error) {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return "", ErrMissingURL
+	}
+	normalized, err := security.ValidatePublicHTTPSURL(raw)
+	if err != nil {
+		return "", err
+	}
+	if normalized == "" {
+		return "", ErrMissingURL
+	}
+	return strings.TrimRight(normalized, "/"), nil
+}
+
+// Resolve picks company BYOK completer when enabled+keyed, else platform AI
+// from admin settings (DB), with optional env fallback via Platform / Env.
+func (s *Service) Resolve(ctx context.Context, companyID uuid.UUID) (Resolved, error) {
+	rpm := s.Env.ProcessingRPM
+	retries := s.Env.ProcessingMaxRetries
+
+	st, err := s.loadStored(ctx, companyID)
+	if err != nil && !errors.Is(err, pgx.ErrNoRows) {
+		return Resolved{}, err
+	}
+	if err == nil && st.enabled && (st.mode == ModePopular || st.mode == ModeCustom) {
+		key, derr := DecryptSecret(s.Key, st.keyEnc)
+		if derr != nil {
+			return Resolved{}, derr
+		}
+		if strings.TrimSpace(key) != "" && strings.TrimSpace(st.baseURL) != "" && strings.TrimSpace(st.model) != "" {
+			client := processing.NewOpenAIClient(key, st.baseURL, st.model, rpm, retries)
+			client.ModeLabel = AnalyticsMode(st.mode, st.popularName)
+			if s.HTTPClient != nil {
+				client.HTTPClient = s.HTTPClient
+			}
+			return Resolved{
+				Completer: client,
+				ModeLabel: client.ModeLabel,
+				UsingBYOK: true,
+			}, nil
+		}
+	}
+
+	platform, err := s.resolvePlatformOpenAI(ctx)
+	if err != nil {
+		return Resolved{}, err
+	}
+	if strings.TrimSpace(platform.APIKey) == "" {
+		return Resolved{ModeLabel: ModeInternalLabel, UsingBYOK: false}, nil
+	}
+	client := processing.NewOpenAIClient(
+		platform.APIKey,
+		platform.BaseURL,
+		platform.Model,
+		rpm,
+		retries,
+	)
+	client.ModeLabel = ModeInternalLabel
+	if s.HTTPClient != nil {
+		client.HTTPClient = s.HTTPClient
+	}
+	return Resolved{
+		Completer: client,
+		ModeLabel: ModeInternalLabel,
+		UsingBYOK: false,
+	}, nil
+}
+
+func (s *Service) platformConfigured(ctx context.Context) (bool, error) {
+	oi, err := s.resolvePlatformOpenAI(ctx)
+	if err != nil {
+		return false, err
+	}
+	return strings.TrimSpace(oi.APIKey) != "", nil
+}
+
+func (s *Service) resolvePlatformOpenAI(ctx context.Context) (platformsettings.ResolvedOpenAI, error) {
+	if s.Platform != nil {
+		return s.Platform.ResolveOpenAI(ctx)
+	}
+	out := platformsettings.ResolvedOpenAI{
+		APIKey:  strings.TrimSpace(s.Env.OpenAIAPIKey),
+		BaseURL: strings.TrimSpace(s.Env.OpenAIBaseURL),
+		Model:   strings.TrimSpace(s.Env.OpenAIModel),
+		Source:  platformsettings.SourceNone,
+	}
+	if out.APIKey != "" {
+		out.Source = platformsettings.SourceEnv
+	}
+	return out, nil
+}
+
+// ResolveCompleter implements processing.CompanyCompleterResolver (legacy callers).
+// Prefer ResolveCompleterForRole for new call sites.
+func (s *Service) ResolveCompleter(ctx context.Context, companyID uuid.UUID) (processing.Completer, string, bool, error) {
+	r, err := s.Resolve(ctx, companyID)
+	if err != nil {
+		return nil, ModeInternalLabel, false, err
+	}
+	return r.Completer, r.ModeLabel, r.UsingBYOK, nil
+}
+
+// TestPlatformRole probes admin platform AI role credentials (not company BYOK).
+// Chat roles send a minimal completion; vectorization sends a one-token embed.
+// Never returns upstream error bodies (may contain key fragments).
+func (s *Service) TestPlatformRole(ctx context.Context, role string) (map[string]any, error) {
+	ctx, cancel := context.WithTimeout(ctx, aiProbeTimeout)
+	defer cancel()
+	role = strings.TrimSpace(role)
+	out := map[string]any{"role": role}
+	if role == "" || !platformsettings.ValidAIRole(role) {
+		out["status"] = "failed"
+		out["message"] = "unknown ai role"
+		return out, fmt.Errorf("unknown ai role %q", role)
+	}
+
+	if role == RoleVectorization {
+		emb, err := s.ResolveEmbedderForRole(ctx, uuid.Nil, role)
+		if err != nil {
+			out["status"] = "failed"
+			out["message"] = "provider resolve failed"
+			return out, err
+		}
+		if emb == nil {
+			out["status"] = "skipped"
+			out["message"] = "Vectorization AI is not configured in admin platform settings"
+			return out, nil
+		}
+		if _, err := emb.Embed(ctx, []string{"ping"}); err != nil {
+			out["status"] = "failed"
+			out["message"] = "connection failed — check vectorization provider, key, and model"
+			return out, err
+		}
+		out["status"] = "ok"
+		out["message"] = "Embeddings probe succeeded"
+		return out, nil
+	}
+
+	completer, _, _, err := s.resolvePlatformRoleCompleter(ctx, role)
+	if err != nil {
+		out["status"] = "failed"
+		out["message"] = "provider resolve failed"
+		return out, err
+	}
+	if completer == nil {
+		out["status"] = "skipped"
+		out["message"] = "AI role is not configured (or disabled) in admin platform settings"
+		return out, nil
+	}
+	if _, err := completer.Complete(ctx, "Reply with exactly: ok", "ping"); err != nil {
+		out["status"] = "failed"
+		out["message"] = "connection failed — check provider, key, base URL, and model"
+		return out, err
+	}
+	out["status"] = "ok"
+	out["message"] = "Connection probe succeeded"
+	return out, nil
+}
+
+// TestConnection sends a minimal chat completion and records last_test_*.
+func (s *Service) TestConnection(ctx context.Context, companyID uuid.UUID) (map[string]any, error) {
+	ctx, cancel := context.WithTimeout(ctx, aiProbeTimeout)
+	defer cancel()
+	resolved, err := s.Resolve(ctx, companyID)
+	status := "ok"
+	message := "connection successful"
+	if err != nil {
+		status = "failed"
+		message = "provider resolve failed"
+		_, _ = s.Pool.Exec(ctx, `
+			UPDATE ai_providers SET last_test_at = now(), last_test_status = $2, updated_at = now()
+			WHERE company_id = $1`, companyID, status)
+		return map[string]any{"status": status, "message": message, "mode": ModeInternalLabel}, err
+	}
+	if resolved.Completer == nil {
+		status = "failed"
+		message = "no api key configured (company BYOK or admin platform settings)"
+		_, _ = s.Pool.Exec(ctx, `
+			UPDATE ai_providers SET last_test_at = now(), last_test_status = $2, updated_at = now()
+			WHERE company_id = $1`, companyID, status)
+		return map[string]any{"status": status, "message": message, "mode": resolved.ModeLabel}, ErrNotConfigured
+	}
+	_, err = resolved.Completer.Complete(ctx, "Reply with exactly: ok", "ping")
+	if err != nil {
+		status = "failed"
+		// TruncateError classifies transport/auth failures without leaking secrets.
+		message = processing.TruncateError(err)
+		if message == "" || message == "provider error (details redacted)" {
+			message = "connection failed — check provider, key, base URL, and model"
+		}
+		_, _ = s.Pool.Exec(ctx, `
+			UPDATE ai_providers SET last_test_at = now(), last_test_status = $2, updated_at = now()
+			WHERE company_id = $1`, companyID, status)
+		return map[string]any{"status": status, "message": message, "mode": resolved.ModeLabel}, err
+	}
+	_, _ = s.Pool.Exec(ctx, `
+		UPDATE ai_providers SET last_test_at = now(), last_test_status = $2, updated_at = now()
+		WHERE company_id = $1`, companyID, status)
+	return map[string]any{
+		"status":  status,
+		"message": message,
+		"mode":    resolved.ModeLabel,
+		"byok":    resolved.UsingBYOK,
+	}, nil
+}
+
+func firstNonEmpty(vals ...string) string {
+	for _, v := range vals {
+		if strings.TrimSpace(v) != "" {
+			return v
+		}
+	}
+	return ""
+}

apps/api/internal/aiprovider/service_test.go

@@ -0,0 +1,93 @@
+package aiprovider
+
+import "testing"
+
+func TestEncryptDecryptRoundTrip(t *testing.T) {
+	t.Setenv("APP_ENV", "development")
+	key := DeriveKey("test-ai-key-material", "fallback")
+	enc, err := EncryptSecret(key, "sk-test-secret-value")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if enc == "" || enc == "sk-test-secret-value" {
+		t.Fatalf("expected ciphertext, got %q", enc)
+	}
+	plain, err := DecryptSecret(key, enc)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if plain != "sk-test-secret-value" {
+		t.Fatalf("got %q", plain)
+	}
+}
+
+func TestDecryptSecret_plaintextPassthrough(t *testing.T) {
+	// Legacy/migrated rows may store unprefixed plaintext in local/dev only.
+	t.Setenv("APP_ENV", "development")
+	key := DeriveKey("test-ai-key-material", "fallback")
+	got, err := DecryptSecret(key, "sk-legacy-plain")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got != "sk-legacy-plain" {
+		t.Fatalf("got %q", got)
+	}
+}
+
+func TestDecryptSecret_plaintextRejectedInProduction(t *testing.T) {
+	t.Setenv("APP_ENV", "production")
+	key := DeriveKey("test-ai-key-material", "fallback")
+	if _, err := DecryptSecret(key, "sk-legacy-plain"); err == nil {
+		t.Fatal("expected plaintext decrypt rejected in production")
+	}
+}
+
+func TestAnalyticsMode(t *testing.T) {
+	cases := []struct {
+		mode, name, want string
+	}{
+		{ModeInternal, "", "internal"},
+		{ModePopular, "openai", "popular:openai"},
+		{ModePopular, "Google", "popular:google"},
+		{ModeCustom, "", "custom"},
+		{"", "", "internal"},
+	}
+	for _, c := range cases {
+		got := AnalyticsMode(c.mode, c.name)
+		if got != c.want {
+			t.Fatalf("AnalyticsMode(%q,%q)=%q want %q", c.mode, c.name, got, c.want)
+		}
+	}
+}
+
+func TestLast4(t *testing.T) {
+	if got := last4("sk-abcdefgh"); got != "efgh" {
+		t.Fatalf("got %q", got)
+	}
+	if got := last4("ab"); got != "ab" {
+		t.Fatalf("got %q", got)
+	}
+}
+
+func TestFindPopular(t *testing.T) {
+	p, ok := FindPopular("openai")
+	if !ok || p.BaseURL == "" {
+		t.Fatal("expected openai")
+	}
+	if _, ok := FindPopular("nope"); ok {
+		t.Fatal("expected miss")
+	}
+}
+
+func TestValidateProviderBaseURL(t *testing.T) {
+	ok, err := validateProviderBaseURL("https://api.openai.com/v1")
+	if err != nil || ok == "" {
+		t.Fatalf("want ok, got %q err=%v", ok, err)
+	}
+	if _, err := validateProviderBaseURL("http://169.254.169.254/"); err == nil {
+		t.Fatal("expected metadata URL blocked")
+	}
+	if _, err := validateProviderBaseURL("http://192.168.1.1/v1"); err == nil {
+		t.Fatal("expected private IP blocked")
+	}
+}

apps/api/internal/aiprovider/types.go

@@ -0,0 +1,55 @@
+package aiprovider
+
+import (
+	"time"
+
+	"github.com/descrybe/descrybe-v2/apps/api/internal/processing"
+)
+
+// PublicConfig is the tenant-safe view (no raw secrets).
+type PublicConfig struct {
+	Mode              string     `json:"mode"`
+	PopularName       string     `json:"popular_name,omitempty"`
+	BaseURL           string     `json:"base_url,omitempty"`
+	Model             string     `json:"model,omitempty"`
+	IsEnabled         bool       `json:"is_enabled"`
+	Configured        bool       `json:"configured"`
+	HasAPIKey         bool       `json:"has_api_key"`
+	APIKeyLast4       string     `json:"api_key_last4,omitempty"`
+	APIKeyMasked      string     `json:"api_key_masked,omitempty"`
+	LastTestAt        *time.Time `json:"last_test_at,omitempty"`
+	LastTestStatus    *string    `json:"last_test_status,omitempty"`
+	ActiveModeLabel   string     `json:"active_mode_label"`
+	PlatformFallback  bool       `json:"platform_fallback_available"`
+	PopularProviders  []PopularProvider `json:"popular_providers,omitempty"`
+}
+
+// UpdateInput is the PUT body. Empty api_key keeps the existing encrypted key.
+type UpdateInput struct {
+	Mode        string `json:"mode"`
+	PopularName string `json:"popular_name"`
+	BaseURL     string `json:"base_url"`
+	Model       string `json:"model"`
+	APIKey      string `json:"api_key"`
+	IsEnabled   bool   `json:"is_enabled"`
+	ClearAPIKey bool   `json:"clear_api_key"`
+}
+
+// Resolved is the runtime completer + analytics mode for one company job.
+type Resolved struct {
+	Completer processing.Completer
+	ModeLabel string // internal | popular:<name> | custom
+	UsingBYOK bool   // true when company key is used (skip managed token credits)
+}
+
+type EnvConfig struct {
+	AppEncryptionKey         string
+	CredentialsEncryptionKey string
+	TokenSigningSecret       string
+	DatabaseURL              string
+	OpenAIAPIKey             string // optional env bootstrap; prefer admin platform settings
+	OpenAIBaseURL            string
+	OpenAIModel              string
+	ProcessingRPM            int
+	ProcessingMaxRetries     int
+}

apps/api/internal/auth/apikey.go

@@ -0,0 +1,63 @@
+package auth
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"strings"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5"
+)
+
+var ErrInvalidAPIKey = errors.New("invalid api key")
+
+// APIKeyIdentity is the tenant binding resolved from a valid API key.
+type APIKeyIdentity struct {
+	KeyID          uuid.UUID
+	CompanyID      uuid.UUID
+	UserID         uuid.UUID
+	MembershipRole string // active membership role for the key owner (admin|member)
+}
+
+// HashAPIKey returns a SHA-256 hex digest for O(1) api_keys.key_hash lookup.
+// Matches hashes written by dashboard key creation. Also used for invite tokens at rest.
+func HashAPIKey(raw string) string {
+	sum := sha256.Sum256([]byte(raw))
+	return hex.EncodeToString(sum[:])
+}
+
+// AuthenticateAPIKey looks up a non-revoked key by hash and updates last_used_at.
+// Keys owned by inactive users or without an active company membership are rejected.
+// MembershipRole is returned so HTTP middleware can withhold company-admin powers
+// when the owner is no longer an admin (keys are admin-created; scopes/expiry columns
+// do not exist yet — empty/full privilege remains the default for admin-owned keys).
+func (s *Service) AuthenticateAPIKey(ctx context.Context, raw string) (APIKeyIdentity, error) {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return APIKeyIdentity{}, ErrInvalidAPIKey
+	}
+	hash := HashAPIKey(raw)
+	var id APIKeyIdentity
+	var role string
+	err := s.Pool.QueryRow(ctx, `
+		SELECT k.id, k.company_id, k.user_id, m.role
+		FROM api_keys k
+		INNER JOIN users u ON u.id = k.user_id AND u.is_active = true
+		INNER JOIN memberships m ON m.user_id = k.user_id
+			AND m.company_id = k.company_id
+			AND m.status = 'active'
+		WHERE k.key_hash = $1 AND k.revoked_at IS NULL`, hash).
+		Scan(&id.KeyID, &id.CompanyID, &id.UserID, &role)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return APIKeyIdentity{}, ErrInvalidAPIKey
+	}
+	if err != nil {
+		return APIKeyIdentity{}, err
+	}
+	id.MembershipRole = NormalizeMembershipRole(role)
+	_, _ = s.Pool.Exec(ctx, `
+		UPDATE api_keys SET last_used_at = now(), updated_at = now() WHERE id = $1`, id.KeyID)
+	return id, nil
+}

apps/api/internal/auth/apikey_test.go

@@ -0,0 +1,28 @@
+package auth
+
+import (
+	"testing"
+)
+
+func TestHashAPIKeyDeterministic(t *testing.T) {
+	t.Parallel()
+	a := HashAPIKey("dk_test_secret_value")
+	b := HashAPIKey("dk_test_secret_value")
+	if a != b {
+		t.Fatalf("hash not deterministic")
+	}
+	if len(a) != 64 {
+		t.Fatalf("expected sha256 hex length 64, got %d", len(a))
+	}
+	if HashAPIKey("other") == a {
+		t.Fatal("different keys must not collide")
+	}
+}
+
+func TestHashAPIKeyEmpty(t *testing.T) {
+	t.Parallel()
+	got := HashAPIKey("")
+	if len(got) != 64 {
+		t.Fatalf("empty input still hashes: len=%d", len(got))
+	}
+}

apps/api/internal/auth/errors.go

@@ -0,0 +1,41 @@
+package auth
+
+import "errors"
+
+var (
+	ErrRegisterFieldsRequired = errors.New("email, password, and company name are required")
+	ErrPasswordTooShort       = errors.New("password must be at least 8 characters")
+	ErrUserNotFound           = errors.New("user not found")
+	ErrNotCompanyMember       = errors.New("not a member of company")
+	ErrInviteNotFound         = errors.New("invite not found")
+	ErrEmailRequired          = errors.New("email is required")
+	ErrSyntheticEmail         = errors.New("synthetic migration email cannot receive invites")
+	ErrNotEligibleSetPassword = errors.New("user not eligible for set-password invite")
+	ErrEmailMismatch          = errors.New("signed-in email does not match invite email")
+)
+
+// ClientError reports whether err is a known client-facing auth error.
+func ClientError(err error) (msg string, ok bool) {
+	switch {
+	case err == nil:
+		return "", false
+	case errors.Is(err, ErrRegisterFieldsRequired),
+		errors.Is(err, ErrPasswordTooShort),
+		errors.Is(err, ErrPasswordAlreadySet),
+		errors.Is(err, ErrUserExists),
+		errors.Is(err, ErrInviteInvalid),
+		errors.Is(err, ErrInvalidCredentials),
+		errors.Is(err, ErrMustSetPassword),
+		errors.Is(err, ErrUserNotFound),
+		errors.Is(err, ErrNotCompanyMember),
+		errors.Is(err, ErrInviteNotFound),
+		errors.Is(err, ErrTokenInvalid),
+		errors.Is(err, ErrEmailRequired),
+		errors.Is(err, ErrSyntheticEmail),
+		errors.Is(err, ErrNotEligibleSetPassword),
+		errors.Is(err, ErrEmailMismatch):
+		return err.Error(), true
+	default:
+		return "", false
+	}
+}

apps/api/internal/auth/invites.go

@@ -0,0 +1,327 @@
+package auth
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5"
+)
+
+// Invite is a pending company invite row (plaintext token returned once at creation; hashed at rest).
+type Invite struct {
+	ID        uuid.UUID `json:"id"`
+	CompanyID uuid.UUID `json:"company_id"`
+	Email     string    `json:"email"`
+	Role      string    `json:"role"`
+	ExpiresAt time.Time `json:"expires_at"`
+}
+
+func normalizeInviteRole(role string) string {
+	role = strings.TrimSpace(strings.ToLower(role))
+	if role == "admin" {
+		return "admin"
+	}
+	return "member"
+}
+
+// NormalizeMembershipRole maps invite/membership role strings to admin|member.
+// Unknown values collapse to member (safe default for invites).
+func NormalizeMembershipRole(role string) string {
+	return normalizeInviteRole(role)
+}
+
+// ErrInvalidMembershipRole is returned when a role is not exactly admin|member.
+var ErrInvalidMembershipRole = errors.New("invalid membership role")
+
+// ParseMembershipRole accepts only admin|member (case-insensitive). Unlike
+// NormalizeMembershipRole it does not coerce unknown values to member — use for
+// PATCH/role updates where coercion would silently demote admins.
+func ParseMembershipRole(role string) (string, error) {
+	role = strings.TrimSpace(strings.ToLower(role))
+	switch role {
+	case "admin", "member":
+		return role, nil
+	default:
+		return "", ErrInvalidMembershipRole
+	}
+}
+
+// preferMembershipRole keeps admin on invite accept conflict (never demote admin→member).
+// Mirrors AcceptInvite ON CONFLICT role CASE.
+func preferMembershipRole(existing, invited string) string {
+	if existing == "admin" {
+		return "admin"
+	}
+	return normalizeInviteRole(invited)
+}
+
+// HashInviteToken returns the SHA-256 hex digest stored in invites.token (same construction as API keys).
+func HashInviteToken(raw string) string {
+	return HashAPIKey(raw)
+}
+
+// IsSyntheticLegacyEmail reports Clerk-missing synthetic addresses that must not receive invites.
+func IsSyntheticLegacyEmail(email string) bool {
+	email = strings.ToLower(strings.TrimSpace(email))
+	return strings.HasSuffix(email, "@legacy.local")
+}
+
+// EmailsEqual compares emails case-insensitively after trim.
+func EmailsEqual(a, b string) bool {
+	return strings.EqualFold(strings.TrimSpace(a), strings.TrimSpace(b))
+}
+
+// ResolveInviteEmail returns the invitee email for a pending, unexpired invite token.
+func (s *Service) ResolveInviteEmail(ctx context.Context, token string) (string, error) {
+	token = strings.TrimSpace(token)
+	if token == "" {
+		return "", ErrInviteInvalid
+	}
+	var (
+		email      string
+		expiresAt  time.Time
+		acceptedAt *time.Time
+	)
+	tokenHash := HashInviteToken(token)
+	err := s.Pool.QueryRow(ctx, `
+		SELECT email, expires_at, accepted_at
+		FROM invites
+		WHERE token = $1 OR token = $2
+		ORDER BY CASE WHEN token = $1 THEN 0 ELSE 1 END
+		LIMIT 1`, tokenHash, token).Scan(&email, &expiresAt, &acceptedAt)
+	if errors.Is(err, pgx.ErrNoRows) || (acceptedAt != nil) || time.Now().After(expiresAt) {
+		return "", ErrInviteInvalid
+	}
+	if err != nil {
+		return "", err
+	}
+	return strings.ToLower(strings.TrimSpace(email)), nil
+}
+
+// SetPasswordInvite is a one-time accept-invite token for a migrated user (plaintext returned once).
+type SetPasswordInvite struct {
+	InviteID  uuid.UUID
+	UserID    uuid.UUID
+	Email     string
+	CompanyID uuid.UUID
+	Role      string
+	Token     string
+	ExpiresAt time.Time
+}
+
+// CreateInvite inserts a pending invite (token hashed at rest) and returns the plaintext token once.
+func (s *Service) CreateInvite(ctx context.Context, companyID, invitedBy uuid.UUID, email, role string) (Invite, string, error) {
+	email = strings.ToLower(strings.TrimSpace(email))
+	if email == "" {
+		return Invite{}, "", ErrEmailRequired
+	}
+	role = normalizeInviteRole(role)
+	token, err := RandomToken(24)
+	if err != nil {
+		return Invite{}, "", err
+	}
+	expires := time.Now().UTC().Add(7 * 24 * time.Hour)
+	var inv Invite
+	err = s.Pool.QueryRow(ctx, `
+		INSERT INTO invites (company_id, email, role, token, invited_by, expires_at)
+		VALUES ($1, $2, $3, $4, $5, $6)
+		RETURNING id, company_id, email, role, expires_at`,
+		companyID, email, role, HashInviteToken(token), invitedBy, expires,
+	).Scan(&inv.ID, &inv.CompanyID, &inv.Email, &inv.Role, &inv.ExpiresAt)
+	if err != nil {
+		return Invite{}, "", err
+	}
+	return inv, token, nil
+}
+
+// ListPendingInvites returns unaccepted, unexpired invites for a company.
+func (s *Service) ListPendingInvites(ctx context.Context, companyID uuid.UUID, limit, offset int) ([]Invite, int64, error) {
+	const where = `company_id = $1 AND accepted_at IS NULL AND expires_at > now()`
+	var total int64
+	if err := s.Pool.QueryRow(ctx, `SELECT count(*) FROM invites WHERE `+where, companyID).Scan(&total); err != nil {
+		return nil, 0, err
+	}
+	rows, err := s.Pool.Query(ctx, `
+		SELECT id, company_id, email, role, expires_at
+		FROM invites
+		WHERE `+where+`
+		ORDER BY created_at DESC LIMIT $2 OFFSET $3`, companyID, limit, offset)
+	if err != nil {
+		return nil, 0, err
+	}
+	defer rows.Close()
+	var out []Invite
+	for rows.Next() {
+		var inv Invite
+		if err := rows.Scan(&inv.ID, &inv.CompanyID, &inv.Email, &inv.Role, &inv.ExpiresAt); err != nil {
+			return nil, 0, err
+		}
+		out = append(out, inv)
+	}
+	return out, total, rows.Err()
+}
+
+// RevokeInvite deletes a pending invite owned by the company.
+func (s *Service) RevokeInvite(ctx context.Context, companyID, inviteID uuid.UUID) error {
+	ct, err := s.Pool.Exec(ctx, `
+		DELETE FROM invites
+		WHERE id = $1 AND company_id = $2 AND accepted_at IS NULL`, inviteID, companyID)
+	if err != nil {
+		return err
+	}
+	if ct.RowsAffected() == 0 {
+		return ErrInviteNotFound
+	}
+	return nil
+}
+
+// CompanyName returns the display name for a company.
+func (s *Service) CompanyName(ctx context.Context, companyID uuid.UUID) (string, error) {
+	var name string
+	err := s.Pool.QueryRow(ctx, `SELECT name FROM companies WHERE id = $1`, companyID).Scan(&name)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return "", errors.New("company not found")
+	}
+	return name, err
+}
+
+// UpdateMembershipRole sets an active membership role to admin or member.
+func (s *Service) UpdateMembershipRole(ctx context.Context, companyID, userID uuid.UUID, role string) (Membership, error) {
+	role = normalizeInviteRole(role)
+	var m Membership
+	err := s.Pool.QueryRow(ctx, `
+		UPDATE memberships
+		SET role = $3, updated_at = now()
+		WHERE company_id = $1 AND user_id = $2 AND status = 'active'
+		RETURNING id, company_id, user_id, role, status`,
+		companyID, userID, role,
+	).Scan(&m.ID, &m.CompanyID, &m.UserID, &m.Role, &m.Status)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return Membership{}, ErrNotCompanyMember
+	}
+	return m, err
+}
+
+// IsPlatformAdmin reports whether the user has full platform admin privileges
+// (admin/developer or legacy is_platform_admin). support_staff is excluded.
+func (s *Service) IsPlatformAdmin(ctx context.Context, userID uuid.UUID) (bool, error) {
+	access, err := s.GetStaffAccess(ctx, userID)
+	if err != nil {
+		return false, err
+	}
+	return access.FullAdmin, nil
+}
+
+// UpdateProfile updates the user's display name.
+func (s *Service) UpdateProfile(ctx context.Context, userID uuid.UUID, name string) (User, error) {
+	name = strings.TrimSpace(name)
+	var n *string
+	if name != "" {
+		n = &name
+	}
+	_, err := s.Pool.Exec(ctx, `
+		UPDATE users SET name = $2, updated_at = now() WHERE id = $1`, userID, n)
+	if err != nil {
+		return User{}, err
+	}
+	return s.GetUser(ctx, userID)
+}
+
+// ListUsersNeedingPassword returns active users with must_set_password (migration cutover).
+func (s *Service) ListUsersNeedingPassword(ctx context.Context, limit int) ([]User, error) {
+	if limit <= 0 {
+		limit = 100
+	}
+	rows, err := s.Pool.Query(ctx, `
+		SELECT id, email, name, must_set_password, is_platform_admin, staff_role, is_active
+		FROM users
+		WHERE must_set_password = true AND is_active = true
+		ORDER BY email
+		LIMIT $1`, limit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []User
+	for rows.Next() {
+		var u User
+		if err := rows.Scan(&u.ID, &u.Email, &u.Name, &u.MustSetPassword, &u.IsPlatformAdmin, &u.StaffRole, &u.IsActive); err != nil {
+			return nil, err
+		}
+		out = append(out, u)
+	}
+	return out, rows.Err()
+}
+
+// ReissueSetPasswordInvite expires prior pending invites and creates a durable invite for a
+// must_set_password user with an active membership. Token plaintext is returned once.
+func (s *Service) ReissueSetPasswordInvite(ctx context.Context, userID uuid.UUID, ttl time.Duration) (SetPasswordInvite, error) {
+	if ttl <= 0 {
+		ttl = 7 * 24 * time.Hour
+	}
+	var (
+		out             SetPasswordInvite
+		mustSetPassword bool
+		isActive        bool
+	)
+	err := s.Pool.QueryRow(ctx, `
+		SELECT id, email, must_set_password, is_active
+		FROM users WHERE id = $1`, userID).Scan(&out.UserID, &out.Email, &mustSetPassword, &isActive)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return SetPasswordInvite{}, ErrUserNotFound
+	}
+	if err != nil {
+		return SetPasswordInvite{}, err
+	}
+	if !isActive || !mustSetPassword {
+		return SetPasswordInvite{}, ErrNotEligibleSetPassword
+	}
+	if IsSyntheticLegacyEmail(out.Email) {
+		return SetPasswordInvite{}, ErrSyntheticEmail
+	}
+	out.Email = strings.ToLower(strings.TrimSpace(out.Email))
+
+	err = s.Pool.QueryRow(ctx, `
+		SELECT company_id, role
+		FROM memberships
+		WHERE user_id = $1 AND status = 'active'
+		ORDER BY created_at
+		LIMIT 1`, userID).Scan(&out.CompanyID, &out.Role)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return SetPasswordInvite{}, ErrNotEligibleSetPassword
+	}
+	if err != nil {
+		return SetPasswordInvite{}, err
+	}
+	out.Role = normalizeInviteRole(out.Role)
+
+	token, err := RandomToken(24)
+	if err != nil {
+		return SetPasswordInvite{}, err
+	}
+	out.Token = token
+	out.ExpiresAt = time.Now().UTC().Add(ttl)
+
+	// Expire prior unaccepted invites for this email+company so re-issue is safe.
+	if _, err := s.Pool.Exec(ctx, `
+		UPDATE invites
+		SET expires_at = least(expires_at, now())
+		WHERE company_id = $1 AND lower(email) = lower($2) AND accepted_at IS NULL`,
+		out.CompanyID, out.Email); err != nil {
+		return SetPasswordInvite{}, err
+	}
+
+	err = s.Pool.QueryRow(ctx, `
+		INSERT INTO invites (company_id, email, role, token, expires_at)
+		VALUES ($1, $2, $3, $4, $5)
+		RETURNING id`,
+		out.CompanyID, out.Email, out.Role, HashInviteToken(token), out.ExpiresAt,
+	).Scan(&out.InviteID)
+	if err != nil {
+		return SetPasswordInvite{}, err
+	}
+	return out, nil
+}

apps/api/internal/auth/invites_test.go

@@ -0,0 +1,113 @@
+package auth
+
+import (
+	"errors"
+	"testing"
+)
+
+func TestPreferMembershipRoleNeverDemotesAdmin(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		name     string
+		existing string
+		invited  string
+		want     string
+	}{
+		{name: "admin stays admin on member invite", existing: "admin", invited: "member", want: "admin"},
+		{name: "admin stays admin on admin invite", existing: "admin", invited: "admin", want: "admin"},
+		{name: "member promotes to admin", existing: "member", invited: "admin", want: "admin"},
+		{name: "member stays member", existing: "member", invited: "member", want: "member"},
+		{name: "unknown invited normalizes to member", existing: "member", invited: "owner", want: "member"},
+		{name: "empty existing yields invited role", existing: "", invited: "admin", want: "admin"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			got := preferMembershipRole(tc.existing, tc.invited)
+			if got != tc.want {
+				t.Fatalf("preferMembershipRole(%q, %q)=%q want %q", tc.existing, tc.invited, got, tc.want)
+			}
+		})
+	}
+}
+
+func TestHashInviteTokenMatchesAPIKeyHash(t *testing.T) {
+	t.Parallel()
+	const raw = "invite-plaintext-secret"
+	got := HashInviteToken(raw)
+	if got != HashAPIKey(raw) {
+		t.Fatalf("HashInviteToken must match HashAPIKey construction")
+	}
+	if len(got) != 64 {
+		t.Fatalf("expected sha256 hex length 64, got %d", len(got))
+	}
+	if got == raw {
+		t.Fatal("invite token must not be stored as plaintext")
+	}
+}
+
+func TestNormalizeInviteRole(t *testing.T) {
+	t.Parallel()
+	if normalizeInviteRole("Admin") != "admin" {
+		t.Fatal("expected admin")
+	}
+	if normalizeInviteRole(" MEMBER ") != "member" {
+		t.Fatal("expected member")
+	}
+	if normalizeInviteRole("owner") != "member" {
+		t.Fatal("unknown roles collapse to member")
+	}
+	if NormalizeMembershipRole("Admin") != "admin" {
+		t.Fatal("NormalizeMembershipRole should accept Admin")
+	}
+}
+
+func TestParseMembershipRole(t *testing.T) {
+	t.Parallel()
+	got, err := ParseMembershipRole(" Admin ")
+	if err != nil || got != "admin" {
+		t.Fatalf("admin: got %q err=%v", got, err)
+	}
+	got, err = ParseMembershipRole("MEMBER")
+	if err != nil || got != "member" {
+		t.Fatalf("member: got %q err=%v", got, err)
+	}
+	if _, err := ParseMembershipRole("owner"); !errors.Is(err, ErrInvalidMembershipRole) {
+		t.Fatalf("owner: err=%v want ErrInvalidMembershipRole", err)
+	}
+	if _, err := ParseMembershipRole(""); !errors.Is(err, ErrInvalidMembershipRole) {
+		t.Fatalf("empty: err=%v want ErrInvalidMembershipRole", err)
+	}
+}
+
+func TestIsSyntheticLegacyEmail(t *testing.T) {
+	t.Parallel()
+	if !IsSyntheticLegacyEmail("user_abc@legacy.local") {
+		t.Fatal("expected synthetic")
+	}
+	if !IsSyntheticLegacyEmail("  User@Legacy.Local ") {
+		t.Fatal("expected case-insensitive synthetic")
+	}
+	if IsSyntheticLegacyEmail("real@example.com") {
+		t.Fatal("real email must not be treated as synthetic")
+	}
+	if IsSyntheticLegacyEmail("legacy.local@example.com") {
+		t.Fatal("suffix-only match; local-part must not trigger")
+	}
+	if IsSyntheticLegacyEmail("") {
+		t.Fatal("empty must not be synthetic")
+	}
+}
+
+func TestEmailsEqual(t *testing.T) {
+	t.Parallel()
+	if !EmailsEqual("A@Example.COM", " a@example.com ") {
+		t.Fatal("expected equal after normalize")
+	}
+	if EmailsEqual("a@example.com", "b@example.com") {
+		t.Fatal("expected mismatch")
+	}
+	if !EmailsEqual("", "") {
+		t.Fatal("empty emails should compare equal")
+	}
+}

apps/api/internal/auth/password.go

@@ -0,0 +1,61 @@
+package auth
+
+import (
+	"crypto/rand"
+	"crypto/subtle"
+	"encoding/base64"
+	"errors"
+	"fmt"
+	"strings"
+
+	"golang.org/x/crypto/argon2"
+)
+
+const (
+	argonTime    = 1
+	argonMemory  = 64 * 1024
+	argonThreads = 4
+	argonKeyLen  = 32
+	argonSaltLen = 16
+)
+
+func HashPassword(password string) (string, error) {
+	if len(password) < 8 {
+		return "", ErrPasswordTooShort
+	}
+	salt := make([]byte, argonSaltLen)
+	if _, err := rand.Read(salt); err != nil {
+		return "", err
+	}
+	hash := argon2.IDKey([]byte(password), salt, argonTime, argonMemory, argonThreads, argonKeyLen)
+	b64Salt := base64.RawStdEncoding.EncodeToString(salt)
+	b64Hash := base64.RawStdEncoding.EncodeToString(hash)
+	return fmt.Sprintf("$argon2id$v=%d$m=%d,t=%d,p=%d$%s$%s",
+		argon2.Version, argonMemory, argonTime, argonThreads, b64Salt, b64Hash), nil
+}
+
+func VerifyPassword(encoded, password string) (bool, error) {
+	parts := strings.Split(encoded, "$")
+	if len(parts) != 6 || parts[1] != "argon2id" {
+		return false, errors.New("invalid password hash format")
+	}
+	var version int
+	if _, err := fmt.Sscanf(parts[2], "v=%d", &version); err != nil {
+		return false, err
+	}
+	var memory, timeCost uint32
+	var threads uint8
+	if _, err := fmt.Sscanf(parts[3], "m=%d,t=%d,p=%d", &memory, &timeCost, &threads); err != nil {
+		return false, err
+	}
+	salt, err := base64.RawStdEncoding.DecodeString(parts[4])
+	if err != nil {
+		return false, err
+	}
+	want, err := base64.RawStdEncoding.DecodeString(parts[5])
+	if err != nil {
+		return false, err
+	}
+	got := argon2.IDKey([]byte(password), salt, timeCost, memory, threads, uint32(len(want)))
+	return subtle.ConstantTimeCompare(want, got) == 1, nil
+}

apps/api/internal/auth/password_reset.go

@@ -0,0 +1,173 @@
+package auth
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5"
+)
+
+// DefaultPasswordResetTTL is the self-serve reset link lifetime.
+const DefaultPasswordResetTTL = time.Hour
+
+// PasswordResetIssue is returned once when a reset token is created (plaintext token for email only).
+type PasswordResetIssue struct {
+	UserID uuid.UUID
+	Email  string
+	Token  string
+}
+
+// IssuePasswordReset creates a durable hashed reset token for an active user with a deliverable email.
+// Unknown, inactive, and synthetic @legacy.local addresses return ErrUserNotFound / ErrSyntheticEmail
+// so callers can respond opaquely without enumeration.
+func (s *Service) IssuePasswordReset(ctx context.Context, email string, ttl time.Duration) (PasswordResetIssue, error) {
+	email = strings.ToLower(strings.TrimSpace(email))
+	if email == "" {
+		return PasswordResetIssue{}, ErrEmailRequired
+	}
+	if IsSyntheticLegacyEmail(email) {
+		return PasswordResetIssue{}, ErrSyntheticEmail
+	}
+	if ttl <= 0 {
+		ttl = DefaultPasswordResetTTL
+	}
+
+	var (
+		userID   uuid.UUID
+		isActive bool
+	)
+	err := s.Pool.QueryRow(ctx, `
+		SELECT id, is_active
+		FROM users
+		WHERE lower(email) = $1`, email).Scan(&userID, &isActive)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return PasswordResetIssue{}, ErrUserNotFound
+	}
+	if err != nil {
+		return PasswordResetIssue{}, err
+	}
+	if !isActive {
+		return PasswordResetIssue{}, ErrUserNotFound
+	}
+
+	token, err := RandomToken(24)
+	if err != nil {
+		return PasswordResetIssue{}, err
+	}
+	expiresAt := time.Now().UTC().Add(ttl)
+
+	tx, err := s.Pool.Begin(ctx)
+	if err != nil {
+		return PasswordResetIssue{}, err
+	}
+	defer tx.Rollback(ctx)
+
+	// Invalidate prior unused tokens so only the latest link works.
+	if _, err := tx.Exec(ctx, `
+		UPDATE password_reset_tokens
+		SET expires_at = least(expires_at, now())
+		WHERE user_id = $1 AND consumed_at IS NULL AND expires_at > now()`, userID); err != nil {
+		return PasswordResetIssue{}, err
+	}
+
+	if _, err := tx.Exec(ctx, `
+		INSERT INTO password_reset_tokens (user_id, token_hash, expires_at)
+		VALUES ($1, $2, $3)`, userID, HashInviteToken(token), expiresAt); err != nil {
+		return PasswordResetIssue{}, err
+	}
+	if err := tx.Commit(ctx); err != nil {
+		return PasswordResetIssue{}, err
+	}
+
+	return PasswordResetIssue{UserID: userID, Email: email, Token: token}, nil
+}
+
+// ResetPasswordWithToken consumes a one-time reset token and sets a new password
+// regardless of must_set_password (dedicated reset path — not SetPassword / ForceSetPassword).
+func (s *Service) ResetPasswordWithToken(ctx context.Context, rawToken, password string) error {
+	rawToken = strings.TrimSpace(rawToken)
+	if rawToken == "" {
+		return ErrTokenInvalid
+	}
+	passwordHash, err := HashPassword(password)
+	if err != nil {
+		return err
+	}
+
+	tx, err := s.Pool.Begin(ctx)
+	if err != nil {
+		return err
+	}
+	defer tx.Rollback(ctx)
+
+	var (
+		tokenID    uuid.UUID
+		userID     uuid.UUID
+		expiresAt  time.Time
+		consumedAt *time.Time
+	)
+	err = tx.QueryRow(ctx, `
+		SELECT id, user_id, expires_at, consumed_at
+		FROM password_reset_tokens
+		WHERE token_hash = $1
+		FOR UPDATE`, HashInviteToken(rawToken)).Scan(&tokenID, &userID, &expiresAt, &consumedAt)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return ErrTokenInvalid
+	}
+	if err != nil {
+		return err
+	}
+	if consumedAt != nil || !expiresAt.After(time.Now().UTC()) {
+		return ErrTokenInvalid
+	}
+
+	var isActive bool
+	err = tx.QueryRow(ctx, `SELECT is_active FROM users WHERE id = $1 FOR UPDATE`, userID).Scan(&isActive)
+	if errors.Is(err, pgx.ErrNoRows) || (err == nil && !isActive) {
+		return ErrTokenInvalid
+	}
+	if err != nil {
+		return err
+	}
+
+	ct, err := tx.Exec(ctx, `
+		UPDATE users
+		SET password_hash = $2,
+		    must_set_password = false,
+		    session_version = session_version + 1,
+		    updated_at = now()
+		WHERE id = $1 AND is_active = true`, userID, passwordHash)
+	if isUndefinedColumn(err) {
+		// Pre-042 DBs: still reset password; session revoke requires session_version migration.
+		ct, err = tx.Exec(ctx, `
+			UPDATE users
+			SET password_hash = $2, must_set_password = false, updated_at = now()
+			WHERE id = $1 AND is_active = true`, userID, passwordHash)
+	}
+	if err != nil {
+		return err
+	}
+	if ct.RowsAffected() == 0 {
+		return ErrTokenInvalid
+	}
+
+	if _, err := tx.Exec(ctx, `
+		UPDATE password_reset_tokens
+		SET consumed_at = now()
+		WHERE id = $1`, tokenID); err != nil {
+		return err
+	}
+	// Expire any sibling unused tokens for this user.
+	if _, err := tx.Exec(ctx, `
+		UPDATE password_reset_tokens
+		SET expires_at = least(expires_at, now())
+		WHERE user_id = $1 AND id <> $2 AND consumed_at IS NULL AND expires_at > now()`,
+		userID, tokenID); err != nil {
+		return err
+	}
+
+	return tx.Commit(ctx)
+}

apps/api/internal/auth/password_reset_test.go

@@ -0,0 +1,28 @@
+package auth
+
+import (
+	"errors"
+	"testing"
+	"time"
+)
+
+func TestDefaultPasswordResetTTL(t *testing.T) {
+	t.Parallel()
+	if DefaultPasswordResetTTL != time.Hour {
+		t.Fatalf("DefaultPasswordResetTTL=%v want 1h", DefaultPasswordResetTTL)
+	}
+}
+
+func TestIssuePasswordResetRejectsSyntheticEmail(t *testing.T) {
+	t.Parallel()
+	s := &Service{} // no Pool — synthetic check must return before any DB use
+	for _, email := range []string{
+		"user_abc@legacy.local",
+		"  User_ABC@Legacy.Local ",
+	} {
+		_, err := s.IssuePasswordReset(t.Context(), email, 0)
+		if !errors.Is(err, ErrSyntheticEmail) {
+			t.Fatalf("email=%q err=%v want ErrSyntheticEmail", email, err)
+		}
+	}
+}

apps/api/internal/auth/password_test.go

@@ -0,0 +1,59 @@
+package auth
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestHashPasswordRejectsShort(t *testing.T) {
+	t.Parallel()
+	_, err := HashPassword("short")
+	if err == nil {
+		t.Fatal("expected error for password shorter than 8 characters")
+	}
+}
+
+func TestHashPasswordAndVerifyRoundTrip(t *testing.T) {
+	t.Parallel()
+	const password = "correct-horse-battery"
+	encoded, err := HashPassword(password)
+	if err != nil {
+		t.Fatalf("HashPassword: %v", err)
+	}
+	if !strings.HasPrefix(encoded, "$argon2id$") {
+		t.Fatalf("unexpected encoding prefix: %q", encoded)
+	}
+	ok, err := VerifyPassword(encoded, password)
+	if err != nil {
+		t.Fatalf("VerifyPassword: %v", err)
+	}
+	if !ok {
+		t.Fatal("expected password to verify")
+	}
+	ok, err = VerifyPassword(encoded, "wrong-password")
+	if err != nil {
+		t.Fatalf("VerifyPassword wrong: %v", err)
+	}
+	if ok {
+		t.Fatal("expected wrong password to fail verification")
+	}
+}
+
+func TestVerifyPasswordInvalidFormat(t *testing.T) {
+	t.Parallel()
+	_, err := VerifyPassword("not-a-hash", "anything12")
+	if err == nil {
+		t.Fatal("expected invalid format error")
+	}
+}
+
+func TestRandomTokenLength(t *testing.T) {
+	t.Parallel()
+	tok, err := RandomToken(24)
+	if err != nil {
+		t.Fatalf("RandomToken: %v", err)
+	}
+	if len(tok) != 48 {
+		t.Fatalf("expected hex length 48, got %d (%q)", len(tok), tok)
+	}
+}

apps/api/internal/auth/service.go

@@ -0,0 +1,491 @@
+package auth
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"errors"
+	"strings"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+var (
+	ErrInvalidCredentials = errors.New("invalid credentials")
+	ErrMustSetPassword    = errors.New("password_not_set")
+	ErrInviteInvalid      = errors.New("invite invalid or expired")
+	ErrPasswordAlreadySet = errors.New("password already set")
+	ErrUserExists         = errors.New("user already exists")
+)
+
+type Service struct {
+	Pool *pgxpool.Pool
+}
+
+type User struct {
+	ID              uuid.UUID `json:"id"`
+	Email           string    `json:"email"`
+	Name            *string   `json:"name,omitempty"`
+	MustSetPassword bool      `json:"must_set_password"`
+	IsPlatformAdmin bool      `json:"is_platform_admin"`
+	StaffRole       *string   `json:"staff_role,omitempty"`
+	IsActive        bool      `json:"is_active"`
+}
+
+type Membership struct {
+	ID        uuid.UUID `json:"id"`
+	CompanyID uuid.UUID `json:"company_id"`
+	UserID    uuid.UUID `json:"user_id"`
+	Role      string    `json:"role"`
+	Status    string    `json:"status"`
+}
+
+type Company struct {
+	ID   uuid.UUID `json:"id"`
+	Name string    `json:"name"`
+}
+
+type RegisterInput struct {
+	Email       string
+	Password    string
+	Name        string
+	CompanyName string
+}
+
+type LoginResult struct {
+	User      User      `json:"user"`
+	CompanyID uuid.UUID `json:"company_id"`
+	Companies []Company `json:"companies"`
+}
+
+func (s *Service) Register(ctx context.Context, in RegisterInput) (LoginResult, error) {
+	email := strings.ToLower(strings.TrimSpace(in.Email))
+	if email == "" || in.Password == "" || strings.TrimSpace(in.CompanyName) == "" {
+		return LoginResult{}, ErrRegisterFieldsRequired
+	}
+	hash, err := HashPassword(in.Password)
+	if err != nil {
+		return LoginResult{}, err
+	}
+
+	tx, err := s.Pool.Begin(ctx)
+	if err != nil {
+		return LoginResult{}, err
+	}
+	defer tx.Rollback(ctx)
+
+	var existing uuid.UUID
+	err = tx.QueryRow(ctx, `SELECT id FROM users WHERE email = $1`, email).Scan(&existing)
+	if err == nil {
+		return LoginResult{}, ErrUserExists
+	}
+	if !errors.Is(err, pgx.ErrNoRows) {
+		return LoginResult{}, err
+	}
+
+	var userID uuid.UUID
+	var name *string
+	if strings.TrimSpace(in.Name) != "" {
+		n := strings.TrimSpace(in.Name)
+		name = &n
+	}
+	err = tx.QueryRow(ctx, `
+		INSERT INTO users (email, name, password_hash, must_set_password)
+		VALUES ($1, $2, $3, false)
+		RETURNING id`, email, name, hash).Scan(&userID)
+	if err != nil {
+		return LoginResult{}, err
+	}
+
+	var companyID uuid.UUID
+	err = tx.QueryRow(ctx, `
+		INSERT INTO companies (name) VALUES ($1) RETURNING id`, strings.TrimSpace(in.CompanyName)).Scan(&companyID)
+	if err != nil {
+		return LoginResult{}, err
+	}
+
+	_, err = tx.Exec(ctx, `
+		INSERT INTO memberships (company_id, user_id, role, status)
+		VALUES ($1, $2, 'admin', 'active')`, companyID, userID)
+	if err != nil {
+		return LoginResult{}, err
+	}
+	_, err = tx.Exec(ctx, `
+		INSERT INTO company_settings (company_id) VALUES ($1)
+		ON CONFLICT DO NOTHING`, companyID)
+	if err != nil {
+		return LoginResult{}, err
+	}
+	_, err = tx.Exec(ctx, `
+		INSERT INTO credit_balances (company_id) VALUES ($1)
+		ON CONFLICT DO NOTHING`, companyID)
+	if err != nil {
+		return LoginResult{}, err
+	}
+
+	if err := tx.Commit(ctx); err != nil {
+		return LoginResult{}, err
+	}
+
+	user, err := s.GetUser(ctx, userID)
+	if err != nil {
+		return LoginResult{}, err
+	}
+	return LoginResult{
+		User:      user,
+		CompanyID: companyID,
+		Companies: []Company{{ID: companyID, Name: strings.TrimSpace(in.CompanyName)}},
+	}, nil
+}
+
+func (s *Service) Login(ctx context.Context, email, password string) (LoginResult, error) {
+	email = strings.ToLower(strings.TrimSpace(email))
+	var (
+		user User
+		hash *string
+	)
+	err := s.Pool.QueryRow(ctx, `
+		SELECT id, email, name, password_hash, must_set_password, is_platform_admin, staff_role, is_active
+		FROM users WHERE email = $1`, email).Scan(
+		&user.ID, &user.Email, &user.Name, &hash, &user.MustSetPassword, &user.IsPlatformAdmin, &user.StaffRole, &user.IsActive,
+	)
+	if isUndefinedColumn(err) {
+		err = s.Pool.QueryRow(ctx, `
+			SELECT id, email, name, password_hash, must_set_password, is_platform_admin, is_active
+			FROM users WHERE email = $1`, email).Scan(
+			&user.ID, &user.Email, &user.Name, &hash, &user.MustSetPassword, &user.IsPlatformAdmin, &user.IsActive,
+		)
+	}
+	if errors.Is(err, pgx.ErrNoRows) {
+		return LoginResult{}, ErrInvalidCredentials
+	}
+	if err != nil {
+		return LoginResult{}, err
+	}
+	if !user.IsActive {
+		return LoginResult{}, ErrInvalidCredentials
+	}
+	// Migrated / invite-pending accounts have no usable password until accept-invite or set-password.
+	if user.MustSetPassword || hash == nil || *hash == "" {
+		if user.MustSetPassword {
+			return LoginResult{}, ErrMustSetPassword
+		}
+		return LoginResult{}, ErrInvalidCredentials
+	}
+	ok, err := VerifyPassword(*hash, password)
+	if err != nil || !ok {
+		return LoginResult{}, ErrInvalidCredentials
+	}
+
+	companies, err := s.ListUserCompanies(ctx, user.ID)
+	if err != nil {
+		return LoginResult{}, err
+	}
+	var companyID uuid.UUID
+	if len(companies) > 0 {
+		companyID = companies[0].ID
+	}
+	_, _ = s.Pool.Exec(ctx, `UPDATE users SET last_login_at = now(), updated_at = now() WHERE id = $1`, user.ID)
+	return LoginResult{User: user, CompanyID: companyID, Companies: companies}, nil
+}
+
+func (s *Service) AcceptInvite(ctx context.Context, token, password, name string) (LoginResult, error) {
+	token = strings.TrimSpace(token)
+	if token == "" {
+		return LoginResult{}, ErrInviteInvalid
+	}
+	var (
+		inviteID, companyID uuid.UUID
+		email, role         string
+		expiresAt           time.Time
+		acceptedAt          *time.Time
+	)
+	// Prefer hashed lookup (at-rest); also accept legacy plaintext rows until they expire.
+	tokenHash := HashInviteToken(token)
+	err := s.Pool.QueryRow(ctx, `
+		SELECT id, company_id, email, role, expires_at, accepted_at
+		FROM invites
+		WHERE token = $1 OR token = $2
+		ORDER BY CASE WHEN token = $1 THEN 0 ELSE 1 END
+		LIMIT 1`, tokenHash, token).Scan(
+		&inviteID, &companyID, &email, &role, &expiresAt, &acceptedAt,
+	)
+	if errors.Is(err, pgx.ErrNoRows) || (acceptedAt != nil) || time.Now().After(expiresAt) {
+		return LoginResult{}, ErrInviteInvalid
+	}
+	if err != nil {
+		return LoginResult{}, err
+	}
+
+	tx, err := s.Pool.Begin(ctx)
+	if err != nil {
+		return LoginResult{}, err
+	}
+	defer tx.Rollback(ctx)
+
+	var userID uuid.UUID
+	var existingHash string
+	var mustSet bool
+	err = tx.QueryRow(ctx, `
+		SELECT id, password_hash, must_set_password FROM users WHERE email = $1`,
+		strings.ToLower(email)).Scan(&userID, &existingHash, &mustSet)
+	if errors.Is(err, pgx.ErrNoRows) {
+		hash, herr := HashPassword(password)
+		if herr != nil {
+			return LoginResult{}, herr
+		}
+		var n *string
+		if strings.TrimSpace(name) != "" {
+			nn := strings.TrimSpace(name)
+			n = &nn
+		}
+		err = tx.QueryRow(ctx, `
+			INSERT INTO users (email, name, password_hash, must_set_password)
+			VALUES ($1, $2, $3, false) RETURNING id`, strings.ToLower(email), n, hash).Scan(&userID)
+		if err != nil {
+			return LoginResult{}, err
+		}
+	} else if err != nil {
+		return LoginResult{}, err
+	} else if mustSet {
+		// Migration / first-password invites may set a password once.
+		hash, herr := HashPassword(password)
+		if herr != nil {
+			return LoginResult{}, herr
+		}
+		_, err = tx.Exec(ctx, `
+			UPDATE users SET password_hash = $2, must_set_password = false, updated_at = now()
+			WHERE id = $1 AND must_set_password = true`, userID, hash)
+		if err != nil {
+			return LoginResult{}, err
+		}
+	} else {
+		// Existing accounts keep their password; invitee must prove ownership.
+		ok, verr := VerifyPassword(existingHash, password)
+		if verr != nil || !ok {
+			return LoginResult{}, ErrInvalidCredentials
+		}
+	}
+
+	_, err = tx.Exec(ctx, `
+		INSERT INTO memberships (company_id, user_id, role, status)
+		VALUES ($1, $2, $3, 'active')
+		ON CONFLICT (company_id, user_id) DO UPDATE
+		SET role = CASE
+			WHEN memberships.role = 'admin' THEN memberships.role
+			ELSE EXCLUDED.role
+		END,
+		status = 'active', updated_at = now()`,
+		companyID, userID, role)
+	if err != nil {
+		return LoginResult{}, err
+	}
+	ct, err := tx.Exec(ctx, `
+		UPDATE invites SET accepted_at = now()
+		WHERE id = $1 AND accepted_at IS NULL`, inviteID)
+	if err != nil {
+		return LoginResult{}, err
+	}
+	if ct.RowsAffected() == 0 {
+		return LoginResult{}, ErrInviteInvalid
+	}
+	if err := tx.Commit(ctx); err != nil {
+		return LoginResult{}, err
+	}
+
+	user, err := s.GetUser(ctx, userID)
+	if err != nil {
+		return LoginResult{}, err
+	}
+	companies, err := s.ListUserCompanies(ctx, userID)
+	if err != nil {
+		return LoginResult{}, err
+	}
+	return LoginResult{User: user, CompanyID: companyID, Companies: companies}, nil
+}
+
+func (s *Service) SetPassword(ctx context.Context, userID uuid.UUID, password string) error {
+	hash, err := HashPassword(password)
+	if err != nil {
+		return err
+	}
+	// Only users flagged must_set_password may set via token/session bootstrap.
+	// This also makes HMAC set-password tokens single-use after success.
+	ct, err := s.Pool.Exec(ctx, `
+		UPDATE users
+		SET password_hash = $2,
+		    must_set_password = false,
+		    session_version = session_version + 1,
+		    updated_at = now()
+		WHERE id = $1 AND must_set_password = true`, userID, hash)
+	if isUndefinedColumn(err) {
+		ct, err = s.Pool.Exec(ctx, `
+			UPDATE users SET password_hash = $2, must_set_password = false, updated_at = now()
+			WHERE id = $1 AND must_set_password = true`, userID, hash)
+	}
+	if err != nil {
+		return err
+	}
+	if ct.RowsAffected() == 0 {
+		var exists bool
+		_ = s.Pool.QueryRow(ctx, `SELECT EXISTS(SELECT 1 FROM users WHERE id = $1)`, userID).Scan(&exists)
+		if exists {
+			return ErrPasswordAlreadySet
+		}
+		return ErrUserNotFound
+	}
+	return nil
+}
+
+// ChangePassword verifies the current password then sets a new one (in-app Settings).
+// Bumps session_version so other sessions are revoked; callers must re-stamp the cookie.
+func (s *Service) ChangePassword(ctx context.Context, userID uuid.UUID, currentPassword, newPassword string) error {
+	var (
+		hash            string
+		mustSetPassword bool
+		isActive        bool
+	)
+	err := s.Pool.QueryRow(ctx, `
+		SELECT password_hash, must_set_password, is_active
+		FROM users WHERE id = $1`, userID).Scan(&hash, &mustSetPassword, &isActive)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return ErrUserNotFound
+	}
+	if err != nil {
+		return err
+	}
+	if !isActive {
+		return ErrUserNotFound
+	}
+	if mustSetPassword {
+		return ErrMustSetPassword
+	}
+	ok, err := VerifyPassword(hash, currentPassword)
+	if err != nil {
+		return err
+	}
+	if !ok {
+		return ErrInvalidCredentials
+	}
+	newHash, err := HashPassword(newPassword)
+	if err != nil {
+		return err
+	}
+	ct, err := s.Pool.Exec(ctx, `
+		UPDATE users
+		SET password_hash = $2,
+		    must_set_password = false,
+		    session_version = session_version + 1,
+		    updated_at = now()
+		WHERE id = $1 AND is_active = true AND must_set_password = false`, userID, newHash)
+	if isUndefinedColumn(err) {
+		ct, err = s.Pool.Exec(ctx, `
+			UPDATE users
+			SET password_hash = $2, must_set_password = false, updated_at = now()
+			WHERE id = $1 AND is_active = true AND must_set_password = false`, userID, newHash)
+	}
+	if err != nil {
+		return err
+	}
+	if ct.RowsAffected() == 0 {
+		return ErrUserNotFound
+	}
+	return nil
+}
+
+// ForceSetPassword sets a password regardless of must_set_password (local/admin bootstrap).
+func (s *Service) ForceSetPassword(ctx context.Context, userID uuid.UUID, password string) error {
+	hash, err := HashPassword(password)
+	if err != nil {
+		return err
+	}
+	ct, err := s.Pool.Exec(ctx, `
+		UPDATE users SET password_hash = $2, must_set_password = false, updated_at = now()
+		WHERE id = $1 AND is_active = true`, userID, hash)
+	if err != nil {
+		return err
+	}
+	if ct.RowsAffected() == 0 {
+		return ErrUserNotFound
+	}
+	return nil
+}
+
+func (s *Service) GetUser(ctx context.Context, id uuid.UUID) (User, error) {
+	var u User
+	err := s.Pool.QueryRow(ctx, `
+		SELECT id, email, name, must_set_password, is_platform_admin, staff_role, is_active
+		FROM users WHERE id = $1`, id).Scan(
+		&u.ID, &u.Email, &u.Name, &u.MustSetPassword, &u.IsPlatformAdmin, &u.StaffRole, &u.IsActive,
+	)
+	if isUndefinedColumn(err) {
+		err = s.Pool.QueryRow(ctx, `
+			SELECT id, email, name, must_set_password, is_platform_admin, is_active
+			FROM users WHERE id = $1`, id).Scan(
+			&u.ID, &u.Email, &u.Name, &u.MustSetPassword, &u.IsPlatformAdmin, &u.IsActive,
+		)
+	}
+	return u, err
+}
+
+func (s *Service) ListUserCompanies(ctx context.Context, userID uuid.UUID) ([]Company, error) {
+	// Prefer Platform Demo sandbox when present, then richest tenant (products/feeds).
+	// A1 Slovenija wins remaining ties; accept old Local Demo Co rename as A1 alias.
+	const a1LegacyCompanyID = "97e1a309-3d23-4aa2-b518-8e8d7afdfec7"
+	rows, err := s.Pool.Query(ctx, `
+		SELECT c.id, c.name
+		FROM memberships m
+		JOIN companies c ON c.id = m.company_id
+		WHERE m.user_id = $1 AND m.status = 'active'
+		ORDER BY
+			CASE
+				WHEN lower(c.name) IN ('platform demo', 'demo') THEN 0
+				ELSE 1
+			END,
+			(SELECT COUNT(*) FROM processed_products p WHERE p.company_id = c.id) DESC,
+			(SELECT COUNT(*) FROM input_feeds f WHERE f.company_id = c.id) DESC,
+			CASE
+				WHEN lower(c.name) = 'a1 slovenija' THEN 0
+				WHEN lower(c.name) = 'local demo co' THEN 0
+				WHEN lower(COALESCE(c.legacy_company_id, '')) = lower($2) THEN 0
+				ELSE 1
+			END,
+			c.name`, userID, a1LegacyCompanyID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []Company
+	for rows.Next() {
+		var c Company
+		if err := rows.Scan(&c.ID, &c.Name); err != nil {
+			return nil, err
+		}
+		out = append(out, c)
+	}
+	return out, rows.Err()
+}
+
+func (s *Service) EnsureMembership(ctx context.Context, userID, companyID uuid.UUID) (Membership, error) {
+	var m Membership
+	err := s.Pool.QueryRow(ctx, `
+		SELECT id, company_id, user_id, role, status
+		FROM memberships
+		WHERE user_id = $1 AND company_id = $2 AND status = 'active'`,
+		userID, companyID).Scan(&m.ID, &m.CompanyID, &m.UserID, &m.Role, &m.Status)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return Membership{}, ErrNotCompanyMember
+	}
+	return m, err
+}
+
+func RandomToken(n int) (string, error) {
+	b := make([]byte, n)
+	if _, err := rand.Read(b); err != nil {
+		return "", err
+	}
+	return hex.EncodeToString(b), nil
+}

apps/api/internal/auth/session.go

@@ -0,0 +1,33 @@
+package auth
+
+import (
+	"net/http"
+	"time"
+
+	"github.com/alexedwards/scs/pgxstore"
+	"github.com/alexedwards/scs/v2"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+func NewSessionManager(pool *pgxpool.Pool, cookieName string, secure bool, idleHours int) *scs.SessionManager {
+	sm := scs.New()
+	sm.Store = pgxstore.New(pool)
+	sm.Lifetime = 7 * 24 * time.Hour
+	if idleHours <= 0 {
+		idleHours = 24
+	}
+	sm.IdleTimeout = time.Duration(idleHours) * time.Hour
+	sm.Cookie.Name = cookieName
+	sm.Cookie.HttpOnly = true
+	sm.Cookie.Secure = secure
+	sm.Cookie.SameSite = http.SameSiteLaxMode
+	sm.Cookie.Path = "/"
+	return sm
+}
+
+const (
+	SessionUserIDKey         = "user_id"
+	SessionCompanyIDKey      = "company_id"
+	SessionImpersonatorIDKey = "impersonator_id" // non-prod user switch: original admin/demo
+	SessionVersionKey        = "session_version" // must match users.session_version
+)

apps/api/internal/auth/session_test.go

@@ -0,0 +1,45 @@
+package auth
+
+import (
+	"net/http"
+	"testing"
+	"time"
+)
+
+func TestNewSessionManagerCookieFlags(t *testing.T) {
+	t.Parallel()
+
+	sm := NewSessionManager(nil, "descrybe_session", true, 12)
+	if sm.Cookie.Name != "descrybe_session" {
+		t.Fatalf("Name = %q", sm.Cookie.Name)
+	}
+	if !sm.Cookie.HttpOnly {
+		t.Fatal("session cookie must be HttpOnly")
+	}
+	if !sm.Cookie.Secure {
+		t.Fatal("secure=true must set Secure")
+	}
+	if sm.Cookie.SameSite != http.SameSiteLaxMode {
+		t.Fatalf("SameSite = %v, want Lax", sm.Cookie.SameSite)
+	}
+	if sm.Cookie.Path != "/" {
+		t.Fatalf("Path = %q, want /", sm.Cookie.Path)
+	}
+	if sm.IdleTimeout != 12*time.Hour {
+		t.Fatalf("IdleTimeout = %v, want 12h", sm.IdleTimeout)
+	}
+	if sm.Lifetime != 7*24*time.Hour {
+		t.Fatalf("Lifetime = %v, want 7d", sm.Lifetime)
+	}
+
+	insecure := NewSessionManager(nil, "descrybe_session", false, 0)
+	if insecure.Cookie.Secure {
+		t.Fatal("secure=false must not set Secure")
+	}
+	if !insecure.Cookie.HttpOnly {
+		t.Fatal("session cookie must remain HttpOnly")
+	}
+	if insecure.IdleTimeout != 24*time.Hour {
+		t.Fatalf("default IdleTimeout = %v, want 24h", insecure.IdleTimeout)
+	}
+}

apps/api/internal/auth/session_version.go

@@ -0,0 +1,39 @@
+package auth
+
+import (
+	"context"
+	"errors"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5"
+)
+
+// UserSessionState is the cookie-session gate (active flag + version for revoke-on-reset).
+type UserSessionState struct {
+	Active  bool
+	Version int
+}
+
+// UserSessionState loads is_active and session_version for RequireSession.
+// When session_version is not migrated yet, Version defaults to 0 (pre-hardening sessions keep working).
+func (s *Service) UserSessionState(ctx context.Context, userID uuid.UUID) (UserSessionState, error) {
+	var st UserSessionState
+	err := s.Pool.QueryRow(ctx, `
+		SELECT is_active, session_version
+		FROM users
+		WHERE id = $1`, userID).Scan(&st.Active, &st.Version)
+	if isUndefinedColumn(err) {
+		err = s.Pool.QueryRow(ctx, `
+			SELECT is_active
+			FROM users
+			WHERE id = $1`, userID).Scan(&st.Active)
+		st.Version = 0
+	}
+	if errors.Is(err, pgx.ErrNoRows) {
+		return UserSessionState{}, ErrUserNotFound
+	}
+	if err != nil {
+		return UserSessionState{}, err
+	}
+	return st, nil
+}

apps/api/internal/auth/session_version_test.go

@@ -0,0 +1,192 @@
+package auth
+
+import (
+	"os"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+func TestResetPasswordWithTokenBumpsSessionVersion(t *testing.T) {
+	dsn := strings.TrimSpace(os.Getenv("DATABASE_URL"))
+	if dsn == "" {
+		t.Skip("DATABASE_URL not set")
+	}
+	ctx := t.Context()
+	pg, err := pgxpool.New(ctx, dsn)
+	if err != nil {
+		t.Fatalf("postgres: %v", err)
+	}
+	t.Cleanup(pg.Close)
+
+	var ready bool
+	if err := pg.QueryRow(ctx, `
+		SELECT EXISTS (
+			SELECT 1 FROM information_schema.columns
+			WHERE table_schema = 'public' AND table_name = 'users' AND column_name = 'session_version'
+		)`).Scan(&ready); err != nil || !ready {
+		t.Skip("users.session_version missing — run goose up for 042_user_session_version")
+	}
+	if err := pg.QueryRow(ctx, `
+		SELECT EXISTS (
+			SELECT 1 FROM information_schema.tables
+			WHERE table_schema = 'public' AND table_name = 'password_reset_tokens'
+		)`).Scan(&ready); err != nil || !ready {
+		t.Skip("password_reset_tokens missing — run goose up for 041_password_reset_tokens")
+	}
+
+	svc := &Service{Pool: pg}
+	userID := uuid.New()
+	email := "session-ver-" + userID.String()[:8] + "@example.test"
+	hash, err := HashPassword("OldPassword123!")
+	if err != nil {
+		t.Fatalf("hash: %v", err)
+	}
+	_, err = pg.Exec(ctx, `
+		INSERT INTO users (id, email, name, password_hash, must_set_password, is_platform_admin, is_active, session_version)
+		VALUES ($1, $2, $3, $4, false, false, true, 3)`,
+		userID, email, "Session Ver", hash)
+	if err != nil {
+		t.Fatalf("seed user: %v", err)
+	}
+	t.Cleanup(func() {
+		cleanupCtx := t.Context()
+		_, _ = pg.Exec(cleanupCtx, `DELETE FROM password_reset_tokens WHERE user_id = $1`, userID)
+		_, _ = pg.Exec(cleanupCtx, `DELETE FROM users WHERE id = $1`, userID)
+	})
+
+	issue, err := svc.IssuePasswordReset(ctx, email, time.Hour)
+	if err != nil {
+		t.Fatalf("IssuePasswordReset: %v", err)
+	}
+	if err := svc.ResetPasswordWithToken(ctx, issue.Token, "NewPassword456!"); err != nil {
+		t.Fatalf("ResetPasswordWithToken: %v", err)
+	}
+
+	st, err := svc.UserSessionState(ctx, userID)
+	if err != nil {
+		t.Fatalf("UserSessionState: %v", err)
+	}
+	if !st.Active {
+		t.Fatal("expected active user")
+	}
+	if st.Version != 4 {
+		t.Fatalf("session_version=%d want 4 (bumped from 3)", st.Version)
+	}
+}
+
+func TestChangePasswordBumpsSessionVersion(t *testing.T) {
+	dsn := strings.TrimSpace(os.Getenv("DATABASE_URL"))
+	if dsn == "" {
+		t.Skip("DATABASE_URL not set")
+	}
+	ctx := t.Context()
+	pg, err := pgxpool.New(ctx, dsn)
+	if err != nil {
+		t.Fatalf("postgres: %v", err)
+	}
+	t.Cleanup(pg.Close)
+
+	var ready bool
+	if err := pg.QueryRow(ctx, `
+		SELECT EXISTS (
+			SELECT 1 FROM information_schema.columns
+			WHERE table_schema = 'public' AND table_name = 'users' AND column_name = 'session_version'
+		)`).Scan(&ready); err != nil || !ready {
+		t.Skip("users.session_version missing — run goose up for 042_user_session_version")
+	}
+
+	svc := &Service{Pool: pg}
+	userID := uuid.New()
+	email := "change-pw-" + userID.String()[:8] + "@example.test"
+	const oldPassword = "OldPassword123!"
+	hash, err := HashPassword(oldPassword)
+	if err != nil {
+		t.Fatalf("hash: %v", err)
+	}
+	_, err = pg.Exec(ctx, `
+		INSERT INTO users (id, email, name, password_hash, must_set_password, is_platform_admin, is_active, session_version)
+		VALUES ($1, $2, $3, $4, false, false, true, 2)`,
+		userID, email, "Change PW", hash)
+	if err != nil {
+		t.Fatalf("seed user: %v", err)
+	}
+	t.Cleanup(func() {
+		_, _ = pg.Exec(t.Context(), `DELETE FROM users WHERE id = $1`, userID)
+	})
+
+	if err := svc.ChangePassword(ctx, userID, "wrong-password", "NewPassword456!"); err != ErrInvalidCredentials {
+		t.Fatalf("wrong current: err=%v want ErrInvalidCredentials", err)
+	}
+
+	if err := svc.ChangePassword(ctx, userID, oldPassword, "short"); err != ErrPasswordTooShort {
+		t.Fatalf("short password: err=%v want ErrPasswordTooShort", err)
+	}
+
+	if err := svc.ChangePassword(ctx, userID, oldPassword, "NewPassword456!"); err != nil {
+		t.Fatalf("ChangePassword: %v", err)
+	}
+
+	st, err := svc.UserSessionState(ctx, userID)
+	if err != nil {
+		t.Fatalf("UserSessionState: %v", err)
+	}
+	if st.Version != 3 {
+		t.Fatalf("session_version=%d want 3 (bumped from 2)", st.Version)
+	}
+
+	var stored string
+	if err := pg.QueryRow(ctx, `SELECT password_hash FROM users WHERE id = $1`, userID).Scan(&stored); err != nil {
+		t.Fatalf("load hash: %v", err)
+	}
+	ok, err := VerifyPassword(stored, "NewPassword456!")
+	if err != nil || !ok {
+		t.Fatalf("new password verify ok=%v err=%v", ok, err)
+	}
+	ok, err = VerifyPassword(stored, oldPassword)
+	if err != nil || ok {
+		t.Fatal("old password should no longer verify")
+	}
+}
+
+func TestSetPasswordRejectsWhenAlreadySet(t *testing.T) {
+	dsn := strings.TrimSpace(os.Getenv("DATABASE_URL"))
+	if dsn == "" {
+		t.Skip("DATABASE_URL not set")
+	}
+	ctx := t.Context()
+	pg, err := pgxpool.New(ctx, dsn)
+	if err != nil {
+		t.Fatalf("postgres: %v", err)
+	}
+	t.Cleanup(pg.Close)
+
+	svc := &Service{Pool: pg}
+	userID := uuid.New()
+	email := "set-pw-" + userID.String()[:8] + "@example.test"
+	hash, err := HashPassword("AlreadySet123!")
+	if err != nil {
+		t.Fatalf("hash: %v", err)
+	}
+	_, err = pg.Exec(ctx, `
+		INSERT INTO users (id, email, name, password_hash, must_set_password, is_platform_admin, is_active)
+		VALUES ($1, $2, $3, $4, false, false, true)`,
+		userID, email, "Set PW", hash)
+	if err != nil {
+		t.Fatalf("seed user: %v", err)
+	}
+	t.Cleanup(func() {
+		_, _ = pg.Exec(t.Context(), `DELETE FROM users WHERE id = $1`, userID)
+	})
+
+	if err := svc.SetPassword(ctx, userID, "AnotherPass123!"); err != ErrPasswordAlreadySet {
+		t.Fatalf("SetPassword: err=%v want ErrPasswordAlreadySet", err)
+	}
+	if err := svc.ChangePassword(ctx, userID, "AlreadySet123!", "short"); err != ErrPasswordTooShort {
+		// ensure ChangePassword path still works for eligible users after SetPassword rejection
+		t.Fatalf("ChangePassword short: err=%v", err)
+	}
+}

apps/api/internal/auth/staff.go

@@ -0,0 +1,264 @@
+package auth
+
+import (
+	"context"
+	"errors"
+	"strings"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgconn"
+)
+
+// Platform staff roles (users.staff_role). Orthogonal to company membership roles.
+const (
+	StaffRoleAdmin        = "admin"
+	StaffRoleDeveloper    = "developer"
+	StaffRoleSupportStaff = "support_staff"
+)
+
+var (
+	ErrInvalidStaffRole  = errors.New("invalid staff_role")
+	ErrStaffUserNotFound = errors.New("user not found")
+)
+
+// StaffAccess is the resolved capability set for a platform staff user.
+type StaffAccess struct {
+	Role          string `json:"staff_role,omitempty"`
+	FullAdmin     bool   `json:"full_admin"`
+	SupportDesk   bool   `json:"support_desk"`
+	IsSupportOnly bool   `json:"is_support_only"`
+}
+
+// NormalizeStaffRole returns a known staff role or empty string.
+func NormalizeStaffRole(raw string) (string, error) {
+	role := strings.ToLower(strings.TrimSpace(raw))
+	switch role {
+	case "", StaffRoleAdmin, StaffRoleDeveloper, StaffRoleSupportStaff:
+		return role, nil
+	default:
+		return "", ErrInvalidStaffRole
+	}
+}
+
+// ResolveStaffRole returns the effective staff role per contract 04:
+// staff_role if set; else admin when is_platform_admin; else empty.
+func ResolveStaffRole(isPlatformAdmin bool, staffRole string) string {
+	role, _ := NormalizeStaffRole(staffRole)
+	if role != "" {
+		return role
+	}
+	if isPlatformAdmin {
+		return StaffRoleAdmin
+	}
+	return ""
+}
+
+// ResolveStaffAccess maps DB flags to capabilities.
+//
+// Rules (fail closed):
+//   - staff_role=support_staff → support desk only (never full admin), even if is_platform_admin.
+//   - staff_role=admin|developer → full admin + support desk.
+//   - staff_role empty + is_platform_admin → legacy full admin (backward compatible).
+//   - otherwise → no staff access.
+func ResolveStaffAccess(isPlatformAdmin bool, staffRole string) StaffAccess {
+	role := ResolveStaffRole(isPlatformAdmin, staffRole)
+	switch role {
+	case StaffRoleSupportStaff:
+		return StaffAccess{
+			Role:          StaffRoleSupportStaff,
+			FullAdmin:     false,
+			SupportDesk:   true,
+			IsSupportOnly: true,
+		}
+	case StaffRoleAdmin, StaffRoleDeveloper:
+		return StaffAccess{
+			Role:        role,
+			FullAdmin:   true,
+			SupportDesk: true,
+		}
+	default:
+		return StaffAccess{}
+	}
+}
+
+// StaffCapabilities lists platform capability keys for a resolved staff role.
+func StaffCapabilities(role string) []string {
+	switch role {
+	case StaffRoleAdmin, StaffRoleDeveloper:
+		return []string{
+			"staff.admin_shell",
+			"staff.support.queue",
+			"staff.support.reply",
+			"staff.support.assign",
+			"staff.users.read",
+			"staff.users.write",
+			"staff.analytics",
+			"staff.billing",
+			"staff.plans_features",
+			"staff.feature_gates",
+			"staff.settings",
+			"staff.jobs_stuck",
+			"staff.impersonate",
+			"staff.dev_password",
+		}
+	case StaffRoleSupportStaff:
+		return []string{
+			"staff.admin_shell",
+			"staff.support.queue",
+			"staff.support.reply",
+			"staff.support.assign",
+		}
+	default:
+		return nil
+	}
+}
+
+// GetStaffAccess loads is_platform_admin + staff_role for an active user.
+// Missing staff_role column (pre-migration) falls back to boolean-only admin.
+func (s *Service) GetStaffAccess(ctx context.Context, userID uuid.UUID) (StaffAccess, error) {
+	if s == nil || s.Pool == nil {
+		return StaffAccess{}, errors.New("auth service unavailable")
+	}
+	var isAdmin bool
+	var staffRole *string
+	err := s.Pool.QueryRow(ctx, `
+		SELECT is_platform_admin, staff_role
+		FROM users
+		WHERE id = $1 AND is_active = true`, userID,
+	).Scan(&isAdmin, &staffRole)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return StaffAccess{}, nil
+	}
+	if err != nil {
+		if isUndefinedColumn(err) {
+			ok, err2 := s.platformAdminFlag(ctx, userID)
+			if err2 != nil {
+				return StaffAccess{}, err2
+			}
+			return ResolveStaffAccess(ok, ""), nil
+		}
+		return StaffAccess{}, err
+	}
+	role := ""
+	if staffRole != nil {
+		role = *staffRole
+	}
+	return ResolveStaffAccess(isAdmin, role), nil
+}
+
+// platformAdminFlag reads users.is_platform_admin without staff_role resolution.
+func (s *Service) platformAdminFlag(ctx context.Context, userID uuid.UUID) (bool, error) {
+	var ok bool
+	err := s.Pool.QueryRow(ctx, `
+		SELECT is_platform_admin FROM users WHERE id = $1 AND is_active = true`, userID).Scan(&ok)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return false, nil
+	}
+	return ok, err
+}
+
+// StaffUser is a platform staff directory row.
+type StaffUser struct {
+	ID              uuid.UUID `json:"id"`
+	Email           string    `json:"email"`
+	Name            *string   `json:"name,omitempty"`
+	IsPlatformAdmin bool      `json:"is_platform_admin"`
+	StaffRole       *string   `json:"staff_role,omitempty"`
+	ResolvedRole    string    `json:"resolved_role"`
+	IsActive        bool      `json:"is_active"`
+}
+
+// ListStaffUsers returns active users with any platform staff access.
+func (s *Service) ListStaffUsers(ctx context.Context, limit, offset int) ([]StaffUser, error) {
+	if limit <= 0 || limit > 200 {
+		limit = 50
+	}
+	if offset < 0 {
+		offset = 0
+	}
+	rows, err := s.Pool.Query(ctx, `
+		SELECT id, email, name, is_platform_admin, staff_role, is_active
+		FROM users
+		WHERE is_active = true
+			AND (is_platform_admin = true OR staff_role IS NOT NULL)
+		ORDER BY coalesce(staff_role, ''), email
+		LIMIT $1 OFFSET $2`, limit, offset)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	out := make([]StaffUser, 0)
+	for rows.Next() {
+		var u StaffUser
+		if err := rows.Scan(&u.ID, &u.Email, &u.Name, &u.IsPlatformAdmin, &u.StaffRole, &u.IsActive); err != nil {
+			return nil, err
+		}
+		stored := ""
+		if u.StaffRole != nil {
+			stored = *u.StaffRole
+		}
+		u.ResolvedRole = ResolveStaffRole(u.IsPlatformAdmin, stored)
+		out = append(out, u)
+	}
+	return out, rows.Err()
+}
+
+// SetStaffRole assigns or clears a platform staff role.
+// Non-empty role sets is_platform_admin=true (contract invariant).
+// Empty role clears staff_role and is_platform_admin.
+func (s *Service) SetStaffRole(ctx context.Context, userID uuid.UUID, staffRole string) (StaffUser, error) {
+	role, err := NormalizeStaffRole(staffRole)
+	if err != nil {
+		return StaffUser{}, err
+	}
+	var (
+		u      StaffUser
+		stored *string
+	)
+	if role == "" {
+		err = s.Pool.QueryRow(ctx, `
+			UPDATE users
+			SET staff_role = NULL, is_platform_admin = false, updated_at = now()
+			WHERE id = $1 AND is_active = true
+			RETURNING id, email, name, is_platform_admin, staff_role, is_active`, userID,
+		).Scan(&u.ID, &u.Email, &u.Name, &u.IsPlatformAdmin, &stored, &u.IsActive)
+	} else {
+		err = s.Pool.QueryRow(ctx, `
+			UPDATE users
+			SET staff_role = $2, is_platform_admin = true, updated_at = now()
+			WHERE id = $1 AND is_active = true
+			RETURNING id, email, name, is_platform_admin, staff_role, is_active`, userID, role,
+		).Scan(&u.ID, &u.Email, &u.Name, &u.IsPlatformAdmin, &stored, &u.IsActive)
+	}
+	if errors.Is(err, pgx.ErrNoRows) {
+		return StaffUser{}, ErrStaffUserNotFound
+	}
+	if err != nil {
+		return StaffUser{}, err
+	}
+	u.StaffRole = stored
+	storedRole := ""
+	if stored != nil {
+		storedRole = *stored
+	}
+	u.ResolvedRole = ResolveStaffRole(u.IsPlatformAdmin, storedRole)
+	return u, nil
+}
+
+// IsAssignableSupportStaff reports whether userID may be set as a ticket assignee.
+func (s *Service) IsAssignableSupportStaff(ctx context.Context, userID uuid.UUID) (bool, error) {
+	access, err := s.GetStaffAccess(ctx, userID)
+	if err != nil {
+		return false, err
+	}
+	return access.SupportDesk, nil
+}
+
+func isUndefinedColumn(err error) bool {
+	var pgErr *pgconn.PgError
+	if errors.As(err, &pgErr) {
+		return pgErr.Code == "42703"
+	}
+	return false
+}

apps/api/internal/auth/staff_role_defaults.go

@@ -0,0 +1,92 @@
+package auth
+
+import (
+	"strings"
+)
+
+// StaffRoleFromPlatformAdmin maps the legacy boolean gate onto staff roles.
+// Until a dedicated staff_role column exists: platform admin → admin.
+func StaffRoleFromPlatformAdmin(isPlatformAdmin bool) string {
+	if isPlatformAdmin {
+		return StaffRoleAdmin
+	}
+	return ""
+}
+
+// supportStaffFeatureOff keys denied for support_staff (03-roles-matrix.json).
+var supportStaffFeatureOff = map[string]struct{}{
+	"billing.checkout":                {},
+	"billing.customer_portal":         {},
+	"billing.quick_upgrade":           {},
+	"capability.api_access":           {},
+	"capability.brand_ai_apply":       {},
+	"capability.byok":                 {},
+	"capability.campaign_ai":          {},
+	"capability.email_live_send":      {},
+	"capability.seo_ai_rewrite":       {},
+	"catalog.structured_descriptions": {},
+	"catalog.vector_categories":       {},
+	"dashboard.store_reconnect":       {},
+	"integrations.ai":                 {},
+	"integrations.ai.byok":            {},
+	"integrations.email":              {},
+	"integrations.email.blast":        {},
+	"integrations.email.test":         {},
+	"marketing.brand_ai_apply":        {},
+	"marketing.brand_kit":             {},
+	"marketing.campaigns":             {},
+	"marketing.campaigns.create":      {},
+	"marketing.campaigns.generate_ai": {},
+	"marketing.campaigns.send":        {},
+	"marketing.content_calendar":      {},
+	"marketing.reviews":               {},
+	"marketing.seo":                   {},
+	"marketing.seo.ai_rewrite":        {},
+	"marketing.seo.template_fill":     {},
+	"settings.api_keys":               {},
+	"settings.team_invite":            {},
+	"stores.hub":                      {},
+	"stores.shopify":                  {},
+	"stores.shopify.connection":       {},
+	"stores.shopify.orders":           {},
+	"stores.shopify.settings":         {},
+	"stores.woocommerce":              {},
+	"stores.woocommerce.attributes":   {},
+	"stores.woocommerce.categories":   {},
+	"stores.woocommerce.connection":   {},
+	"stores.woocommerce.orders":       {},
+	"stores.woocommerce.reviews":      {},
+	"stores.woocommerce.settings":     {},
+}
+
+// DefaultStaffRoleAllows reports the dashboard feature ceiling for a staff role
+// when acting in a tenant context (compose with plan_allows at resolve time).
+// admin / developer → all keys ON; support_staff → limited set; unknown → false.
+func DefaultStaffRoleAllows(role string, featureKey string) bool {
+	featureKey = strings.TrimSpace(featureKey)
+	normalized, _ := NormalizeStaffRole(role)
+	switch normalized {
+	case StaffRoleAdmin, StaffRoleDeveloper:
+		return true
+	case StaffRoleSupportStaff:
+		_, denied := supportStaffFeatureOff[featureKey]
+		return !denied
+	default:
+		return false
+	}
+}
+
+// StaffRoleAllowsAdminRoute is the platform console ceiling (not feature keys).
+// Per contract 04: support_staff → /admin/support only; admin|developer → all.
+func StaffRoleAllowsAdminRoute(role string, route string) bool {
+	route = strings.ToLower(strings.TrimSpace(route))
+	normalized, _ := NormalizeStaffRole(role)
+	switch normalized {
+	case StaffRoleAdmin, StaffRoleDeveloper:
+		return true
+	case StaffRoleSupportStaff:
+		return strings.HasPrefix(route, "/admin/support")
+	default:
+		return false
+	}
+}