ganbatte-os 0.2.37 → 0.2.41

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

@@ -0,0 +1,124 @@
+# Supabase Stack KB — Free Tier (2026-05)
+
+> Referencia consultada por `adr-tech-decisions`. Data: 2026-05.
+> Sempre verificar https://supabase.com/pricing para limites atuais.
+
+## Filosofia G-OS para Supabase
+
+1. Usar quando precisa Postgres real, auth pronta, ou Realtime escalavel.
+2. Combina bem com Cloudflare Pages (front) + Supabase (backend completo).
+3. Free tier projetos pausam apos 7 dias inativos — atencao para MVPs descartaveis em demo.
+4. **Anti-vendor-lock**: Postgres standard, Auth pode ser substituida (Auth.js, Lucia).
+
+## Free tier (2 projetos ativos simultaneos)
+
+### Database (Postgres)
+- 500MB storage
+- 2GB bandwidth/mes
+- 50k MAU em Auth
+- 5GB storage de arquivos (Storage)
+- 7 dias de inatividade -> projeto pausa (precisa logar e dar resume)
+
+### Auth (free 50k MAU)
+- Email/password, magic link, OAuth (Google, GitHub, ~20 providers)
+- Row Level Security (RLS) Postgres-based
+- JWT signing automatico
+- **Limite: 4 social providers em free, 30 em pro**
+
+### Realtime (free)
+- Postgres logical replication -> canais por tabela
+- 200 conexoes simultaneas
+- 2M mensagens/mes
+- **Limite: 200 conexoes pode ser baixo para chat publico; suficiente para dashboard interno**
+
+### Storage (free)
+- 5GB
+- 5GB egress/mes
+- Image transformations (resize, format)
+
+### Edge Functions (free)
+- 500k invocations/mes
+- 2s execution time
+- Deno-based
+- Bom para webhooks, cron jobs, API routes leves
+
+## Patterns recomendados
+
+### Pattern: Front Cloudflare + Back Supabase (recomendado MVP rapido)
+
+```
+[Cloudflare Pages]            [Supabase]
+   Vite + React               Postgres + Auth + Storage
+   |                          |
+   +--- supabase-js client ---+
+        (direto do browser, RLS protege)
+```
+
+Pros:
+- Sem Workers necessarios
+- Auth pronta em 1 hora
+- RLS substitui boa parte de backend
+
+Contras:
+- Vendor lock no Auth (mas Postgres e portavel)
+- Cold start de project apos 7 dias de inatividade
+
+### Pattern: Cloudflare Workers + Supabase Postgres (apenas DB)
+
+Use quando:
+- Quer logica de servidor (Workers) mas precisa Postgres real (D1 nao basta).
+- Auth simples ou via Cloudflare Access.
+
+## Realtime: Supabase Realtime vs Cloudflare DO+WS
+
+| Criterio | Supabase Realtime | Cloudflare DO+WS |
+|----------|-------------------|------------------|
+| Custo MVP | Free 200 conn | Free 1M ops/mes |
+| Modelo | Postgres-based (subscribe a INSERT/UPDATE) | Codigo livre (qualquer mensagem) |
+| Boa para | Notificacoes vindas de DB | Chat, jogo, presenca |
+| Limite escala | 200 conn free / 500 pro | 32k por DO, infinito DOs |
+| Latencia | ~100ms | ~50ms (edge) |
+| Setup | `.from('table').on('INSERT', ...)` | Implementar `webSocketMessage()` |
+
+**Regra G-OS**: usuario indicou "chat ao vivo" sem DB transacional -> DO+WS. Indicou "notificacao quando alguem cadastra X" -> Supabase Realtime.
+
+## Anti-patterns
+
+- Free project como demo permanente: pausa em 7 dias, demo quebra.
+- RLS desabilitado em prod: vazamento de dados.
+- service_role key exposta no front: bypassa RLS — NUNCA por no Pages.
+- Storage publico sem moderacao: ataques de upload em MVP.
+
+## Bindings (Cloudflare Workers consumindo Supabase)
+
+```typescript
+import { createClient } from '@supabase/supabase-js'
+
+export default {
+  async fetch(req: Request, env: Env) {
+    const supabase = createClient(
+      env.SUPABASE_URL,
+      env.SUPABASE_ANON_KEY  // ou SERVICE_ROLE pra ops privilegiadas
+    )
+    // ...
+  }
+}
+```
+
+`wrangler secret put SUPABASE_URL` e `SUPABASE_ANON_KEY`.
+
+## Limites para alarmar
+
+| Recurso | Limite free | Alarme |
+|---------|-------------|--------|
+| DB storage | 500MB | >300MB |
+| MAU auth | 50k | >30k |
+| Realtime conn | 200 | >100 sustentadas |
+| Edge Function invocations | 500k/mes | >300k/mes |
+| Inatividade | 7 dias | demos publicas precisam ping |
+
+## Ferramentas
+
+- **CLI**: `npm i -g supabase` — `supabase init`, `supabase db push`, migrations
+- **Studio**: dashboard web em supabase.com — SQL editor, table editor, Auth users
+- **Local dev**: `supabase start` (precisa Docker) — sobe Postgres + Auth + Storage local

package/.gos/libraries/timer-pattern-spec.md

@@ -0,0 +1,252 @@
+# Timer Pattern — Spec abstrata
+
+> Abstracao do timer-de-estudo passo-a-passo, baseada em `code-kata-timer/script.js`
+> + `code-kata-timer/style.css`. Adaptado para React + TypeScript + Tailwind.
+>
+> Use quando o usuario pedir contador regressivo, timer de pomodoro, code kata,
+> stopwatch com countdown, ou qualquer interface de tempo com play/pause/edit.
+
+## State machine
+
+```ts
+export const TimerStatus = {
+  STOPPED: 'STOPPED',
+  COUNTDOWN: 'COUNTDOWN',  // animacao 3-2-1-GO antes de iniciar
+  RUNNING: 'RUNNING',
+  PAUSED: 'PAUSED',
+  EDITING: 'EDITING',      // usuario editando valor
+} as const;
+export type TimerStatusType = typeof TimerStatus[keyof typeof TimerStatus];
+
+export const isRunning = (s: TimerStatusType) =>
+  s === TimerStatus.RUNNING || s === TimerStatus.COUNTDOWN;
+```
+
+Transicoes validas:
+```
+STOPPED -> COUNTDOWN -> RUNNING -> PAUSED -> RUNNING
+                                          -> STOPPED
+EDITING <-> STOPPED  (so edita parado)
+```
+
+## Persistencia
+
+LocalStorage com chave `timerSettings`:
+```ts
+interface TimerSettings {
+  currentSeconds: number;
+  timerStatus: TimerStatusType;  // sempre STOPPED ao recarregar
+  theme: 'dark' | 'light';
+  showContributors?: boolean;     // app-specific, opcional
+}
+```
+
+**Regra critica** (do code-kata-timer original): ao carregar settings, **sempre forcar status para STOPPED** — nao restaurar RUNNING. Caso contrario timer "fantasma" continua contando.
+
+## Hook reutilizavel
+
+```ts
+export function useTimer(defaultSeconds = 30) {
+  const [status, setStatus] = useState<TimerStatusType>(TimerStatus.STOPPED);
+  const [seconds, setSeconds] = useState(defaultSeconds);
+  const intervalRef = useRef<number | null>(null);
+
+  const start = useCallback(() => {
+    if (status === TimerStatus.RUNNING) return;
+    setStatus(TimerStatus.RUNNING);
+    intervalRef.current = window.setInterval(() => {
+      setSeconds(s => {
+        if (s <= 1) {
+          if (intervalRef.current) clearInterval(intervalRef.current);
+          setStatus(TimerStatus.STOPPED);
+          // dispatch event 'timer:done' para componentes ouvirem
+          window.dispatchEvent(new CustomEvent('timer:done'));
+          return 0;
+        }
+        return s - 1;
+      });
+    }, 1000);
+  }, [status]);
+
+  const pause = useCallback(() => {
+    if (intervalRef.current) clearInterval(intervalRef.current);
+    setStatus(TimerStatus.PAUSED);
+  }, []);
+
+  const reset = useCallback((to = defaultSeconds) => {
+    if (intervalRef.current) clearInterval(intervalRef.current);
+    setSeconds(to);
+    setStatus(TimerStatus.STOPPED);
+  }, [defaultSeconds]);
+
+  useEffect(() => {
+    return () => {
+      if (intervalRef.current) clearInterval(intervalRef.current);
+    };
+  }, []);
+
+  return { status, seconds, start, pause, reset, setSeconds };
+}
+```
+
+## Display
+
+Formato `MM:SS` com font monospace (Orbitron, JetBrains Mono ou Tailwind `font-mono`):
+
+```tsx
+function formatTime(s: number) {
+  const m = Math.floor(s / 60);
+  const ss = s % 60;
+  return `${String(m).padStart(2, '0')}:${String(ss).padStart(2, '0')}`;
+}
+
+<div className="text-7xl md:text-9xl font-mono font-bold tabular-nums">
+  {formatTime(seconds)}
+</div>
+```
+
+`tabular-nums` garante que digitos nao "pulem" durante a contagem.
+
+## Controles (Lucide React)
+
+```tsx
+import { Play, Pause, RotateCcw, Pencil } from "lucide-react";
+
+<div className="flex gap-3 justify-center">
+  {status === TimerStatus.STOPPED || status === TimerStatus.PAUSED ? (
+    <Button onClick={start} size="lg" aria-label="Iniciar">
+      <Play className="h-5 w-5" />
+    </Button>
+  ) : (
+    <Button onClick={pause} size="lg" aria-label="Pausar">
+      <Pause className="h-5 w-5" />
+    </Button>
+  )}
+  <Button onClick={() => reset()} size="lg" variant="outline" aria-label="Resetar">
+    <RotateCcw className="h-5 w-5" />
+  </Button>
+  <Button
+    onClick={() => setStatus(TimerStatus.EDITING)}
+    size="lg"
+    variant="outline"
+    aria-label="Editar tempo"
+    disabled={isRunning(status)}
+  >
+    <Pencil className="h-5 w-5" />
+  </Button>
+</div>
+```
+
+## Atalhos de teclado
+
+```ts
+useEffect(() => {
+  function onKey(e: KeyboardEvent) {
+    if (e.target instanceof HTMLInputElement) return; // nao interferir em editing
+    if (e.code === 'Space') { e.preventDefault(); status === TimerStatus.RUNNING ? pause() : start(); }
+    if (e.code === 'KeyR') reset();
+    if (e.code === 'KeyE') setStatus(TimerStatus.EDITING);
+  }
+  window.addEventListener('keydown', onKey);
+  return () => window.removeEventListener('keydown', onKey);
+}, [status, start, pause, reset]);
+```
+
+## Tema
+
+Variaveis CSS (root data-theme):
+- `--timer-bg`: bg principal
+- `--timer-fg`: cor do texto/digitos
+- `--timer-accent`: cor do CTA primario
+
+Toggle via `document.documentElement.dataset.theme = 'dark' | 'light'`. Persistir em `localStorage`.
+
+## Edicao inline
+
+Ao entrar em `EDITING`:
+- Display vira `<input type="number">` com mesmo styling do display.
+- Enter -> salva e volta para `STOPPED`.
+- Esc -> cancela e volta para `STOPPED`.
+
+```tsx
+{status === TimerStatus.EDITING ? (
+  <input
+    type="number"
+    autoFocus
+    defaultValue={seconds}
+    className="text-7xl font-mono font-bold tabular-nums bg-transparent w-64 text-center"
+    onBlur={(e) => {
+      const v = Number(e.currentTarget.value);
+      if (v > 0) setSeconds(v);
+      setStatus(TimerStatus.STOPPED);
+    }}
+    onKeyDown={(e) => {
+      if (e.key === 'Enter') e.currentTarget.blur();
+      if (e.key === 'Escape') setStatus(TimerStatus.STOPPED);
+    }}
+  />
+) : (
+  <div>{formatTime(seconds)}</div>
+)}
+```
+
+## Eventos customizados
+
+Dispatch quando timer termina:
+```ts
+window.dispatchEvent(new CustomEvent('timer:done', { detail: { duration } }));
+```
+
+Componentes ouvem:
+```ts
+useEffect(() => {
+  const handler = (e: Event) => {
+    const evt = e as CustomEvent<{ duration: number }>;
+    // mostrar toast, tocar som, etc
+  };
+  window.addEventListener('timer:done', handler);
+  return () => window.removeEventListener('timer:done', handler);
+}, []);
+```
+
+## Som ao terminar (opcional)
+
+Web Audio API simples — sem precisar arquivo:
+```ts
+function beep(frequency = 800, duration = 200) {
+  const ctx = new AudioContext();
+  const osc = ctx.createOscillator();
+  const gain = ctx.createGain();
+  osc.connect(gain);
+  gain.connect(ctx.destination);
+  osc.frequency.value = frequency;
+  osc.start();
+  setTimeout(() => { osc.stop(); ctx.close(); }, duration);
+}
+```
+
+## Estados visuais (UI guardrails)
+
+- **Loading**: nao aplicavel (timer e estado puro).
+- **Empty**: tempo zerado mostra `00:00` mas botao Iniciar disabled.
+- **Error**: nao deve haver erro em runtime — se houver, fallback para reset.
+- **Running indicator**: Lucide `Activity` pulsando ou borda do display animada.
+
+## Anti-patterns
+
+- `setInterval` sem cleanup -> memory leak.
+- Restaurar status RUNNING do localStorage -> timer fantasma.
+- Sem `tabular-nums` -> digitos pulam visualmente.
+- Sem atalho de teclado -> mau UX em uso intensivo.
+- Emoji nos botoes -> usar Lucide.
+- Sem dispatch de evento ao terminar -> componentes externos nao reagem.
+
+## Reuso no G-OS
+
+`gos-master` reconhece pedidos:
+- "timer", "contador regressivo", "countdown"
+- "pomodoro", "pomodoro timer"
+- "code kata timer", "kata"
+- "stopwatch" (variacao — countup vs countdown)
+
+Aciona skill `timer-component-pattern` que aplica spec acima.

package/.gos/libraries/typeform-pattern-spec.md

@@ -0,0 +1,204 @@
+# Typeform Pattern — Spec abstrata
+
+> Abstracao do quiz/form passo-a-passo estilo Typeform, baseada em
+> `body-metrics-edge/.examples/tsx/old/body-metrics-quiz-typeform.tsx`
+> e `template-lp-wanderson/.a8z/skills/designkit/templates/form.tsx.template`.
+>
+> Use sempre que o usuario pedir form de coleta de dados, quiz, onboarding multi-step,
+> survey, lead form, ou qualquer entrada estruturada que beneficia de **uma pergunta por vez**.
+
+## Por que esse pattern
+
+- **Conversao 2-3x maior** que forms longos (uma tela por pergunta vs paredao de inputs).
+- **Cognitive load baixo** — usuario ve so uma decisao por vez.
+- **Mobile-first natural** — funciona perfeitamente em telas pequenas.
+- **Estado intermediario salvavel** — refresh nao perde progresso.
+
+## Anatomia do pattern
+
+### 1. Question schema
+
+```ts
+export type QuestionType = 'welcome' | 'text' | 'number' | 'choice' | 'multiChoice' | 'date' | 'review';
+
+export interface QuestionOption {
+  value: string;
+  label: string;
+  description?: string;
+  iconName?: keyof typeof import('lucide-react');  // Lucide React (zero emoji)
+}
+
+export interface Question<F = Record<string, unknown>> {
+  id: string;
+  type: QuestionType;
+  field: keyof F | null;
+  question: string | ((data: F) => string);  // pode ser dinamica
+  description?: string;
+  placeholder?: string;
+  suffix?: string;
+  decimal?: boolean;
+  buttonText?: string;
+  options?: QuestionOption[];
+  validate?: (value: unknown, data: F) => string | null;  // null = ok, string = erro
+  showWhen?: (data: F) => boolean;  // condicional
+}
+```
+
+### 2. State
+
+```ts
+const [currentIndex, setCurrentIndex] = useState(0);
+const [data, setData] = useState<FormData>({});
+const [isAnimating, setIsAnimating] = useState(false);
+```
+
+Persistir em `sessionStorage` ou `Supabase row` se descartavel = false.
+
+### 3. Filtro de ativas (condicional)
+
+```ts
+const activeQuestions = questions.filter(q => !q.showWhen || q.showWhen(data));
+const currentQ = activeQuestions[currentIndex];
+```
+
+### 4. Navegacao
+
+- `Enter` -> next (com validacao).
+- `Shift+Enter` (em textarea) -> nova linha.
+- `Esc` -> previous (opcional).
+- Botao "Voltar" sempre visivel exceto na welcome.
+- Animacao opacity+translate-y com 200-300ms entre transicoes.
+
+### 5. Componentes-tipo
+
+**Welcome screen**
+```
+- Titulo grande (text-4xl/5xl)
+- Subtitulo
+- CTA primario "Comecar" (Button size lg)
+- Lucide icon ilustrativo (h-16 w-16)
+```
+
+**Text input**
+```
+- Question (text-2xl semibold)
+- Description opcional (text-base muted-foreground)
+- Input grande (h-12 ou h-14, text-lg)
+- Hint "Pressione Enter para continuar" + CornerDownLeft icon
+```
+
+**Number input**
+```
+- Igual text input mas type="number"
+- Suffix visual ao lado (ex: "anos", "kg", "cm")
+- Decimal opt-in via prop
+```
+
+**Choice (radio)**
+```
+- Stack vertical de cards clicaveis
+- Cada card: Lucide icon + label + description opcional
+- Hover ring + active filled
+- Selecao avanca automaticamente apos 300ms
+```
+
+**MultiChoice (checkbox)**
+```
+- Igual choice mas selecao acumula
+- Botao "Continuar" obrigatorio (nao auto-avanca)
+- Mostra contagem ("3 de 5 selecionados")
+```
+
+**Review (final)**
+```
+- Resumo dos dados coletados em cards
+- Botao "Editar" por secao (volta para a question correspondente)
+- CTA primario "Confirmar" / "Calcular" / "Enviar"
+```
+
+### 6. Animacao
+
+```tsx
+<div className={`transition-all duration-300 ${
+  isAnimating ? 'opacity-0 translate-y-4' : 'opacity-100 translate-y-0'
+}`}>
+  {/* question */}
+</div>
+```
+
+### 7. Progress bar
+
+Top of screen, fixed:
+```tsx
+<div className="fixed top-0 left-0 right-0 h-1 bg-muted">
+  <div
+    className="h-full bg-primary transition-all duration-300"
+    style={{ width: `${((currentIndex + 1) / activeQuestions.length) * 100}%` }}
+  />
+</div>
+```
+
+### 8. Validacao
+
+Por question:
+```ts
+{
+  id: 'email',
+  type: 'text',
+  field: 'email',
+  question: 'Qual seu email?',
+  validate: (value) => {
+    if (!value) return 'Campo obrigatorio';
+    if (!/^[^@]+@[^@]+\.[^@]+$/.test(String(value))) return 'Email invalido';
+    return null;
+  }
+}
+```
+
+Erro inline abaixo do input. Nunca toast/alert.
+
+### 9. Estados visuais (UI guardrails)
+
+- **Loading** (submitting): botao disabled + Lucide `Loader2` com `animate-spin`.
+- **Empty** (review sem dados): mostrar "Voce ainda nao respondeu — comece pelo inicio."
+- **Error** (submit falhou): inline acima do CTA + botao retry.
+- **Success**: tela final com Lucide `CheckCircle2` h-16 w-16 + redirect ou prox-step.
+
+### 10. Acessibilidade
+
+- `aria-live="polite"` no container de question (anuncia mudanca pra screen reader).
+- Focus auto no input ao mudar de question (`useEffect` + `inputRef.current?.focus()`).
+- Labels via `<Label htmlFor>` ou `aria-label`.
+- Botao voltar com `aria-label="Pergunta anterior"`.
+
+## Stack obrigatorio
+
+- React 18+
+- TypeScript strict
+- Tailwind v4 + shadcn/ui (Button, Input, Card, Label)
+- Lucide React (UNICA lib de icones — zero emoji)
+- React Hook Form + Zod (validacao schema-first quando form complexo)
+
+## Variantes
+
+- **Quiz com calculo** (body-metrics-quiz original): apos ultima question, calcula metricas e mostra resultado.
+- **Lead form** (capturar email/whats): submita para Supabase.
+- **Onboarding** (apos signup): salva preferencias na profiles table.
+- **Survey publico** (NPS, feedback): tabela com RLS public-insert apenas.
+
+## Anti-patterns
+
+- Mostrar todas perguntas de uma vez como form tradicional — defeats the purpose.
+- Sem progress bar — usuario nao sabe quanto falta.
+- Pular validacao no front — mau UX (back so pra forma).
+- Auto-avanco SEM debounce em choice — usuario clica errado e ja avancou.
+- Texto unicode/emoji nas opcoes — usar `iconName` Lucide.
+- Sem estado de submitting no final — usuario clica enviar 3x.
+
+## Reuso no G-OS
+
+Quando usuario pede "form de cadastro", "quiz", "onboarding", "captura de leads":
+1. `gos-master` sugere pattern typeform.
+2. Usuario aprova -> skill `typeform-form-pattern` gera estrutura base.
+3. Customiza questions[] do dominio.
+4. Estilizacao via tokens shadcn (sem hardcoded colors).