Runbooks

Operational procedures for common situations.

Deploy the web app

cd apps/web && npx vercel --prod

GitHub auto-deploy is unreliable — always deploy via CLI. Verify with the health check:

curl -s https://app.tryvio.ai/api/health   # expect 200 {"status":"ok"}

A merchant’s billing UI looks wrong

The /billing page self-reconciles against Shopify on every load. If a merchant reports a stuck state, have them reload /billing. To inspect: check app_logs (billing.reconciled_from_shopify, billing.no_active_subscription).

Reset a store’s usage / grant relief

Admin → Merchants → expand the store:

Reset usage — zeroes try_ons_used + overage_pending.
Grant credit — issues a Shopify app credit.
★ Custom plan — create a tailored subscription (sends a confirmation URL).

Debug a stuck generation

Find the session in tryon_sessions / the job in tryon_provider_jobs (external task id).
Check the provider snapshot via getTaskSnapshot(taskId).
KIE results land on tempfile.aiquickdraw.com; the callback persists to Supabase Storage. If the callback never fired, the client keeps polling try-on-status.

The landing live demo is failing

Confirm the demo garment images resolve: https://app.tryvio.ai/landing/demo/<id>.jpg.
/api/demo/try-on has an in-memory per-IP cap (12/hr per warm instance) — not the issue for normal traffic.
It does not touch the demo store; check app_logs demo.tryon.*.

Read demo leads / contact inquiries

Admin → Demo Leads (CSV export) and Inquiries tabs. Both are rows in captured_emails filtered by source.

Rotate a key

Update the value in Vercel env (tryvio-shopify project) → redeploy (vercel --prod). For TOKEN_ENCRYPTION_KEY, rotating invalidates stored tokens — avoid unless necessary.

Deploy docs

cd apps/docs && npx vercel --prod --scope mihogv-1894s-projects           # public
cd apps/docs-internal && npx vercel --prod --scope mihogv-1894s-projects  # internal

Env Vars