@luanpdd/kit-mcp 1.6.1 → 1.8.1

package/kit/framework/workflows/new-project.md

@@ -210,69 +210,21 @@ Proceed to Step 4 (skip Steps 3 and 5).
 
 ## 3. Deep Questioning
 
-**If auto mode:** Skip (already handled in Step 2a). Extract project context from provided document instead and proceed to Step 4.
+**Auto mode:** pular (handled em 2a) — extrair contexto do documento e ir pra passo 4.
 
-**Display stage banner:**
+**Banner:** `framework ► QUESTIONING`.
 
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- framework ► QUESTIONING
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-**Open the conversation:**
-
-Ask inline (freeform, NOT AskUserQuestion):
-
-"What do you want to build?"
-
-Wait for their response. This gives you the context needed to ask intelligent follow-up questions.
-
-**Research-before-questions mode:** Check if `workflow.research_before_questions` is enabled in `.planning/config.json` (or the config from init context). When enabled, before asking follow-up questions about a topic area:
-
-1. Do a brief web search for best practices related to what the user described
-2. Mention key findings naturally as you ask questions (e.g., "Most projects like this use X — is that what you're thinking, or something different?")
-3. This makes questions more informed without changing the conversational flow
-
-When disabled (default), ask questions directly as before.
-
-**Follow the thread:**
-
-Based on what they said, ask follow-up questions that dig into their response. Use AskUserQuestion with options that probe what they mentioned — interpretations, clarifications, concrete examples.
-
-Keep following threads. Each answer opens new threads to explore. Ask about:
-
-- What excited them
-- What problem sparked this
-- What they mean by vague terms
-- What it would actually look like
-- What's already decided
-
-Consult `questioning.md` for techniques:
+**Abrir:** pergunta inline freeform (NÃO AskUserQuestion): "What do you want to build?". Aguardar resposta.
 
-- Challenge vagueness
-- Make abstract concrete
-- Surface assumptions
-- Find edges
-- Reveal motivation
+**Modo `workflow.research_before_questions`:** se enabled, antes de follow-ups numa área, fazer breve web search por melhores práticas e mencionar findings naturalmente ("Most projects like this use X — is that what you're thinking?"). Default off, perguntar direto.
 
-**Check context (background, not out loud):**
+**Follow the thread:** AskUserQuestion com options que provocam interpretações/clarificações/exemplos. Cada resposta abre novos threads. Cobrir: o que empolgou, problema que sparkou, termos vagos, como seria na prática, o que já está decidido.
 
-As you go, mentally check the context checklist from `questioning.md`. If gaps remain, weave questions naturally. Don't suddenly switch to checklist mode.
+**Técnicas de `questioning.md`:** challenge vagueness, concretize abstract, surface assumptions, find edges, reveal motivation.
 
-**Decision gate:**
+Mentalmente validar checklist do `questioning.md`; se gaps, tecer perguntas naturalmente (não modo checklist).
 
-When you could write a clear PROJECT.md, use AskUserQuestion:
-
-- header: "Ready?"
-- question: "I think I understand what you're after. Ready to create PROJECT.md?"
-- options:
-  - "Create PROJECT.md" — Let's move forward
-  - "Keep exploring" — I want to share more / ask me more
-
-If "Keep exploring" — ask what they want to add, or identify gaps and probe naturally.
-
-Loop until "Create PROJECT.md" selected.
+**Decision gate:** quando puder escrever PROJECT.md claro, AskUserQuestion `Ready?` — "Create PROJECT.md" ou "Keep exploring". Loop até "Create".
 
 ## 4. Write PROJECT.md
 
@@ -449,60 +401,17 @@ questions: [
 ]
 ```
 
-**Round 2 — Workflow agents:**
+**Round 2 — Workflow agents (opt-in, adicionam tokens/tempo, melhoram qualidade):**
 
-These spawn additional agents during planning/execution. They add tokens and time but improve quality.
+| Agent | Quando | O que faz |
+|---|---|---|
+| Researcher | Antes de cada plan-phase | Investiga domínio, padrões, pitfalls |
+| Plan Checker | Após plano criado | Verifica se plano atinge o goal |
+| Verifier | Após execução | Confirma must-haves entregues |
 
-| Agent | When it runs | What it does |
-|-------|--------------|--------------|
-| **Researcher** | Before planning each phase | Investigates domain, finds patterns, surfaces gotchas |
-| **Plan Checker** | After plan is created | Verifies plan actually achieves the phase goal |
-| **Verifier** | After phase execution | Confirms must-haves were delivered |
+Todos recomendados pra projetos sérios; pular pra experimentos rápidos.
 
-All recommended for important projects. Skip for quick experiments.
-
-```
-questions: [
-  {
-    header: "Research",
-    question: "Research before planning each phase? (adds tokens/time)",
-    multiSelect: false,
-    options: [
-      { label: "Yes (Recommended)", description: "Investigate domain, find patterns, surface gotchas" },
-      { label: "No", description: "Plan directly from requirements" }
-    ]
-  },
-  {
-    header: "Plan Check",
-    question: "Verify plans will achieve their goals? (adds tokens/time)",
-    multiSelect: false,
-    options: [
-      { label: "Yes (Recommended)", description: "Catch gaps before execution starts" },
-      { label: "No", description: "Execute plans without verification" }
-    ]
-  },
-  {
-    header: "Verifier",
-    question: "Verify work satisfies requirements after each phase? (adds tokens/time)",
-    multiSelect: false,
-    options: [
-      { label: "Yes (Recommended)", description: "Confirm deliverables match phase goals" },
-      { label: "No", description: "Trust execution, skip verification" }
-    ]
-  },
-  {
-    header: "AI Models",
-    question: "Which AI models for planning agents?",
-    multiSelect: false,
-    options: [
-      { label: "Balanced (Recommended)", description: "Sonnet for most agents — good quality/cost ratio" },
-      { label: "Quality", description: "Opus for research/roadmap — higher cost, deeper analysis" },
-      { label: "Budget", description: "Haiku where possible — fastest, lowest cost" },
-      { label: "Inherit", description: "Use the current session model for all agents (OpenCode /model)" }
-    ]
-  }
-]
-```
+AskUserQuestion: 4 perguntas — `Research` (yes/no), `Plan Check` (yes/no), `Verifier` (yes/no), `AI Models` (Balanced=Sonnet recomendado / Quality=Opus / Budget=Haiku / Inherit=session model).
 
 Create `.planning/config.json` with all settings (CLI fills in remaining defaults automatically):
 

package/kit/framework/workflows/plan-phase.md

@@ -13,8 +13,33 @@ Tipos de subagentes framework válidos (use nomes exatos — não use 'general-p
 - phase-researcher — Pesquisa abordagens técnicas para uma fase
 - planner — Cria planos detalhados a partir do escopo da fase
 - plan-checker — Revisa qualidade do plano antes da execução
+
+**Agents especializados por domínio** (use ao invés de phase-researcher quando aplicável):
+- supabase-architect — para fases Supabase (DB/Auth/Realtime/Edge/Storage), substitui phase-researcher genérico. Já tem questionamento Supabase-específico (tier, branches, RLS strategy, multi-tenant).
+- supabase-{migration-writer,rls-writer,edge-fn-writer,realtime-implementer,auth-bootstrapper,storage-implementer} — destinos de delegação que o `planner` pode incluir como `subagent_type` em tasks específicas do PLAN.md.
+- schema-checker — pré-validação de SQL para tasks que tocam migrations existentes.
 </available_agent_types>
 
+<supabase_phase_detection>
+**Detecção de fase Supabase no Step 1:** após carregar contexto via `init plan-phase`, verifique se a fase mexe em domínios Supabase (DB/Auth/Realtime/Edge/Storage/RLS/migrations). Sinais no objetivo do ROADMAP.md ou nos REQs mapeados: "Supabase", "Postgres", "RLS", "migration", "Edge Function", "broadcast", "pgvector", "bucket", `supabase/migrations/`, `supabase/schemas/`, `supabase/functions/`.
+
+**Se for fase Supabase:**
+1. **Pesquisa:** invoque `supabase-architect` em vez de `phase-researcher` genérico no Step 5 (Tratar Pesquisa). Architect produz plano de schema/RLS/topology que o planner usa como base.
+2. **Plano:** o `planner` deve incluir tasks com `subagent_type` apontando para o agent especializado correto (ver tabela abaixo). O `executor` lê e dispatcha automaticamente.
+
+| Task no plano envolve | `subagent_type:` para o `executor` dispatch |
+|---|---|
+| Migration ou schema declarative | `supabase-migration-writer` |
+| RLS policies | `supabase-rls-writer` |
+| Edge Function | `supabase-edge-fn-writer` |
+| Realtime (3 layers) | `supabase-realtime-implementer` |
+| Bootstrap auth Next.js | `supabase-auth-bootstrapper` |
+| Storage bucket + RLS | `supabase-storage-implementer` |
+| Validar SQL pre-apply | `schema-checker` |
+
+**Anti-pitfall:** agents `supabase-*` não devem se invocar uns aos outros — toda chain passa pelo `executor` lendo o plan. (Gate `agent-no-recursive-dispatch` valida.)
+</supabase_phase_detection>
+
 <process>
 
 ## 1. Inicializar
@@ -234,43 +259,15 @@ Se "Executar discuss-phase primeiro":
 
 ## 5. Tratar Pesquisa
 
-**Pular se:** flag `--gaps` ou flag `--skip-research` ou flag `--reviews`.
-
-**Se `has_research` for true (do init) E sem flag `--research`:** Usar existente, pular para o passo 6.
-
-**Se RESEARCH.md ausente OU flag `--research`:**
-
-**Se sem flag explícita (`--research` ou `--skip-research`) e não `--auto`:**
-Perguntar ao usuário se deseja pesquisar, com uma recomendação contextual baseada na fase:
+**Pular se:** `--gaps`, `--skip-research`, ou `--reviews`.
 
-Se `TEXT_MODE` for true, apresentar como lista numerada de texto simples:
-```
-Pesquisar antes de planejar a Fase {X}: {phase_name}?
+**Se `has_research` true e sem `--research`:** usar existente, ir pra passo 6.
 
-1. Pesquisar primeiro (Recomendado) — Investigar domínio, padrões e dependências antes do planejamento. Melhor para novas funcionalidades, integrações desconhecidas ou mudanças arquiteturais.
-2. Pular pesquisa — Planejar diretamente a partir do contexto e requisitos. Melhor para correções de bugs, refatorações simples ou tarefas bem compreendidas.
-
-Digite o número:
-```
+**Se ausente OR `--research`:** sem flag explícita e sem `--auto`, perguntar (AskUserQuestion ou lista numerada se TEXT_MODE):
+- "Pesquisar primeiro (Recomendado)" — investiga domínio/padrões/deps antes de planejar. Melhor pra features novas, integrações novas, mudanças arquiteturais.
+- "Pular pesquisa" — planeja direto do contexto. Melhor pra bug fix, refactor simples, tarefas bem compreendidas.
 
-Caso contrário usar AskUserQuestion:
-```
-AskUserQuestion([
-  {
-    question: "Pesquisar antes de planejar a Fase {X}: {phase_name}?",
-    header: "Pesquisa",
-    multiSelect: false,
-    options: [
-      { label: "Pesquisar primeiro (Recomendado)", description: "Investigar domínio, padrões e dependências antes do planejamento. Melhor para novas funcionalidades, integrações desconhecidas ou mudanças arquiteturais." },
-      { label: "Pular pesquisa", description: "Planejar diretamente a partir do contexto e requisitos. Melhor para correções de bugs, refatorações simples ou tarefas bem compreendidas." }
-    ]
-  }
-])
-```
-
-Se o usuário selecionar "Pular pesquisa": pular para o passo 6.
-
-**Se `--auto` e `research_enabled` for false:** Pular pesquisa silenciosamente (preserva comportamento automatizado).
+Se "Pular": passo 6. Se `--auto` e `research_enabled=false`: pular silenciosamente.
 
 Exibir banner:
 ```
@@ -365,51 +362,16 @@ test -f "${PHASE_DIR}/${PADDED_PHASE}-VALIDATION.md" && echo "VALIDATION_CREATED
 > Pular se `workflow.ui_phase` for explicitamente `false` E `workflow.ui_safety_gate` for explicitamente `false` em `.planning/config.json`. Se as chaves estiverem ausentes, tratar como habilitado.
 
 ```bash
-UI_PHASE_CFG=$(node "./.claude/framework/bin/tools.cjs" config-get workflow.ui_phase 2>/dev/null || echo "true")
-UI_GATE_CFG=$(node "./.claude/framework/bin/tools.cjs" config-get workflow.ui_safety_gate 2>/dev/null || echo "true")
-```
-
-**Se ambos forem `false`:** Pular para o passo 6.
-
-Verificar se a fase tem indicadores de frontend:
-
-```bash
-PHASE_SECTION=$(node "./.claude/framework/bin/tools.cjs" roadmap get-phase "${PHASE}" 2>/dev/null)
-echo "$PHASE_SECTION" | grep -iE "UI|interface|frontend|component|layout|page|screen|view|form|dashboard|widget" > /dev/null 2>&1
-HAS_UI=$?
-```
+`UI_PHASE_CFG` / `UI_GATE_CFG` (default true). Se ambos false, pular pra passo 6.
 
-**Se `HAS_UI` for 0 (indicadores de frontend encontrados):**
+**Detecção:** grep `-iE "UI|interface|frontend|component|layout|page|screen|view|form|dashboard|widget"` na descrição da fase. Se sem match, pular silenciosamente.
 
-Verificar UI-SPEC existente:
-```bash
-UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
-```
-
-**Se UI-SPEC.md encontrado:** Definir `UI_SPEC_PATH=$UI_SPEC_FILE`. Exibir: `Usando contrato de design de UI: ${UI_SPEC_PATH}`
-
-**Se UI-SPEC.md ausente E `UI_GATE_CFG` for `true`:**
-
-Se `TEXT_MODE` for true, apresentar como lista numerada de texto simples:
-```
-A Fase {N} tem indicadores de frontend mas sem UI-SPEC.md. Gerar um contrato de design antes do planejamento?
-
-1. Gerar UI-SPEC primeiro — Execute /fase-ui {N} então re-execute /planejar-fase {N}
-2. Continuar sem UI-SPEC
-3. Não é uma fase de frontend
-
-Digite o número:
-```
-
-Caso contrário usar AskUserQuestion:
-- header: "Contrato de Design de UI"
-- question: "A Fase {N} tem indicadores de frontend mas sem UI-SPEC.md. Gerar um contrato de design antes do planejamento?"
-- options:
-  - "Gerar UI-SPEC primeiro" → Exibir: "Execute `/fase-ui {N} ${WS}` então re-execute `/planejar-fase {N} ${WS}`". Sair do workflow.
-  - "Continuar sem UI-SPEC" → Continuar para o passo 6.
-  - "Não é uma fase de frontend" → Continuar para o passo 6.
-
-**Se `HAS_UI` for 1 (sem indicadores de frontend):** Pular silenciosamente para o passo 6.
+**Se match encontrado:**
+- UI-SPEC.md existe → usar (`UI_SPEC_PATH`); exibir confirmação
+- UI-SPEC.md ausente E `UI_GATE_CFG=true` → AskUserQuestion (ou lista numerada se TEXT_MODE):
+  - "Gerar UI-SPEC primeiro" → exibir `/fase-ui {N} ${WS}` e sair do workflow
+  - "Continuar sem UI-SPEC" → passo 6
+  - "Não é frontend" → passo 6
 
 ## 6. Verificar Planos Existentes
 
@@ -511,28 +473,13 @@ Output consumed by /execute-phase. Plans need:
 
 Every task MUST include these fields — they are NOT optional:
 
-1. **`<read_first>`** — Files the executor MUST read before touching anything. Always include:
-   - The file being modified (so executor sees current state, not assumptions)
-   - Any "source of truth" file referenced in CONTEXT.md (reference implementations, existing patterns, config files, schemas)
-   - Any file whose patterns, signatures, types, or conventions must be replicated or respected
-
-2. **`<acceptance_criteria>`** — Verifiable conditions that prove the task was done correctly. Rules:
-   - Every criterion must be checkable with grep, file read, test command, or CLI output
-   - NEVER use subjective language ("looks correct", "properly configured", "consistent with")
-   - ALWAYS include exact strings, patterns, values, or command outputs that must be present
-   - Examples:
-     - Code: `auth.py contains def verify_token(` / `test_auth.py exits 0`
-     - Config: `.env.example contains DATABASE_URL=` / `Dockerfile contains HEALTHCHECK`
-     - Docs: `README.md contains '## Installation'` / `API.md lists all endpoints`
-     - Infra: `deploy.yml has rollback step` / `docker-compose.yml has healthcheck for db`
-
-3. **`<action>`** — Must include CONCRETE values, not references. Rules:
-   - NEVER say "align X with Y", "match X to Y", "update to be consistent" without specifying the exact target state
-   - ALWAYS include the actual values: config keys, function signatures, SQL statements, class names, import paths, env vars, etc.
-   - If CONTEXT.md has a comparison table or expected values, copy them into the action verbatim
-   - The executor should be able to complete the task from the action text alone, without needing to read CONTEXT.md or reference files (read_first is for verification, not discovery)
-
-**Why this matters:** Executor agents work from the plan text. Vague instructions like "update the config to match production" produce shallow one-line changes. Concrete instructions like "add DATABASE_URL=postgresql://... , set POOL_SIZE=20, add REDIS_URL=redis://..." produce complete work. The cost of verbose plans is far less than the cost of re-doing shallow execution.
+1. **`<read_first>`** — files o executor DEVE ler antes de tocar em qualquer coisa: o arquivo sendo modificado, "source of truth" do CONTEXT.md, qualquer arquivo cujas convenções/tipos/assinaturas precisem ser replicados.
+
+2. **`<acceptance_criteria>`** — condições verificáveis com grep/file read/test command/CLI output. NUNCA linguagem subjetiva ("looks correct"); SEMPRE strings/patterns exatos. Ex: `auth.py contains "def verify_token("`, `test_auth.py exits 0`, `.env.example contains "DATABASE_URL="`.
+
+3. **`<action>`** — valores CONCRETOS, nunca referências. NUNCA "align X with Y"; SEMPRE valores reais (config keys, function signatures, SQL, imports, env vars). Se CONTEXT.md tem tabela de comparação, copie no `<action>` literal. Executor deve completar só com texto do action.
+
+**Por quê:** instruções vagas ("update config to match production") geram one-line changes; instruções concretas ("add DATABASE_URL=..., POOL_SIZE=20, REDIS_URL=...") geram trabalho completo. Custo de plano verboso é ínfimo vs custo de redo de execução shallow.
 </deep_work_rules>
 
 <quality_gate>
@@ -725,58 +672,17 @@ Rotear para `<offer_next>` OU `auto_advance` dependendo de flags/config.
 
 Verificar gatilho de avanço automático:
 
-1. Analisar flag `--auto` de $ARGUMENTS
-2. **Sincronizar flag de cadeia com intenção** — se o usuário invocou manualmente (sem `--auto`), limpar a flag de cadeia efêmera de qualquer cadeia `--auto` anterior interrompida. Isso NÃO toca em `workflow.auto_advance` (preferência persistente do usuário):
-   ```bash
-   if [[ ! "$ARGUMENTS" =~ --auto ]]; then
-     node "./.claude/framework/bin/tools.cjs" config-set workflow._auto_chain_active false 2>/dev/null
-   fi
-   ```
-3. Ler tanto a flag de cadeia quanto a preferência do usuário:
-   ```bash
-   AUTO_CHAIN=$(node "./.claude/framework/bin/tools.cjs" config-get workflow._auto_chain_active 2>/dev/null || echo "false")
-   AUTO_CFG=$(node "./.claude/framework/bin/tools.cjs" config-get workflow.auto_advance 2>/dev/null || echo "false")
-   ```
-
-**Se flag `--auto` presente OU `AUTO_CHAIN` for true OU `AUTO_CFG` for true:**
-
-Exibir banner:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- framework ► AVANÇANDO AUTOMATICAMENTE PARA EXECUÇÃO
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+**Detecção:** flag `--auto` em $ARGUMENTS, OR `workflow._auto_chain_active=true`, OR `workflow.auto_advance=true`.
 
-Planos prontos. Iniciando execute-phase...
-```
-
-Iniciar execute-phase usando a ferramenta Skill para evitar sessões Task aninhadas (que causam freezes de runtime devido ao aninhamento profundo de agentes):
-```
-Skill(skill="framework:executar-fase", args="${PHASE} --auto --no-transition ${WS}")
-```
+**Sync de cadeia:** se invocação manual (sem `--auto`), zere `workflow._auto_chain_active` (não toque `workflow.auto_advance`).
 
-A flag `--no-transition` diz ao execute-phase para retornar status após verificação em vez de encadear mais. Isso mantém a cadeia de avanço automático plana — cada fase roda no mesmo nível de aninhamento em vez de criar agentes Task mais profundos.
+**Quando ativo:** dispare `Skill(skill="framework:executar-fase", args="${PHASE} --auto --no-transition ${WS}")`. A flag `--no-transition` diz pra execute-phase retornar status após verificação (não encadear), mantendo cadeia plana.
 
-**Lidar com retorno do execute-phase:**
-- **FASE CONCLUÍDA** → Exibir resumo final:
-  ```
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-   framework ► FASE ${PHASE} CONCLUÍDA ✓
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-  Pipeline de avanço automático finalizado.
-
-  Próximo: /discutir-fase ${NEXT_PHASE} --auto ${WS}
-  ```
-- **LACUNAS ENCONTRADAS / VERIFICAÇÃO FALHOU** → Exibir resultado, parar cadeia:
-  ```
-  Avanço automático parado: Execução precisa de revisão.
-
-  Revisar a saída acima e continuar manualmente:
-  /executar-fase ${PHASE} ${WS}
-  ```
+**Roteamento de retorno:**
+- `FASE CONCLUÍDA` → próximo: `/discutir-fase ${NEXT_PHASE} --auto ${WS}` (após `/clear`)
+- `LACUNAS ENCONTRADAS` / `VERIFICAÇÃO FALHOU` → parar cadeia. Continuar: `/executar-fase ${PHASE} ${WS}`
 
-**Se nem `--auto` nem config habilitado:**
-Rotear para `<offer_next>` (comportamento existente).
+**Quando inativo:** rotear para `<offer_next>`.
 
 </process>
 

package/kit/skills/_shared-supabase/glossary.md

@@ -0,0 +1,180 @@
+# Glossário Supabase — Termos, Comandos e Patterns Canônicos
+
+> Arquivo de referência compartilhado pelas skills `supabase-*`. **NÃO é skill** — não tem `description:` triggerável; não aparece em `listKit`. Cross-referenciado pelas 11 skills via Markdown link relativo.
+
+---
+
+## (a) Termos PT-BR ↔ EN
+
+### Authorization e Auth
+
+| EN | PT-BR / Significado |
+|---|---|
+| **RLS** | Row Level Security — segurança em nível de linha. Filtra automaticamente quais linhas de uma tabela cada usuário vê/modifica baseado em policies. |
+| **policy** | Política de RLS — regra `create policy ... on <table> for <op> ...`. Sempre granular por operação (SELECT/INSERT/UPDATE/DELETE). |
+| **`auth.uid()`** | Função que retorna o UUID do usuário autenticado da sessão atual. **Sempre** usar em `(select auth.uid())` em policies. |
+| **`auth.jwt()`** | Função que retorna o JWT decodificado da sessão. Acesso via `auth.jwt()->'app_metadata'` ou `auth.jwt()->>'aal'`. |
+| **`app_metadata`** | Metadata controlado pelo backend (apenas service_role pode mutar). **Use para roles/permissions** em RLS. |
+| **`user_metadata`** | Metadata controlado pelo cliente (`auth.updateUser({data: ...})`). **NUNCA** use em policy de autorização — privilege escalation. |
+| **service_role** | Role do Postgres com bypass total de RLS. **NUNCA** expor ao cliente — vazamento = acesso total ao DB. |
+| **anon** | Role para requests sem autenticação. RLS aplicado normalmente. |
+| **authenticated** | Role para usuário autenticado. RLS aplicado normalmente. |
+| **public** | Role default — equivale a anon + authenticated juntos. Evite — sempre use `to authenticated` ou `to anon` explícito. |
+| **AAL** | Authentication Assurance Level. `aal1` = senha apenas; `aal2` = senha + 2FA. Verifica via `(auth.jwt()->>'aal')::text`. |
+
+### Database e Schema
+
+| EN | PT-BR / Significado |
+|---|---|
+| **`schemas/`** | Pasta `supabase/schemas/` — fonte da verdade declarative do schema. Editar aqui, depois `db diff` gera migration. |
+| **`migrations/`** | Pasta `supabase/migrations/` — arquivos `YYYYMMDDHHmmss_<name>.sql` versionados em git. |
+| **`db diff`** | `supabase db diff -f <name>` — gera migration a partir do diff entre schemas/ declarado e DB local atual. |
+| **`db reset`** | `supabase db reset` — recria DB local do zero + reaplica todas as migrations + seeds. |
+| **`search_path`** | Caminho de busca de schema do Postgres. **Sempre** `set search_path = ''` em funções. |
+| **schema-qualified** | Referência a objeto com schema explícito: `public.tasks` em vez de só `tasks`. Obrigatório quando `search_path = ''`. |
+| **`SECURITY INVOKER`** | Função executa com permissões de quem chamou. Default obrigatório. |
+| **`SECURITY DEFINER`** | Função executa com permissões do owner. Apenas com justificativa documentada. |
+| **`IMMUTABLE`** | Função sempre retorna o mesmo para os mesmos inputs (sem consultar DB). |
+| **`STABLE`** | Função consulta DB mas não modifica — mesmo resultado dentro de uma transação. |
+| **`VOLATILE`** | Default. Função pode retornar valores diferentes ou ter side effects. |
+
+### Realtime
+
+| EN | PT-BR / Significado |
+|---|---|
+| **broadcast** | Mensagens custom via WebSocket — tipo recomendado em 2026 (substitui `postgres_changes` em apps novos). |
+| **postgres_changes** | Pattern legado de receber mudanças do DB via stream. Single-threaded — não escala. **Migrar para broadcast.** |
+| **presence** | Tracking de "quem está online". Usar **com moderação** — só para presence real (online status, cursor de colaboração). |
+| **channel** | Canal de comunicação — naming canônico `scope:entity:id` (ex: `room:123:messages`). |
+| **private channel** | Canal autenticado — `private: true` + RLS sobre `realtime.messages`. **Default em produção.** |
+| **`realtime.broadcast_changes`** | Função SQL para emitir broadcast de dentro do Postgres (de trigger). |
+| **`realtime.send`** | Função SQL para emitir mensagem custom (não amarrada a tabela). |
+
+### Edge Functions
+
+| EN | PT-BR / Significado |
+|---|---|
+| **Edge Function** | Função serverless Deno hospedada por Supabase. Roda perto do usuário. |
+| **`Deno.serve`** | Built-in para HTTP server em Edge Functions (NÃO usar `serve` de `deno.land/std`). |
+| **`EdgeRuntime.waitUntil`** | Permite tarefa background continuar após response retornar. |
+| **`npm:` / `jsr:`** | Specifiers de import obrigatórios (sem bare specifiers). Ex: `import x from "npm:hono@4.6.7"`. |
+
+### Storage e Vector
+
+| EN | PT-BR / Significado |
+|---|---|
+| **bucket** | Container de arquivos — público ou privado. Privado por default. |
+| **signed URL** | URL temporária com expiration para download de arquivo privado. |
+| **`storage.objects`** | Tabela onde Storage grava metadados — RLS aplicado aqui controla acesso. |
+| **multi-tenant path isolation** | Pattern: prefixar path do arquivo com `auth.uid()` (`{user_id}/file.png`) para isolar por tenant via RLS. |
+| **TUS** | Tus Resumable Upload protocol — upload em chunks resumable. |
+| **pgvector** | Extensão Postgres para embeddings/similarity search. |
+| **HNSW** | Hierarchical Navigable Small World — index para vector. **Recall melhor.** Default em 2026. |
+| **IVFFlat** | Inverted File Flat — index alternativo. Mais rápido com volumes grandes mas recall menor. |
+| **`<=>`** | Operador cosine distance em pgvector. |
+| **`<#>`** | Operador inner product em pgvector. |
+| **`<->`** | Operador L2 (euclidean) distance em pgvector. |
+
+### Background Jobs
+
+| EN | PT-BR / Significado |
+|---|---|
+| **`pg_cron`** | Extensão para jobs cron dentro do Postgres. Schedule SQL/funções. |
+| **`pgmq`** | Postgres Message Queue — extensão de queues. Requer Postgres 15.6.1.143+. |
+| **`pg_net`** | Extensão para requests HTTP de dentro do Postgres. v0.10.0+. |
+
+### Branching
+
+| EN | PT-BR / Significado |
+|---|---|
+| **branch database** | Cópia preview do DB de produção para feature branches. |
+| **persistent branch** | Branch que sobrevive entre PRs (staging long-lived). |
+| **preview branch** | Branch criado para PR específico — destruído ao merge. |
+
+---
+
+## (b) Comandos CLI canônicos
+
+```bash
+# Schema declarative
+supabase stop                                          # parar containers (necessário antes de db diff)
+supabase db diff -f <name>                             # gera migration de schemas/ → migrations/
+supabase db reset                                      # reset local + reaplica migrations + seeds
+supabase db push                                       # aplica migrations não aplicadas no DB remote
+supabase db pull                                       # pulla mudanças remote → cria migration local
+
+# Migrations
+supabase migration new <name>                          # cria migration vazia com timestamp UTC
+
+# Edge Functions
+supabase functions new <name>                          # cria boilerplate de Edge Function
+supabase functions deploy <name>                       # deploy para Supabase
+supabase functions invoke <name> --body '{}'           # invoca localmente
+
+# Tipos
+supabase gen types typescript --local > types/db.ts    # gera tipos do schema local
+supabase gen types typescript --linked > types/db.ts   # gera tipos do remote linked
+
+# Project lifecycle
+supabase init                                          # inicializa supabase/ no projeto
+supabase start                                         # sobe stack local (Postgres + Studio + Auth + ...)
+supabase stop                                          # derruba stack local
+supabase status                                        # status dos containers locais
+supabase link --project-ref <ref>                      # linka projeto local com remote
+
+# Branching
+supabase branches create <name>                        # cria preview branch
+supabase branches list                                 # lista branches
+supabase branches delete <name>                        # deleta branch (importante para custo!)
+
+# Secrets
+supabase secrets set --env-file .env.production        # setar secrets em remote
+supabase secrets list                                  # listar (sem revelar valores)
+```
+
+---
+
+## (c) Patterns canônicos consolidados
+
+### Pattern: `(select auth.uid())` wrapper em RLS
+- Sem `(select)`: degradação até **1000×** em queries com filtro RLS
+- Detalhes: [supabase-rls-policies](../supabase-rls-policies/SKILL.md)
+
+### Pattern: `set search_path = ''` em funções
+- Sem isso: vulnerável a hijack de schema via `search_path` manipulation
+- Detalhes: [supabase-database-functions](../supabase-database-functions/SKILL.md)
+
+### Pattern: `getAll`/`setAll` cookies em SSR (Next.js)
+- Pacote `@supabase/ssr` — **NUNCA** `@supabase/auth-helpers-nextjs` (deprecated)
+- Detalhes: [supabase-auth-ssr](../supabase-auth-ssr/SKILL.md)
+
+### Pattern: `cron → pgmq → Edge Function` (background jobs)
+- Schedule via `pg_cron` → enqueue em `pgmq` → consumir e disparar `pg_net.http_post()` para Edge Function
+- Sem dep externa (Inngest/Trigger.dev) — tudo dentro de Supabase
+- Detalhes: [supabase-cron-queues](../supabase-cron-queues/SKILL.md)
+
+### Pattern: RAG with permissions (similarity + RLS)
+- Embeddings em coluna vector + RLS policy filtrando por `user_id` ou `org_id`
+- Sem RLS, qualquer cliente vê embeddings de todos os tenants
+- Detalhes: [supabase-pgvector-rag](../supabase-pgvector-rag/SKILL.md)
+
+### Pattern: multi-tenant path isolation em Storage
+- Path do arquivo prefixado com `auth.uid()` ou `org_id`: `{user_id}/avatar.png`, `{org_id}/docs/file.pdf`
+- RLS sobre `storage.objects` valida que o cliente acessa apenas o próprio prefixo
+- Detalhes: [supabase-storage](../supabase-storage/SKILL.md)
+
+### Pattern: declarative-first → diff → migration
+- Editar schemas em `supabase/schemas/*.sql`
+- Rodar `supabase stop && supabase db diff -f <name>` para gerar migration em `supabase/migrations/`
+- Revisar migration manualmente antes de aplicar
+- Detalhes: [supabase-declarative-schema](../supabase-declarative-schema/SKILL.md)
+
+### Pattern: `private: true` em Realtime channels
+- Default em produção (2026) — desabilita acesso anônimo
+- Requer RLS sobre `realtime.messages` para SELECT (read) e INSERT (write)
+- Detalhes: [supabase-realtime](../supabase-realtime/SKILL.md)
+
+### Pattern: schema-qualified em Edge Functions chamando Supabase
+- Function consulta `public.tasks` (não `tasks`) quando usar service-role client
+- Combina com `set search_path = ''` em DB functions chamadas via RPC
+- Detalhes: [supabase-edge-functions](../supabase-edge-functions/SKILL.md)