wizz-method 2.1.1 → 2.3.0

package/src/skills-lib/wizz-inicio-de-projeto/SKILL.md

@@ -1,95 +1,95 @@
 ---
 name: wizz-inicio-de-projeto
 description: >
-  Ponto de partida para projetos novos ou novas features. Usar quando: iniciar um projeto web, criar um novo módulo/feature,
-  precisar de padrões de arquitetura, definir estrutura de pastas, estabelecer regras de código, começar um app SaaS/produto,
-  onboarding de desenvolvedor no projeto. Contém princípios de produto, padrões arquiteturais P0-P3, regras de código,
-  stack (Next.js + Supabase + Clerk + Zod), estrutura de pastas e checklist de início.
-  Use quando o pedido for começar um projeto novo, criar um módulo/feature do zero, ou definir
-  arquitetura, stack e estrutura de pastas antes de codar.
+  Starting point for new projects or new features. Use when: starting a web project, creating a new module/feature,
+  needing architecture standards, defining folder structure, establishing code rules, starting a SaaS app/product,
+  or onboarding a developer to the project. Contains product principles, P0-P3 architectural patterns, code rules,
+  stack (Next.js + Supabase + Clerk + Zod), folder structure, and a kickoff checklist.
+  Use when the request is to start a new project, create a module/feature from scratch, or define
+  architecture, stack, and folder structure before coding.
 ---
 
-# Início de Projeto — Padrões de Engenharia
+# Project Kickoff — Engineering Standards
 
-Você é um engenheiro de software sênior especializado em desenvolvimento web moderno com TypeScript, React 19,
-Next.js (App Router), shadcn/ui e Supabase. Atencioso, preciso e focado em soluções que duram.
+You are a senior software engineer specialized in modern web development with TypeScript, React 19,
+Next.js (App Router), shadcn/ui, and Supabase. Attentive, precise, and focused on solutions that last.
 
-Consulte este guia no início de qualquer projeto ou feature nova. Preencha as seções marcadas com `[PREENCHER]`
-com os dados do projeto específico antes de começar a codar.
+Consult this guide at the start of any project or new feature. Fill in the sections marked `[FILL IN]`
+with the specific project's data before starting to code.
 
-## Princípios de Produto (sempre aplicar)
+## Product Principles (always apply)
 
-| Código | Princípio | Regra prática |
+| Code | Principle | Practical rule |
 |--------|-----------|---------------|
-| P-001 | **Linguagem do domínio** | UI fala o idioma do usuário — nunca "entidade", "registro", "submeter", "payload" |
-| P-002 | **Mobile-first real** | Tela primária = celular em contexto real. Web = versão adaptada para escritório |
-| P-003 | **Defaults inteligentes / auto-save** | Usuário não clica "Salvar" durante rascunho. Uma decisão no fim: "Concluir" ou "Descartar" |
-| P-004 | **Filtragem proativa** | Mostrar só itens elegíveis para a ação — nunca mostrar tudo e alertar depois |
-| P-005 | **Validação no servidor** | Cliente é cosmético. Toda regra de negócio re-validada no backend com Zod |
-| P-006 | **Estado na URL** | Filtros, seleção, aba ativa e etapa de wizard em query params. F5 mantém estado |
-| P-007 | **Soft delete e auditoria** | Nada é apagado. `deleted_at timestamp` em toda tabela de domínio. Eventos críticos em `audit_logs` |
+| P-001 | **Domain language** | The UI speaks the user's language — never "entity", "record", "submit", "payload" |
+| P-002 | **Real mobile-first** | Primary screen = phone in a real context. Web = office-adapted version |
+| P-003 | **Smart defaults / auto-save** | The user doesn't click "Save" during a draft. One decision at the end: "Finish" or "Discard" |
+| P-004 | **Proactive filtering** | Show only items eligible for the action — never show everything and warn afterward |
+| P-005 | **Server-side validation** | The client is cosmetic. Every business rule is re-validated on the backend with Zod |
+| P-006 | **State in the URL** | Filters, selection, active tab, and wizard step live in query params. F5 preserves state |
+| P-007 | **Soft delete and audit** | Nothing is deleted. `deleted_at timestamp` on every domain table. Critical events in `audit_logs` |
 
-## Contexto do Projeto
+## Project Context
 
 ```
-Nome: [PREENCHER]
-Objetivo: [PREENCHER — 3-5 linhas: o que resolve, para quem, diferencial]
+Name: [FILL IN]
+Goal: [FILL IN — 3-5 lines: what it solves, for whom, differentiator]
 Personas:
-  - A-001 [PREENCHER — quem usa, contexto, fluência digital]
-  - A-002 [PREENCHER]
-  - A-003 [PREENCHER — persona crítica, quem usa mais em condições adversas]
-MVP: [PREENCHER — módulos, escopo single/multi-tenant]
+  - A-001 [FILL IN — who uses it, context, digital fluency]
+  - A-002 [FILL IN]
+  - A-003 [FILL IN — critical persona, who uses it most under adverse conditions]
+MVP: [FILL IN — modules, single/multi-tenant scope]
 ```
 
-> **Pendências críticas:** ao encontrar uma decisão que bloqueia implementação, registre aqui e pergunte ao usuário antes de assumir um default.
+> **Critical open items:** when you find a decision that blocks implementation, log it here and ask the user before assuming a default.
 
-## Stack do Projeto
+## Project Stack
 
-| Categoria | Tecnologia |
+| Category | Technology |
 |-----------|------------|
 | Framework | Next.js (App Router) |
 | UI | React 19, Tailwind CSS, shadcn/ui |
-| Linguagem | TypeScript (obrigatório) |
+| Language | TypeScript (required) |
 | Auth | Clerk |
-| Banco | Supabase (PostgreSQL) |
-| Validação | Zod |
-| Formulários | React Hook Form + Zod |
+| Database | Supabase (PostgreSQL) |
+| Validation | Zod |
+| Forms | React Hook Form + Zod |
 | Data Fetching | React Query (@tanstack/react-query) |
-| Data/Hora | dayjs |
-| Notificações | Sonner |
-| Ícones | @tabler/icons-react ou lucide-react |
-| Mascaras | react-number-format |
+| Date/Time | dayjs |
+| Notifications | Sonner |
+| Icons | @tabler/icons-react or lucide-react |
+| Input masks | react-number-format |
 
-## Glossário do Domínio
+## Domain Glossary
 
-> Crítico: toda label, mensagem, botão e erro usa estes termos — nunca termos técnicos de software.
+> Critical: every label, message, button, and error uses these terms — never generic software terms.
 
 ```
-[PREENCHER — ex:]
-  extração → busca de leads
-  workspace → empresa / conta
-  crédito → crédito de extração
-
-Termos PROIBIDOS na UI (genéricos):
-  "registro", "entidade", "submeter", "validação", "transação", "objeto",
-  "instância", "tenant", "request", "payload", "null", "undefined", "erro 500"
+[FILL IN — e.g.:]
+  extração → lead search
+  workspace → company / account
+  crédito → search credit
+
+FORBIDDEN terms in the UI (generic):
+  "registro" (record), "entidade" (entity), "submeter" (submit), "validação" (validation), "transação" (transaction), "objeto" (object),
+  "instância" (instance), "tenant", "request", "payload", "null", "undefined", "erro 500" (error 500)
 ```
 
-## References (carregar sob demanda)
+## References (load on demand)
 
-- `references/padroes-arquiteturais-e-pastas.md` — os 4 padrões arquiteturais P0-P3 (ciclo de vida com rascunho, cascatas, estado calculado, dashboards) e a estrutura de pastas completa do projeto. Carregar ao mapear um módulo novo ou criar a estrutura inicial.
-- `references/implementacao-api-forms.md` — padrões de código para API routes (Supabase + Zod + rate limit), schemas Supabase (RLS, soft delete), formulários (React Hook Form + Zod) e estado na URL (P-006). Carregar ao escrever uma rota, tabela ou formulário.
-- `references/seguranca-e-regras-codigo.md` — checklist de segurança embutida (resumo; ver skill `wizz-web-security` para a versão completa) e as regras de código do projeto (TypeScript, naming, tamanho de arquivo/função, imutabilidade). Carregar antes de finalizar qualquer PR.
+- `references/padroes-arquiteturais-e-pastas.md` — the 4 P0-P3 architectural patterns (lifecycle with draft, cascades, computed state, dashboards) and the project's complete folder structure. Load when mapping a new module or creating the initial structure.
+- `references/implementacao-api-forms.md` — code patterns for API routes (Supabase + Zod + rate limit), Supabase schemas (RLS, soft delete), forms (React Hook Form + Zod), and state in the URL (P-006). Load when writing a route, table, or form.
+- `references/seguranca-e-regras-codigo.md` — built-in security checklist (summary; see the `wizz-web-security` skill for the full version) and the project's code rules (TypeScript, naming, file/function size, immutability). Load before finalizing any PR.
 
-## Checklist de Início de Projeto
+## Project Kickoff Checklist
 
-- [ ] Glossário de domínio preenchido (termos do usuário, termos proibidos)
-- [ ] Personas definidas (especialmente A-003, quem usa em condições adversas)
-- [ ] Cada módulo mapeado a um padrão P0/P1/P2/P3
-- [ ] RLS configurado nas tabelas Supabase
-- [ ] `.env.example` criado (sem valores reais) e `.env*` no `.gitignore`
-- [ ] Headers de segurança em `next.config.ts`
-- [ ] `enforceRateLimit` nos endpoints de escrita/cobrança
-- [ ] Auto-save implementado para módulos P0 (debounce 300ms)
-- [ ] Estado em URL para filtros/abas/etapas (P-006)
-- [ ] `deleted_at` em tabelas de domínio (P-007)
+- [ ] Domain glossary filled in (user terms, forbidden terms)
+- [ ] Personas defined (especially A-003, who uses it under adverse conditions)
+- [ ] Each module mapped to a P0/P1/P2/P3 pattern
+- [ ] RLS configured on Supabase tables
+- [ ] `.env.example` created (no real values) and `.env*` in `.gitignore`
+- [ ] Security headers in `next.config.ts`
+- [ ] `enforceRateLimit` on write/billing endpoints
+- [ ] Auto-save implemented for P0 modules (300ms debounce)
+- [ ] State in URL for filters/tabs/steps (P-006)
+- [ ] `deleted_at` on domain tables (P-007)

package/src/skills-lib/wizz-inicio-de-projeto/references/implementacao-api-forms.md

@@ -1,10 +1,10 @@
-# Padrões de Implementação: API Routes, Schemas Supabase, Formulários, Estado na URL
+# Implementation Patterns: API Routes, Supabase Schemas, Forms, State in the URL
 
-Carregue este arquivo ao escrever uma rota de API, uma tabela Supabase, um formulário, ou ao implementar estado em query params.
+Load this file when writing an API route, a Supabase table, a form, or when implementing state in query params.
 
-## Padrões de API Routes (Supabase + Zod)
+## API Route patterns (Supabase + Zod)
 
-Toda rota de API que recebe input de usuário:
+Every API route that receives user input:
 ```ts
 // src/app/api/[modulo]/route.ts
 import { auth } from "@clerk/nextjs/server"
@@ -28,42 +28,42 @@ export async function POST(request: Request) {
   const parsed = schema.safeParse(body)
   if (!parsed.success) return fail("Dados inválidos", 400)
 
-  // lógica de negócio aqui — revalidar regras de negócio no servidor (P-005)
+  // business logic here — revalidate business rules on the server (P-005)
 }
 ```
 
-**Regras de API routes:**
-- SEMPRE valide com Zod (`.safeParse()` ou `.parse()`)
-- SEMPRE filtre por `workspace_id` nas queries Supabase
-- NUNCA confie em cálculos do cliente — recalcule no server
-- NUNCA vaze detalhes internos em mensagens de erro
-- Webhooks SEMPRE verificam assinatura antes de processar o body
+**API route rules:**
+- ALWAYS validate with Zod (`.safeParse()` or `.parse()`)
+- ALWAYS filter by `workspace_id` in Supabase queries
+- NEVER trust client-side calculations — recalculate on the server
+- NEVER leak internal details in error messages
+- Webhooks ALWAYS verify the signature before processing the body
 
-## Schemas Supabase (padrões)
+## Supabase schemas (patterns)
 
-Toda tabela de domínio:
+Every domain table:
 ```sql
 CREATE TABLE [modulo] (
   id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
   workspace_id uuid NOT NULL REFERENCES workspaces(id),
-  -- campos do domínio
+  -- domain fields
   deleted_at timestamp,          -- soft delete (P-007)
   created_at timestamp NOT NULL DEFAULT now(),
   updated_at timestamp NOT NULL DEFAULT now()
 );
 
--- RLS obrigatório
+-- RLS mandatory
 ALTER TABLE [modulo] ENABLE ROW LEVEL SECURITY;
 CREATE POLICY "workspace_isolation" ON [modulo]
   USING (workspace_id = (SELECT workspace_id FROM workspace_members WHERE user_id = auth.uid()));
 ```
 
-**Regras de dados:**
-- Valores monetários SEMPRE em centavos (integer). Display com `formatCurrency()`
-- Unidades físicas SEMPRE na menor unidade (integer) no banco
-- Datas como `timestamp` (UTC). Display com dayjs no locale do usuário
+**Data rules:**
+- Monetary values ALWAYS in cents (integer). Display with `formatCurrency()`
+- Physical units ALWAYS in the smallest unit (integer) in the database
+- Dates as `timestamp` (UTC). Display with dayjs in the user's locale
 
-## Formulários (React Hook Form + Zod)
+## Forms (React Hook Form + Zod)
 
 ```tsx
 "use client"
@@ -85,7 +85,7 @@ export function MeuForm() {
       method: "POST",
       body: JSON.stringify(data),
     })
-    // tratar resposta
+    // handle the response
   }
 
   return (
@@ -96,17 +96,17 @@ export function MeuForm() {
 }
 ```
 
-## Estado na URL (P-006)
+## State in the URL (P-006)
 
 ```ts
-// Filtros, abas, paginação sempre em query params
-// F5 mantém estado, link é compartilhável
+// Filters, tabs, pagination always in query params
+// F5 preserves state, the link is shareable
 
-// Exemplos de hooks canônicos:
+// Examples of canonical hooks:
 useUrlState<"ativo" | "inativo">("status", "ativo")
 useUrlListState("categoria")        // ?categoria=A,B
 useUrlDateRange("criado")          // ?criadoDe=...&criadoAte=...
 
-// Wizard multi-etapa: ?etapa=1
-// Só persistir etapas navegáveis, não estados transientes (loading, sucesso)
+// Multi-step wizard: ?etapa=1
+// Only persist navigable steps, not transient states (loading, success)
 ```

package/src/skills-lib/wizz-inicio-de-projeto/references/padroes-arquiteturais-e-pastas.md

@@ -1,71 +1,71 @@
-# Padrões Arquiteturais (P0-P3) e Estrutura de Pastas
+# Architectural Patterns (P0-P3) and Folder Structure
 
-Carregue este arquivo ao mapear um módulo novo a um padrão arquitetural, ou ao criar a estrutura de pastas do projeto.
+Load this file when mapping a new module to an architectural pattern, or when creating the project's folder structure.
 
-## Padrões Arquiteturais
+## Architectural Patterns
 
-Mapeie cada módulo a um padrão antes de codar.
+Map each module to a pattern before coding.
 
-### P0 — Ciclo de Vida com Rascunho
-Para fluxos onde o usuário monta dados em etapas e decide no fim.
+### P0 — Draft Lifecycle
+For flows where the user builds up data in steps and decides at the end.
 
-**Estados:** `rascunho` → `confirmado` → `estornado` | `descartado`
+**States:** `rascunho` (draft) → `confirmado` (confirmed) → `estornado` (reversed) | `descartado` (discarded)
 
-**Auto-save (P-003):** rascunho persiste a cada alteração (debounce 300ms). Sem botão "Salvar". Decisão única: **Concluir** ou **Descartar**.
+**Auto-save (P-003):** the draft persists on every change (300ms debounce). No "Save" button. Single decision: **Complete** or **Discard**.
 
-**Filtragem proativa (P0.5):** tela de seleção só mostra itens elegíveis. Não confiar em validação depois.
+**Proactive filtering (P0.5):** the selection screen only shows eligible items. Don't rely on validation afterward.
 
-Enum Supabase:
+Supabase enum:
 ```sql
 CREATE TYPE status_workflow AS ENUM ('rascunho', 'confirmado', 'descartado', 'estornado');
 ```
 
-### P1 — Operações com Cascatas
-Confirmação dispara cascatas em outros módulos. Toda cascata na MESMA transação (RPC Supabase). Falha em qualquer cascata = rollback completo.
+### P1 — Operations with Cascades
+Confirmation triggers cascades in other modules. Every cascade in the SAME transaction (Supabase RPC). Failure in any cascade = full rollback.
 
-### P2 — Lançamentos com Estado Calculado
-NÃO armazenar estado — calcular em runtime a partir de datas/saldos. Movimentações são append-only (nunca update, apenas insert).
+### P2 — Entries with Calculated State
+Do NOT store state — calculate it at runtime from dates/balances. Movements are append-only (never update, only insert).
 
-### P3 — Telas Analíticas (Dashboards)
-Read-only. Cache de 5-15 min para KPIs pesados, ≤1 min para KPIs operacionais. Mobile-first prioriza KPIs operacionais acima do fold.
+### P3 — Analytical Screens (Dashboards)
+Read-only. Cache of 5-15 min for heavy KPIs, ≤1 min for operational KPIs. Mobile-first prioritizes operational KPIs above the fold.
 
-## Estrutura de Pastas
+## Folder Structure
 
 ```
 src/
 ├── app/
-│   ├── (auth)/                    # rotas públicas (login, signup)
+│   ├── (auth)/                    # public routes (login, signup)
 │   ├── (app)/
-│   │   ├── dashboard/             # P3 — analítico
+│   │   ├── dashboard/             # P3 — analytical
 │   │   ├── [modulo]/
 │   │   │   ├── page.tsx
 │   │   │   └── [id]/page.tsx
 │   │   └── configuracoes/
 │   └── api/
 │       ├── [modulo]/
-│       │   └── route.ts           # validação Zod + lógica de negócio
-│       └── webhooks/              # sempre verificar assinatura antes de processar
+│       │   └── route.ts           # Zod validation + business logic
+│       └── webhooks/              # always verify the signature before processing
 ├── components/
-│   ├── ui/                        # shadcn/ui base (não editar)
-│   └── [modulo]/                  # componentes de domínio reutilizáveis
+│   ├── ui/                        # shadcn/ui base (do not edit)
+│   └── [modulo]/                  # reusable domain components
 ├── features/
 │   └── [modulo]/
-│       ├── components/            # componentes específicos do módulo
-│       ├── services/              # lógica de negócio (chamadas Supabase)
-│       └── hooks/                 # React Query hooks do módulo
+│       ├── components/            # module-specific components
+│       ├── services/              # business logic (Supabase calls)
+│       └── hooks/                 # the module's React Query hooks
 ├── hooks/
 │   ├── queries/                   # use-[entidade].ts
 │   ├── mutations/                 # use-[acao].ts
-│   └── use-url-state.ts           # estado em URL (P-006)
+│   └── use-url-state.ts           # URL state (P-006)
 ├── lib/
 │   ├── supabase/
-│   │   ├── client.ts              # client browser
-│   │   └── server.ts              # client server (service role — apenas server-side)
+│   │   ├── client.ts              # browser client
+│   │   └── server.ts              # server client (service role — server-side only)
 │   ├── api/
 │   │   ├── response.ts            # ok() / fail() helpers
-│   │   └── handle-route-error.ts  # mensagens seguras (não vazar detalhes internos)
+│   │   └── handle-route-error.ts  # safe messages (don't leak internal details)
 │   ├── security/
 │   │   └── rate-limit.ts          # enforceRateLimit helper
 │   └── format/                    # formatCurrency, formatDate, etc.
-└── types/                         # interfaces e tipos compartilhados
+└── types/                         # shared interfaces and types
 ```

package/src/skills-lib/wizz-inicio-de-projeto/references/seguranca-e-regras-codigo.md

@@ -1,26 +1,26 @@
-# Segurança e Regras de Código
+# Security and Code Rules
 
-Carregue este arquivo antes de finalizar qualquer PR — checklist de segurança embutida e convenções de código do projeto.
+Load this file before finalizing any PR — built-in security checklist and the project's code conventions.
 
-## Segurança (embutida por padrão)
+## Security (built in by default)
 
-Ver skill `wizz-web-security` para checklist completa. Resumo:
-- Validação Zod em TODOS os endpoints que recebem input
-- `enforceRateLimit` em endpoints de escrita, cobrança, operações caras
-- Comparação de tokens/secrets com `crypto.timingSafeEqual` (nunca `===`)
-- Soft delete via `deleted_at` em toda tabela de domínio
-- Logs de auditoria append-only para eventos críticos
-- `.env*` nunca commitado; secrets via variáveis de ambiente da plataforma
-- `SUPABASE_SERVICE_ROLE_KEY` apenas server-side
+See the `wizz-web-security` skill for the full checklist. Summary:
+- Zod validation on ALL endpoints that receive input
+- `enforceRateLimit` on write, billing, and expensive-operation endpoints
+- Compare tokens/secrets with `crypto.timingSafeEqual` (never `===`)
+- Soft delete via `deleted_at` on every domain table
+- Append-only audit logs for critical events
+- `.env*` never committed; secrets via the platform's environment variables
+- `SUPABASE_SERVICE_ROLE_KEY` server-side only
 
-## Regras de Código
+## Code Rules
 
-- SEMPRE TypeScript. Sem `any` explícito.
-- Nomes descritivos: `isLoading`, `hasError`, `handleConfirmarAcao`
-- **kebab-case** para arquivos e pastas: `confirmar-acao.ts`
-- SOLID e Clean Code; funções < 50 linhas; arquivos < 800 linhas
-- DRY: componentes reutilizáveis para padrões repetidos
-- NUNCA escreva comentários no código
-- NUNCA rode `npm run dev` para testar TypeScript — use `npx tsc --noEmit`
-- Imutabilidade: SEMPRE crie novos objetos, NUNCA mutate (spread, map, filter)
-- Sem `console.log` em produção
+- ALWAYS TypeScript. No explicit `any`.
+- Descriptive names: `isLoading`, `hasError`, `handleConfirmarAcao`
+- **kebab-case** for files and folders: `confirmar-acao.ts`
+- SOLID and Clean Code; functions < 50 lines; files < 800 lines
+- DRY: reusable components for repeated patterns
+- NEVER write comments in the code
+- NEVER run `npm run dev` to test TypeScript — use `npx tsc --noEmit`
+- Immutability: ALWAYS create new objects, NEVER mutate (spread, map, filter)
+- No `console.log` in production