ipix-supabase

name	ipix-supabase
description	iPix Supabase hub (project nvdlhrodvevgwdsneplk): schema, RLS, migrations, auth, edge functions, storage, Realtime, verify-rls. Consolidates edge-functions, generic Supabase SQL/RLS/migrations, the Supabase CLI, and Postgres performance best-practices into one skill with on-demand references. Use for ANY Supabase work in this repo. NOT for Mercur commerce tables or legacy Medellín/FashionOS edge functions.
version	1.4.0
paths	["supabase/**","**/*.sql","app/src/lib/supabase*","app/src/lib/onboarding.ts","src/lib/supabase*","src/services/profileService.ts"]

ipix-supabase — Supabase hub

Single entry point for all Supabase work on iPix / Lumina Studio. Combines iPix topic files + child skills + references/project-rules/.

Load child SKILL.md on demand — do not paste their bodies here.

---

Folded topics (load on demand from references/)

Consolidation note: the former standalone skills edge-functions, supabase, supabase-cli, and supabase-postgres-best-practices are now references/ inside this hub. Behavior preserved; only the packaging changed.

User intent	Reference
Start here — iPix project, PLT tables, remote-only, verify-rls	(this hub) SKILL.md + topic files (postgres.md, realtime.md, storage.md, …)
Deno edge functions, JWT, Gemini in functions	references/edge-functions/edge-functions.md + edge-functions.md + references/edge-functions/edge-functions-inventory.md — see Edge Functions reference index below
Generic migrations, RLS SQL, DB functions, schema, SQL style	references/supabase-core/supabase-core.md (+ MIGRATIONS/RLS-POLICIES/FUNCTIONS/SCHEMA/SQL-STYLE.md) + references/project-rules/
Supabase CLI workflows (supabase CLI, local/remote)	references/cli/cli.md
Query perf, indexes, connection pooling, EXPLAIN	references/postgres-best-practices.md → detail in references/postgres/ (already mirrored)

Edge Functions reference index (references/edge-functions/)

File	Topic	When to load
edge-functions.md	Entry point — Deno.serve, CORS, JWT, DB access	Always first for edge function work
architecture.md	Serverless at edge, global distribution, cold starts	Debugging performance or runtime behaviour
cli.md	supabase functions new/serve/deploy/invoke	Creating, serving locally, or deploying
Configuration.md	Per-function config.toml — JWT toggle, import maps	Function needs non-default auth or deploy opts
dependencies.md	npm / esm.sh / deno.land, import maps, vendoring	Adding or updating a package
development.md	Local dev — functions serve, env vars, Docker	Setting up or troubleshooting local dev
custom-routing.md	Multi-route functions, path/method matching	Consolidating actions into one function
secrets.md	supabase secrets set/list, default env vars	Adding API keys or sensitive config
testing.md	Deno.test — HTTP, auth, DB test patterns	Writing or debugging function tests
ai-models.md	Supabase AI API — embeddings, LLM inference	Adding AI/embedding calls inside a function

Routing decision tree

Supabase task in iPix
  ├─ Which project / table / MVP policy?         → this SKILL.md + topic files
  ├─ Edge function (Deno, CORS, Gemini)?          → references/edge-functions/edge-functions.md
  ├─ Migration, RLS policy, Postgres function?    → references/supabase-core/supabase-core.md + references/project-rules/
  ├─ Supabase CLI workflow?                       → references/cli/cli.md
  └─ Slow query, index, EXPLAIN, pool limits?     → references/postgres-best-practices.md + references/postgres/

---

When NOT to use

• Mercur catalog (products, orders, sellers) — lives on Mercur Postgres, not Supabase
• Auth0 / Clerk / Firebase as primary auth — iPix uses Supabase Auth (PLT-002)
• Raw Postgres without Supabase client, RLS, or Edge Functions in scope

Triggers

supabase, RLS, auth.uid, edge function, Deno.serve, verify_jwt, storage bucket, signed URL, migration, supabase-js, service role, publishable key, brands, brand_scores, ai_agent_logs, verify-rls, remote-only.

---

Project identity

Key	Value
Project ref	nvdlhrodvevgwdsneplk
Dashboard	https://supabase.com/dashboard/project/nvdlhrodvevgwdsneplk
Policy	Remote-only for MVP — do not run supabase start
Commerce	Mercur — never duplicate product/order tables in Supabase

Canonical ops: supabase/README.md
Roadmap & issue index: docs/linear/issues/README.md

MCP / CLI trust

1. Prefer Supabase CLI --linked for SQL and migration state.
2. npm run supabase:verify-rls after every RLS change (19 checks).
3. Cursor user-supabase MCP may show legacy Medellín/FashionOS objects — ignore unless MCP is confirmed on nvdlhrodvevgwdsneplk.
4. Use CLI when plugin MCP returns permission errors.

---

iPix MVP tables (PLT-001)

Table	Purpose
brands	Operator brand profiles (user_id, ai_profile jsonb)
brand_scores	DNA scores (score_type, score, details)
commerce_product_links	Supabase ↔ Mercur medusa_product_id
ai_agent_logs	Agent runs (duration_ms, tokens, model)
assets	+ brand_id, dna_score, dna_status, dna_pillars
profiles	PLT-002 sync with auth.users
shoots	Shoot metadata (legacy, still used)

Legacy FashionOS tables coexist on the shared project — do not extend them for iPix MVP without audit (SEC-001 / IPI-52 · issues README).

Full orientation: references/tables-overview.md

---

Repo coordinates

What	Where
Supabase client (canonical)	app/src/lib/supabase/server.ts, session.ts
Supabase client (legacy)	src/lib/supabase.ts — remove after IPI-89
Types	src/types/supabase.ts (regenerate: npm run supabase:types)
Auth UI	app/src/app/(marketing)/login, app/src/app/auth/callback/route.ts
Profile sync	app/src/lib/onboarding.ts (createOrgAndBrand) · legacy src/services/profileService.ts
Edge functions	supabase/functions/<name>/index.ts
Migrations	supabase/migrations/
RLS verify	scripts/verify-rls.mjs → npm run supabase:verify-rls
Client env	NEXT_PUBLIC_SUPABASE_* in app/ only (post–IPI-89)
Server secrets	SUPABASE_SERVICE_ROLE_KEY, GEMINI_API_KEY (edge/Mastra only)

---

Daily commands

cd /home/sk/ipix
export $(grep -v '^#' .env.local | xargs)

npm run supabase:verify
npm run supabase:verify-rls
npm run supabase:migrations
npm run supabase:types
npm run supabase:push    # after new migration SQL reviewed

New migrations (remote-only)

supabase migration new <name>
# edit supabase/migrations/<timestamp>_<name>.sql

# If db push blocked by orphan migration — see supabase/README.md:
supabase db query --linked --file supabase/migrations/<file>.sql
supabase migration repair --status applied <timestamp> --linked

npm run supabase:types
npm run supabase:verify-rls

IPI-126 / BI-OPS-002 gate: push 20260625000000_brand_scores_unique_update_rls.sql → verify-rls (includes brand_scores UPDATE probe) → onboarding smoke on /app/onboarding → marks IPI-46 Done. Run after IPI-46 code is on main; this is the remote apply slice of IPI-46 B3–B4. Tracker: IPI-126 · issues README.

IPI-26 / IPI-BI-003 (spec): After IPI-46 + IPI-126 Done — Postgres enum brand_intake_status (7 states on brands; HITL on brand_intake_drafts.status); 4 new tables + indexes; score_version/source on brand_scores; alter brand_intake_drafts RLS; extend verify-rls.mjs for all 5 tables; explicit Realtime publication + pg_publication_tables verify. Do not duplicate IPI-126 migration.

Do not rewrite applied remote history. PLT-010 (squash / local Docker) is deferred.

---

Path-scoped rules — references/project-rules/

Topic	File
Client usage, RLS mindset, schema habits	supabase-patterns.md
Migration file conventions	supabase-migrations.md
RLS policy SQL patterns	supabase-rls-policies.md
Postgres functions	supabase-database-functions.md
Edge Functions (Deno)	supabase-edge-functions.md
Realtime	supabase-realtime.md
SQL style	supabase-sql-style.md

---

Core principles

1. Database is source of truth. RLS enforces this — not frontend state.
2. Verify, don't assume. Run advisors + verify-rls before declaring done.
3. Service-role key never reaches the browser. Edge functions / CLI only. No VITE_*.
4. Every new iPix table has RLS. No exceptions in public.
5. (SELECT auth.uid()) not auth.uid() in RLS — cached per query.

---

Routing — read topic files on demand

User intent	Read
Auth, profiles, GoTrue, session	client-and-auth.md + references/auth/
Edge functions, Gemini, deploy	edge-functions.md + references/edge-functions/edge-functions.md + references/edge-functions/edge-functions-inventory.md
AI edge patterns	references/edge-functions/ai-edge-functions.md
Schema / table groups	references/tables-overview.md
Query perf, indexes, advisors	postgres.md + references/postgres-best-practices.md + references/postgres/
Realtime channels	realtime.md
Storage buckets, signed URLs	storage.md

---

iPix edge functions (as-built — post PR #3)

Function	Purpose
health	Liveness
edge-test	Authenticated Gemini smoke (replaces legacy gemini-ping)
brand-intelligence	URL → brand profile (Gemini + urlContext + responseSchema)
start-brand-crawl	Firecrawl v2 crawl job start (IPI-24)
firecrawl-webhook	Firecrawl signed webhook → brand_crawls / brand_crawl_results
audit-asset-dna	Image DNA scoring — not shipped (DNA-001 / AI-010)

Do not copy Medellín/mde edge functions from MCP inventory — different product.

After adding functions: update supabase/config.toml + references/edge-functions/edge-functions-inventory.md → run scripts/verify-edge-inventory.sh.

---

Storage (PLT-011 — Cloudinary, not Supabase Storage)

MVP decision: Cloudinary holds bytes; Supabase holds metadata in assets + optional cloudinary_assets.

• Folder: ipix/{user_id}/{brand_id}/{asset_id}
• Edge: cloudinary-sign (signed upload params), register-asset (persist row)
• Secrets: CLOUDINARY_* edge-only — see docs/supabase/secrets-inventory.md
• Spec: docs/linear/issues/IPI-30-PLT-011.md
• Do not create ipix-assets Supabase buckets for MVP unless explicitly re-approved

Legacy FashionOS storage buckets and shoot-scoped RLS remain — extend with brand-owner policies via forward migration.

---

Auth (PLT-002)

• Operator: app/src/app/(operator)/app/* — session via Supabase SSR (app/src/lib/supabase/server.ts, session.ts)
• Login: app/src/app/(marketing)/login · callback app/src/app/auth/callback/route.ts
• Legacy Vite: /login + ProtectedRoute in src/ — retire with IPI-89
• Google OAuth: signInWithOAuth({ provider: "google" }) with redirect to /app
• Prod redirect URLs: IPI-125

Auth references — references/auth/

File	When to load
architecture.md	Debugging auth flow, JWT issuance, GoTrue internals
google.md	Google OAuth setup, Google Cloud Console config, One Tap
facebook.md	Facebook OAuth setup, App Review, email permission
sessions.md	JWT expiry, refresh tokens, session limits, unexpected logouts
users.md	User object schema, RLS with auth.uid(), app_metadata vs user_metadata
Identities.md	Multiple identities per user, identity linking, anonymous users
nextjs.md	Auth setup for app/ Next.js operator hub (PKCE, cookie auth)

---

Universal security checklist

• user_metadata is user-editable — never authorize from it
• UPDATE needs SELECT RLS policy
• Storage upsert needs INSERT + SELECT + UPDATE policies
• Service role never in app/ or src/
• Extend scripts/verify-rls.mjs when adding tenant-scoped tables

---

Pre-ship checklist

• Migration applied on remote (repair if orphan blocks push)
• npm run supabase:types if schema changed
• npm run supabase:verify-rls passes
• No service role or Gemini key in client bundle
• Edge function CORS + JWT documented in Linear spec

---

Companion skills

• ipix-task-lifecycle — Linear issue steps + verifier probes
• gemini — Gemini in edge functions

Source of truth

Location	Role
.claude/skills/ipix-supabase/	The one Supabase skill — hub + iPix topic files + references/ (incl. folded edge-functions, supabase-core, cli, postgres-best-practices)

---

References (deep dives)

• references/postgres/ — query perf, indexes, RLS perf, locking
• references/storage/rls-policies.md
• references/realtime/rls-policy-cookbook.md
• references/supabase/skill-feedback.md

---

Exit conditions

• Routed to correct topic file(s)
• iPix project ref + remote-only policy respected
• RLS verify run after policy changes
• Inventory updated after edge function add/remove