@luanpdd/kit-mcp 1.7.0 → 1.8.1

package/kit/skills/supabase-edge-functions/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: supabase-edge-functions
+description: Use ao escrever Edge Functions — Deno + imports npm:/jsr: (NUNCA bare), Deno.serve, env vars pre-populadas, file writes APENAS em /tmp, EdgeRuntime.waitUntil.
+---
+
+# Supabase — Edge Functions (Deno)
+
+## Quando usar
+
+LLM carrega esta skill quando criar, editar ou debugar Supabase Edge Functions (Deno runtime). Trigger phrases:
+
+- "criar Edge Function", "Supabase functions"
+- "Deno + Supabase"
+- "supabase functions deploy"
+- "Edge Function background task"
+- "import npm: jsr: em Edge Function"
+
+## Regras absolutas
+
+- **Runtime é Deno**, não Node.js. Use APIs Deno (`Deno.serve`, `Deno.env`, `Deno.writeTextFile`).
+- **Imports SEMPRE com `npm:` ou `jsr:`** prefix. **NUNCA** bare specifiers (`import x from 'pkg'` falha em runtime).
+- **Use versão pinada** nos imports — `npm:hono@4.6.7`, `npm:@supabase/supabase-js@2`. Sem version, runtime resolve para latest e quebra em deploy.
+- **Env vars pre-populadas** (não definir manualmente):
+  - `SUPABASE_URL`
+  - `SUPABASE_PUBLISHABLE_KEYS` (anon key — para client-side context)
+  - `SUPABASE_SECRET_KEYS` (service role — server-side only)
+  - `SUPABASE_DB_URL` (conexão direta ao Postgres)
+- Para outros secrets, set via `supabase secrets set --env-file path/to/.env`.
+- **`Deno.serve`** é o entry point canônico. **Nunca** `addEventListener('fetch')` (deprecated) ou `serve` de `https://deno.land/std@0.168.0/http/server.ts` (não usar).
+- **File writes APENAS em `/tmp`** — qualquer outro path é read-only.
+- Para tarefas em background após resposta, use **`EdgeRuntime.waitUntil(promise)`**. Sem isso, função termina antes da promise.
+- Multi-rota com Hono ou Express deve **prefixar** todas as rotas com `/<function-name>` (ex: `/my-function/users`) — sem prefix, request 404 quando deployada.
+
+## Patterns canônicos
+
+### Função básica — Deno.serve + npm: import
+
+```ts
+// supabase/functions/hello/index.ts
+// PT-BR: imports versionados sempre com npm:
+import { createClient } from 'npm:@supabase/supabase-js@2'
+
+Deno.serve(async (req) => {
+  const supabase = createClient(
+    Deno.env.get('SUPABASE_URL')!,
+    Deno.env.get('SUPABASE_SECRET_KEYS')!   // service role server-side
+  )
+
+  const { data, error } = await supabase
+    .from('tasks')
+    .select('id, title')
+    .limit(10)
+
+  if (error) {
+    return new Response(JSON.stringify({ error: error.message }), {
+      status: 500,
+      headers: { 'Content-Type': 'application/json' },
+    })
+  }
+
+  return new Response(JSON.stringify(data), {
+    headers: { 'Content-Type': 'application/json' },
+  })
+})
+```
+
+### Background task com `EdgeRuntime.waitUntil`
+
+```ts
+// supabase/functions/audit-log/index.ts
+// PT-BR: responde rápido, processa pesado em background
+
+Deno.serve(async (req) => {
+  const body = await req.json()
+
+  // PT-BR: `waitUntil` mantém runtime alive até promise resolver
+  EdgeRuntime.waitUntil((async () => {
+    // PT-BR: file write apenas em /tmp
+    await Deno.writeTextFile(
+      `/tmp/audit-${Date.now()}.log`,
+      JSON.stringify(body)
+    )
+    // PT-BR: pode chamar APIs externas, gerar embeddings, etc.
+    await fetch('https://example.com/audit', {
+      method: 'POST',
+      body: JSON.stringify(body),
+    })
+  })())
+
+  // PT-BR: response volta imediatamente
+  return new Response('accepted', { status: 202 })
+})
+```
+
+### Multi-rota com Hono
+
+```ts
+// supabase/functions/api/index.ts
+// PT-BR: rotas prefixadas com /api (nome da function)
+import { Hono } from 'npm:hono@4.6.7'
+
+const app = new Hono().basePath('/api')
+
+app.get('/users', (c) => c.json({ users: [] }))
+app.get('/users/:id', (c) => c.json({ id: c.req.param('id') }))
+app.post('/users', async (c) => {
+  const body = await c.req.json()
+  return c.json({ created: body }, 201)
+})
+
+Deno.serve(app.fetch)
+```
+
+### Função usando JSR e Node built-in
+
+```ts
+// supabase/functions/hash/index.ts
+// PT-BR: imports do JSR + Node built-in (precisa node: prefix)
+import { encodeHex } from 'jsr:@std/encoding/hex'
+import { createHash } from 'node:crypto'
+
+Deno.serve(async (req) => {
+  const { text } = await req.json()
+  const hash = createHash('sha256').update(text).digest('hex')
+  return new Response(JSON.stringify({ hash }), {
+    headers: { 'Content-Type': 'application/json' },
+  })
+})
+```
+
+### Auth — service-role server-side
+
+```ts
+// supabase/functions/admin-action/index.ts
+// PT-BR: service-role bypassa RLS — apenas server-side
+import { createClient } from 'npm:@supabase/supabase-js@2'
+
+Deno.serve(async (req) => {
+  // PT-BR: extrair JWT do header Authorization e validar
+  const authHeader = req.headers.get('Authorization')
+  if (!authHeader?.startsWith('Bearer ')) {
+    return new Response('unauthorized', { status: 401 })
+  }
+
+  // PT-BR: client com service-role para operação privilegiada
+  const supabase = createClient(
+    Deno.env.get('SUPABASE_URL')!,
+    Deno.env.get('SUPABASE_SECRET_KEYS')!
+  )
+
+  // PT-BR: validar JWT e extrair user
+  const { data: { user }, error } = await supabase.auth.getUser(
+    authHeader.replace('Bearer ', '')
+  )
+  if (!user || error) return new Response('unauthorized', { status: 401 })
+
+  // PT-BR: agora pode operar com privilégios de service_role
+  await supabase.from('audit_log').insert({ user_id: user.id, action: 'admin_view' })
+
+  return new Response('ok')
+})
+```
+
+## Anti-patterns
+
+### Anti-pattern 1: Bare specifier sem `npm:`/`jsr:`
+
+**Errado:**
+```ts
+import { createClient } from '@supabase/supabase-js'      // ⚠ bare specifier
+```
+
+**Por quê:** Deno não resolve bare specifiers. Runtime falha em startup com erro `Module not found`.
+
+**Certo:**
+```ts
+import { createClient } from 'npm:@supabase/supabase-js@2'
+```
+
+### Anti-pattern 2: `Deno.writeTextFile` fora de `/tmp`
+
+**Errado:**
+```ts
+await Deno.writeTextFile('/data/audit.log', data)         // ⚠ filesystem read-only
+await Deno.writeTextFile('./local/x.log', data)           // ⚠ idem
+```
+
+**Por quê:** Edge Functions runtime tem filesystem read-only exceto `/tmp`. Writes fora de `/tmp` falham com `EACCES`.
+
+**Certo:**
+```ts
+await Deno.writeTextFile(`/tmp/audit-${Date.now()}.log`, data)
+```
+
+### Anti-pattern 3: Trabalho pesado inline na response
+
+**Errado:**
+```ts
+Deno.serve(async (req) => {
+  const body = await req.json()
+  await processHeavyJob(body)        // ⚠ trava response 30s+
+  await sendEmail(body)              // ⚠ idem
+  return new Response('done')
+})
+```
+
+**Por quê:** cliente espera resposta. Edge Functions têm timeout (default 60s). Falhas pontuais quebram UX.
+
+**Certo:** use `EdgeRuntime.waitUntil` para liberar resposta:
+```ts
+Deno.serve(async (req) => {
+  const body = await req.json()
+  EdgeRuntime.waitUntil((async () => {
+    await processHeavyJob(body)
+    await sendEmail(body)
+  })())
+  return new Response('accepted', { status: 202 })
+})
+```
+
+### Anti-pattern 4: Multi-rota sem prefix
+
+**Errado:**
+```ts
+const app = new Hono()                  // ⚠ sem basePath
+app.get('/users', handler)
+Deno.serve(app.fetch)                   // request a /users → 404 em produção
+```
+
+**Por quê:** quando deployado, URL é `https://<ref>.supabase.co/functions/v1/<name>/...`. Sem `basePath('/<name>')` no router, request a `/users` não casa.
+
+**Certo:**
+```ts
+const app = new Hono().basePath('/api')   // PT-BR: prefix com nome da function
+```
+
+## Ver também
+
+- [supabase-auth-ssr](../supabase-auth-ssr/SKILL.md) — clients usam `npm:@supabase/supabase-js`
+- [supabase-rls-policies](../supabase-rls-policies/SKILL.md) — service-role server-side bypassa RLS
+- [supabase-cron-queues](../supabase-cron-queues/SKILL.md) — Edge Functions invocadas por `pg_net.http_post`
+- [glossário](../_shared-supabase/glossary.md) — comandos CLI (`supabase functions deploy`)

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

@@ -0,0 +1,175 @@
+---
+name: supabase-migrations
+description: Use ao criar arquivos de migration Supabase — naming YYYYMMDDHHmmss_short.sql, header de metadados, RLS obrigatório em toda nova tabela, granular policies.
+---
+
+# Supabase — Migrations
+
+## Quando usar
+
+LLM carrega esta skill quando criar/editar arquivos em `supabase/migrations/`. Trigger phrases:
+
+- "criar migration Supabase", "supabase migration new"
+- "alterar schema do banco", "alter table"
+- "criar nova tabela em Postgres/Supabase"
+- "adicionar coluna a tabela existente"
+- "drop column / drop table" (operações destrutivas — exige cuidado extra)
+
+## Regras absolutas
+
+- **Naming canônico:** `YYYYMMDDHHmmss_short_description.sql` em UTC (ex: `20260506120000_create_tasks.sql`). Use `supabase migration new <name>` para gerar timestamp correto.
+- **Header de metadados** no topo de cada migration (block comment) descrevendo Migration / Created / Purpose / Affects.
+- **lowercase em todo SQL** (alinhado com `supabase-postgres-style`).
+- **Comentários copiosos** em comandos destrutivos: `drop table`, `drop column`, `alter table ... drop column`, `truncate`, `delete from` em massa. Comentário explica o porquê + impacto.
+- **`RLS` obrigatório em toda nova tabela** — `alter table public.<name> enable row level security;` no mesmo arquivo da criação.
+- **`granular policies`** — uma `for select`, uma `for insert`, uma `for update`, uma `for delete`. **Nunca** `for all`.
+- **`(select auth.uid())`** sempre wrapped (REGRA #1 de RLS).
+- **Index nas colunas referenciadas por RLS:** `create index on public.<table> (user_id);` no mesmo arquivo.
+- Idempotência onde possível: `create table if not exists`, `create index if not exists`. Migrations rodam em ordem mas tooling pode re-executar.
+- Migrations são **append-only**. Para reverter, criar nova migration que desfaz — nunca editar migration já aplicada.
+
+## Patterns canônicos
+
+### Criar tabela com RLS + policies granulares + index
+
+```sql
+/*
+  Migration: create_tasks
+  Created: 2026-05-06
+  Purpose: Cria tabela tasks com RLS habilitado e policies granulares por operação.
+  Affects: public.tasks (new), public.tasks policies (new — 4 policies)
+*/
+
+create table if not exists public.tasks (
+  id uuid primary key default gen_random_uuid(),
+  user_id uuid not null references auth.users (id) on delete cascade,
+  title text not null,
+  status text not null default 'todo',
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now()
+);
+
+alter table public.tasks enable row level security;
+
+-- granular policies: uma por operação por role
+create policy "users_select_own_tasks"
+  on public.tasks for select to authenticated
+  using ((select auth.uid()) = user_id);
+
+create policy "users_insert_own_tasks"
+  on public.tasks for insert to authenticated
+  with check ((select auth.uid()) = user_id);
+
+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);
+
+create policy "users_delete_own_tasks"
+  on public.tasks for delete to authenticated
+  using ((select auth.uid()) = user_id);
+
+-- index obrigatório nas colunas usadas pela policy
+create index if not exists tasks_user_id_idx on public.tasks (user_id);
+```
+
+### Adicionar coluna a tabela existente
+
+```sql
+/*
+  Migration: add_priority_to_tasks
+  Created: 2026-05-06
+  Purpose: Adiciona coluna priority (low/medium/high) a tasks com default low.
+  Affects: public.tasks (column added — non-destructive)
+*/
+
+alter table public.tasks
+  add column if not exists priority text not null default 'low';
+
+-- check constraint para enum-like
+alter table public.tasks
+  add constraint tasks_priority_check
+  check (priority in ('low', 'medium', 'high'));
+```
+
+### Operação destrutiva — drop column com comentário extensivo
+
+```sql
+/*
+  Migration: drop_legacy_subtitle_column
+  Created: 2026-05-06
+  Purpose: Remove coluna subtitle (deprecated em v3.0 — nunca foi usada em produção).
+  Affects: public.tasks (column dropped — DESTRUCTIVE)
+  Risk: Baixo — coluna nullable nunca populada (validado via select count(*) where subtitle is not null = 0).
+  Rollback: criar nova migration `add subtitle column` se necessário.
+*/
+
+-- DROP de coluna deprecated. Validado upstream: zero linhas com valor não-null.
+-- Operação destrutiva — irreversível sem backup.
+alter table public.tasks
+  drop column if exists subtitle;
+```
+
+## Anti-patterns
+
+### Anti-pattern 1: Criar tabela sem RLS
+
+**Errado:**
+```sql
+create table public.tasks (
+  id uuid primary key default gen_random_uuid(),
+  user_id uuid not null,
+  title text not null
+);
+-- esqueceu enable row level security
+```
+
+**Por quê:** sem RLS, tabela exposta ao role `anon` e `authenticated` sem filtro — qualquer cliente lê tudo. RLS habilitado sem policies bloqueia tudo (mais seguro como default que deixar aberto).
+
+**Certo:** sempre `alter table public.tasks enable row level security;` + policies granulares no mesmo arquivo.
+
+### Anti-pattern 2: `for all` em vez de granular policies
+
+**Errado:**
+```sql
+create policy "users_manage_tasks" on public.tasks
+  for all to authenticated
+  using ((select auth.uid()) = user_id);
+```
+
+**Por quê:** mistura `using` (controla SELECT/UPDATE/DELETE) com `with check` (controla INSERT/UPDATE) — em UPDATE você pode querer regras diferentes para "qual linha tocar" vs "qual estado novo".
+
+**Certo:** 4 policies separadas (uma por operação) — ver pattern "Criar tabela" acima.
+
+### Anti-pattern 3: `drop column` sem comentário
+
+**Errado:**
+```sql
+alter table public.tasks drop column legacy_field;
+```
+
+**Por quê:** futuros leitores não sabem por que a coluna foi removida; rollback fica difícil; risk não documentado.
+
+**Certo:** comentário no header explica Purpose + Affects + Risk + Rollback (ver pattern destrutivo acima).
+
+### Anti-pattern 4: `auth.uid()` sem `(select)` wrapper
+
+**Errado:**
+```sql
+using (auth.uid() = user_id)
+```
+
+**Por quê:** degradação 1000× em queries com filtro RLS (Postgres reavalia por linha).
+
+**Certo:**
+```sql
+using ((select auth.uid()) = user_id)
+```
+
+## Ver também
+
+- [supabase-postgres-style](../supabase-postgres-style/SKILL.md) — convenção de naming + style aplicada
+- [supabase-rls-policies](../supabase-rls-policies/SKILL.md) — granular policies + WARNING user_metadata
+- [supabase-database-functions](../supabase-database-functions/SKILL.md) — funções com `set search_path = ''`
+- [supabase-declarative-schema](../supabase-declarative-schema/SKILL.md) — workflow alternativo (declarative-first → diff)
+- [glossário](../_shared-supabase/glossary.md) — termos PT-BR↔EN + comandos CLI

package/kit/skills/supabase-pgvector-rag/SKILL.md

@@ -0,0 +1,253 @@
+---
+name: supabase-pgvector-rag
+description: Use ao implementar RAG com pgvector — create extension vector, dim consistente, HNSW vs IVFFlat, operadores <=>/<#>, RAG with permissions via RLS, chunking.
+---
+
+# Supabase — pgvector + RAG
+
+## Quando usar
+
+LLM carrega esta skill quando implementar embeddings, similarity search ou RAG (Retrieval-Augmented Generation) com Supabase. Trigger phrases:
+
+- "pgvector", "vector embeddings"
+- "RAG Supabase", "retrieval augmented generation"
+- "semantic search Postgres"
+- "HNSW vs IVFFlat"
+- "embedding dimension"
+- "match_documents function"
+
+## Regras absolutas
+
+- **Setup:** `create extension if not exists vector;` em migration ou `supabase/schemas/`.
+- **Dimension fixa por modelo** — defina `embedding vector(N)` com N = dim do modelo: 1536 (OpenAI ada-002), 768 (nomic-embed-text), 384 (all-MiniLM-L6-v2). Mismatch = silent fail ou matches aleatórios.
+- **Index obrigatório** — sem index, similarity search faz full scan e degrada drasticamente em > 10k linhas.
+- **`HNSW`** = default em 2026 — recall melhor, queries mais rápidas com mais data. Build mais lento.
+- **`IVFFlat`** = alternativa quando build time domina (datasets dinâmicos com re-build frequente). Recall menor.
+- **Distance operators canônicos:**
+  - **`<=>`** — cosine distance (mais comum em embeddings normalizados)
+  - **`<#>`** — negative inner product
+  - **`<->`** — L2 (euclidean) distance
+- **`RAG with permissions`** — combine similarity search com RLS na tabela source. Sem isso, retrieval vaza documents entre tenants.
+- **Chunking:** 200-500 tokens com overlap 10-20%. Chunks > 1k tokens degradam embeddings; < 100 perdem contexto.
+- **Embedding generation server-side** — geração via Edge Function ou worker (model API key não vai para client).
+
+## Patterns canônicos
+
+### Schema com RLS + HNSW index
+
+```sql
+-- PT-BR: extension uma vez por projeto
+create extension if not exists vector;
+
+-- PT-BR: documents com embedding e user_id para RAG with permissions
+create table public.documents (
+  id uuid primary key default gen_random_uuid(),
+  user_id uuid not null references auth.users (id) on delete cascade,
+  content text not null,                    -- PT-BR: chunk de texto (200-500 tokens)
+  embedding vector(1536) not null,          -- PT-BR: dim casa com modelo
+  metadata jsonb default '{}'::jsonb,
+  created_at timestamptz default now()
+);
+
+-- PT-BR: HNSW com cosine distance (default 2026)
+create index documents_embedding_hnsw_idx
+  on public.documents
+  using hnsw (embedding vector_cosine_ops);
+
+-- PT-BR: RLS — RAG with permissions
+alter table public.documents enable row level security;
+
+create policy "users_read_own_docs"
+  on public.documents for select to authenticated
+  using ((select auth.uid()) = user_id);
+
+create policy "users_insert_own_docs"
+  on public.documents for insert to authenticated
+  with check ((select auth.uid()) = user_id);
+
+create index documents_user_id_idx on public.documents (user_id);
+```
+
+### Função `match_documents` — RAG with permissions
+
+```sql
+create or replace function public.match_documents(
+  query_embedding vector(1536),
+  match_threshold float,
+  match_count int
+)
+returns table (
+  id uuid,
+  content text,
+  similarity float,
+  metadata jsonb
+)
+language plpgsql
+security invoker                            -- PT-BR: invoker → respeita RLS do caller
+set search_path = ''
+stable
+as $$
+begin
+  return query
+    select
+      d.id,
+      d.content,
+      1 - (d.embedding <=> query_embedding) as similarity,
+      d.metadata
+    from public.documents as d
+    where 1 - (d.embedding <=> query_embedding) > match_threshold
+    order by d.embedding <=> query_embedding
+    limit match_count;
+end;
+$$;
+```
+
+**Por que `security invoker`:** garante que a função só retorna documentos que o caller (usuário autenticado) tem permissão de ver via RLS. Sem RLS, qualquer caller via similarity recupera documents de outros tenants.
+
+### Uso da função do client
+
+```ts
+// PT-BR: gerar embedding (em Edge Function, server-side) e chamar match_documents
+const queryEmbedding = await embedQuery(userQuestion)   // dim 1536
+
+const { data: matches } = await supabase.rpc('match_documents', {
+  query_embedding: queryEmbedding,
+  match_threshold: 0.78,
+  match_count: 10,
+})
+
+// matches: [{ id, content, similarity, metadata }, ...] já filtrado por RLS
+const context = matches.map((m) => m.content).join('\n\n')
+const answer = await llmComplete({ context, question: userQuestion })
+```
+
+### IVFFlat alternativa
+
+```sql
+-- PT-BR: usar IVFFlat quando build time importa (dataset dinâmico)
+-- lists = sqrt(N) é heurística para N total de linhas
+create index documents_embedding_ivfflat_idx
+  on public.documents
+  using ivfflat (embedding vector_cosine_ops)
+  with (lists = 100);                       -- ajustar conforme volume
+```
+
+### Geração de embeddings em Edge Function
+
+```ts
+// supabase/functions/embed-document/index.ts
+// PT-BR: chunking + embedding + insert
+import { createClient } from 'npm:@supabase/supabase-js@2'
+import OpenAI from 'npm:openai@4'
+
+Deno.serve(async (req) => {
+  const { user_id, document } = await req.json()
+  const openai = new OpenAI({ apiKey: Deno.env.get('OPENAI_API_KEY') })
+  const supabase = createClient(
+    Deno.env.get('SUPABASE_URL')!,
+    Deno.env.get('SUPABASE_SECRET_KEYS')!
+  )
+
+  // PT-BR: chunk em pedaços de ~400 tokens com overlap 20%
+  const chunks = chunkText(document, { size: 400, overlap: 80 })
+
+  for (const chunk of chunks) {
+    const embedRes = await openai.embeddings.create({
+      model: 'text-embedding-3-small',      // dim 1536
+      input: chunk,
+    })
+    await supabase.from('documents').insert({
+      user_id,
+      content: chunk,
+      embedding: embedRes.data[0].embedding,
+    })
+  }
+
+  return new Response('embedded')
+})
+```
+
+## Anti-patterns
+
+### Anti-pattern 1: Dim mismatch entre modelo e coluna
+
+**Errado:**
+```sql
+create table documents (embedding vector(1536) not null);
+```
+```ts
+// PT-BR: usa nomic-embed-text que retorna dim 768
+const embedding = await nomicEmbed(text)              // 768
+await supabase.from('documents').insert({ embedding })  // ⚠ insert falha
+```
+
+**Por quê:** Postgres rejeita insert com dim mismatch (`expected 1536 dimensions, got 768`). Em pior caso, se aceito, similarity retorna ranking aleatório.
+
+**Certo:** alinhe dim:
+```sql
+create table documents (embedding vector(768) not null);
+```
+ou troque o modelo para um que retorne 1536.
+
+### Anti-pattern 2: Similarity search sem RLS — vazamento RAG
+
+**Errado:**
+```sql
+-- PT-BR: tabela documents sem RLS
+create table public.documents (
+  id uuid primary key,
+  content text,
+  embedding vector(1536)
+);
+```
+
+**Por quê:** qualquer authenticated chama `match_documents` e recupera documents de outros usuários. Em apps multi-tenant, é vazamento crítico — RAG do tenant A vê docs do tenant B.
+
+**Certo:** habilite RLS + policies por `user_id`/`org_id` + use `security invoker` em funções de match (ver pattern canônico).
+
+### Anti-pattern 3: Chunks gigantes (> 1k tokens)
+
+**Errado:**
+```ts
+// PT-BR: chunk inteiro de documento (5k tokens)
+const chunks = [fullDocument]
+const embedding = await embed(fullDocument)
+```
+
+**Por quê:** embeddings perdem detalhe semântico em chunks muito grandes. O modelo média muitos conceitos em um único vetor, similarity vira ruidosa. Ranking RAG fica ruim.
+
+**Certo:** chunks de 200-500 tokens com overlap:
+```ts
+const chunks = chunkText(fullDocument, { size: 400, overlap: 80 })
+for (const chunk of chunks) {
+  await embed(chunk).then(insert)
+}
+```
+
+### Anti-pattern 4: Sem index em coluna `embedding`
+
+**Errado:**
+```sql
+create table documents (embedding vector(1536) not null);
+-- (esqueceu create index)
+```
+
+**Por quê:** sem index, similarity search vira sequential scan. Em > 10k linhas, queries levam segundos a minutos. Em produção, app fica inviável.
+
+**Certo:**
+```sql
+create index documents_embedding_hnsw_idx on documents using hnsw (embedding vector_cosine_ops);
+```
+
+## Notas de futuro
+
+- **Hybrid search** (FTS + vector com RRF — Reciprocal Rank Fusion) está coberto em skill `supabase-fts` (defer v1.9 — full-text search standalone).
+- **Vector Buckets** e **Analytics Buckets** ainda em alpha em 2026 — mencione como existência mas não detalhe (pattern canônico evoluindo).
+
+## Ver também
+
+- [supabase-rls-policies](../supabase-rls-policies/SKILL.md) — RLS é base de RAG with permissions
+- [supabase-database-functions](../supabase-database-functions/SKILL.md) — função `match_documents` com `security invoker` + `set search_path = ''`
+- [supabase-edge-functions](../supabase-edge-functions/SKILL.md) — geração de embeddings server-side
+- [supabase-migrations](../supabase-migrations/SKILL.md) — schema com `vector` extension
+- [glossário](../_shared-supabase/glossary.md) — operadores `<=>`/`<#>`/`<->`