@luanpdd/kit-mcp 1.22.0 → 1.27.0

package/kit/agents/executor.md

@@ -521,3 +521,44 @@ Separado dos commits por tarefa — captura apenas os resultados de execução.
 
 Inclua TODOS os commits (anteriores + novos se agente de continuação).
 </completion_format>
+
+<sql_auto_handoff_cooperativo>
+## SQL auto-handoff cooperativo (v1.23 — CROSS-10)
+
+Ao executar PLAN.md que produz SQL/DDL (CREATE TABLE, CREATE POLICY, etc.), **antes** de aplicar via `mcp__supabase__apply_migration` ou escrever arquivo `supabase/migrations/`, faça handoff cooperativo para `supabase-rls-hardener`.
+
+**Heurística de detecção (regex no SQL gerado):**
+
+```regex
+(create\s+table|create\s+policy|create\s+view|alter\s+table|create\s+function.*security\s+definer|grant\s+.*on|enable\s+row\s+level\s+security)
+```
+
+Se ≥ 1 match → invoca handoff:
+
+```python
+hardener_result = Task(
+  subagent_type="supabase-rls-hardener",
+  prompt=f"""
+  <upstream_intent>
+  Source agent: executor
+  Original goal: aplicar SQL definido em {plan_file}
+  Constraints: {plan_constraints if available else 'follow plan as-is'}
+  </upstream_intent>
+
+  <draft_sql>{generated_sql}</draft_sql>
+
+  <user_facing_caller>true</user_facing_caller>
+  """
+)
+```
+
+**Processamento de verdict:**
+- **GO** → aplica SQL direto sem mudanças
+- **STRENGTHEN** → aplica diff sugerido (ajustes mantendo intent); registra no commit message + SUMMARY.md
+- **REWRITE** → se user_facing_caller=true, PAUSA execução e pede confirmação ao usuário; sem confirmação, não aplica
+
+**Princípio canônico v1.23:** Executor faz (aplica plan); supabase-rls-hardener hardena (valida defense-in-depth). Conflitos viram diff explícito, nunca abortos silenciosos.
+
+**Registro em SUMMARY.md:** se hardener veredict ≠ GO, SUMMARY.md inclui section "## RLS Hardener Trace" com verdict + diff aplicado + justificativa.
+
+</sql_auto_handoff_cooperativo>

package/kit/agents/invite-flow-implementer.md

@@ -128,8 +128,60 @@ INVITE-FLOW-IMPLEMENTER · output integrado
 - Histogram `invite.accept_latency_ms` (tempo entre create e accept)
 - Alarme se `invite.created.count > bulk_limit_per_hour` por org → suspeita de abuso
 
+## Cooperative handoff to supabase-rls-hardener (v1.23)
+
+Após gerar CREATE TABLE org_invites + RPC create_invite/accept_invite + cron expire pending, faça handoff cooperativo para SQL bloco:
+
+```python
+Task(subagent_type="supabase-rls-hardener", prompt=f"""
+<upstream_intent>
+Source agent: invite-flow-implementer
+Original goal: implementar invite flow B2B com token-based para {org_context}
+Constraints: token SHA-256 (raw enviado por email, hash no banco); TTL 7d single-use; state machine 5 estados (pending→accepted|rejected|cancelled|expired); email-lock obrigatório; idempotência via FOR UPDATE em transação
+</upstream_intent>
+
+<draft_sql>{generated_invites_sql}</draft_sql>
+
+<user_facing_caller>true</user_facing_caller>
+""")
+```
+
+Hardener valida token security (hash apenas no DB), RPC com SECURITY DEFINER em schema private, RLS por org_id. **NUNCA descarte intent upstream silenciosamente**.
+
+## Cooperative handoff column-level (v1.24 — CROSS-15)
+
+`org_invites.token_raw` é gerado durante create do invite (raw enviado por email, hash armazenado). Após email enviado, **nenhum role além de service_role** deve poder ler o raw — é segredo de uso único. Aplique handoff cooperativo column-level:
+
+```python
+Task(subagent_type="supabase-column-privileges-writer", prompt=f"""
+<upstream_intent>
+Source agent: invite-flow-implementer
+Original goal: token raw column (org_invites.token_raw) legível APENAS para service_role pós-criação
+Constraints: token_raw é segredo único, enviado por email durante create; hash armazenado para validation em accept; raw NUNCA visível em REST API; member_invited audit event não logga token_raw
+</upstream_intent>
+
+<table>schema: public, name: org_invites</table>
+
+<sensitive_columns>
+- token_raw (text — segredo, apenas service_role)
+</sensitive_columns>
+
+<allowed_roles>
+- service_role: SELECT all (incluindo token_raw — usado durante envio de email)
+- authenticated: SELECT (id, org_id, email, role, status, expires_at, created_at, accepted_at) — sem token_raw
+- anon: SELECT (status) — minimal, para "this invite is still valid?" check pre-login
+</allowed_roles>
+
+<user_facing_caller>true</user_facing_caller>
+""")
+```
+
+**Caveat:** mesmo com column-level, considere também armazenar APENAS o hash do token (não o raw) na tabela. token_raw fica em memory durante envio do email e descartado. Isso é defense-in-depth Camada 9 (não armazenar segredos).
+
 ## Ver também
 
+- [supabase-rls-hardener](./supabase-rls-hardener.md) — canonical handoff target v1.23
+- [supabase-column-privileges-writer](./supabase-column-privileges-writer.md) — canonical handoff target v1.24 (column-level token raw)
 - [member-invite-flow](../skills/member-invite-flow/SKILL.md) — base de conhecimento
 - [supabase-migration-writer](./supabase-migration-writer.md) — invoked via Task() para SQL
 - [supabase-edge-fn-writer](./supabase-edge-fn-writer.md) — invoked via Task() para Edge Function

package/kit/agents/lgpd-compliance-auditor.md

@@ -197,8 +197,97 @@ Se ausente OU regions diferentes de `gru1` / `sa-east-1` → P2 informacional.
 - Counter `lgpd.audit.gaps.found{severity}` por execução
 - Histogram `lgpd.audit.duration_ms`
 
+## Cooperative handoff to supabase-rls-hardener (v1.23)
+
+Após gerar DSR table + Art. 18 right workflows + erasure via anonymization, faça handoff cooperativo para SQL bloco:
+
+```python
+Task(subagent_type="supabase-rls-hardener", prompt=f"""
+<upstream_intent>
+Source agent: lgpd-compliance-auditor
+Original goal: implementar LGPD compliance per-tenant (9 direitos Art. 18) para {org_context}
+Constraints: DSR SLA 15 dias (Art. 19) com alert pg_cron D-3; consent default opt-out (Art. 8 §5); erasure via anonymization (UUID preserved + PII NULL/hash); cross-border config (gru1 Vercel + sa-east-1 Supabase); PII sanitization em audit_logs (cross-ref Phase 109)
+</upstream_intent>
+
+<draft_sql>{generated_dsr_sql}</draft_sql>
+
+<user_facing_caller>true</user_facing_caller>
+""")
+```
+
+Hardener valida pseudonymization correto, retention policies via pg_cron, PII sanitization em audit_logs. **NUNCA descarte intent upstream silenciosamente**.
+
+## Cooperative handoff Postgres Roles (v1.26 — CROSS-20)
+
+Crie role `dpo_role` (Data Protection Officer) para acessar DSR requests + erasure operations. Role dedicado em vez de service_role API key permite audit trail granular para compliance LGPD/GDPR.
+
+```python
+Task(subagent_type="supabase-roles-implementer", prompt=f"""
+<upstream_intent>
+Source agent: lgpd-compliance-auditor
+Original goal: criar role dpo_role para DSR access + erasure operations (LGPD Art. 18 compliance)
+Constraints: BYPASSRLS necessário (DPO precisa ver todos requests cross-org); column-level GRANT em PII columns (cross-ref v1.24 CROSS-12); login com password forte; audit obrigatório
+</upstream_intent>
+
+<roles_to_create>
+- name: dpo_role
+  type: user
+  login: true
+  password_source: vault
+  bypassrls: true
+  inherit: false
+  description: "Data Protection Officer. Acesso DSR requests + erasure operations. LGPD Art. 18."
+  owner: "dpo@company.com"
+</roles_to_create>
+
+<grants>
+dpo_role:
+  - schema: public, usage: true
+  - table: public.dsr_requests, ops: [SELECT, INSERT, UPDATE]
+  - table: public.audit_log, ops: [SELECT]  # column-level já em payload
+</grants>
+
+<use_case>system_access</use_case>
+<user_facing_caller>true</user_facing_caller>
+""")
+```
+
+## Cooperative handoff column-level (v1.24 — CROSS-12)
+
+DSR (Data Subject Request) workflow precisa de erasure granular por coluna — não só DELETE row, mas anonymize PII columns específicas. Cross-border PII restriction (gru1 Vercel + sa-east-1 Supabase) também requer column-level audit. Aplique handoff cooperativo:
+
+```python
+Task(subagent_type="supabase-column-privileges-writer", prompt=f"""
+<upstream_intent>
+Source agent: lgpd-compliance-auditor
+Original goal: implementar DSR + erasure por coluna + cross-border PII restriction para LGPD Art. 18 compliance
+Constraints: DSR table tem colunas PII (subject_email, subject_phone, subject_address); erasure via anonymization (não DELETE); legível só por dpo_role + service_role; cross-border config sa-east-1 obrigatório
+</upstream_intent>
+
+<table>schema: public, name: dsr_requests</table>
+
+<sensitive_columns>
+- subject_email
+- subject_phone
+- subject_address
+- subject_metadata (jsonb — pode ter info sensível adicional)
+</sensitive_columns>
+
+<allowed_roles>
+- service_role: SELECT all (admin tasks)
+- dpo_role: SELECT all (Data Protection Officer — quem processa DSR)
+- authenticated: SELECT (id, request_type, status, created_at, resolved_at) — minimal
+- anon: denied (sem GRANT)
+</allowed_roles>
+
+<user_facing_caller>true</user_facing_caller>
+""")
+```
+
 ## Ver também
 
+- [supabase-rls-hardener](./supabase-rls-hardener.md) — canonical handoff target v1.23
+- [supabase-column-privileges-writer](./supabase-column-privileges-writer.md) — canonical handoff target v1.24 (column-level DSR/erasure)
 - [lgpd-multi-tenant-compliance](../skills/lgpd-multi-tenant-compliance/SKILL.md) — base de conhecimento
 - [audit-log-multi-tenant](../skills/audit-log-multi-tenant/SKILL.md) — Phase 109, PII sanitization + legal_hold
 - [multi-tenant-isolation-auditor](./multi-tenant-isolation-auditor.md) — agent sibling padrão de audit

package/kit/agents/multi-tenant-rls-writer.md

@@ -252,8 +252,86 @@ NOTAS
 - super_admin actions emitem evento `super_admin_action` em `audit_logs` (Phase 109)
 - Counter `rls.deny.count{tenant_id, policy}` (cross-ref [`four-golden-signals`](../skills/four-golden-signals/SKILL.md))
 
+## Cooperative handoff to supabase-rls-hardener (v1.23)
+
+Após gerar policies RLS hierárquicas, faça handoff cooperativo para `supabase-rls-hardener` validar defense-in-depth:
+
+```python
+Task(subagent_type="supabase-rls-hardener", prompt=f"""
+<upstream_intent>
+Source agent: multi-tenant-rls-writer
+Original goal: gerar policies RLS hierárquicas org→dept→role→permission para {table_name}
+Constraints: helper functions já existem em schema private (is_member_of, has_role, has_permission, is_super_admin); STABLE; partial index em organization_members
+</upstream_intent>
+
+<draft_sql>{generated_policies_sql}</draft_sql>
+
+<user_facing_caller>true</user_facing_caller>
+""")
+```
+
+Hardener processa verdict GO/STRENGTHEN/REWRITE-com-confirmação. **NUNCA descarte intent upstream silenciosamente** — conflitos viram diff explícito. Princípio canônico v1.23: agents não-Supabase pensam/planejam; agents Supabase materializam/hardenam; ninguém descarta o outro.
+
+## Cooperative handoff column-level (v1.24 — CROSS-14)
+
+Em hierarquia multi-tenant org→dept→role→permission, column-level pode ser aplicado para restringir acesso granular a colunas sensíveis dentro de tabelas multi-tenant. Casos típicos: department_settings com colunas configurações sensíveis visíveis apenas para department_lead; org_billing com colunas credit_card_token visíveis apenas para org_owner.
+
+```python
+Task(subagent_type="supabase-column-privileges-writer", prompt=f"""
+<upstream_intent>
+Source agent: multi-tenant-rls-writer
+Original goal: column-level privileges dentro de hierarquia org/dept/role/permission
+Constraints: tabela {table_name} tem coluna(s) sensível(eis) {sensitive_cols} que devem ser legíveis apenas para role específico na hierarquia; helper functions existem em schema private (private.is_member_of, private.has_role, private.has_permission)
+</upstream_intent>
+
+<table>schema: public, name: {table_name}</table>
+
+<sensitive_columns>
+{sensitive_cols_list}
+</sensitive_columns>
+
+<allowed_roles>
+- service_role: SELECT all
+- {specific_role}: SELECT all (via private.has_role check em RLS combinada)
+- authenticated: SELECT non-sensitive columns
+</allowed_roles>
+
+<user_facing_caller>true</user_facing_caller>
+""")
+```
+
+**Caveat hierarquia:** column-level é Postgres role-level (não muda baseado em RLS row context). Para casos onde acesso depende de hierarquia *dinâmica* (membership ativa em dept específico), prefira RLS policy + dedicated role table (mais flexível). Use column-level apenas para casos estáticos com role Postgres separado.
+
+## Cooperative handoff RBAC via Custom Claims (v1.25 — CROSS-16)
+
+Para RBAC em B2B multi-tenant, **combine** Custom Access Token Auth Hook (claim global para role) com helper functions PG STABLE (context-aware per-org). Pattern v1.25 é zero-JOIN para role global, helper function continua para per-org context. Aplique handoff cooperativo:
+
+```python
+Task(subagent_type="supabase-rbac-implementer", prompt=f"""
+<upstream_intent>
+Source agent: multi-tenant-rls-writer
+Original goal: implementar RBAC híbrido (claim global + helper function per-org) para B2B multi-tenant
+Constraints: roles globais (super_admin, billing_admin) via custom claim; roles per-org (org_admin, org_member) via helper function STABLE; combinar em policies via OR
+</upstream_intent>
+
+<roles>super_admin, billing_admin, support</roles>
+<permissions_matrix>
+super_admin: [orgs.*, users.*, audit.read]
+billing_admin: [billing.*, subscriptions.read]
+support: [users.read, support_tickets.*]
+</permissions_matrix>
+<multi_tenant>true</multi_tenant>
+<user_facing_caller>true</user_facing_caller>
+""")
+```
+
+Hardener processa verdict; output combina custom claim (zero-JOIN para super_admin) + helper functions PG existentes (per-org context). Princípio canônico v1.23 (herdado): nenhum lado descarta upstream.
+
 ## Ver também
 
+- [supabase-rls-hardener](./supabase-rls-hardener.md) — canonical handoff target v1.23 (verdicts GO/STRENGTHEN/REWRITE)
+- [supabase-column-privileges-writer](./supabase-column-privileges-writer.md) — canonical handoff target v1.24 (column-level hierarquia)
+- [supabase-rbac-implementer](./supabase-rbac-implementer.md) — canonical handoff target v1.25 (Custom Claims + Auth Hook)
 - [supabase-rls-writer](./supabase-rls-writer.md) — agent base v1.8 que herda anti-pitfalls
 - [supabase-rls-policies](../skills/supabase-rls-policies/SKILL.md) — base de conhecimento canônica v1.8
 - [multi-tenant-rls-hierarchy](../skills/multi-tenant-rls-hierarchy/SKILL.md) — base de conhecimento desta agent

package/kit/agents/org-onboarding-implementer.md

@@ -192,8 +192,29 @@ Onboarding é hot path crítico — emite eventos canônicos:
 3. **Counter:** `signup.org_created.count` (skill [`four-golden-signals`](../skills/four-golden-signals/SKILL.md))
 4. **Histogram:** `signup.duration_ms` (latência total signup → dashboard)
 
+## Cooperative handoff to supabase-rls-hardener (v1.23)
+
+Após gerar migration atômica (org + members em 1 trx) + Edge Function setup wizard async, faça handoff cooperativo para SQL bloco:
+
+```python
+Task(subagent_type="supabase-rls-hardener", prompt=f"""
+<upstream_intent>
+Source agent: org-onboarding-implementer
+Original goal: signup → criar org → primeiro admin → setup wizard para nova org
+Constraints: atomicidade (org + first_member em 1 trx); slug imutável + único cross-tenant (uniqueness constraint); RLS desde dia 1; first admin sem invite (admin direto via signup)
+</upstream_intent>
+
+<draft_sql>{generated_signup_migration_sql}</draft_sql>
+
+<user_facing_caller>true</user_facing_caller>
+""")
+```
+
+Hardener valida que RLS está ativo já na primeira migration, GRANTs corretos para anon (durante signup) e authenticated (pós-login). **NUNCA descarte intent upstream silenciosamente**.
+
 ## Ver também
 
+- [supabase-rls-hardener](./supabase-rls-hardener.md) — canonical handoff target v1.23
 - [org-onboarding-flow](../skills/org-onboarding-flow/SKILL.md) — base de conhecimento (regras + patterns + anti-patterns)
 - [b2b-saas-architecture](../skills/b2b-saas-architecture/SKILL.md) — schema canônico (Phase 106)
 - [supabase-migration-writer](./supabase-migration-writer.md) — invoked via Task() para SQL

package/kit/agents/planner.md

@@ -889,3 +889,34 @@ Siga os templates nas seções checkpoints e revision_mode respectivamente.
 - [ ] Usuário sabe rodar `/executar-fase {X} --gaps-only`
 
 </success_criteria>
+
+<sql_auto_handoff_cooperativo>
+## SQL auto-handoff cooperativo (v1.23 — CROSS-10)
+
+Ao gerar PLAN.md que inclui tarefas com SQL/DDL (CREATE TABLE, CREATE POLICY, CREATE VIEW, ALTER TABLE adicionando column, etc.), **automaticamente** adiciona ao plan uma tarefa final de handoff cooperativo para `supabase-rls-hardener`.
+
+**Heurística de detecção (regex):**
+
+```regex
+(create\s+table|create\s+policy|create\s+view|alter\s+table|create\s+function.*security\s+definer|grant\s+.*on|enable\s+row\s+level\s+security)
+```
+
+Se ≥ 1 match em qualquer tarefa do plan → injetar tarefa final:
+
+```markdown
+### Tarefa: Handoff cooperativo SQL para supabase-rls-hardener (v1.23)
+
+**Tipo:** Validation
+**Arquivos:** N/A (validation only)
+**Ação:** Invocar `Task(subagent_type=supabase-rls-hardener, prompt=<draft+intent>)` para cada bloco SQL gerado na fase. Processar verdict GO/STRENGTHEN/REWRITE.
+
+**Verify:** Output do hardener inclui verdict + SQL hardenado. Em STRENGTHEN/REWRITE, aplicar diff sugerido (se aceito pelo executor ou usuário humano).
+
+**Done:** Verdict GO atingido OU diff aplicado com sucesso OU REWRITE confirmado pelo usuário.
+```
+
+**Princípio canônico v1.23:** Planner pensa/planeja (estrutura do plan, decomposition, deps); supabase-rls-hardener materializa/hardena (SQL final). Plan não descarta intent — só adiciona camada de validação cooperativa.
+
+**Não bloqueia execução:** se hardener responde STRENGTHEN/REWRITE, executor absorve o feedback e aplica diff. Aborto silencioso é proibido.
+
+</sql_auto_handoff_cooperativo>

package/kit/agents/release-pipeline-auditor.md

@@ -335,6 +335,17 @@ Policy Enforcement:   <N>/10
 3. Re-audit em 30d para verificar progresso
 ```
 
+## Branching Workflow Validation (v1.27)
+
+Para projetos que adotaram Supabase Branching, o auditor verifica adicionalmente:
+
+- [ ] **Required check enforced:** repository settings → branches → main → required status checks inclui "Supabase Preview"
+- [ ] **Secrets stored:** SUPABASE_ACCESS_TOKEN, PRODUCTION_DB_PASSWORD, PRODUCTION_PROJECT_ID configurados em Settings → Secrets
+- [ ] **Migration safety pre-merge:** preview branch é criado antes de merge para main (não há push direto na main)
+- [ ] **Backup workflow não está em repo público:** se `backup.yml` existe E repo é público → BLOCK (warning canônico)
+
+Ver skill canônica: `kit/skills/supabase-ci-cd-github-actions/SKILL.md`.
+
 ## Quando NÃO invocar
 
 - Repo recém-criado (< 1 mês) — pipeline ainda imatura

package/kit/agents/supabase-architect.md

@@ -13,6 +13,20 @@ Você é o arquiteto Supabase. O caller (orquestrador, geralmente Claude) entreg
 
 Apps Supabase são fáceis de começar e difíceis de evoluir quando schema/RLS/topology realtime são improvisados. Decisões arquiteturais erradas no início (ex: tabela única vs particionada, RLS frouxa, broadcast vs postgres_changes) se tornam tech debt caro. Este agent força decisões explícitas **antes** da primeira migration.
 
+## Branching Strategy Decision (v1.27)
+
+Antes de projetar schema/RLS/topology, considerar a estratégia de branching que será usada:
+
+- **GitHub integration recomendada** vs Dashboard alpha (Dashboard tem caveats — ver skill `supabase-branching-workflow`)
+- **Persistent (staging/QA long-lived) vs ephemeral (preview auto-pause)**
+- **Cost alert:** Branching Compute Hours estão **FORA do Spend Cap** — Micro $0.01344/h, Compute Credits NÃO aplicam
+
+Se a estratégia ainda não foi decidida, delegar para `supabase-branching-architect` (cross-suite handoff) ANTES de prosseguir com schema design.
+
+Cross-suite handoff: invocar via `Task(subagent_type="supabase-branching-architect", ...)`.
+
+Ver skill canônica: `kit/skills/supabase-branching-workflow/SKILL.md`.
+
 ## Inputs esperados (do caller)
 
 - `feature_description`: descrição em texto livre (ex: "app de chat multi-room com presence", "RAG sobre documentos privados").
@@ -124,6 +138,23 @@ projeto: {project_id ou "novo"} · tier: {tier} · gerado em {timestamp}
 ## 5. Edge Functions / Background (se aplicável)
 {functions + cron pattern}
 
+## 5.1 Postgres Roles (v1.26 — ARCH-PATCH-01)
+
+**Pergunta canônica upfront:** Esta feature precisa de **service accounts internos** (custom Postgres roles)?
+
+Casos típicos:
+- Cron jobs com pg_cron (cleanup, retention) — recomenda role dedicado em vez de service_role API key
+- BI tools (Metabase, dbt) conectando direto no DB — recomenda role read-only com BYPASSRLS
+- ETL scripts (replication, backups) — recomenda role com permissions específicos
+- Admin roles para column-level GRANTs (security_admin, dpo_role, lead_manager)
+
+**Se sim, listar service accounts esperados:**
+- {role_name}: {description}, owner: {team_email}, type: {group|user}, bypassrls: {bool}
+
+**Cross-suite handoff:** delegar criação para `supabase-roles-implementer` (v1.26) na ordem de implementação.
+
+Para application access (end-users), usar **RLS + Custom Claims** (skill `supabase-custom-claims-rbac` v1.25) — NÃO criar Postgres roles para "admin vs user" end-users.
+
 ## 6. Ordem de Implementação
 {sequence numerada com agent delegate}
 

package/kit/agents/supabase-auth-bootstrapper.md

@@ -297,9 +297,89 @@ Auth events são SLI primário — "successful login %" é métrica de saúde di
 
 **Output adicionado:** seção "## Observability hooks" com snippet de span wrapper em handlers `/auth/*`.
 
+## Custom Claims & RBAC integration (v1.25 — AUTH-PATCH-01)
+
+Quando o projeto usa **RBAC via Custom Access Token Auth Hook** (skill `supabase-custom-claims-rbac` v1.25), este agent inclui no bootstrap:
+
+### 1. Dependency `jwt-decode`
+
+Adicionar ao `package.json`:
+
+```bash
+npm install jwt-decode
+```
+
+### 2. `utils/supabase/client.ts` — listener com decoder
+
+```ts
+import { createBrowserClient } from '@supabase/ssr'
+import { jwtDecode } from 'jwt-decode'
+
+export function createClient() {
+  const supabase = createBrowserClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
+  )
+
+  // listener para decodificar custom claims após login/refresh
+  supabase.auth.onAuthStateChange(async (event, session) => {
+    if (session) {
+      const jwt = jwtDecode<{ user_role?: string }>(session.access_token)
+      // userRole disponível para UI conditional rendering
+      // (use context provider para propagar — não documentado aqui)
+      console.log('User role from JWT:', jwt.user_role)
+    }
+  })
+
+  return supabase
+}
+```
+
+### 3. `utils/supabase/server.ts` — server-side decode
+
+```ts
+import { jwtDecode } from 'jwt-decode'
+
+export async function getUserRole() {
+  const supabase = await createClient()
+  const { data: { session } } = await supabase.auth.getSession()
+  if (!session) return null
+
+  const jwt = jwtDecode<{ user_role?: string }>(session.access_token)
+  return jwt.user_role ?? null
+}
+```
+
+### 4. Handoff cooperativo para `supabase-rbac-implementer`
+
+Quando caller sinaliza `enable_rbac: true` ou detecta tabela `user_roles` no projeto, faça handoff:
+
+```python
+Task(subagent_type="supabase-rbac-implementer", prompt=f"""
+<upstream_intent>
+Source agent: supabase-auth-bootstrapper
+Original goal: bootstrap Next.js v16 + Supabase Auth com RBAC via Custom Access Token Auth Hook
+Constraints: projeto novo Next.js v16; jwt-decode adicionado ao package.json; listener jwt decode adicionado em client.ts; helper getUserRole() adicionado em server.ts
+</upstream_intent>
+
+<roles>{caller_provided_roles or default ['admin', 'user']}</roles>
+<permissions_matrix>{caller_provided or default}</permissions_matrix>
+<multi_tenant>{caller_provided}</multi_tenant>
+<user_facing_caller>true</user_facing_caller>
+""")
+```
+
+**Caveats embutidos no bootstrap:**
+
+- ⚠ JWT freshness: mudanças em user_roles refletem após refresh (TTL 1h). Para revogação imediata, usar `auth.admin.signOut(userId)` no server-side com service_role.
+- ⚠ Auth hook deve ser habilitado no Dashboard (Authentication > Hooks Beta) ou config.toml local — esse setup não é automatizado pelo bootstrap (DDL do hook é feito pelo `supabase-rbac-implementer` mas o enable depende de UI/config).
+- ⚠ `jwt-decode` é apenas decode (NÃO valida assinatura) — para validação server-side, use `@supabase/ssr` `getUser()` que valida.
+
 ## Ver também
 
 - [supabase-auth-ssr](../skills/supabase-auth-ssr/SKILL.md) — base de conhecimento canônica
 - [supabase-rls-policies](../skills/supabase-rls-policies/SKILL.md) — RLS aplicado quando user autenticado consulta tabelas
+- [supabase-custom-claims-rbac](../skills/supabase-custom-claims-rbac/SKILL.md) (v1.25) — Custom Access Token Auth Hook + jwt-decode
+- [supabase-rbac-implementer](./supabase-rbac-implementer.md) (v1.25) — canonical handoff target para RBAC setup
 - [structured-events](../skills/structured-events/SKILL.md) — campos canônicos para auth events
 - [event-based-slos](../skills/event-based-slos/SKILL.md) *(Phase 32)* — SLO de "successful login %"