@luanpdd/kit-mcp 1.7.0 → 1.9.0

package/kit/skills/supabase-realtime/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: supabase-realtime
+description: Use ao implementar Realtime — broadcast com private:true, naming scope:entity:id, RLS sobre realtime.messages, removeChannel cleanup, migrar de postgres_changes.
+---
+
+# Supabase — Realtime
+
+## Quando usar
+
+LLM carrega esta skill quando implementar features Realtime em Supabase (chat, presence, notifications, live dashboards). Trigger phrases:
+
+- "Supabase Realtime", "broadcast", "presence"
+- "subscrever a mudanças no banco em tempo real"
+- "WebSocket Supabase"
+- "migrar postgres_changes para broadcast"
+- "RLS realtime.messages"
+- "channel state", "removeChannel"
+
+## Regras absolutas
+
+- **Use `broadcast` por default** — `postgres_changes` é pattern legado (single-threaded, não escala). **Migrar para broadcast** em features novas.
+- **`private: true`** em todos os canais novos — exige autenticação + RLS sobre `realtime.messages`. Default em produção 2026.
+- **Naming canônico `scope:entity:id`** — ex: `room:messages:abc123`, `user:notifications:xyz789`, `org:announcements:org_42`.
+- **Eventos em `entity_action`** — ex: `message_inserted`, `task_updated`, `presence_joined`.
+- **`removeChannel` no cleanup obrigatório** — chamar `supabase.removeChannel(channel)` em `useEffect return` ou equivalente. Sem cleanup, memory leak + stale state (anti-pitfall B1).
+- **State checking antes de subscribe** — `if (channel.state === 'joined') return;` evita double-subscribe.
+- **RLS sobre `realtime.messages`** — SELECT (read) e INSERT (write) policies separadas, com index nas colunas usadas.
+- **Use Presence com moderação** — apenas para online status / cursors colaborativos, não para listas de objects (use queries normais).
+- Realtime tem **retry built-in** — log `status` no callback do `subscribe` mas não implementar retry manual.
+
+## Patterns canônicos
+
+### Subscribe via broadcast — client com cleanup
+
+```ts
+// PT-BR: subscrição típica em Client Component
+'use client'
+import { useEffect, useState } from 'react'
+import { createClient } from '@/utils/supabase/client'
+
+export function ChatRoom({ roomId }: { roomId: string }) {
+  const supabase = createClient()
+  const [messages, setMessages] = useState<Message[]>([])
+
+  useEffect(() => {
+    const channel = supabase
+      .channel(`room:messages:${roomId}`, { config: { private: true } })
+      .on('broadcast', { event: 'message_inserted' }, ({ payload }) => {
+        setMessages((prev) => [...prev, payload as Message])
+      })
+      .subscribe((status) => {
+        if (status === 'SUBSCRIBED') console.log('joined channel')
+        if (status === 'CHANNEL_ERROR') console.error('channel error')
+      })
+
+    // PT-BR: cleanup obrigatório — sem isso, memory leak
+    return () => {
+      supabase.removeChannel(channel)
+    }
+  }, [roomId, supabase])
+
+  return <ul>{messages.map((m) => <li key={m.id}>{m.text}</li>)}</ul>
+}
+```
+
+### RLS sobre `realtime.messages`
+
+```sql
+-- PT-BR: SELECT policy permite ouvir broadcast em canal autenticado
+-- Granular: SELECT = read, INSERT = write — duas policies separadas
+create policy "auth_select_realtime_messages"
+  on realtime.messages
+  for select
+  to authenticated
+  using ((select auth.uid()) is not null);
+
+-- PT-BR: INSERT policy permite enviar broadcast
+create policy "auth_insert_realtime_messages"
+  on realtime.messages
+  for insert
+  to authenticated
+  with check ((select auth.uid()) is not null);
+
+-- PT-BR: index obrigatório (extension é a coluna usada por broadcast)
+create index if not exists realtime_messages_extension_idx
+  on realtime.messages (extension);
+```
+
+### DB trigger via `realtime.broadcast_changes`
+
+Para emitir broadcast quando linha de tabela muda (substitui `postgres_changes`):
+
+```sql
+-- PT-BR: trigger function emite broadcast no canal scope:entity:id
+create or replace function public.notify_message_insert()
+returns trigger
+language plpgsql
+security invoker
+set search_path = ''
+as $$
+begin
+  perform realtime.broadcast_changes(
+    'room:messages:' || new.room_id::text,    -- canal
+    'message_inserted',                        -- event name
+    'INSERT',                                  -- operation
+    'messages',                                -- table
+    'public',                                  -- schema
+    new,                                       -- new row
+    null                                       -- old row
+  );
+  return new;
+end;
+$$;
+
+create trigger messages_broadcast_on_insert
+  after insert on public.messages
+  for each row
+  execute function public.notify_message_insert();
+```
+
+### Presence — apenas para online status
+
+```ts
+// PT-BR: presence é sparingly — só para "quem está online"
+const channel = supabase
+  .channel(`room:${roomId}`, { config: { private: true } })
+  .on('presence', { event: 'sync' }, () => {
+    const state = channel.presenceState()
+    setOnlineUsers(Object.keys(state))
+  })
+  .subscribe(async (status) => {
+    if (status !== 'SUBSCRIBED') return
+    await channel.track({ user_id: userId, online_at: new Date().toISOString() })
+  })
+
+return () => {
+  supabase.removeChannel(channel)
+}
+```
+
+### Migrar de `postgres_changes` para `broadcast`
+
+```ts
+// ❌ PADRÃO LEGADO — postgres_changes
+const channel = supabase
+  .channel('messages_changes')
+  .on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'messages' }, callback)
+  .subscribe()
+
+// ✅ PADRÃO ATUAL — broadcast com trigger DB
+// 1. Criar trigger SQL `realtime.broadcast_changes` (ver pattern acima)
+// 2. Subscribe via broadcast no client:
+const channel = supabase
+  .channel(`room:messages:${roomId}`, { config: { private: true } })
+  .on('broadcast', { event: 'message_inserted' }, callback)
+  .subscribe()
+```
+
+## Anti-patterns
+
+### Anti-pattern 1: Canal sem `private: true`
+
+**Errado:**
+```ts
+const channel = supabase.channel('messages')                  // canal público
+  .on('broadcast', { event: 'msg' }, callback)
+  .subscribe()
+```
+
+**Por quê:** canal público — qualquer cliente recebe payload sem RLS. Em produção isso vaza dados (broadcast pode incluir info sensível).
+
+**Certo:**
+```ts
+const channel = supabase
+  .channel(`room:messages:${roomId}`, { config: { private: true } })
+  .on('broadcast', { event: 'message_inserted' }, callback)
+  .subscribe()
+```
+
+### Anti-pattern 2: Subscribe sem `removeChannel` no cleanup
+
+**Errado:**
+```tsx
+useEffect(() => {
+  const channel = supabase.channel('...').subscribe()
+  // ⚠ sem return — canal nunca limpo
+}, [])
+```
+
+**Por quê:** memory leak. Em SPA com navegação, canais antigos continuam recebendo eventos — UI fica em estado inconsistente. WebSocket connections crescem indefinidamente.
+
+**Certo:**
+```tsx
+useEffect(() => {
+  const channel = supabase.channel('...').subscribe()
+  return () => {
+    supabase.removeChannel(channel)
+  }
+}, [])
+```
+
+### Anti-pattern 3: `postgres_changes` em features novas
+
+**Errado:**
+```ts
+supabase.channel('changes')
+  .on('postgres_changes', { event: '*', schema: 'public', table: 'messages' }, callback)
+  .subscribe()
+```
+
+**Por quê:** `postgres_changes` é single-threaded em Realtime backend. Em escala (>100 connections, >1k events/sec), throughput cai drasticamente. Documentado em [Realtime Limits](https://supabase.com/docs/guides/realtime/limits).
+
+**Certo:** trigger DB com `realtime.broadcast_changes` + subscribe via `broadcast` (ver pattern "Migrar" acima).
+
+### Anti-pattern 4: Presence para listar objetos
+
+**Errado:**
+```ts
+// ⚠ usar presence para listar tasks ativas
+channel.on('presence', { event: 'sync' }, () => {
+  const tasks = Object.values(channel.presenceState())
+  setTasks(tasks)
+})
+```
+
+**Por quê:** Presence é projetado para "quem está online" — state efêmero ligado a connection. Para listas de objetos, use query normal + broadcast quando muda. Presence inflado degrada toda a infraestrutura Realtime do projeto.
+
+**Certo:** query SQL para `tasks` + broadcast em mudanças via trigger DB.
+
+## Ver também
+
+- [supabase-rls-policies](../supabase-rls-policies/SKILL.md) — RLS sobre `realtime.messages` (SELECT + INSERT separados)
+- [supabase-database-functions](../supabase-database-functions/SKILL.md) — trigger functions com `set search_path = ''`
+- [supabase-auth-ssr](../supabase-auth-ssr/SKILL.md) — autenticação que habilita canais `private: true`
+- [supabase-edge-functions](../supabase-edge-functions/SKILL.md) — Edge Functions disparando broadcast via `realtime.send`
+- [glossário](../_shared-supabase/glossary.md) — termos PT-BR↔EN

package/kit/skills/supabase-rls-policies/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: supabase-rls-policies
+description: Use ao criar/auditar RLS — sempre (select auth.uid()), policies separadas por operação, índices nas colunas, NUNCA user_metadata em autorização.
+---
+
+# Supabase — RLS Policies
+
+## Quando usar
+
+LLM carrega esta skill quando criar, auditar ou debugar Row Level Security em Supabase. Trigger phrases:
+
+- "criar policy RLS", "RLS policy", "row level security"
+- "policies separadas por operação"
+- "auth.uid()", "auth.jwt()"
+- "MFA enforcement", "AAL2"
+- "auditar segurança de tabela Supabase"
+
+## Regras absolutas
+
+**WARNING — REGRA #1 (segurança crítica):** **NUNCA** referencie `user_metadata` em policy de autorização. `user_metadata` é editável pelo cliente via `auth.updateUser({data: {...}})` — usuário pode auto-elevar `role: 'admin'` ou `plan: 'premium'`. Use **`app_metadata`** (set apenas via service_role) para roles/permissions.
+
+**REGRA #2 (performance crítica):** **SEMPRE** envolva `auth.uid()` em `(select auth.uid())`. Sem o wrapper, Postgres reavalia a função **uma vez por linha** — degrada queries com filtro RLS em **até 1000×**.
+
+**Outras regras:**
+
+- **`policies separadas por operação`** — uma `for select`, uma `for insert`, uma `for update`, uma `for delete`. **Nunca** `for all` cobrindo CRUD inteiro.
+- **`TO authenticated`** ou **`to anon`** sempre explícito — nunca deixar implícito (default `to public` é insecure).
+- `for select` e `for delete` usam **apenas `using`** (sem `with check`).
+- `for insert` usa **apenas `with check`** (sem `using`).
+- `for update` usa **`using` + `with check`** (using para qual linha pode ser atualizada, with check para qual estado a linha pode assumir).
+- Índice obrigatório nas colunas referenciadas pela policy: `create index on public.tasks (user_id);`. Sem index, scan full em cada query.
+- `permissive` é default e preferido. `restrictive` é raro e exige justificativa explícita.
+- Para MFA enforcement: `(auth.jwt()->>'aal')::text = 'aal2'` em policies que exigem 2FA ativo.
+
+## Patterns canônicos
+
+### SELECT — usuário lê apenas suas próprias linhas
+
+```sql
+-- política de SELECT com wrapper (select auth.uid()) obrigatório
+create policy "users_select_own_tasks"
+  on public.tasks
+  for select
+  to authenticated
+  using ((select auth.uid()) = user_id);
+
+-- index obrigatório (sem isso, scan full)
+create index tasks_user_id_idx on public.tasks (user_id);
+```
+
+### INSERT, UPDATE, DELETE separados
+
+```sql
+-- INSERT — usuário só pode criar linhas com user_id = ele mesmo
+create policy "users_insert_own_tasks"
+  on public.tasks
+  for insert
+  to authenticated
+  with check ((select auth.uid()) = user_id);
+
+-- UPDATE — restringe quais linhas (using) E qual estado novo (with check)
+create policy "users_update_own_tasks"
+  on public.tasks
+  for update
+  to authenticated
+  using ((select auth.uid()) = user_id)
+  with check ((select auth.uid()) = user_id);
+
+-- DELETE — apenas a coluna using (sem with check)
+create policy "users_delete_own_tasks"
+  on public.tasks
+  for delete
+  to authenticated
+  using ((select auth.uid()) = user_id);
+```
+
+### Role admin via `app_metadata`
+
+```sql
+-- segurança: app_metadata é set apenas via service_role (admin API)
+-- cliente NÃO pode mutá-lo
+create policy "admins_manage_all_tasks"
+  on public.tasks
+  for update
+  to authenticated
+  using (
+    (select auth.jwt()->'app_metadata'->>'role') = 'admin'
+  )
+  with check (
+    (select auth.jwt()->'app_metadata'->>'role') = 'admin'
+  );
+```
+
+### MFA enforcement (AAL2)
+
+```sql
+-- exigir 2FA ativo para acessar dados sensíveis
+create policy "mfa_required_for_billing"
+  on public.billing_records
+  for select
+  to authenticated
+  using (
+    (select (auth.jwt()->>'aal')::text) = 'aal2'
+    and (select auth.uid()) = user_id
+  );
+```
+
+## Anti-patterns
+
+### Anti-pattern 1: `auth.uid()` sem `(select)` wrapper
+
+**Errado:**
+```sql
+create policy "users_select_own_tasks"
+  on public.tasks
+  for select
+  to authenticated
+  using (auth.uid() = user_id);            -- sem (select) — re-executa por linha
+```
+
+**Por quê:** Postgres reavalia `auth.uid()` para cada linha sendo testada. Em tabela com 100k linhas, isso é 100k chamadas. O `(select)` permite Postgres executar **uma vez** e reusar — degradação de até **1000×** sem o wrapper. Documentado em [RLS Performance](https://supabase.com/docs/guides/troubleshooting/rls-performance-and-best-practices-Z5Jjwv).
+
+**Certo:**
+```sql
+using ((select auth.uid()) = user_id)
+```
+
+### Anti-pattern 2: `WARNING user_metadata` em autorização — privilege escalation
+
+**Errado:**
+```sql
+create policy "admins_manage_all"
+  on public.tasks
+  for update
+  to authenticated
+  using (
+    (auth.jwt()->'user_metadata'->>'role') = 'admin'   -- editável pelo cliente!
+  );
+```
+
+**Por quê:** o cliente pode chamar `supabase.auth.updateUser({ data: { role: 'admin' } })` e instantaneamente ganhar privilégios de admin. `user_metadata` é projetado para preferences do usuário (tema, idioma), não para autorização. Documentado em [Splinter linter 0015](https://supabase.github.io/splinter/0015_rls_references_user_metadata/).
+
+**Certo:** ver "Role admin via `app_metadata`" acima — `app_metadata` requer service_role para mutar.
+
+### Anti-pattern 3: `for all` em vez de policies granulares
+
+**Errado:**
+```sql
+create policy "users_manage_own_tasks"
+  on public.tasks
+  for all                                  -- cobre CRUD inteiro com mesma regra
+  to authenticated
+  using ((select auth.uid()) = user_id);
+```
+
+**Por quê:** semântica de `for all` mistura `using` (que controla SELECT/UPDATE/DELETE) com `with check` (que controla INSERT/UPDATE), levando a confusão. Em UPDATE você pode querer regras diferentes para "qual linha tocar" vs "qual estado novo". Granularidade explícita previne erros sutis.
+
+**Certo:** ver pattern com 4 policies separadas acima (SELECT, INSERT, UPDATE, DELETE).
+
+### Anti-pattern 4: Sem índice nas colunas da policy
+
+**Errado:**
+```sql
+-- policy referencia user_id mas não há index
+create policy "users_select_own_tasks" on public.tasks
+  for select to authenticated
+  using ((select auth.uid()) = user_id);
+
+-- (esqueceu) create index on public.tasks (user_id);
+```
+
+**Por quê:** cada query com filtro RLS força sequential scan. Em produção com 100k+ linhas, isso é lentidão crônica.
+
+**Certo:**
+```sql
+create index tasks_user_id_idx on public.tasks (user_id);
+```
+
+## Ver também
+
+- [supabase-database-functions](../supabase-database-functions/SKILL.md) — funções com `set search_path = ''` que respeitam RLS
+- [supabase-storage](../supabase-storage/SKILL.md) — RLS sobre `storage.objects` (multi-tenant path isolation)
+- [supabase-auth-ssr](../supabase-auth-ssr/SKILL.md) — autenticação que popula `auth.uid()`
+- [supabase-migrations](../supabase-migrations/SKILL.md) — migrations sempre com RLS habilitado em novas tabelas
+- [glossário](../_shared-supabase/glossary.md) — termos PT-BR↔EN + roles + comandos CLI

package/kit/skills/supabase-storage/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: supabase-storage
+description: Use ao integrar Storage — buckets públicos vs privados, signed URLs com expiration, RLS sobre storage.objects com multi-tenant path, image transforms, TUS uploads.
+---
+
+# Supabase — Storage
+
+## Quando usar
+
+LLM carrega esta skill quando trabalhar com upload, download, ou serve de arquivos via Supabase Storage. Trigger phrases:
+
+- "Supabase Storage", "upload de arquivo"
+- "signed URL", "createSignedUrl"
+- "bucket público vs privado"
+- "RLS storage.objects"
+- "multi-tenant arquivos"
+- "image transforms Supabase"
+- "TUS resumable upload"
+
+## Regras absolutas
+
+- **Bucket privado é default em produção** — apenas dados públicos (avatares públicos, marketing) vão em buckets públicos.
+- **Bucket público:** URL direta `getPublicUrl()` + servida via CDN (cache).
+- **Bucket privado:** apenas `signed URL` (`createSignedUrl()`) com `expiresIn` curto (60s downloads, 3600s imagens).
+- **`storage.objects`** — RLS sempre habilitada. Sem RLS, qualquer authenticated lê qualquer bucket privado.
+- **`multi-tenant path`** isolation — usar `auth.uid()` (ou `org_id`) como path prefix: `<user_id>/<filename>`. Validar em RLS via `(storage.foldername(name))[1] = (select auth.uid())::text`.
+- **Image transformations** apenas em buckets com transformation enabled (Pro plan+). Query params `?width=800&height=600&resize=contain`.
+- **Uploads grandes (> 6 MB):** use TUS resumable protocol (`uploadToSignedUrl` + chunked upload).
+- **Awareness de egress billing** — bucket público sem cache headers customizados pode disparar custo significativo. Use Smart CDN + TTL adequado.
+- **Não overwrite arquivos públicos** com mesmo nome — CDN cache fica stale. Use versionamento (`avatar-v2.jpg`) ou random suffix.
+
+## Patterns canônicos
+
+### RLS multi-tenant em `storage.objects`
+
+```sql
+-- PT-BR: usuário só vê arquivos sob seu próprio prefix de path
+-- path canônico: <user_id>/<filename> (ex: 550e8400-e29b-41d4-a716-446655440000/avatar.jpg)
+
+create policy "users_read_own_files"
+  on storage.objects for select to authenticated
+  using (
+    bucket_id = 'private-uploads'
+    and (storage.foldername(name))[1] = (select auth.uid())::text
+  );
+
+create policy "users_insert_own_files"
+  on storage.objects for insert to authenticated
+  with check (
+    bucket_id = 'private-uploads'
+    and (storage.foldername(name))[1] = (select auth.uid())::text
+  );
+
+create policy "users_update_own_files"
+  on storage.objects for update to authenticated
+  using (
+    bucket_id = 'private-uploads'
+    and (storage.foldername(name))[1] = (select auth.uid())::text
+  );
+
+create policy "users_delete_own_files"
+  on storage.objects for delete to authenticated
+  using (
+    bucket_id = 'private-uploads'
+    and (storage.foldername(name))[1] = (select auth.uid())::text
+  );
+```
+
+### Upload com path multi-tenant
+
+```ts
+// PT-BR: cliente — path sempre prefixado com user.id
+import { createClient } from '@/utils/supabase/client'
+
+async function uploadAvatar(file: File) {
+  const supabase = createClient()
+  const { data: { user } } = await supabase.auth.getUser()
+  if (!user) throw new Error('not authenticated')
+
+  // PT-BR: path = <user_id>/<filename>
+  const path = `${user.id}/avatar.jpg`
+
+  const { data, error } = await supabase.storage
+    .from('private-uploads')
+    .upload(path, file, {
+      cacheControl: '3600',
+      upsert: true,                   // PT-BR: sobrescreve se mesmo path
+    })
+
+  if (error) throw error
+  return data
+}
+```
+
+### Signed URL — download privado
+
+```ts
+// PT-BR: signed URL com expiração 1h
+const { data, error } = await supabase.storage
+  .from('private-uploads')
+  .createSignedUrl(`${userId}/avatar.jpg`, 3600)
+
+// data.signedUrl pode ser usado em <img src={data.signedUrl}> por 1h
+```
+
+### Image transformations (em bucket com transform habilitado)
+
+```ts
+// PT-BR: signed URL com transformação inline
+const { data } = await supabase.storage
+  .from('private-uploads')
+  .createSignedUrl(`${userId}/avatar.jpg`, 3600, {
+    transform: { width: 200, height: 200, resize: 'cover' },
+  })
+```
+
+### Public bucket — getPublicUrl + cache headers
+
+```ts
+// PT-BR: para bucket PÚBLICO apenas (não funciona em privado)
+const { data } = supabase.storage
+  .from('public-avatars')
+  .getPublicUrl('hero.jpg')
+
+// PT-BR: ao upload, set cacheControl alto para reduzir egress
+await supabase.storage
+  .from('public-avatars')
+  .upload('hero.jpg', file, {
+    cacheControl: '31536000',         // 1 ano — assets imutáveis
+    upsert: false,                    // não sobrescrever (versionar via path)
+  })
+```
+
+### TUS resumable upload (arquivos grandes)
+
+```ts
+// PT-BR: signed upload URL + TUS chunked upload (>6MB)
+import * as tus from 'npm:tus-js-client'
+
+async function uploadLarge(file: File, path: string) {
+  const supabase = createClient()
+  const { data, error } = await supabase.storage
+    .from('private-uploads')
+    .createSignedUploadUrl(path)
+  if (error) throw error
+
+  return new Promise((resolve, reject) => {
+    const upload = new tus.Upload(file, {
+      endpoint: data.signedUrl,
+      headers: { authorization: `Bearer ${data.token}` },
+      chunkSize: 6 * 1024 * 1024,     // 6 MB chunks
+      onError: reject,
+      onSuccess: () => resolve(upload.url),
+    })
+    upload.start()
+  })
+}
+```
+
+### Notas de futuro (alpha — não detalhar em produção)
+
+- **Vector Buckets** e **Analytics Buckets** existem em alpha (2026). Mencione apenas como existência se relevante; pattern canônico ainda mudando — não detalhar.
+
+## Anti-patterns
+
+### Anti-pattern 1: Path sem prefix de tenant
+
+**Errado:**
+```ts
+await supabase.storage.from('private-uploads').upload('avatar.jpg', file)
+```
+
+**Por quê:** path global — qualquer user sobrescreve `avatar.jpg`. RLS multi-tenant não consegue isolar.
+
+**Certo:**
+```ts
+const path = `${user.id}/avatar.jpg`
+await supabase.storage.from('private-uploads').upload(path, file)
+```
+
+### Anti-pattern 2: Bucket privado sem RLS em `storage.objects`
+
+**Errado:**
+```sql
+create bucket 'private-uploads';
+-- (esqueceu policies em storage.objects)
+```
+
+**Por quê:** sem RLS em `storage.objects`, qualquer `authenticated` lê arquivos do bucket — multi-tenancy quebrado.
+
+**Certo:** ver pattern "RLS multi-tenant" acima — 4 policies separadas (SELECT/INSERT/UPDATE/DELETE).
+
+### Anti-pattern 3: `getPublicUrl` em bucket privado
+
+**Errado:**
+```ts
+// PT-BR: bucket-id é privado
+const { data } = supabase.storage.from('private-uploads').getPublicUrl('x.jpg')
+// data.publicUrl retorna mas o URL não funciona (403)
+```
+
+**Por quê:** `getPublicUrl` só funciona em buckets marcados public. Em privado, retorna URL que sempre dá 403.
+
+**Certo:** use `createSignedUrl` com expiration:
+```ts
+const { data } = await supabase.storage
+  .from('private-uploads')
+  .createSignedUrl('x.jpg', 3600)
+// data.signedUrl funciona por 1h
+```
+
+### Anti-pattern 4: Overwrite de arquivo público com mesmo path
+
+**Errado:**
+```ts
+// PT-BR: hero.jpg público
+await supabase.storage.from('public').upload('hero.jpg', newFile, { upsert: true })
+// CDN cache antigo continua servindo old hero.jpg por horas/dias
+```
+
+**Por quê:** CDN cache pelo path. Overwrite não invalida cache; usuários veem versão antiga.
+
+**Certo:** versionar ou random suffix:
+```ts
+await supabase.storage.from('public').upload(`hero-${version}.jpg`, newFile)
+// ou: hero-<sha>.jpg, hero-<timestamp>.jpg
+```
+
+## Ver também
+
+- [supabase-rls-policies](../supabase-rls-policies/SKILL.md) — RLS sobre `storage.objects` + multi-tenant pattern
+- [supabase-auth-ssr](../supabase-auth-ssr/SKILL.md) — usuário autenticado obtém `auth.uid()` para path prefix
+- [supabase-edge-functions](../supabase-edge-functions/SKILL.md) — Edge Functions podem mediar uploads complexos
+- [glossário](../_shared-supabase/glossary.md) — termos PT-BR↔EN