sinapse-ai 9.4.0 → 9.5.0

package/.sinapse-ai/development/knowledge-base/environment-deployment-patterns.md

@@ -0,0 +1,353 @@
+# Environment & Deployment Patterns
+
+> **Agente(s):** @devops (Pipeline)
+> **Fonte:** environment-secrets-management.md, gitflow-branching-at-scale.md
+> **Uso:** Consultar ao configurar ambientes, secrets, CI/CD e branching strategy para projetos SINAPSE
+
+---
+
+## 1. Tiers de Ambientes Padrao
+
+### Para Startups (1-10 devs) -- 3 ambientes
+
+| Ambiente | Branch | Vercel | Supabase | Dados |
+|----------|--------|--------|----------|-------|
+| Local | qualquer | `vercel dev` | Supabase CLI (local) | Seed/mock |
+| Preview | PR branches | Auto (por PR) | Projeto de staging | Sinteticos |
+| Production | `main` | Production deploy | Projeto de producao | Reais |
+
+### Para Scale-ups (10-50 devs) -- 4 ambientes
+
+| Ambiente | Branch | Vercel | Supabase | Dados |
+|----------|--------|--------|----------|-------|
+| Local | qualquer | `vercel dev` | CLI local | Seed/mock |
+| Preview | PR branches | Preview deploy | Staging project | Sinteticos |
+| Staging | `staging` | Staging deploy | Staging project | Anonimizados |
+| Production | `main` | Production deploy | Prod project | Reais |
+
+### Regras de Paridade (12-Factor)
+
+1. Mesma versao do PostgreSQL em TODOS os ambientes
+2. Mesma versao do runtime (Node.js, Deno)
+3. Mesmos backing services (Redis, S3)
+4. Mesma estrutura de env vars (nomes identicos, valores diferentes)
+
+---
+
+## 2. Env Var Naming Convention
+
+### Formato: `PREFIX_SERVICE_KEY` (SCREAMING_SNAKE_CASE)
+
+```bash
+# Database
+DATABASE_URL=<connection-string>
+DATABASE_POOL_SIZE=20
+DATABASE_SSL_MODE=require
+
+# APIs externas
+STRIPE_SECRET_KEY=<sk_live_or_test>
+STRIPE_WEBHOOK_SECRET=<whsec_...>
+SENDGRID_API_KEY=<SG.xxx>
+
+# Auth
+AUTH_JWT_SECRET=<min-32-chars>
+AUTH_JWT_EXPIRY=3600
+
+# Feature toggles
+FEATURE_NEW_CHECKOUT=true
+FEATURE_DARK_MODE=false
+
+# Infraestrutura
+REDIS_URL=<redis-connection-string>
+S3_BUCKET_NAME=my-app-uploads
+```
+
+### Regras de Nomenclatura
+
+| Regra | Correto | Errado |
+|-------|---------|--------|
+| SCREAMING_SNAKE_CASE | `DATABASE_URL` | `databaseUrl` |
+| Prefixo por servico | `STRIPE_SECRET_KEY` | `SECRET_KEY` |
+| Sem abreviacoes | `DATABASE_POOL_SIZE` | `DB_PS` |
+| Sem dados no nome | `STRIPE_SECRET_KEY` | `STRIPE_SK_LIVE_4242` |
+
+### NEXT_PUBLIC_ -- Regras Criticas
+
+**PODE ter NEXT_PUBLIC_:**
+- `NEXT_PUBLIC_APP_URL`, `NEXT_PUBLIC_SUPABASE_URL`
+- `NEXT_PUBLIC_SUPABASE_ANON_KEY` (respeita RLS)
+- `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` (publica por design)
+
+**NUNCA pode ter NEXT_PUBLIC_:**
+- `DATABASE_URL`, `STRIPE_SECRET_KEY`, `SUPABASE_SERVICE_ROLE`
+- `JWT_SECRET`, `AWS_SECRET_ACCESS_KEY`
+
+---
+
+## 3. Estrutura de Arquivos .env
+
+```
+project/
+  .env.example       # Template com placeholders (COMMITADO)
+  .env.local         # Overrides locais (GITIGNORED)
+  .env.development   # Defaults dev (commitar se sem secrets)
+  .env.test          # Valores para testes (commitar)
+  .env.staging       # GITIGNORED (ou em secrets manager)
+  .env.production    # NUNCA commitar
+```
+
+### .gitignore obrigatorio
+
+```
+.env
+.env*.local
+.env.staging
+.env.production
+```
+
+### Validacao na Inicializacao (t3-env para Next.js)
+
+```typescript
+// src/env.ts
+import { createEnv } from "@t3-oss/env-nextjs";
+import { z } from "zod";
+
+export const env = createEnv({
+  server: {
+    DATABASE_URL: z.string().url(),
+    AUTH_JWT_SECRET: z.string().min(32),
+    STRIPE_SECRET_KEY: z.string().startsWith("sk_"),
+  },
+  client: {
+    NEXT_PUBLIC_APP_URL: z.string().url(),
+    NEXT_PUBLIC_SUPABASE_URL: z.string().url(),
+    NEXT_PUBLIC_SUPABASE_ANON_KEY: z.string().min(1),
+  },
+  runtimeEnv: { /* ... */ },
+});
+```
+
+---
+
+## 4. Secrets Management Decision Tree
+
+```
+100% na AWS?
+|-- SIM --> Precisa de rotation automatica?
+|   |-- SIM --> AWS Secrets Manager ($0.40/secret/mes)
+|   +-- NAO --> AWS SSM Parameter Store (GRATIS)
++-- NAO --> Precisa de dynamic secrets / PKI?
+    |-- SIM --> HashiCorp Vault (HCP ou self-hosted)
+    +-- NAO --> Prioridade e DX e velocidade?
+        |-- SIM --> Doppler (gratis ate 3 devs)
+        +-- NAO --> Self-hosted?
+            |-- SIM --> Infisical (MIT, gratis)
+            +-- NAO --> Doppler
+```
+
+### Recomendacao por Perfil
+
+| Perfil | Ferramenta | Justificativa |
+|--------|-----------|---------------|
+| Startup ate 5 devs | Doppler Free ou Infisical | Setup em minutos |
+| Time 5-20 devs, multi-cloud | Infisical Cloud ou Doppler | CI/CD integration |
+| Enterprise, compliance | HashiCorp Vault | Dynamic secrets, PKI |
+| 100% AWS | SSM + Secrets Manager | Zero overhead, nativo |
+
+### Vercel + Supabase Secrets
+
+**Vercel:** Variaveis com scoping Production/Preview/Development no dashboard. Marcar como Sensitive para ocultar valor.
+
+**Supabase Edge Functions:**
+```bash
+supabase secrets set STRIPE_SECRET_KEY=<key>
+supabase secrets set RESEND_API_KEY=<key>
+# Acesso: Deno.env.get("STRIPE_SECRET_KEY")
+```
+
+---
+
+## 5. Branching Strategy Decision Tree
+
+```
+Equipe faz continuous deployment (deploy a cada merge)?
+|-- SIM --> Maturidade alta? Feature flags? CI rapido?
+|   |-- SIM --> Trunk-Based Development
+|   +-- NAO --> GitHub Flow
++-- NAO --> Software com releases versionados (mobile, SDK)?
+    |-- SIM --> GitFlow
+    +-- NAO --> Multiplos ambientes com aprovacao?
+        |-- SIM --> GitLab Flow
+        +-- NAO --> GitHub Flow
+```
+
+### Comparativo Rapido
+
+| Criterio | GitHub Flow | GitLab Flow | GitFlow | TBD |
+|----------|-------------|-------------|---------|-----|
+| Complexidade | Baixa | Media | Alta | Baixa |
+| Deploy frequency | Alta | Media-alta | Baixa | Muito alta |
+| Feature flags | Opcional | Opcional | Opcional | Essencial |
+| Team size | 1-50+ | 5-50 | 5-20 | 10-10K+ |
+| Melhor para | SaaS, web apps | Multi-env | SDKs, mobile | High-perf |
+
+### SINAPSE Default: GitHub Flow
+
+Para projetos SINAPSE, o padrao e **GitHub Flow** com:
+- Branch `main` sempre deployavel
+- Feature branches curtas (`caio/feat/xxx`, `soier/fix/xxx`)
+- PR obrigatorio com review
+- Deploy automatico apos merge em main
+
+---
+
+## 6. Branch-to-Environment Mapping
+
+| Branch | Ambiente | Deploy | Aprovacao |
+|--------|----------|--------|-----------|
+| Feature branches | Preview (Vercel) | Automatico (on push) | Nenhuma |
+| `main` | Production (Vercel + Supabase) | Automatico (on merge) | PR approved |
+| `staging` (se existir) | Staging | Automatico | Nenhuma |
+
+### Branch Naming (SINAPSE Convention)
+
+```
+<user>/<type>/<short-desc>
+```
+
+| User | Prefixo | Exemplo |
+|------|---------|---------|
+| Caio | `caio/` | `caio/feat/new-checkout` |
+| Matheus | `soier/` | `soier/fix/auth-bug` |
+| Unknown | `dev/` | `dev/feat/feature-x` |
+
+Types: `feat`, `fix`, `refactor`, `docs`, `chore`, `test`
+
+---
+
+## 7. CI/CD Pipeline Template (GitHub Actions)
+
+```yaml
+name: Production Pipeline
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run build
+      - run: npm run test -- --coverage
+      - run: npm run lint
+      - run: npm run typecheck
+
+  security-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npm ci
+      - run: npm audit --audit-level=high
+      - name: Secret scanning
+        run: npx gitleaks detect --source=.
+
+  # Deploy automatico via Vercel Git Integration
+  # (nao precisa de step manual -- Vercel detecta push)
+```
+
+---
+
+## 8. Feature Flags Quick-Start
+
+### Recomendacao por Perfil
+
+| Perfil | Ferramenta | Custo |
+|--------|-----------|-------|
+| Startup / cost-conscious | GrowthBook (self-hosted) | Gratis |
+| Product-led, A/B testing | GrowthBook Cloud ou Statsig | $0-50/mes |
+| Enterprise, compliance | LaunchDarkly | $12+/seat/mes |
+
+### Tipos de Flag
+
+| Tipo | Duracao | Exemplo |
+|------|---------|---------|
+| Release Flag | Dias-semanas | `flag_new_checkout` |
+| Experiment Flag | Semanas-meses | `exp_pricing_v2` |
+| Ops Flag | Permanente | `ops_enable_cache` |
+| Kill Switch | Permanente | `kill_external_payment` |
+
+**Regra:** Release flags DEVEM ser removidas em 30 dias apos 100%.
+
+---
+
+## 9. Rollback Procedures
+
+### Vercel
+
+```bash
+# Listar deployments
+vercel ls
+
+# Reverter para deployment anterior
+vercel rollback [deployment-url]
+
+# Ou via dashboard: Deployments > ... > Promote to Production
+```
+
+### Supabase (Database)
+
+```bash
+# Listar migrations
+supabase migration list
+
+# Reverter migration (criar migration reversa)
+supabase migration new revert_last_change
+# Escrever SQL de rollback manualmente
+
+# Point-in-Time Recovery (Pro plan)
+# Dashboard > Database > Backups > Restore to point in time
+```
+
+### Git
+
+```bash
+# Reverter ultimo commit em main (cria novo commit)
+git revert HEAD
+git push origin main
+
+# NUNCA usar git reset --hard em branches compartilhadas
+```
+
+---
+
+## 10. Commit Convention (Conventional Commits)
+
+```
+<type>(<scope>): <description>
+
+feat(auth): add Google OAuth login
+fix(cart): correct total calculation with discounts
+docs(api): update authentication guide
+chore(deps): update next.js to 15.2
+refactor(db): extract query builder module
+test(payment): add Stripe webhook integration tests
+```
+
+Types: `feat`, `fix`, `docs`, `chore`, `refactor`, `test`, `perf`, `ci`, `style`, `revert`
+
+---
+
+## 11. Cross-References
+
+- Infrastructure tiers: ver `infrastructure-decision-framework.md`
+- Database environments: ver `database-scaling-patterns.md`
+- Security checklist pre-deploy: ver `security-pre-deploy-checklist.md`

package/.sinapse-ai/development/knowledge-base/gotchas-patterns.md

@@ -0,0 +1,224 @@
+# Gotchas & Error Patterns
+
+> **Agente(s):** ALL agents
+> **Uso:** Consult BEFORE debugging -- the answer may already be here.
+> Auto-populated by agents when encountering recurring errors.
+
+---
+
+## Format
+
+Each entry follows:
+- **Pattern:** What the error looks like
+- **Root Cause:** Why it happens
+- **Fix:** How to resolve it
+- **Agents:** Which agents encounter this
+- **Added:** Date first documented
+
+---
+
+## Git & CI/CD Gotchas
+
+### G-GIT-01: Push blocked by hook
+
+- **Pattern:** `BLOCKED: Only @devops (Pipeline) can execute git push` when any agent tries to push
+- **Root Cause:** `enforce-git-push-authority.sh` hook enforces Constitution Article II -- only @devops has push authority
+- **Fix:** Delegate push to @devops via `*push`. Never attempt `git push` from @developer or other agents
+- **Agents:** @developer, @architect, @quality-gate
+- **Added:** 2026-01-15
+
+### G-GIT-02: Working on main branch
+
+- **Pattern:** Agent starts coding directly on `main`, later blocked by branch protection or creates merge conflicts
+- **Root Cause:** Session start did not follow Safe Collaboration protocol (auto-branch)
+- **Fix:** Always create a feature branch before any work. Pattern: `{user}/{type}/{short-desc}` (e.g., `caio/feat/new-feature`). Run `git fetch origin` + check branch at session start
+- **Agents:** @developer
+- **Added:** 2026-01-15
+
+### G-GIT-03: Merge conflict on package-lock.json
+
+- **Pattern:** `CONFLICT (content): Merge conflict in package-lock.json` after pulling main
+- **Root Cause:** Two branches modified dependencies independently
+- **Fix:** Delete `package-lock.json`, run `npm install` to regenerate, then commit the new lockfile. Never manually resolve lockfile conflicts
+- **Agents:** @developer, @devops
+- **Added:** 2026-02-10
+
+---
+
+## Hook & Permission Gotchas
+
+### G-HOOK-01: Story gate blocks code writing
+
+- **Pattern:** `BLOCKED: No story found for this work` when trying to Write/Edit source files
+- **Root Cause:** `enforce-story-gate.cjs` requires a valid story in `docs/stories/` with status >= Ready before code changes
+- **Fix:** Create a story via @sprint-lead `*draft`, validate via @product-lead `*validate`, then proceed with implementation. Framework governance work by @sinapse-orqx is exempt
+- **Agents:** @developer
+- **Added:** 2026-01-20
+
+### G-HOOK-02: Architecture-first gate blocks protected paths
+
+- **Pattern:** `BLOCKED: Architecture documentation required before modifying protected paths` when editing core files
+- **Root Cause:** `enforce-architecture-first.cjs` requires architecture docs before modifying L1/L2 paths
+- **Fix:** Document the architectural decision first, then modify the code. Check `.claude/rules/hook-governance.md` for which paths are protected
+- **Agents:** @developer, @architect
+- **Added:** 2026-02-01
+
+### G-HOOK-03: Delegation hook blocks orchestrator execution
+
+- **Pattern:** `BLOCKED: Orchestrators cannot execute domain work directly` when an orchestrator tries to write code
+- **Root Cause:** `enforce-delegation.cjs` enforces Constitution Article VIII -- orchestrators must delegate
+- **Fix:** The orchestrator must delegate to the appropriate specialist agent. Orchestrators can only do routing, diagnostics, and coordination
+- **Agents:** @sinapse-orqx, all *-orqx orchestrators
+- **Added:** 2026-02-15
+
+### G-HOOK-04: Hook crashes but operation proceeds
+
+- **Pattern:** Hook outputs an error traceback but the operation is NOT blocked (exit code 0)
+- **Root Cause:** Hooks follow fail-open design -- if a hook crashes or cannot parse input, it exits 0 (allow)
+- **Fix:** This is by design. Fix the hook itself if the crash is recurring, but do not rely on broken hooks for enforcement. Report to @devops
+- **Agents:** ALL
+- **Added:** 2026-03-01
+
+---
+
+## Testing Gotchas
+
+### G-TEST-01: Tests pass locally but fail in CI
+
+- **Pattern:** `npm test` passes on developer machine but CI reports failures
+- **Root Cause:** Common causes: (1) tests depend on OS-specific paths (Windows backslashes vs Unix forward slashes), (2) timezone-dependent assertions, (3) missing environment variables in CI, (4) test execution order dependency
+- **Fix:** Use `path.join()` or `path.posix` for paths. Use UTC in date assertions. Add required env vars to CI config. Ensure tests are independently runnable with `--randomize`
+- **Agents:** @developer, @quality-gate
+- **Added:** 2026-02-20
+
+### G-TEST-02: MSW handlers not intercepting requests
+
+- **Pattern:** Integration tests hit real API endpoints instead of MSW mocks, causing timeouts or unexpected data
+- **Root Cause:** MSW server not started before tests, or handler URL does not match the actual request URL (trailing slashes, query params, base URL mismatch)
+- **Fix:** Verify `server.listen()` in `beforeAll`, `server.resetHandlers()` in `afterEach`, `server.close()` in `afterAll`. Match URLs exactly including protocol and path
+- **Agents:** @developer, @quality-gate
+- **Added:** 2026-03-10
+
+### G-TEST-03: Vitest snapshot mismatch after dependency update
+
+- **Pattern:** `Snapshot mismatch` errors across multiple test files after updating a UI library
+- **Root Cause:** Component HTML output changed with the library update, invalidating stored snapshots
+- **Fix:** Review the snapshot diffs. If changes are expected, run `vitest --update` to regenerate snapshots. Prefer `toHaveTextContent`/`toHaveAttribute` assertions over snapshots for resilience
+- **Agents:** @developer
+- **Added:** 2026-03-15
+
+---
+
+## MCP & Browser Gotchas
+
+### G-MCP-01: Docker MCP secrets not passed to containers
+
+- **Pattern:** `docker mcp tools ls` shows "(N prompts)" instead of "(N tools)". MCP server starts but fails authentication
+- **Root Cause:** Docker MCP Toolkit secrets store and template interpolation do not work properly (known bug Dec 2025+). Credentials set via `docker mcp secret set` are NOT passed to containers
+- **Fix:** Edit `~/.docker/mcp/catalogs/docker-mcp.yaml` directly with hardcoded env values. See `.claude/rules/mcp-usage.md` for details
+- **Agents:** @devops
+- **Added:** 2026-01-10
+
+### G-MCP-02: Using docker-gateway for local file operations
+
+- **Pattern:** File read/write fails with path errors like `/mnt/c/Users/...` not found, or operations are unexpectedly slow
+- **Root Cause:** Using `docker-gateway` MCP for operations that should use native Claude Code tools. Docker runs in a Linux container with different filesystem paths
+- **Fix:** Always use native tools for local operations: `Read` for files, `Write`/`Edit` for writing, `Bash` for commands, `Grep` for search. Only use docker-gateway for MCP servers running inside Docker (EXA, Context7, Apify)
+- **Agents:** ALL
+- **Added:** 2026-01-25
+
+### G-MCP-03: Chrome DevTools MCP connection refused
+
+- **Pattern:** `Connection refused` or `Cannot connect to browser` when using chrome-devtools MCP
+- **Root Cause:** Chrome not launched with remote debugging enabled, or port conflict
+- **Fix:** Launch Chrome with `--remote-debugging-port=9222`. Ensure no other process is using port 9222. On Windows, close all Chrome instances first
+- **Agents:** @developer, @quality-gate
+- **Added:** 2026-02-28
+
+---
+
+## Supabase & Database Gotchas
+
+### G-DB-01: RLS enabled but no policies -- data inaccessible
+
+- **Pattern:** Supabase queries return empty arrays even though data exists in the table
+- **Root Cause:** RLS was enabled on the table (`ALTER TABLE ... ENABLE ROW LEVEL SECURITY`) but no policies were created. PostgreSQL default is deny-all when RLS is active without policies
+- **Fix:** Create explicit policies for each operation (SELECT, INSERT, UPDATE, DELETE). At minimum: `CREATE POLICY "allow_authenticated" ON table FOR SELECT TO authenticated USING (true)`
+- **Agents:** @data-engineer, @developer
+- **Added:** 2026-01-15
+
+### G-DB-02: RLS performance degradation -- slow queries
+
+- **Pattern:** API response times increase from <100ms to 500ms+ as data grows, EXPLAIN ANALYZE shows sequential scans
+- **Root Cause:** RLS policy columns not indexed, or `auth.uid()` called without wrapping in `SELECT` subquery
+- **Fix:** (1) Index all columns used in RLS policies: `CREATE INDEX idx_user ON table(user_id)`. (2) Use `(SELECT auth.uid()) = user_id` instead of `auth.uid() = user_id` (up to 95% faster due to caching). (3) Add explicit `.eq()` filters in SDK queries
+- **Agents:** @data-engineer, @developer
+- **Added:** 2026-02-05
+
+### G-DB-03: service_role key exposed in frontend
+
+- **Pattern:** Security scan detects `service_role` key in client-side bundle or `NEXT_PUBLIC_` variable
+- **Root Cause:** Developer accidentally used service_role key (which bypasses RLS) instead of anon key in frontend code
+- **Fix:** Immediately rotate the exposed key in Supabase Dashboard. Use ONLY `anon` key with `NEXT_PUBLIC_` prefix. Keep `service_role` in server-only env vars (no `NEXT_PUBLIC_` prefix). Add secret scanning hook
+- **Agents:** @developer, @devops
+- **Added:** 2026-01-20
+
+### G-DB-04: SQL Editor bypasses RLS -- false sense of security
+
+- **Pattern:** Developer tests RLS policies in Supabase SQL Editor and sees all data, concluding RLS is broken
+- **Root Cause:** The SQL Editor runs with superuser/service_role privileges, which bypasses RLS entirely
+- **Fix:** Test RLS policies using the Supabase client SDK (JS/Python) with the anon key, not the SQL Editor. Alternatively, use `SET ROLE authenticated; SET request.jwt.claims = '{"sub":"user-uuid"}'` in SQL to simulate a user
+- **Agents:** @data-engineer, @developer
+- **Added:** 2026-03-01
+
+---
+
+## NPM & Publishing Gotchas
+
+### G-NPM-01: npm publish fails with 403
+
+- **Pattern:** `npm ERR! 403 Forbidden - PUT https://registry.npmjs.org/sinapse-ai` when publishing
+- **Root Cause:** (1) Not logged in to npm, (2) package name already taken by another user, (3) npm token expired, or (4) 2FA required but not provided
+- **Fix:** Run `npm login` to refresh auth. Check package name availability with `npm view <name>`. For scoped packages, ensure the org exists. For 2FA, use `npm publish --otp=<code>`
+- **Agents:** @devops
+- **Added:** 2026-02-10
+
+### G-NPM-02: Version conflict on publish
+
+- **Pattern:** `npm ERR! 403 - cannot publish over previously published version` when trying to publish
+- **Root Cause:** The version in `package.json` already exists on the npm registry
+- **Fix:** Bump the version using `npm version patch|minor|major` before publishing. Use `pre-commit-version-check.sh` hook to catch this early
+- **Agents:** @devops
+- **Added:** 2026-02-15
+
+---
+
+## Next.js & Vercel Gotchas
+
+### G-NEXT-01: Server Component importing client-only code
+
+- **Pattern:** `Error: useState is not a function` or `Error: window is not defined` in a Server Component
+- **Root Cause:** Server Components cannot use React hooks (useState, useEffect, etc.) or browser APIs (window, document). All components are Server Components by default in App Router
+- **Fix:** Add `'use client'` directive at the top of files that need interactivity. Keep the client boundary as small as possible -- pass Server Components as `children` to Client Components
+- **Agents:** @developer
+- **Added:** 2026-03-05
+
+### G-NEXT-02: NEXT_PUBLIC_ variable undefined at runtime
+
+- **Pattern:** `process.env.NEXT_PUBLIC_API_URL` is `undefined` in the browser even though it is set in `.env.local`
+- **Root Cause:** `NEXT_PUBLIC_` variables are inlined at BUILD time, not runtime. If the variable was added after the last build, it will not be available
+- **Fix:** Restart the dev server (`npm run dev`) after adding new env vars. For production, redeploy after changing environment variables in Vercel Dashboard
+- **Agents:** @developer
+- **Added:** 2026-03-10
+
+---
+
+## How to Add New Entries
+
+When encountering a recurring error (seen 2+ times), add a new entry:
+
+1. Choose the appropriate category (or create a new one)
+2. Use the next sequential ID: `G-{CATEGORY}-{NN}`
+3. Fill in all fields: Pattern, Root Cause, Fix, Agents, Added
+4. Keep descriptions concise -- max 3 lines per field
+5. Reference relevant documentation or hook files when applicable