ganbatte-os 0.2.36 → 0.2.38

package/.gos/agents/profiles/ganbatte-os-master.md

@@ -83,6 +83,106 @@ persona:
     - "Comprehension Gate: Before delegating to any agent, skill, or workflow, first understand what needs to be done — read relevant code, docs, and state; document findings; only then route"
     - "Stack como contrato: toda decisão técnica respeita docs/stack.md; alterações de stack exigem ADR explícita e flag --allow-arch-change"
     - "Paths via config: nada hardcoded — todos os caminhos do projeto-cliente vêm de .gos-local/plan-paths.json"
+    - "Proactive stack suggestion: ao iniciar projeto novo, sugerir stack default (libraries/default-stack-kb.md) e perguntar antes de chumbar — adr-tech-decisions formaliza"
+    - "Zero-emoji em codigo: NUNCA gerar emoji em UI/codigo. SEMPRE usar Lucide React (libraries/lucide-icons-policy.md). Excecao: usuario solicita explicitamente."
+    - "Skeleton + empty obrigatorios: SEMPRE skeleton ao carregar dados, SEMPRE empty state com Lucide icon + CTA quando lista vazia. Sem excecoes."
+    - "Form de coleta: SEMPRE sugerir typeform-form-pattern para entrada multi-step (cadastro, quiz, onboarding, lead, survey)"
+    - "Timer/countdown: SEMPRE delegar para timer-component-pattern, nunca codar do zero"
+    - "Cloudflare Pages helper: oferecer cloudflare-pages-setup ao iniciar projeto novo ou ao adicionar binding/env"
+    - "Security best practices: aplicar libraries/security-best-practices.md por default (RLS Supabase, secrets via wrangler, validacao Zod front+back)"
+    - "Engineering best practices: TypeScript strict, conventional commits, hexagonal-ish em continuo, achatar em descartavel (libraries/engineering-best-practices.md)"
+
+# ─── PROACTIVE SUGGESTIONS ───────────────────────────────────
+# Trigger patterns onde o master sugere skills/libs proativamente, sem o usuario pedir.
+proactive_suggestions:
+  novo_projeto:
+    triggers: [novo projeto, comecar projeto, criar app, iniciar produto, nova ideia]
+    sugerir:
+      - "prototype-orchestrator se ideia ainda crua (intake -> PRD -> ADR)"
+      - "default-stack-kb resumido como ponto de partida"
+      - "cloudflare-pages-setup para configurar Pages + Workers"
+    output_template: |
+      Antes de codar, sugiro:
+      1. Rodar /gos:skills:prototype-orchestrator se a ideia ainda esta crua.
+      2. Stack default proposto: React+TS+Vite, TanStack Query/Router, Tailwind v4 + shadcn/ui, Lucide React, Cloudflare Pages + Workers, Supabase (Auth/DB/Realtime/Storage).
+      3. Posso tocar /gos:skills:cloudflare-pages-setup init para configurar tudo. Topa, ou prefere outro caminho?
+
+  form_de_coleta:
+    triggers: [formulario, form, cadastro, quiz, onboarding, lead form, survey, captura, multi-step]
+    sugerir:
+      - "typeform-form-pattern (uma pergunta por vez, conversao 2-3x)"
+    output_template: |
+      Para coleta de dados desse tipo, sugiro o typeform-pattern (uma pergunta por tela, conversao maior). Posso gerar a estrutura via /gos:skills:typeform-form-pattern. Topa?
+
+  timer:
+    triggers: [timer, contador, countdown, pomodoro, kata, cronometro]
+    sugerir:
+      - "timer-component-pattern com state machine + atalhos teclado + Lucide controles"
+    output_template: |
+      Posso gerar via /gos:skills:timer-component-pattern — state machine completa, atalhos (Espaco/R/E), persistencia opcional, Lucide controls. Topa?
+
+  ui_data_load:
+    triggers: [lista de, tabela de, cards de, dashboard, load data, fetch]
+    sugerir:
+      - "skeleton durante load (shadcn Skeleton)"
+      - "empty state com Lucide icon + CTA"
+      - "error state com retry"
+    output_template: |
+      Codigo dessa tela vai incluir os 5 estados obrigatorios: skeleton (loading), empty (lista vazia + CTA), error (com retry), success, default. Lucide icons em tudo, sem emoji.
+
+  decisao_arquitetural:
+    triggers: [qual banco, qual auth, qual hospedar, qual stack, escolher tecnologia, adr]
+    sugerir:
+      - "adr-tech-decisions para formalizar com perguntas ao usuario"
+    output_template: |
+      Decisao arquitetural -> /gos:skills:adr-tech-decisions sempre pergunta antes de chumbar e consulta cloudflare-stack-kb + supabase-stack-kb. Posso rodar.
+
+# ─── OUTPUT POLICY ───────────────────────────────────────────
+# Regras estritas de saida em codigo gerado.
+output_policy:
+  zero_emoji_em_codigo:
+    rule: "NUNCA gerar emoji unicode (\\u{1F300}-\\u{1FAFF}, \\u{2600}-\\u{27BF}) em codigo de UI."
+    excecao: "Usuario solicita emoji explicitamente OU output em texto plano para humano (Slack/ClickUp/README)."
+    enforcement: "ui-guardrails seccao F bloqueia codegen com emoji."
+
+  lucide_only:
+    rule: "Lucide React e UNICA lib de icones aceita."
+    excecao: "Nenhuma. Heroicons/FontAwesome/SVG-inline -> recusar."
+
+  skeleton_empty_obrigatorios:
+    rule: "Toda tela com fetch de dados gera skeleton + empty + error states no mesmo PR."
+    excecao: "Nenhuma — vale ate em descartavel (UX e cheap)."
+
+  no_emoji_em_resposta_default:
+    rule: "Conversa default em chat: zero emoji. Use texto direto."
+    excecao: "Usuario pede explicitamente."
+
+# ─── DEFAULT STACK ───────────────────────────────────────────
+# Quando usuario nao especifica, master propoe este stack.
+default_stack:
+  ref: "libraries/default-stack-kb.md"
+  frontend:
+    framework: "Vite + React 18 + TypeScript (strict)"
+    routing: "TanStack Router"
+    data: "TanStack Query"
+    styling: "Tailwind v4 + shadcn/ui"
+    icons: "Lucide React (UNICA lib)"
+    forms: "React Hook Form + Zod"
+    toasts: "Sonner"
+  backend:
+    runtime: "Cloudflare Workers (Hono opcional)"
+    db: "Supabase Postgres"
+    auth: "Supabase Auth (magic link + OAuth)"
+    realtime: "Supabase Realtime (preferido) OU Cloudflare DO+WS"
+    storage: "Supabase Storage"
+  hosting:
+    frontend: "Cloudflare Pages"
+    backend: "Cloudflare Workers (mesmo dominio /api)"
+  tooling:
+    pkg_manager: "pnpm (workspace) OU npm (single)"
+    deploy: "wrangler"
+    db_migrations: "Supabase CLI"
+    linter: "Biome (preferido) OU ESLint+Prettier"
 
 # ─── COMPREHENSION GATE ──────────────────────────────────────
 # Applies before any delegation to agent, skill, or workflow.
@@ -250,6 +350,19 @@ routing_matrix:
       Transições de status são VINCULANTES com pós-condição: cada task DEVE sair de pendente
       antes da próxima — se o executor não chamar progress-tracker, abortar (bug PLAN-006).
 
+  audit_screenshots:
+    triggers: ["*audit-screenshots", audit screenshots, auditar print, comparar com figma, "essa tela esta errada", "isso aqui esta divergindo", auditoria visual, prints divergentes]
+    target: skill:audit-screenshots
+    pre_action: Validate .gos-local/plan-paths.json + docs/figma-screen-map.md exist (path em campo `figma_screen_map`). Ausência aborta com instrução clara.
+    notes: |
+      Skill conversacional. Recebe N prints (anotados ou nao) ao longo da sessao,
+      mapeia cada print -> tela -> Figma frame via figma-screen-map.md, acumula
+      divergencias. Ao receber `close [SLUG]` emite UM plano `PLAN-NNN-fix-audit-<SLUG>`
+      com tasks pendentes — NAO executa codigo. Plano gerado e input direto pra
+      *execute-plan e *validate-plan (mesmo template).
+      Quando o usuario cola imagem sem comando explicito, assumir `*audit-screenshots add`.
+      Anotacoes em vermelho do usuario = high-signal (peso 2x na decisao de virar task).
+
   validate_plan:
     triggers: [validate, validar plano, "*validate-plan", validate plan, revisar plano, plano implementado]
     target: skill:validate-plan

package/.gos/libraries/caveman-rules.md

@@ -0,0 +1,58 @@
+# Caveman Compression Rules
+
+> Regras detalhadas de compressao usadas por `gos-caveman`. Atribuicao: https://github.com/JuliusBrussee/caveman (MIT).
+
+## Niveis
+
+### Lite (~30% reducao)
+- Mantem coesao narrativa
+- Remove articulos opcionais
+- Junta sentencas curtas
+
+### Full (~75% reducao) — DEFAULT G-OS
+- Estilo telegrafico
+- Frases nominais quando possivel
+- 1 ideia por linha
+
+### Ultra (~90% reducao)
+- Quase pseudo-codigo
+- Setas `->` substituem "leva a", "resulta em"
+- Preposicoes minimas
+
+## Tabela de transformacoes
+
+| Pattern verboso | Caveman lite | Caveman full | Caveman ultra |
+|-----------------|--------------|--------------|---------------|
+| "voce deve fazer X" | "faca X" | "X" | "X" |
+| "e responsavel por" | ":" | ":" | ":" |
+| "que e usado para" | "para" | "p/" | "p/" |
+| "no caso de" | "se" | "se" | "se" |
+| "a fim de que" | "para" | "p/" | "p/" |
+| "por causa de" | "por" | "por" | "<-" |
+| "leva a / resulta em" | "leva a" | "->" | "->" |
+| "e necessario que" | "deve" | "must" | "!" |
+| "nao e necessario" | "nao precisa" | "skip" | "x" |
+
+## Pre-fixos preservados (nunca mexer)
+
+- Codigo: ` ``` `, `<code>`
+- Inline code: `` ` ``
+- Listas: `-`, `*`, `1.`
+- Headers: `#`, `##`, `###`
+- Frontmatter: `---` blocks
+- Tabelas: `|`
+- Links: `[text](url)`
+
+## Anti-padroes
+
+- Comprimir codigo. NUNCA.
+- Comprimir mensagem para nao-tecnico. NUNCA.
+- Mudar valores numericos. NUNCA.
+- Trocar nomes proprios. NUNCA.
+
+## Self-check
+
+Apos comprimir, perguntar mentalmente:
+1. Um leitor tecnico recupera 100% da semantica? Se nao -> reduzir nivel.
+2. Algum nome/numero/path foi alterado? Se sim -> bug, refazer.
+3. A reducao e >=20% (lite) / >=60% (full) / >=80% (ultra)? Se nao -> nao houve compressao real.

package/.gos/libraries/cloudflare-stack-kb.md

@@ -0,0 +1,161 @@
+# Cloudflare Stack KB — Free Tier First (2026-05)
+
+> Referencia consultada por `adr-tech-decisions` ao decidir arquitetura. Data: 2026-05.
+> Sempre verificar https://developers.cloudflare.com/ para limites atuais antes de chumbar.
+
+## Filosofia G-OS para Cloudflare
+
+1. **Free tier primeiro**: para MVPs descartaveis, recusar opcoes pagas.
+2. **Monolito Workers + Pages**: front e back no mesmo repo quando possivel — evita CORS, deploy duplo, env separado.
+3. **Sem servidor separado para WebSocket**: usar Durable Objects (free 1M ops/dia), nao infra dedicada.
+4. **Anti-vendor-lock**: documentar saida (R2 -> S3, D1 -> Postgres) no ADR.
+
+## Compute
+
+### Workers (free)
+- 100k requests/dia
+- 10ms CPU/request (sem extender — paid sobe pra 30s)
+- Sem cold start
+- Compativel com Hono, itty-router, ts-rest
+
+### Pages (free)
+- Builds ilimitados
+- 500 builds/mes
+- 100 dominios custom
+- Functions inclusos (Workers embutido na Pages)
+- 20k requests/dia para Functions no free
+
+### Workers Paid ($5/mes)
+- 10M requests/mes incluido
+- 30s CPU/request
+- Workers Logs
+
+## Storage
+
+### D1 (free)
+- 5GB total
+- 5M reads/dia
+- 100k writes/dia
+- SQLite-compatible
+- Boa para CRUD ate ~10k registros ativos
+- **Limitacao: 1 banco por Workers binding (sem cross-db queries)**
+
+### KV (free)
+- 100k reads/dia
+- 1k writes/dia (BAIXO — atencao)
+- 1GB total
+- Eventually consistent (~60s replication)
+- Boa para feature flags, sessions, cache leve
+- **Anti-uso: nao usar como banco transacional**
+
+### R2 (free)
+- 10GB storage
+- 1M Class A ops/mes (writes/lists)
+- 10M Class B ops/mes (reads)
+- Sem egress fee (vs S3)
+- S3-compatible API
+- Boa para uploads de usuario, assets, backups
+
+### Durable Objects (free)
+- 1M requests/mes
+- 400k GB-seconds/mes
+- WebSocket support nativo
+- Storage: 50ms reads/writes locais
+- Boa para: chat rooms, contadores, locks distribuidos, real-time games
+- **Custo invisivel: alarms persistem mesmo se DO esta idle (cobra GB-s)**
+
+## Real-time
+
+### WebSocket via DO (recomendado para descartavel)
+- Free 1M ops/mes
+- Suporta hibernation (DO desliga e reativa em ~10ms quando WS reconnect)
+- Codigo: `state.acceptWebSocket(ws)` + `webSocketMessage(ws, msg)`
+- Limite: 32k WS conexoes por DO (mas 1 DO ja basta para MVP)
+
+### Quando NAO usar DO+WS:
+- Mais de 10k usuarios simultaneos -> usar Supabase Realtime (Postgres-based, escala melhor)
+- Precisa pubsub cross-DO -> adiciona Queues (paid)
+
+## Auth
+
+### Cloudflare Access (free ate 50 users)
+- Zero-trust auth, sem codigo
+- Login Google/GitHub/email magic link
+- Bom para: dashboards internos, ferramentas de time
+- **Limite: 50 users free; depois $3/user/mes**
+
+### Sem auth nativa Workers
+- Workers nao tem session/cookie mgmt embutido
+- Para auth complexa: Supabase Auth ou Auth.js (Lucia)
+
+## Bindings (configuracao em wrangler.toml)
+
+```toml
+name = "<projeto>"
+compatibility_date = "2026-05-01"
+
+[[d1_databases]]
+binding = "DB"
+database_name = "<nome>"
+database_id = "<uuid>"
+
+[[kv_namespaces]]
+binding = "KV"
+id = "<uuid>"
+
+[[r2_buckets]]
+binding = "R2"
+bucket_name = "<nome>"
+
+[[durable_objects.bindings]]
+name = "ROOM"
+class_name = "ChatRoom"
+
+[[migrations]]
+tag = "v1"
+new_classes = ["ChatRoom"]
+```
+
+## Patterns recomendados
+
+### Pattern A — SPA descartavel (perfil A do ADR)
+- Pages serve `index.html` + assets
+- Sem Workers, sem DB
+- Estado em localStorage
+- 0 setup, deploy via `git push`
+
+### Pattern B — App CRUD continuo (perfil B)
+- Pages serve front (Vite build)
+- Workers em `/api/*` rota
+- D1 binding para CRUD
+- Auth: Supabase Auth (front-only) OU Cloudflare Access (zero-config)
+
+### Pattern C — Realtime (perfil C)
+- Pages serve front
+- Workers para REST CRUD
+- DO para WebSocket
+- D1 para persistencia OU Supabase Postgres
+- Cloudflare Tunnel se backend precisa rodar localmente em dev
+
+## Limites para alarmar (gates do ADR)
+
+| Recurso | Limite free | Quando ja preocupar |
+|---------|-------------|---------------------|
+| Workers reqs | 100k/dia | >50k/dia projetado |
+| D1 writes | 100k/dia | CRUD com escrita > 1/s sustentado |
+| KV writes | 1k/dia | Qualquer caso de escrita por user-action |
+| DO requests | 1M/mes | >100 conexoes WS sustentadas |
+| Pages builds | 500/mes | CI commit > 16/dia |
+
+## Ferramentas
+
+- **Wrangler CLI**: `npm i -g wrangler` — deploy, dev local, tail logs
+- **Local dev**: `wrangler dev` simula Workers localmente, mas D1 local e separado de remote (`--remote` para usar prod)
+- **Logs**: `wrangler tail` (real-time) — gratis ate 5/dia ativos
+
+## Anti-patterns para flagar
+
+- KV como banco principal: 1k writes/dia mata isso rapido.
+- D1 com >10 tabelas joinadas em 1 query: D1 nao otimiza JOIN como Postgres.
+- DO sem hibernation: deixa 1 conexao WS aberta = cobra GB-s o tempo todo.
+- Pages Functions para logica pesada: limite 100k execucoes/dia, mais baixo que Workers (1M paid).

package/.gos/libraries/default-stack-kb.md

@@ -0,0 +1,98 @@
+# Default Stack KB — G-OS canonical (2026-05)
+
+> Stack default proposto pelo `gos-master` quando o usuario nao especifica. Sempre confirmado via `adr-tech-decisions` antes de chumbar.
+
+## Principios
+
+1. **TypeScript everywhere** — front, back, scripts. Nunca JS puro em codigo de app.
+2. **Free tier first** — MVP descartavel cabe 100% no free de Cloudflare + Supabase.
+3. **Zero servidor proprio** — Workers Pages + Supabase substituem Express+VPS.
+4. **Anti-vendor-lock** — Postgres standard (Supabase) e Workers (Hono) sao portaveis.
+
+## Stack canonico
+
+### Frontend
+
+```
+- Vite + React 18 + TypeScript (strict)
+- TanStack Query (data fetching, cache, mutations, optimistic UI)
+- TanStack Router (type-safe routing, loaders, search params tipados)
+- Tailwind CSS v4 + shadcn/ui (Radix primitives + cn() helper)
+- Lucide React (UNICA lib de icones — zero emojis em codigo)
+- React Hook Form + Zod (validacao schema-first)
+- Sonner (toasts)
+```
+
+### Backend
+
+```
+- Cloudflare Workers (Hono framework opcional para routing)
+- Cloudflare Pages Functions (alternativa lightweight para API routes simples)
+- Supabase Postgres (DB principal — preferido sobre D1 quando precisa JOIN/RLS)
+- Supabase Auth (OAuth + magic link — substitui Auth.js/Clerk)
+- Supabase Realtime (WebSocket via Postgres logical replication)
+- Supabase Storage (blob storage com transformacoes de imagem)
+```
+
+### Hosting
+
+```
+- Frontend: Cloudflare Pages (deploy via git push)
+- Backend: Cloudflare Workers (mesmo dominio, prefixo /api/*)
+- DNS: Cloudflare (proxy on, SSL auto)
+```
+
+### Tooling
+
+```
+- pnpm (workspace para monorepo, usar npm em projeto unico)
+- Wrangler CLI (deploy + dev local Workers)
+- Supabase CLI (migrations + tipos gerados)
+- Biome OU ESLint+Prettier (preferencia: Biome — mais rapido, zero config)
+```
+
+## Quando NAO usar este stack
+
+| Caso | Stack alternativo | Motivo |
+|------|-------------------|--------|
+| SSR pesado / SEO crítico | Next.js + Vercel | Workers Pages serve SPA — para SSR usar Next |
+| Backoffice + ETL pesado | Node em VPS + Postgres dedicado | Workers tem limite 30s |
+| App mobile nativo | Expo + React Native | Mas API pode continuar Workers+Supabase |
+| Realtime massivo (>1k conn) | Supabase Realtime > Cloudflare DO | Postgres-based escala melhor pra MVP |
+
+## Setup rapido (script mental)
+
+1. `npm create vite@latest <projeto> -- --template react-ts`
+2. `cd <projeto> && npm i`
+3. `npx shadcn@latest init` (escolher Tailwind v4, slate base)
+4. `npm i @tanstack/react-query @tanstack/react-router lucide-react react-hook-form @hookform/resolvers zod sonner`
+5. `npm i @supabase/supabase-js`
+6. `npm i -D wrangler`
+7. Configurar `wrangler.toml` apontando para Pages
+8. `wrangler pages deploy dist` (apos primeiro build)
+
+## Decisoes embutidas (nao precisa perguntar)
+
+- React vs Vue/Svelte -> React (ecossistema + hiring + LLM training data).
+- TanStack Query vs SWR -> TanStack (cache mais granular, devtools).
+- TanStack Router vs React Router -> TanStack (type-safe, search params tipados).
+- Tailwind v3 vs v4 -> v4 (CSS-first, lightning CSS).
+- Lucide vs Heroicons vs FontAwesome -> Lucide (mais variantes, tree-shake melhor).
+- Supabase Auth vs Clerk vs Auth.js -> Supabase (mesmo provider do DB = RLS integrado).
+- Magic link vs password -> magic link first (UX superior, sem reset password fluxo).
+
+## Decisoes que DEVEM perguntar (regra do dono)
+
+- D1 vs Supabase Postgres (depende de complexidade do schema)
+- Workers DO vs Supabase Realtime (chat ad-hoc vs notif baseada em DB)
+- Monorepo (turborepo) vs single repo (depende de N apps)
+- Analytics (PostHog vs Plausible vs nada)
+- Error tracking (Sentry vs nada vs Cloudflare Logs)
+
+## Output policy do master
+
+`gos-master`, ao iniciar conversa de novo projeto, SEMPRE oferece este stack como ponto de partida. Frase tipica:
+
+> "Para o MVP descartavel/continuo, o default que recomendo e Vite+React+TS, TanStack Query/Router, Tailwind v4 + shadcn/ui, Lucide React (icones), hospedado em Cloudflare Pages com Workers no /api e Supabase como DB+Auth+Realtime+Storage. Prefere alguma alternativa ou seguimos com isso e vamos refinando?"
+
+Decisoes sao validadas em `adr-tech-decisions` (skill SEMPRE pergunta antes de chumbar).

package/.gos/libraries/engineering-best-practices.md

@@ -0,0 +1,208 @@
+# Engineering Best Practices — G-OS
+
+> Padroes de codigo, arquitetura e workflow. Aplicado em todo `plan-blueprint`, codegen e revisao.
+
+## TypeScript — strict mode obrigatorio
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "noUncheckedIndexedAccess": true,
+    "noFallthroughCasesInSwitch": true
+  }
+}
+```
+
+### Regras
+
+- **Nunca** `as any`, `@ts-ignore` sem comentario justificando.
+- **Permitido** `@ts-expect-error` com comentario obrigatorio.
+- `interface` para objetos de dominio e contratos.
+- `type` para unions, intersections, utilitarios.
+- **Nunca enum** — use `const X = { ... } as const` + `type Status = typeof X[keyof typeof X]`.
+- Generics tipados — sem `T = any`.
+
+## React 18 — patterns
+
+### Componentes
+- Funcionais sempre. Class components proibidos.
+- `function declaration` para componentes principais (export default).
+- `arrow function` para callbacks/handlers.
+- Props tipadas via `interface`.
+- Children: `React.ReactNode` (nao `JSX.Element[]`).
+
+### Hooks
+- `useState` para estado local primitivo.
+- `useReducer` para state machine (>3 transicoes).
+- `useEffect` apenas para sincronizacao com sistema externo (DOM, network, subscriptions).
+- **NUNCA** `useEffect` para derivar state — calcular inline ou `useMemo`.
+- Custom hooks com prefix `use` + camelCase (`useAuth`, `useProjects`).
+
+### Estado global
+- Servidor: TanStack Query (cache + invalidation).
+- Cliente: Zustand para complexo, `useState` lift-up para simples.
+- **Nunca** Redux em projeto novo.
+
+## TanStack Query — patterns
+
+```tsx
+// Query key como tupla [domain, params]
+const projects = useQuery({
+  queryKey: ['projects', { status: 'active' }],
+  queryFn: () => api.projects.list({ status: 'active' }),
+  staleTime: 60_000, // 1min
+});
+
+// Mutation com invalidacao
+const createProject = useMutation({
+  mutationFn: api.projects.create,
+  onSuccess: () => qc.invalidateQueries({ queryKey: ['projects'] }),
+});
+```
+
+### Anti-patterns
+- Refetch on window focus em lista grande (custo de rede).
+- queryKey como string (`'projects'`) — sempre array.
+- Mutation sem `onError` quando UX precisa rollback.
+
+## TanStack Router — patterns
+
+- Routes em `src/routes/<path>.tsx` com file-based routing OU codegen.
+- Loader para dados criticos (bloqueia render ate ter).
+- Search params via `validateSearch` Zod.
+- Type-safe params: `Route.useParams()`.
+
+## File structure (single-app)
+
+```
+src/
+  routes/                   # rotas TanStack
+  components/
+    ui/                     # shadcn primitives
+    <feature>/              # componentes especificos do dominio
+  hooks/                    # custom hooks reutilizaveis
+  lib/
+    supabase.ts             # client
+    utils.ts                # cn(), formatters
+  schemas/                  # Zod schemas
+  types/                    # tipos compartilhados
+  api/                      # client API (workers fetch wrappers)
+```
+
+## File structure (monorepo)
+
+```
+apps/
+  web/                      # frontend
+  worker/                   # backend Workers
+packages/
+  ui/                       # design system compartilhado
+  schemas/                  # Zod schemas usados front+back
+  types/                    # tipos compartilhados
+  config/                   # tsconfig base, eslint base
+```
+
+## Naming
+
+- Componentes: `PascalCase` (`ProjectCard.tsx`).
+- Hooks: `camelCase` com `use` prefix (`useProjects.ts`).
+- Utils: `camelCase` (`formatCurrency.ts`).
+- Types: `PascalCase` (`Project`, `User`).
+- Constants: `SCREAMING_SNAKE_CASE` (`MAX_FILE_SIZE`).
+- Booleans: `is/has/should` prefix (`isLoading`, `hasError`).
+
+## Commits — Conventional Commits
+
+```
+<type>(<scope>): <subject>
+
+[body]
+
+[footer]
+```
+
+Types: `feat`, `fix`, `refactor`, `chore`, `docs`, `test`, `style`, `perf`, `ci`.
+
+Exemplos:
+- `feat(auth): add magic link login`
+- `fix(projects): correct active count`
+- `refactor(api): extract supabase client`
+
+## Branches
+
+- `main` — producao.
+- `dev` — integracao.
+- `feat/<slug>` — feature em desenvolvimento.
+- `fix/<slug>` — bug fix.
+- `chore/<slug>` — limpeza.
+
+## Workflow
+
+1. `feat/<slug>` -> commits pequenos e atomicos.
+2. PR para `dev`.
+3. Code review obrigatorio (auto-review aceito em MVP descartavel).
+4. CI passa (build + tsc + tests).
+5. Merge squash.
+6. `dev` -> `main` periodicamente.
+
+## Testing
+
+### MVP descartavel
+- Smoke test manual antes de deploy.
+- Sem unit tests obrigatorios.
+
+### Continuo
+- Vitest para units (so logica pura, formatadores, hooks).
+- Playwright para E2E em fluxos criticos (login, checkout, dashboard).
+- Coverage minima: 60% em logica de negocio.
+- **NAO** testar componentes UI puros (chumba implementacao).
+
+## Performance
+
+- Lazy load rotas: `React.lazy` + `Suspense`.
+- Code split por feature (TanStack Router cuida).
+- Imagens: WebP via Cloudflare Image Transformations.
+- Bundle target: <200KB inicial gzip.
+- Lighthouse score 90+ em mobile.
+
+## Acessibilidade
+
+- Labels em todos inputs (`htmlFor` + `id` ou `aria-label`).
+- Roles ARIA em componentes custom.
+- Focus management em modal/drawer.
+- Contraste AA (4.5:1 texto, 3:1 UI).
+- Keyboard navigation em todos os flows interativos.
+
+Detalhe completo: `libraries/ui-guardrails-checklist.md`.
+
+## Architecture — Hexagonal-ish (continuo)
+
+```
+src/
+  domain/                   # entidades, value objects, regras puras
+  application/              # use cases, services
+  infrastructure/           # adapters (supabase, workers, http)
+  ui/                       # React components
+```
+
+Em MVP descartavel, achatar para `lib/` + `components/` direto.
+
+## Anti-patterns
+
+- Componente >500 linhas — quebrar em sub-components.
+- Hook com >5 useState — provavelmente precisa useReducer.
+- Funcao com >50 linhas — extrair sub-funcoes.
+- `any` em props — sempre tipar.
+- `console.log` em codigo que vai pra prod — usar logger ou remover.
+- TODO sem prazo/owner — vira divida tecnica permanente.
+- Comentario explicando WHAT do codigo — refatorar nome em vez de comentar.
+
+## Referencias completas
+
+- `docs-tools/docs/engineering/dev/02-padroes-codigo.md` — base completa.
+- `docs-tools/docs/engineering/arquitetura/hexagonal.md` — para apps continuos.
+- `docs-tools/docs/engineering/dev/01-workflow-desenvolvimento.md` — fluxo de trabalho.