# AGENTS.md — Guia para agentes de IA no repositório SAR

> Pre-requisito de leitura para qualquer agente trabalhando neste repositório.

## Fontes da verdade (ler ANTES de propor código)

1. **[`STACK.md`](STACK.md) v2.2** — tecnologias, versões, monorepo, multi-tenancy, infra
2. **[`CODING-RULES.md`](CODING-RULES.md) v2.0** — invariantes + pegadinhas críticas 🔥
3. **[`brand.md`](brand.md)** — identidade visual JCS

## Phase 1/2 artifacts (contexto estratégico)

- [`design-artifacts/A-Product-Brief/`](design-artifacts/A-Product-Brief/) — Brief estratégico completo
  - `00-handover-summary.md` ⭐ entrada rápida
  - `01-product-brief.md` (Brief)
  - `02-content-language.md` (tom, vocabulário canônico, SEO)
  - `03-visual-direction.md` (Visual DNA)
  - `04-platform-requirements.md` (Stack consolidada)
- [`design-artifacts/B-Trigger-Map/`](design-artifacts/B-Trigger-Map/) — Personas + driving forces + feature impact
  - `00-trigger-map.md` ⭐ hub
  - `01-business-goals.md`
  - `personas/02-05-*.md` (Rafael, Sandra, Daniel, Alice)
  - `06-feature-impact-analysis.md`

## Regras essenciais

1. **Antes de propor tecnologia fora de STACK.md:** pergunte e justifique (RFC em `docs/adr/NNN-titulo.md`)
2. **NestJS é CJS** (PGD-DB-004) — `apps/api/package.json` sem `"type": "module"`
3. **Multi-tenancy é BD-por-workspace** (ADR 0006) — sem `tenantId` em modelos de domínio
4. **Vocabulário canônico:** Cliente · Rep · Orçamento · Pedido · Faturado · Visita · Carteira · Inativo · Painel · Aprovação
5. **Tom de microcopy:** Direto · Profissional sem ser frio · Confiante · Específico · Empático nos momentos difíceis
6. **Visual:** Modern Flat + Minimal · JCS Blue `#004a99` único accent · Plus Jakarta Sans · radius 12/20 · sombra `0 4px 25px rgba(0,0,0,0.05)`
7. **Personas com prioridades:** Rafael PRIMARY (mobile-first PWA iOS) · Sandra SECONDARY · Daniel SECONDARY · Alice TERTIARY
8. **P0 absoluto:** zero pedidos perdidos por bug/sync (force R-3 do Rafael)

## Conventional commits

Conforme STACK.md §19: `feat, fix, chore, docs, refactor, test, perf, style, ci, build`.

## Não fazer

- ❌ Sem `console.log` em produção (use Pino estruturado)
- ❌ Sem `any` / `@ts-ignore` sem justificativa
- ❌ Sem `process.env.X` direto (use Zod-validated config)
- ❌ Sem `import { prisma }` singleton em service de domínio (PGD-DB-009 — multi-tenancy BD-por-workspace)
- ❌ Sem `db push` em produção (PGD-DB-001 — migrate via 5432 direto)
- ❌ Sem secret runtime embutido no build/bundle (PGD-SEC-002 — Vault Agent)